Next.js TypeScript 개발 환경 설정: 시작부터 배포까지 완벽 가이드

Next.js와 TypeScript 기반 프로젝트 개발 환경을 처음부터 완벽하게 설정하는 방법을 상세히 안내합니다. 필수 도구 설치부터 효율적인 개발 워크플로우 구축까지, 이 가이드로 당신의 프로젝트를 성공적으로 시작하세요.

새로운 웹 프로젝트를 시작할 때, 개발 환경 설정은 생각보다 많은 시간과 노력을 요구하는 과정입니다. 특히 Next.js와 TypeScript를 함께 사용하고자 한다면, 두 기술의 강점을 최대한 활용하면서도 효율적인 개발 워크플로우를 구축하는 것이 중요합니다. 단순히 프로젝트를 생성하는 것을 넘어, 코드의 품질을 높이고 개발 생산성을 극대화하기 위한 다양한 도구와 설정을 체계적으로 이해하고 적용해야 합니다.

혹시 이런 고민을 해보신 적이 있나요? "Next.js와 TypeScript를 사용하고 싶은데, 어떻게 시작해야 할지 막막해요." 또는 "프로젝트를 시작했는데, ESLint나 Prettier 같은 도구들을 어떻게 연동해야 할지 모르겠어요." 또 "복잡한 모듈 경로 때문에 코드 가독성이 떨어지는데, 더 좋은 방법이 없을까요?"

이 가이드는 이러한 문제들을 해결하고, Next.js와 TypeScript를 기반으로 하는 프로젝트의 개발 환경 설정을 처음부터 끝까지 완벽하게 안내합니다. 필수적인 준비물부터 프로젝트 생성, 그리고 ESLint, Prettier, Absolute Imports와 같은 핵심 개발 도구 설정까지, 실용적인 정보와 구체적인 예시를 통해 여러분의 프로젝트를 성공적으로 시작할 수 있도록 돕겠습니다.

📑 목차

• Next.js와 TypeScript, 왜 함께 사용해야 할까요?
• 개발 환경 설정을 위한 필수 준비물
• Node.js 및 패키지 매니저
• 통합 개발 환경 (IDE): VS Code
• 버전 관리 시스템: Git
• Next.js 프로젝트 생성 및 TypeScript 연동
• `create-next-app`으로 프로젝트 생성
• 초기 프로젝트 구조 탐색
• 주요 개발 도구 및 설정: ESLint, Prettier, Absolute Imports
• 일관된 코드 스타일을 위한 ESLint와 Prettier
• 모듈 경로 관리를 위한 Absolute Imports
• VS Code 개발 환경 최적화
• 추천 VS Code 확장 프로그램
• VS Code 설정: `settings.json`
• 프로젝트 시작 및 개발 워크플로우
• 기본 스크립트 실행
• 간단한 페이지 및 컴포넌트 생성 예시
• 테스팅 환경 구축 (선택 사항)
• 마무리하며: 안정적인 시작을 위한 조언

Image by Boskampi on Pixabay

Next.js와 TypeScript, 왜 함께 사용해야 할까요?

현대 웹 개발에서 Next.js는 React 기반의 애플리케이션 개발에 강력한 프레임워크로 자리 잡았습니다. 서버 사이드 렌더링(SSR), 정적 사이트 생성(SSG), API 라우트 등 다양한 기능을 내장하여 개발자가 웹 애플리케이션을 더 쉽고 효율적으로 구축할 수 있게 돕습니다. 반면 TypeScript는 JavaScript에 정적 타입 시스템을 추가하여 대규모 애플리케이션의 안정성과 유지보수성을 크게 향상시킵니다.

이 두 기술을 함께 사용하는 것은 단순한 시너지를 넘어, 견고하고 확장 가능한 웹 애플리케이션을 만들기 위한 최적의 조합으로 평가받습니다. 하지만 왜 이 조합이 그렇게 강력한지, 구체적으로 어떤 이점을 제공하는지 비교해볼 필요가 있습니다.

특징	Next.js의 강점	TypeScript의 강점
개발 생산성	파일 시스템 기반 라우팅, 내장 이미지 최적화, 데이터 페칭 방식(SSR, SSG, ISR) 지원으로 개발 시간 단축.	자동 완성, 오타 방지, 리팩토링 용이성으로 개발 속도 및 효율 증대.
코드 안정성	React 생태계의 견고함 위에 구축되어 안정적인 개발 환경 제공.	컴파일 시점 오류 검출, 런타임 오류 감소, 명시적인 타입 정의로 코드의 신뢰성 향상.
유지보수성	모듈화된 구조, API 라우트 분리 등으로 대규모 프로젝트 관리 용이.	타입 정보가 문서 역할을 하여 코드 이해도 증진, 협업 시 의사소통 비용 절감.
성능 최적화	자동 코드 스플리팅, 이미지 최적화, 빠른 새로고침 등으로 사용자 경험 및 개발자 경험 향상.	타입 체크는 런타임 성능에 직접적인 영향은 없지만, 개발 단계에서 버그를 줄여 결과적으로 더 안정적인 애플리케이션을 만듦.

결론적으로, Next.js는 애플리케이션의 뼈대와 성능 최적화를 담당하고, TypeScript는 그 뼈대 안의 코드를 더욱 견고하고 유지보수하기 쉽게 만듭니다. 이 두 기술의 결합은 개발자가 더 자신감 있고 효율적으로 고품질의 웹 애플리케이션을 구축할 수 있는 기반을 제공합니다.

개발 환경 설정을 위한 필수 준비물

본격적인 Next.js와 TypeScript 프로젝트 시작에 앞서, 몇 가지 필수 도구들을 설치해야 합니다. 이 도구들은 개발 환경의 핵심 구성 요소이며, 대부분의 웹 개발 프로젝트에서 공통적으로 사용됩니다.

Node.js 및 패키지 매니저

Next.js는 Node.js 런타임 위에서 동작합니다. 따라서 가장 먼저 Node.js를 설치해야 합니다. Node.js는 npm(Node Package Manager)을 기본으로 포함하고 있으며, 이는 프로젝트에 필요한 라이브러리를 설치하고 관리하는 데 사용됩니다. Node.js의 LTS(Long Term Support) 버전을 설치하는 것을 권장합니다. LTS 버전은 장기적인 안정성과 지원을 보장하여 예상치 못한 문제를 줄일 수 있습니다.

• Node.js 설치: Node.js 공식 웹사이트에서 운영체제에 맞는 LTS 버전을 다운로드하여 설치합니다.
• 설치 확인: 설치 후 터미널(또는 명령 프롬프트)에서 다음 명령어를 실행하여 Node.js와 npm이 제대로 설치되었는지 확인합니다.

node -v
npm -v

npm 외에 Yarn이나 pnpm과 같은 다른 패키지 매니저를 선호할 수도 있습니다. 이 가이드에서는 npm을 기준으로 설명하지만, 어떤 패키지 매니저를 사용하든 기본적인 명령어만 다르므로 어렵지 않게 적용할 수 있습니다.

통합 개발 환경 (IDE): VS Code

코드 작성 및 개발을 위한 IDE(Integrated Development Environment)는 필수적입니다. 많은 개발자들이 VS Code를 선호하며, Next.js와 TypeScript 개발에 최적화된 다양한 확장 프로그램과 기능을 제공합니다. VS Code는 가볍고 빠르며, 강력한 TypeScript 지원 기능을 내장하고 있어 개발 생산성을 크게 높여줍니다.

• VS Code 설치: VS Code 공식 웹사이트에서 다운로드하여 설치합니다.

버전 관리 시스템: Git

프로젝트의 코드 변경 이력을 관리하고 여러 개발자와 협업하기 위해 Git은 필수적인 도구입니다. Git은 분산 버전 관리 시스템으로, 코드의 안정적인 관리와 효율적인 협업을 가능하게 합니다.

• Git 설치: Git 공식 웹사이트에서 운영체제에 맞는 버전을 다운로드하여 설치합니다.
• 설치 확인: 설치 후 터미널에서 다음 명령어를 실행하여 Git이 제대로 설치되었는지 확인합니다.

git --version

이 세 가지 필수 준비물이 갖춰졌다면, 이제 Next.js와 TypeScript 기반의 프로젝트를 생성할 준비가 완료된 것입니다.

Next.js 프로젝트 생성 및 TypeScript 연동

필수 준비물을 모두 갖췄다면, 이제 Next.js 프로젝트를 생성하고 TypeScript를 연동할 차례입니다. Next.js는 프로젝트 생성을 위한 매우 편리한 CLI 도구인 `create-next-app`을 제공합니다. 이 도구를 사용하면 TypeScript를 포함하여 기본적인 개발 환경을 쉽게 설정할 수 있습니다.

`create-next-app`으로 프로젝트 생성

터미널을 열고, 프로젝트를 생성하고자 하는 디렉토리로 이동한 후 다음 명령어를 실행합니다.

npx create-next-app@latest my-nextjs-ts-app

여기서 `my-nextjs-ts-app`은 여러분이 만들 프로젝트의 이름입니다. 이 명령어를 실행하면 몇 가지 설정 질문이 나옵니다. TypeScript 기반의 프로젝트를 위해 다음과 같이 선택하는 것을 권장합니다.

• Would you like to use TypeScript? `Yes` (TypeScript 사용을 위해 반드시 `Yes`를 선택합니다.)
• Would you like to use ESLint? `Yes` (코드 품질 유지를 위해 `Yes`를 선택합니다.)
• Would you like to use Tailwind CSS? `No` (또는 `Yes`, 필요에 따라 선택합니다. 이 가이드에서는 기본 설정을 위해 `No`를 가정합니다.)
• Would you like to use `src/` directory? `Yes` (프로젝트 구조를 좀 더 깔끔하게 관리하기 위해 `Yes`를 선택하는 것을 권장합니다.)
• Would you like to use App Router? (recommended) `Yes` (최신 Next.js의 App Router를 사용하는 것을 권장합니다.)
• Would you like to customize the default import alias? `No` (또는 `Yes`, 기본값인 `@/*`를 사용하는 것이 편리합니다. 이 가이드에서는 `No`를 가정합니다.)

모든 질문에 답하고 나면, `create-next-app`이 필요한 패키지를 설치하고 프로젝트 구조를 생성합니다. 이 과정은 잠시 시간이 소요될 수 있습니다.

초기 프로젝트 구조 탐색

프로젝트 생성이 완료되면, 다음과 같은 기본적인 디렉토리 구조를 확인할 수 있습니다.

my-nextjs-ts-app/
├── node_modules/
├── public/
├── src/
│   ├── app/
│   │   ├── favicon.ico
│   │   ├── globals.css
│   │   ├── layout.tsx
│   │   └── page.tsx
│   └── lib/ (선택 사항, 유틸리티 함수 등)
├── .eslintrc.json
├── .gitignore
├── next-env.d.ts
├── next.config.js
├── package.json
├── postcss.config.js
├── README.md
├── tailwind.config.ts (Tailwind CSS를 선택한 경우)
└── tsconfig.json

여기서 몇 가지 중요한 파일들을 살펴보겠습니다.

• `src/app/`: App Router 기반의 페이지와 레이아웃 컴포넌트들이 위치하는 핵심 디렉토리입니다. `page.tsx`는 각 라우트의 UI를 정의하고, `layout.tsx`는 해당 라우트의 공유 UI를 정의합니다.
• `next-env.d.ts`: Next.js 환경을 위한 TypeScript 타입 정의 파일입니다. 이 파일은 수정하지 않는 것이 좋습니다.
• `tsconfig.json`: TypeScript 컴파일러 설정 파일입니다. `create-next-app`이 기본 설정을 해두었지만, 필요에 따라 수정할 수 있습니다. TypeScript가 프로젝트의 `.ts`, `.tsx` 파일을 어떻게 해석하고 컴파일할지 정의합니다.
• `.eslintrc.json`: ESLint 설정 파일입니다. 코드 품질과 스타일 규칙을 정의합니다.
• `package.json`: 프로젝트의 메타데이터, 의존성(dependencies), 개발 의존성(devDependencies), 그리고 스크립트(scripts)를 정의합니다.

이제 프로젝트 디렉토리로 이동하여 개발 서버를 실행해봅니다.

cd my-nextjs-ts-app
npm run dev

성공적으로 실행되었다면, 브라우저에서 `http://localhost:3000`으로 접속하여 Next.js 개발 서버가 제공하는 기본 페이지를 확인할 수 있습니다. 이제 Next.js와 TypeScript가 연동된 기본적인 개발 환경 설정이 완료되었습니다.

Image by jamesmarkosborne on Pixabay

주요 개발 도구 및 설정: ESLint, Prettier, Absolute Imports

프로젝트 생성이 완료되었다면, 이제 코드의 품질을 높이고 개발 효율성을 극대화하기 위한 도구들을 설정할 차례입니다. ESLint와 Prettier는 코드 스타일을 일관되게 유지하고 잠재적인 오류를 미리 방지하는 데 필수적이며, Absolute Imports는 모듈 경로를 깔끔하게 관리하여 코드 가독성을 향상시킵니다.

일관된 코드 스타일을 위한 ESLint와 Prettier

개발 프로젝트에서 여러 개발자가 함께 작업하거나, 시간이 지나면서 코드의 양이 많아질수록 코드 스타일의 일관성을 유지하는 것은 매우 중요합니다. 일관성 없는 코드는 가독성을 해치고, 잠재적인 버그를 유발하며, 유지보수 비용을 증가시킵니다. 이러한 문제를 해결하기 위해 ESLint와 Prettier를 함께 사용하는 것이 일반적입니다.

• ESLint: 코드에서 잠재적인 오류나 스타일 위반을 찾아내 경고하거나 오류를 발생시키는 린터(Linter)입니다. Next.js는 `create-next-app`으로 프로젝트 생성 시 ESLint를 기본으로 포함하여 설정해줍니다.
• Prettier: 정해진 규칙에 따라 코드의 포맷을 자동으로 정리해주는 코드 포맷터(Code Formatter)입니다. 들여쓰기, 따옴표 사용, 세미콜론 여부 등을 일관되게 만들어줍니다.

Prettier 설치 및 설정

ESLint는 이미 설치되어 있지만, Prettier는 별도로 설치하고 ESLint와 연동해야 합니다. 프로젝트 루트 디렉토리에서 다음 명령어를 실행하여 Prettier와 ESLint와의 충돌을 방지하는 플러그인들을 설치합니다.

npm install -D prettier eslint-config-prettier eslint-plugin-prettier

• `prettier`: 코드 포맷터 본체
• `eslint-config-prettier`: Prettier와 충돌하는 ESLint 규칙을 비활성화하여 Prettier가 단독으로 코드 포맷을 담당하게 합니다.
• `eslint-plugin-prettier`: Prettier 규칙을 ESLint 규칙으로 추가하여, ESLint가 Prettier 규칙 위반을 린팅 오류로 보고하게 합니다.

설치 후, `package.json` 파일의 `devDependencies` 섹션에 위 패키지들이 추가된 것을 확인할 수 있습니다.

이제 ESLint 설정을 수정하여 Prettier를 연동합니다. 프로젝트 루트의 `.eslintrc.json` 파일을 열어 `extends` 배열에 `plugin:prettier/recommended`를 추가합니다. 이 항목은 항상 배열의 마지막에 위치해야 다른 ESLint 규칙들을 덮어쓰지 않고 Prettier 규칙을 적용할 수 있습니다.

// .eslintrc.json
{
  "extends": [
    "next/core-web-vitals",
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:prettier/recommended" // 이 부분을 추가합니다. 항상 마지막에 위치해야 합니다.
  ],
  "rules": {
    // 여기에 개별 ESLint 규칙을 추가하거나 재정의할 수 있습니다.
    // 예: "no-unused-vars": "warn",
    // "prettier/prettier": ["error", { "endOfLine": "auto" }] // Prettier 규칙을 ESLint 오류로 설정
  }
}

Prettier의 세부 설정을 위해 `.prettierrc.json` 파일을 프로젝트 루트에 생성합니다. 이 파일은 Prettier가 코드를 포맷할 때 사용할 규칙들을 정의합니다. 예를 들어:

// .prettierrc.json
{
  "semi": true,          // 세미콜론 사용 여부 (true: 사용, false: 사용 안 함)
  "singleQuote": true,   // 작은따옴표 사용 여부 (true: 작은따옴표, false: 큰따옴표)
  "tabWidth": 2,         // 탭 너비
  "trailingComma": "all",// 객체나 배열의 마지막 요소 뒤에 쉼표를 항상 추가
  "printWidth": 80,      // 한 줄 최대 길이
  "arrowParens": "always" // 화살표 함수의 매개변수에 항상 괄호 사용
}

이제 VS Code와 같은 IDE에서 파일을 저장할 때마다 Prettier가 자동으로 코드를 포맷하고, ESLint가 설정된 규칙에 따라 코드 품질을 검사하게 됩니다. 만약 자동 포맷이 동작하지 않는다면, VS Code 설정에서 `Editor: Format On Save` 옵션을 활성화해야 합니다.

모듈 경로 관리를 위한 Absolute Imports

프로젝트가 커질수록 컴포넌트나 유틸리티 파일의 경로가 깊어지는 경우가 많습니다. 이때 `../../components/Button`과 같이 상대 경로를 사용하면 경로가 복잡해지고 가독성이 떨어지며, 파일을 이동할 때마다 경로를 수정해야 하는 번거로움이 발생합니다.

이러한 문제를 해결하기 위해 Absolute Imports(절대 경로 임포트)를 사용하는 것이 좋습니다. Next.js는 `create-next-app` 생성 시 `@/*`와 같은 기본 절대 경로 별칭을 설정할 수 있는 옵션을 제공합니다. 만약 이때 `Yes`를 선택했다면, 이미 `tsconfig.json` 파일에 설정이 되어 있을 것입니다.

만약 설정되어 있지 않거나, 다른 별칭을 사용하고 싶다면 `tsconfig.json` 파일을 직접 수정하여 `paths` 옵션을 추가합니다.

// tsconfig.json
{
  "compilerOptions": {
    "target": "es5",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [
      {
        "name": "next"
      }
    ],
    "paths": {
      "@/*": ["./src/*"] // src 디렉토리의 모든 파일에 대해 @/ 별칭을 사용합니다.
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

위 설정에서 `"@/*": ["./src/*"]`는 `@/`로 시작하는 모든 경로를 `src/` 디렉토리 아래에서 찾으라는 의미입니다. 예를 들어, `src/components/Button.tsx` 파일은 다음과 같이 임포트할 수 있습니다.

// 상대 경로 (불편함)
import Button from '../../components/Button';

// 절대 경로 (깔끔하고 편리함)
import Button from '@/components/Button';

이 설정은 TypeScript 컴파일러가 경로를 인식하게 할 뿐만 아니라, VS Code와 같은 IDE에서도 자동 완성 기능을 제공하여 개발 편의성을 크게 향상시킵니다.

VS Code 개발 환경 최적화

VS Code는 Next.js와 TypeScript 개발에 최적화된 IDE입니다. 다양한 확장 프로그램과 설정으로 개발 환경을 더욱 편리하고 효율적으로 만들 수 있습니다. 다음은 추천하는 확장 프로그램과 VS Code 설정 팁입니다.

추천 VS Code 확장 프로그램

VS Code의 확장 프로그램 마켓플레이스에서 다음 확장 프로그램들을 검색하여 설치하는 것을 권장합니다.

• ESLint: ESLint의 린팅 결과를 VS Code 내에서 직접 보여주고, 문제가 있는 코드를 강조하여 즉시 수정할 수 있도록 돕습니다.
• Prettier - Code formatter: Prettier를 VS Code에 통합하여 파일을 저장할 때 자동으로 코드를 포맷팅하거나, 단축키로 포맷팅할 수 있게 합니다.
• TypeScript and JavaScript Language Features (기본 내장): TypeScript와 JavaScript를 위한 강력한 언어 지원 기능을 제공합니다.
• Path Intellisense: 파일 경로를 입력할 때 자동 완성을 제공하여 오타를 줄이고 작업 속도를 높입니다. Absolute Imports와 함께 사용하면 더욱 편리합니다.
• Tailwind CSS Intellisense (Tailwind CSS를 사용하는 경우): Tailwind CSS 클래스 이름을 자동 완성하고, CSS 정의를 표시하여 생산성을 높입니다.
• GitLens — Git supercharged: Git 기능을 시각적으로 향상시켜 코드의 변경 이력, 작성자 등을 쉽게 확인할 수 있습니다.
• React Refactor: React 컴포넌트를 리팩토링할 때 유용한 기능을 제공합니다.

VS Code 설정: `settings.json`

VS Code의 `settings.json` 파일을 수정하여 개발 환경을 개인화할 수 있습니다. 특히 `formatOnSave`와 같은 설정은 개발 워크플로우를 크게 개선합니다.

VS Code에서 `Ctrl + Shift + P` (또는 `Cmd + Shift + P`)를 눌러 명령 팔레트를 연 후, "Preferences: Open User Settings (JSON)"을 검색하여 `settings.json` 파일을 엽니다. 또는 "Preferences: Open Workspace Settings (JSON)"을 선택하여 현재 프로젝트에만 적용되는 설정을 할 수도 있습니다.

// settings.json (일부 예시)
{
  "editor.formatOnSave": true, // 파일 저장 시 자동 포맷팅 활성화
  "editor.defaultFormatter": "esbenp.prettier-vscode", // 기본 포맷터로 Prettier 설정
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit" // 저장 시 ESLint 자동 수정 활성화
  },
  "eslint.validate": [ // ESLint가 검사할 파일 타입 지정
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact"
  ],
  "typescript.tsdk": "node_modules/typescript/lib", // 워크스페이스의 TypeScript 버전 사용
  "files.autoSave": "afterDelay" // 일정 시간 후 자동 저장
}

• `"editor.formatOnSave": true`: 이 설정은 파일을 저장할 때마다 Prettier가 코드를 자동으로 포맷하도록 합니다. 이는 ESLint와 Prettier를 함께 사용할 때 매우 유용합니다.
• `"editor.defaultFormatter": "esbenp.prettier-vscode"`: VS Code의 기본 포맷터를 Prettier 확장 프로그램으로 지정합니다.
• `"editor.codeActionsOnSave": { "source.fixAll.eslint": "explicit" }`: 파일을 저장할 때 ESLint가 자동으로 수정할 수 있는 문제(예: 불필요한 세미콜론 제거)를 해결하도록 합니다.
• `"typescript.tsdk": "node_modules/typescript/lib"`: 특정 워크스페이스에서 로컬에 설치된 TypeScript 버전을 사용하도록 설정하여, 프로젝트별 TypeScript 버전을 일관되게 유지할 수 있습니다.

이러한 설정들을 통해 VS Code는 Next.js와 TypeScript 개발을 위한 강력하고 편리한 도구로 거듭나게 될 것입니다. 코드 작성에 더 집중하고, 반복적인 작업이나 사소한 오류로 인한 시간을 절약할 수 있습니다.

Image by fancycrave1 on Pixabay

프로젝트 시작 및 개발 워크플로우

이제 Next.js와 TypeScript 기반의 개발 환경 설정이 완료되었습니다. 이 섹션에서는 프로젝트의 기본적인 실행 방법과 함께, 효율적인 개발 워크플로우를 위한 몇 가지 팁을 제공합니다.

기본 스크립트 실행

`package.json` 파일에는 Next.js 프로젝트를 개발하고 빌드하며 실행하는 데 필요한 스크립트가 정의되어 있습니다.

// package.json (scripts 부분)
{
  "name": "my-nextjs-ts-app",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  },
  // ...
}

• `npm run dev`: 개발 서버를 시작합니다. 코드를 수정하면 자동으로 새로고침되며, 개발 중인 애플리케이션을 브라우저에서 확인할 수 있습니다. 일반적으로 `http://localhost:3000`에서 실행됩니다.
• `npm run build`: 프로덕션 배포를 위한 애플리케이션을 빌드합니다. 이 과정에서 TypeScript 코드가 JavaScript로 컴파일되고, Next.js가 페이지를 최적화하여 정적 파일이나 서버 번들을 생성합니다.
• `npm run start`: `npm run build`로 빌드된 프로덕션 애플리케이션을 실행합니다. 실제 서비스 환경에서 사용될 애플리케이션을 테스트할 때 유용합니다.
• `npm run lint`: ESLint를 실행하여 코드의 잠재적인 문제나 스타일 가이드 위반을 검사합니다. 주기적으로 실행하여 코드 품질을 유지하는 것이 좋습니다.

간단한 페이지 및 컴포넌트 생성 예시

Next.js App Router에서는 `src/app` 디렉토리 안에 파일 시스템 기반으로 라우팅이 이루어집니다. 예를 들어, `src/app/about/page.tsx` 파일을 생성하면 `http://localhost:3000/about` 경로로 접근할 수 있는 페이지가 만들어집니다.

새로운 페이지 생성 (`src/app/about/page.tsx`)

// src/app/about/page.tsx
import React from 'react';

const AboutPage: React.FC = () => {
  return (
    <div>
      <h1>About Us</h1>
      <p>이것은 Next.js와 TypeScript로 만들어진 About 페이지입니다.</p>
      <p>현재 프로젝트는 안정적인 개발 환경에서 실행 중입니다.</p>
    </div>
  );
};

export default AboutPage;

컴포넌트 생성 (`src/components/Button.tsx`)

`src/components` 디렉토리를 생성하고, 재사용 가능한 버튼 컴포넌트를 만들어보겠습니다. TypeScript를 사용하므로 컴포넌트의 props에 타입을 정의하여 안정성을 높입니다.

// src/components/Button.tsx
import React from 'react';

interface ButtonProps {
  children: React.ReactNode;
  onClick: () => void;
  variant?: 'primary' | 'secondary'; // 버튼 스타일 변형
}

const Button: React.FC<ButtonProps> = ({ children, onClick, variant = 'primary' }) => {
  const baseStyle = "px-4 py-2 rounded-md font-semibold text-white";
  const primaryStyle = "bg-blue-600 hover:bg-blue-700";
  const secondaryStyle = "bg-gray-600 hover:bg-gray-700";

  const style = variant === 'primary' ? primaryStyle : secondaryStyle;

  return (
    <button className={`${baseStyle} ${style}`} onClick={onClick}>
      {children}
    </button>
  );
};

export default Button;

생성된 컴포넌트를 페이지에서 사용 (`src/app/page.tsx`)

기존 `src/app/page.tsx` 파일에서 위에서 만든 `Button` 컴포넌트를 절대 경로로 임포트하여 사용해봅니다.

// src/app/page.tsx
import Button from '@/components/Button'; // Absolute Imports 사용

export default function Home() {
  const handleClick = () => {
    alert('버튼이 클릭되었습니다!');
  };

  return (
    <main className="flex min-h-screen flex-col items-center justify-between p-24">
      <div className="z-10 w-full max-w-5xl items-center justify-between font-mono text-sm lg:flex">
        <p className="fixed left-0 top-0 flex w-full justify-center border-b border-gray-300 bg-gradient-to-b from-zinc-200 pb-6 pt-8 backdrop-blur-2xl dark:border-neutral-800 dark:bg-zinc-800/30 dark:from-inherit lg:static lg:w-auto  lg:rounded-xl lg:border lg:bg-gray-200 lg:p-4 lg:dark:bg-zinc-800/30">
          Next.js와 TypeScript 개발 환경 설정 완료!
        </p>
      </div>

      <div className="relative z-[-1] flex place-items-center before:absolute before:h-[300px] before:w-full before:-translate-x-1/2 before:rounded-full before:bg-gradient-radial before:from-white before:to-transparent before:blur-2xl before:content-[''] after:absolute after:-z-20 after:h-[180px] after:w-full after:translate-x-1/3 after:bg-gradient-conic after:from-sky-200 after:via-blue-200 after:blur-2xl after:content-[''] before:dark:bg-gradient-to-br before:dark:from-transparent before:dark:to-blue-700 before:dark:opacity-10 after:dark:from-sky-900 after:dark:via-[#0141ff] after:dark:opacity-40 sm:before:w-[480px] sm:after:w-[240px] before:lg:h-[360px]">
        <h1 className="text-4xl font-bold">Hello Next.js & TypeScript!</h1>
      </div>

      <div className="mb-32 grid text-center lg:mb-0 lg:w-full lg:max-w-5xl lg:grid-cols-4 lg:text-left">
        <Button onClick={handleClick} variant="primary">
          클릭하세요!
        </Button>
        <Button onClick={() => alert('세컨더리 버튼')} variant="secondary">
          보조 버튼
        </Button>
      </div>
    </main>
  );
}

이렇게 페이지와 컴포넌트를 생성하고 나면, TypeScript의 타입 체크 기능 덕분에 개발 과정에서 발생할 수 있는 잠재적인 오류들을 미리 감지하고 수정할 수 있습니다. 예를 들어, `Button` 컴포넌트에 `onClick` prop을 전달하지 않으면 TypeScript 컴파일러가 오류를 보고할 것입니다. 또한 ESLint와 Prettier는 코드 스타일을 자동으로 정리하여 일관된 코드 품질을 유지해줍니다.

테스팅 환경 구축 (선택 사항)

대규모 프로젝트에서는 테스팅 환경을 구축하여 코드의 신뢰성을 더욱 높이는 것이 중요합니다. Next.js 프로젝트에서는 주로 Jest와 React Testing Library를 조합하여 유닛 및 통합 테스트를 수행합니다. `create-next-app`은 기본적으로 테스팅 라이브러리를 포함하지 않으므로, 필요에 따라 별도로 설치하고 설정해야 합니다.

npm install -D jest @types/jest jest-environment-jsdom @testing-library/react @testing-library/jest-dom

이후 `jest.config.js`와 같은 설정 파일을 생성하여 테스트 환경을 구성할 수 있습니다. 테스팅은 개발 워크플로우에서 중요한 부분이지만, 이 가이드의 범위를 넘어서므로 여기서는 간략히 언급만 합니다.

이러한 워크플로우를 통해 개발자는 코드를 작성하고, 실시간으로 변경 사항을 확인하며, TypeScript의 타입 시스템으로 오류를 줄이고, ESLint와 Prettier로 코드 품질을 유지할 수 있습니다. 이는 안정적이고 효율적인 Next.js + TypeScript 개발의 핵심입니다.

마무리하며: 안정적인 시작을 위한 조언

지금까지 Next.js와 TypeScript 기반 프로젝트의 개발 환경 설정을 위한 모든 과정을 상세히 살펴보았습니다. 필수 준비물부터 프로젝트 생성, ESLint, Prettier, Absolute Imports와 같은 핵심 개발 도구 설정, 그리고 VS Code 최적화와 기본적인 개발 워크플로우까지, 견고하고 효율적인 개발 환경을 구축하기 위한 여정이었습니다.

이 가이드를 통해 여러분은 다음을 얻을 수 있습니다:

• 강력한 기반: Next.js의 생산성과 TypeScript의 안정성을 동시에 활용할 수 있는 프로젝트 시작점.
• 자동화된 코드 품질 관리: ESLint와 Prettier를 통해 일관된 코드 스타일과 높은 코드 품질을 유지하는 방법.
• 향상된 개발 경험: Absolute Imports와 VS Code 최적화를 통해 더욱 빠르고 편리하게 코드를 작성하는 환경.

개발 환경 설정은 프로젝트의 성공적인 시작을 위한 첫 단추입니다. 이 과정에서 충분한 시간을 투자하고 체계적으로 준비하는 것은 앞으로의 개발 과정에서 발생할 수 있는 많은 문제들을 예방하고, 개발 팀의 생산성을 극대화하는 중요한 밑거름이 됩니다. 잘 정돈된 환경은 개발자가 핵심 로직 구현에 더 집중할 수 있도록 돕고, 결과적으로 더 높은 품질의 애플리케이션을 만들어낼 수 있게 합니다.

웹 개발의 세계는 끊임없이 변화하고 발전합니다. Next.js와 TypeScript 역시 지속적으로 업데이트되고 새로운 기능들이 추가됩니다. 따라서 공식 문서를 주기적으로 확인하고, 새로운 정보에 관심을 가지는 것이 중요합니다. 이 가이드는 여러분의 여정에 튼튼한 이정표가 되었기를 바랍니다.

이 가이드가 Next.js와 TypeScript 프로젝트를 시작하는 데 도움이 되었기를 바라며, 궁금한 점이나 추가하고 싶은 내용이 있다면 언제든지 댓글로 남겨주세요. 여러분의 피드백은 더 나은 콘텐츠를 만드는 데 큰 힘이 됩니다!

📌 함께 읽으면 좋은 글

• [튜토리얼] Nginx Let's Encrypt HTTPS 적용 가이드: 웹 서버 보안 강화와 설정 최적화
• [생산성 자동화] 셸 스크립트로 개발 워크플로우 자동화: 반복 작업 효율을 극대화하는 실전 팁
• [개발 도구] VS Code 생산성 극대화: 필수 확장 프로그램과 고급 설정 팁

이 글이 도움이 되셨다면 공감(♥)과 댓글로 응원해 주세요!
궁금한 점이나 다루었으면 하는 주제가 있다면 댓글로 남겨주세요.