Installation

빠른 시작 (Quick start)

가장 빠르게 시작하는 방법입니다. 아래 순서대로 따라 해보세요!

1. my-app이라는 이름의 새로운 Next.js 앱을 만듭니다.
2. cd my-app 명령어로 해당 폴더로 이동한 뒤, 개발 서버를 시작합니다.
3. 브라우저를 열고 http://localhost:3000에 접속합니다.

사용하시는 패키지 매니저에 맞춰 아래 명령어 중 하나를 실행해 보세요.

pnpm create next-app@latest my-app --yes
cd my-app
pnpm dev

npx create-next-app@latest my-app --yes
cd my-app
npm run dev

yarn create next-app@latest my-app --yes
cd my-app
yarn dev

bun create next-app@latest my-app --yes
cd my-app
bun dev

• 명령어 끝에 붙은 --yes 옵션은 설정 프롬프트(질문)를 건너뛰고, 저장된 설정이나 기본값으로 바로 설치하겠다는 뜻이에요. 기본 설정으로는 TypeScript, Tailwind CSS, ESLint, App Router, 그리고 Turbopack이 활성화되며, import 별칭(alias)은 @/*로 설정됩니다.

💡 강사님의 팁!
실무에서는 보통 npm이나 yarn을 많이 썼지만, 최근에는 속도가 빠른 pnpm이나 아예 새로운 런타임인 bun도 많이 도입하는 추세예요. 아직 초보자시라면 우리에게 가장 익숙한 npm(즉, npx 명령어)으로 시작하시는 것을 추천해 드립니다!

시스템 요구사항 (System requirements)

시작하기 전에, 여러분의 개발 환경이 다음 요구사항을 충족하는지 꼭 확인해 주세요:

• 최소 Node.js 버전: 20.9 이상
• 운영체제: macOS, Windows (WSL 포함), Linux 모두 지원합니다.

💡 강사님의 팁!
Node.js 버전이 낮아서 설치 중 에러가 나는 경우가 정말 많아요. 터미널에 node -v를 입력해서 현재 버전을 꼭 확인해 보세요. 버전을 쉽게 관리하고 싶다면 NVM(Node Version Manager)이나 FNM(Fast Node Manager)을 설치해서 사용하는 것을 강력히 추천합니다!

지원하는 브라우저 (Supported browsers)

Next.js는 아무런 추가 설정 없이도 최신 브라우저들을 지원합니다. 정말 편리하죠?

• Chrome 111+
• Edge 111+
• Firefox 111+
• Safari 16.4+

폴리필(polyfills)을 구성하는 방법이나 특정 구형 브라우저를 타겟팅하는 방법 등 브라우저 지원(browser support)에 대해 더 자세히 알아볼 수 있습니다.

CLI를 사용해서 생성하기 (Create with the CLI)

새 Next.js 앱을 만드는 가장 빠르고 추천하는 방법은 create-next-app이라는 도구를 사용하는 거예요. 이 도구가 모든 초기 설정을 자동으로 다 해준답니다. 프로젝트를 만들려면 아래 명령어를 실행하세요:

pnpm create next-app

npx create-next-app@latest

yarn create next-app

bun create next-app

설치를 시작하면, 터미널 화면에 다음과 같은 질문(프롬프트)들이 나타납니다:

What is your project named? my-app
Would you like to use the recommended Next.js defaults?
    Yes, use recommended defaults - TypeScript, ESLint, Tailwind CSS, App Router, Turbopack
    No, reuse previous settings
    No, customize settings - Choose your own preferences

(해석: 프로젝트 이름은 무엇으로 할까요? / Next.js에서 추천하는 기본 설정을 사용하시겠습니까?)

만약 여러분이 customize settings(설정 커스터마이징)을 선택한다면, 다음과 같은 세부 질문들을 보게 될 거예요:

Would you like to use TypeScript? No / Yes
Which linter would you like to use? ESLint / Biome / None
Would you like to use React Compiler? No / Yes
Would you like to use Tailwind CSS? No / Yes
Would you like your code inside a `src/` directory? No / Yes
Would you like to use App Router? (recommended) No / Yes
Would you like to customize the import alias (`@/*` by default)? No / Yes
What import alias would you like configured? @/*

이 질문들에 대답하고 나면, create-next-app이 여러분이 지은 프로젝트 이름으로 폴더를 만들고, 실행에 필요한 모든 패키지(dependencies)를 알아서 설치해 줍니다.

💡 강사님의 팁! (프롬프트 선택 가이드)

• TypeScript: 무조건 Yes를 추천합니다. 처음엔 타입 에러 때문에 귀찮을 수 있지만, 나중에 앱이 커지면 타입스크립트가 여러분의 퇴근 시간을 지켜줄 거예요.
• Linter: 기본인 ESLint를 선택하시면 무난합니다. (Biome은 빠르지만 아직 생태계 적응이 필요할 수 있어요)
• src/ directory: Yes를 강력 추천합니다! 프로젝트 루트 폴더에 설정 파일들과 소스 코드가 섞이는 걸 방지해 주거든요.
• App Router: Yes! 과거의 Pages Router 대신 현재 Next.js가 밀고 있는 최신 라우팅 방식입니다. 이 문서도 App Router를 기준으로 하고 있어요.

수동 설치 (Manual installation)

초기화 도구(create-next-app)를 쓰지 않고 맨바닥부터 수동으로 Next.js 앱을 만들 수도 있습니다. 그러려면 필요한 패키지들을 직접 설치해야 해요:

pnpm i next@latest react@latest react-dom@latest

npm i next@latest react@latest react-dom@latest

yarn add next@latest react@latest react-dom@latest

bun add next@latest react@latest react-dom@latest

알아두면 좋은 점 (Good to know):

• 새로운 방식인 App Router는 React canary 릴리즈를 내장하여 사용합니다. 여기에는 안정화된 React 19의 모든 변경 사항은 물론, 프레임워크들에서 검증 중인 최신 기능들도 포함되어 있어요. 하지만 도구들과 생태계 호환성을 위해 여러분의 package.json에는 여전히 react와 react-dom을 명시적으로 선언해 두어야 합니다.
• 기존 방식인 Pages Router는 여러분의 package.json에 명시된 React 버전을 그대로 사용합니다.

패키지를 설치했다면, package.json 파일을 열어서 다음 스크립트들을 추가해 주세요:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "eslint",
    "lint:fix": "eslint --fix"
  }
}

이 스크립트들은 애플리케이션 개발의 각기 다른 단계를 의미합니다:

• next dev: 개발 서버를 시작합니다. 기본 번들러로 Turbopack을 사용해요.
• next build: 서비스를 배포하기 위해 프로덕션용으로 애플리케이션을 빌드(최적화)합니다.
• next start: 빌드된 프로덕션 서버를 시작합니다.
• eslint: ESLint(코드 스타일과 오류를 검사하는 도구)를 실행합니다.

이제 Turbopack이 기본 번들러가 되었습니다. 만약 기존의 Webpack을 사용하고 싶다면 next dev --webpack 또는 next build --webpack이라고 실행하면 됩니다. 자세한 설정 방법은 Turbopack 문서를 참고해 주세요.

💡 강사님의 팁!
"수동 설치는 언제 하나요?" 라고 물어보실 수 있는데, 실무에서 새 프로젝트를 할 때는 99% create-next-app을 씁니다. 하지만 수동 설치 과정을 한 번 읽어보면 "아, Next.js가 결국 내부적으로는 React를 의존성으로 깔고 명령어를 통해 실행되는구나!"라는 내부 구조를 이해하는 데 큰 도움이 됩니다.

app 디렉토리 만들기 (Create the app directory)

Next.js는 파일 기반 라우팅(file-system routing)을 사용합니다. 이게 무슨 말이냐면, 여러분이 폴더와 파일을 어떻게 구성하느냐에 따라 웹사이트의 주소(URL) 경로가 결정된다는 뜻이에요.

먼저 app이라는 이름의 폴더를 만드세요. 그런 다음, 그 app 폴더 안에 layout.tsx 파일을 만듭니다. 이 파일은 애플리케이션의 뼈대가 되는 루트 레이아웃(root layout)입니다. 이 파일은 필수적으로 있어야 하며, 반드시 <html> 태그와 <body> 태그를 포함하고 있어야 해요.

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

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}

이제 첫 화면(홈페이지)이 될 app/page.tsx 파일을 만들고, 초기 내용을 조금 채워봅시다:

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

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

여러분이 만든 이 애플리케이션의 최상위 주소(/)로 접속하면, 위에서 만든 layout.tsx 안에 page.tsx의 내용이 쏙 들어가서 렌더링 된답니다.

알아두면 좋은 점 (Good to know):

• 만약 여러분이 깜빡하고 루트 레이아웃(layout.tsx)을 안 만들었더라도 걱정 마세요. next dev 명령어로 개발 서버를 실행하면 Next.js가 알아서 이 파일을 만들어 줍니다. 참 똑똑하죠?
• 프로젝트 최상위 경로에 src 폴더를 만들고 그 안에 app 폴더를 넣는 방식을 선택적으로 사용할 수도 있습니다. 이렇게 하면 애플리케이션의 소스 코드를 각종 설정 파일들과 분리할 수 있어서 훨씬 깔끔해져요.

public 폴더 만들기 (선택 사항)

프로젝트 최상단(루트)에 public 폴더를 만들어서 이미지나 폰트 같은 정적(static) 파일들을 보관할 수 있습니다. public 폴더 안에 있는 파일들은 여러분의 코드 안에서 기본 URL인 /를 시작점으로 삼아 바로 불러올 수 있어요.

예를 들어, 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} />
}

import Image from 'next/image'

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

💡 강사님의 팁!
"이미지를 src 폴더에 넣으면 안 되나요?" 네, 가능은 합니다. 하지만 로고 이미지나 파비콘(favicon), 폰트 파일처럼 브라우저에서 직접 URL로 접근해야 하는 파일들은 반드시 public 폴더에 넣어야 작동한다는 점을 기억해 주세요!

개발 서버 실행하기 (Run the development server)

자, 이제 준비가 다 되었습니다!

1. 터미널에 npm run dev (또는 사용하는 패키지 매니저의 명령어)를 입력해서 개발 서버를 켭니다.
2. 브라우저를 열고 http://localhost:3000 주소로 들어가서 여러분의 애플리케이션을 확인해 보세요.
3. app/page.tsx 파일을 열어서 내용을 수정하고 저장해 보세요. 브라우저를 새로고침하지 않아도 화면이 즉시 업데이트(Hot Reloading)되는 것을 볼 수 있습니다!

TypeScript 설정하기 (Set up TypeScript)

최소 요구되는 TypeScript 버전: v5.1.0

Next.js는 TypeScript 지원 기능을 아예 내장하고 있습니다. 기존 프로젝트에 타입스크립트를 추가하고 싶다면, 자바스크립트 파일의 확장자를 .ts나 .tsx로 바꾸고 next dev를 실행하기만 하면 됩니다. 그러면 Next.js가 필요한 패키지들을 알아서 설치해 주고, 권장 설정이 담긴 tsconfig.json 파일까지 자동으로 만들어 줘요. 정말 편하죠?

IDE 플러그인 (IDE Plugin)

Next.js는 자체적인 커스텀 TypeScript 플러그인과 타입 검사기(type checker)를 포함하고 있습니다. VS Code 같은 코드 에디터에서 이를 활용하면 훨씬 더 고도화된 타입 검사와 자동 완성 기능을 쓸 수 있어요.

VS Code에서 이 플러그인을 활성화하려면 다음 순서를 따르세요:

1. 명령 팔레트를 엽니다. (단축키: Ctrl/⌘ + Shift + P)
2. "TypeScript: Select TypeScript Version" 이라고 검색해서 선택합니다.
3. "Use Workspace Version (작업 공간 버전 사용)" 을 선택합니다.

더 자세한 정보가 필요하시다면 TypeScript 레퍼런스 페이지를 참고해 보세요.

린팅 설정하기 (Set up linting)

Next.js는 코드의 오류를 잡아주고 스타일을 통일해주는 린터(Linter)로 ESLint와 Biome을 모두 지원합니다. 둘 중 원하는 린터를 골라서 package.json의 스크립트로 직접 실행하시면 됩니다.

• ESLint 사용 시 (방대하고 포괄적인 규칙을 원할 때):

{
  "scripts": {
    "lint": "eslint",
    "lint:fix": "eslint --fix"
  }
}

• Biome 사용 시 (엄청나게 빠른 린터와 포매터 통합 도구를 원할 때):

{
  "scripts": {
    "lint": "biome check",
    "format": "biome format --write"
  }
}

만약 여러분의 기존 프로젝트가 예전 방식인 next lint 명령어를 쓰고 있었다면, 아래의 codemod(코드 자동 변환 도구)를 실행해서 ESLint CLI를 직접 호출하는 방식으로 스크립트를 마이그레이션 하세요:

npx @next/codemod@canary next-lint-to-eslint-cli .

ESLint를 사용한다면, 명시적인 설정 파일(권장하는 파일명: eslint.config.mjs)을 만드는 것이 좋습니다. ESLint는 기존의 레거시 .eslintrc.* 포맷과 새로운 eslint.config.mjs 포맷을 모두 지원합니다. 추천하는 초기 설정 방법은 ESLint API 레퍼런스를 확인해 보세요.

알아두면 좋은 점 (Good to know):
Next.js 16 버전부터는 next build를 실행할 때 더 이상 린터가 자동으로 돌아가지 않습니다! (빌드 속도 최적화를 위해서죠.) 대신, 빌드하기 전에 NPM 스크립트를 통해 여러분이 직접 린터를 실행해주시면 됩니다.

더 자세한 정보는 ESLint 플러그인 페이지에서 확인하실 수 있습니다.

절대 경로와 모듈 경로 별칭 설정하기 (Set up Absolute Imports and Module Path Aliases)

Next.js는 tsconfig.json 또는 jsconfig.json 파일의 "paths"와 "baseUrl" 옵션을 내장으로 완벽하게 지원합니다.

이 옵션들을 사용하면 프로젝트 내의 특정 디렉토리를 절대 경로로 별칭(alias) 지정할 수 있어서, 모듈을 불러올(import) 때 훨씬 쉽고 코드가 깔끔해집니다. 아래 예시를 한 번 볼까요?

// 적용 전 (Before) - 일명 '상대경로 지옥'
import { Button } from '../../../components/button'

// 적용 후 (After) - 깔끔하고 직관적이죠!
import { Button } from '@/components/button'

절대 경로를 설정하려면, tsconfig.json (또는 jsconfig.json) 파일에 baseUrl 설정 옵션을 추가해 주면 됩니다.

{
  "compilerOptions": {
    "baseUrl": "src/"
  }
}

baseUrl 경로를 설정하는 것 외에도, "paths" 옵션을 사용해서 모듈 경로에 직접 "별칭(alias)"을 달아줄 수도 있습니다.

예를 들어, 아래와 같이 설정하면 @/components/* 라는 경로를 실제 components/* 경로와 연결(매핑)해 줍니다:

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

여기서 명시된 각각의 "paths" 경로는 위에서 설정한 baseUrl 위치를 기준으로 한다는 점을 기억해 주세요.

💡 강사님의 팁!
이 절대 경로 설정(@/*)은 프로젝트가 조금만 커져도 정말 유용합니다. 폴더 깊이가 깊어질 때마다 ../../../를 세고 있는 건 너무 고통스럽거든요. create-next-app으로 설치할 때 What import alias would you like configured? @/* 라고 물어봤던 것 기억나시죠? 그때 기본값인 @/*를 그대로 쓰시면 이 설정이 자동으로 다 되어있으니 걱정 안 하셔도 됩니다!

---

• 모든 문서의 의미론적 개요(Semantic overview)를 보려면 /docs/sitemap.md를 확인하세요.
• 사용 가능한 모든 문서의 색인(Index)을 보려면 /docs/llms.txt를 확인하세요.

---

어떠셨나요? 공식 문서를 차근차근 읽어보니 Next.js의 기본 구조가 눈에 조금씩 들어오기 시작하죠? 혹시 따라 하다가 막히거나 이해가 안 가는 부분이 있다면 언제든 다시 질문해 주세요. 여러분의 프론트엔드 여정을 끝까지 응원하겠습니다. 파이팅! 🚀