Next.js 안내서 · 1/6

Next.js 시작하기

이 장에서는 Next.js 프로젝트를 만들고 개발 서버를 실행한 뒤, 첫 페이지를 고치고 새 페이지를 추가하는 데까지 진행합니다. 편집기를 어떻게 설정하면 편한지도 함께 살펴봅니다. 이 안내서는 app 폴더를 쓰는 App Router를 기준으로 설명합니다. 예전 방식인 pages 폴더(Pages Router)도 여전히 지원되지만, 새 프로젝트에는 App Router를 권장합니다.

준비물

Next.js는 Node.js 위에서 동작합니다. nodejs.org에서 LTS(장기 지원) 버전을 설치하는 것이 가장 무난합니다. Next.js 버전마다 요구하는 최소 Node.js 버전이 다르므로, 오래된 Node.js를 쓰고 있다면 공식 설치 문서에서 요구 사항을 확인합니다. 패키지 관리자는 Node.js에 들어 있는 npm을 써도 되고, pnpm · Yarn · Bun을 써도 됩니다.

node --version
npm --version

create-next-app으로 프로젝트 만들기

가장 빠른 방법은 공식 생성 도구 create-next-app을 쓰는 것입니다. 필요한 패키지를 설치하고 기본 설정 파일까지 만들어 줍니다.

npx create-next-app@latest my-app

# 다른 패키지 관리자를 쓴다면
pnpm create next-app my-app
yarn create next-app my-app
bun create next-app my-app

실행하면 몇 가지 질문이 나옵니다. 권장 기본값을 고르면 TypeScript, 린터(ESLint), Tailwind CSS, App Router, @/* 경로 별칭이 함께 설정됩니다. 직접 고르는 경우에는 다음 항목을 묻습니다. 질문 구성은 버전에 따라 조금씩 다를 수 있습니다.

TypeScript 사용 여부
린터 선택(ESLint, Biome, 사용 안 함)
Tailwind CSS 사용 여부
소스를 src/ 폴더 안에 둘지 여부
App Router 사용 여부(권장)
가져오기 경로 별칭(기본 @/*)

처음이라면 기본값을 그대로 쓰는 편이 좋습니다. TypeScript는 나중에 추가할 수도 있지만, 처음부터 켜 두면 컴포넌트의 속성과 데이터 구조를 편집기가 검사해 줍니다.

개발 서버 실행

프로젝트 폴더로 들어가 개발 서버를 실행합니다.

cd my-app
npm run dev

브라우저에서 http://localhost:3000을 열면 시작 화면이 보입니다. 개발 서버는 파일을 저장할 때마다 바뀐 부분만 다시 빌드하고, Fast Refresh로 컴포넌트 상태를 최대한 유지한 채 화면을 갱신합니다. 최근 버전의 개발 서버는 Rust로 작성된 번들러 Turbopack을 기본으로 사용합니다.

package.json에는 다음과 같은 스크립트가 들어 있습니다.

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

dev는 개발 서버, build는 운영용 빌드, start는 빌드 결과를 실행하는 운영 서버입니다. 다른 포트를 쓰려면 npm run dev -- -p 4000처럼 -p 옵션을 넘깁니다.

첫 페이지 고치기

App Router에서는 app 폴더 안의 page.tsx 파일이 하나의 주소가 됩니다. app/page.tsx는 사이트의 첫 화면(/)입니다. 내용을 다음처럼 바꾸고 저장하면 브라우저가 바로 갱신됩니다.

// app/page.tsx
export default function Page() {
  return (
    <main>
      <h1>Hello, Next.js!</h1>
      <p>첫 페이지를 고쳤습니다.</p>
    </main>
  );
}

모든 페이지를 감싸는 공통 틀은 app/layout.tsx입니다. 이 루트 레이아웃은 반드시 있어야 하며 <html>과 <body> 태그를 포함해야 합니다. 화면 언어에 맞게 lang 속성을 바꿔 두면 검색 엔진과 화면 낭독기가 언어를 올바르게 인식합니다.

새 페이지 추가하기

폴더를 하나 만들고 그 안에 page.tsx를 두면 새 주소가 생깁니다. app/about/page.tsx는 /about 주소가 됩니다. 페이지 사이를 오갈 때는 <a> 대신 next/link의 Link 컴포넌트를 씁니다. Link는 전체 페이지를 다시 불러오지 않고 필요한 부분만 바꾸며, 화면에 보이는 링크의 대상 페이지를 미리 가져와(prefetch) 이동을 빠르게 합니다.

// app/about/page.tsx
import Link from "next/link";

export default function AboutPage() {
  return (
    <main>
      <h1>소개</h1>
      <Link href="/">처음으로</Link>
    </main>
  );
}

편집기 설정

VS Code를 쓴다면 다음 설정을 권합니다.

Next.js에는 전용 TypeScript 플러그인이 들어 있습니다. .ts나 .tsx 파일을 연 상태에서 명령 팔레트로 "TypeScript: Select TypeScript Version"을 실행하고 "Use Workspace Version"을 고르면, 잘못된 설정 값이나 "use client" 사용 실수를 편집기가 알려 줍니다.
ESLint 확장을 설치하면 저장할 때 린트 오류를 바로 볼 수 있습니다. Biome을 골랐다면 Biome 확장을 설치합니다.
Tailwind CSS를 쓴다면 Tailwind CSS IntelliSense 확장이 클래스 이름 자동 완성을 제공합니다.
브라우저에는 React Developer Tools를 설치해 두면 Client Component의 속성과 상태를 살펴볼 수 있습니다.

정리

npx create-next-app@latest로 프로젝트를 만들고 npm run dev로 개발 서버를 실행합니다.
app 폴더 안의 page.tsx가 주소가 되고, layout.tsx가 공통 틀을 맡습니다.
페이지 사이 이동에는 next/link의 Link를 씁니다.
편집기에서 작업 공간의 TypeScript 버전을 쓰도록 하면 Next.js 전용 검사를 받을 수 있습니다.

이 장에 대해 질문이 있나요?