Next.js 16 프로젝트 생성

Node.js와 npm을 설치했다면 이제 Next.js 프로젝트를 직접 만들 차례입니다. Next.js는 프로젝트를 쉽고 빠르게 시작할 수 있도록 create-next-app이라는 도구를 제공하며, 이 도구가 필요한 초기 설정과 폴더 구조를 자동으로 만들어 주므로 곧바로 개발을 시작할 수 있습니다. 이 글에서는 프로젝트를 저장할 위치를 고른 뒤 만드는 명령과 옵션 선택, 설치 완료, 개발 서버 확인의 순서로 진행하고, 만들어진 프로젝트의 기본 구조도 간단히 살펴봅니다.

프로젝트를 만들 위치 고르기

가장 먼저 프로젝트를 저장할 폴더를 정합니다. 터미널(명령 프롬프트나 PowerShell, 터미널 앱)을 열고 프로젝트를 만들 디렉터리로 이동하세요. 예를 들어 Windows의 C:\dev나 macOS·Linux의 ~/Documents/dev에 만들려면 다음과 같이 이동합니다.

# Windows 예시
cd C:\dev

# macOS/Linux 예시
cd ~/Documents/dev

이후의 명령은 모두 이 폴더를 기준으로 실행되며, 다음 단계에서 이 안에 프로젝트 폴더가 새로 만들어집니다. 폴더가 아직 없다면 cd가 실패하므로, 탐색기나 mkdir 명령으로 먼저 만들어 둡니다.

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

고른 디렉터리에서 다음 명령으로 새 Next.js 프로젝트를 만듭니다. 프로젝트 이름은 원하는 대로 정할 수 있으며, 여기서는 my-next-app이라고 붙입니다.

npx create-next-app@16 my-next-app

npx는 npm 5.2 이상에서 제공하는 명령으로, 로컬에 설치되지 않은 패키지의 실행 파일을 임시로 내려받아 실행하므로 create-next-app을 전역으로 설치하지 않고도 바로 쓸 수 있게 해 줍니다. 그 버전을 아직 내려받은 적이 없다면 npx는 먼저 Need to install the following packages:와 설치할 패키지를 보여 주고 Ok to proceed? (y)라고 묻습니다. y를 입력하거나 Enter를 누르면 패키지를 내려받은 뒤 생성 도구가 시작됩니다. create-next-app@16은 교재와 같은 16 메이저 버전의 생성 도구를 쓰겠다는 뜻이며, @latest는 실행하는 시점의 최신 버전이므로 앞으로 다른 메이저 버전이 될 수 있습니다. my-next-app은 만들어질 프로젝트의 폴더 이름입니다.

명령을 실행하면 권장 기본값, 이전 설정의 재사용, 직접 설정 가운데 하나를 고를 수 있습니다. 아래 질문은 16 버전의 대표적인 예이며, 세부 버전이나 저장된 설정, 명령 옵션에 따라 순서와 항목이 달라질 수 있습니다. 저장해 둔 선택을 지우려면 --reset-preferences 옵션을 씁니다. 이 교재는 각 선택의 뜻을 확인하려고 No, customize settings를 고릅니다.

Would you like to use the recommended Next.js defaults?
  Yes, use recommended defaults
  No, reuse previous settings
> No, customize settings
# 권장값을 그대로 쓰지 않고 항목별로 선택합니다. 이전 설정의 재사용은 저장된 설정이 있을 때만 나타납니다.

Would you like to use TypeScript? No / Yes
# Yes: 이 교재의 예제는 TypeScript를 기준으로 합니다.

Which linter would you like to use? ESLint / Biome / None
# ESLint: 처음에는 생태계가 넓은 ESLint를 선택합니다.

Would you like to use React Compiler? No / Yes
# No: 기본 개념을 먼저 익힌 뒤 필요할 때 도입합니다.

Would you like to use Tailwind CSS? No / Yes
# No: 이 장에서는 기본 CSS부터 확인하고 Tailwind는 9장에서 설정합니다.

Would you like your code inside a `src/` directory? No / Yes
# Yes: 애플리케이션 코드를 설정 파일과 분리합니다.

Would you like to use App Router? (recommended) No / Yes
# Yes: 이 교재는 App Router를 기준으로 합니다.

Would you like to use Cache Components? No / Yes

Would you like to customize the import alias (`@/*` by default)? No / Yes
# No: 기본 별칭 `@/*`를 유지합니다.

Would you like to include AGENTS.md to guide coding agents to write up-to-date Next.js code? No / Yes
# No: 코딩 에이전트에게 주는 안내 파일을 만들지 않습니다. 기본 선택은 Yes이며, 이 교재의 예제는 어느 쪽을 골라도 같게 동작합니다.

Would you like to help improve Next.js by letting agents prepare anonymized feedback for your review as you code? (Disable anytime with `experimental.agentFeedback: false`.) No / Yes
# No: 기본 선택은 Yes이며, Yes를 고르면 next.config.ts에 experimental.agentFeedback 설정이 들어갑니다.

16.4부터 나오는 Cache Components 질문은 기본 선택이 Yes이지만, 이 교재는 이 기능을 켜지 않은 구성을 기준으로 하므로 No를 고릅니다. 선택한 결과는 만들어진 파일에서도 확인할 수 있습니다. tsconfig.json은 TypeScript와 경로 별칭, ESLint 설정 파일은 검사 규칙, src/app은 라우트의 위치, globals.css는 전역 스타일의 출발점이며, React Compiler와 Cache Components를 골랐는지는 next.config.ts의 설정과 의존성에서 확인합니다. 질문이 더 나타나면 Next.js 문서의 create-next-app CLI에서 그 옵션의 뜻을 확인하세요.

모든 질문에 답하면 create-next-app이 필요한 파일과 의존성을 내려받아 프로젝트를 만들기 시작하며, 네트워크 속도에 따라 몇 분 걸릴 수 있습니다. 성공 메시지에는 만들어진 경로와 다음에 실행할 명령이 나옵니다. 아래는 16 버전이 보여 주는 메시지의 형식이며 경로는 환경마다 다릅니다. 이 메시지에는 lint 스크립트가 나오지 않으므로, 그 스크립트가 있는지와 명령은 고른 도구와 만들어진 package.json에서 확인합니다.

Success! Created my-next-app at /path/to/my-next-app

Inside that directory, you can run several commands:

  npm run dev
    Starts the development server.

  npm run build
    Builds the app for production.

  npm start
    Runs the built app in production mode.

We suggest that you begin by typing:

  cd my-next-app
  npm run dev

프로젝트를 다 만든 것과 개발 서버를 실행한 것은 다릅니다. 안내된 폴더로 이동한 뒤 서버를 실행하고, 표시된 주소를 브라우저에서 열어 확인합니다.

만들어진 프로젝트 구조 살펴보기

만들어진 my-next-app 디렉터리로 이동해 보세요. create-next-app은 명령을 실행한 위치 아래에 새 폴더를 만들 뿐 터미널의 현재 위치는 바꾸지 않으므로, 이후의 npm 명령을 실행하려면 직접 그 폴더로 들어가야 합니다. 들어간 뒤 ls나 dir로 목록을 보면 아래 그림과 같은 파일과 폴더를 확인할 수 있습니다.

cd my-next-app

위 그림은 교재처럼 src 디렉터리를 고르고 만든 결과로, 프로젝트 루트 아래의 폴더와 파일이 어떤 역할을 하는지 나누어 보여 줍니다. 그림의 캡션이 밝히듯 영역이 안에 들어 있다는 것은 그 파일과 폴더가 프로젝트 안에 놓이는 위치를 뜻하며, src/app은 src 안에 있고 public과 설정 파일, 도구가 만든 결과 폴더는 프로젝트 루트에 있습니다. src/app/에는 페이지인 page.tsx, 공통 UI인 layout.tsx, 전역 CSS인 globals.css가 있어 처음 고칠 곳은 page.tsx이며, 공용 컴포넌트를 둘 components/는 필요할 때 직접 더합니다.

public/에는 이미지와 폰트 같은 정적 파일을 두며, 예를 들어 public/logo.png의 주소는 /logo.png가 됩니다. 루트의 package.json과 lockfile은 의존성과 dev, build, start 스크립트를 정하고(검사 명령은 고른 도구에 따라 다름), next.config.ts는 프레임워크 설정, tsconfig.json은 TypeScript와 별칭 설정입니다. 점선 화살표는 manifest와 lockfile을 기준으로 설치하면 node_modules/가, 개발과 빌드 명령을 실행하면 .next/가 생기는 관계이며, 이 두 결과는 도구가 관리하므로 직접 고치지 않습니다. 그림의 마지막 설명처럼 공용 컴포넌트는 src/components처럼 별도의 폴더에 둘 수 있고, create-next-app의 세부 결과는 고른 옵션과 버전에 따라 달라집니다.

프로젝트 폴더의 주요 디렉터리와 파일을 정리하면 다음과 같습니다. node_modules/는 프로젝트에 설치된 모든 Node.js 패키지가 저장되는 곳으로 Git 같은 버전 관리 시스템에 넣지 않고, public/은 이미지와 폰트 같은 정적 파일을 두는 곳으로 그 안의 파일은 루트 경로에서 바로 접근할 수 있습니다. 이 교재에서는 src 안에 app이 만들어지며, src/app/은 App Router의 라우트와 레이아웃을 정의하는 핵심 디렉터리로 page.tsx가 홈(루트) 페이지를, layout.tsx가 애플리케이션 전체의 레이아웃을, globals.css가 전역 스타일을 맡습니다.

.next/는 Next.js가 빌드한 결과와 캐시를 저장하는 디렉터리로 직접 고칠 필요가 없습니다. package.json은 프로젝트의 이름과 버전 같은 정보, 설치된 패키지의 목록, 스크립트(명령)를 정의하고, package-lock.json(Yarn이라면 yarn.lock)은 설치된 패키지의 정확한 버전을 기록해 다른 환경에서도 같은 의존성을 유지하게 합니다. next.config.ts는 Next.js의 설정을 바꿀 때 쓰는 파일이고, TypeScript를 골랐다면 tsconfig.json이 TypeScript 컴파일러의 설정을 정의합니다.

개발 서버 실행하기

이제 만든 Next.js 애플리케이션을 브라우저에서 직접 확인해 봅니다. 프로젝트 디렉터리(my-next-app)에서 다음 명령으로 개발 서버를 시작합니다.

npm run dev

npm run dev는 package.json의 scripts에 적힌 dev 항목인 next dev를 실행합니다. 개발 서버는 터미널을 차지한 채 계속 실행되므로, 끄려면 그 터미널에서 Ctrl + C를 누릅니다. Yarn을 쓴다면 다음 명령이며, Yarn은 run을 생략해도 스크립트 이름을 알아듣습니다.

yarn dev

명령을 실행하면 접속 주소와 준비 상태가 표시됩니다. 다음은 Next.js 16의 출력이 어떤 정보를 담는지 보여 주는 예이며, 실제 문구와 숫자는 버전과 환경에 따라 다릅니다.

   ▲ Next.js 16.x (Turbopack)
   - Local:        http://localhost:3000
   - Network:      http://<내 컴퓨터의 IP>:3000

 ✓ Starting...
 ✓ Ready in <걸린 시간>

준비 완료 표시를 확인한 뒤 터미널에 나온 주소로 들어갑니다. 기본 주소는 http://localhost:3000이지만, 그 포트를 이미 다른 프로그램이 쓰고 있다면 다른 포트가 골라질 수 있습니다. 웹 브라우저로 그 주소에 들어가 Next.js의 환영 페이지가 보이면 첫 프로젝트를 만들어 실행한 것입니다.

내 프로젝트의 변경을 보고 있는지 확인하기

만든 프로젝트의 src/app/page.tsx를 열어 첫 화면의 제목을 바꿉니다. 처음에는 이 파일을 다음처럼 간단한 컴포넌트로 바꾸어 확인해도 되며, 파일이 기본으로 내보내는 함수가 돌려준 제목이 루트 페이지의 내용입니다.

export default function Home() {
  return <h1>안녕하세요, Next.js!</h1>;
}

저장한 뒤 지금 실행 중인 터미널에 나온 주소를 열어 제목을 확인합니다. http://localhost:3000에서 다른 프로젝트가 이미 실행 중이고 새 서버가 다른 포트를 썼다면, 3000번의 화면을 보는 것만으로는 이번 파일이 반영되었는지 알 수 없으므로 새로 나온 주소와 실행한 폴더, 저장한 파일을 함께 대조합니다.

개발 서버는 코드를 고치면 변경을 감지해 브라우저에 반영해 줍니다. 일반적인 소스 수정은 Fast Refresh로 바로 확인할 수 있지만, 설정이나 의존성의 변경은 개발 서버를 다시 시작해야 할 수 있으므로 터미널의 안내도 함께 확인하세요. 개발 서버를 끝내려면 터미널에서 Ctrl + C를 누릅니다.

만든 결과 점검하기

명령이 시작되지 않으면 현재 경로와 폴더 권한, 프로젝트 이름의 중복, Node.js와 npm의 설치를 확인합니다. 패키지 설치가 실패하면 첫 오류와 네트워크, registry에 접근할 수 있는지를 확인하며, 성공 메시지가 없는데 설치가 끝났다고 판단하지 않습니다. package.json의 dev, build, start와 고른 검사 도구, lockfile과 node_modules를 확인하고, 설치를 다시 시도하는 것은 원인을 확인한 뒤에 합니다. src/app/page.tsx의 문구를 조금 바꿔 저장했는데 화면에 반영되지 않으면 저장했는지와 실행 중인 프로젝트, 터미널의 로그를 확인하고, 화면에 들어갈 수 없으면 실제로 나온 주소와 포트, 서버의 오류를 먼저 확인합니다.

정리

• npx create-next-app@16 my-next-app으로 교재와 같은 16 메이저 버전의 프로젝트를 만들며, 이 교재는 TypeScript, ESLint, src/ 디렉터리, App Router를 고릅니다.
• src/app/의 page.tsx, layout.tsx, globals.css가 라우트와 공통 UI, 전역 스타일을 맡고, public/의 파일은 루트 경로로 공개됩니다.
• node_modules/와 .next/는 도구가 만드는 결과이므로 직접 고치지 않습니다.
• npm run dev로 개발 서버를 시작한 뒤, 터미널에 실제로 나온 주소에서 화면을 확인합니다.
• 폴더가 생긴 것, 설치를 마친 것, 서버가 실행된 것, 내 소스가 화면에 반영된 것은 각각 따로 확인합니다.

연습 문제

1. 설치 오류와 다른 터미널의 화면

만드는 명령이 의존성 설치 오류로 끝났지만 my-next-app 폴더는 생겼습니다. 다른 터미널의 3000번 주소에는 환영 페이지도 보입니다. 이 두 사실만으로 새 프로젝트의 설치와 실행이 끝났다고 볼 수 있을까요?

2. public 폴더의 파일 주소

public/images/logo.png에 파일을 두었습니다. 페이지의 <img> 태그에서 이 파일을 가리키는 주소는 무엇일까요? /public/images/logo.png라고 쓰면 어떻게 될까요?

3. 다른 포트로 시작된 서버

npm run dev를 실행했더니 터미널에 http://localhost:3001이 나왔습니다. 무엇을 의미하며, 화면은 어디서 확인해야 할까요?

다음 글 프로젝트 구조에서는 만들어진 프로젝트의 폴더와 파일이 각각 어떤 일을 하는지 더 자세히 살펴봅니다.