1. 프로젝트 초기 설정과 타입스크립트 환경 구성

모든 프로젝트의 시작은 견고한 초기 설정에서 비롯됩니다. Next.js와 TypeScript를 함께 사용하면 개발 초기 단계부터 타입 안정성을 확보하여 생산성을 크게 향상시킬 수 있습니다.

Next.js 프로젝트 생성

최신 Next.js 프로젝트는 create-next-app CLI 도구를 통해 쉽게 생성할 수 있습니다. TypeScript는 이제 기본 옵션으로 제공되므로 별도의 설정 없이 바로 시작할 수 있습니다.

npx create-next-app@latest

위 명령어를 실행하면 몇 가지 질문이 나타납니다.

• What is your project named? my-next-ts-app
• Would you like to use TypeScript? Yes
• Would you like to use ESLint? Yes
• Would you like to use Tailwind CSS? Yes (선택 사항이지만 추천)
• Would you like to use src/ directory? Yes (프로젝트 구조화를 위해 추천)
• Would you like to use App Router? Yes (최신 Next.js의 핵심 기능)

TypeScript 설정: tsconfig.json

프로젝트 생성 시 tsconfig.json 파일이 자동으로 생성됩니다. 이 파일은 TypeScript 컴파일러의 동작을 제어하는 중요한 설정 파일입니다. 주요 옵션들을 살펴보겠습니다.

• target: 컴파일될 JavaScript 버전을 지정합니다. ES5는 오래된 브라우저 호환성을 보장합니다.
• lib: 컴파일에 포함될 라이브러리 파일 목록입니다. DOM, DOM.Iterable, ESNext가 기본으로 포함됩니다.
• strict: 모든 엄격한 타입 체크 옵션을 활성화합니다 (true를 강력히 권장).
• noEmit: TypeScript가 JavaScript 파일을 생성하지 않도록 합니다. Next.js가 자체적으로 이 과정을 처리하기 때문입니다.
• esModuleInterop: CommonJS 모듈을 ES 모듈처럼 가져올 수 있게 해줍니다.
• jsx: JSX 코드 변환 방식을 지정합니다. preserve로 설정하면 Next.js가 처리합니다.
• paths: 모듈 경로에 대한 별칭(alias)을 설정할 수 있습니다. 예를 들어 @/*를 src/*로 매핑하여 절대 경로 임포트를 쉽게 만듭니다.

{
  "compilerOptions": {
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [
      {
        "name": "next"
      }
    ],
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

**경로 별칭(Path Alias)**을 사용하면 ../../../components/Button과 같은 복잡한 상대 경로 대신 @/components/Button처럼 깔끔하게 컴포넌트를 가져올 수 있어 가독성과 유지보수성이 크게 향상됩니다.