🚀 Next.js App Router 설치 및 프로젝트 시작 가이드

Next.js는 React 기반의 풀스택 웹 애플리케이션을 구축하기 위한 프레임워크로, 최신 기능들을 활용하여 효율적인 개발을 지원합니다. 이번 가이드에서는 Next.js의 App Router를 기반으로 프로젝트를 설치하고 시작하는 방법을 단계별로 설명합니다.

✅ 시스템 요구 사항

Node.js:버전 18.18 이
운영 체제:macOS, Windows(WSL 포함), 또는 Linu

⚙️ 자동 설치: create-next-app 사용하기

Next.js에서는 create-next-app CLI를 통해 빠르게 프로젝트를 생성할 수 있습니다.

1. 프로젝트 생성

npx create-next-app@latest

실행 후, 아래와 같은 프롬프트가 나타납니다:

프로젝트 이름 입력
TypeScript 사용 여부
ESLint 사용 여부
Tailwind CSS 사용 여부
src/ 디렉토리 사용 여부
App Router 사용 여부 (권장)
Turbopack 사용 여부
import alias 설정 여부

선택에 따라 프로젝트가 생성되고 필요한 의존성이 설치됩니다.

🛠️ 수동 설치: 직접 설정하기

직접 프로젝트를 설정하려면 다음 단계를 따르세요.

1. 필수 패키지 설치

npm install next@latest react@latest react-dom@latest

2. package.json 스크립트 추가

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  }
}

3. 디렉토리 및 파일 구조 설정

app/layout.tsx

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="ko">
      <body>{children}</body>
    </html>
  );
}

app/page.tsx

export default function Page() {
  return <h1>Hello, Next.js!</h1>;
}

🖼️ 정적 자산 관리: public 폴더 사용 (선택 사항)

프로젝트 루트에 public 폴더를 생성하여 이미지, 폰트 등의 정적 자산을 관리할 수 있습니다. 예를 들어, public/profile.png 파일은 코드에서 /profile.png로 참조할 수 있습니다.

import Image from 'next/image';

export default function Page() {
  return <Image src="/profile.png" alt="Profile" width={100} height={100} />;
}

🚀 개발 서버 실행

개발 서버 시작:

npm run dev

브라우저에서 http://localhost:3000 접속하여 애플리케이션 확인
app/page.tsx 파일을 수정하고 저장하여 변경 사항 확인

🧩 TypeScript 설정

Next.js는 기본적으로 TypeScript를 지원합니다. .ts 또는 .tsx 파일을 생성하고 next dev를 실행하면 필요한 의존성이 자동으로 설치되고 tsconfig.json 파일이 생성됩니다.

🧹 ESLint 설정

ESLint는 코드 품질을 유지하는 데 도움이 됩니다. create-next-app을 사용할 경우 자동으로 설정되며, 수동으로 설정하려면 다음을 따르세요:

package.json에 스크립트 추가:

{
  "scripts": {
    "lint": "next lint"
  }
}

ESLint 실행:

npm run lint

프롬프트에 따라 설정을 완료하면 .eslintrc.json 파일이 생성되고, 선택한 구성에 따라 eslint 및 eslint-config-next 패키지가 설치됩니다.

📦 절대 경로 및 모듈 경로 별칭 설정

tsconfig.json 또는 jsconfig.json 파일에 다음과 같이 설정하여 절대 경로 및 모듈 경로 별칭을 사용할 수 있습니다:

{
  "compilerOptions": {
    "baseUrl": "src/",
    "paths": {
      "@/components/*": ["components/*"],
      "@/styles/*": ["styles/*"]
    }
  }
}

이렇게 설정하면 다음과 같이 간단하게 모듈을 import할 수 있습니다:

import { Button } from '@/components/button';

🧪 프로젝트 테스트

설정이 완료되면 다음 명령어로 프로젝트를 실행하고 테스트할 수 있습니다:

npm run dev

브라우저에서 http://localhost:3000 접속하여 "Hello, Next.js!" 메시지를 확인하세요.

Next.js, App Router, React, 웹 개발, 풀스택, TypeScript, ESLint, Tailwind CSS, 프로젝트 설정, 정적 자산 관리