1단계 — 프로젝트 셋업

Next.js 16 + TypeScript strict + Tailwind v4 + Turbopack — 2026 년 모던 풀스택의 기본 조합.

1. create-next-app

pnpm create next-app@latest my-fullstack

질문 순서대로 응답:

질문	권장
TypeScript?	Yes
ESLint?	Yes
Tailwind CSS?	Yes
`src/` directory?	Yes
App Router?	Yes
Turbopack?	Yes
import alias?	No (기본 `@/*`)

플래그 한 번에:

pnpm create next-app@latest my-fullstack \
  --typescript --tailwind --app --src-dir --turbopack --eslint --no-import-alias

2. 폴더 구조

my-fullstack/
├── src/
│   ├── app/
│   │   ├── layout.tsx        # 루트 레이아웃
│   │   ├── page.tsx          # / 페이지
│   │   ├── globals.css       # 전역 CSS (Tailwind 포함)
│   │   └── favicon.ico
│   └── (향후 routes 추가)
├── public/                   # 정적 자산
├── package.json
├── pnpm-lock.yaml
├── next.config.ts
├── tsconfig.json
├── tailwind.config.ts (v4 에서는 옵션)
└── eslint.config.mjs

src/app/ 아래의 파일 구조가 URL 구조.

3. 개발 서버

cd my-fullstack
pnpm dev

http://localhost:3000 에서 기본 페이지
파일 수정 시 HMR (자동 새로고침)
Turbopack 으로 Webpack 대비 수 배 빠른 빌드

4. TypeScript strict 확인

tsconfig.json:

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true
  }
}

strict: true 기본. 엄격함을 더 높이려면 noUncheckedIndexedAccess 추가 권장.

5. 첫 페이지 수정

src/app/page.tsx:

export default function Home() {
  return (
    <main className="grid min-h-screen place-items-center bg-slate-50">
      <section className="text-center space-y-4">
        <h1 className="text-4xl font-bold text-slate-900">My Fullstack</h1>
        <p className="text-slate-600">Next.js 16 · TypeScript · Tailwind v4</p>
        <a
          href="/about"
          className="inline-block rounded-md bg-slate-900 px-6 py-2 text-white"
        >
          시작하기
        </a>
      </section>
    </main>
  );
}

저장하면 브라우저 자동 새로고침.

6. 새 라우트 추가

파일 시스템이 라우팅. src/app/about/page.tsx 를 만들면 /about.

// src/app/about/page.tsx
export default function About() {
  return <h1 className="text-2xl p-10">About</h1>;
}

동적 라우트는 대괄호: src/app/posts/[id]/page.tsx → /posts/:id.

7. layout.tsx — 공통 레이아웃

src/app/layout.tsx:

import type { Metadata } from "next";
import "./globals.css";

export const metadata: Metadata = {
  title: "My Fullstack",
  description: "Next 16 + TS + Tailwind",
};

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="ko">
      <body>
        <nav className="p-4 border-b">
          <a href="/" className="font-bold">My App</a>
        </nav>
        {children}
      </body>
    </html>
  );
}

layout.tsx 가 자식 페이지를 감쌈. 폴더별로 nested layout 가능.

8. Tailwind v4 살펴보기

src/app/globals.css:

@import "tailwindcss";

@theme {
  --color-brand: #0ea5e9;
}

Tailwind v4 는 설정을 CSS 안에서. 별도 tailwind.config.ts 최소화.

<h1 className="text-brand text-3xl font-bold">

--color-brand 가 text-brand · bg-brand 유틸리티로 자동 생성.

9. 환경변수

.env.local (git ignore):

DATABASE_URL=postgresql://localhost:5432/my_app
NEXT_PUBLIC_SITE_URL=http://localhost:3000

NEXT_PUBLIC_ prefix — 브라우저 노출
prefix 없음 — 서버에서만

10. ESLint 즉시 실행

pnpm lint

문법 오류 · 규칙 위반을 미리 잡음. 저장 시 자동 포맷은 VS Code 확장.

11. 빌드 · 프로덕션 실행

pnpm build     # Turbopack 으로 빌드
pnpm start     # production 서버 (포트 3000)

빌드 결과는 .next/ 에. 배포 준비.

12. 자주 걸리는 자리

포트 3000 이미 사용 — pnpm dev -p 3001
node_modules 설치 실패 — Node 버전 확인 (20+) · 삭제 후 재설치
브라우저에 변경 안 보임 — 강력 새로고침 (Cmd+Shift+R)
src/ 인식 안 됨 — tsconfig.json · next.config.ts paths 확인

하고픈 말

pnpm create next-app 한 줄이면 production-ready 기반. 과도한 boilerplate 없이 바로 학습 가능.

02-server-client

Next.js 공식 — Getting Started · Tailwind v4 를 참고합니다.

1. create-next-app

pnpm create next-app@latest my-fullstack

질문 순서대로 응답:

질문

권장

TypeScript?

Yes

ESLint?

Yes

Tailwind CSS?

Yes

src/ directory?

Yes

App Router?

Yes

Turbopack?

Yes

import alias?

No (기본 @/*)

플래그 한 번에:

pnpm create next-app@latest my-fullstack \ --typescript --tailwind --app --src-dir --turbopack --eslint --no-import-alias

2. 폴더 구조

my-fullstack/ ├── src/ │ ├── app/ │ │ ├── layout.tsx # 루트 레이아웃 │ │ ├── page.tsx # / 페이지 │ │ ├── globals.css # 전역 CSS (Tailwind 포함) │ │ └── favicon.ico │ └── (향후 routes 추가) ├── public/ # 정적 자산 ├── package.json ├── pnpm-lock.yaml ├── next.config.ts ├── tsconfig.json ├── tailwind.config.ts (v4 에서는 옵션) └── eslint.config.mjs

src/app/ 아래의 파일 구조가 URL 구조.

5. 첫 페이지 수정

src/app/page.tsx:

export default function Home() { return ( <main className="grid min-h-screen place-items-center bg-slate-50"> <section className="text-center space-y-4"> <h1 className="text-4xl font-bold text-slate-900">My Fullstack</h1> <p className="text-slate-600">Next.js 16 · TypeScript · Tailwind v4</p> <a href="/about" className="inline-block rounded-md bg-slate-900 px-6 py-2 text-white" > 시작하기 </a> </section> </main> ); }

저장하면 브라우저 자동 새로고침.

7. layout.tsx — 공통 레이아웃

src/app/layout.tsx:

import type { Metadata } from "next"; import "./globals.css"; export const metadata: Metadata = { title: "My Fullstack", description: "Next 16 + TS + Tailwind", }; export default function RootLayout({ children }: { children: React.ReactNode }) { return ( <html lang="ko"> <body> <nav className="p-4 border-b"> <a href="/" className="font-bold">My App</a> </nav> {children} </body> </html> ); }

layout.tsx 가 자식 페이지를 감쌈. 폴더별로 nested layout 가능.