Next.js 16 프로젝트 생성

Node.js와 npm 설치를 성공적으로 마치셨다면, 이제 Next.js의 핵심인 프로젝트를 직접 생성해 볼 차례입니다.

Next.js는 프로젝트를 쉽고 빠르게 시작할 수 있도록 create-next-app이라는 편리한 도구를 제공합니다.

이 도구를 사용하면 필요한 초기 설정과 폴더 구조를 자동으로 구성해주어, 우리가 곧바로 개발에 착수할 수 있도록 돕습니다.

이 절에서는 create-next-app을 사용하여 Next.js 16 프로젝트를 생성하는 과정을 단계별로 안내해 드리고, 프로젝트의 기본 구조에 대해서도 간략하게 살펴보겠습니다.

먼저 프로젝트 생성 흐름을 위치 선택, 명령 실행, 질문 선택, 설치 확인, 개발 서버 실행으로 나눠 봅니다.

프로젝트를 생성할 위치 선택

가장 먼저 할 일은 프로젝트를 저장할 폴더를 결정하는 것입니다.

터미널(명령 프롬프트 또는 PowerShell, 터미널 앱)을 열고, 프로젝트를 생성하고 싶은 디렉터리로 이동하세요.

예를 들어, C:\dev (Windows) 또는 ~/Documents/dev (macOS/Linux)와 같은 경로에 프로젝트를 만들고 싶다면 다음과 같이 이동합니다.

# Windows 예시
cd C:\dev

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

create-next-app으로 프로젝트 생성하기

이제 선택한 디렉터리에서 다음 명령어를 입력하여 새로운 Next.js 프로젝트를 생성합니다.

프로젝트 이름은 원하는 대로 지정할 수 있습니다.

여기서는 예시로 my-next-app이라고 이름을 붙여보겠습니다.

npx create-next-app@latest my-next-app

• npx: npm 5.2 버전 이상에서 제공하는 명령어로, 로컬에 설치되지 않은 패키지의 실행 파일을 임시로 다운로드하여 실행할 때 사용합니다. create-next-app을 전역으로 설치하지 않고도 바로 사용할 수 있게 해줍니다.
• create-next-app@latest: create-next-app 도구의 최신 버전을 사용하겠다는 의미입니다. Next.js 16는 이 최신 버전을 통해 생성됩니다.
• my-next-app: 생성될 프로젝트의 폴더 이름입니다. 원하는 이름으로 변경할 수 있습니다.

명령어를 실행하면 먼저 권장 기본값을 그대로 사용할지 묻습니다.

이 교재는 각 선택의 의미를 확인하기 위해 No, customize settings를 선택합니다.

Would you like to use the recommended Next.js defaults?
  Yes, use recommended defaults
> No, customize settings
  No, reuse previous 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 customize the import alias (`@/*` by default)? No / Yes
# 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

아래 다이어그램은 프로젝트 생성 명령부터 브라우저 확인까지의 실행 흐름을 한 번에 점검할 수 있도록 정리한 것입니다.

생성된 프로젝트 구조 살펴보기

생성된 폴더 구조는 App Router의 라우팅, 전역 레이아웃, 정적 파일, 패키지 스크립트를 나눠 보여줍니다.

이제 생성된 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/globals.css: 전역 스타일을 정의하는 파일입니다.
• .next/: Next.js가 빌드된 결과물이나 캐시를 저장하는 디렉터리입니다. 직접 수정할 필요는 없습니다.
• package.json: 프로젝트의 메타데이터(이름, 버전 등)와 설치된 패키지 목록, 그리고 스크립트(명령어)가 정의된 파일입니다.
• package-lock.json (또는 yarn.lock): 설치된 패키지들의 정확한 버전 정보를 기록하여, 다른 환경에서도 동일한 의존성을 유지할 수 있도록 돕습니다.
• next.config.ts: 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)를 누르면 됩니다.

프로젝트 생성 과정은 질문 선택과 실행 확인이 이어지는 흐름이므로, 아래 다이어그램으로 각 선택이 무엇을 결정하는지 다시 정리해 보세요.

프로젝트 생성 후에는 화면이 열리는지뿐 아니라 스크립트, 폴더, 의존성, 개발 서버 상태가 맞는지도 함께 확인합니다.

마지막으로 create-next-app 질문들이 이후 폴더 구조와 학습 흐름에 어떤 영향을 주는지 연결합니다.