Post

Next.js (1. Installation) 정리

Posted
Next.js v16
Next.js v16
By H-JuKyung
12 min read
Next.js (1. Installation) 정리

0. 설치

새로운 Next.js 프로젝트를 생성하고 로컬에서 실행해보자.

1. 빠른 시작

Next.js 프로젝트를 가장 빠르게 생성하는 방법은 아래와 같다. (pnpm 기준)

  1. 프로젝트 생성

    1

     pnpm create next-app@latest my-app --yes
    • my-app: 생성할 프로젝트 폴더 이름
    • --yes: 기본 설정을 자동으로 적용해 프롬프트를 건너뜀
      • TypeScript, TailwindCSS, ESLint, App Router, Turbopack 사용
      • import alias 사용(@/*)

  2. 실행

    1
2

     cd my-app
 pnpm dev

  3. 접속

    • 브라우저에서 http://localhost:3000 방문

2. 시스템 요구사항

Next.js를 사용하기 위한 최소 개발 환경:

  • Node.js 20.9 이상
  • 지원 OS: macOS, Windows(WSL 포함), Linux

3. 지원되는 브라우저

Next.js는 별도의 설정 없이 최신 브라우저를 지원한다.

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

4. CLI로 생성

Next.js 프로젝트를 가장 빠르게 생성하는 방법은 create-next-app을 사용하는 것이다.
이 명령어는 기본 설정이 자동으로 구성된다.

1

npx create-next-app@latest

설치 과정에서 다음과 같은 메시지가 표시된다.

1
2
3
4
5

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
  1. 프로젝트 이름 입력 (What is your project named?)
  2. 추천 기본 설정 사용 여부 선택 (Would you like to use the recommended Next.js defaults?)
    • Yes: TypeScript, ESLint, TailwindCSS, App Router, Turbopack 포함
    • No, reuse previous settings: 이전 설정 재사용
    • No, customize settings: 직접 설정 선택

No, customize settings 선택 시 다음과 같은 메시지가 표시된다.

1
2
3
4
5
6
7
8

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? @/*
  1. TypeScript 사용 여부
  2. Linter 선택 (ESLint / Biome / None)
  3. React Compiler 사용 여부
  4. TailwindCSS 사용 여부
  5. src/ 디렉터리 사용 여부
  6. App Router 사용 여부 (권장)
  7. import alias 커스터마이징 여부 (@/* 기본값)
  8. 직접 입력할 alias 값

설정이 완료되면 프로젝트 폴더가 생성되고 필요한 패키지가 자동으로 설치된다.

5. 수동 설치

CLI를 사용하지 않고 수동으로도 Next.js 프로젝트를 생성할 수 있다. (pnpm 기준)

  1. 필수 패키지 설치

    1

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

  2. package.json 스크립트 설정

    수동 설치 시 package.json에 다음 스크립트를 직접 추가해야 한다.

    1
2
3
4
5
6
7
8
9

     {
 "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 검사 실행
    • eslint --fix: 자동 수정 기능 실행

  3. Turbopack과 Webpack (선택사항)

    • Turbopack은 Next.js 기본 번들러이다.
    • Webpack을 사용하려면 아래와 같이 실행하면 된다.
    1
2

     next dev --webpack
 next build --webpack

5-1. app 디렉터리 생성

Next.js는 파일 시스템 기반 라우팅(file-system routing)을 사용한다.

즉, 파일과 폴더 구조가 곧 라우트를 결정한다.

  1. 프로젝트 루트(/)에 app 폴더 생성

  2. 루트 레이아웃 생성 (app/layout.tsx)

    layout.tsx는 반드시 필요한 파일이며, Next.js의 전체 UI 구조를 정의한다.
    또한, 반드시 <html>과 <body> 태그를 포함해야 한다.

    1
2
3
4
5
6
7
8
9
10
11
12
13

     // app/layout.tsx

 export default function RootLayout({
 children,
 }: {
 children: React.ReactNode
 }) {
 return (
     <html lang="en">
     <body>{children}</body>
     </html>
 )
 }
    • children에는 각 라우트의 페이지가 렌더링된다.
    • 이 파일은 애플리케이션 전체에 적용되는 공통 레이아웃이다.

  3. 페이지 생성 (app/page.tsx)

    사용자가 루트 URL(/)에 접속했을 때 보여지는 페이지이다.

    1
2
3
4
5

     // app/page.tsx

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

    App Folder Structure

    아래 두 파일은 루트 URL(/)에서 함께 렌더링된다.

    • app/layout.tsx
    • app/page.tsx

    즉, 페이지는 레이아웃 안에 포함된 형태로 렌더링된다.

알아두면 좋은 점:

  • 만약 루트 레이아웃을 만드는 것을 잊어버린 경우, 개발 서버를 실행(next dev)하면 Next.js가 자동으로 생성한다.

  • 프로젝트 루트에 src 폴더를 추가하여 코드(src/app)와 설정 파일을 구분하는 구조를 선택적으로 사용할 수도 있다.

5-2. public 폴더 생성 (선택사항)

프로젝트 루트(/)에 public 폴더를 생성하면 이미지, 아이콘, 폰트 등 정적 파일을 보관할 수 있다.
public 폴더 안의 파일은 모두 루트 경로를 기준으로 접근된다.

  • 파일 위치: public/profile.png
  • 접근 경로: /profile.png

6. 개발 서버 실행하기

  1. 개발 서버를 시작하려면 pnpm dev를 실행한다.
  2. 애플리케이션을 보려면 http://localhost:3000을 방문한다.
  3. 파일(예: app/page.tsx)을 편집하고 저장하면 브라우저에서 업데이트된 결과를 확인할 수 있다.

7. TypeScript 설정

Next.js에서 사용 가능한 최소 TypeScript 버전은 v5.1.0이다.

Next.js는 TypeScript를 기본적으로 지원한다.
추가 설정 없이 아래 과정만으로 TypeScript 환경이 자동으로 구성된다.

  1. 기존 파일 확장자를 .ts 또는 .tsx로 변경

  2. 개발 서버 실행

    1

     next dev
  3. 실행 시 자동으로 이루어지는 작업
    • TypeScript 관련 패키지 설치
    • tsconfig.json 파일 생성
    • 권장 설정이 포함된 기본 TypeScript 설정 추가

7-1. IDE(TypeScript Plugin) 설정

Next.js는 사용자 정의 TypeScript 플러그인과 타입 검사기를 제공한다.
또한, VSCode 등 에디터에서 더 발전된 타입 검사와 자동 완성 기능을 사용할 수 있다.

VSCode에서 플러그인을 활성화하는 방법은 아래와 같다.

  1. 명령 팔레트 열기 (Ctrl/Cmd + Shift + P)
  2. “TypeScript: Select TypeScript Version” 입력
  3. “Use Workspace Version” 선택

TypeScript Command Palette

이렇게 설정하면 VSCode는 Next.js가 제공하는 타입 시스템을 사용한다.

8. Linting 설정

Next.js는 두 가지 린터를 지원한다.

  • ESLint: 규칙이 풍부하고 널리 사용됨
  • Biome: 빠른 린터 + 포맷터 기능 포함

둘 중 원하는 린터를 선택하고, package.json 스크립트를 통해 실행하면 된다.

8-1. ESLint 사용하기

ESLint를 사용할 경우 package.json에 아래 스크립트를 추가하면 된다.

1
2
3
4
5
6

{
  "scripts": {
    "lint": "eslint",
    "lint:fix": "eslint --fix"
  }
}
  • lint: 코드 검사 실행
  • lint:fix: 자동 수정 가능한 부분을 고침

8-2. Biome 사용하기

Biome을 사용할 경우 package.json에 아래 스크립트를 추가하면 된다.

1
2
3
4
5
6

{
  "scripts": {
    "lint": "biome check",
    "format": "biome format --write"
  }
}
  • lint: 코드 검사 실행
  • format: 코드 포맷팅

Biome은 린팅 + 포맷팅 기능이 함께 제공된다.

8-3. next lint를 사용 중이었다면

Next.js 16 이전 프로젝트에서 next lint를 사용했다면 아래 명령어로 ESLint CLI 방식으로 마이그레이션할 수 있다.

1

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

8-4. ESLint 설정 파일

ESLint를 사용할 경우 명시적인 설정 파일을 생성하는 것이 권장된다.

  • 기존 방식: .eslintrc.*
  • 새로운 방식(권장): eslint.config.mjs

알아두면 좋은 점:

Next.js 16부터 next build는 더 이상 자동으로 lint를 실행하지 않는다.
lint는 NPM 스크립트로 직접 실행해야 한다.

1

npm run lint

9. 절대 경로 import와 모듈 경로 별칭 설정

Next.js는 기본적으로 tsconfig.json 또는 jsconfig.json에서 아래 두 옵션을 지원한다.

  • baseUrl
  • paths

이 두 가지를 설정하면 모듈을 상대 경로(../../../) 대신
절대 경로(@/components/button)로 깔끔하게 불러올 수 있다.

1
2
3
4
5

// Before
import { Button } from '../../../components/button'
 
// After
import { Button } from '@/components/button'

9-1. baseUrl 설정

프로젝트의 기준 경로를 설정한다.
보통 src/ 폴더를 기준으로 한다.

tsconfig.json 또는 jsconfig.json 파일에 추가

1
2
3
4
5

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

9-2. paths 옵션으로 경로 별칭(alias) 만들기

tsconfig.json 또는 jsconfig.json 파일에 추가

1
2
3
4
5
6
7
8
9

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

paths의 모든 경로는 baseUrl을 기준으로 해석된다.

Next.js, Getting Started
Next.js docs App Router
This post is licensed under CC BY 4.0 by the author.