4개 언어를 지원하는 예약 사이트를 개발하던 중, 언어를 바꿔도 날짜의 요일 표기만 그대로 남는 이슈를 발견했다. 원인은 i18n과 moment.js가 서로 다른 로케일 체계를 사용한다는 점이었다. 두 라이브러리를 언어 변경 이벤트로 동기화하고, 중국어 weekday는 moment 기본 표기(周X)와 디자인 시안(星期X)이 달라 디자이너와 협의를 거쳐 정자형으로 통일한 과정을 정리한다.

1. 문제 인식

사이트 상단의 언어 선택을 한국어에서 영어로 바꾸자 메뉴와 본문 텍스트는 영어로 잘 바뀌었지만, 예약 캘린더의 요일 표기만은 여전히 한국어("일 / 월 / 화 / 수 / 목 / 금 / 토")로 남아있었다.

처음에는 번역 키가 빠진 줄 알고 번역 파일을 확인했다. 그런데 해당 텍스트는 번역 키 자체가 아니었다. 코드를 따라가 보니 그 자리에는 moment.js로 포맷팅한 결과가 들어가고 있었다.

moment(date).format('dddd'); 
// → '월요일' (언어를 영어로 바꿔도 계속 한국어)

호출부에서는 어떤 언어 관련 인자도 전달하고 있지 않았다. 그렇다면 출력 결과를 결정하는 것은 moment 내부의 로케일 상태일 수밖에 없었다. 콘솔에서 moment.locale()을 확인해 보니, 언어를 영어로 바꿔도 값은 계속 'ko'로 남아 있었다. i18n 쪽 언어를 바꿔도 moment의 로케일은 그대로라는 의미였다. 그제야 두 라이브러리가 서로의 로케일을 공유하지 않는다는 점을 알게 됐다.

그렇다면 각 라이브러리가 왜 자기만의 로케일을 갖고 있는지부터 짚어볼 필요가 있었다.

2. 원인 분석

대부분의 i18n 라이브러리(i18next, react-intl 등)는 번역 텍스트만 관리한다. t('greeting')이 '안녕하세요'로 매핑되는 키-값 구조가 핵심이다.

반면 moment.js(혹은 date-fns, dayjs)는 날짜와 시간 포맷팅을 위한 자체 로케일을 별도로 갖는다. 월 이름, 요일 이름, 시간 형식("오전 9시" vs "9 AM"), 상대 시간 표현("3일 전") 같은 정보가 여기에 들어있다.

// i18n: 텍스트 키-값 매핑
i18n.t('greeting') // → '안녕하세요'

// moment: 날짜 포맷팅에 자체 로케일 사용
moment().format('LL') // → '2025년 11월 11일' (한국어 로케일일 때)

즉, i18n.changeLanguage('en')을 호출해도 moment의 로케일은 바뀌지 않는다. 그래서 번역 텍스트는 전환되지만 날짜 표기는 한국어로 남는, 절반만 동작하는 상태가 된다.

같은 문제는 moment뿐 아니라 브라우저 내장 Intl.NumberFormat, Intl.DateTimeFormat, 통화·숫자 포맷팅 라이브러리 전반에 동일하게 적용된다. 각 라이브러리는 자체 로케일을 가지고 있고, 명시적으로 동기화하지 않으면 따로 움직인다.

결국 두 로케일을 명시적으로 묶어주는 작업이 필요했다.

3. 1차 해결 — 언어 변경 이벤트로 두 로케일 연결

i18next는 언어가 바뀔 때마다 languageChanged 이벤트를 발화한다. 이 이벤트에 moment.locale() 호출을 연결하면 두 로케일이 함께 움직인다.

import i18n from 'i18next';
import moment from 'moment';

// 언어 변경 이벤트 → moment 로케일 동기화
i18n.on('languageChanged', (lng) => {
  moment.locale(lng);
});

한 가지 주의할 점이 있다. moment는 기본적으로 영어 로케일만 들고 있다. 다른 언어를 사용하려면 명시적으로 import해서 등록해야 한다.

import 'moment/locale/ja';     // 일본어
import 'moment/locale/zh-cn';  // 중국어
// 한국어는 'moment/locale/ko'

import만 해두면 moment가 내부적으로 해당 로케일을 등록한다. 등록되지 않은 로케일을 moment.locale('xx')로 호출하면 오류 없이 영어로 폴백되기 때문에, 누락된 import는 런타임에 발견하기 어렵다.

이 설정까지 적용하면 한국어 / 영어 / 일본어 간 전환은 의도대로 동작했다. 다만 중국어 화면에서는 또 다른 이슈가 남아 있었다.

4. 추가 이슈 — 중국어 weekday 표기 차이

QA를 돌리던 중, 중국어 화면의 요일 표기가 디자인 시안과 다른 것을 발견했다.

확인해 보니 moment의 zh-cn 기본 로케일은 요일을 다음과 같이 출력하고 있었다.

周日 周一 周二 周三 周四 周五 周六

반면 디자인 시안은 정자형이었다.

星期日 星期一 星期二 星期三 星期四 星期五 星期六

두 표기 모두 문법적으로 올바른 중국어다. 차이는 다음과 같다.

라이브러리 기본값(周X)이 틀린 표기는 아니었기 때문에 처음에는 그대로 두는 것도 고려했다. 다만 디자이너가 정자형을 의도해서 선택했을 가능성이 있어 의도를 확인해 보았는데, 한옥 예약 서비스 특유의 전통적이고 격식 있는 톤을 살리기 위해 의도적으로 정자형을 선택한 것이었다.

5. 2차 해결 — moment.updateLocale로 weekday 덮어쓰기

요일 표기만 바꾸기 위해 moment.updateLocale을 사용했다.

const updateMomentLocale = (lng: string) => {
  if (lng === 'zh') {
    // 중국어는 디자인 시안에 맞춰 weekday 커스텀
    moment.updateLocale('zh-cn', {
      weekdays: ['星期日', '星期一', '星期二', '星期三', '星期四', '星期五', '星期六'],
    });
  } else {
    moment.locale(lng);
  }
};

여기서 moment.locale과 moment.updateLocale은 동작이 다르다.

• moment.locale('zh-cn') — 어떤 로케일을 사용할지 선택한다. 기존 로케일을 그대로 사용한다.
• moment.updateLocale('zh-cn', { ... }) — 기존 로케일의 일부 설정만 덮어쓴다. 명시한 필드(weekdays)만 바뀌고, 나머지 설정(월 이름, 시간 표기, 상대 시간 등)은 기본값을 유지한다.

updateLocale을 사용하면 weekdays만 정자형으로 바꾸고, 월 이름(一月 / 二月 / ...)이나 시간 표기는 기본 zh-cn 값을 그대로 사용할 수 있다.

6. 최종 코드

앞서 만든 모든 처리를 합치면 다음과 같이 정리된다.

import i18n from 'i18next';
import moment from 'moment';
import 'moment/locale/ja';
import 'moment/locale/zh-cn';

// i18n 언어 → moment 로케일 동기화 함수
const updateMomentLocale = (lng: string) => {
  if (lng === 'zh') {
    // 중국어는 디자인 시안에 맞춰 weekday 커스텀
    moment.updateLocale('zh-cn', {
      weekdays: ['星期日', '星期一', '星期二', '星期三', '星期四', '星期五', '星期六'],
    });
  } else {
    moment.locale(lng);
  }
};

// 1) 페이지 진입 시 1회 동기화
updateMomentLocale(i18n.language);

// 2) 이후 언어 변경마다 동기화
i18n.on('languageChanged', updateMomentLocale);

15줄 남짓의 코드지만, 절반만 동작하던 다국어를 완성된 상태로 만들어 준다.

7. 정리

기술적으로 어려운 작업은 아니었다. moment와 i18next의 문서를 차근차근 따라가다 보면 패턴이 어렵지 않게 보이는 수준이었다. 다만 이 과정에서 정리해 둘 만한 두 가지가 있었다.

1) 라이브러리마다 로케일은 별도다

i18n 라이브러리가 번역 텍스트의 로케일을 관리한다고 해서, 날짜·통화·숫자 같은 다른 영역의 로케일까지 함께 챙겨주는 것은 아니다. 라이브러리마다 자체 로케일이 따로 있고, 이를 묶어주는 처리가 없으면 동기화되지 않는다.

다국어 사이트를 만들 때는 지금 이 데이터가 어느 로케일을 보고 있는지 항상 점검할 필요가 있다. moment뿐 아니라 날짜·시간·통화·숫자를 다루는 모든 영역이 잠재적인 동기화 포인트다.

2) 라이브러리 기본값과 디자인 의도는 다를 수 있다

moment의 zh-cn 기본 표기가 틀린 것은 아니었다. 단지 디자인 의도와 달랐을 뿐이다. 코드가 동작하는 것과 의도대로 동작하는 것은 다른 문제다. 그리고 그 의도는 코드만 들여다봐서는 알 수 없는 경우가 많다.

디자이너에게 의도를 확인한 덕분에 서비스 톤의 일관성을 가져갈 수 있었다.

QA에서 마주친 작은 어색함을 지나치지 않은 것, 그리고 라이브러리 기본값을 그대로 받아들이지 않고 한 번 더 확인한 것 — 결국 이 두 가지가 서비스의 디테일을 만들어 준 과정이었다.

Next.js · Vite · Astro로 만들어진 6개 앱과 3개의 공유 패키지(UI 라이브러리, API 서비스, 다국어 리소스)를 하나의 pnpm 워크스페이스로 묶은 작업 기록이다. pnpm-workspace.yaml을 추가하는 수준이 아니라, 다중 프레임워크가 공존할 때 생기는 빌드 / HMR / 배포 / 타입 동기화 이슈를 어떻게 풀었는지에 초점을 맞췄다.

1. 모노레포로 옮긴 이유

원래 구조는 폴리레포였다. 호스트 관리 페이지, 게스트 예약 포털, 디자인 스튜디오, 랜딩 페이지가 각각 다른 저장소에 있었다. 그러다 보니 다음 문제가 누적됐다.

• 코드 중복: 같은 모양의 버튼·인풋·다이얼로그가 4번씩 작성된다.
• 타입 불일치: 백엔드 Swagger에서 자동 생성한 클라이언트가 앱마다 따로 존재해서 DTO가 미묘하게 어긋난다.
• 다국어 동기화 누락: ko·en·ja·fr 4개 언어 키를 저장소마다 따로 추가해야 하고, 빠뜨리면 런타임에 키가 그대로 노출된다.
• PR 검토 비용: 한 기능이 호스트·게스트·스튜디오에 동시에 영향을 줘도 PR이 3개로 쪼개져서 리뷰 흐름이 깨진다.

그래서 pnpm workspaces + Turborepo 조합으로 단일 저장소로 합쳤다. yarn / npm workspaces 대신 pnpm을 고른 이유는 크게 두 가지였다.

1. 하드 링크 기반 설치라 디스크 사용량이 적다. 앱 6개가 각자 무거운 node_modules를 들고 있는 상황을 떠올려 보면, 같은 패키지를 6번 복사하지 않고 store에 한 번만 두는 pnpm 방식이 결정적인 차이를 만든다.
2. workspace:* 프로토콜로 내부 패키지 의존성을 명시적으로 표현할 수 있다. 버전 번호 대신 이 키워드 하나로 워크스페이스 안의 다른 패키지를 가리킬 수 있어서, 내부 패키지 변경이 곧장 모든 앱에 반영된다.

2. 최종 디렉토리 구조

stay-monorepo/
├── packages/
│   ├── stay-front/             # Next.js 15  - 호스트 관리 (port 4100)
│   ├── stay-host/              # Vite + React - 신규 호스트 SPA (port 4100)
│   ├── studio/                  # Next.js 15  - 디자인 스튜디오 (port 4000)
│   ├── stay-guest-portal/      # Astro       - 게스트 예약 포털 (port 4200)
│   ├── stay-landing/           # Astro       - 마케팅 랜딩 (port 4300)
│   ├── stay-planner/           # Astro       - 플래너 툴
│   │
│   ├── stay-ui/                # 공유: 디자인 시스템 (Vite library build)
│   ├── stay-common-services/   # 공유: API 클라이언트 + 타입
│   ├── stay-shared-locales/    # 공유: 4개 언어 i18n 리소스
│   │
│   ├── stay-host-api/          # AWS Lambda API
│   ├── stay-lambda/            # AWS Lambda (온보딩/번역)
│   └── stay-embedding-lambda/  # AWS Lambda (AI 임베딩)
│
├── pnpm-workspace.yaml
├── turbo.json
├── tsconfig.base.json
├── package.json
└── deploy.sh

루트 package.json은 패키지 매니저를 고정하고, 모든 패키지를 워크스페이스로 잡는다.

{
  "name": "stay-monorepo",
  "private": true,
  "packageManager": "pnpm@10.13.1",
  "workspaces": ["packages/**"]
}

# pnpm-workspace.yaml
packages:
  - "packages/**"
  - "!packages/stay-front"

!packages/stay-front처럼 워크스페이스에서 명시적으로 제외할 수 있는 게 중요하다. 마이그레이션 도중 일부 앱은 잠시 외부 의존성으로 두고 점진적으로 끌어올 수 있어서, 한 번에 모든 앱을 옮기지 않아도 된다.

3. 공유 패키지 3종 설계

모노레포의 핵심은 결국 "공유 패키지를 어떻게 쪼개느냐"다. 잘못 자르면 한 패키지를 고칠 때마다 모든 앱이 리빌드된다.

3.1 @stay/ui — 디자인 시스템

가장 무거운 공유 패키지다. SVG 아이콘 150개, GridBuilder(드래그 앤 드롭 페이지 빌더), 어메니티 카탈로그, MUI/Mantine 래퍼 등이 들어 있다.

전체를 단일 번들로 export하면 호스트 앱이 1MB짜리 chunk를 그대로 들고 가게 된다. 그래서 다중 엔트리(multi-entry) 라이브러리 빌드로 설계했다.

// packages/stay-ui/vite.config.ts (요약)
const entries = {
  index: "src/index.ts",
  inputs: "src/components/inputs/index.ts",
  gridBuilder: "src/components/gridBuilder/index.ts",
  layouts: "src/components/layout/index.ts",
  utils: "src/utils/index.ts",
  types: "src/types/index.ts",
  themes: "src/themes/index.ts",
  hooks: "src/hooks/index.ts",
  i18n: "src/i18n/index.ts",
  templateComponents: "src/components/templateComponents/index.tsx",
  // ... 27개+
};

export default defineConfig({
  build: {
    lib: { entry: entries, formats: ["es"], fileName: (_, name) => `${name}.js` },
    rollupOptions: {
      external: [
        "react", "react-dom", "styled-components",
        /^@mui\//, /^@mantine\//, /^@dnd-kit\//, /^@xyflow\//,
        "framer-motion", "zustand", "axios", ...
      ],
    },
  },
});

그리고 package.json의 exports 필드로 각 엔트리에 별도 경로를 부여한다.

{
  "name": "@stay/ui",
  "exports": {
    ".":              { "types": "./dist/index.d.ts",            "import": "./dist/index.js" },
    "./inputs":       { "types": "./dist/components/inputs/index.d.ts",     "import": "./dist/inputs.js" },
    "./gridBuilder":  { "types": "./dist/components/gridBuilder/index.d.ts","import": "./dist/gridBuilder.js" },
    "./hooks":        { "types": "./dist/hooks/index.d.ts",       "import": "./dist/hooks.js" },
    "./themes":       { "types": "./dist/themes/index.d.ts",      "import": "./dist/themes.js" },
    "./styles":       { "import": "./src/styles/index.css" }
  }
}

이렇게 해두면 앱 코드에서 필요한 부분만 import할 수 있고, 트리 셰이킹이 명확하게 동작한다.

import { StayButton } from "@stay/ui/inputs";
import { useGridBuilderStore } from "@stay/ui/gridBuilder";
import { stayTheme } from "@stay/ui/themes";

3.2 @stay/common-services — API 클라이언트 + 공용 비즈니스 로직

이 패키지에는 두 가지가 들어간다.

• 백엔드 Swagger에서 자동 생성된 TypeScript Axios 클라이언트
• DynamoDB 리포지토리, JWT 갱신 로직, Zustand 기반 useAuthStore 등 앱 간 공유 비즈니스 로직

빌드 산출물(dist)을 쓸 수도 있지만, 개발 편의를 위해 exports에서 TS 소스를 그대로 노출하는 방식을 택했다.

{
  "name": "@stay/common-services",
  "exports": {
    ".":                                    "./src/index.ts",
    "./services":                           "./src/services/helpers/index.ts",
    "./dynamodb/repositories":              "./src/dynamodb/repositories/index.ts",
    "./aiDefinitions/pageTypeSectionConfig":"./src/aiDefinitions/pageTypeSectionConfig.ts",
    "./*":                                  "./src/*"
  }
}

장점은 두 가지다.

• 빌드를 거치지 않으니 수정 → 즉시 앱에 반영된다 (HMR이 바로 잡힌다).
• Swagger 클라이언트를 재생성해도 별도 publish 절차 없이 곧장 동기화된다.

대신 각 앱의 번들러가 이 패키지를 트랜스파일 대상에 포함해야 한다. 외부 패키지로 인식하면 TS 소스를 JS로 변환하지 못해 빌드가 깨지기 때문이다. Next.js는 transpilePackages, Vite는 optimizeDeps.include에 명시하는 식으로 처리한다.

3.3 @stay/shared-locales — 4개 언어 다국어 리소스

ko·en·ja·fr 4개 언어 × 13개 namespace(common, error, guestPortal, editor 등)의 JSON 리소스를 단일 객체로 export한다.

// packages/stay-shared-locales/src/locales/index.ts
import koCommon from "./ko/common.json";
import enCommon from "./en/common.json";
// ...

export const sharedLocales = {
  ko: { common: koCommon, error: koError, guestPortal: koGuestPortal, ... },
  en: { common: enCommon, error: enError, guestPortal: enGuestPortal, ... },
  ja: { ... },
  fr: { ... },
} as const;

package.json은 빌드 산출물 없이 TS 소스 자체를 main으로 잡는다.

{
  "name": "@stay/shared-locales",
  "main": "src/index.ts",
  "types": "src/index.ts",
  "exports": {
    ".": {
      "types": "./src/index.ts",
      "import": "./src/index.ts"
    }
  }
}

이 한 줄짜리 설정 덕분에 번역 키 한 개만 추가하면 6개 앱에 동시 반영된다. 폴리레포 구조에서는 같은 키를 4개 저장소에 따로 추가해야 했는데, 그 작업이 통째로 사라졌다.

각 앱은 이 객체를 i18next의 resources로 넘겨 쓴다.

import { sharedLocales } from "@stay/shared-locales";

i18n.use(initReactI18next).init({
  resources: sharedLocales,
  lng: "ko",
  fallbackLng: "ko",
  defaultNS: "common",
});

4. 워크스페이스 의존성 — workspace:*

내부 패키지를 참조할 때는 버전 대신 workspace:*를 적는다. 그러면 pnpm이 워크스페이스 안에서 심볼릭 링크로 연결한다.

// packages/stay-host/package.json
{
  "dependencies": {
    "@stay/ui":              "workspace:*",
    "@stay/common-services": "workspace:*",
    "@stay/shared-locales":  "workspace:*"
  }
}

workspace:*의 효과는 다음과 같다.

• pnpm publish 시 자동으로 실제 버전으로 치환된다 (배포 호환).
• 외부 패키지에 같은 이름이 있어도 항상 로컬 워크스페이스가 우선이다.
• pnpm install 후 node_modules/@stay/ui는 ../packages/stay-ui 심볼릭 링크가 된다 → IDE의 "Go to Definition"이 곧장 소스로 점프한다.

pnpm.overrides — 의존성 충돌 강제 해결

여러 앱이 서로 다른 minor 버전의 라이브러리를 의존하면 React/Emotion이 두 번 로드되는 사고가 난다. 루트 package.json의 overrides로 단일 버전을 강제했다.

{
  "pnpm": {
    "overrides": {
      "framer-motion":            "^12.23.12",
      "motion-dom":               "^12.23.12",
      "@aws-sdk/client-dynamodb": "3.948.0",
      "@aws-sdk/lib-dynamodb":    "3.948.0",
      "entities":                 "4.5.0",
      "parse5>entities":          "^6.0.1"
    }
  }
}

여기서 parse5>entities 같은 표기는 "parse5 패키지가 안쪽에서 의존하는 entities만 따로 버전을 박는다"는 의미다. 이렇게 특정 패키지의 transitive dependency(간접 의존성)만 골라서 override할 수 있는 점이 유용했다. 라이브러리 전체 버전을 건드리지 않고도 충돌만 정확히 짚어 해결할 수 있다.

.npmrc — AWS SDK / Smithy 호이스팅

pnpm은 기본적으로 strict한 node_modules 구조를 만든다. 즉 package.json에 직접 적은 의존성만 import할 수 있고, transitive dependency를 우연히 import하는 사고(이른바 phantom dependency)를 차단해 준다. 그런데 AWS SDK는 내부 모듈을 동적으로 require하는 케이스가 있어서, 이 strict 구조에서는 모듈을 못 찾고 런타임 에러가 난다. 그래서 호이스팅(평탄화)을 따로 켜줘야 한다.

# .npmrc
shamefully-hoist=true
public-hoist-pattern[]=@smithy/*
public-hoist-pattern[]=@aws-sdk/*

shamefully-hoist=true는 가능하면 안 켜는 게 좋다. 다만 AWS SDK + Smithy 조합처럼 호이스팅을 가정하고 작성된 라이브러리를 쓸 때는 어쩔 수 없다.

5. 동시 실행 패턴

모노레포의 가장 큰 함정은 공유 패키지를 수정해도 앱에서 반영이 안 되는 상황이다. @stay/ui 컴포넌트를 고쳤는데 호스트 앱은 옛 코드를 쓰고 있다면 보통 둘 중 하나다.

1. UI 패키지가 빌드되지 않아 dist/가 갱신되지 않은 경우다. 앱은 빌드된 결과물을 보고 있는데 그 결과물 자체가 옛것이니 변화가 보일 리 없다.
2. 앱의 번들러가 dist/ 변화를 감지하지 못한 경우다. UI는 새로 빌드됐지만 번들러가 그걸 모르고 옛 버전을 캐싱하고 있다.

해결책은 concurrently로 UI watch 빌드와 앱 dev 서버를 동시에 실행하는 것이다.

// 루트 package.json (요약)
{
  "scripts": {
    "front":  "rimraf packages/stay-front/.next && concurrently -n ui,front -c blue,green   \"pnpm --filter @stay/ui dev:watch\" \"pnpm --filter stay-front dev\"",
    "studio": "rimraf packages/studio/.next        && concurrently -n ui,studio -c blue,yellow \"pnpm --filter @stay/ui dev:watch\" \"pnpm --filter @stay/studio dev\"",
    "host":   "node scripts/kill-ports.mjs && pnpm build:ui && concurrently --kill-others -n ui,api,host -c blue,yellow,magenta \"pnpm --filter @stay/ui dev:watch\" \"pnpm --filter stay-host-api dev\" \"pnpm --filter stay-host dev\""
  }
}

이 스크립트에서 눈여겨볼 만한 디테일이 세 가지 있다.

• rimraf packages/stay-front/.next — Next.js의 stale 캐시가 워크스페이스 패키지 변경을 못 잡는 경우가 있어서, 시작 시 .next를 비우고 출발한다.
• kill-ports.mjs — lsof -ti:4100 또는 netstat으로 좀비 프로세스를 미리 정리해 둔다. 이전 dev 서버가 깔끔하게 죽지 않았을 때 발생하는 포트 충돌을 막기 위해서다.
• --kill-others — 한 프로세스가 죽으면 나머지도 같이 종료시킨다. UI watch가 죽었는데 앱이 살아 있으면 stale 빌드를 보게 되는 사고를 막을 수 있다.

Vite watch → Next.js 리빌드 트리거

@stay/ui는 Vite library mode로 빌드되고 결과물이 dist/에 떨어진다. 그런데 Next.js의 Webpack은 성능상의 이유로 node_modules 안의 변화를 기본적으로 watch하지 않는다. 즉 UI 라이브러리를 새로 빌드해도 Next.js dev 서버는 그 사실을 알아채지 못하고 옛 코드를 계속 쓴다. 그래서 dev:watch 전용 Vite 설정에 다음 플러그인을 끼웠다.

// packages/stay-ui/vite.config.watch.ts
const triggerNextRebuild = () => ({
  name: "trigger-next-rebuild",
  closeBundle() {
    // 빌드가 끝날 때마다 dummy 파일 timestamp를 갱신
    const triggerFile = path.resolve(__dirname, "dist/.rebuild-trigger");
    fs.writeFileSync(triggerFile, Date.now().toString());
    console.log("[vite] Build complete, triggering Next.js rebuild...");
  },
});

원리는 단순하다. Vite 빌드가 끝날 때마다 의미 없는 dummy 파일의 timestamp를 갱신한다. 그리고 Next.js 앱 코드 어딘가에서 이 dummy 파일을 import해두면, 파일 수정 시각이 바뀐 걸 Next.js가 감지하고 페이지를 재컴파일한다. 별것 아닌 트릭이지만 공유 UI 수정 → Next.js HMR까지의 체인이 자동화된다.

// 앱 어딘가 (보통 i18n init 옆)
import "@stay/ui/dist/.rebuild-trigger?raw";

watch 모드에서는 vite-plugin-dts(타입 생성)와 vite-plugin-checker(TS 체크)를 꺼뒀다. 메모리 사용량이 두 배 가까이 줄어 dev 환경 안정성이 좋아진다.

// vite.config.watch.ts — dts/checker 제외
build: {
  sourcemap: false,
  reportCompressedSize: false,
  emptyOutDir: false, // build:ui 결과물 보존
},

6. Turborepo — 빌드 그래프와 캐싱

pnpm -r run build만으로도 모든 패키지를 빌드할 수 있다. 다만 패키지 간 의존 순서(@stay/ui가 먼저 빌드돼야 stay-host가 빌드 가능)와 캐싱을 위해 Turborepo를 얹었다.

// turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "ui": "tui",
  "globalDependencies": [".env*"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"],
      "cache": true
    },
    "build:ui": {
      "dependsOn": [],
      "outputs": ["dist/**"],
      "cache": true
    },
    "dev": {
      "dependsOn": ["^build:ui"],   // 앱 dev 시작 전에 UI lib 1회 빌드
      "persistent": true,
      "cache": false
    },
    "type-check": {
      "dependsOn": ["^build"],
      "cache": true
    }
  }
}

• ^build — 캐럿 기호는 Turborepo 표기법으로 "이 패키지가 의존하는 다른 패키지의 build를 먼저 실행하라"는 뜻이다. 예를 들어 stay-host의 build를 돌리면 @stay/ui의 build가 먼저 자동 실행된다.
• outputs — 캐시 대상 디렉토리를 지정한다. .next/cache/**는 일부러 제외해서 캐시가 끝없이 부풀지 않도록 했다.
• globalDependencies: [".env*"] — .env 파일이 바뀌면 모든 캐시를 무효화한다. 환경 변수에 따라 빌드 결과가 달라질 수 있기 때문이다.
• dev의 cache: false — dev 모드는 항상 새로 띄워야 하므로 캐싱하지 않는다.

pnpm front:turbo처럼 turbo를 통한 빠른 dev 모드도 별도로 노출했다. 캐시가 적중하면 @stay/ui를 다시 빌드하지 않아 콜드 스타트가 수십 초 단축된다.

7. TypeScript 설정 — tsconfig.base.json 상속

모든 앱이 동일한 strict 옵션을 쓰도록 루트에 tsconfig.base.json을 두고, 각 앱·패키지의 tsconfig.json이 상속한다.

// tsconfig.base.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "lib": ["dom", "dom.iterable", "esnext"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "allowSyntheticDefaultImports": true,
    "incremental": true,
    "jsx": "preserve",
    "noEmit": true
  },
  "exclude": ["node_modules", ".next", "dist", "out", "build", ".turbo", "coverage"]
}

// packages/stay-host/tsconfig.json
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "baseUrl": "./src",
    "paths": { "@/*": ["./*"] }
  },
  "include": ["src", "vite.config.ts"]
}

moduleResolution: "bundler"가 핵심이다. TypeScript의 모듈 해석 모드 중 Node16은 package.json의 exports 필드를 표준 그대로 까다롭게 검증해서, @stay/ui/inputs 같은 subpath import에 자주 빨간 줄을 띄운다.

반면 bundler 모드는 Vite / Next.js 같은 번들러의 실제 동작과 일치하도록 설계돼 있어서, IDE 에러 없이 subpath import가 그대로 통한다. 모노레포에서 IDE 빨간 줄을 없애려면 이 설정이 사실상 필수다.

8. 배포 — deploy.sh 단일 진입점

Vercel에 4개 프로젝트(front / landing / guest-portal / studio)가 등록돼 있다. vercel --prod를 직접 실행하면 의도와 다른 프로젝트로 배포될 수 있어, 모든 배포를 단일 스크립트로 묶어 처리하도록 했다.

# deploy.sh (요약)
deploy_project() {
  local project=$1
  local prod_flag=$2
  local project_id=$(get_project_id "$project")  # case문으로 ID 매핑

  # .vercel/project.json 을 매번 덮어써서 프로젝트 컨텍스트 확정
  echo "{\"projectId\":\"$project_id\",\"orgId\":\"$ORG_ID\"}" > .vercel/project.json

  # 로컬 빌드 → prebuilt 업로드
  vercel build ${prod_flag} --yes
  vercel deploy --prebuilt ${prod_flag} --yes

  # guest-portal은 와일드카드 alias 자동 설정
  if [ "$project" = "guest-portal" ] && [ "$prod_flag" = "--prod" ]; then
    vercel alias "$deployment_url" '*.stay.site'
    vercel alias "$deployment_url" 'www.example.com'
  fi
}

이 스크립트의 핵심 디자인 포인트는 세 가지다.

• vercel build → vercel deploy --prebuilt 분리: 로컬에서 빌드하고 결과물만 업로드하는 방식이다. Vercel의 원격 빌드 환경이 매번 새로 셋업되는 부담을 줄일 수 있다.
• .vercel/project.json 동적 생성: 프로젝트마다 ID가 다르므로 매 배포마다 덮어쓴다. 이게 없으면 마지막에 배포한 프로젝트로 잘못 푸시된다.
• alias 자동 설정: 게스트 포털은 *.stay.site 와일드카드 도메인을 받아야 하는데, prebuilt 배포는 alias가 자동 적용되지 않으므로 스크립트가 직접 호출한다.

pnpm deploy:front           # production
pnpm deploy:guest-portal    # production
pnpm deploy:all             # 한 번에 4개 모두
pnpm deploy:front:preview   # preview

9. 회고

좋았던 점

1. 공유 패키지의 export 경로를 잘게 쪼갠 것 — 처음엔 단일 entry였는데 트리 셰이킹이 전혀 안 돼서 호스트 앱 번들에 GridBuilder 전체가 들어왔다. 27개로 쪼개고 나서야 chunk 크기가 안정됐다.
2. workspace:* 강제 — 내부 패키지를 npm 버전으로 참조하면 pnpm publish까지 가야 변경이 반영된다. 무조건 workspace:*로 통일하니 개발 흐름이 끊기지 않았다.
3. shared-locales의 TS-source export — JSON을 import한 객체를 그대로 노출했더니 번역 키 검색이 IDE에서 곧장 점프된다. 별도 빌드 단계가 없어 라이브러리 수준의 중복 문제도 사라졌다.

주의할 점

1. Next.js는 node_modules 안 패키지의 변경을 watch하지 않는다 — triggerNextRebuild 플러그인을 만들기 전엔 매번 dev 서버를 종료하고 다시 띄워야 했다.
2. shamefully-hoist는 좋은 수단이 아니다 — AWS SDK 호이스팅이 필요해서 켰는데, 그 결과 앱이 의도치 않은 transitive 패키지에 의존하는 일이 생겼다. CI에서는 --frozen-lockfile로 잡고 있다.
3. pnpm.overrides는 silent하게 동작한다 — 버전을 강제로 박았다는 사실을 모르면 디버깅이 미궁에 빠진다. CHANGELOG로 따로 문서화해 두는 편이 좋다.
4. Turbo dev의 dependsOn: ["^build:ui"] — 처음엔 ^build였는데 dev 시작 시 모든 패키지가 풀 빌드되면서 30초씩 걸렸다. UI lib만 의존하도록 좁히는 게 정답이었다.

10. 마치며

폴리레포에서 모노레포로 옮기면서 가장 크게 달라진 부분은 두 가지였다.

1. 공유 패키지를 수정하면 모든 앱에 즉시 반영된다.
2. 하나의 의존성 그래프 안에서 일관된 버전이 유지된다.

처음엔 '한 PR로 여러 앱을 한꺼번에 바꿀 수 있다'는 게 가장 큰 이점이라고 생각했는데, 실제로 일하면서 체감한 차이는 이 두 가지가 더 컸다.

Next.js · Vite · Astro가 한 저장소에 공존하는 게 처음엔 부담스러웠지만, 각 프레임워크의 책임 영역이 명확해지자 오히려 자연스러운 선택지가 됐다 (Next.js는 인증/관리, Vite는 SPA, Astro는 SSG/마케팅). pnpm workspaces는 이 구성을 가장 가볍게 떠받쳐 주는 도구였다.

이번 작업을 돌아보면, 처음부터 모든 도구를 한꺼번에 도입하지 말고 pnpm workspace로 최소 구성을 만든 뒤 필요할 때 Turborepo를 얹어가는 순서로 진행했다면 시행착오가 더 적었을 것 같다.

Reference

• pnpm workspaces — https://pnpm.io/workspaces
• pnpm workspace: protocol — https://pnpm.io/workspaces#workspace-protocol-workspace
• Turborepo tasks 설정 — https://turbo.build/repo/docs/reference/configuration
• Vite Library Mode — https://vitejs.dev/guide/build.html#library-mode
• Node.js package.json#exports — https://nodejs.org/api/packages.html#subpath-exports

그 사이에 진행 상황도 안 보이니 "되고 있는 건가?" 싶어서 버튼을 여러 번 더 누르기도 했다. 어차피 만들어야 하는 기능이라면 처음부터 제대로 구조를 잡자는 생각으로 압축 → AI 분류 → 병렬 업로드 파이프라인을 설계했다.

문제 인식

기존 방식은 단순했다.

파일 선택 → FormData → POST /api/upload → 완료

세 가지가 문제였다.

• 원본 파일 그대로 전송: DSLR로 찍은 숙소 사진은 한 장에 5~15MB에 달한다. 이걸 압축 없이 그대로 올리면 업로드 시간이 길어지는 건 물론이고, 서버 스토리지와 네트워크 비용도 낭비다.
• 진행 상황 없음: 업로드 중에 아무 피드백이 없으면 잘 되고 있는 건지 알 수가 없다. 기다리다 못해 버튼을 한 번 더 누르면 같은 파일이 중복으로 올라가고, 그걸 나중에 수동으로 정리해야 하는 상황이 생긴다.
• 순차 처리: 파일을 하나씩 순서대로 처리하면 장수가 늘수록 대기 시간이 그대로 늘어난다. 10장이면 10배, 15장이면 15배다. 숙소 등록 시 사진을 한꺼번에 올리는 경우가 많은데, 매번 30초 넘게 기다리는 건 현실적으로 쓸 수 없는 흐름이었다.

파이프라인 구조

파일 선택 → 유효성 검사 → 청크 분할 (3개씩)
    ↓ Promise.all (청크 내 병렬)
  [Canvas 압축 (업로드용 1600px / Vision용 1200px) → Vision API → SEO 파일명]
    ↓
  S3 Presigned URL 발급 → XHR PUT (progress 추적)
    ↓
  메인 지정 → 순서 저장 → 삭제 처리

1. Canvas 기반 다단계 이미지 압축

서버 정책(2MB 이하, JPEG/PNG/WebP)을 맞추기 위해 Canvas로 직접 구현했다. 단순히 1600px 고정으로 리사이즈하면 고해상도 원본은 여전히 2MB를 넘는다. 목표 용량을 달성할 때까지 단계적으로 압축 강도를 올리는 방식을 썼다.

const passes = [
  { size: 1600, quality: 0.85 },
  { size: 1280, quality: 0.78 },
  { size: 1024, quality: 0.70 },
  { size: 800,  quality: 0.60 }, // 최후 수단
];

for (const { size, quality } of passes) {
  const compressed = await compressImage(file, size, quality);
  if (compressed.size <= TARGET_MAX_BYTES) return compressed;
}

같은 파일을 업로드용(1600px)과 Vision 분석용(1200px base64)으로 각각 압축해야 하는데, 두 작업을 Promise.all로 병렬 실행해 대기 시간을 줄였다.

const [uploadFile, visionBase64] = await Promise.all([
  compressImageForUpload(file),
  compressImageForVision(file),
]);

2. Vision API로 이미지 자동 분류 + SEO 파일명 생성

숙소 사진은 공간별로 분류되어야 하는데(침실, 욕실, 주방 등), 호스트가 일일이 지정하기엔 번거롭다. Vision API에 압축된 이미지를 넘기면 공간 카테고리를 자동으로 반환한다.

const visionResult = await callVisionApi(visionBase64, visionTimeout);
// { category: 'BEDROOM', confidence: 0.92 }

Vision API가 실패하거나 타임아웃(기본 10초)이 나도 업로드는 계속 진행된다. 실패는 warnings 배열에 누적하고 fallback으로 UNCERTAIN을 사용한다.

Vision 결과는 SEO 파일명 생성에도 활용한다. IMG_2048.JPG 같은 파일명은 검색엔진에 기여하지 못한다.

// gyedong-hanok-bedroom-03.jpg
generateSeoFilename({
  accommodationSlug: 'gyedong-hanok',
  category: visionResult.category,
  sequence: 3,
  extension: 'jpg',
});

Vision이 실패하면 gyedong-hanok-photo-03.jpg로 fallback한다.

3. S3 Presigned URL + XHR 진행률 추적

파일을 서버를 거쳐 올리면 서버 메모리와 대역폭을 소모한다. Presigned URL을 쓰면 클라이언트가 S3에 직접 PUT한다.

클라이언트 → POST /api/s3-upload (파일명, 크기, 타입)
서버        → Presigned URL 생성 후 반환
클라이언트 → PUT presignedUrl (직접 전송)

fetch()는 업로드 진행률을 추적할 수 없어 XMLHttpRequest를 사용했다.

xhr.upload.addEventListener('progress', (event) => {
  if (event.lengthComputable) {
    const progress = Math.round((event.loaded / event.total) * 100);
    onProgress?.(progress);
  }
});

4. 청크 병렬 처리

파일 1장에 약 2초, 10장 순차 처리면 20초다. 파일 배열을 concurrency=3 단위로 쪼개고 청크 내부에서 Promise.all로 병렬 실행한다.

const chunks: File[][] = [];
for (let i = 0; i < files.length; i += concurrency) {
  chunks.push(files.slice(i, i + concurrency));
}

for (const chunk of chunks) {
  const results = await Promise.all(chunk.map(processFile));
}

concurrency를 3으로 설정한 이유는 Vision API 동시 요청 한도와 브라우저 메모리(파일당 35MB × 3 ≈ 1015MB) 사이의 균형점이기 때문이다.

5. 업로드 오케스트레이션 (imageChangeSync)

업로드 이후에도 메인 이미지 지정, 순서 저장, 삭제 처리가 남아있다. 이 흐름을 processImages가 담당한다.

// 1) 신규 파일 업로드
for (const item of newItems) {
  const imageType = await api.analyze?.(item.file);
  const uploaded = await api.upload(item.file, imageType);
}

// 2) 메인 이미지 지정
await api.setMain(mainId);

// 3) 순서 저장 (변경 없으면 스킵)
if (!isSameOrder(currentOrderIds, finalOrderIds)) {
  await api.reorder(finalOrderIds);
}

// 4) 삭제 처리
await api.deleteOne(id); // 또는 api.deleteAll()

return { warnings }; // 부분 실패는 throw 대신 누적

두 가지 원칙을 지켰다. 부분 실패 허용 — 이미지는 숙소 저장의 필수값이 아니라서, 업로드 실패가 전체 저장 실패로 전파되면 안 된다. 의존성 주입 — ImageApi 인터페이스를 주입받는 구조라 룸, 조직 등 다른 엔터티에도 동일한 유틸을 재사용할 수 있다.

성능 추정

파일 1장 처리 시간을 분해하면, 전체 약 2,240ms 중 86%가 네트워크 I/O다(Vision 1,200ms + S3 600ms + Presigned URL 140ms). Promise.all로 병렬화가 가장 효과적인 구간이다.

위 수치는 각 단계별 평균 소요 시간을 기반으로 한 이론적 추정치다. 실제 수치는 Vision API 응답 속도와 네트워크 환경에 따라 달라진다.

단축률이 파일 수와 무관하게 일정한 이유는, ceil(n / 3) 청크 수에 비례해 시간이 줄어들기 때문이다.

마치며

지금 구조에서 아직 해결 못 한 게 있다면, 업로드 실패 시 재시도 로직이다. 현재는 실패를 warnings에 누적하고 끝이라서, 네트워크가 불안정한 환경에서는 일부 파일이 조용히 빠질 수 있다.

이 부분을 어떻게 개선할지 찾아보다가 지수 백오프(exponential backoff) 라는 패턴을 알게 됐다. 실패했을 때 즉시 재시도하면 서버가 과부하 상태일 경우 오히려 503이 반복되는데, 재시도 간격을 1초 → 2초 → 4초처럼 점점 늘려가면 서버가 회복할 시간을 줄 수 있다는 개념이다. 아직 적용하지는 못했지만, 다음 개선 포인트로 정해뒀다.

Vision API 타임아웃도 마찬가지다. 현재 10초로 설정했는데, 이 값은 실측 없이 일단 넉넉하게 잡은 숫자다. 타임아웃을 어떻게 정해야 하는지 찾아보니, 실제 응답 시간 분포를 측정해서 대부분의 요청이 완료되는 시점을 기준으로 잡는 게 맞다고 한다. 운영 데이터가 쌓이면 그때 다시 조정해볼 생각이다.

개인 포트폴리오 사이트(Next.js 15 / App Router)를 만들고 Lighthouse를 돌려보니 첫 페인트 시점, 메인 스레드 점유 시간, 폰트 로딩 시 레이아웃 시프트 등에서 개선할 만한 지점들이 보였다.

이번 글에서는 LCP / TBT / CLS 세 가지 지표를 중심으로, 지표별 원인과 해결 과정을 코드와 함께 남겨둔다.

적용 스택: Next.js 15, React 18, App Router, Tailwind CSS, Framer Motion

1. 이미지 최적화 — PNG → WebP/AVIF 전환

이번 최적화 과정에서 가장 효과가 컸던 부분이다. 프로젝트 썸네일 이미지를 모두 PNG로 관리하고 있었는데, 용량이 큰 데다, 호버 시 두 번째 이미지까지 함께 로드되면서 네트워크 비용이 커지는 문제가 있었다.

1-1. 원본 이미지를 WebP로 일괄 전환

- defaultImage: "/images/projects/panzy-main.png",
- hoverImage: "/images/projects/panzy-hover.png",
+ defaultImage: "/images/projects/panzy-main.webp",
+ hoverImage: "/images/projects/panzy-hover.webp",

PNG 대비 평균 60~70% 정도 용량이 감소했다. 화질 손실은 육안으로 거의 차이가 없는 수준이다.

1-2. next.config.ts로 이미지 파이프라인 튜닝

// next.config.ts
const nextConfig: NextConfig = {
    images: {
        // 브라우저가 지원하는 최적 포맷 자동 선택 (AVIF 우선)
        formats: ["image/avif", "image/webp"],
        // 이미지 CDN 캐시 1년
        minimumCacheTTL: 31536000,
        // 뷰포트별 최적 크기
        deviceSizes: [640, 750, 828, 1080, 1200, 1920],
        // 176 포함: 프로필 이미지(176×176) 정확히 매칭 → 리사이즈 비용 절감
        imageSizes: [16, 32, 48, 64, 96, 128, 176, 256, 384],
    },
};

포인트는 imageSizes 배열에 실제 사용하는 사이즈를 추가한 것. 프로필 이미지가 176×176인데 기본 imageSizes에는 176이 없어서 가장 가까운 256으로 리사이즈된 후 표시되고 있었다. 실제 사용하는 크기를 명시하면 Next.js의 이미지 최적화 단계에서 불필요한 리사이즈 과정을 줄일 수 있다.

1-3. next/image에 quality, sizes 명시

<Image
    src={project.defaultImage}
    alt={`${project.name} 프로젝트 메인 이미지`}
    fill
    sizes="(max-width: 768px) 100vw, 50vw"
    loading="lazy"
    quality={85}        // 기본 75 → 85, 화질과 용량 사이 절충
    className="object-cover transition-all duration-500"
/>

• sizes를 정확히 지정해야 Next.js가 viewport에 맞는 이미지만 다운로드한다.
• 기본 quality는 75인데, 프로젝트 썸네일은 화질이 중요해 85로 약간 올렸다. 대신 메인 LCP 요소인 프로필 이미지는 90으로 유지했다.

2. 폰트 최적화 — 다운로드 크기 줄이고 CLS 막기

next/font/google를 쓰면 self-host로 자동 처리되긴 하지만, 굵기(weight)를 명시하지 않으면 사용하지도 않는 굵기까지 다 받아온다.

2-1. 실제 사용하는 weight만 로드

// src/app/layout.tsx
const inter = Inter({
    subsets: ["latin"],
    variable: "--font-inter",
    display: "swap",
    adjustFontFallback: true,
    preload: true,
    // 실제 사용하는 굵기만 로드 → 폰트 다운로드 크기 절감
    weight: ["400", "500", "600", "700"],
});

weight를 명시하지 않으면 200~900 범위의 variable font 전체가 함께 로드된다. 실제로 쓰는 4개 굵기만 지정하면 폰트 페이로드가 크게 줄어든다.

2-2. 보조 폰트는 display: "optional"로 CLS 방지

Fira Code는 Nav 로고 한 곳에만 쓰는 보조 폰트라 굳이 swap으로 시스템 폰트에서 웹폰트로 전환되는 과정을 사용자에게 보여줄 필요가 없었다.

const firaCode = Fira_Code({
    subsets: ["latin"],
    weight: ["600"],
    variable: "--font-fira-code",
    display: "optional",  // swap → optional
});

핵심 본문 폰트(Inter)는 시각적 일관성이 중요해서 swap을 유지하고, 사이드 폰트만 optional로 바꿨다.

2-3. adjustFontFallback: true

adjustFontFallback 옵션을 사용해 폴백 폰트의 메트릭(글자 크기와 행간)을 웹폰트와 유사하게 자동 보정했다. 이로 인해 폰트 교체 과정에서 발생하는 미세한 레이아웃 시프트를 줄이고, Inter 적용 시에도 보다 안정적인 렌더링을 유지할 수 있었다.

3. LCP 개선 — 히어로 영역 프로필 이미지

LCP 요소는 첫 화면의 프로필 이미지(176×176). 원래 Framer Motion의 scaleIn 변형을 그대로 사용하고 있었는데, 이로 인해 LCP 측정 시점이 불필요하게 지연되고 있었다.

3-1. LCP 요소에 opacity: 0이 들어가면 안 된다

// 기존: scaleIn — opacity 0 → 1 트랜지션 포함
// 문제: Lighthouse는 opacity:0인 동안 LCP가 "보이지 않는다"고 판단해
//       transition이 끝날 때까지 LCP 측정을 미룬다.

scaleIn 안에 opacity: 0 → 1이 포함되어 있어 이미지 자체는 빨리 다운로드되었지만 LCP 시간이 트랜지션 종료 시점까지 늦춰지는 현상이 발생했다.

3-2. opacity 없이 scale만 사용하는 변형 추가

// LCP 요소(프로필 이미지)는 opacity:0 으로 시작하면 LCP가 늦게 측정됨
// → opacity 없이 scale만 사용해 즉시 visible 상태 유지
const profileImageVariant: Variants = {
    hidden: { scale: 0.9 },
    visible: {
        scale: 1,
        transition: { duration: 0.5, ease: [0.22, 1, 0.36, 1] },
    },
};

이미지는 처음부터 화면에 보이는 상태로 렌더링되고, 단지 scale만 변경되며 애니메이션이 적용된다. 이 경우 요소가 opacity: 0 상태를 거치지 않기 때문에, 브라우저는 해당 이미지를 DOM에 페인트하는 시점에 바로 LCP를 측정한다.

3-3. priority + 정확한 sizes + 적절한 quality

<Image
    src={PROFILE_IMAGE_PATH}
    alt={`${personalInfo.name} 프로필 사진`}
    width={176}
    height={176}
    sizes="176px"   // 고정 크기라 정확히 명시
    priority         // <head>에 preload 자동 삽입
    quality={90}     // 얼굴 사진이라 약간 높게
    className="..."
/>

priority를 주면 Next.js가 <link rel="preload">를 자동으로 넣어줘서 HTML 파싱 직후 이미지 다운로드가 시작된다.

4. TBT 개선 — scroll 이벤트를 IntersectionObserver로

상단 Nav가 현재 활성 섹션을 하이라이트하기 위해 window.scroll 이벤트로 위치를 계산하고 있었다.

4-1. 기존 코드의 문제

// Before: scroll 이벤트 + rAF 쓰로틀링
useEffect(() => {
    const sections = Array.from(document.querySelectorAll("section[id]"));
    let ticking = false;

    const handleScroll = () => {
        if (ticking) return;
        ticking = true;
        requestAnimationFrame(() => {
            let current = "";
            sections.forEach((el) => {
                if (window.scrollY >= el.offsetTop - 100) {
                    current = el.getAttribute("id") ?? "";
                }
            });
            setActiveSection(current);
            ticking = false;
        });
    };
    window.addEventListener("scroll", handleScroll);
    return () => window.removeEventListener("scroll", handleScroll);
}, []);

requestAnimationFrame으로 실행 횟수를 60fps로 제한했지만, 근본적인 문제는 그대로다. 스크롤하는 내내 매 프레임 메인 스레드에서 JS가 실행되고, el.offsetTop 접근이 강제 레이아웃(forced layout)을 유발해 추가 비용까지 생긴다. TBT(Total Blocking Time)는 메인 스레드가 50ms 이상 점유되는 구간을 집계하는 지표라, 스크롤 중 누적되는 JS 실행 시간이 점수에 직접적인 영향을 준다.

4-2. IntersectionObserver로 교체

useEffect(() => {
    /**
     * IntersectionObserver 기반 활성 섹션 감지
     *
     * - 스크롤마다 실행 ❌, 섹션이 진입/이탈할 때만 실행 ✅
     * - 브라우저 내부에서 처리 → 메인 스레드 부담 없음 → TBT 개선
     *
     * rootMargin: "-40% 0px -55% 0px"
     *  → 뷰포트 상단 40%, 하단 55% 제외한 중간 5% 영역에서만 감지
     *  → 스크롤 중간쯤 왔을 때 활성화돼 자연스러운 하이라이트
     */
    const observer = new IntersectionObserver(
        (entries) => {
            entries.forEach((entry) => {
                if (entry.isIntersecting) {
                    setActiveSection(entry.target.getAttribute("id") ?? "");
                }
            });
        },
        { rootMargin: "-40% 0px -55% 0px" },
    );

    document.querySelectorAll("section[id]").forEach((s) => observer.observe(s));
    return () => observer.disconnect();
}, []);

rootMargin을 -40% 0px -55% 0px로 줘서 뷰포트의 정중앙(약 5% 영역)을 지날 때만 활성화되도록 했다. 섹션이 스크롤 중간쯤 왔을 때 부드럽게 바뀐다.

4-3. 불필요한 whileInView 제거

Skills 섹션에서 그룹마다 stagger 애니메이션을 돌리고 있었는데, 그룹 안 뱃지마다 또다시 whileInView를 거는 불필요하게 중복된 구조였다.

// Before: 그룹과 뱃지 양쪽에서 IntersectionObserver 등록
<m.div variants={staggerContainer(0.05)} initial="hidden" whileInView="visible">
    {group.skills.map((skill) => (
        <m.span key={skill.id} variants={badgeVariant} ... />
    ))}
</m.div>

// After: 부모 stagger를 자식이 상속받게 단순화
<div className="flex flex-wrap gap-2">
    {group.skills.map((skill) => (
        <m.span key={skill.id} variants={badgeVariant} ... />
    ))}
</div>

Framer Motion은 부모의 variants를 자식이 자동으로 상속받는다. 따라서 중간 wrapper에 whileInView를 따로 걸 필요가 없다. 이를 제거하자 스크롤마다 동작하던 IntersectionObserver 인스턴스 수가 줄었고, 그만큼 TBT도 개선됐다.

5. CSS·번들 최적화

5-1. Critical CSS 자동 인라인 (optimizeCss)

// next.config.ts
const nextConfig: NextConfig = {
    experimental: {
        // 첫 화면에 필요한 CSS만 추출해 <head>에 인라인
        optimizeCss: true,
    },
};

critters 의존성을 함께 추가하면 Next.js가 빌드 단계에서 첫 화면 렌더링에 필요한 CSS만 골라 <head>에 인라인해준다. 나머지는 비동기로 로드되므로 FCP가 빨라진다.

5-2. Tailwind safelist로 동적 클래스 누락 방지

// tailwind.config.ts
safelist: [
    "object-contain",
    "object-cover",
],

JIT 모드는 사용하지 않는 클래스를 제거하는데, 데이터 파일에서 문자열로 조립되는 클래스는 빌드 시 감지되지 않아 누락될 수 있다. 런타임에서 동적으로 쓰는 클래스는 safelist에 명시해 둔다.

5-3. 모던 브라우저 타깃으로 polyfill 축소

// package.json
"browserslist": {
    "production": [
        "chrome >= 90",
        "firefox >= 90",
        "safari >= 14",
        "edge >= 90"
    ]
}

포트폴리오 사이트는 채용 담당자가 주로 보는 용도라, 방문자층이 좁고 구형 브라우저 지원이 불필요한 만큼, 모던 브라우저로 타깃을 좁히면 transpile 결과물이 가벼워지고 불필요한 polyfill도 줄어든다.

6. 작은 디테일 — willChange와 metadataBase

6-1. 무한 애니메이션 요소에 willChange

<m.div
    animate={{ y: [0, -18, 0] }}
    transition={{ duration: 7, repeat: Infinity, ease: "easeInOut" }}
    style={{ willChange: "transform" }}  // GPU 레이어 분리
/>

Hero 배경의 둥둥 떠다니는 그라디언트 원에 will-change: transform을 적용했다. 브라우저가 미리 GPU 레이어로 합성해서 애니메이션 중 리페인트가 발생하지 않는다.

단, 모든 요소에 남발하면 메모리 사용량이 늘어나니 무한 반복되는 transform 애니메이션에만 선별 적용했다.

6-2. metadataBase로 OG 이미지 절대 경로 자동 처리

metadataBase: new URL(process.env.NEXT_PUBLIC_SITE_URL ?? "https://..."),

OG 이미지 경로를 상대 경로로 적어도 자동으로 절대 URL로 변환된다. 환경별 URL을 환경변수로 분기할 수 있어 Vercel preview/production 모두 대응할 수 있다.

마치며

이번 작업을 돌아보면, 성능 문제의 대부분은 브라우저가 이미 잘 처리하는 일을 JS로 다시 구현하면서 생겼다.

"브라우저가 이미 잘하는 일은 브라우저에게 맡기고, JS는 꼭 필요한 곳에만 쓴다."

이미지 포맷 변환은 Next.js가, 스크롤 위치 감지는 IntersectionObserver가, 폰트 폴백 보정은 adjustFontFallback이 처리하도록 역할을 넘겼다. 각자가 맡은 일을 하도록 두었더니 지표도 함께 개선됐다.

그 중 LCP 요소에 opacity: 0을 넣었던 실수가 특히 기억에 남았다. 애니메이션을 넣고 싶었을 뿐인데, Lighthouse가 이를 "보이지 않는 요소"로 판단해 LCP 측정 대상에서 아예 제외해버린다는 걸 직접 겪고 나서야 알았다.

결국 브라우저가 어떻게 해석하는지를 먼저 이해하는 게 중요하다는 걸 다시 확인했다.

참고

• Next.js Image Optimization
• next/font
• web.dev — Optimize LCP
• MDN — IntersectionObserver

배경

작업한 서비스는 세 개의 레이어로 나뉩니다.

Studio (개발자)
  어메니티 항목 등록 — 아이콘 코드, 이름, 카테고리 등
        ↓
host (숙소 운영자)
  자기 숙소에서 제공하는 어메니티 선택·추가
        ↓
게스트 화면
  해당 숙소의 제공 어메니티 아이콘 노출

Studio는 개발자가 어메니티 항목을 관리하는 어드민 페이지입니다. 여기서 새 어메니티를 등록하면, 숙소 운영자는 host 페이지에서 자기 숙소가 해당 어메니티를 제공한다고 설정할 수 있습니다. 그리고 게스트는 숙소 홈페이지에서 해당 숙소의 제공 어메니티를 아이콘으로 확인합니다.

여기서 핵심 조건이 하나 있습니다. Studio에서 새 어메니티를 추가할 때마다 개발자가 프론트엔드 코드를 수정하고 배포해야 하면 안 된다는 점입니다. 어메니티는 운영 중에도 수시로 추가되는데, 그때마다 배포가 필요하다면 현실적으로 운영이 어렵습니다.

정적 import 방식의 한계

제일 먼저 떠올린 방식은 아이콘 컴포넌트를 직접 import하는 방법이었습니다.

import { BathTowelIcon } from 'panzy-ui'
import { WifiIcon } from 'panzy-ui'

<BathTowelIcon />
<WifiIcon />

그런데 백엔드에서 내려오는 데이터는 이런 형태였습니다.

{
  "amenities": [
    { "name": "수건", "code": "BATH_TOWEL" },
    { "name": "WiFi", "code": "WIFI" }
  ]
}

code 값이 문자열로 오기 때문에, 어떤 아이콘을 렌더링할지 런타임 전에는 알 수 없습니다. 결국 정적 import 방식으로는 가능한 모든 code에 대해 아래처럼 직접 매핑 코드를 작성해야 합니다.

import { BathTowelIcon } from 'panzy-ui'
import { WifiIcon } from 'panzy-ui'
import { ParkingIcon } from 'panzy-ui'
// ...

const iconMap: Record<string, React.FC> = {
  BATH_TOWEL: BathTowelIcon,
  WIFI: WifiIcon,
  PARKING: ParkingIcon,
  // DB에 있는 모든 code를 여기에 직접 등록해야 함
}

const icon = iconMap[amenity.code]

Studio에서 새 어메니티가 추가될 때마다 개발자가 import 한 줄, iconMap 항목 한 줄을 수동으로 추가하고 배포해야 합니다. 어메니티가 총 150개가 넘고 계속 추가될 수 있는 상황이므로 이 방식은 처음부터 한계가 있었습니다.

아이콘 표시 방식 검토

정적 import의 한계를 확인하고 나서, 어떤 방식으로 아이콘을 관리하고 표시할지 몇 가지 방법을 비교했습니다.

CDN에 SVG 파일 서빙

SVG 파일을 S3 같은 스토리지에 올려두고 code 값으로 URL을 조합해 <img> 태그로 표시하는 방식입니다. 새 아이콘 추가 시 파일 업로드만 하면 되니 배포가 전혀 필요 없습니다. 다만 <img> 태그로 렌더링하면 CSS color 속성이 적용되지 않아 색상을 동적으로 제어할 수 없다는 단점이 있습니다.

SVG 스프라이트

모든 SVG를 하나의 sprite.svg 파일로 묶고 <use href="#icon-id">로 참조하는 방식입니다. 요청이 한 번으로 줄고 currentColor로 색상 제어도 됩니다. 하지만 아이콘이 추가될 때마다 스프라이트 파일을 다시 빌드해야 해서 완전한 무배포 운영은 어렵습니다.

DB에 SVG 마크업 저장

Studio에서 아이콘을 등록할 때 SVG 마크업 자체를 DB에 저장하고, 프론트에서 dangerouslySetInnerHTML로 렌더링하는 방식입니다. 프론트엔드 코드 변경이 전혀 필요 없고 색상 제어도 가능합니다. 다만 XSS 보안 처리가 필요하고, DB에 마크업을 직접 저장하는 구조가 관리 측면에서 부담이 됩니다.

SVG → TSX 컴포넌트

SVG를 빌드 타임에 React 컴포넌트로 변환해 패키지에서 관리하는 방식입니다. 색상 제어, 타입 안정성, 번들 최적화가 모두 가능합니다. 새 아이콘 추가 시 파일 변환과 배포가 필요하지만, code 값 기반 동적 매핑을 통해 Studio에서 어메니티를 추가할 때는 배포 없이 바로 연결되도록 구성할 수 있습니다.

이 프로젝트에서는 color prop으로 색상을 자유롭게 제어해야 했고, TypeScript 기반 모노레포에서 타입 안정성도 중요했습니다. 아이콘 파일이 추가될 때 배포가 필요하다는 점은 code 기반 동적 렌더링으로 보완할 수 있었기 때문에, SVG → TSX 컴포넌트 방식을 선택했습니다.

AmenityIconWrapper: 동적 렌더링으로 전환

code 값 자체를 활용하는 방향으로 전환했습니다. BATH_TOWEL이라는 문자열이 오면 이를 컴포넌트 이름으로 변환해 해당 컴포넌트를 찾아 렌더링하는 방식입니다.

<AmenityIconWrapper iconKey="BATH_TOWEL" color="#4A90E2" size={32} />

내부 변환 흐름은 다음과 같습니다.

"BATH_TOWEL"
  → "bath-towel"     (snake_case → kebab-case)
  → "BathTowelIcon"  (PascalCase로 변환)
  → 해당 컴포넌트 렌더링

이 방식을 쓰면 Studio에서 새 어메니티를 추가해도 프론트엔드 코드를 수정하거나 배포할 필요 없이 host와 게스트 화면에서 바로 아이콘이 연결됩니다.

code 값이 컴포넌트 이름과 정확히 일치하지 않는 케이스를 대비해 키워드 기반 fallback도 추가했습니다. coffee_maker_v2 같은 값이 오면 coffee 키워드를 보고 CoffeeMachineIcon으로 연결되는 식입니다. 완벽하진 않지만 아이콘이 아예 렌더링되지 않는 것보다는 낫다고 판단했습니다.

아이콘 관리 구조

아이콘 컴포넌트는 panzy-ui 패키지에서 중앙 관리합니다. SVG 파일을 그대로 쓰는 게 아니라 TSX 컴포넌트로 변환해서 사용했고, 원본 SVG는 amenitiesOriginal/ 폴더에 따로 보관했습니다.

카테고리별로 폴더를 나눴으며, 총 10개 카테고리 150개 이상입니다.

packages/panzy-ui/src/components/icons/amenities/
├── amenitiesOriginal/
├── bath/       (32개)
├── bedding/    (16개)
├── facility/   (15개)
├── kitchen/    (25개)
├── laundry/    (8개)
├── outdoor/    (8개)
├── pet/        (7개)
├── room/       (24개)
├── safety/     (9개)
└── service/    (10개)

모든 아이콘은 24x24 viewBox에 currentColor를 기본값으로 사용했습니다. currentColor를 쓰면 부모 요소의 CSS color를 상속받기 때문에, color prop 하나로 색상을 자유롭게 제어할 수 있습니다.

Studio 관리 UI

개발자가 어메니티 항목을 등록·관리하는 Studio 쪽 UI도 함께 작업했습니다.

packages/studio/src/app/studio/management/amenity-categories/
├── AmenityForm.tsx
├── AmenityCategoryForm.tsx
├── AmenityTable.tsx
└── AmenityCategoryTable.tsx

데이터 모델에서 신경 쓴 부분은 scope 필드입니다. 어메니티가 숙소 전체에 해당하는지, 객실별로 다른지를 구분해야 했습니다. 수영장·주차장은 숙소 공통이고, 침대 타입·욕실 비품은 객실마다 다를 수 있기 때문입니다.

• ACCOMMODATION — 숙소 공통
• ROOM — 객실별
• BOTH — 둘 다

다국어 이름·설명(translations)과 정렬 순서(seq)도 관리할 수 있도록 했습니다.

초기 구현 이후 발견한 문제와 개선

초기 구현을 마치고 나서 세 가지 문제가 눈에 들어왔습니다.

1. SVG 수동 변환 자동화

아이콘이 추가될 때마다 SVG 파일을 직접 TSX 컴포넌트로 변환했는데, 150개가 넘다 보니 반복 작업의 비중이 꽤 컸습니다. 아이콘이 늘어날수록 더 심해질 게 분명해서 @svgr/cli와 svgo로 자동화했습니다.

package.json에 스크립트를 추가했습니다.

{
  "scripts": {
    "generate:icons": "svgr --config .svgrrc.json src/components/icons/amenities/amenitiesOriginal --out-dir src/components/icons/amenities/generated"
  }
}

.svgrrc.json 설정은 아래와 같습니다.

{
  "plugins": ["@svgr/plugin-svgo", "@svgr/plugin-jsx"],
  "svgoConfig": {
    "plugins": [
      { "name": "preset-default" },
      { "name": "prefixIds" }
    ]
  },
  "typescript": true,
  "dimensions": false,
  "replaceAttrValues": { "#000": "currentColor", "#000000": "currentColor" }
}

이제 amenitiesOriginal/ 폴더에 SVG를 넣고 스크립트를 실행하면 TSX 컴포넌트가 자동으로 생성됩니다.

2. SVG id 충돌 방지

SVG 내부에서 mask나 linearGradient 같은 요소에 id를 사용하는 경우, 같은 페이지에 동일한 아이콘이 여러 개 렌더링되면 id가 충돌해 렌더링이 깨질 수 있습니다.

예를 들어 같은 아이콘 두 개가 각각 mask0라는 id를 가지고 있으면, 두 번째 아이콘의 마스크가 첫 번째 것을 참조하게 되어 시각적으로 오동작합니다.

svgo의 prefixIds 플러그인을 자동화 파이프라인에 포함시켜서 해결했습니다. 변환 시 각 SVG 파일의 id를 파일명 기반 고유 prefix로 자동 대체해줍니다.

{
  "svgoConfig": {
    "plugins": [
      { "name": "prefixIds" }
    ]
  }
}

변환 전후를 비교하면 이렇습니다.

<!-- 변환 전 -->
<mask id="mask0">...</mask>
<rect mask="url(#mask0)" />

<!-- 변환 후 (bath-towel.svg 기준) -->
<mask id="bath-towel-mask0">...</mask>
<rect mask="url(#bath-towel-mask0)" />

자동화 파이프라인에 포함되어 있으니, 이후 추가되는 아이콘도 별도 처리 없이 id 충돌이 방지됩니다.

3. 트리쉐이킹 — 동적 import로 전환

AmenityIconWrapper가 내부에서 전체 아이콘 맵을 정적으로 들고 있는 구조였습니다.

import * as AmenityIcons from '../icons/amenities'

const iconMap = { ...AmenityIcons }

이렇게 하면 실제로 사용하지 않는 아이콘도 전부 번들에 포함됩니다. 150개 이상의 SVG 컴포넌트가 모두 번들에 들어가는 셈입니다.

동적 import로 바꿔서 렌더링 시점에 필요한 아이콘만 로드하도록 했습니다.

import { lazy, Suspense } from 'react'

function AmenityIconWrapper({ iconKey, size = 24, color = 'currentColor' }: Props) {
  const componentName = toComponentName(iconKey) // "BATH_TOWEL" → "BathTowelIcon"

  const IconComponent = lazy(() =>
    import(`../icons/amenities/generated/${toKebabCase(iconKey)}`).then((mod) => ({
      default: mod[componentName] ?? mod.default,
    }))
  )

  return (
    <Suspense fallback={<span style={{ width: size, height: size, display: 'inline-block' }} />}>
      <IconComponent width={size} height={size} color={color} />
    </Suspense>
  )
}

번들 사이즈가 줄었고, 실제로 노출되는 아이콘만 네트워크 요청이 발생합니다. 다만 아이콘마다 별도 chunk가 생기기 때문에, 한 화면에 아이콘이 여러 개 노출된다면 그만큼 요청이 늘어납니다. 숙소 상세 페이지처럼 어메니티를 한꺼번에 여러 개 보여주는 화면에서는 문제가 될 수 있습니다.

이를 보완하기 위해 아이콘을 카테고리 단위로 묶어 하나의 chunk로 로드하는 방식을 적용했습니다. 각 카테고리별로 index 파일을 두고, 아이콘 코드에서 카테고리를 먼저 추출한 뒤 해당 카테고리 chunk를 동적으로 import합니다.

// 카테고리별 index (예: bath/index.ts)
export { BathTowelIcon } from './BathTowelIcon'
export { ShampooIcon } from './ShampooIcon'
export { SoapIcon } from './SoapIcon'
// ...

// AmenityIconWrapper
const IconComponent = lazy(() =>
  import(`../icons/amenities/${getCategory(iconKey)}/index`).then((mod) => ({
    default: mod[componentName],
  }))
)

이렇게 하면 같은 카테고리의 아이콘들은 첫 번째 요청 이후 캐싱되어 추가 요청 없이 바로 렌더링됩니다. 숙소 상세 페이지처럼 bath 카테고리 아이콘이 여러 개 노출되는 경우, 요청이 아이콘 수만큼이 아니라 카테고리 수만큼으로 줄어듭니다.

마무리

Studio에서 어메니티를 추가하면 host와 게스트 화면에 배포 없이 바로 반영되어야 한다는 조건 하나가 설계 방향 자체를 바꿨습니다. 단순히 아이콘을 렌더링하는 문제가 아니라, code 문자열을 컴포넌트로 동적 연결하는 구조를 설계해야 했고, 이를 위해 SVG → TSX 컴포넌트 방식을 선택하게 됐습니다.

초기 구현 이후에 보이기 시작한 문제들은 모두 "처음부터 알았더라면"이라는 생각이 드는 것들이었습니다. 수동 변환 작업은 svgr 파이프라인으로 없앴고, SVG id 충돌은 prefixIds를 파이프라인에 포함하면서 변환 시점에 원천 차단했습니다. 번들 최적화는 동적 import와 카테고리 단위 chunk 묶음을 조합해 해결했습니다. 세 가지 모두 기능 자체가 아니라 운영 맥락에서 비로소 보이는 문제였다는 점이 공통점입니다.

코드가 정상적으로 실행되는 것과, 실제 환경에서 지속적으로 사용될 수 있는 수준의 코드 사이에는 분명한 차이가 있었습니다. 이번 작업은 그 차이를 구성하는 요소들(유지보수성, 예외 처리, 코드 구조 등)을 구체적으로 고민해볼 수 있는 경험이었습니다.

vercel.app 서브도메인으로 배포한 포트폴리오 사이트에서 Lighthouse SEO 점수가 100점에서 63점으로 급락했다. 코드를 아무리 뜯어봐도 문제가 없는데, 원인은 의외로 단순했다.

문제 상황

포트폴리오 사이트를 Vercel에 배포한 후 Lighthouse로 성능을 측정했다.

• 성능: 99
• 접근성: 100
• 권장사항: 100
• 검색엔진 최적화(SEO): 63 🚨

SEO 항목을 클릭해서 펼쳐보니 이런 오류가 표시됐다.

크롤링 및 색인 생성
▲ 페이지의 색인 생성이 차단됨

Blocking Directive Source
x-robots-tag: noindex

meta 태그도 문제없고, sitemap도 있고, 코드 상에서 noindex를 설정한 적이 없는데 왜 이런 헤더가 붙는 걸까?

x-robots-tag가 뭔가요?

x-robots-tag는 HTTP 응답 헤더로, 검색엔진 크롤러에게 해당 페이지를 어떻게 처리할지 지시하는 역할을 한다.

x-robots-tag: noindex

이 헤더가 응답에 포함되면 Google, Bing 등 검색엔진은 해당 페이지를 크롤링은 하지만 검색 결과에는 포함시키지 않는다.

HTML에서 사용하는 아래 메타 태그와 동일한 효과를 HTTP 헤더 레벨에서 발휘한다.

<meta name="robots" content="noindex" />

차이점은 메타 태그는 HTML 파싱 후 적용되지만, HTTP 헤더는 페이지 로드 전에 이미 적용된다는 점이다.

왜 Vercel이 자동으로 붙이는 걸까?

원인은 vercel.app 서브도메인 정책 때문이다.

Vercel은 무료 플랜에서 *.vercel.app 서브도메인으로 프로젝트를 배포한다.

https://my-project.vercel.app

문제는 이 vercel.app 도메인 아래에 수천, 수만 개의 프로젝트가 배포되어 있다는 점이다. 만약 모든 프로젝트가 검색엔진에 인덱싱된다면:

• 테스트용, 임시 배포 프로젝트들이 검색 결과에 노출됨
• 스팸성 콘텐츠로 분류될 가능성이 높아짐
• vercel.app 도메인 자체의 검색 신뢰도가 낮아짐

이런 이유로 Vercel은 커스텀 도메인이 연결되지 않은 vercel.app 서브도메인에는 자동으로 x-robots-tag: noindex 헤더를 삽입한다.

즉, 내 코드의 문제가 아니라 Vercel 인프라 레벨에서 강제로 삽입하는 헤더다.

직접 확인하는 방법

터미널에서 curl 명령어로 응답 헤더를 확인할 수 있다.

curl -I https://my-project.vercel.app

응답 헤더에서 아래와 같이 확인된다.

HTTP/2 200
...
x-robots-tag: noindex
...

커스텀 도메인이 연결된 경우에는 이 헤더가 없다.

코드로 우회할 수 없을까?

next.config.js에서 응답 헤더를 직접 설정해서 index로 덮어쓰려고 시도해봤다.

// next.config.js
const nextConfig = {
  async headers() {
    return [
      {
        source: "/(.*)",
        headers: [
          { key: "X-Robots-Tag", value: "index" },
        ],
      },
    ];
  },
};

결과는 효과 없음이다.

Vercel 인프라 레벨에서 응답 헤더를 후처리하여 noindex를 덮어쓰기 때문에, 애플리케이션 코드에서 설정한 헤더는 무시된다. 이것이 핵심 포인트다.

코드 레벨에서는 해결이 불가능하다.

해결 방법

방법 1 — 커스텀 도메인 연결 (가장 확실)

커스텀 도메인을 연결하면 Vercel이 noindex 헤더를 자동으로 제거한다.

1. 도메인 구매 (가비아, Namecheap, Google Domains 등)
2. Vercel 프로젝트 → Settings → Domains
3. 구매한 도메인 입력 후 DNS 설정
4. 연결 완료 후 x-robots-tag: noindex 헤더 사라짐

방법 2 — GitHub Pages로 이전

GitHub Pages는 무료 플랜에서도 noindex 헤더를 붙이지 않는다.

Next.js 프로젝트의 경우 next.config.js에서 정적 내보내기 설정이 필요하다.

// next.config.js
const nextConfig = {
  output: "export",
};

방법 3 — Netlify로 이전

Netlify도 무료 플랜에서 noindex 없이 배포가 가능하다. 설정 없이 GitHub 연동 후 바로 배포할 수 있다.

정리

번외 — X-Robots-Tag, noindex 말고 뭐가 더 있을까?

이번 문제를 겪으면서 x-robots-tag를 처음 접했다면, noindex 외에도 다양한 디렉티브가 있다는 걸 알아두면 나중에 유용하다.

자주 쓰이는 디렉티브

숫자로 세밀하게 제어하는 디렉티브도 있다.

# 스니펫 최대 150자
X-Robots-Tag: max-snippet: 150

# 이미지 미리보기 크기 제한 (none | standard | large)
X-Robots-Tag: max-image-preview: standard

# 특정 날짜 이후 검색 결과에서 제거
X-Robots-Tag: unavailable_after: Tue, 31 Dec 2025 23:59:59 GMT

특정 봇에만 적용하기

봇 이름을 앞에 붙이면 해당 크롤러에게만 규칙이 적용된다.

X-Robots-Tag: googlebot: nofollow
X-Robots-Tag: googlebot: nofollow, BadBot: noindex, nofollow

X-Robots-Tag vs robots.txt

헷갈리기 쉬운 둘의 차이를 정리하면 다음과 같다.

한 가지 주의할 점이 있다. robots.txt로 접근이 차단된 URL은 크롤러가 x-robots-tag를 읽지 못한다. 색인 제거가 목적이라면 크롤링을 허용한 상태에서 noindex를 쓰는 것이 맞다.

Next.js에서 직접 설정할 때

커스텀 도메인이 연결된 환경에서 특정 경로만 색인화를 막고 싶다면 이렇게 쓴다.

// next.config.js
async headers() {
  return [
    {
      source: '/admin/:path*',
      headers: [{ key: 'X-Robots-Tag', value: 'noindex, nofollow' }],
    },
  ];
},

마치며

Lighthouse SEO 점수가 갑자기 낮아졌다고 해서 코드를 한참 뒤졌는데, 원인은 Vercel의 플랫폼 정책이었다.

포트폴리오 사이트처럼 실제 검색 노출이 중요한 경우라면 커스텀 도메인 연결을 고려하는 것이 좋다. 도메인 가격은 연간 1~2만원 수준으로 부담이 크지 않다.

반대로 개발 중인 프로젝트나 테스트 배포라면 vercel.app 서브도메인의 noindex 정책이 오히려 의도치 않은 검색 노출을 막아주는 장점이 되기도 한다.

참고

• Vercel 공식 문서 — Deployment Protection
• Google 검색 센터 — robots 메타 태그 및 X-Robots-Tag HTTP 헤더
• MDN Web Docs — X-Robots-Tag

포트폴리오 사이트의 기술 스택 섹션을 개발하면서 아이콘 처리 방식이 성능에 이렇게까지 영향을 미칠 거라고는 생각하지 못했습니다.

처음엔 단순히 타입 안전성을 높이는 리팩토링이었는데, 결국 외부 CDN 의존을 완전히 제거하는 방향으로 이어졌습니다.

이 글은 그 과정을 단계별로 정리한 기록입니다.

1단계 — Type-safe 구조로: SkillId union type 도입

문제

처음 코드는 스킬 이름(string)을 key로 아이콘 URL을 매핑하는 구조였습니다.

// Skills.tsx
const ICON_URL: Record<string, string> = {
    "HTML": `${DI}/html5/html5-original.svg`,
    "React": `${DI}/react/react-original.svg`,
    // ...
};

이 구조는 오타가 발생해도 TypeScript가 잡아주지 못했고, 존재하지 않는 키에 접근해도 컴파일 에러가 없었습니다.

해결

SkillId union type을 정의하고 Record<SkillId, string>으로 타입을 좁혔습니다.

// types/index.ts
export type SkillId =
    | "html"
    | "css"
    | "javascript"
    | "typescript"
    | "react"
    | "nextjs"
    // ...

export interface Skill {
    id: SkillId;
    name: string;
    color: string;
}

// Skills.tsx
const ICON_URL: Record<SkillId, string> = {
    html: `${DI}/html5/html5-original.svg`,
    react: `${DI}/react/react-original.svg`,
    // ...
};

효과: 오타 시 즉시 컴파일 에러. 존재하지 않는 id 접근 차단.

2단계 — 데이터 구조 개선: 아이콘을 데이터 안으로 이동

문제

스킬 데이터(portfolio.ts)와 아이콘 URL(Skills.tsx)이 분리되어 있어서, 스킬을 추가할 때 두 파일을 동시에 수정해야 했습니다.

portfolio.ts  → 스킬 데이터 (name, color)
Skills.tsx    → 아이콘 매핑 (ICON_URL)

유지보수할 때 둘 중 하나를 빠뜨리면 아이콘이 깨지는 문제가 있었습니다.

해결: 데이터 colocation 구조

Skill 인터페이스에 icon 필드를 추가하고, 아이콘 URL을 데이터 안에 포함시켰습니다.

// types/index.ts
export interface Skill {
    id: SkillId;
    name: string;
    color: string;
    icon?: string; // 추가
}

// portfolio.ts
export const skillGroups: SkillGroup[] = [
    {
        category: "Language",
        skills: [
            { id: "html", name: "HTML", color: "#e34c26", icon: `${DI}/html5/html5-original.svg` },
            { id: "react", name: "React", color: "#61dafb", icon: `${DI}/react/react-original.svg` },
        ],
    },
];

// Skills.tsx — ICON_URL 완전 제거
{skill.icon ? (
    <img src={skill.icon} alt={skill.name} width={14} height={14} />
) : (
    <span style={{ backgroundColor: skill.color }} />
)}

효과: 스킬을 추가할 때 portfolio.ts 한 곳만 수정하면 됩니다. 데이터와 아이콘 정보가 같은 곳에 있으니(data colocation) 누락이 생길 수 없습니다.

ICON_URL을 제거하고 <img> 태그를 직접 쓰게 되면서, 이미지 최적화에 대해 평소 알고 있던 내용을 적용해보고 싶었습니다.

"이미지 태그에는 loading="lazy" 거는 게 성능에 좋다고 했으니까 추가해두자."

<img
    src={skill.icon}
    alt={skill.name}
    width={14}
    height={14}
    loading="lazy" // 추가
/>

이미지 성능 최적화를 공부하다 보면 loading="lazy"가 자주 등장합니다. 스크롤 아래 이미지를 뷰포트에 가까워질 때까지 로드를 미뤄서 초기 로딩을 빠르게 만드는 기법인데, 문제는 이걸 14×14px짜리 아이콘에도 그대로 적용했다는 점입니다.

loading="lazy"가 효과적인 상황은 따로 있습니다.

• 뷰포트 아래에 있는 크고 무거운 이미지
• 초기 로딩 시 굳이 가져올 필요 없는 이미지

Skills 섹션의 아이콘은 달랐습니다. 크기가 14x14px라 용량 자체가 작고, Lighthouse가 모바일 에뮬레이션으로 측정할 때 측정이 끝나기 전에 로드가 완료되지 않아 미완성 상태로 점수에 반영됩니다. 결과는 87점 → 75점, 12점 하락이었습니다.

loading="lazy"를 제거하자 점수는 82점으로 회복됐지만, 초기 87점으로 돌아오지 않았습니다. lazy가 문제가 아니라 외부 CDN 요청 자체가 병목이었다는 걸 파악하게 됐습니다.

3단계 — 성능 개선: 외부 CDN → 로컬 SVG

문제

아이콘 URL이 두 개의 외부 CDN을 사용하고 있었습니다.

const DI = "https://cdn.jsdelivr.net/gh/devicons/devicon@latest/icons";
const SI = "https://cdn.simpleicons.org";

총 33개의 외부 이미지 요청이 발생하고 있었고, Lighthouse 성능 점수가 82점에서 더 오르지 않았습니다.

원인 분석

외부 CDN 요청의 문제는 단순히 파일을 가져오는 게 아닙니다. 각 도메인마다 아래 과정이 필요합니다.

cdn.jsdelivr.net  : DNS 조회 → TCP 연결 → TLS 핸드셰이크 → 요청
cdn.simpleicons.org: DNS 조회 → TCP 연결 → TLS 핸드셰이크 → 요청

preconnect로 사전 연결을 맺어도, 33개 요청 자체가 네트워크 비용이었습니다. 특히 Lighthouse가 모바일 에뮬레이션으로 측정할 때 외부 네트워크 지연이 점수에 직접 반영됩니다.

해결 — 아이콘 로컬 저장

모든 SVG 아이콘을 /public/icons/에 다운로드했습니다.

# 터미널에서 일괄 다운로드
DI="https://cdn.jsdelivr.net/gh/devicons/devicon@latest/icons"
SI="https://cdn.simpleicons.org"
OUT="./public/icons"

curl -s -o "$OUT/html.svg"       "${DI}/html5/html5-original.svg"
curl -s -o "$OUT/react.svg"      "${DI}/react/react-original.svg"
curl -s -o "$OUT/mobx.svg"       "${SI}/mobx/ff7a00"
# ... (36개 전체)

이후 portfolio.ts의 icon 경로를 로컬로 전환했습니다.

// Before
{ id: "html", name: "HTML", color: "#e34c26", icon: `${DI}/html5/html5-original.svg` }

// After
{ id: "html", name: "HTML", color: "#e34c26", icon: "/icons/html.svg" }

CDN 상수와 preconnect 힌트도 모두 제거했습니다.

// 제거
const DI = "https://cdn.jsdelivr.net/gh/devicons/devicon@latest/icons";
const SI = "https://cdn.simpleicons.org";

// layout.tsx에서 제거
<link rel="preconnect" href="https://cdn.jsdelivr.net" />
<link rel="preconnect" href="https://cdn.simpleicons.org" />

결과

단계별 변화를 정리하면 아래와 같습니다.

배운 점

loading="lazy"는 크기와 위치를 먼저 따져야 한다

14×14px 아이콘처럼 용량이 작고 페이지 중간에 위치한 이미지에는 오히려 역효과가 납니다. 뷰포트 아래 멀리 있는 크고 무거운 이미지에만 사용해야 합니다.

외부 CDN은 파일 수와 배포 환경을 고려해야 한다

아이콘 36개처럼 파일 수가 적고 Vercel처럼 자체 엣지 서빙이 되는 환경에서는 외부 CDN보다 로컬 파일이 더 안정적입니다.

next/image는 SVG에 최적화가 적용되지 않는다

SVG는 WebP 변환이 불가능하고 보안상 기본 차단됩니다. 14px 아이콘에는 width/height를 명시한 <img>가 더 적합합니다.

🔍 번외 — next/image vs <img>: SVG 아이콘에는 무엇이 맞을까?

로컬 SVG로 전환하고 나서 한 가지 의문이 더 생겼습니다. "Next.js 프로젝트니까 이미지는 next/image로 통일하는 게 맞지 않을까?" 검토해보니 이 경우엔 오히려 잘못된 선택이었습니다.

next/image의 핵심 기능

next/image가 제공하는 주요 최적화는 세 가지입니다.

• PNG/JPG → WebP/AVIF 자동 변환
• 뷰포트 기반 사이즈 리사이징
• Lazy loading 및 CLS(Cumulative Layout Shift) 방지

SVG에는 최적화가 적용되지 않음

SVG는 벡터 포맷이라 WebP 변환이나 사이즈 리사이징이 불가능합니다. next/image를 사용해도 SVG는 원본 파일 그대로 서빙됩니다.

PNG/JPG → next/image → WebP 변환 ✅ 최적화됨
SVG     → next/image → SVG 그대로 ❌ 최적화 없음

next/image는 SVG를 기본적으로 차단

SVG 내부에 <script>가 포함될 수 있어 보안상 이유로, next/image는 SVG를 기본적으로 차단합니다. 제대로 사용하려면 next.config.ts에 별도 설정이 필요합니다.

// next.config.ts
const nextConfig: NextConfig = {
    images: {
        dangerouslyAllowSVG: true, // 명시적으로 허용해야 함
    },
};

이 설정 없이 SVG를 next/image에 넘기면 내부적으로 unoptimized 처리되거나 예상치 못한 동작이 발생할 수 있습니다.

14×14px 아이콘에 next/image는 오버엔지니어링

next/image가 진가를 발휘하는 건 히어로 이미지, 프로젝트 썸네일처럼 크고 무거운 이미지일 때입니다. 14px짜리 아이콘 36개에 적용하면 오히려 불필요한 JS 번들 비용만 추가됩니다.

CLS 방지는 width와 height를 명시하는 것만으로 충분합니다. next/image 없이도 동일한 효과를 얻을 수 있습니다.

최종 코드

// ✅ 로컬 SVG 아이콘 — 일반 <img> 사용
{skill.icon ? (
    // eslint-disable-next-line @next/next/no-img-element
    <img
        src={skill.icon}
        alt={skill.name}
        width={14}
        height={14}
        style={{ width: 14, height: 14, flexShrink: 0 }}
    />
) : (
    <span
        className="w-2 h-2 rounded-full flex-shrink-0"
        style={{ backgroundColor: skill.color }}
    />
)}

이미지 종류별 권장 방법 정리

next/image는 강력한 도구지만, 모든 이미지에 무조건 적용하는 게 정답은 아닙니다. 이미지의 포맷과 크기, 역할에 따라 적절한 방법을 선택하는 것이 중요합니다.

그래서 이 과정이 의미있었나?

최종 점수는 처음과 같은 87점입니다. 솔직히 말하면 저도 이 질문을 스스로 했습니다. 하지만 CDN을 이용한 87점과 지금의 87점은 다릅니다.

CDN 87점은 외부 네트워크 상태에 따라 달라질 수 있지만, 로컬 SVG 87점은 외부 요인 없이 항상 같은 점수가 나옵니다. 그리고 Lighthouse 점수와 무관하게, SkillId union type과 data colodation은 코드를 더 안전하고 유지보수하기 쉽게 만들었습니다. 스킬을 추가할 때 파일 두 곳을 동시에 수정하지 않아도 되고, 오타가 생기면 즉시 컴파일 에러로 잡힙니다.

점수는 같아도 코드는 달라졌습니다.

마치며

아이콘 36개의 로딩 방식만으로도 Lighthouse 점수가 10점 이상 차이 날 수 있음을 확인했습니다. 성능 최적화는 대규모 아키텍처 개선뿐 아니라, 이처럼 작은 리소스 처리 방식의 선택에서도 크게 좌우된다는 점을 다시 느꼈습니다.

웹 개발을 하다 보면 페이지 로딩 시 폰트가 갑자기 바뀌는 경험을 한 적이 있을 것이다.
이 현상을 FOUT(Flash of Unstyled Text)라고 한다.

이번 글에서는 FOUT이 무엇인지, 왜 발생하는지, 그리고 실무에서 어떻게 방지하는지 정리해본다.

FOUT이란?

FOUT (Flash of Unstyled Text)
웹폰트가 로딩되기 전에 기본 폰트로 먼저 렌더링되었다가,
이후 웹폰트가 적용되면서 텍스트 스타일이 바뀌는 현상이다.

예시 흐름

1. 페이지 로딩 시작
2. 기본 시스템 폰트로 텍스트 표시
3. 웹폰트 로딩 완료
4. 텍스트가 다른 폰트로 변경됨

→ 이때 폰트가 바뀌는 느낌이 바로 FOUT

왜 문제가 될까?

• UI가 깜빡이는 것처럼 보임
• 디자인 완성도가 떨어져 보일 수 있음
• 콘텐츠 집중도를 방해
• 경우에 따라 CLS(Cumulative Layout Shift)에도 영향

FOIT과의 차이

→ 최근에는 FOIT보다 FOUT을 허용하고 최적화하는 방향이 일반적이다.

🛠️ FOUT 줄이는 방법

1. font-display 속성 활용

@font-face {
  font-family: 'MyFont';
  src: url('/fonts/myfont.woff2') format('woff2');
  font-display: swap;
}

• swap: 기본 폰트 → 웹폰트 교체 (가장 많이 사용)
• block: 텍스트 숨김 후 표시 (FOIT)
• optional: 네트워크 상황에 따라 웹폰트 생략

→ 실무에서는 보통 swap을 기본으로 사용한다.

2. preload로 폰트 로딩 최적화

<link 
  rel="preload" 
  href="/fonts/myfont.woff2" 
  as="font" 
  type="font/woff2" 
  crossorigin
/>

→ 폰트를 우선적으로 다운로드해서 FOUT 시간을 줄인다.

3. fallback 폰트 설정

font-family: 'MyFont', 'Apple SD Gothic Neo', 'Noto Sans KR', sans-serif;

→ 웹폰트와 비슷한 폰트를 설정하면 변경 시 이질감이 줄어든다.

4. 폰트 파일 최적화

• woff2 포맷 사용
• 필요한 글자만 포함 (subset)
• 폰트 용량 최소화

→ 로딩 속도가 빨라질수록 FOUT도 줄어든다.

5. 폰트 로딩 이후 처리 (선택)

document.fonts.ready.then(() => {
  document.body.classList.add('fonts-loaded');
});

→ 폰트 로딩 시점을 기준으로 스타일 제어가 가능하다.

실무에서 사용하는 기본 조합

@font-face {
  font-family: 'MyFont';
  src: url('/fonts/myfont.woff2') format('woff2');
  font-display: swap;
}

body {
  font-family: 'MyFont', 'Apple SD Gothic Neo', sans-serif;
}

<link rel="preload" href="/fonts/myfont.woff2" as="font" type="font/woff2" crossorigin>

→ 이 정도 설정으로 대부분의 FOUT 문제는 완화된다.

추가로 고려할 점

CLS까지 함께 고려하기

폰트 변경 시 레이아웃이 흔들릴 수 있다.

• fallback 폰트를 최대한 유사하게 선택
• font-size-adjust 사용 고려

Google Fonts 사용할 경우

<link href="https://fonts.googleapis.com/css2?family=Roboto&display=swap" rel="stylesheet">

→ display=swap 옵션을 함께 사용하는 것이 좋다.

정리

• FOUT은 웹폰트 로딩 과정에서 발생하는 자연스러운 현상
• font-display: swap은 기본적으로 적용하는 것이 좋음
• preload + fallback 폰트 조합으로 대부분의 문제는 완화 가능
• 완전히 제거하기보다, 사용자 입장에서 자연스럽게 보이도록 만드는 것이 더 중요

마무리

웹폰트는 단순히 디자인 요소라고만 생각했는데,
실제로는 성능과 UX에도 영향을 주는 부분이었다.

특히 fallback 폰트나 로딩 전략에 따라 사용자가 느끼는 화면의 안정감이 달라진다는 점이 인상적이었다.

앞으로는 폰트를 적용할 때도 단순히 디자인만 생각할 게 아니라, 로딩 과정과 사용자 경험까지 같이 고려해야겠다고 느꼈다.

특히 Next.js는 Server와 Client가 함께 존재하기 때문에
환경 변수의 사용 범위를 명확히 구분해야 한다.

1. .env.local

Next.js에서는 .env.local 파일을 통해 환경 변수를 관리한다.

NEXT_PUBLIC_API_URL=https://api.example.com
NEXT_PUBLIC_APP_ENV=development

DATABASE_URL=postgres://user:password@localhost:5432/db
JWT_SECRET=super-secret-key

특징

• 로컬 환경에서만 사용
• Git에 포함되지 않음 (.gitignore)
• 민감 정보(API Key, DB 정보) 분리 가능

환경 파일 종류

우선순위

.env.local > .env.development > .env

실무 기준

• 로컬: .env.local 사용
• 배포: 플랫폼(Vercel 등)에 직접 설정

2. process.env 사용법

환경 변수는 process.env로 접근한다.

const apiUrl = process.env.NEXT_PUBLIC_API_URL;

핵심 규칙

1. 클라이언트에서 사용하려면 NEXT_PUBLIC_ 필요

NEXT_PUBLIC_API_URL=...

→ 브라우저에서 접근 가능

2. prefix 없는 변수는 서버 전용

JWT_SECRET=...

→ 서버에서만 사용 가능

왜 이런 구조일까?

Next.js는 클라이언트 코드를 브라우저로 번들링한다.

• NEXT_PUBLIC_ → 번들에 포함됨
• 일반 변수 → 서버에만 존재

→ 잘못 사용하면 비밀 정보가 그대로 노출됨

3. 실행 환경 (Server vs Client)

Next.js는 코드 실행 위치에 따라 동작이 달라진다.

Server Side

• Node.js에서 실행
• 모든 환경 변수 접근 가능

export async function getServerSideProps() {
  const db = process.env.DATABASE_URL;
}

Client Side

• 브라우저에서 실행
• NEXT_PUBLIC_ 변수만 접근 가능

useEffect(() => {
  fetch(process.env.NEXT_PUBLIC_API_URL);
}, []);

핵심

→ 같은 코드라도 실행 위치에 따라 결과가 달라진다

4. 환경 변수 로딩 시점

환경 변수는 빌드 및 서버 시작 시점에 로딩된다

특징

• 실행 중 변경 불가
• 변경 후 서버 재시작 필요

npm run dev

5. 실무 패턴

API 주소 분리

# 개발
NEXT_PUBLIC_API_URL=http://localhost:3000

# 배포
NEXT_PUBLIC_API_URL=https://api.myapp.com

환경 구분

NEXT_PUBLIC_APP_ENV=development

if (process.env.NEXT_PUBLIC_APP_ENV === "development") {
  console.log("dev mode");
}

서버 전용 변수

JWT_SECRET=...
DATABASE_URL=...

→ NEXT_PUBLIC_ 붙이지 않기

6. 보안 원칙

잘못된 예:

const secret = process.env.JWT_SECRET;

→ 클라이언트 코드에서 사용 시 노출 위험

올바른 방식:

• 비밀 값 → 서버에서만 사용
• 클라이언트 → API 호출만 수행

7. 디버깅 체크리스트

• NEXT_PUBLIC_ prefix 확인
• 서버 재시작 여부
• 변수명 오타
• .env.local 위치 확인

8. 배포 시 주의사항

• .env.local은 배포 서버에 포함되지 않음
• 환경 변수는 배포 플랫폼에 직접 등록해야 함

정리

• 환경 변수는 실행 환경에 따라 접근 범위가 다르다
• 클라이언트에서는 NEXT_PUBLIC_ 필수
• 민감 정보는 서버에서만 처리
• 환경 변수는 빌드/실행 시점에 적용된다

1. Vercel 배포

Next.js는 Vercel에서 가장 쉽게 배포할 수 있다.

배포 흐름

1. GitHub에 코드 push
2. Vercel에서 프로젝트 import
3. 자동 빌드
4. 배포 완료 (URL 생성)

특징

• Next.js와 높은 호환성
• SSR / SSG 자동 처리
• 서버리스 함수(/api) 지원
• CDN 자동 적용
• Git 기반 CI/CD

추가 기능

• Preview 배포 (브랜치별)
• PR 미리보기 URL 생성
• 이전 배포로 롤백 가능

2. 빌드 과정 (next build)

npm run build

빌드는 단순 번들링이 아니라
각 페이지의 렌더링 방식(SSR / SSG / ISR)을 결정하는 단계다.

빌드 시 수행 작업

• 코드 분할 (Code Splitting)
• 정적 페이지 생성 (SSG)
• 서버 코드 번들링 (SSR)
• 이미지 및 자산 최적화
• Tree Shaking

결과물

.next/

• 정적 HTML
• JS 번들
• 서버 실행 코드

이 폴더가 없으면 production 실행 불가

3. 실행 (next start)

npm run start

• production 환경에서 실행
• SSR 요청 처리

확인 방법

npm run build && npm run start

배포 전에 반드시 실행해서
production 환경에서 문제 없는지 확인해야 한다.

4. 개발 vs 배포 환경 차이

개발 (next dev)

• Hot Reload
• 디버깅 중심
• 최적화 없음

배포 (build + start)

• 코드 최적화
• 캐싱 및 압축 적용
• 에러 기준 엄격

자주 발생하는 문제

• window / document 사용
• 환경 변수 누락
• hydration 불일치

예시

window.innerWidth

→ 서버에서는 실행 불가

해결

if (typeof window !== "undefined") {
  console.log(window.innerWidth);
}

5. 환경 변수 (배포 시)

문제

.env.local은 로컬 전용이므로 배포 서버에 존재하지 않는다.

해결

Vercel에서 직접 설정

• Development
• Preview
• Production

예시

NEXT_PUBLIC_API_URL=https://api.myapp.com
JWT_SECRET=xxxx

6. API 주소 문제

잘못된 방식

fetch("http://localhost:3000/api");

배포 환경에서는 동작하지 않는다.

올바른 방식

fetch(`${process.env.NEXT_PUBLIC_API_URL}/api`);

또는

fetch("/api");

7. 빌드 에러 대응

자주 발생하는 문제

타입 에러

빌드 시 타입 오류 발생 → 타입 명확히 정의 필요

window is not defined

서버에서 실행되기 때문

hydration error

서버와 클라이언트 렌더링 결과 불일치

예시

const time = new Date();

해결

useEffect(() => {
  setTime(new Date());
}, []);

8. 배포 체크리스트

• npm run build 성공
• npm run start 로컬 테스트
• 환경 변수 설정 완료
• API 주소 분리
• window 사용 여부 확인

9. 성능 최적화

• next/image 사용
• dynamic import 적용
• CSR 최소화 (가능하면 SSR / SSG 사용)

10. 배포 흐름

git push → build → deploy → production

정리

• 배포는 빌드 중심 과정이다.
• 개발과 배포 환경은 다르게 동작한다.
• 환경 변수는 별도로 관리해야 한다.
• 대부분의 문제는 환경 차이에서 발생한다.

한 줄 요약

Next.js 배포는 코드보다 환경 변수, 렌더링 전략(SSR/SSG), 실행 환경 차이에 더 크게 영향을 받는다.

웹 서비스에서 SEO(Search Engine Optimization)는
검색 엔진 노출과 유입에 직접적인 영향을 준다.

Next.js(App Router 기준)는 Metadata API를 통해
SEO 설정을 매우 간단하고 강력하게 관리할 수 있다.

이 글에서는 다음 3가지를 핵심으로 정리한다:

• Metadata 설정
• 동적 메타데이터
• SEO 최적화 전략

🏷 1. Metadata 설정

✅ Metadata란?

• 페이지의 정보를 담는 메타 태그
• 검색 엔진 & SNS 공유 시 사용됨

대표적으로:

• title
• description
• og:image
• keywords

✅ 기본 사용법

import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: 'My Page',
  description: 'This is my page',
}

👉 layout.tsx 또는 page.tsx에서 선언 가능

✅ 주요 옵션

export const metadata: Metadata = {
  title: '페이지 제목',
  description: '페이지 설명',
  keywords: ['nextjs', 'seo'],
  openGraph: {
    title: 'OG 제목',
    description: 'OG 설명',
    images: ['/og-image.png'],
  },
}

✅ title 템플릿

export const metadata = {
  title: {
    default: 'Panzy',
    template: '%s | Panzy',
  },
}

👉 페이지별 title 자동 구성 가능

⚡ 2. 동적 메타데이터

✅ 왜 필요한가?

• 상품 상세 페이지
• 블로그 글
• 숙소 상세 페이지

👉 각각 다른 title/description 필요

✅ generateMetadata 사용

import type { Metadata } from 'next'

export async function generateMetadata({ params }): Promise<Metadata> {
  const data = await fetch(`https://api.example.com/${params.id}`).then(res => res.json())

  return {
    title: data.title,
    description: data.description,
  }
}

✅ 예시 (숙소 상세)

export async function generateMetadata({ params }) {
  const accommodation = await getAccommodation(params.id)

  return {
    title: accommodation.name,
    description: accommodation.description,
  }
}

⚠️ 주의사항

• 서버 컴포넌트에서만 사용 가능
• fetch는 캐싱 전략 고려 필요

🔍 3. SEO 최적화 전략

✅ 1. 메타데이터 최적화

• title: 핵심 키워드 포함
• description: 클릭 유도 문장
• 중복 제거 필수

✅ 2. Open Graph 설정

SNS 공유 최적화

openGraph: {
  title: '제목',
  description: '설명',
  images: ['/image.png'],
}

✅ 3. 구조화된 URL

❌ 나쁜 예

• /page?id=123

✅ 좋은 예

• /accommodation/123

✅ 4. SSR 활용

• 검색 엔진은 JS 실행 제한적
• 서버 렌더링이 SEO에 유리

✅ 5. 이미지 SEO

• alt 속성 필수
• next/image 사용 권장

<Image src=\"/image.png\" alt=\"숙소 이미지\" />

✅ 6. 사이트맵 & robots.txt

• sitemap.xml 생성
• robots.txt 설정

👉 검색 엔진 크롤링 최적화

✅ 7. 성능 최적화

• Core Web Vitals 중요
• LCP, CLS, TTI 개선 필요

👉 SEO 랭킹에 직접 영향

📌 한눈에 정리

Metadata

• title, description 설정
• Open Graph 포함

동적 메타데이터

• generateMetadata 사용
• 페이지별 SEO 대응

SEO 전략

• 키워드 최적화
• SSR 활용
• URL 구조 개선
• 성능 최적화

🚀 결론

Next.js에서는 Metadata API를 활용하면
SEO 설정을 매우 효율적으로 관리할 수 있다.

👉 핵심 요약

• 정적 페이지 → metadata 사용
• 동적 페이지 → generateMetadata 사용
• 전체 전략 → SEO + 성능 최적화

이 구조만 제대로 잡아도
검색 유입과 클릭률이 크게 개선된다.

Next.js는 기본적으로 다양한 성능 최적화 기능을 내장하고 있다.
특히 이미지, 폰트, 번들 크기 최적화는 실제 서비스에서 로딩 속도와 UX에 큰 영향을 준다.

이 글에서는 다음 3가지를 핵심으로 정리한다:

• next/image
• next/font
• 번들 최적화 개념

🖼 1. next/image (이미지 최적화)

✅ 왜 필요한가?

일반 <img> 태그를 사용하면 다음과 같은 문제가 발생한다:

• 이미지 크기가 크면 로딩 속도 저하
• 다양한 디바이스 대응 어려움
• lazy loading 직접 구현 필요

👉 next/image는 이 문제를 자동으로 해결해준다.

✅ 주요 기능

1. 자동 사이즈 최적화

• 디바이스 해상도에 맞는 이미지 제공
• 불필요하게 큰 이미지 다운로드 방지

2. Lazy Loading (지연 로딩)

• 화면에 보일 때만 이미지 로딩

3. WebP / AVIF 자동 변환

• 더 가벼운 이미지 포맷으로 자동 변환

4. CDN 기반 최적화

• 요청 시 최적화된 이미지 제공

✅ 기본 사용법

import Image from 'next/image'

<Image
  src="/example.png"
  alt="example"
  width={500}
  height={300}
/>

✅ 주요 옵션

● priority (LCP 최적화)

<Image src="/hero.png" priority />

👉 가장 먼저 보여야 하는 이미지에 사용

● fill (부모 요소 채우기)

<Image src="/image.png" fill style={{ objectFit: 'cover' }} />

● sizes (반응형 최적화)

sizes="(max-width: 768px) 100vw, 50vw"

⚠️ 주의사항

• width/height 또는 fill 반드시 필요
• 외부 이미지 사용 시 설정 필요

images: {
  domains: ['example.com'],
}

🔤 2. next/font (폰트 최적화)

✅ 왜 필요한가?

기존 웹폰트 사용 시 문제:

• FOUT (Flash of Unstyled Text)
• FOIT (Flash of Invisible Text)
• 렌더링 지연
• 외부 요청 증가

👉 next/font는 이를 해결한다.

✅ 주요 특징

1. 자동 서브셋

• 필요한 문자만 다운로드

2. Self-hosting

• 외부 서버 요청 없이 내부에서 제공

3. Layout Shift 방지

• CLS 개선

✅ 기본 사용법 (Google Font)

import { Inter } from 'next/font/google'

const inter = Inter({
  subsets: ['latin'],
})

export default function RootLayout({ children }) {
  return (
    <html className={inter.className}>
      <body>{children}</body>
    </html>
  )
}

✅ 로컬 폰트 사용

import localFont from 'next/font/local'

const myFont = localFont({
  src: './fonts/my-font.woff2',
})

⚠️ 주의사항

• 글로벌 layout에서 적용 권장
• 폰트 개수 최소화

📦 3. 번들 최적화 개념

✅ 번들이란?

• 브라우저에 전달되는 JavaScript 파일 묶음
• 번들 크기가 클수록 로딩 속도 저하

✅ 왜 중요한가?

• 초기 로딩 속도 개선
• TTI (Time To Interactive) 향상
• 사용자 이탈 감소

✅ 주요 전략

1. Code Splitting

import dynamic from 'next/dynamic'

const Component = dynamic(() => import('./Component'))

2. Dynamic Import

const HeavyComponent = dynamic(() => import('./HeavyComponent'), {
  ssr: false,
})

3. Tree Shaking

• 사용하지 않는 코드 제거
• ES Module 사용 시 자동 적용

4. 라이브러리 최적화

❌ 잘못된 예

import _ from 'lodash'

✅ 좋은 예

import debounce from 'lodash/debounce'

5. Bundle Analyzer

npm install @next/bundle-analyzer

const withBundleAnalyzer = require('@next/bundle-analyzer')({
  enabled: true,
})

module.exports = withBundleAnalyzer({})

👉 번들 크기 시각적으로 분석 가능

⚡ 추가 최적화 포인트

1. SSR vs CSR 선택

• SSR: 초기 렌더링 빠름 (SEO 유리)
• CSR: 인터랙션 빠름

👉 상황에 맞게 선택

2. 캐싱 전략

• 브라우저 캐시
• CDN 캐시

3. API 요청 최적화

• batching
• caching (SWR, React Query)

📌 한눈에 정리

next/image

• 자동 이미지 최적화
• lazy loading
• WebP 변환

next/font

• 폰트 최적화
• CLS 방지
• self-hosting

번들 최적화

• code splitting
• dynamic import
• tree shaking

🚀 결론

Next.js는 강력한 최적화 기능을 기본 제공하지만,
제대로 활용하지 않으면 성능 차이가 크게 난다.

👉 핵심 요약

• 이미지 → next/image
• 폰트 → next/font
• JS → 번들 최적화

이 3가지만 적용해도 체감 성능은 확실히 개선된다.

• "Middleware는 Edge Runtime에서 실행된다"

여기서 자연스럽게 이런 의문이 생긴다.

👉 Edge Runtime은 정확히 무엇이고, 언제 사용해야 할까?

이 글에서는 Edge Runtime의 개념과
Node.js Runtime과의 차이를 중심으로 정리한다.

1. Edge Runtime이란?

Edge Runtime은
👉 사용자와 가까운 위치(CDN)에서 코드를 실행하는 환경이다.

실행 구조 비교

[Node.js Runtime]
사용자 → 중앙 서버 → 응답

[Edge Runtime]
사용자 → 가까운 CDN 서버 → 응답

👉 요청을 더 가까운 위치에서 처리하여 네트워크 지연(Latency)을 줄이는 구조이다.

2. 왜 필요한가?

Edge Runtime의 목적은 응답 속도 개선이다.

장점

• 네트워크 지연 감소
• 초기 응답 속도 개선
• 글로벌 환경에서 일관된 성능 제공

👉 특히 요청 초기에 실행되는 로직에서 효과가 크다.

3. Next.js에서 Edge Runtime

Next.js에서는 일부 기능이 Edge Runtime에서 실행된다.

대표적인 기능

• Middleware
• Route Handler (옵션 설정 시)
• Edge API Routes

👉 Middleware는 기본적으로 Edge에서 실행된다.

4. Node.js Runtime과의 차이

두 환경은 역할이 명확히 다르다.

Node.js Runtime

• 서버 환경
• Node API 사용 가능 (fs, net 등)
• DB 접근 가능
• 복잡한 로직 처리에 적합

Edge Runtime

• CDN 기반 실행 환경
• 일부 API 제한
• 빠른 실행에 최적화
• 가벼운 로직 처리에 적합

👉 "무거운 처리 vs 빠른 분기 처리" 기준으로 구분하면 이해하기 쉽다.

5. Edge Runtime의 제한

Edge Runtime은 경량 환경이기 때문에 제약이 존재한다.

사용 불가능

• fs (파일 시스템)
• net, http
• 일부 Node.js 전용 라이브러리

👉 Node.js와 동일한 서버 환경이 아니다는 점이 핵심이다.

6. Edge Runtime에서 가능한 것

• fetch
• 쿠키 / 헤더 처리
• 인증 로직
• 리다이렉트
• 간단한 조건 분기

👉 요청 초기에 빠르게 판단하는 로직에 최적화된 환경이다.

7. 왜 Middleware는 Edge에서 실행될까?

Middleware는 요청이 들어오자마자 실행된다.

특징

• 모든 요청에서 실행됨
• 응답 지연 최소화가 중요
• 단순한 분기 로직 중심

이 특성 때문에
👉 지연을 최소화할 수 있는 Edge Runtime이 적합하다.

8. 언제 Edge Runtime을 사용해야 할까?

적합한 경우

• 인증 체크 (로그인 여부)
• 리다이렉트 처리
• 요청 필터링
• 로깅
• A/B 테스트

👉 공통점: 빠르게 판단하고 넘기는 로직

부적합한 경우

• DB 접근
• 복잡한 비즈니스 로직
• 무거운 연산

이런 경우는 Node.js Runtime이 더 적합하다.

9. 핵심 정리

• Edge Runtime은 CDN 환경에서 실행되는 경량 실행 환경
• 빠른 응답을 위해 설계됨
• Node.js보다 기능 제한이 존재
• Middleware는 기본적으로 Edge에서 실행됨
• 빠른 분기 처리가 필요한 로직에 적합

한 줄 정리

Edge Runtime은 사용자와 가까운 위치에서 실행되는 경량 환경으로,
요청 초기에 빠른 처리가 필요한 로직에 적합하다.

마무리

Next.js는 하나의 실행 환경만 사용하는 구조가 아니다.

• Edge Runtime → 요청 초기에 빠르게 처리
• Node.js Runtime → 복잡한 서버 로직 처리

👉 실행 위치와 역할을 기준으로 구분하면 각 기능을 언제 사용해야 하는지 명확해진다.

예를 들어:

• 로그인 여부 확인 (인증)
• 특정 페이지 접근 제한
• 요청 로깅
• 조건에 따른 리다이렉트

이런 로직을 페이지나 API마다 반복 구현하면 코드가 분산되고 관리가 어려워진다.

이때 사용하는 기능이 Middleware이다.

1. Middleware란?

Middleware는 요청이 라우트에 도달하기 전에 실행되는 함수이다.

👉 요청을 가로채서 사전에 처리할 수 있다.

실행 흐름

Request → Middleware → Route → Response

역할

• 인증 처리
• 리다이렉트
• 요청 검사
• 로깅

2. 기본 구조

Middleware는 프로젝트 루트에 middleware.ts로 작성한다.

예시

import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  return NextResponse.next();
}

핵심 포인트

• 모든 요청 전에 실행됨
• NextRequest, NextResponse 사용
• next() 호출 시 다음 단계로 전달

3. 실행 범위 (matcher)

기본적으로 모든 요청에 실행되므로
필요한 경로에만 적용하는 것이 중요하다.

예시

export const config = {
  matcher: ['/dashboard/:path*'],
};

👉 /dashboard 이하 경로에만 적용

4. 인증 처리 (Auth)

가장 많이 사용하는 패턴

예시

export function middleware(request: NextRequest) {
  const token = request.cookies.get('token');

  if (!token) {
    return NextResponse.redirect(new URL('/login', request.url));
  }

  return NextResponse.next();
}

포인트

• 쿠키 / 헤더 기반 인증
• 접근 제어 로직 중앙 관리

5. redirect vs rewrite

redirect

• URL 변경됨

return NextResponse.redirect(new URL('/login', request.url));

rewrite

• URL 유지, 내부 라우팅 변경

return NextResponse.rewrite(new URL('/home', request.url));

👉 redirect = 이동 / rewrite = 내부 매핑

6. 요청 가공 및 공통 처리

전역적으로 적용되는 공통 로직 처리 가능

예시

export function middleware(request: NextRequest) {
  const response = NextResponse.next();

  response.headers.set('x-custom-header', 'middleware');

  return response;
}

활용

• 공통 헤더
• 보안 설정
• 요청 추적
• A/B 테스트

7. Edge Runtime

Middleware는 Edge Runtime에서 실행된다.

👉 Edge Runtime = 사용자와 가까운 서버(CDN 위치)에서 코드를 실행하는 환경

특징

• 빠른 응답
• 사용자와 가까운 위치에서 실행
• 요청 초기에 처리

주의사항

• Node.js API 사용 불가
• DB 직접 접근 비추천
• 무거운 로직 부적합

👉 가벼운 분기 처리에 적합

8. 실행 순서

Next.js의 요청 처리 흐름은 다음과 같다.

Middleware → Route Handler / Page → Response

👉 Middleware는 항상 가장 먼저 실행된다.

즉, 실제 페이지나 API 로직이 실행되기 전에 요청을 선별하고 제어하는 역할을 담당한다.

9. 언제 사용해야 할까?

다음과 같은 "요청 이전 단계에서 처리해야 하는 로직"에 적합하다.

인증 / 권한 처리

• 로그인 여부 확인
• 관리자 페이지 접근 제한

리다이렉트

• 로그인 상태에 따른 페이지 이동
• 특정 조건에 따른 경로 변경

공통 로직 처리

• 요청 로깅
• A/B 테스트
• 트래픽 제어

👉 공통적으로 여러 페이지에서 반복되는 로직일수록 Middleware에 적합하다.

10. 사용하면 안 되는 경우

Middleware는 모든 요청마다 실행되기 때문에
👉 무거운 로직을 처리하기에는 적합하지 않다.

피해야 할 경우

• DB 접근
• 복잡한 비즈니스 로직
• 시간이 오래 걸리는 작업

👉 이런 로직은
Route Handler 또는 Server Action에서 처리하는 것이 적절하다.

11. 주의사항

정적 파일이나 내부 경로에도 Middleware가 실행될 수 있다.

예:

• /_next/*
• /favicon.ico

문제

불필요한 요청에도 Middleware가 실행되면서
👉 성능에 영향을 줄 수 있다.

해결

export const config = {
  matcher: ['/((?!_next|favicon.ico).*)'],
};

👉 필요한 경로에만 적용하도록 제한하는 것이 중요하다.

12. 핵심 정리

• 요청을 가로채는 사전 처리 레이어
• 인증, 리다이렉트, 로깅에 사용
• Edge Runtime에서 실행
• matcher로 범위 제어
• redirect / rewrite 구분 필요

한 줄 정리

Middleware는 요청 이전 단계에서 실행되어 인증, 리다이렉트 등 공통 로직을 처리하는 레이어이다.

마무리

Middleware는 요청이 실제 라우트에 도달하기 전에 실행되며,
Next.js의 서버 처리 흐름에서 가장 앞단에 위치한다.

Next.js에서는 서버 로직을 처리하는 방식이 나뉜다.

• 요청 이전 → Middleware
• API 처리 → Route Handlers
• UI 기반 변경 → Server Actions

👉 실행 위치를 기준으로 보면
각 기능의 역할과 사용 시점을 더 명확하게 구분할 수 있다.

• Route Handlers (API Routes)
• Server Actions

두 방식 모두 서버에서 실행되지만,
👉 사용 목적과 구조가 다르기 때문에 구분해서 이해하는 것이 중요하다.

이 글에서는 Route Handlers를 중심으로
👉 언제 사용하고, 어떻게 구성하는지에 초점을 맞춰 정리하려고 한다.

1. Route Handlers란?

Route Handlers는 App Router에서 사용하는 API 서버 기능이다.

기존 pages/api 방식 대신
👉 app/api/*/route.ts 구조를 사용한다.

기본 구조

// app/api/posts/route.ts
export async function GET() {
  return Response.json({ message: 'Hello World' });
}

2. 지원 메서드

Route Handlers는 HTTP 메서드별로 함수를 정의한다.

• GET
• POST
• PUT
• PATCH
• DELETE

예시

export async function POST(request: Request) {
  const body = await request.json();

  return Response.json({
    message: 'Post created',
    data: body,
  });
}

핵심 포인트

• 함수 이름 = HTTP Method
• Request 객체를 통해 데이터 접근
• Response로 결과 반환

3. 동작 방식

Route Handler는 요청이 들어올 때마다 실행되는
👉 서버 함수이다.

특징

• 기본적으로 서버에서 실행
• 클라이언트 / 서버 어디서든 호출 가능
• REST API 형태로 사용 가능

4. 데이터 처리 흐름

Client → API Route → DB → Response

예시

export async function POST(request: Request) {
  const data = await request.json();

  await db.post.create({
    data,
  });

  return Response.json({ success: true });
}

5. Route Handlers vs Server Actions

두 기능은 역할이 겹쳐 보이지만, 실제로는 용도가 다르다.

비교

정리

• Route Handlers → API 중심
• Server Actions → UI 중심

6. 언제 Route Handlers를 사용해야 할까?

외부에서 호출되는 API가 필요한 경우

• 모바일 앱
• 외부 서비스 연동
• Webhook 처리

REST API 구조가 필요한 경우

• CRUD API
• 인증 처리
• 파일 업로드

클라이언트와 서버를 분리해야 하는 경우

• 백엔드 로직을 독립적으로 관리할 때

7. 언제 Server Actions를 사용하는 것이 더 좋은가?

UI에서 직접 데이터 변경이 필요한 경우

<form action={createPost}>

간단한 Mutation

• 게시글 생성
• 댓글 작성
• 좋아요

핵심 차이

👉 Route Handler → API 중심
👉 Server Action → UI 중심

8. 캐싱과의 관계

Route Handlers에서도 캐싱 전략을 적용할 수 있다.

예시

export async function GET() {
  const data = await fetch('https://api.example.com', {
    next: { revalidate: 60 },
  });

  return Response.json(data);
}

핵심

• fetch 캐싱 전략 그대로 적용됨
• revalidate 사용 가능

추가 포인트

Route Handler 자체는 요청마다 실행되지만,
내부 fetch는 Next.js 캐싱 전략을 따른다.

필요한 경우 라우트 단위로 동적 처리도 가능하다.

export const dynamic = 'force-dynamic';

👉 항상 최신 데이터를 기준으로 동작

9. NextRequest / NextResponse

Route Handler에서는 기본 Request, Response 대신
Next.js에서 제공하는 확장 객체를 사용할 수 있다.

NextRequest

import { NextRequest } from 'next/server';

export async function GET(request: NextRequest) {
  const searchParams = request.nextUrl.searchParams;
  const id = searchParams.get('id');

  return Response.json({ id });
}

NextResponse

import { NextResponse } from 'next/server';

export async function GET() {
  return NextResponse.json({ message: 'Hello' });
}

핵심 포인트

• URL, 쿠키, 헤더 접근이 편리함
• Next.js 기능과 자연스럽게 연결됨

10. 핵심 정리

• Route Handlers는 App Router의 API 서버 기능
• app/api/*/route.ts 구조 사용
• HTTP Method 기반 함수 정의
• REST API 형태로 활용 가능
• NextRequest / NextResponse로 확장 기능 사용 가능
• fetch 캐싱 및 revalidate 전략 적용 가능

한 줄 정리

Route Handlers는 API 중심의 서버 로직을 구성하는 방식이며,
외부 요청 처리나 REST 구조가 필요한 경우에 적합하다.

마무리

Next.js App Router에서는 서버 로직을 처리하는 방식이 하나로 고정되어 있지 않다.

Route Handlers와 Server Actions는 모두 서버에서 실행되지만,
👉 어떤 방식으로 연결되는지에 따라 역할이 달라진다.

• 외부 요청이나 API 구조가 필요한 경우 → Route Handlers
• UI와 직접 연결된 데이터 변경 → Server Actions

이 기준으로 구분하면
상황에 맞는 구조를 더 명확하게 선택할 수 있다.

• "데이터를 바꿨는데 왜 화면이 그대로지?"
• "왜 어떤 요청은 다시 안 나가지?"
• "revalidate를 했는데 왜 안 바뀌지?"

이런 문제의 대부분은
👉 Next.js의 캐싱 구조를 정확히 이해하지 못해서 발생한다.

Next.js는 단순한 캐싱이 아니라,
여러 레이어의 캐싱이 동시에 동작하는 구조를 가지고 있다.

전체 캐싱 구조

Next.js의 캐싱은 크게 3가지 레이어로 나뉜다.

1. Request Memoization (요청 단위)
2. Data Cache (데이터 단위)
3. Full Route Cache (페이지 단위)

동작 흐름

[Request]
   ↓
[Request Memoization]
   ↓
[Data Cache]
   ↓
[Full Route Cache]

👉 이 구조를 이해하면 대부분의 캐싱 문제를 설명할 수 있다.

1. Request Memoization

개념

하나의 요청 사이클 내에서
같은 fetch 요청을 여러 번 보내지 않도록 하는 메커니즘

특징

• 서버 렌더링 중에만 적용
• 동일한 요청은 한 번만 실행됨
• 이후 요청은 결과 재사용

예시

await fetch('/api/data');
await fetch('/api/data'); // 실제로는 한 번만 요청됨

핵심 포인트

• 성능 최적화를 위한 내부 동작
• 개발자가 직접 제어하지 않음

👉 "왜 fetch를 두 번 했는데 한 번만 호출되지?"의 원인

2. Data Cache

개념

fetch 요청 결과를 캐싱하는 레이어

👉 Next.js에서는 기본적으로 fetch가 캐시된다

기본 동작

await fetch('/api/data'); // 기본적으로 캐싱됨

캐시 제어

1. revalidate (시간 기반)

await fetch('/api/data', {
  next: { revalidate: 60 },
});

• 60초 동안 캐시 유지
• 이후 요청 시 재검증

2. no-store (캐시 비활성화)

await fetch('/api/data', {
  cache: 'no-store',
});

• 항상 최신 데이터 요청

핵심 포인트

• Data Cache는 데이터 단위 캐싱
• 대부분의 캐싱 이슈는 여기서 발생

👉 기본값이 "캐시됨"이라는 점이 중요하다

3. Full Route Cache

개념

페이지 전체(HTML + 데이터)를 캐싱하는 레이어

👉 Static Rendering 시 자동 적용됨

특징

• 페이지 단위 캐싱
• 빌드 시 또는 첫 요청 시 생성
• 이후 동일 요청은 캐시된 결과 반환

라우트 옵션으로 제어

1. dynamic

export const dynamic = 'force-dynamic';

• 항상 서버에서 렌더링
• 캐싱 비활성화

2. revalidate

export const revalidate = 60;

• 60초마다 페이지 재생성

핵심 포인트

• Full Route Cache는 페이지 단위 캐싱
• Data Cache와 함께 동작함

👉 "페이지가 안 바뀌는 이유"는 대부분 이 레이어 때문

4. Revalidation 전략

데이터가 변경되었을 때
👉 캐시를 갱신하는 방법

1. revalidatePath

import { revalidatePath } from 'next/cache';

revalidatePath('/posts');

• 특정 페이지 캐시 무효화

2. revalidateTag

import { revalidateTag } from 'next/cache';

revalidateTag('posts');

• 태그 기반 캐시 무효화

언제 사용하나?

👉 Server Action 이후

'use server';

export async function createPost() {
  await db.post.create(...);

  revalidatePath('/posts');
}

핵심 포인트

• Mutation 이후 반드시 필요
• 안 하면 데이터는 바뀌었지만 UI는 그대로

5. 클라이언트 캐시와의 관계

Next.js 캐시는 서버 중심이지만,
클라이언트에서도 별도의 캐시 전략이 존재한다.

예시

• React Query
• SWR

차이점

👉 두 캐시는 경쟁 관계가 아니라 보완 관계

6. 언제 어떤 캐싱 전략을 써야 할까?

캐싱 구조를 이해하는 것도 중요하지만,
실제로는 상황에 따라 어떤 전략을 선택할지가 더 중요하다.

Next.js에서는 데이터의 성격에 따라 캐싱 방식을 다르게 가져가는 것이 일반적이다.

항상 최신 데이터가 필요한 경우

사용자 정보, 주문 상태처럼
요청마다 데이터가 달라질 수 있는 경우에는 캐싱을 사용하지 않는 것이 적절하다.

await fetch('/api/data', {
  cache: 'no-store',
});

또는

export const dynamic = 'force-dynamic';

이렇게 설정하면 요청마다 새로운 데이터를 기준으로 렌더링된다.

데이터가 거의 변하지 않는 경우

블로그 글, 정적 페이지처럼
데이터 변경이 거의 없는 경우에는 캐싱을 사용하는 것이 유리하다.

이 경우에는 별도의 설정 없이 기본 fetch를 사용해도
Next.js가 자동으로 캐싱을 적용한다.

일정 주기로 업데이트되는 경우

게시글 목록, 상품 리스트처럼
완전히 실시간일 필요는 없지만 일정 주기로 갱신되어야 하는 데이터는
revalidate를 사용하는 방식이 적절하다.

await fetch('/api/data', {
  next: { revalidate: 60 },
});

이 방식은 캐시된 데이터를 먼저 제공하고,
이후 백그라운드에서 최신 데이터를 반영한다.

데이터 변경(Mutation)이 발생하는 경우

데이터를 변경한 이후에는 기존 캐시가 유지되기 때문에
명시적으로 캐시를 갱신해줘야 한다.

revalidatePath('/posts');

또는

revalidateTag('posts');

이 과정을 통해 변경된 데이터가 화면에 반영된다.

캐싱 전략 선택

** 언제 무엇을 쓸까 **

• 항상 최신 데이터 → 캐시 사용하지 않음 (no-store)
• 거의 변하지 않는 데이터 → 캐싱 활용 (Static)
• 주기적으로 변하는 데이터 → revalidate 사용 (ISR)
• 데이터 변경 이후 → revalidatePath / revalidateTag

캐싱 구조 요약

** 무엇이 어떻게 동작할까 **

• Request Memoization: 동일 요청을 한 번만 실행하여 중복 fetch 방지
• Data Cache: fetch 결과를 캐싱하여 동일 데이터 요청 시 재사용
• Full Route Cache: 페이지 전체를 캐싱하여 빠른 응답 제공
• Revalidation: 변경된 데이터가 반영되도록 캐시를 갱신

마무리

Next.js의 캐싱은 각 데이터의 특성과 업데이트 방식에 따라
적절한 전략을 선택하는 것이 더 중요하다.

특히 Next.js는 여러 레이어의 캐싱이 함께 동작하기 때문에,
문제가 발생했을 때 "어느 레이어에서 캐시되고 있는지"를 먼저 파악하는 것이 중요하다.

👉 Next.js 13+에서 추가된 핵심 기능으로,
👉 클라이언트 → 서버 데이터 변경(Mutation)을 단순하게 처리할 수 있다.

기존에는 데이터 변경을 위해 API Route를 따로 만들어야 했지만,
Server Actions를 사용하면 컴포넌트에서 직접 서버 로직을 실행할 수 있다.

개념

Server Action은 서버에서 실행되는 함수로,
주로 데이터 생성 / 수정 / 삭제 (Mutation) 작업을 담당한다.

정리하면 다음과 같이 역할이 나뉜다.

• 데이터 조회 → Server Component / fetch
• 데이터 변경 → Server Action

👉 즉, Server Action은 Next.js에서 Mutation을 담당하는 표준 방식이라고 볼 수 있다.

왜 중요한가?

기존 방식:

1. 클라이언트에서 API 호출
2. API Route에서 로직 처리
3. 응답을 받아 상태 업데이트

Server Actions:

👉 API 없이 서버 함수 직접 실행

이 구조 덕분에

• API Route를 따로 만들지 않아도 되어 코드가 줄어들고
• 클라이언트 → 서버 → 클라이언트로 이어지던 흐름이 단순해지며
• 데이터 변경 로직을 한 곳에서 관리할 수 있다

👉 결과적으로, 구현해야 할 구조 자체가 단순해진다.

기본 사용법

1. 서버 액션 정의

'use server';

export async function createPost(formData: FormData) {
  const title = formData.get('title');

  await db.post.create({
    data: { title },
  });
}

2. form에서 바로 사용

import { createPost } from './actions';

export default function Page() {
  return (
    <form action={createPost}>
      <input name="title" />
      <button type="submit">Submit</button>
    </form>
  );
}

핵심 포인트

• form의 action에 함수 직접 연결
• 별도의 API endpoint 불필요
• 자동으로 서버에서 실행됨

👉 기존 fetch + API 구조보다 훨씬 직관적이다.

클라이언트 컴포넌트에서 사용

Client Component에서도 Server Action을 사용할 수 있다.

'use client';

import { createPost } from './actions';

export default function Button() {
  return (
    <button onClick={() => createPost()}>
      생성하기
    </button>
  );
}

주의할 점

• 브라우저 이벤트 → 서버 함수 호출 구조이기 때문에
• 네트워크 요청이 발생한다는 점을 고려해야 한다

👉 단순 함수 호출처럼 보여도 실제로는 서버 통신이다.

revalidate로 데이터 갱신

Mutation 이후에는 기존 데이터가 stale 상태가 되기 때문에
캐시를 갱신해야 한다.

'use server';

import { revalidatePath } from 'next/cache';

export async function createPost(formData: FormData) {
  await db.post.create({
    data: { title: formData.get('title') },
  });

  revalidatePath('/posts');
}

핵심 포인트

• Server Action + revalidate 조합이 중요
• 데이터 변경 후 UI 최신 상태 유지

👉 이걸 놓치면 "데이터는 바뀌었는데 화면은 안 바뀌는" 문제가 생긴다.

기존 방식 vs Server Actions

언제 사용하면 좋은가?

• form 기반 데이터 제출
• CRUD 작업
• 간단한 서버 로직 처리
• 빠르게 기능을 구현해야 하는 경우

한계 및 고려할 점

• 복잡한 비즈니스 로직은 여전히 분리하는 것이 좋다

• 서버 로직이 컴포넌트와 가까워지면서 구조가 섞일 수 있다
  → 규모가 커지면 레이어 분리가 필요하다

• 내부적으로는 네트워크 요청이 발생한다

👉 즉, Server Action은 편리하지만 모든 상황에서 사용하는 것이 아니라
단순한 Mutation이나 빠른 구현이 필요한 경우에 더 적합하다.

정리

• Server Action은 데이터 변경(Mutation)을 담당
• API Route 없이 서버 로직 실행 가능
• form과 자연스럽게 결합됨
• revalidate를 통해 데이터 최신화 필요

한 줄 정리

Server Action은 Next.js에서 데이터 변경(Mutation) 흐름을 단순화해주는 기능이며,
API 없이도 서버 로직을 직접 처리할 수 있게 해준다.

처음에는 단순한 보조 UI라고 생각했지만, 직접 적용해보면서
Streaming만으로는 UX가 완성되지 않고, fallback UI 설계가 반드시 필요하다는 점을 체감하게 되었다.

이 글에서는 다음 내용을 정리한다.

• loading.tsx
• error.tsx
• not-found.tsx
• Suspense 기반 로딩 처리
• Streaming과 UI fallback의 관계

1. loading.tsx

개념

loading.tsx는 해당 라우트(segment)가 로딩 중일 때 자동으로 보여지는 UI이다.

즉, 데이터 fetching 또는 서버 컴포넌트가 아직 준비되지 않았을 때
사용자에게 보여줄 fallback UI를 정의하는 역할을 한다.

특징

• 해당 폴더(라우트 segment)에 자동 적용
• 별도의 import 없이 Next.js가 자동 연결
• 내부적으로 Suspense fallback 역할 수행

예시

// app/posts/loading.tsx
export default function Loading() {
  return <p>Loading posts...</p>;
}

핵심 포인트

• 페이지 전환 시 깜빡임 없이 자연스러운 UX 제공
• Skeleton UI와 함께 사용하는 것이 일반적

👉 실제로 적용해보니 단순 텍스트보다 Skeleton UI가 훨씬 자연스럽게 느껴졌다.

2. error.tsx

개념

error.tsx는 해당 라우트에서 에러 발생 시 보여주는 UI이다.

React의 Error Boundary 기반으로 동작하며,
예상치 못한 에러 상황에서도 UI를 유지할 수 있게 해준다.

특징

• 반드시 클라이언트 컴포넌트 ('use client')
• reset() 함수를 통해 에러 복구 가능

예시

'use client';

export default function Error({ error, reset }: { error: Error; reset: () => void }) {
  return (
    <div>
      <h2>Something went wrong!</h2>
      <button onClick={() => reset()}>Try again</button>
    </div>
  );
}

핵심 포인트

• 에러 발생 시에도 UI가 깨지지 않음
• 사용자에게 재시도 기회 제공

👉 단순히 에러를 보여주는 것보다, 다시 시도할 수 있게 만드는 게 훨씬 중요하다고 느꼈다.

3. not-found.tsx

개념

not-found.tsx는 존재하지 않는 경로이거나
notFound()가 호출될 때 보여지는 UI이다.

특징

• 404 페이지를 라우트 단위로 정의 가능
• 서버 컴포넌트에서도 쉽게 트리거 가능

예시

// app/posts/not-found.tsx
export default function NotFound() {
  return <h2>Post Not Found</h2>;
}

// 사용 예시
import { notFound } from 'next/navigation';

export default async function Page({ params }) {
  const data = await fetchData(params.id);

  if (!data) {
    notFound();
  }

  return <div>{data.title}</div>;
}

핵심 포인트

• 페이지 단위가 아닌 segment 단위 404 처리
• SEO 및 UX 모두에 유리

👉 기존에는 전역 404만 생각했는데, 이렇게 나눌 수 있다는 점이 인상적이었다.

4. Suspense 기반 로딩 처리

개념

React의 Suspense를 활용하면
컴포넌트 단위로 로딩 상태를 제어할 수 있다.

예시

import { Suspense } from 'react';
import PostList from './PostList';

export default function Page() {
  return (
    <Suspense fallback={<p>Loading posts...</p>}>
      <PostList />
    </Suspense>
  );
}

핵심 포인트

• 페이지 전체가 아니라 부분 단위 로딩 처리 가능
• 느린 컴포넌트만 분리해서 UX 개선 가능

👉 loading.tsx만으로는 부족하고, Suspense를 같이 써야 세밀한 제어가 가능했다.

5. Streaming vs UI Fallback

Streaming이란?

서버에서 데이터를 모두 준비한 후 보내는 것이 아니라,
준비된 UI부터 점진적으로 클라이언트에 전달하는 방식이다.

직접 적용하면서 느낀 점

Streaming을 적용하면 페이지가 빠르게 보이긴 했지만,
실제로는 UX가 완전히 좋아졌다고 느껴지지는 않았다.

특히 아래와 같은 상황이 있었다.

문제점

• 어떤 부분이 아직 로딩 중인지 알기 어려움
• UI가 중간중간 늦게 나타나면서 흐름이 끊기는 느낌
• fallback 없이 콘텐츠가 갑자기 바뀌는 느낌

결론

👉 Streaming만으로는 부족하고,
👉 반드시 fallback UI와 같이 설계해야 한다.

즉,

• loading.tsx
• Suspense fallback

이 둘이 함께 있어야 자연스러운 UX가 만들어진다.

동작 흐름

[사용자 요청]
   ↓
[Streaming 시작]
   ↓
[Fallback UI 먼저 렌더링]
   ↓
[데이터 준비 완료]
   ↓
[실제 UI로 점진적 교체]

6. 핵심 정리

• loading.tsx → 자동 fallback UI
• error.tsx → Error Boundary
• not-found.tsx → 라우트 단위 404 처리
• Suspense → 컴포넌트 단위 로딩 제어
• Streaming → 성능 개선, UX 완성은 fallback이 담당

한 줄 정리

Streaming은 빠르게 보여주기 위한 것이고,
실제 사용자 경험은 fallback UI가 완성한다.

7. 실무에서 적용할 수 있는 포인트 정리

• loading.tsx에는 Skeleton UI를 사용하는 것이 좋다
• Suspense는 "느린 컴포넌트 기준"으로 분리하는 것이 효과적이다
• error.tsx에는 retry UX를 반드시 포함하는 것이 좋다
• not-found는 SEO까지 고려해서 설계해야 한다

마무리

이번 내용을 정리하면서 느낀 점은,
로딩과 에러 처리는 단순히 "예외 상황 처리"가 아니라
사용자 흐름을 끊지 않기 위한 설계 요소라는 것이다.

Next.js App Router는 이런 부분을 구조적으로 나눌 수 있게 해주기 때문에,
기능 구현뿐 아니라 UX까지 같이 고민하게 만드는 도구라고 느꼈다.

Next.js 13부터 도입된 App Router에서는 기존 Page Router와 달리
애플리케이션의 UI를 페이지가 아닌 Layout 중심으로 설계한다.

이 글에서는 다음 내용을 정리한다.

• layout.tsx
• template.tsx
• Nested Layout 구조
• 공통 UI 관리 방식
• 실제 렌더링 흐름과 동작 원리

1. layout.tsx

📌 개념

layout.tsx는 공통 UI를 정의하는 파일이다.
해당 경로 이하의 모든 페이지에서 공통으로 유지되는 UI를 담당한다.

예를 들어:

• Header
• Footer
• Sidebar
• Navigation

같은 요소들을 포함할 수 있다.

📌 기본 구조

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="ko">
      <body>
        <header>Header</header>
        {children}
        <footer>Footer</footer>
      </body>
    </html>
  );
}

📌 특징

• 페이지 이동 시 다시 렌더링되지 않음
• 상태(state)가 유지됨
• 공통 레이아웃을 효율적으로 관리 가능

📌 왜 다시 렌더링되지 않을까?

Next.js App Router에서는 layout이 React Tree에서 유지되기 때문이다.

즉,

• layout은 유지되고
• 내부의 page만 교체된다

👉 이 구조 덕분에:

• state 유지 가능
• 불필요한 렌더링 감소
• 성능 최적화

2. template.tsx

📌 개념

template.tsx는 layout.tsx와 구조는 비슷하지만
페이지 이동 시마다 새로 렌더링되는 레이아웃이다.

📌 왜 template가 필요할까?

layout은 유지되기 때문에 다음과 같은 문제가 있다:

• 애니메이션이 실행되지 않음
• 초기화 로직이 동작하지 않음

👉 그래서 등장한 것이 template.tsx

📌 차이점 (layout vs template)

📌 사용 예시

• 페이지 전환 애니메이션
• 진입 시마다 초기화가 필요한 UI
• 특정 페이지 진입 효과

3. children 구조와 렌더링 흐름 (핵심)

App Router는 children을 통해 계층 구조를 구성한다.

📌 구조

layout
  → template
    → page

또는 Nested 구조에서는:

Root Layout
  └ Dashboard Layout
       └ Template
            └ Page

📌 핵심 동작

• layout은 children을 감싼다
• 하위 layout도 children으로 계속 중첩된다
• 결국 트리 구조로 UI가 구성됨

4. Nested Layout 구조

📌 개념

Next.js는 폴더 구조를 기반으로
레이아웃을 계층적으로 중첩(Nested)해서 적용할 수 있다.

📌 예시 구조

app/
 ├─ layout.tsx
 ├─ page.tsx
 ├─ dashboard/
 │   ├─ layout.tsx
 │   └─ page.tsx

📌 동작 방식

• app/layout.tsx → 전체 공통 레이아웃
• dashboard/layout.tsx → dashboard 전용 레이아웃

👉 /dashboard 접근 시:

Root Layout
  └ Dashboard Layout
       └ Page

📌 장점

• 기능별 UI 분리
• 유지보수 용이
• 복잡한 UI 구조 관리 가능

5. 실제 렌더링 흐름 (중요)

📌 페이지 이동 시 동작

예: /home → /dashboard

1. 기존 layout 유지
2. 새로운 page만 교체
3. template이 있다면 새로 렌더링

📌 정리

• layout → 유지됨
• template → 새로 렌더링됨
• page → 교체됨

👉 이 구조가 Next.js 성능의 핵심

6. 공통 UI 관리 방식

📌 기존 방식 (Page Router)

• _app.tsx에서 공통 UI 관리
• 모든 페이지에 동일 적용

📌 App Router 방식

• layout.tsx를 활용하여
  경로별로 공통 UI를 분리 가능

📌 예시

전체 공통 UI

// app/layout.tsx
<header>Global Header</header>

특정 영역 전용 UI

// app/dashboard/layout.tsx
<aside>Dashboard Sidebar</aside>

📌 핵심 포인트

• UI를 "페이지"가 아닌 "구조" 기준으로 설계
• 필요한 곳에만 레이아웃 적용
• 불필요한 렌더링 감소

7. layout vs template 언제 사용할까?

📌 layout.tsx

• Header / Footer
• Sidebar
• 상태 유지가 필요한 UI
• 공통 구조

📌 template.tsx

• 페이지 전환 애니메이션
• 초기화가 필요한 UI
• 매번 새로 렌더링이 필요한 경우

📌 최종 정리

• layout.tsx → 공통 UI, 상태 유지, 재사용
• template.tsx → 매번 새로 렌더링, 초기화 목적
• Nested Layout → 구조 기반 UI 설계
• children → UI 트리 구성 핵심

👉 App Router의 핵심은
페이지가 아니라 Layout 중심으로 구조를 설계하는 것

웹팩 데브 서버(Webpack Dev Server)는 개발 과정에서 사용하는 개발용 서버로, 빌드 대상 파일이 변경되면 매번 웹팩 명령어를 다시 실행하지 않아도 코드 변경 후 저장 시 자동으로 빌드하고 브라우저를 새로고침하여 변경 내용을 바로 확인할 수 있게 해준다.

웹팩 데브 서버 실행 명령어

package.json의 scripts에 아래와 같이 작성하여 실행할 수 있다.

{
  "scripts": {
    "dev": "webpack serve",
    "build": "webpack"
  }
}

• npm run dev: 웹팩 데브 서버 실행
• npm run build: 일반 웹팩 빌드 실행

웹팩 데브 서버의 특징

웹팩 데브 서버는 일반 웹팩 빌드와 달리 개발 환경에 최적화된 기능을 제공한다.

1. 빌드 결과물을 메모리에 저장

• 일반 웹팩 빌드 → dist 같은 폴더에 파일 생성
• 웹팩 데브 서브 → 빌드 결과물을 메모리에 저장
• 따라서 실제 프로젝트 폴더에서는 빌드 파일을 확인할 수 없다.

2. 코드 변경 시 자동 빌드

• 소스 코드를 수정하고 저장하면 변경을 감지하여 자동으로 다시 빌드한다.
• 매번 웹팩 명령어를 실행할 필요가 없다.

3. 브라우저 자동 새로고침

• 빌드가 완료되면 브라우저가 자동으로 새로고침되어 변경된 결과를 바로 확인할 수 있다.

정리

웹팩 데브 서버는 개발 환경에서 사용하는 도구로 다음과 같은 특징이 있다.

• 코드 변경 시 자동 빌드
• 브라우저 자동 새로고침
• 빌드 결과물을 메모리에 저장
• 개발 속도 향상

따라서 개발 단계에서는 웹팩 데브 서버를 사용하고, 개발이 완료되면 webpack 명령어로 배포용 빌드 파일을 생성한다.