Next.js 프로젝트 생성하기: 처음부터 완벽하게 시작하는 방법

 

개요

Next.js를 공부중이다. 프로젝트 생성시에 인터렉티브하게 물어보는 옵션들의 의미를 Claude의 도움을 받아서 정리해보았다.

생성하기

생성명령

npx create-next-app@latest 명령어는 다양한 옵션을 CLI 상호작용 없이 미리 지정할 수 있다. 앱 이름, 템플릿, 각종 설정 옵션을 사전에 지정하는 방법을 체계적으로 정리해본다.

기본 구조

npx create-next-app@latest <프로젝트명> [options]

주요 옵션 정리

옵션 설명 예시

--example 또는 -e	특정 예제 템플릿 사용	-e with-supabase-e https://github.com/사용자/리포
--ts	TypeScript 사용	--ts
--no-ts	TypeScript 미사용	--no-ts
--tailwind	Tailwind CSS 포함	--tailwind
--no-tailwind	Tailwind 포함 안 함	--no-tailwind
--eslint	ESLint 포함	--eslint
--no-eslint	ESLint 생략	--no-eslint
--src-dir	src/ 디렉토리 사용	--src-dir
--no-src-dir	src/ 사용 안 함	--no-src-dir
--app	App Router 사용 (app/ 디렉토리)	--app
--no-app	Pages Router 사용 (pages/ 디렉토리)	--no-app
--import-alias <경로>	import 경로 별칭 지정	--import-alias "@/components"
--use-npm / --use-yarn / --use-pnpm / --use-bun	패키지 매니저 지정	--use-pnpm 등

예시 1: 기본 템플릿 + 옵션 자동화

my-app이라는 이름으로 TypeScript + Tailwind + App Router + @/components alias 포함된 프로젝트가 자동 생성됨.

npx create-next-app@latest my-app \
  --ts \
  --tailwind \
  --eslint \
  --src-dir \
  --app \
  --import-alias "@/components" \
  --use-pnpm

예시 2: Supabase 템플릿 사용

with-supabase 예제 기반 프로젝트가 my-supabase-app으로 생성됨.

npx create-next-app@latest my-supabase-app -e with-supabase

예시 3: GitHub의 커스텀 템플릿 사용

개인 템플릿을 통해 팀 내 통일된 초기 프로젝트 구조를 쉽게 배포.

npx create-next-app@latest custom-app -e <https://github.com/yourname/your-next-template>

설정 옵션

설정 옵션을 정하지 않으면 하나씩 인터렉티브하게 상호작용을 하며 선택하게 한다. 하나씩 들여다보자.

1. TypeScript 사용 여부

✔ Would you like to use TypeScript? … No / Yes

TypeScript는 JavaScript에 정적 타입 시스템을 추가한 언어이다. TypeScript를 사용하면 개발 과정에서 타입 관련 오류를 미리 발견할 수 있어 런타임 에러를 줄이고, 코드의 자동 완성과 문서화에도 도움이 된다. 특히 팀 프로젝트나 규모가 큰 프로젝트에서 유용하다.

• Yes 선택 시: .ts와 .tsx 파일 확장자를 사용하며, 타입 체크를 통해 코드의 안정성을 높일 수 있다.
• No 선택 시: 일반 JavaScript(.js, .jsx)를 사용한다.

2. ESLint 사용 여부

✔ Would you like to use ESLint? … No / Yes

ESLint는 코드 품질과 스타일을 검사하는 도구이다. ESLint를 사용하면 일관된 코드 스타일을 유지하고, 잠재적인 버그나 안티 패턴을 미리 발견할 수 있다. 코드 리뷰 과정에서도 스타일 관련 논의를 줄여 핵심 로직에 집중할 수 있게 해준다.

• Yes 선택 시: 코드 문법, 스타일, 잠재적 문제를 자동으로 검사하는 설정이 추가된다.
• No 선택 시: ESLint 설정이 포함되지 않는다.

3. Tailwind CSS 사용 여부

✔ Would you like to use Tailwind CSS? … No / Yes

Tailwind CSS는 유틸리티 클래스 기반의 CSS 프레임워크이다. Tailwind를 사용하면 HTML 내에서 직접 클래스를 적용하여 빠르게 UI를 구현할 수 있다. CSS 파일을 별도로 작성하는 시간을 줄이고, 일관된 디자인 시스템을 쉽게 구축할 수 있다.

• Yes 선택 시: Tailwind CSS 초기 설정이 완료되고 globals.css에 연결된다.
• No 선택 시: 일반 CSS를 사용하거나 다른 CSS 프레임워크를 직접 설정해야 한다.

4. src/ 디렉토리 사용 여부

✔ Would you like your code inside a src/ directory? … No / Yes

프로젝트 코드의 위치를 결정한다. src/ 디렉토리를 사용하면 소스 코드와 설정 파일, 빌드 결과물 등을 명확히 구분할 수 있어 프로젝트 구조가 더 깔끔해진다. 특히 규모가 큰 프로젝트에서 유용하다.

• Yes 선택 시: 모든 소스 코드가 src/ 폴더 아래에 위치한다.
• No 선택 시: 소스 코드가 프로젝트 루트 디렉토리에 직접 위치한다.

5. App Router 사용 여부

✔ Would you like to use App Router? (recommended) … No / Yes

설명: Next.js의 라우팅 시스템을 선택한다. App Router는 레이아웃 중첩, 서버 컴포넌트, 스트리밍 등 Next.js의 최신 기능을 활용할 수 있게 해준다. 파일 기반 라우팅 시스템이 더 직관적이고 강력해져 복잡한 라우팅 구조도 쉽게 관리할 수 있다.

• Yes 선택 시: Next.js 13부터 도입된 App Router(app/ 디렉토리 기반)를 사용한다.
• No 선택 시: 전통적인 Pages Router(pages/ 디렉토리 기반)를 사용한다.

6. Turbopack 사용 여부

✔ Would you like to use Turbopack for next dev? … No / Yes

개발 서버 실행 시 사용할 번들러를 선택한다. Turbopack은 Webpack보다 훨씬 빠른 속도를 제공하지만, 아직 실험적인 단계이다. 일부 패키지나 설정과 호환성 문제가 있을 수 있어 안정성이 중요한 프로젝트에서는 기존 Webpack을 선택하는 것이 안전할 수 있다.

• Yes 선택 시: Vercel에서 개발 중인 새로운 번들러 Turbopack을 사용한다.
• No 선택 시: 기존의 Webpack을 사용한다.

7. Import Alias 커스터마이징

✔ Would you like to customize the import alias (@/* by default)? … No / Yes

파일 경로 임포트를 위한 별칭 설정이다. 임포트 별칭을 사용하면 @/components/Button과 같이 깔끔하고 일관된 방식으로 모듈을 임포트할 수 있어, 상대 경로의 복잡성(../../../components/Button)을 피할 수 있다. 이는 코드의 가독성을 높이고 파일 이동 시 발생할 수 있는 경로 문제를 줄여준다.

• Yes 선택 시: 임포트 경로 별칭을 직접 설정할 수 있다.
• No 선택 시: 기본값인 @/로 설정된다.

설정 옵션 추천 조합

프로젝트의 성격과 팀의 요구사항에 따라 적절한 옵션을 선택하는 것이 중요하지만 권장사항은 다음과 같다.

• TypeScript: Yes (타입 안정성)
• ESLint: Yes (코드 품질)
• Tailwind CSS: 팀 선호도에 따라 다르지만 빠른 UI 개발에는 Yes
• src/ 디렉토리: Yes (구조화)
• App Router: Yes (최신 기능 활용)
• Turbopack: No (안정성 중시), Yes(개발속도 향상)
• Import alias: Yes (@/)