Next.js

Next.js 프로젝트 생성

김영수 2025. 3. 16. 14:11

 

Next.js 프로젝트 생성 순서

1. 프로젝트 생성

npx create-next-app@latest my-next-app
# 또는
yarn create next-app my-next-app
# 또는
pnpm create next-app my-next-app
 
  • my-next-app → 프로젝트 폴더명 (원하는 이름으로 변경 가능)
  • @latest → 최신 버전 사용

 

옵션

  • --typescript → TypeScript 사용
  • --tailwind → Tailwind CSS 자동 설정
  • --eslint → ESLint 설정 추가

예시:

npx create-next-app@latest my-next-app --typescript --tailwind --eslint
 

2. 프로젝트 실행

cd my-next-app
npm run dev
# 또는
yarn dev
# 또는
pnpm dev
 
  • 기본적으로 localhost:3000에서 실행됨

3. 프로젝트 구조 확인

my-next-app/
├── public/        # 정적 파일 (이미지, 폰트 등)
├── src/           # (Next.js 14 기준) 프로젝트 소스
│   ├── app/       # App Router (Server Components)
│   ├── pages/     # (기존 방식) Pages Router
│   ├── components/ # 재사용 가능한 UI 컴포넌트
│   ├── styles/    # CSS, Tailwind 설정
├── .next/         # Next.js 빌드 파일 (자동 생성됨)
├── package.json   # 프로젝트 설정 파일
├── next.config.js # Next.js 설정 파일
└── tsconfig.json  # TypeScript 설정 (TS 프로젝트일 경우)
 
  • Next.js 13+에서는 pages 대신 app 디렉토리를 사용하는 App Router 권장
  • pages/를 사용하면 기존 방식과 동일하게 CSR 및 SSR이 가능

4. 페이지 생성

(1) pages 방식 (Page Router)

// src/pages/index.tsx
export default function Home() {
  return <h1>Hello Next.js</h1>;
}
 
  • pages/index.tsx → localhost:3000/에서 렌더링됨

(2) app 방식 (App Router - Server Components)

// src/app/page.tsx
export default function Home() {
  return <h1>Hello Next.js App Router</h1>;
}
 
  • app/page.tsx → localhost:3000/에서 렌더링됨

5. 스타일 적용

(1) CSS 모듈 사용 (styles/Home.module.css)

.title {
  color: blue;
  font-size: 24px;
}​
 
import styles from "@/styles/Home.module.css";

export default function Home() {
  return <h1 className={styles.title}>Hello Next.js</h1>;
}
 

(2) Tailwind CSS 적용 (globals.css)

@tailwind base;
@tailwind components;
@tailwind utilities;​
 
export default function Home() {
  return <h1 className="text-blue-500 text-2xl">Hello Next.js</h1>;
}
 

 

6. API 라우트 생성 (/api)

  • Next.js는 API 라우트를 지원하며, pages/api 또는 app/api에 API를 작성 가능

(1) pages 방식 API

// src/pages/api/hello.ts
import { NextApiRequest, NextApiResponse } from "next";

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  res.status(200).json({ message: "Hello API!" });
}​
  • localhost:3000/api/hello에서 실행 가능

(2) app 방식 API (Route Handlers)

// src/app/api/hello/route.ts
export async function GET() {
  return Response.json({ message: "Hello API!" });
}​
localhost:3000/api/hello에서 실행 가능

7. 환경 변수 설정

.env.local 파일 생성

NEXT_PUBLIC_API_URL=https://api.example.com
DATABASE_URL=postgres://user:password@localhost:5432/dbname
 
  • NEXT_PUBLIC_ 접두사가 있는 환경 변수는 클라이언트에서도 접근 가능
  • 서버 전용 변수는 NEXT_PUBLIC_ 없이 사용해야 함

사용 예시:

console.log(process.env.NEXT_PUBLIC_API_URL);​

8. 빌드 및 배포

npm run build   # 프로젝트 빌드
npm run start   # 프로덕션 서버 실행
 
  • out/ 폴더를 생성하여 정적 사이트로 배포 가능 (next export)

Vercel 배포

 
npm install -g vercel
vercel
 
  • Vercel에서 자동으로 Next.js 프로젝트를 배포 가능

✅ 정리

1️⃣ npx create-next-app my-next-app 으로 프로젝트 생성
2️⃣ cd my-next-app && npm run dev 로 개발 서버 실행
3️⃣ pages 또는 app 디렉토리에서 페이지 생성
4️⃣ API 라우트(/api) 활용 가능
5️⃣ CSS 모듈, Tailwind, globals.css로 스타일 적용
6️⃣ .env.local로 환경 변수 설정
7️⃣ npm run build && npm start 로 배포 준비
8️⃣ vercel 등으로 간편하게 배포

 

질문:

터미널에서" would you like to use 'src/' directory?... 를 YES 로 수정하려면 어떻게 해야 하는가요?
 

응답:

Next.js 프로젝트를 생성할 때 "Would you like to use 'src/' directory?"를 자동으로 YES로 설정하려면, create-next-app 실행 시 --src-dir 옵션을 사용하면 됩니다.

✅ 방법 1: 터미널에서 직접 설정

아래 명령어로 src/ 디렉토리를 자동으로 사용하도록 설정할 수 있습니다.

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

 

또는

yarn create next-app my-next-app --src-dir
 

 

또는

pnpm create next-app my-next-app --src-dir​
 

이렇게 하면 src/ 디렉토리가 자동으로 생성되며, pages/, app/, components/ 등의 폴더가 src/ 내부에 위치하게 됩니다.

✅ 방법 2: 수동으로 변경

이미 프로젝트를 생성했는데 src/ 디렉토리를 사용하지 않았다면, 다음과 같이 구조를 변경할 수 있습니다.

1.src/ 디렉토리 생성

mkdir src​

 

 

2.기존 폴더 이동

 
mv pages src/
mv app src/
mv components src/
mv styles src/
 
  • pages/ 또는 app/이 존재하는 경우 이동

3.Next.js 설정 파일 수정 (next.config.js)

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  experimental: {
    appDir: true, // App Router 사용 시 추가
  },
}

module.exports = nextConfig;
 
 

이후 프로젝트를 다시 실행하면 정상적으로 src/ 구조를 사용할 수 있습니다.

✅ 추가 설정 (Next.js 14 이상)

Next.js 14부터는 app/ 디렉토리를 기본 사용하므로, src/app/을 사용하려면 --src-dir과 함께 --experimental-app 옵션을 추가하면 됩니다.

npx create-next-app@latest my-next-app --src-dir --experimental-app
 

🎯 결론

  • 프로젝트 생성 시 --src-dir 옵션을 추가하면 자동 설정됨
  • 기존 프로젝트는 src/ 폴더를 만들고 관련 폴더를 이동하면 됨