Next.js 15 프로젝트 생성
Node.js와 npm 설치를 성공적으로 마치셨다면, 이제 Next.js의 핵심인 프로젝트를 직접 생성해 볼 차례입니다. Next.js는 프로젝트를 쉽고 빠르게 시작할 수 있도록 create-next-app이라는 편리한 도구를 제공합니다. 이 도구를 사용하면 필요한 초기 설정과 폴더 구조를 자동으로 구성해주어, 우리가 곧바로 개발에 착수할 수 있도록 돕습니다.
이 절에서는 create-next-app을 사용하여 Next.js 15 프로젝트를 생성하는 과정을 단계별로 안내해 드리고, 프로젝트의 기본 구조에 대해서도 간략하게 살펴보겠습니다.
프로젝트를 생성할 위치 선택
가장 먼저 할 일은 프로젝트를 저장할 폴더를 결정하는 것입니다. 터미널(명령 프롬프트 또는 PowerShell, 터미널 앱)을 열고, 프로젝트를 생성하고 싶은 디렉터리로 이동하세요. 예를 들어, C:\dev (Windows) 또는 ~/Documents/dev (macOS/Linux)와 같은 경로에 프로젝트를 만들고 싶다면 다음과 같이 이동합니다.
# Windows 예시
cd C:\dev
# macOS/Linux 예시
cd ~/Documents/devcreate-next-app으로 프로젝트 생성하기
이제 선택한 디렉터리에서 다음 명령어를 입력하여 새로운 Next.js 프로젝트를 생성합니다. 프로젝트 이름은 원하는 대로 지정할 수 있습니다. 여기서는 예시로 my-next-app이라고 이름을 붙여보겠습니다.
npx create-next-app@latest my-next-appnpx: npm 5.2 버전 이상에서 제공하는 명령어로, 로컬에 설치되지 않은 패키지의 실행 파일을 임시로 다운로드하여 실행할 때 사용합니다.create-next-app을 전역으로 설치하지 않고도 바로 사용할 수 있게 해줍니다.create-next-app@latest:create-next-app도구의 최신 버전을 사용하겠다는 의미입니다. Next.js 15는 이 최신 버전을 통해 생성됩니다.my-next-app: 생성될 프로젝트의 폴더 이름입니다. 원하는 이름으로 변경할 수 있습니다.
명령어를 실행하면 create-next-app은 몇 가지 질문을 할 것입니다. Next.js 15와 App Router를 기반으로 프로젝트를 구성하기 위해 다음 지침에 따라 답변해 주세요.
What is your project named? my-next-app
# 프로젝트 이름 (위에서 지정한 이름이 기본으로 표시됨)
Would you like to use TypeScript? No / Yes
# TypeScript를 사용할까요? (Next.js와 TypeScript는 좋은 조합입니다. 여기서는 Yes를 선택하겠습니다.)
Would you like to use ESLint? No / Yes
# ESLint를 사용할까요? (코드 품질 관리를 위해 Yes를 선택하는 것을 권장합니다.)
Would you like to use Tailwind CSS? No / Yes
# Tailwind CSS를 사용할까요? (개인의 취향에 따라 선택하세요. 여기서는 No를 선택하겠습니다.)
Would you like to use `src/` directory? No / Yes
# `src/` 디렉토리를 사용할까요? (코드를 깔끔하게 분리하기 위해 Yes를 선택하는 것을 권장합니다.)
Would you like to use App Router? (recommended) No / Yes
# App Router를 사용할까요? (권장) (이 책의 핵심이므로 반드시 Yes를 선택해야 합니다!)
Would you like to customize the default import alias? No / Yes
# 기본 import alias를 사용자 정의할까요? (편의성을 위해 No를 선택하겠습니다.)모든 질문에 답하고 나면, create-next-app은 필요한 파일과 의존성을 다운로드하고 프로젝트를 생성하기 시작합니다. 이 과정은 네트워크 속도에 따라 몇 분 정도 소요될 수 있습니다.
성공적으로 프로젝트가 생성되면 다음과 비슷한 메시지를 볼 수 있습니다.
Success! Created my-next-app at /path/to/my-next-app
Inside that directory, you can run these commands:
npm run dev
Starts the development server.
npm run build
Builds the app for production.
npm run start
Runs the built app in production mode.
npm run lint
Runs ESLint to catch code issues.
We suggest that you begin by typing:
cd my-next-app
npm run dev생성된 프로젝트 구조 살펴보기
이제 생성된 my-next-app 디렉터리로 이동해 보세요.
cd my-next-app프로젝트 폴더 안에는 Next.js 애플리케이션 개발에 필요한 기본적인 파일과 디렉터리가 생성되어 있습니다. 주요 디렉터리와 파일은 다음과 같습니다.
node_modules/: 프로젝트에 설치된 모든 Node.js 패키지(라이브러리)가 저장되는 곳입니다. 이 폴더는 Git과 같은 버전 관리 시스템에 포함시키지 않습니다.public/: 이미지, 폰트 등 정적 파일을 저장하는 곳입니다. 이 안에 있는 파일들은 루트 경로에서 직접 접근할 수 있습니다.src/(또는app/): 이 책에서는src디렉터리 안에app디렉터리가 생성될 것입니다.src/app/: App Router를 사용하는 핵심 디렉터리입니다. 웹 애플리케이션의 모든 라우팅과 컴포넌트들이 이 안에 정의됩니다.src/app/page.tsx: 애플리케이션의 홈(루트) 페이지를 나타내는 파일입니다.src/app/layout.tsx: 애플리케이션 전체에 적용되는 레이아웃을 정의하는 파일입니다.src/app/global.css: 전역 스타일을 정의하는 파일입니다.
.next/: Next.js가 빌드된 결과물이나 캐시를 저장하는 디렉터리입니다. 직접 수정할 필요는 없습니다.package.json: 프로젝트의 메타데이터(이름, 버전 등)와 설치된 패키지 목록, 그리고 스크립트(명령어)가 정의된 파일입니다.package-lock.json(또는yarn.lock): 설치된 패키지들의 정확한 버전 정보를 기록하여, 다른 환경에서도 동일한 의존성을 유지할 수 있도록 돕습니다.next.config.js: Next.js 애플리케이션의 설정을 커스터마이징할 때 사용하는 파일입니다.tsconfig.json(TypeScript를 선택했을 경우): TypeScript 컴파일러 설정을 정의하는 파일입니다.
개발 서버 실행하기
프로젝트 생성이 완료되고 폴더 구조를 살펴보셨다면, 이제 우리가 만든 Next.js 애플리케이션을 브라우저에서 직접 확인해 볼 시간입니다. 프로젝트 디렉터리(my-next-app)에서 다음 명령어를 실행하여 개발 서버를 시작합니다.
npm run dev또는 yarn을 사용한다면:
yarn dev명령어를 실행하면 터미널에 다음과 비슷한 메시지가 나타날 것입니다.
ready - started server on 0.0.0.0:3000, url: http://localhost:3000이 메시지는 개발 서버가 성공적으로 시작되었으며, http://localhost:3000 주소로 접속하면 애플리케이션을 확인할 수 있다는 의미입니다. 이제 웹 브라우저를 열고 해당 주소로 접속해 보세요. Next.js의 환영 페이지가 보인다면 성공적으로 첫 프로젝트를 생성하고 실행한 것입니다.
개발 서버는 코드를 수정하면 자동으로 변경 사항을 감지하여 브라우저에 반영해 줍니다. 따라서 개발 중에는 서버를 다시 시작할 필요 없이 바로바로 변경 사항을 확인할 수 있습니다. 개발 서버를 종료하려면 터미널에서 Ctrl + C (Windows/Linux) 또는 Cmd + C (macOS)를 누르면 됩니다.