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@16 my-next-app

• npx: npm 5.2 버전 이상에서 제공하는 명령어로, 로컬에 설치되지 않은 패키지의 실행 파일을 임시로 다운로드하여 실행할 때 사용합니다. create-next-app을 전역으로 설치하지 않고도 바로 사용할 수 있게 해줍니다.
• 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, 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: 기본 별칭 `@/*`를 유지합니다.

선택 결과는 생성된 파일에서도 확인할 수 있습니다. tsconfig.json은 TypeScript와 별칭, ESLint 설정 파일은 검사 규칙, src/app은 라우트 위치, globals.css는 전역 스타일의 출발점입니다. React Compiler는 관련 설정과 의존성에서 확인합니다. 추가 질문이 나타나면 공식 CLI 문서에서 해당 옵션의 의미를 확인하세요.

모든 질문에 답하고 나면, create-next-app은 필요한 파일과 의존성을 다운로드하고 프로젝트를 생성하기 시작합니다.

이 과정은 네트워크 속도에 따라 몇 분 정도 소요될 수 있습니다.

성공 메시지에는 생성된 경로와 다음 실행 명령이 안내됩니다. 아래는 명령의 역할을 함께 적은 설명용 예시이며 실제 출력 문구는 버전에 따라 다릅니다. lint 스크립트의 존재와 명령은 선택한 도구 및 생성된 package.json에서 확인합니다.

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를 사용하는 핵심 디렉터리입니다. App Router의 라우트와 레이아웃을 정의합니다. 공용 컴포넌트는 src/components처럼 별도 폴더에 둘 수도 있습니다.
    • 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의 환영 페이지가 보인다면 성공적으로 첫 프로젝트를 생성하고 실행한 것입니다.

직접 확인: 내 프로젝트의 변경을 보고 있는가?

생성한 프로젝트의 src/app/page.tsx를 열어 첫 화면의 제목을 바꿉니다. 처음에는 이 파일을 다음처럼 간단한 컴포넌트로 바꾸어 확인해도 됩니다. 파일의 기본 내보내기 함수가 반환한 제목이 루트 페이지의 내용입니다.

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

저장한 뒤 현재 실행 중인 터미널의 주소를 열고 제목을 확인합니다. http://localhost:3000에 다른 프로젝트가 이미 실행 중이고 새 서버가 다른 포트를 사용했다면, 3000의 화면을 보는 것만으로 이번 파일의 반영을 확인할 수 없습니다. 새 출력 주소, 실행한 폴더, 저장한 파일을 함께 대조합니다.

개발 서버는 코드를 수정하면 자동으로 변경 사항을 감지하여 브라우저에 반영해 줍니다.

일반적인 소스 수정은 Fast Refresh로 확인할 수 있습니다. 설정·의존성 변경 등은 개발 서버 재시작이 필요할 수 있으므로 터미널 안내를 함께 확인하세요.

개발 서버를 종료하려면 터미널에서 Ctrl + C (Windows/macOS/Linux)를 누르면 됩니다.

생성 결과 점검

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

스스로 실행 상태 판단하기

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