기본 프로젝트 생성 및 구조
Next.js 프로젝트를 생성하고 기본 파일 구조를 파악합니다.
Next.js 기초 입문 2회차: 기본 프로젝트 생성 및 구조 파악
총 30회차 중 2번째 학습 시간입니다.
📌 이번 회차 학습 목표
- Next.js 프로젝트를 성공적으로 생성할 수 있습니다.
create-next-app명령어의 주요 옵션을 이해하고 활용할 수 있습니다.- 생성된 Next.js 프로젝트의 핵심 디렉토리 및 파일 구조를 파악할 수 있습니다.
- 각 주요 파일과 디렉토리의 역할 및 중요성을 설명할 수 있습니다.
📝 개념 설명
Next.js는 React 기반의 웹 애플리케이션을 빠르고 효율적으로 개발할 수 있도록 돕는 프레임워크입니다. 프로젝트를 시작하는 가장 기본적인 단계는 템플릿을 통해 초기 환경을 설정하는 것입니다. 이 과정에서 create-next-app 도구가 사용되며, 이는 Next.js 개발에 필요한 모든 초기 설정과 파일들을 자동으로 생성해줍니다.
Next.js 프로젝트 생성 도구: create-next-app
create-next-app은 Next.js 애플리케이션을 빠르고 쉽게 시작할 수 있도록 설계된 CLI(Command Line Interface) 도구입니다. 이 도구를 사용하면 복잡한 빌드 설정 없이 바로 개발을 시작할 수 있는 최적화된 환경이 구축됩니다. 마치 React의 create-react-app과 유사한 역할을 수행합니다.
Next.js 프로젝트의 기본 구조
Next.js 프로젝트가 생성되면 여러 디렉토리와 파일들이 자동으로 구성됩니다. 이 구조를 이해하는 것은 Next.js 애플리케이션의 동작 방식과 파일 배치 규칙을 파악하는 데 필수적입니다.
pages/디렉토리 (App Router 사용 시app/): Next.js의 핵심적인 라우팅 시스템을 담당합니다. 이 디렉토리 내부에 생성되는 파일들은 자동으로 경로(route)가 됩니다. 예를 들어,pages/about.js파일은/about경로에 매핑됩니다. (Next.js 13부터는app/디렉토리를 사용하는 App Router가 기본으로 도입되었으나, 본 학습지에서는 기존pages/디렉토리를 기준으로 설명합니다. App Router는 추후 별도 회차에서 다룰 예정입니다.)public/디렉토리: 이미지, 폰트 등 정적 자산(static assets)을 저장하는 공간입니다. 이 디렉토리의 파일들은 웹 서버의 루트 경로에서 직접 접근 가능합니다. 예를 들어,public/image.png는/image.png로 접근할 수 있습니다.styles/디렉토리: 전역 스타일 시트나 모듈화된 CSS 파일을 저장하는 공간입니다. Next.js는 CSS Modules 및 Sass를 기본적으로 지원합니다.package.json: 프로젝트의 메타데이터(이름, 버전 등)와 의존성(dependencies), 개발 스크립트(scripts)를 정의하는 파일입니다.npm install또는yarn install명령어를 실행하면 이 파일에 명시된 패키지들이 설치됩니다.next.config.js: Next.js 애플리케이션의 동작 방식을 사용자 정의할 수 있는 설정 파일입니다. 빌드 설정, 환경 변수, 이미지 최적화 등 다양한 옵션을 구성할 수 있습니다.
pages/public/styles/next.config.js💡 예제 & 실습
이제 실제로 Next.js 프로젝트를 생성하고 그 구조를 탐색해보겠습니다.
1단계: 프로젝트 생성
터미널 또는 명령 프롬프트를 열고, 프로젝트를 생성할 디렉토리로 이동한 후 다음 명령어를 실행합니다.
npx create-next-app@latest my-next-app이 명령어는 my-next-app이라는 이름의 새로운 Next.js 프로젝트를 생성합니다. 실행 시 몇 가지 질문이 나타날 수 있습니다. 본 학습지에서는 다음과 같이 선택하는 것을 권장합니다.
Would you like to use TypeScript?: No (JavaScript 기반으로 진행)Would you like to use ESLint?: Yes (코드 품질 유지에 도움)Would you like to use Tailwind CSS?: No (기본 CSS로 진행)Would you like to use 'src/' directory?: No (간결한 구조 유지)Would you like to use App Router? (recommended): No (pages/디렉토리 기반으로 학습)Would you like to customize the default import alias?: No
2단계: 프로젝트 디렉토리로 이동
프로젝트 생성이 완료되면, 생성된 프로젝트 디렉토리로 이동합니다.
cd my-next-app3단계: 개발 서버 실행
프로젝트가 정상적으로 생성되었는지 확인하기 위해 개발 서버를 실행합니다.
npm run dev명령어를 실행하면 터미널에 Ready on http://localhost:3000과 같은 메시지가 나타납니다. 웹 브라우저를 열고 해당 주소로 접속하면 Next.js의 기본 시작 페이지를 확인할 수 있습니다.
4단계: 프로젝트 구조 탐색
이제 VS Code와 같은 코드 편집기를 사용하여 my-next-app 디렉토리를 열고 파일 구조를 살펴보겠습니다.
. (my-next-app)
├── node_modules/
├── pages/
│ ├── _app.js
│ ├── _document.js
│ ├── api/
│ │ └── hello.js
│ └── index.js
├── public/
│ ├── favicon.ico
│ └── vercel.svg
├── styles/
│ ├── Home.module.css
│ └── globals.css
├── .eslintrc.json
├── .gitignore
├── next.config.js
├── package.json
├── package-lock.json
└── README.md주요 파일 및 디렉토리의 역할은 다음과 같습니다.
pages/index.js: 웹사이트의 루트 경로(/)에 해당하는 메인 페이지 컴포넌트입니다.pages/_app.js: 모든 페이지를 초기화하는 데 사용되는 최상위 컴포넌트입니다. 전역 CSS를 임포트하거나 레이아웃을 정의하는 데 활용됩니다.pages/_document.js: 서버 측에서 렌더링되는 문서의<html>및<body>태그를 사용자 정의할 때 사용됩니다. (주로 SEO나 외부 스크립트 삽입 시 활용)pages/api/hello.js: Next.js의 API Routes 기능을 보여주는 예제 파일입니다./api/hello경로로 접근하면 JSON 응답을 반환합니다.styles/globals.css: 애플리케이션 전역에 적용되는 CSS 스타일을 정의합니다.styles/Home.module.css:pages/index.js페이지에만 적용되는 CSS 모듈 파일입니다. 클래스 이름이 자동으로 해싱되어 충돌을 방지합니다.
npx create-next-app 실행npm run dev로 서버 실행⚠️ 자주 틀리는 것 / 주의사항
- 오타 주의:
create-next-app명령어 입력 시 오타가 발생하면 프로젝트가 제대로 생성되지 않거나 예상치 못한 오류가 발생할 수 있습니다. - 디렉토리 이름 규칙:
pages/디렉토리 내의 파일 이름은 URL 경로와 직접적으로 연결되므로, 파일명 규칙(예:index.js는/,about.js는/about)을 정확히 이해해야 합니다. node_modules삭제 금지:node_modules디렉토리는 프로젝트의 모든 의존성 패키지를 포함하므로, 임의로 삭제하거나 수정해서는 안 됩니다. 문제가 발생하면rm -rf node_modules && npm install명령어로 재설치할 수 있습니다.- App Router와 Pages Router 혼동: Next.js 13부터 App Router가 도입되었으나, 본 학습지에서는 Pages Router를 기반으로 설명합니다. 두 라우터는 구조와 동작 방식에 차이가 있으므로 혼동하지 않도록 주의해야 합니다.
- Next.js 프로젝트는
npx create-next-app@latest [프로젝트명]명령어로 생성됩니다. - 주요 디렉토리로는 라우팅을 담당하는
pages/, 정적 자산을 위한public/, 스타일을 위한styles/가 있습니다. package.json은 프로젝트의 의존성과 스크립트를 정의하며,next.config.js는 Next.js 설정을 사용자 정의합니다.npm run dev명령어로 개발 서버를 실행하여 프로젝트를 브라우저에서 확인할 수 있습니다.
🔗 다음 회차 예고
이번 회차에서는 Next.js 프로젝트를 생성하고 기본적인 파일 구조를 파악했습니다. 다음 3회차에서는 ‘페이지 라우팅 및 컴포넌트 이해’를 주제로, pages/ 디렉토리 내에서 페이지를 생성하고, 페이지 간 이동을 위한 라우팅 방법, 그리고 재사용 가능한 컴포넌트의 개념과 활용에 대해 심도 있게 학습할 예정입니다. 이번에 생성한 프로젝트를 바탕으로 실제 페이지를 구성하는 방법을 익혀보겠습니다.