본 글에선 MSW에 대한 구체적인 설명이나 기본적인 설정 방법에 대해서는 다루지 않습니다.

시작하며

아직까지(2024.01.04) Next.js 13에서 새롭게 추가된 App Directory 기능을 MSW가 지원하지 않고 있는 상황입니다.(깃헙 이슈) 그 이유는 Node.js에서 MSW가 작동하기 위해서는 전역 Node 모듈(http, https 등)을 패치해야 하는데, Next.js의 현재 프로세스 구조상 전역적인 곳에서 패치를 하는것이 아니라 개별 레이아웃마다 패치하기 때문에 어렵다고 합니다.

그럼 App Directory에서는 node환경에서 msw를 사용하지 못하는 걸까요? 아닙니다. next프로젝트와 상관이 없는 독립적인 서버를 구축하고 next의 서버사이드측에서 api요청을 보낼때 middleware를 사용하여 요청을 가로채면 위 문제가 해결이 됩니다.

물론 임시적인 해결책이고 Next.js에서 정상적으로 지원을 해주면 방식을 바꿔야합니다.

문제의 코드

보통 node와 browser환경에서 msw설정을 하기 위해서 다음과 같은 코드를 작성했을 것입니다.

export async function init() {
  if(typeof window === 'undefined') {
    const { server } = await import('./server');
    server.listen();
  } else {
    const { worker } = await import('./browser');
    worker.start();
  }
}

위와 같은 방식을 server component에서 사용하게 되면, data fetching이 msw가 활성화되는 시점보다 먼저 발생해서 msw가 동작하지 않습니다.

서버사이드에서 정상적으로 msw동작시키기

독립적인 서버(express)를 띄워서 서버사이드에서 일어나는 데이터 패칭 로직을 가로채는 과정을 살펴보겠습니다.

express 서버 구축

@mswjs/http-middleware와 express 를 의존성에 추가를 해주고 코드를 다음과 같이 작성해줍니다.

// src/mocks/http.ts
import express from 'express'
import { createMiddleware } from '@mswjs/http-middleware'
import { handlers } from './handlers'

const app = express()
const port = 9090

app.use(express.json())
app.use(createMiddleware(...handlers))

app.listen(port, () => console.log(`Mock server is running on port: ${port}`))

참고자료 : https://github.com/mswjs/msw/issues/1644#issuecomment-1750722052

pacakge.json에 express server실행을 위한 script를 다음과 같이 정의를 해줍니다.

"scripts": {
    "mock": "npx tsx watch ./src/mocks/http.ts",
    "dev": "next dev"
}

next의 dev서버를 실행시킬때 mock server실행을 위한 mock script도 같이 실행을 시켜주면 됩니다.

위 코드 구성을 완료했으면 msw에서 정의한 handler를 server component에서 사용할 수 있게 됩니다.

동작과정

// server component 예시
async function getUser() {
  const response = await fetch('http://localhost:9090/user')
  const json = await response.json()

  return json
}

const UserPage = async () => {
  const user = await getUser()
  console.log('user', user)
  return <div></div>
}

export default UserPage

1. 위의 server component에서 http요청을 생성하여 http://localhost:9090/user에 보냅니다.
2. express서버에서 http://localhost:9090에 대한 요청을 수신합니다.
3. @mswjs/http-middleware 라이브러리로 정의된 msw 핸들러가 이 요청을 가로채고 처리합니다. msw는 설정된 핸들러를 통해 요청을 확인하고 mock 데이터를 사용하여 응답을 생성합니다.
4. msw는 설정된 핸들러(handlers)에서 정의된 mock 데이터 또는 응답을 사용하여 요청에 대한 가짜 응답을 생성합니다. 이 mock 응답이 express 서버로 반환됩니다.
5. express 서버는 msw로부터 받은 mock 응답을 클라이언트에 반환합니다.

baseURL의 문제점

하지만, 실제 코드에 적용하기엔 약간 부족한 점이 보입니다. 보통 프론트 개발서버에서는 개발 api서버(https://dev.api/user)를 호출하고 있을 것이고 baseUrl로 설정이 되어있을 것입니다.

next 개발서버를 실행시킬때 mock api서버를 띄워야하는지 판단해주는 환경변수를 주입해서 baseUrl을 localhost로 설정할지에 대한 판단을 해주면 됩니다.

매번 next dev server서버와 express서버를 실행시키기는 귀찮으므로 concurrently라는 라이브러리를 활용해서 next dev server와 express서버를 한 번에 실행을 시키고 next프로젝트에 NEXT_PUBLIC_API_MOCKING이라는 환경변수를 주입해줍니다.

"scripts": {
    "dev:mock": "concurrently --kill-others \"NEXT_PUBLIC_API_MOCKING=enable next dev\" \"npx tsx watch ./src/mocks/http.ts\"",
    //...
}

그리고 프로젝트에선 다음과 같이 설정해주면 됩니다.

const baseUrl = process.env.NEXT_PUBLIC_API_MOCKING === 'enable' ? 'http://localhost:9090' : 환경별baseURL판단로직

마치며

생각보다 간편한 방법으로 App Directory에서 msw를 사용할 수 있지만, express서버를 별도로 띄워야 하므로 불편한 느낌이 조금은 있습니다. msw측에서 next의 instrumentation을 이용하여 해결하는 방법을 제시했는데 빨리 지원이 됐으면 좋겠습니다. (관련 pr 입니다. https://github.com/mswjs/examples-new/pull/7) 혹시 다른 좋은 방법 있으시면 의견 부탁드립니다!

next11에서 serverless-next를 이용하여 배포하던 방식을(serverless-next는 현재 관리가 되지 않는 오픈소스여서 next13이후 배포를 지원하지 않습니다.) next14로 버전업을 함에 따라 SST로 변경을 했습니다. SST를 이용하여 next.js를 배포하는 방법에 대해 공유하고자 합니다.

SST란?

SST는 Next.js,Svelte,Remix,Astro,Solid와 같은 프레임워크의 배포를 손 쉽게 도와줍니다.

사용되는 AWS의 서비스는 기본적으로 다음과 같습니다.

• S3 : 클라이언트 자산이 위치합니다.
• Cloudfront : 빠른 컨텐츠 전송을 위해 사용이 됩니다.
• Lambda : app server와 api기능이 배포 됩니다. (edge플래그가 활성화된 경우 Lambda@Edge에 배포가 됩니다.)

SST로 배포하는 방법

프로젝트에 sst 세팅

npx create-sst@latest를 실행후 sst.config.ts파일이 생성이 됐는지 확인을 해줍니다.(drop-in mode) 위 사진처럼 파일이 생성되게 됩니다. npm install을 해주고 sst모듈을 받아주시면 됩니다.(빨간줄도 사라지게 됩니다.)

//package.json
"scrips":{
  "dev": "sst bind next dev"
  //...
}

dev 명령어가 next dev 에서 sst bind next dev 로 바뀐것도 인지를 해줍니다. 만약 로컬 환경에서 sst가 필요 없다면 next dev로 돌려주시면 됩니다. (제 생각엔 로컬에서 lambda함수를 디버깅이나 테스트를 할 필요가 없다면 로컬 환경마다 credential 설정을 해야 하므로 next dev로 개발을 하는게 좋을거 같습니다.)

로컬에서 SST를 실행시키기 위한 IAM Credentials 설정

aws에 배포하기 때문에 SST가 사용할 IAM Credentials 설정을 해줘야 합니다.

저의 경우 로컬에서는 SST를 이용하지 않아서 로컬에 credential을 설정하는 과정은 생략했습니다.

로컬에 Credential 설정

일반적으로 credential 파일이 존재한다면 다음 경로에 위치합니다.

• macOS : ~/.aws/credentials
• windows : C:\Users\USER_NAME\.aws\credentials

내 컴퓨터에 credential파일이 없는 경우 다음 두가지 과정을 진행해줘야 합니다.

1. IAM 사용자 생성 가이드를 이용하여 key 생성후
2. AWS CLI를 이용하여 컴퓨터에 credential구성

위 과정을 마쳤으면 다음과 같은 파일이 생성되어야 합니다.

[default]
aws_access_key_id = <YOUR_ACCESS_KEY_ID>
aws_secret_access_key = <YOUR_SECRET_ACCESS_KEY>

여러 자격 증명을 구성한 경우

[default]
aws_access_key_id = <DEFAULT_ACCESS_KEY_ID>
aws_secret_access_key = <DEFAULT_SECRET_ACCESS_KEY>

[staging]
aws_access_key_id = <STAGING_ACCESS_KEY_ID>
aws_secret_access_key = <STAGING_SECRET_ACCESS_KEY>

[production]
aws_access_key_id = <PRODUCTION_ACCESS_KEY_ID>
aws_secret_access_key = <PRODUCTION_SECRET_ACCESS_KEY>

기본적으로 SST는 [defalut] 프로필에 대한 credential을 사용합니다. 위의 staging이나 production중 하나를 사용하려면 AWS_PROFILE 환경 변수를 설정하면 됩니다.

$ AWS_PROFILE=staging npx sst deploy

이제 sst bind next dev 나 npx sst deploy와 같은 명령어를 실행시키면 정상적으로 동작하는걸 확인할 수 있습니다.

GitHub Action으로 배포하기 위한 방법

OpenID Connect를 통해 AWS에 인증처리를 해줍니다.

1. 자격 증명 공급자 추가

공급자 추가를 눌러줍니다.

• Provider URL: https://token.actions.githubusercontent.com
• Audience: sts.amazonaws.com

위의 설정값을 넣어주고 공급자 추가를 해주면 완료입니다.

2. IAM Role 설정

공급자 상세로 들어가 줍니다.

해당 화면에서 역할 할당을 눌러줍니다.

• Trusted entity type: Web identity
• Identity provider: token.actions.githubusercontent.com
• Audience: sts.amazonaws.com
• GitHub organization: 깃헙 조직이름이나 자신의 깃헙 계정 이름

각 칸에 위와 같이 정보들을 제대로 입력을 했다면, 다음으로 넘어가줍니다.

AdministratorAccess 정책을 선택 후 다음을 눌러줍니다.

역할 이름을 입력을 해주고 역할 생성을 하면 완료입니다.

생성했던 역할 이름으로 역할 검색을 해주고 ARN을 확인해줍니다. (arn:aws:iam::?????????:role/Ssoon과 같은 형태입니다.)

3. Github Worlfow 구성하기

name: SST workflow
on: push

# Concurrency group name ensures concurrent workflow runs wait for any in-progress job to finish
concurrency:
  group: merge-${{ github.ref }}

permissions:
  id-token: write # This is required for requesting the JWT
  contents: read # This is required for actions/checkout

jobs:
  DeployApp:
    runs-on: ubuntu-latest
    steps:
      - name: Git clone the repository
        uses: actions/checkout@v3
      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::????????:role/Ssoon
          aws-region: us-east-1
      - name: Deploy app
        run: |
          npm i && npx sst deploy --stage prod

두가지 부분만 수정을 해주면 됩니다.

• role-to-assume : 위에서 설정한arn:aws:iam::?????????:role/Ssoon를 입력해주면 됩니다.

• aws-region : sst.config.ts에 설정한 region을 적어주면 됩니다.

모든 과정을 마치고 github action을 실행시켜보면 정상적으로 배포가 되는걸 확인할 수 있습니다.

SST 배포환경별 설정및 사용자 지정 도메인 구성

배포 환경별 설정

stage option을 이용하여 production과 staging환경을 나눌수 있습니다.

$ npx sst deploy --stage prod

stage에 전달한 값이 sst config파일에 아래와 같이 전달이 됩니다.

//sst.config.ts
import { SSTConfig } from "sst";
import { NextjsSite } from "sst/constructs";

export default {
  config(_input) {
    return {
      name: _input.stage === "prod" ? "prod-web" : "staging-web",
      region: "us-east-1",
    };
  },
  stacks(app) {
    if (!["dev", "prod"].includes(app.stage)) {
      throw new Error("Invalid stage");
    }
    app.stack(function Site({ stack }) {
      const site = new NextjsSite(stack, "site", {
        customDomain: {
          domainName:
            stack.stage === "prod" ? "naver.com" : "dev.naver.com",
            hostedZone: "naver.com",
        },
      });
      stack.addOutputs({
        SiteUrl: site.url,
      });
    });
  },
} satisfies SSTConfig;

Route 53을 사용할 경우

customDomain 부분의 hostedZone은 Route 53의 호스팅 영역을 적어주면 됩니다. domainName 부분에는 말 그대로 도메인명을 적어주면 됩니다. 만약 하위 도메인을 적어주면 sst에서 자동으로 하위 도메인을 생성해서 배포를 진행해줍니다.

외부 호스팅을 사용할 경우

제일 간단한 방식은 Route 53으로 이동시키는 것입니다.

1. 사용 중인 도메인을 Route 53으로 DNS 서비스로 설정 - 도메인이 현재 많은 트래픽이 있을 경우에 대한 방법
2. 비활성화된 도메인을 Route 53으로 DNS서비스로 설정 - 도메인이 사용되지 않거나 많은 트래픽이 없을 경우에 대한 방법

Route 53을 사용하지 않을 경우 CNAME레코드를 생성하고 이를 CloudFront배포로 지정하면됩니다. 배포를 했을때 자동으로 생성되는 URL인 d1p6z4d11yxxds.cloudfront.net을 가리키면 됩니다. 자세한 내용은 공식문서에 있습니다.

SST의 장점

• vercel보다 저렴합니다.
• 개발팀이 있을 경우 organization의 저장소를 추가 과금 없이 배포가 가능합니다.
• 오픈소스 프로젝트이고 디스코드를 통해 소통이 가능합니다.
• Infrastructure as code 패턴입니다. (aws cdk를 이용해서 CloudFormation템플릿으로 변환시켜 배포를 진행합니다. 이 과정을 타입스크립트로 관리합니다.)

SST의 단점

• Next의 경우 open-next기반으로 배포 처리가 되는데, 공식문서를 확인해보면 현재 스트리밍 기술은 실험적인 단계로 지원을 하고 있습니다. 프로덕션에서는 사용하지 않기를 권장하고 있습니다.
• vercel보다 비교적 적은 커뮤니티가 형성되어 있습니다.
• Next.js에서 제공하는 최신 기술이 나오게 되면 해당 기술을 반영하기 까지 오래 걸릴수도 있습니다.
• vercel에 비해 배포하는 과정이 살짝 까다롭습니다.

번외

serverless-next에서 sst로 이관하는 방법에 대해 알아보겠습니다.

1. serverless-next 관련된 패키지를 다 삭제해주고 관련 파일도 삭제를 해줍니다.
2. 기존에 serverless-next를 배포함에 따라 생성된 aws에서의 cloudfront를 삭제를 해줍니다.
3. Route 53에 들어가서 배포할 호스트에 연결되어 있는 A레코드를 전부 삭제를 해줍니다.
4. 위에서 설명한 내용과 같이 sst에 대한 설정을 전부 마치고 aws에 배포를 해주면 정상적으로 배포가 진행이 되는걸 확인할 수 있습니다.

contentlayer에서 rehype와 remark를 활용하여 Markdown 파일을 파싱했을때, 그 결과로 목차(TOC)를 scroll event와 intersection observer로 구현하는 방법을 살펴봅니다. 단, 본 글에서는 contentlayer와 rehype,remark 사용법에 대해서는 다루지 않습니다.

시작하며

개발 블로그를 만들면서 TOC기능을 어떻게 구현했는지 왜 IntersectionObserver를 안쓰게 됐는지 공유하고자 합니다.

TOC란? 책의 TOC를 보면 본문 내용을 간략하게 알거나, 쉽게 찾아 볼 수 있게 해줍니다. 웹 사이트에서의 TOC도 마찬가지입니다. 보통 개발 블로그에서의 TOC는 클릭시 해당 위치로 바로 스크롤을 해주고, 현재 내가 어느 지점의 글을 읽고 있는지 표시를 해줍니다.

어떤 기능을 구현할 것인가?

웹사이트 블로그 글 TOC의 기본이 되는 기능을 구현할 것입니다.(react로 예시코드가 작성되어 있습니다.)

1. 현재 읽고 있는 글이 어느 부분인지 파악하기 위해 제목 태그와 매칭되는 목차가 생기면 목차에 하이라이팅 처리

2. TOC를 클릭했을 경우 해당하는 제목 태그로 이동

1. 제목 태그에 id값을 달아주기

TOC를 클릭 했을때 해당하는 제목 태그 위치로 이동을 시켜야 하므로 html heading에 id를 달아줘야 합니다. rehype-slug라는 라이브러리를 사용하면 다음과 같이 아주 간단하게 제목 태그에 id를 달아줄 수 있습니다.

2. 제목 태그에 id 달아주는 로직 파악하기

목차를 클릭했을 때 글 본문의 heading의 id를 찾아서 이동을 해야하므로 rehype-slug가 id를 어떤식으로 생성을 하는지 알아야합니다. rehype-slug 가 id를 생성하는 방법을 대강 비스무리하게 구현을 하면 목차와 본문heading의 id가 정확히 매칭이 되지 않을수도 있으므로 rehype-slug 라이브러리 코드를 살펴봅시다.

import GithubSlugger from 'github-slugger'
import {headingRank} from 'hast-util-heading-rank'
import {toString} from 'hast-util-to-string'
import {visit} from 'unist-util-visit'

/** @type {Options} */
const emptyOptions = {}
const slugs = new GithubSlugger()

/**
 * Add `id`s to headings.
 *
 * @param {Options | null | undefined} [options]
 *   Configuration (optional).
 * @returns
 *   Transform.
 */
export default function rehypeSlug(options) {
  const settings = options || emptyOptions
  const prefix = settings.prefix || ''

  /**
   * @param {Root} tree
   *   Tree.
   * @returns {undefined}
   *   Nothing.
   */
  return function (tree) {
    slugs.reset()

    visit(tree, 'element', function (node) {
      if (headingRank(node) && !node.properties.id) {
        node.properties.id = prefix + slugs.slug(toString(node))
      }
    })
  }
}

살펴보니 내부적으로 github-slugger를 사용하는걸 확인할 수 있습니다. GithubSlugger 인스턴스를 만들어서 별다른 옵션이 없을 경우 node 의 id 속성에 slug를 생성해서 넣어주고 있습니다. TOC를 만들때 github-slugger를 이용하여 id값을 생성하면 될 거 같습니다.

3. 본문글에서 TOC를 위한 데이터를 추출하기

전체적인 TOC추출 코드의 모습입니다.

export const parseHeadersForTOC = (raw: string) => {
  const calculateHeaderLevels = (arr: Array<number>) => {
    const sorted = [...arr].sort((a, b) => a - b);
    const min = sorted[0];
    const adjusted = arr.map((value) => value - min + 1);
    return adjusted;
  };

  const regex = /\n(?<flag>#{1,3})\s+(?<text>.+)/g;
  const headerMatches = Array.from(raw.matchAll(regex));

  const headerLevels = calculateHeaderLevels(
    headerMatches.map((match) => match.groups?.flag.length!),
  ) as Array<1 | 2 | 3>;

  const slugger = new GithubSlugger();

  const headers: Toc[] = headerMatches.map((header, i) => {
    const { text } = header.groups || { text: '' };
    const slug = slugger.slug(text);
    return { level: headerLevels[i], text, slug };
  });
  return headers;
};

raw파라미터에는 아래 형식과 같은 문자열이 들어오게 됩니다.

# toc
toc level1 입니다.
## toc
toc level2 입니다.
### toc
toc level3 입니다.

"#" 의 개수 n에 따라 heading{n} 이 결정이 됩니다.

정규식(/\n(?<flag>#{1,3})\s+(?<text>.+)/g)을 통해서 제목 태그의 level과 제목 태그의 텍스트를 그룹핑합니다.

각 제목 태그가 개행 문자로 시작하므로 \n을 넣어줍니다. (?<flag>#{1,3})는 flag라는 이름의 그룹을 정의합니다. 이 그룹은 # 문자 1개에서 3개까지 연속으로 나타나는 것을 의미합니다. 즉, #, ##, 또는 ###와 일치하는 것을 찾습니다. \s+는 하나 이상의 공백 문자를 나타냅니다. 이 공백은 #과 제목 텍스트를 구분합니다. (?<text>.+)는 text라는 이름의 그룹을 정의합니다. 이 그룹은 하나 이상의 문자(.+)를 의미하며, 제목의 실제 텍스트를 찾습니다. /g는 전역 검색을 활성화하는 플래그로, 문자열 내에서 모든 일치 항목을 찾아야 함을 나타냅니다.

matchAll을 통해 일치하는 패턴들을 다 찾아주고 배열로 만들어 줍니다.

const headerMatches = Array.from(raw.matchAll(regex));
console.log('headerMatches', headerMatches);
// headerMatches [
  //   [
  //     '\n# toc',
  //     '#',
  //     'toc',
  //     index: 0,
  //     input: '\n# toc\ntoc level1 입니다.\n## toc\ntoc level2 입니다.\n### toc\ntoc level3 입니다.\n\n',
  //     groups: [Object: null prototype] { flag: '#', text: 'toc' }
  //   ],
  //   [
  //     '\n## toc',
  //     '##',
  //     'toc',
  //     index: 22,
  //     input: '\n# toc\ntoc level1 입니다.\n## toc\ntoc level2 입니다.\n### toc\ntoc level3 입니다.\n\n',
  //     groups: [Object: null prototype] { flag: '##', text: 'toc' }
  //   ],
  //   [
  //     '\n### toc',
  //     '###',
  //     'toc',
  //     index: 45,
  //     input: '\n# toc\ntoc level1 입니다.\n## toc\ntoc level2 입니다.\n### toc\ntoc level3 입니다.\n\n',
  //     groups: [Object: null prototype] { flag: '###', text: 'toc' }
  //   ]
  // ]

calculateHeaderLevels 함수는 제목 태그의 수준을 계산합니다.

입력으로 level이 담긴 배열을 받아 해당 배열의 각 요소 간의 차이를 계산하여 최소 level을 1로 조정한 배열을 반환합니다.(예를들어 제목태그에 heading2 밖에 존재하지 않을 경우 level이 1로 계산이 되고, heading1과 headgin2가 존재할 경우 heading1의 level이 1로 계산이 됩니다.)

const headerLevels = calculateHeaderLevels(
    headerMatches.map((match) => match.groups?.flag.length!),
) as Array<1 | 2 | 3>;

headerMathces 배열을 map함수를 이용하여 level,text,slug 속성을 가진 배열을 반환해줍니다. slug는 아까 위에서 받은 GithubSlugger 를 통해서 생성을 해주면 됩니다.

  const slugger = new GithubSlugger();

  const headers: Toc[] = headerMatches.map((header, i) => {
    const { text } = header.groups || { text: '' };
    const slug = slugger.slug(text);
    return { level: headerLevels[i], text, slug };
  });
  return headers;

parseHeadersForTOC 함수의 최종 결과입니다.

[
  { level: 1, text: 'toc', slug: 'toc' },
  { level: 2, text: 'toc', slug: 'toc-1' },
  { level: 3, text: 'toc', slug: 'toc-2' }
]

4. 제목 태그 감지하기

글을 스크롤하며 읽을 때 제목 태그를 자동 감지하여 TOC를 자동으로 활성화하는 기능을 구현해야 합니다. 위 기능을 구현하는 방법은 두가지 정도가 있습니다.

1. intersection observer를 이용하여 제목 태그가 감지되면 TOC활성화
2. scroll event를 이용하여 특정 높이에 위치하면 TOC활성화

저는 1번 방법으로 구현을 했다가 2번 방법으로 변경했습니다. 1번 방법은 고속 스크롤 상황에서 요소를 제대로 감지하지 못하는 이슈가 있었습니다. 그래서 생각이 난 방법은 scroll event로 처리를 하는 방법이였습니다. velog의 toc는 감지가 잘 된다고 느껴서 코드를 참고 해보니 scroll event를 사용하고 있었습니다.

intersection observer, scroll event를 이용한 코드를 각각 살펴보겠습니다. (스타일링 코드는 제외 했습니다.)

intersection observer로 구현

intersection observer를 이용했을 때 느낀 최대 장점은 코드가 간결해서 이해하기가 쉽다는 점이였습니다. 또한, 요소의 상태 변경을 관찰할 때 비동기 콜백으로 동작하기 때문에 scroll event보다 성능상의 이점도 챙길 수 있습니다. 단점은 고속 스크롤 상황에서 intersection observer가 제대로 동작하지 않아서 TOC하이라이팅이 제대로 되지 않는 이슈 입니다.

아래 코드는 블로그 글 안의 h1,h2,h3태그를 다 가져와서 관찰할 요소로 지정을 해주고 감지가 될 경우 해당 요소의 id를 activeToc 에 세팅을 해줍니다. activeToc 와 일치하는 toc의 slug에 스타일링을 해주면 끝입니다. (뎁스에 따른 스타일 처리는 여기서 구현하지 않겠습니다.)

import { type Toc } from '@/lib/types/toc-type';
import Link from 'next/link';
import { useEffect, useRef, useState } from 'react';

interface TocSideProps {
  tableOfContents: Toc[];
}

const TocSide = ({ tableOfContents }: TocSideProps) => {
  const observer = useRef<IntersectionObserver>();
  const [activeToc, setActiveToc] = useState('');

  useEffect(() => {
    observer.current = new IntersectionObserver(
      (entries) => {
        entries.forEach((entry) => {
          if (!entry.isIntersecting) return;
          setActiveToc(entry.target.id);
        });
      },
      {
        rootMargin: '0px 0px -95% 0px',
        threshold: 1.0,
      },
    );
    const headingElements = document.querySelectorAll('.prose h1,h2,h3');
    headingElements.forEach((element) => observer.current?.observe(element));
    return () => observer.current?.disconnect();
  }, []);

  return (
    <>
      {tableOfContents.length ? (
        <ul>
          <div>
            목차
          </div>
          {tableOfContents.map((toc, i) => (
            <li
              data-level={numberToStringMap[toc.level]}
              key={i}
              className={`${activeToc === toc.slug ? 'active' : ''}`}
            >
              <Link href={`#${toc.slug}`}>{toc.text}</Link>
            </li>
          ))}
        </ul>
      ) : null}
    </>
  );
};

export default TocSide;

scroll event로 구현

intersection observer에 비해 코드가 간결하지 않습니다. 하지만, 동작은 intersection observer에 비해 정교해졌습니다.

tableOfContents를 map함수를 이용하여 doucment 에서 각 slug별로 해당하는 heading id를 찾고 찾은 요소는 현재 viewport에서 얼마나 떨어져 있는지(el.getBoundingClientRect().top)와 현재 document가 스크롤된 위치(scrollTop)을 더해줍니다. (el.getBoundingClientRect().top은 요소와 viewport사이의 상대적인 값을 가져오므로 만약 document를 100만큼 스크롤을 했으면 값이 -100이 되기 때문에 scrollTop은 꼭 더해줘야 합니다.)

블로그 게시글의 제목 태그가 어느정도로 스크롤 했을때 어떤 TOC요소와 매칭되는지에 대한 값을 구했으므로 scroll event를 통해 비교를 해주면서 하이라이팅 처리를 해줍니다.

그리고 trackScrollHeight 라는 메서드를 이용해서 0.25초 마다 주기적으로 이전 scrollHeight와 현재 scrollHeight가 같지 않을 경우 settingHeadingTops을 호출해주면서 제목 태그의 top 값을 재조정 해줍니다. (화면의 높이가 변경된 경우 재조정을 해주기 위함)

intersection observer와 마찬가지로 이제 activeToc 와 일치하는 toc의 slug에 스타일링을 해주면 끝입니다.

import { type Toc } from '@/lib/types/toc-type';
import Link from 'next/link';
import { useCallback, useEffect, useState } from 'react';

const numberToStringMap = {
  1: 'one',
  2: 'two',
  3: 'three',
};

const getScrollTop = () => {
  if (!document.body) return 0;
  if (document.documentElement && 'scrollTop' in document.documentElement) {
    return document.documentElement.scrollTop || document.body.scrollTop;
  } else {
    return document.body.scrollTop;
  }
};

interface IHeadingTops {
  slug: string;
  top: number;
}

interface TocSideProps {
  tableOfContents: Toc[];
}

const TocSide = ({ tableOfContents }: TocSideProps) => {
   const [activeToc, setActiveToc] = useState('');
  const [headingTops, setHeadingTops] = useState<null | IHeadingTops[]>([]);

  const settingHeadingTops = useCallback(() => {
    const scrollTop = getScrollTop();
    const headingTops = tableOfContents.map(({ slug }) => {
      const el = document.getElementById(slug);
      const top = el ? el.getBoundingClientRect().top + scrollTop : 0;
      return { slug, top };
    });
    setHeadingTops(headingTops);
  }, [tableOfContents]);

  useEffect(() => {
    settingHeadingTops();
    let prevScrollHeight = document.body.scrollHeight;
    let timeoutId: ReturnType<typeof setTimeout> | null = null;

    const trackScrollHeight = () => {
      const scrollHeight = document.body.scrollHeight;
      if (prevScrollHeight !== scrollHeight) {
        settingHeadingTops();
      }
      prevScrollHeight = scrollHeight;
      timeoutId = setTimeout(trackScrollHeight, 250);
    };

    timeoutId = setTimeout(trackScrollHeight, 250);

    return () => {
      timeoutId && clearTimeout(timeoutId);
    };
  }, [settingHeadingTops]);

  useEffect(() => {
    const onScroll = () => {
      const scrollTop = getScrollTop();
      if (!headingTops) return;
      const currentHeading = headingTops
        .slice()
        .reverse()
        .find((headingTop) => scrollTop >= headingTop.top - 4);

      if (currentHeading) {
        setActiveToc(currentHeading.slug);
      } else {
        setActiveToc('');
      }
    };
    onScroll();
    window.addEventListener('scroll', onScroll);
    return () => {
      window.removeEventListener('scroll', onScroll);
    };
  }, [headingTops]);

  return (
    <>
      {tableOfContents.length ? (
        <ul>
          <div>목차</div>
          {tableOfContents.map((toc, i) => (
            <li
              data-level={numberToStringMap[toc.level]}
              key={i}
              className={`${activeToc === toc.slug ? 'active' : ''}`}
            >
              <Link href={`#${toc.slug}`}>{toc.text}</Link>
            </li>
          ))}
        </ul>
      ) : null}
    </>
  );
};

export default TocSide;

마치며

성능상 이점을 챙기면서 빠르게 TOC를 구현하고 싶으면 intersection observer를 사용하고 시간을 더 들이더라도 ux에 신경을 쓸거면 scroll event를 사용하면 될 거 같습니다. intersection observer를 이용하든 scroll event를 이용하든 뭐가 더 좋다고 단정은 지을수 없을거 같습니다. 상황에 맞는 기술을 적용하는게 좋은 개발자가 되는 길이라고 생각합니다. 읽어주셔서 감사합니다.

Next.js의 static export 옵션을 활성화하면, <Image> 컴포넌트의 이미지 최적화 기능을 제대로 활용할 수 없습니다. 이는 Next.js가 기본적으로 on-demand 형식으로 서버에서 이미지 최적화를 수행하기 때문입니다. 이 글에서는 static export옵션 활성화시 이미지 최적화 기능을 어떻게 적용할지에 대해 다루고자 합니다.

static export시 이미지 최적화 방법

Next.js SSG에서 이미지 최적화는 꽤 오래전부터 많은 논의가 있었습니다.

아래 두가지 방법에 대한 내용입니다.

1. 빌드 타임시 이미지 최적화
2. 이미지 관리 및 최적화 서비스를 해주는 클라우드 서비스를 이용

1번의 경우엔 아직까지는 Next.js에서 공식적으로 제공할 생각이 없어 보였습니다. (빌드 타임시 이미지 최적화는 next-image-export-optimizer와 같은 라이브러리를 이용하거나 직접 구현해야 합니다.)

2번은 Next.js의 공식문서에서 이미지 최적화에 Cloudinary를 권장하고 있기 때문에 2번 방법으로 최적화를 하고자 합니다. (물론 2번 방법을 Cloudinary로만 구현이 가능한건 아닙니다. CloudFront 및 AWS Lambda를 이용한 방법도 있습니다.)

Cloudinary란?

Cloudinary는 이미지 및 비디오 관리 및 최적화 서비스를 제공하는 클라우드 기반 플랫폼입니다.
이 서비스를 통해 사용자는 웹 페이지의 이미지 및 비디오 관리를 간편하게 할 수 있으며, 성능 최적화와 빠른 로딩을 실현할 수 있습니다. Cloudinary는 이미지 변환, 크롭, 리사이즈, 효과 및 다운로드 및 전송 관리 등 다양한 이미지 관리 작업을 지원합니다.

그리고 제일 중요한(?) 요금제 정책을 살펴보겠습니다. 무료플랜 기준으로 한 달에 25 크레딧을 제공해준다고 합니다. (1크레딧 = 1000번의 파일변환, 1GB의 저장용량, 1GB의 대역폭) 개인 블로그와 같은 SSG사이트를 운영할때는 무료플랜으로 해도 문제가 없어 보입니다.

Cloudinary 사용법

우선 Cloudinary 에 로그인을 해줘야 합니다. 그 후 Cloudinary에 사진을 업로드하고 사진의 url을 프로젝트에서 이용하면 끝입니다.

업로드를 하는 방법은 매우 간단합니다.

1. Digital Asset Management 탭으로 이동
2. 우측 상단의 Upload버튼을 누르고 원하는 이미지를 업로드

위 과정을 마쳤다면, Next.js 프로젝트의 config에 loader 설정을 해줘야 합니다. (static export 옵션이 있다면, unoptimized나 loader 둘 중에 하나를 무조건 설정해줘야 합니다.)

// next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  images: {
    loader: 'custom',
    loaderFile: './my-loader.ts',
  },
}

module.exports = nextConfig

이 로더는 원격 소스에서 이미지를 가져오는 방법을 정의합니다. Cloudinary에 대한 URL을 구성해줍니다.

export default function cloudinaryLoader({
  src,
  width,
  quality,
}: {
  src: string
  width: number
  quality?: number
}) {
  const params = ['f_auto', 'c_limit', `w_${width}`, `q_${quality || 'auto'}`]
  return `https://res.cloudinary.com/demo/image/upload/${params.join(
    ','
  )}${src}`
}

loader 설정까지 완료가 됐다면, Next.js Image 컴포넌트를 다음과 같이 구성을 했을 때

<Image src='/demo' width={50} height={50}/>

image src가 cloudinaryLoader 의 return 값으로 바뀌게 됩니다.

loader덕분에 기존 SSG프로젝트의 소스코드를 건드리지 않고 설정만 바꿔서 적용이 가능합니다.

Cloudinary 업로드 자동화 하기

SSG 프로젝트를 만들면서 필요한 이미지들을 일일이 Cloudinary에 업로드 시키는건 상상만해도 생산성이 많이 떨어지는 작업입니다. 따라서 Cloudinary Node.js SDK를 이용하여 이미지 업로드를 자동화를 하고자 합니다.

이루고자 하는 기능은 다음과 같습니다.

1. public 폴더 아래의 이미지들을 전부 Cloudinary에 업로드
2. 기존에 Next.js에서 정적 assets 들을 불러오는 방식에 영향을 주어선 안된다. (예를들면, public/my-profile.png 파일을 불러올때 /my-profile.png 로 파일 참조)
3. script를 한 번 실행시켜서 이미지 업로드가 동작

cloudinary 설정 확인

Cloudinary로그인시 보이는 화면입니다. Node.js에서 어떤식으로 설정을 해야하는지 예시가 나옵니다.

만약 cloud_name을 바꾸고 싶다면 setting -> account 에 들어간 후 edit을 눌러서 수정을 해주면 됩니다.

script 환경 세팅

cloudinary와 glob을 이용해줍니다.

glob 라이브러리를 사용하면 패턴 매칭을 통해 파일 및 디렉토리를 검색할 수 있습니다.

$ yarn add -D cloudinary
$ yarn add -D glob

저는 api_key와 api_secret의 값을 env로 관리할 예정이므로 dotenv도 추가로 받아줬습니다.

scripts폴더 아래에 upload-cloudinary.ts 파일을 생성해서 cloudinary 설정 관련 코드를 작성해줬습니다.

// scripts/upload-cloudinary.ts
import { v2 as cloudinary } from 'cloudinary';
import { glob } from 'glob';
import dotenv from 'dotenv';

dotenv.config();

cloudinary.config({
  cloud_name: 'ssoon',
  api_key: process.env.CLOUDINARY_API_KEY,
  api_secret: process.env.CLOUDINARY_API_SECRET,
  secure: true, // Return "https" URLs by setting secure: true
});

// Log the configuration
console.log(cloudinary.config());

upload-cloudinary.ts 스크립트를 실행시키기 위해 package.json의 scripts에 작성을 해줍니다. (ts파일로 작성을 해서 ts-node 로 실행을 시켰습니다. js파일로 작성하고 node ./scripts/upload-cloudinary.js로 실행시켜도 무관합니다. )

 "scripts": {
    "upload-cloudinary": "ts-node --project tsconfig.node.json ./scripts/upload-cloudinary.ts"
  },

upload-cloudinary 스크립트를 실행 시킨후에 위에서 설정한 config가 제대로 로그에 다음과 같이 찍히는지 확인을 해줍니다.

{
  cloud_name: 'ssoon',
  api_key: '*********',
  api_secret: '*********',
  secure: true
}

설정을 완료 했으므로 이미지 업로드 관련 로직을 작성해줍니다. 업로드 관련 문서를 확인해 보면 cloudinary.uploader.upload 메서드를 사용하는걸 확인할 수 있습니다.

upload에 필요한 각 옵션을 알아보겠습니다.

• use_filename : 업로드된 파일의 원래 이름을 공개 ID로 사용하도록 해줍니다. 만약 true 로 설정하지 않는다면, 8jsb1xofxdqamu2rzwt9q 와 같은 무작위 ID가 생성이 되므로 무조건 true로 설정을 해야 합니다.
• unique_filename : 옵션은 공개 ID에 임의의 문자를 적용해줍니다. false로 설정해야 임의의 문자를 적용하지 않습니다.
• overwrite : 업로드 시 동일한 공개 ID를 가진 이미지를 덮어씁니다.

upload문서 예시에는 없지만 저는 추가적으로 folder 옵션도 추가를 해줬습니다.

folder 옵션이 없다면, 내가 원하는 뎁스에 이미지를 저장하지 못합니다. Next.js프로젝트에서 public/logo/site-og-image.png 의 이미지 파일을 folder 옵션 없이 Cloudinary에 업로드를 한다면 무조건 root경로에 업로드가 됩니다. (https://res.cloudinary.com/{cloud_name}/image/upload/site-og-image.png 경로에 업로드가 됩니다.) Cloudinary를 적용하기전 프로젝트에선 <Image src='logo/site-og-image.png'/> 와 같은 방식으로 호출을 하고 있었을텐데 만약 ~~~/upload/site-og-image.png 경로에 업로드가 됐다면 기존 소스코드를 <Image src='/site-og-image.png'/> 로 바꿔줘야 합니다. (cloudinaryLoader를 설정 했으므로 ~~~/upload/ 부분은 적어줄 필요가 없습니다.) folder 옵션에 "logo" 를 적어주게 된다면 ~~~/upload/logo/site-og-image.png 경로에 이미지가 업로드가 됩니다.

아래와 같이 옵션을 구성해서 uploadImage 함수를 작성해 줍니다.

// scripts/upload-cloudinary.ts
const uploadImage = async ({
  imagePath,
  folder,
}: {
  imagePath: string;
  folder: string;
}) => {
  const options = {
    use_filename: true, // Use the uploaded file's name as the asset's public ID and
    unique_filename: false,
    overwrite: true, // allow overwriting the asset with new versions
    folder,
  };

  // Upload the image
  const result = await cloudinary.uploader.upload(imagePath, options);
  return result.public_id;
};

glob으로 public 폴더 아래의 .jpg, .jpeg, .png, .gif 등의 확장자가 있는 경로를 패턴매칭으로 검색하고 일치하는 파일 경로를 반환 받습니다.

예를 들어 폴더구조가 위와 같이 구성되어 있으면 ['public/posts/blog/example/example-1.png','public/posts/blog/example/example-2.png','public/static/my-profile.webp'] 위 목록을 반환받을 수 있게 패턴을 작성해줍니다.

glob을 이용해서 반환받은 파일 경로는 uploadImage 함수의 imagepath 파라미터에 그대로 넣어줍니다. 그리고 folder 의 경로를 public을 제외하고 넣어줄 수 있게 로직을 작성해줍니다. (public을 제외하는 이유는 위에서 계속 설명을 했듯이 Next.js 프로젝트 내부에서 이미지를 사용할때 public을 붙이고 가져오지 않기 때문입니다.)

// scripts/upload-cloudinary.ts
(async () => {
  const blogImgPaths = await glob(['public/**/*.{jpg,jpeg,png,gif,webp,svg}']);

  if (blogImgPaths.length) {
    const uploadPromises = blogImgPaths.map(async (imgPath) => {
      const folder = imgPath
        .replace('public/', '')
        .replace(/\/[^/]+\.(jpg|jpeg|png|gif|webp|svg)$/, '');
      return uploadImage({
        imagePath: imgPath,
        folder,
      });
    });
    try {
      const result = await Promise.all(uploadPromises);
      console.log('result', result);
    } catch (e: any) {
      throw new Error(e);
    }
  }
})();

최종 코드의 모습입니다.

// scripts/upload-cloudinary.ts
import { v2 as cloudinary } from 'cloudinary';
import { glob } from 'glob';
import dotenv from 'dotenv';

dotenv.config();

cloudinary.config({
  cloud_name: 'ssoon',
  api_key: process.env.CLOUDINARY_API_KEY,
  api_secret: process.env.CLOUDINARY_API_SECRET,
  secure: true, // Return "https" URLs by setting secure: true
});

// Log the configuration
console.log(cloudinary.config());
/////////////////////////
// Uploads an image file
/////////////////////////
const uploadImage = async ({
  imagePath,
  folder,
}: {
  imagePath: string;
  folder: string;
}) => {
  const options = {
    use_filename: true, // Use the uploaded file's name as the asset's public ID and
    unique_filename: false,
    overwrite: true, // allow overwriting the asset with new versions
    folder,
  };

  // Upload the image
  const result = await cloudinary.uploader.upload(imagePath, options);
  return result.public_id;
};

(async () => {
  const blogImgPaths = await glob(['public/**/*.{jpg,jpeg,png,gif,webp,svg}']);
  if (blogImgPaths.length) {
    const uploadPromises = blogImgPaths.map(async (imgPath) => {
      const folder = imgPath
        .replace('public/', '')
        .replace(/\/[^/]+\.(jpg|jpeg|png|gif|webp|svg)$/, '');
      return uploadImage({
        imagePath: imgPath,
        folder,
      });
    });
    try {
      const result = await Promise.all(uploadPromises);
      console.log('result', result);
    } catch (e: any) {
      throw new Error(e);
    }
  }
})();

public폴더에 이미지를 막 넣고 yarn upoad-cloudinary 스크립트를 실행 시킨 결과입니다.

cloudinary에 자동으로 업로드가 되는 모습을 볼 수 있습니다. (아래 사진은 posts/blog 아래에 업로드된 이미지들만 본 결과입니다. )

이제 프로젝트에서 이미지를 사용할 때 static assets경로를 적어주면 기존 코드 수정 없이 cloudinaryLoader 통해 Cloudinary에 업로드된 이미지를 사용할 수 있습니다.

<Image
  src="/logo/white-logo.png"
  width={80}
  height={40}
  priority
  alt="site logo"
/>

마치며

Next.js에서 자체적으로 빌드타임때 이미지 최적화를 해준다면 이런 번거로운 작업은 안 해도 될 거 같은데 살짝 아쉬운거 같습니다. Next.js를 SSG로 마케팅하는 것은 올바르지 않다는 의견도 보이네요 😅 (그래도 Next.js SSG로 개인 블로그를 만들때 이미지 최적화 작업을 제외하면 좋은 경험이였습니다..)

여러분들은 혹시 모듈 캐싱에 대해 알고 계신가요? 모던 웹 개발을 하면서 자연스럽게 활용되는 모듈 시스템의 빠질 수 없는 개념인 모듈 캐싱에 대해 함께 알아보고자 합니다. 모듈 캐싱의 동작 원리와 함께 주의해야 할 사항들을 예시 코드들을 통해 자세히 살펴보도록 하겠습니다.

예시1) js 모듈 스코프

// moduleA.js
let counter = 0;

export function incrementCounter() {
  counter++;
}

export function getCounterValue() {
  return counter;
}

// moduleB.js
import { incrementCounter, getCounterValue } from './moduleA';

console.log(getCounterValue()); // 출력: 0

incrementCounter(); // counter 값 증가

console.log(getCounterValue()); // 출력: 1

// moduleC.js
import {getCounterValue} from './moduleA'

console.log(getCounterValue()); // 출력: 1

moduleC 파일을 살펴보면, counter 변수가 1로 출력되는걸 알 수 있습니다. 마치 moduleB와 moduleC가 한 모듈 스코프 내에 있는것 처럼 결과가 나타났습니다.

왜 이런 결과가 나왔을까요?

모듈 캐싱에 대하여

모듈 시스템에서의 중요한 개념 중 하나는 모듈은 기본적으로 한 번만 로드되고 실행된다는 것입니다. 이는 여러 번 모듈을 불러와 사용하더라도 해당 모듈은 최초 호출 시에만 로드되고 실행된다는 것을 의미합니다. 만약 매번 호출할 때마다 모듈을 실행시키는 방식이라면 moduleC 에서 0이 출력이 됬겠지만, 메모리 사용이 불필요하게 늘어날 수 있습니다. 최초 호출 시에만 모듈을 로드하여 캐싱하는 것은 메모리 사용을 최적화하는 데 도움을 줍니다. 이후 요청 시 해당 모듈이 캐시에 존재하면 재로딩하지 않고, 캐싱된 인스턴스를 활용합니다.

예시1 코드 단계별 동작 과정

1. moduleA 파일에 counter 변수와 getCounterValue 함수를 정의합니다.
2. moduleB에서 moduleA의 함수를 import하고 호출합니다. 이때 moduleA가 로드됩니다.
3. moduleB의 코드 실행 후, moduleC가 실행됩니다. 이때 이미 로드된 moduleA를 다시 로드하지 않고, 이전에 캐싱된 moduleA의 항목들을 그대로 사용합니다.
4. 따라서 moduleC에서 getCounterValue 함수를 호출하면, 이미 증가된 counter 변수의 값인 1이 출력됩니다.

이렇게 moduleB와 moduleC에서 공유하는 moduleA의 모듈 스코프를 통해 변수와 함수가 상태를 유지하며 공유되는 것을 볼 수 있습니다.

예시2) 리액트 함수형 컴포넌트의 바깥 변수 문제

리액트에서 함수형 컴포넌트를 사용할 때, 컴포넌트 바깥에 선언된 변수를 사용하는 경우가 종종 있습니다. 이때 문제가 발생할 수 있는데, 변경 가능한 변수를 컴포넌트 바깥에 선언을 하고 함수형 컴포넌트 내에서 바깥의 변수를 사용할 경우 입니다. 해당 문제도 모듈 스코프의 캐싱 동작 문제입니다.

Counter 라는 함수형 컴포넌트의 바깥에 count 변수를 선언하고 handleCountIncrease 함수를 통해 count 변수를 증가시키는 코드입니다.

// Counter.jsx
import React, { useState } from "react";

let count = 1;

const Counter = () => {
  const [_, setCount] = useState(0);
  const handleCountIncrease = () => {
    setCount(count++);
  };
  return (
    <div style={{ display: "flex", alignItems: "center", gap: "5px" }}>
      <div>{count}</div>
      <button onClick={handleCountIncrease}>+</button>
    </div>
  );
};

export default Counter;

Counter 컴포넌트를 사용하는 부분에서 Counter 컴포넌트를 중복 호출을 했습니다.

import React from "react";
import Counter from "./components/Counter";

function App() {
  return (
    <div className="App">
      <Counter /> {/* 1번 Counter */}
      <hr />
      <Counter /> {/* 2번 Counter */}
    </div>
  );
}

export default App;

1번의 컴포넌트의 counter 값을 5까지 올리고 2번 컴포넌트의 counter 값을 올리면 결과가 어떻게 나올까요? 리액트 컴포넌트를 활용해서 개발을 해온 입장에서는 counter값이 2가 나오는걸 기대하는게 일반적이겠지만, 정답은 6 입니다. 6이라는 값이 나온 이유는 위에서 설명한 모듈 캐싱 동작과 관련이 있습니다.

동작 과정을 살펴 보자면, 예시1의 단계별 동작 과정과 유사한 과정을 거치게 됩니다.

1. App 컴포넌트에서 Counter 컴포넌트를 import하고 호출합니다. 이때 Counter 컴포넌트의 모듈이 로드 됩니다.
2. 1번 Counter 컴포넌트 실행 후 2번 Counter 컴포넌트가 실행이 됩니다. 이때 이미 로드된 Counter 컴포넌트의 모듈은 실행되지 않습니다.
3. 1번 Counter 컴포넌트에서 count 변수를 5까지 올린 후 2번 Counter 컴포넌트에서 handleCountIncrease 함수를 실행 시키면 이미 메모리에 올라가있는 count 변수에 1이 더해져서 6이 출력이 됩니다.

함수형 컴포넌트 외부 변수 예시에서 상세 코드 확인이 가능합니다.

리액트에서 모듈 스코프의 캐싱 동작에 대해 알아봤습니다. 그렇다면, 컴포넌트가 언마운트(unmount) 일때 모듈 캐싱은 어떻게 동작을 할까요?

컴포넌트 언마운트시 모듈 캐싱 동작

리액트에서 컴포넌트가 언마운트되면 해당 컴포넌트와 관련된 리소스 및 상태 등이 정리됩니다. 하지만, 모듈의 캐싱은 모듈 시스템 자체의 동작 방식에 의해 처리되므로, 컴포넌트의 언마운트와 직접적인 연관이 없습니다.

컴포넌트 언마운트 예시에서 상세 코드 확인이 가능합니다.

예시3) 리액트에서 debounce 사용시 예제

즉시실행 함수와 클로저를 조합한 util 함수 문제점

react프로젝트에서 util 함수로 IIFE를 이용하여 debounce를 구현했습니다.

// /utils/debounce.ts
export const debounce = (() => {
  let timeoutId: ReturnType<typeof setTimeout>;
  return (callback: () => void, delay: number) => {
    clearTimeout(timeoutId);
    timeoutId = setTimeout(callback, delay);
  };
})();

input에서 util의 debounce함수를 이용하는 예시 입니다.

onChange이벤트가 발생하고 1초 동안 onChange 이벤트가 없으면 입력한 값이 보이게 됩니다.

자세한 동작 과정은 이렇습니다.

1. debounce 함수는 모듈 스코프에서 생성되고 실행됩니다.
2. 이 함수는 클로저로서 timeoutId 변수에 접근이 가능합니다.
3. debounce 함수를 import시 모듈이 로드가 되고 timeoutId 변수가 debounce 함수의 렉시컬 스코프 내에 선언되었습니다.
4. InputField가 리렌더링 되어도 timeoutId 는 모듈 스코프 내에서 선언되어 있기 때문에 값이 유지가 됩니다.
5. 따라서 InputField 컴포넌트는 원하는 대로 동작을 하게 됩니다.

// /components/InputField

import { useState } from "react";
import { debounce } from "../utils/debounce";

interface Props {
  type: string;
}

const InputField = ({ type }: Props) => {
  const [value, setValue] = useState("");
  const [debounceValue, setDebounceValue] = useState("");
  const handleInputChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    const value = e.currentTarget.value;
    setValue(value);
    debounce(() => setDebounceValue(value), 1000);
  };

  return (
    <>
      <input value={value} onChange={handleInputChange} />
      <div>
        {type}값 : {debounceValue}
      </div>
    </>
  );
};

export default InputField;

debounce 함수를 따로 hook으로 작성을 안 하고 IIFE 로 작성한 결과 컴포넌트에서 바로 import 후 사용하는 형태여서 매우 편하게 사용이 가능한 모습입니다.

그런데 만약 InputField컴포넌트를 사용하는 곳에서 컴포넌트를 두 번 호출을 했다면 정상적으로 동작을 할까요?

import InputField from "./components/InputField";

function App() {
  return (
    <div className="App">
      <InputField type="A" />
      <hr />
      <InputField type="B" />
    </div>
  );
}

export default App;

위의 예시에서 InputField 컴포넌트 내부에서 같은 모듈에서 가져온 debounce 함수를 사용하는 경우, 두 컴포넌트 간에 같은 timeoutId 변수를 공유하게 됩니다. 이로 인해 type A인 InputField에 값을 입력하다가 1초 이내에 type B인 InputField에 값을 입력하면, 두 컴포넌트에서 동일한 debounce 함수를 동시에 조작하게 됩니다.

timeoutId 변수를 공유하기 때문에 type A 컴포넌트의 입력이 type B 컴포넌트의 입력에 영향을 줄 수 있습니다. 즉, type A 입력에서의 디바운싱(delay) 동작이 type B 입력에 영향을 미칠 수 있게 되는 것입니다.

util IIFE deboune 에서 상세 코드 확인이 가능합니다.

개선 방향

이러한 문제를 방지하기 위해서는 InputField 컴포넌트 내부에서 debounce 함수를 사용할 때 즉시 실행 함수(IIFE)를 활용하여 timeoutId를 모듈 스코프에서 캐싱하지 않도록 해야 합니다.

해결 방법은 다음과 같이 debounce 함수 사용 시, 컴포넌트마다 독립적인 timeoutId 변수를 활용하는 것입니다. 이를 통해 각 InputField 컴포넌트는 자신만의 타이머를 유지하며 디바운싱을 수행하게 됩니다.

export const debounce = <T extends unknown[]>(
  callback: (...args: T) => void,
  delay: number
) => {
  let timeoutId: ReturnType<typeof setTimeout>;
  return (...args: T) => {
    clearTimeout(timeoutId);
    timeoutId = setTimeout(() => callback(...args), delay);
  };
};

컴포넌트 리렌더링시 timeoutId 가 초기화 되는 문제도 고려해야 하기 때문에 커스텀 훅에서 useCallback 을 이용하는 방법으로 개선시킬 수 있습니다.

import { useCallback } from "react";
import { debounce } from "../utils/debounce";

export const useDebounce = <T extends unknown[]>(
  callback: (...args: T) => void,
  delay: number,
  deps: unknown[]
) => {
  const debounceCallback = useCallback(
    debounce((...args: T) => callback(...args), delay),
    [...deps]
  );
  return debounceCallback;
};

debounce hooks 에서 상세 코드 확인이 가능합니다.

마치며

모듈을 import하여 사용하는 과정에서 발생할 수 있는 모듈 캐싱의 문제들을 예시코드로 다뤄봤습니다.

실제 프로젝트에서도 모듈 캐싱 동작에 대한 이해를 바탕으로 안정성 있는 코드를 작성할 수 있을 것입니다.

제가 작성한 내용이 도움이 되었으면 좋겠습니다. 만약 잘못된 정보가 있다면, 부담 없이 댓글로 알려주세요 😀

부족한 글 읽어주셔서 감사합니다.

아래 예시들을 통해 항목을 고유하게 식별할 때의 이점과 리액트에서 key 를 잘 활용하는 방법을 알아보자

배열 랜더링 예시

다음과 같은 배열이 있을 때 map을 이용해서 랜더링을 한다고 생각해보자

export default function App() {
  const [list,setList] = useState(['a','b','c','d']);
  return (
    <ul>{list.map(item => <li>{item}</li>)}</ul>
  );
}

a,b,c,d 순서대로 화면에 랜더링이 될 것이다.

그런데 위와 같이 배열을 랜더링하면 문제가 생긴다.

❗ Warning: Each child in a list should have a unique “key” prop.

이 짜증나는 에러를 누구나 한 번쯤은 본 적이 있을것이다. (저 에러 없애려고 배열 index를 key로 넣은 사람 🤚)

리액트팀에서 저 에러를 보여주는 이유는 컴포넌트의 효율적인 랜더링을 위해서다.

key는 왜 존재할까?

리액트의 효율적인 랜더링을 위해서 존재한다.

철수와 짱구가 공용으로 사용하는 컴퓨터에 파일이 있다고 생각해보자. 각 파일명은 맹구,유리 이다. 어느날 철수가 두 파일 사이에 훈이를 추가 하면 짱구는 어떻게 생각을 할까? 다음날 짱구가 해당 컴퓨터 파일을 볼 때 유리자리에 훈이가 추가된 걸 순식간에 알 수 있을 것이다. 그런데 만약 컴퓨터 파일에 파일명이 존재하지 않는다면? 폴더 아이콘만 있다고 생각해보자. 맹구,유리 사이에 훈이가 추가 됐다면 어떤게 추가된 파일이 뭔지 바로 알 수 있을까? 일일이 파일을 들어가봐야 유리 자리에 훈이가 추가 된 것을 알 수 있을것이다.

이러한 비효율적인 일을 하지 않기 위해 react팀에서는 key(파일명)를 만들었다.

key가 없다면 react 입장에서는 어떤게 새롭게 추가된 요소고 어떤게 기존에 존재하던 요소인지 효율적으로 알 수가 없다. ( 자세한 내용은 상태 유지 및 재설정 문서에 나와있다. )

리액트는 형제요소 간에 항목을 고유하게 식별하기 위해 key 가 필요하다.key 가 변하면 항목이 변했다고 간주한다.

이런 리액트의 효율적인 알고리즘을 위해 리액트로 개발하는 개발자 분들이 key를 꼭 넣어주는 수고스러움을 견뎌야 한다.

💡 중요 : key는 전역적으로 유지되지 않고 부모 요소의 내부에서만 유효하다!

배열에서의 key 활용법

이제 key를 왜 추가해야 하는지 알겠는데 다음 코드처럼 배열의 index를 key props로 활용하면 쉽게 해결 되겠네? 라고 생각한다면, 맞기도하고 틀리기도 하다.

콘솔 창의 에러만 없앤 것이지 key를 쓰기 전 동작과 동일하다.

export default function App() {
  const [list,setList] = useState(['a','b','c','d']);
  return (
    <ul>{list.map((item,index) => <li key={index}>{item}</li>)}</ul>
  )
}

배열의 index를 key로 활용할 경우

key를 배열의 index로 사용하는 경우는 두 가지 조건을 모두 만족해야 한다.

• 리스트에 수정, 삭제, 삽입을 할 일이 없을 때
• 리스트의 순서가 변하지 않을 때

이유는 list가 변할 때 컴포넌트가 리렌더링 되면서 배열의 0번 째 index 에 새로운 요소가 추가 됐다면 리액트는 기존의 key 가 0인 컴포넌트가 변하지 않았다고 생각한다.

그래서 변경이 있을거 같은 리스트인 경우 key 를 배열의 index 로 적어주는건 매우 위험하다.

변하는 리스트에서 key를 배열의 index로 사용한다면?

다음 코드 예시로 위험성을 알아보자.

import { useState } from "react";

const Input = (props) => {
  const { placeholder } = props;
  const [value, setValue] = useState("");
  const handleInputChange = (e) => {
    setValue(e.currentTarget.value);
  };

  return (
    <input
      placeholder={placeholder}
      value={value}
      onChange={handleInputChange}
    />
  );
};

export default function App() {
  const [list, setList] = useState(["aaa", "bbb", "ccc", "ddd"]);
  const handleListInsertClick = () => {
    setList((prevList) => ["eee"].concat(prevList));
  };
  return (
    <div>
      <div>
        {list.map((item,index) => (
          <Input key={index} placeholder={item} />
        ))}
      </div>
      <div>
        <button onClick={handleListInsertClick}>요소 삽입</button>
      </div>
    </div>
  );
}

요소 삽입 버튼 클릭시 배열의 맨 앞에 리스트를 추가하는 상황이다.

그리고 input값은 각각 다음과 같다.

위 상황에서 요소 삽입 버튼을 누른다면 eee를 placeholder로 보여주는 input 창이 맨 앞에 나오고 aaa입니다. bbb입니다. 순으로 화면에 보여지는게 기대하는 자연스러운 동작일 것이다.

하지만, 기대와 다르게 요소 삽입 버튼을 누르면 다음과 같이 컴포넌트가 랜더링이 된다.

eee를 0번 째 index 에 삽입을 했으니 eee를 기존의 key 값이 0이였던 컴포넌트로 인식을 해서 상태가 그대로 유지가 된 상황이다.

리액트는 key값을 기준으로 요소가 변경되었는지 판단하기 때문에 당연한 결과이다.

key 값을 리스트 각 하위 항목별로 고유한 id로 적어준다면 예상한대로 동작을 한다.

코드를 다음과 같이 바꿔 보자!

const [list, setList] = useState([
    { id: 0, text: "aaa" },
    { id: 1, text: "bbb" },
    { id: 2, text: "ccc" },
    { id: 3, text: "ddd" }
  ]);
const handleListInsertClick = () => {
  setList((prevList) => [{ id: 4, text: "eee" }].concat(prevList));
};

//...
{list.map((item, index) => (
  <Input key={item.id} placeholder={item.text} />
))}
//...

eee를 삽입시 새로운 항목이 추가됐다고 올바르게 인식을 하고 추가가 정상적으로 잘 됐다.

혹시나 고유한 id를 적어야 하므로 key 에 다음 형태로 넣는건 제발 하지 말자.

<Input key={Math.random()} />

리스트가 변하고 컴포넌트가 리렌더링되면 기존의 key가 다른값으로 바뀌기 때문에 전체 리스트가 새로운 컴포넌트로 인식이 된다.

그렇다면 변하는 리스트의 key에는 교유한 값을 어떻게 넣어줘야 할까?

• 서버에서 리스트를 내려줄 때의 id
• 로컬에서 데이터를 생성했다면 항목을 생성할 때 id를 미리 추가. (incrementing counter , uuid , crypto.randomUUID() 등.. )

리스트의 key에는 컴포넌트가 랜더링 될 때마다 리스트 항목의 key가 바뀌는 값을 넣어주면 안된다.

한 번 생성된 리스트의 key는 다시 렌더링 되더라도 바뀌면 안된다.

컴포넌트 상태 초기화시 key 활용법

key는 배열을 렌더링 할때만 사용하는것이 아니다.key 는 컴포넌트의 식별자라고 생각하면 된다.

key 가 바뀌면 리액트는 새로운 컴포넌트로 인식을 한다는 점을 이용하면 아주 간편하게 컴포넌트의 상태를 초기화 시킬 수 있다.

예시 상황을 보자

ProfilePage 컴포넌트는 useId 를 props로 받는다.

페이지에는 댓글이 포함되어 있으며 comment 상태값을 이용하여 해당 값을 보유한다.

한 프로필에서 다른 프로필로 이동할 때 comment 의 상태가 재설정되지 않는 오류가 있을 때 어떻게 해결을 할 것인가?

다음 코드와 같이 작성하면 된다.

export default function ProfilePage({ userId }) {
  return (
    <Profile
      userId={userId}
      key={userId}
    />
  );
}

function Profile({ userId }) {
  // ✅ This and any other state below will reset on key change automatically
  const [comment, setComment] = useState('');
  // ...
}

key를 사용해서 useEffect 사용을 없애고 아주 우아하게 컴포넌트의 상태값을 초기화 하는 방법을 공식문서에서 확인할 수 있다.(useEffect가 필요하지 않을수도 있다!)

요약

1. 리스트가 변할 가능성이 없다면 배열의 index를 key로 적어도 된다.
2. 리스트가 변할 가능성이 있다면 배열의 index를 key로 쓰는 행동은 절대 하지 말자.
3. 컴포넌트의 상태를 초기화 시키고 싶다면 key를 이용해보자!

❗️library maintainer 일 경우에 대한 에러 해결법 입니다.

만약 maintainer가 아니고 next를 사용하고 있다면 next-transpile-modules 를 사용하시면 됩니다. next에서 사용이 가능하게 transfile을 도와줍니다.

1️⃣ 사용하는 프레임워크의 esm 모듈 지원 여부를 확인 해준다.

Next.js 11.1 부터 ES Modules (e.g. "type": "module" in their package.json) 사용이 가능하다. config.js에 아래 속성을 꼭 적어줘야 한다.

// next.config.js
module.exports = {
  // Prefer loading of ES Modules over CommonJS
  experimental: { esmExternals: true },
};

https://nextjs.org/blog/next-11-1#es-modules-support

ESM 라이브러리의 package.json에 {"type": "module"}이 있는 한 Next.js 12부터는 ES Module에 대한 지원이 기본적으로 활성화됩니다. (esmExternals이 기본적으로 true) https://stackoverflow.com/questions/65974337/import-es-module-in-next-js-err-require-esm

2️⃣ 사용한 모듈의 package.json 확인

package.json 에 "type" 필드가 없거나 "type:commonjs" 인 경우 .js 파일은 CommonJS로 처리된다. "type" : "module" 인 경우엔 ES Module 으로 인식한다.
"type" 필드 값에 관계없이 .mjs 확장자를 가진 파일은 항상 ES Module로 처리되고 .cjs 파일은 항상 CommonJS로 처리된다.
https://nodejs.org/dist/latest-v18.x/docs/api/packages.html#type

위 글을 보면 알 수 있듯이 esm으로 번들링후 해당 모듈을 코드베이스에서 사용할 때 ES Module의 package.json 이나 파일의 확장자에 이 모듈은 ES Module입니다. 라는 명시를 해주지 않으면 사용하는 쪽에서 해당 모듈을 해석할 때 ES Module로 인식을 하지 않고 CommonJS로 인식 함

🔥 그래서 import 에러는 왜 나는건데?

node 에서 ECMAScript 모듈 로더를 사용해야 ES Module 사용이 가능한데 ES Module에서 ECMAScript 모듈 로더를 사용하기 위한 설정을 하지 않아서 생긴 에러이다. 요약하자면, node가 ES Module을 CommonJS 모듈 로더를 사용해서 생긴 문제이다. https://nodejs.org/dist/latest-v16.x/docs/api/esm.html

🚀 결론

csr 에서 사용이 잘 되는 ES Module 인데 ssr에서 동작이 안된다면? ssr쪽에서 ES Module로 인식을 못 하고 있는 것이다.(ES Module 지원을 안 하는 프레임워크거나...) package.json 에 {"type" : "module"}를 적어주거나 확장자를 변경하도록 하자!

잘못된 정보가 있다면 댓글로 지적 부탁드립니다!🙇‍♂️

incldues 와 has 중 뭐가 더 빠를까? 자료구조를 생각해보면 바로 예상이 갈 것이다.

let n = 20000;
let arr = Array.from({ length: n }, (v, i) => i + 1); 
console.time( 'includes Test' );
arr.includes(10000)
console.timeEnd( 'includes Test' );
let set = new Set( arr );
console.time( 'has Test' );
set.has(10000)
console.timeEnd( 'has Test' );

🚀 코드 실행 결과

incldus Test -> 0.010009765625 ms has Test -> 0.003173828125 ms

당연하게도 has로 조회하는게 더 빠르다.

결과를 보고 includes 대신 무조건 has를 써야겠다! 라는 생각이 들 수 있다. 하지만, 항상 has를 사용하는게 좋은건 아니다. 두가지 경우를 보자!

1️⃣ client에서의 has

사이즈가 큰 배열(10만 이상)을 조회하고 싶을 때 set 자료구조에 넣어서 조회하면 매우 빠르게 조회가 가능할 것이다. 하지만, client단에서 굳이 has를 사용하기 위해 set 에 배열 데이터를 넣어야할까? 10만 이상의 데이터를 client단에서 다룰일이 없다고 생각한다. 또한, 10만 이상의 데이터를 조회할 일은 더더욱 없다.

https://stackoverflow.com/questions/39007637/javascript-set-vs-array-performance

위 글을 보면 10만 이상의 데이터를 다룰때 유의미한 차이가 발생한다.

그리고 위 사진처럼 현재 크롬 브라우저에선 배열의 사이즈가 16,777,216를 넘어서면 maximum size exceeded 에러가 발생한다.

client단에선 includes를 사용하자..!

2️⃣ server에서의 has

서버단에서는 db에 있는 데이터를 조회하는 일이 아니라면 inlcudes 대신 has 를 사용하면 좋을거 같다.

결론

조회에 있어선 has 가 includes 보다 빠르지만, 상황에 맞게 사용해야할 거 같다.

잘못된 정보가 있다면 댓글로 지적 부탁드립니다!🙇‍♂️

어떠한 요소 A 가 blur 이벤트를 기다리는중이다. (요소가 focus 되어있는 상황) 이때 다른 요소 B 의 click 이벤트를 먼저 실행시키고 싶다면 어떻게 해야 할까?

B의 click 이벤트를 실행 시키면 mousedown -> blur -> click 순으로 이벤트가 실행이 된다. 브라우저의 click 이벤트에 대한 기본 동작이다. 위 순서를 봤을때 B의 click 이벤트가 실행이 된다면 blur 이벤트가 click 이벤트 보다 먼저 실행이 될 것이다.

그럼 click 이벤트시 blur 이벤트를 무시하는 방법은 없을까?

preventDefault()메서드를 사용하면 된다. preventDefault는 브라우저의 기본 동작을 실행하지 않도록 해준다.

blur이벤트를 무시하는 법

1. click 이벤트를 달아준 B 에 mousedown 이벤트를 추가 해준다.
2. preventDefault 메서드를 실행시켜 해당 이벤트에 대한 사용자 에이전트의 기본 동작을 실행하지 않도록 지정한다.

참고자료 🔗 https://developer.mozilla.org/ko/docs/Web/API/Event/preventDefault

nuxt ssr훅에서 인스턴스 생성 후 해당 메서드에 접근을 할 때 왜 문제가 생길까??

export default class Item {
  id;
  title;
  subTitle;
  writer;
  constructor(id, title, subTitle, writer) {
    this.id = id;
    this.title = title;
    this.subTitle = subTitle;
    this.writer = writer;
  }
  hello(): void {
    console.log('hello~~~~');
  }
}

위의 클래스를 fetch나 asyncData훅에서 생성을 하게 되면 ssr훅의 컨텍스트가 종료가 될때 ssr에서 생성한 인스턴스의 전체 구성 요소 상태가 문자열화된다.

⭐️ 생성한 인스턴스의 메서드 접근 가능 할 때

data(){
  return{
    item : null
  }
},
fetch(){
  this.item = new Item(1,'title','subtitle','writer');
  this.item.hello();
}

❗️생성한 인스턴스의 메서드 접근이 불가능 할 때

mounted(){
  this.item.hello();
}

fetch훅이 끝난 후 mounted에서 메서드에 접근을 하게 되면 메서드에 접근을 못 하게 된다.

참고자료

🔗 https://github.com/nuxt/nuxt.js/issues/10277

배너에 splide 모듈을 사용 했는데 transition이 일어날때 마다 safari에서 깜빡이면서 넘어가는 현상이 있었다.

💡해결책

처음엔 어떠한 이유(모듈 자체의 이슈?) 때문에 버그가 발생했는지 명확히 몰라서 헤맸는데 safari transition bug 라는 키워드로 검색을 해보니

-webkit-transform: translate3d(0, 0, 0);

위 속성을 적용 하라는 글들이 많았다. 깜빡거리는 요소에 추가를 해주니 정상 동작을 확인 할 수 있었다.

속성 설명

transition3d로 하드웨어 가속을 사용하게 변경을 해줘서 깜빡이는 현상을 없애 준다.

transition3d 대신 will-change: -webkit-transform을 추가해줘도 정상 동작을 한다. 하지만, 배너를 하나하나 추가 할 때마다 모든 엘리먼트에 will-change가 붙게 될 것이다. 너무 많은 엘리먼트에 will-change를 사용하게 된다면 자원을 대량으로 사용할 수 있으므로 사용하지 않았다.