Next.js Best Practices - Vercel이 공개한 Next.js 개발 가이드 (전문 번역)

app/
├── layout.tsx          # 루트 레이아웃 (필수)
├── page.tsx            # 홈 페이지 (/)
├── loading.tsx         # 로딩 UI
├── error.tsx           # 에러 UI
├── not-found.tsx       # 404 UI
├── global-error.tsx    # 전역 에러 UI
├── route.ts            # API 엔드포인트
├── template.tsx        # 재렌더링되는 레이아웃
├── default.tsx         # 병렬 라우트 폴백
├── blog/
│   ├── page.tsx        # /blog
│   └── [slug]/
│       └── page.tsx    # /blog/:slug
└── (group)/            # 라우트 그룹 (URL에 영향 없음)
    └── page.tsx

app/
├── blog/               # 정적 세그먼트: /blog
├── [slug]/             # 동적 세그먼트: /:slug
├── [...slug]/          # Catch-all: /a/b/c
├── [[...slug]]/        # 선택적 catch-all: / 또는 /a/b/c
└── (marketing)/        # 라우트 그룹 (URL에서 무시됨)

app/
├── @analytics/
│   └── page.tsx
├── @sidebar/
│   └── page.tsx
└── layout.tsx          # { analytics, sidebar }를 props로 받음

app/
├── feed/
│   └── page.tsx
├── @modal/
│   └── (.)photo/[id]/  # /feed에서 /photo/[id]를 인터셉트
│       └── page.tsx
└── photo/[id]/
    └── page.tsx

app/
├── _components/        # 프라이빗 폴더 (라우트 아님)
│   └── Button.tsx
└── page.tsx

// middleware.ts (프로젝트 루트)
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";

export function middleware(request: NextRequest) {
  // 인증, 리다이렉트, 리라이트 등
  return NextResponse.next();
}

export const config = {
  matcher: ["/dashboard/:path*", "/api/:path*"],
};

// proxy.ts (프로젝트 루트)
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";

export function proxy(request: NextRequest) {
  // middleware와 같은 로직
  return NextResponse.next();
}

export const proxyConfig = {
  matcher: ["/dashboard/:path*", "/api/:path*"],
};

// 잘못된 예: async 클라이언트 컴포넌트
"use client";
export default async function UserProfile() {
  const user = await getUser(); // 클라이언트 컴포넌트에서 await 불가
  return <div>{user.name}</div>;
}

// 올바른 예: async 제거, 부모 서버 컴포넌트에서 데이터 페칭
// page.tsx (서버 컴포넌트 - 'use client' 없음)
export default async function Page() {
  const user = await getUser();
  return <UserProfile user={user} />;
}

// UserProfile.tsx (클라이언트 컴포넌트)
("use client");
export function UserProfile({ user }: { user: User }) {
  return <div>{user.name}</div>;
}

// 잘못된 예: async 화살표 함수 클라이언트 컴포넌트
"use client";
const Dashboard = async () => {
  const data = await fetchDashboard();
  return <div>{data}</div>;
};

// 올바른 예: 서버 컴포넌트에서 페칭 후 데이터를 아래로 전달

// 잘못된 예: 함수 prop
// page.tsx (서버)
export default function Page() {
  const handleClick = () => console.log("clicked");
  return <ClientButton onClick={handleClick} />;
}

// 올바른 예: 클라이언트 컴포넌트 내부에서 함수 정의
// ClientButton.tsx
("use client");
export function ClientButton() {
  const handleClick = () => console.log("clicked");
  return <button onClick={handleClick}>Click</button>;
}

// 잘못된 예: Date 객체 (조용히 문자열이 된 뒤 크래시)
// page.tsx (서버)
export default async function Page() {
  const post = await getPost();
  return <PostCard createdAt={post.createdAt} />; // Date 객체
}

// PostCard.tsx (클라이언트) - .getFullYear()에서 크래시
("use client");
export function PostCard({ createdAt }: { createdAt: Date }) {
  return <span>{createdAt.getFullYear()}</span>; // 런타임 에러!
}

// 올바른 예: 서버에서 문자열로 직렬화
// page.tsx (서버)
export default async function Page() {
  const post = await getPost();
  return <PostCard createdAt={post.createdAt.toISOString()} />;
}

// PostCard.tsx (클라이언트)
("use client");
export function PostCard({ createdAt }: { createdAt: string }) {
  const date = new Date(createdAt);
  return <span>{date.getFullYear()}</span>;
}

// 잘못된 예: 클래스 인스턴스
const user = new UserModel(data)
<ClientProfile user={user} /> // 메서드가 제거됨

// 올바른 예: 평범한 객체 전달
const user = await getUser()
<ClientProfile user={{ id: user.id, name: user.name }} />

// 잘못된 예: Map/Set
<ClientComponent items={new Map([['a', 1]])} />

// 올바른 예: 배열/객체로 변환
<ClientComponent items={Object.fromEntries(map)} />
<ClientComponent items={Array.from(set)} />

// 유효함: Server Action은 전달 가능
// actions.ts
"use server";
export async function submitForm(formData: FormData) {
  // 서버 사이드 로직
}

// page.tsx (서버)
import { submitForm } from "./actions";
export default function Page() {
  return <ClientForm onSubmit={submitForm} />; // OK!
}

// ClientForm.tsx (클라이언트)
("use client");
export function ClientForm({
  onSubmit,
}: {
  onSubmit: (data: FormData) => Promise<void>;
}) {
  return <form action={onSubmit}>...</form>;
}

type Props = { params: Promise<{ slug: string }> };

export default async function Page({ params }: Props) {
  const { slug } = await params;
}

export async function GET(
  request: Request,
  { params }: { params: Promise<{ id: string }> },
) {
  const { id } = await params;
}

type Props = {
  params: Promise<{ slug: string }>;
  searchParams: Promise<{ query?: string }>;
};

export default async function Page({ params, searchParams }: Props) {
  const { slug } = await params;
  const { query } = await searchParams;
}

import { use } from "react";

type Props = { params: Promise<{ slug: string }> };

export default function Page({ params }: Props) {
  const { slug } = use(params);
}

type Props = { params: Promise<{ slug: string }> };

export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const { slug } = await params;
  return { title: slug };
}

import { cookies, headers } from "next/headers";

export default async function Page() {
  const cookieStore = await cookies();
  const headersList = await headers();

  const theme = cookieStore.get("theme");
  const userAgent = headersList.get("user-agent");
}

npx @next/codemod@latest next-async-request-api .

// 올바른 예: 기본값 - 런타임 설정 불필요 (Node.js 사용)
export default function Page() { ... }

// 주의: 프로젝트에서 이미 사용 중이거나 특별히 필요한 경우에만
export const runtime = 'edge'

"use client";

import { useState } from "react";

export function Counter() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(count + 1)}>{count}</button>;
}

"use server";

export async function submitForm(formData: FormData) {
  // 서버에서 실행
}

export default function Page() {
  async function submit() {
    "use server";
    // 서버에서 실행
  }
  return <form action={submit}>...</form>;
}

"use cache";

export async function getCachedData() {
  return await fetchData();
}

// 잘못된 예: 일반 앵커 태그
<a href="/about">About</a>;

// 올바른 예: Next.js Link
import Link from "next/link";

<Link href="/about">About</Link>;

"use client";

import Link from "next/link";
import { usePathname } from "next/navigation";

export function NavLink({ href, children }) {
  const pathname = usePathname();

  return (
    <Link href={href} className={pathname === href ? "active" : ""}>
      {children}
    </Link>
  );
}

// app/blog/[slug]/page.tsx
export async function generateStaticParams() {
  const posts = await getPosts();
  return posts.map((post) => ({ slug: post.slug }));
}

import { after } from "next/server";

export async function POST(request: Request) {
  const data = await processRequest(request);

  after(async () => {
    await logAnalytics(data);
  });

  return Response.json({ success: true });
}

"use client";

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  return (
    <div>
      <h2>Something went wrong!</h2>
      <button onClick={() => reset()}>Try again</button>
    </div>
  );
}

"use client";

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  return (
    <html>
      <body>
        <h2>Something went wrong!</h2>
        <button onClick={() => reset()}>Try again</button>
      </body>
    </html>
  );
}

'use server'

import { redirect } from 'next/navigation'
import { notFound } from 'next/navigation'

// 잘못된 예: try-catch가 내비게이션 "에러"를 잡아버림
async function createPost(formData: FormData) {
  try {
    const post = await db.post.create({ ... })
    redirect(`/posts/${post.id}`)  // throw가 발생!
  } catch (error) {
    // redirect()의 throw가 여기서 잡힘 - 내비게이션 실패!
    return { error: 'Failed to create post' }
  }
}

// 올바른 예: 내비게이션 API를 try-catch 밖에서 호출
async function createPost(formData: FormData) {
  let post
  try {
    post = await db.post.create({ ... })
  } catch (error) {
    return { error: 'Failed to create post' }
  }
  redirect(`/posts/${post.id}`)  // try-catch 밖
}

// 올바른 예: 내비게이션 에러를 다시 throw
async function createPost(formData: FormData) {
  try {
    const post = await db.post.create({ ... })
    redirect(`/posts/${post.id}`)
  } catch (error) {
    if (error instanceof Error && error.message === 'NEXT_REDIRECT') {
      throw error  // 내비게이션 에러는 다시 throw
    }
    return { error: 'Failed to create post' }
  }
}

import { unstable_rethrow } from "next/navigation";

async function action() {
  try {
    // ...
    redirect("/success");
  } catch (error) {
    unstable_rethrow(error); // Next.js 내부 에러를 다시 throw
    return { error: "Something went wrong" };
  }
}

import { redirect, permanentRedirect } from "next/navigation";

// 307 임시 - 대부분의 경우에 사용
redirect("/new-path");

// 308 영구 - URL 마이그레이션에 사용 (브라우저가 캐싱)
permanentRedirect("/new-url");

import { forbidden, unauthorized } from "next/navigation";

async function Page() {
  const session = await getSession();

  if (!session) {
    unauthorized(); // unauthorized.tsx 렌더링 (401)
  }

  if (!session.hasAccess) {
    forbidden(); // forbidden.tsx 렌더링 (403)
  }

  return <Dashboard />;
}

// app/forbidden.tsx
export default function Forbidden() {
  return <div>You don't have access to this resource</div>;
}

// app/unauthorized.tsx
export default function Unauthorized() {
  return <div>Please log in to continue</div>;
}

export default function NotFound() {
  return (
    <div>
      <h2>Not Found</h2>
      <p>Could not find the requested resource</p>
    </div>
  );
}

import { notFound } from "next/navigation";

export default async function Page({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  const post = await getPost(id);

  if (!post) {
    notFound(); // 가장 가까운 not-found.tsx 렌더링
  }

  return <div>{post.title}</div>;
}

app/
├── error.tsx           # 모든 자식의 에러를 잡음
├── blog/
│   ├── error.tsx       # /blog/* 의 에러를 잡음
│   └── [slug]/
│       ├── error.tsx   # /blog/[slug] 의 에러를 잡음
│       └── page.tsx
└── layout.tsx          # 여기의 에러는 global-error.tsx로

데이터를 페칭해야 하나요?
├── Server Component에서?
│   └── 사용: 직접 페칭 (API 불필요)
│
├── Client Component에서?
│   ├── 뮤테이션 (POST/PUT/DELETE)인가?
│   │   └── 사용: Server Action
│   └── 읽기 (GET)인가?
│       └── 사용: Route Handler 또는 Server Component에서 전달
│
├── 외부 API 접근이 필요? (웹훅, 서드파티)
│   └── 사용: Route Handler
│
└── 모바일 앱/외부 클라이언트용 REST API가 필요?
    └── 사용: Route Handler

// app/users/page.tsx
async function UsersPage() {
  // 직접 데이터베이스 접근 - API 라운드트립 없음
  const users = await db.user.findMany();

  // 또는 외부 API에서 페칭
  const posts = await fetch("https://api.example.com/posts").then((r) =>
    r.json(),
  );

  return (
    <ul>
      {users.map((user) => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}

// app/actions.ts
"use server";

import { revalidatePath } from "next/cache";

export async function createPost(formData: FormData) {
  const title = formData.get("title") as string;

  await db.post.create({ data: { title } });

  revalidatePath("/posts");
}

export async function deletePost(id: string) {
  await db.post.delete({ where: { id } });

  revalidateTag("posts");
}

// app/posts/new/page.tsx
import { createPost } from "@/app/actions";

export default function NewPost() {
  return (
    <form action={createPost}>
      <input name="title" required />
      <button type="submit">Create</button>
    </form>
  );
}

// app/api/posts/route.ts
import { NextRequest, NextResponse } from "next/server";

// GET은 캐싱 가능
export async function GET(request: NextRequest) {
  const posts = await db.post.findMany();
  return NextResponse.json(posts);
}

// POST는 뮤테이션용
export async function POST(request: NextRequest) {
  const body = await request.json();
  const post = await db.post.create({ data: body });
  return NextResponse.json(post, { status: 201 });
}

// 잘못된 예: 순차 워터폴
async function Dashboard() {
  const user = await getUser(); // 대기...
  const posts = await getPosts(); // 그다음 대기...
  const comments = await getComments(); // 그다음 대기...

  return <div>...</div>;
}

// 올바른 예: 병렬 페칭
async function Dashboard() {
  const [user, posts, comments] = await Promise.all([
    getUser(),
    getPosts(),
    getComments(),
  ]);

  return <div>...</div>;
}

// 올바른 예: 콘텐츠를 점진적으로 표시
import { Suspense } from "react";

async function Dashboard() {
  return (
    <div>
      <Suspense fallback={<UserSkeleton />}>
        <UserSection />
      </Suspense>
      <Suspense fallback={<PostsSkeleton />}>
        <PostsSection />
      </Suspense>
    </div>
  );
}

async function UserSection() {
  const user = await getUser(); // 독립적으로 페칭
  return <div>{user.name}</div>;
}

async function PostsSection() {
  const posts = await getPosts(); // 독립적으로 페칭
  return <PostList posts={posts} />;
}

// lib/data.ts
import { cache } from "react";

export const getUser = cache(async (id: string) => {
  return db.user.findUnique({ where: { id } });
});

export const preloadUser = (id: string) => {
  void getUser(id); // Fire and forget
};

// app/user/[id]/page.tsx
import { getUser, preloadUser } from "@/lib/data";

export default async function UserPage({ params }) {
  const { id } = await params;

  // 일찍 페칭 시작
  preloadUser(id);

  // 다른 작업 수행...

  // 이 시점엔 데이터가 준비됐을 가능성이 높음
  const user = await getUser(id);
  return <div>{user.name}</div>;
}

// Server Component
async function Page() {
  const data = await fetchData();
  return <ClientComponent initialData={data} />;
}

// Client Component
("use client");
function ClientComponent({ initialData }) {
  const [data, setData] = useState(initialData);
  // ...
}

"use client";
import { useEffect, useState } from "react";

function ClientComponent() {
  const [data, setData] = useState(null);

  useEffect(() => {
    fetch("/api/data")
      .then((r) => r.json())
      .then(setData);
  }, []);

  if (!data) return <Loading />;
  return <div>{data.value}</div>;
}

"use client";
import { getData } from "./actions";
import { useEffect, useState } from "react";

function ClientComponent() {
  const [data, setData] = useState(null);

  useEffect(() => {
    getData().then(setData);
  }, []);

  return <div>{data?.value}</div>;
}

// app/api/users/route.ts
export async function GET() {
  const users = await getUsers();
  return Response.json(users);
}

export async function POST(request: Request) {
  const body = await request.json();
  const user = await createUser(body);
  return Response.json(user, { status: 201 });
}

app/
├── api/
│   └── users/
│       └── route.ts    # /api/users
└── users/
    ├── page.tsx        # /users (페이지)
    └── route.ts        # 경고: page.tsx와 충돌!

app/
├── users/
│   └── page.tsx        # /users (페이지)
└── api/
    └── users/
        └── route.ts    # /api/users (API)

// 잘못된 예: 동작하지 않음 - route handler에는 React DOM이 없어요
import { renderToString } from "react-dom/server";

export async function GET() {
  const html = renderToString(<Component />); // 에러!
  return new Response(html);
}

// app/api/users/[id]/route.ts
export async function GET(
  request: Request,
  { params }: { params: Promise<{ id: string }> },
) {
  const { id } = await params;
  const user = await getUser(id);

  if (!user) {
    return Response.json({ error: "Not found" }, { status: 404 });
  }

  return Response.json(user);
}

export async function GET(request: Request) {
  // URL과 검색 파라미터
  const { searchParams } = new URL(request.url);
  const query = searchParams.get("q");

  // 헤더
  const authHeader = request.headers.get("authorization");

  // 쿠키 (Next.js 헬퍼)
  const cookieStore = await cookies();
  const token = cookieStore.get("token");

  return Response.json({ query, token });
}

// JSON 응답
return Response.json({ data });

// 상태 코드와 함께
return Response.json({ error: "Not found" }, { status: 404 });

// 헤더와 함께
return Response.json(data, {
  headers: {
    "Cache-Control": "max-age=3600",
  },
});

// 리다이렉트
return Response.redirect(new URL("/login", request.url));

// 스트림
return new Response(stream, {
  headers: { "Content-Type": "text/event-stream" },
});

import type { Metadata } from "next";

export const metadata: Metadata = {
  title: "Page Title",
  description: "Page description for search engines",
};

import type { Metadata } from "next";

type Props = { params: Promise<{ slug: string }> };

export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const { slug } = await params;
  const post = await getPost(slug);
  return { title: post.title, description: post.description };
}

import { cache } from "react";

export const getPost = cache(async (slug: string) => {
  return await db.posts.findFirst({ where: { slug } });
});

import type { Viewport } from "next";

export const viewport: Viewport = {
  width: "device-width",
  initialScale: 1,
  themeColor: "#000000",
};

// 또는 동적으로
export function generateViewport({ params }): Viewport {
  return { themeColor: getThemeColor(params) };
}

export const metadata: Metadata = {
  title: { default: "Site Name", template: "%s | Site Name" },
};

app/
├── favicon.ico
├── opengraph-image.png     # OG와 트위터 모두 커버
├── sitemap.ts
├── robots.ts
└── layout.tsx              # title/description 메타데이터 포함

// 올바른 예
import { ImageResponse } from "next/og";

// 잘못된 예
// import { ImageResponse } from '@vercel/og'
// export const runtime = 'edge'

// app/opengraph-image.tsx
import { ImageResponse } from "next/og";

export const alt = "Site Name";
export const size = { width: 1200, height: 630 };
export const contentType = "image/png";

export default function Image() {
  return new ImageResponse(
    <div
      style={{
        fontSize: 128,
        background: "white",
        width: "100%",
        height: "100%",
        display: "flex",
        alignItems: "center",
        justifyContent: "center",
      }}
    >
      Hello World
    </div>,
    { ...size },
  );
}

// app/blog/[slug]/opengraph-image.tsx
import { ImageResponse } from "next/og";

export const alt = "Blog Post";
export const size = { width: 1200, height: 630 };
export const contentType = "image/png";

type Props = { params: Promise<{ slug: string }> };

export default async function Image({ params }: Props) {
  const { slug } = await params;
  const post = await getPost(slug);

  return new ImageResponse(
    <div
      style={{
        fontSize: 48,
        background: "linear-gradient(to bottom, #1a1a1a, #333)",
        color: "white",
        width: "100%",
        height: "100%",
        display: "flex",
        flexDirection: "column",
        alignItems: "center",
        justifyContent: "center",
        padding: 48,
      }}
    >
      <div style={{ fontSize: 64, fontWeight: "bold" }}>{post.title}</div>
      <div style={{ marginTop: 24, opacity: 0.8 }}>{post.description}</div>
    </div>,
    { ...size },
  );
}

import { ImageResponse } from "next/og";
import { join } from "path";
import { readFile } from "fs/promises";

export default async function Image() {
  const fontPath = join(process.cwd(), "assets/fonts/Inter-Bold.ttf");
  const fontData = await readFile(fontPath);

  return new ImageResponse(
    <div style={{ fontFamily: "Inter", fontSize: 64 }}>Custom Font Text</div>,
    {
      width: 1200,
      height: 630,
      fonts: [{ name: "Inter", data: fontData, style: "normal" }],
    },
  );
}

// app/blog/[slug]/opengraph-image.tsx
import { ImageResponse } from "next/og";

export async function generateImageMetadata({ params }) {
  const images = await getPostImages(params.slug);
  return images.map((img, idx) => ({
    id: idx,
    alt: img.alt,
    size: { width: 1200, height: 630 },
    contentType: "image/png",
  }));
}

export default async function Image({ params, id }) {
  const images = await getPostImages(params.slug);
  const image = images[id];
  return new ImageResponse(/* ... */);
}

// app/sitemap.ts
import type { MetadataRoute } from "next";

export async function generateSitemaps() {
  // 사이트맵 ID 배열 반환
  return [{ id: 0 }, { id: 1 }, { id: 2 }];
}

export default async function sitemap({
  id,
}: {
  id: number;
}): Promise<MetadataRoute.Sitemap> {
  const start = id * 50000;
  const end = start + 50000;
  const products = await getProducts(start, end);

  return products.map((product) => ({
    url: `https://example.com/product/${product.id}`,
    lastModified: product.updatedAt,
  }));
}

// 잘못된 예: 네이티브 img 피하기
<img src="/hero.png" alt="Hero" />;

// 올바른 예: next/image 사용
import Image from "next/image";
<Image src="/hero.png" alt="Hero" width={800} height={400} />;

// 로컬 이미지 - 크기 자동 추론
import heroImage from './hero.png'
<Image src={heroImage} alt="Hero" />

// 원격 이미지 - width/height 명시 필수
<Image src="https://example.com/image.jpg" alt="Hero" width={800} height={400} />

// 또는 부모 기준 크기 조정에 fill 사용
<div style={{ position: 'relative', width: '100%', height: 400 }}>
  <Image src="/hero.png" alt="Hero" fill style={{ objectFit: 'cover' }} />
</div>

// next.config.js
module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: "https",
        hostname: "example.com",
        pathname: "/images/**",
      },
      {
        protocol: "https",
        hostname: "*.cdn.com", // 와일드카드 서브도메인
      },
    ],
  },
};

// 전체 너비 히어로
<Image
  src="/hero.png"
  alt="Hero"
  fill
  sizes="100vw"
/>

// 반응형 그리드 (데스크톱 3열, 모바일 1열)
<Image
  src="/card.png"
  alt="Card"
  fill
  sizes="(max-width: 768px) 100vw, 33vw"
/>

// 고정 크기 사이드바 이미지
<Image
  src="/avatar.png"
  alt="Avatar"
  width={200}
  height={200}
  sizes="200px"
/>

// 로컬 이미지 - 자동 blur 해시
import heroImage from './hero.png'
<Image src={heroImage} alt="Hero" placeholder="blur" />

// 원격 이미지 - blurDataURL 제공
<Image
  src="https://example.com/image.jpg"
  alt="Hero"
  width={800}
  height={400}
  placeholder="blur"
  blurDataURL="data:image/jpeg;base64,/9j/4AAQSkZJRg..."
/>

// 또는 색상 플레이스홀더 사용
<Image
  src="https://example.com/image.jpg"
  alt="Hero"
  width={800}
  height={400}
  placeholder="empty"
  style={{ backgroundColor: '#e0e0e0' }}
/>

// 히어로 이미지 - 즉시 로드
<Image src="/hero.png" alt="Hero" fill priority />

// 스크롤 아래 이미지 - 기본으로 지연 로드 (priority 불필요)
<Image src="/card.png" alt="Card" width={400} height={300} />

// 잘못된 예: fill에 sizes 누락 - 가장 큰 이미지를 다운로드
<Image src="/hero.png" alt="Hero" fill />

// 올바른 예: 올바른 반응형 동작을 위해 sizes 추가
<Image src="/hero.png" alt="Hero" fill sizes="100vw" />

// 잘못된 예: 종횡비 용도로만 width/height 사용
<Image src="/hero.png" alt="Hero" width={16} height={9} />

// 올바른 예: 실제 표시 크기를 쓰거나 fill + sizes 사용
<Image src="/hero.png" alt="Hero" fill sizes="100vw" style={{ objectFit: 'cover' }} />

// 잘못된 예: 설정 없는 원격 이미지
<Image src="https://untrusted.com/image.jpg" alt="Image" width={400} height={300} />
// 에러: Invalid src prop, hostname not configured

// 올바른 예: next.config.js remotePatterns에 hostname 추가

// 옵션 1: 최적화 비활성화
<Image src="/hero.png" alt="Hero" width={800} height={400} unoptimized />;

// 옵션 2: 전역 설정
// next.config.js
module.exports = {
  output: "export",
  images: { unoptimized: true },
};

// 옵션 3: 커스텀 로더 (Cloudinary, Imgix 등)
const cloudinaryLoader = ({ src, width, quality }) => {
  return `https://res.cloudinary.com/demo/image/upload/w_${width},q_${quality || 75}/${src}`;
};

<Image
  loader={cloudinaryLoader}
  src="sample.jpg"
  alt="Sample"
  width={800}
  height={400}
/>;

// app/layout.tsx
import { Inter } from "next/font/google";

const inter = Inter({ subsets: ["latin"] });

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en" className={inter.className}>
      <body>{children}</body>
    </html>
  );
}

import { Inter, Roboto_Mono } from "next/font/google";

const inter = Inter({
  subsets: ["latin"],
  variable: "--font-inter",
});

const robotoMono = Roboto_Mono({
  subsets: ["latin"],
  variable: "--font-roboto-mono",
});

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en" className={`${inter.variable} ${robotoMono.variable}`}>
      <body>{children}</body>
    </html>
  );
}

body {
  font-family: var(--font-inter);
}

code {
  font-family: var(--font-roboto-mono);
}

// 단일 두께
const inter = Inter({
  subsets: ["latin"],
  weight: "400",
});

// 다중 두께
const inter = Inter({
  subsets: ["latin"],
  weight: ["400", "500", "700"],
});

// 가변 폰트 (권장) - 모든 두께 포함
const inter = Inter({
  subsets: ["latin"],
  // weight 불필요 - 가변 폰트는 모든 두께를 지원
});

// 이탤릭 포함
const inter = Inter({
  subsets: ["latin"],
  style: ["normal", "italic"],
});

import localFont from "next/font/local";

const myFont = localFont({
  src: "./fonts/MyFont.woff2",
});

// 두께별 여러 파일
const myFont = localFont({
  src: [
    {
      path: "./fonts/MyFont-Regular.woff2",
      weight: "400",
      style: "normal",
    },
    {
      path: "./fonts/MyFont-Bold.woff2",
      weight: "700",
      style: "normal",
    },
  ],
});

// 가변 폰트
const myFont = localFont({
  src: "./fonts/MyFont-Variable.woff2",
  variable: "--font-my-font",
});

// app/layout.tsx
import { Inter } from "next/font/google";

const inter = Inter({
  subsets: ["latin"],
  variable: "--font-inter",
});

export default function RootLayout({ children }) {
  return (
    <html lang="en" className={inter.variable}>
      <body>{children}</body>
    </html>
  );
}

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      fontFamily: {
        sans: ["var(--font-inter)"],
      },
    },
  },
};

// Latin만 (가장 흔한 경우)
const inter = Inter({ subsets: ["latin"] });

// 다중 서브셋
const inter = Inter({ subsets: ["latin", "latin-ext", "cyrillic"] });

const inter = Inter({
  subsets: ["latin"],
  display: "swap", // 기본값 - 폴백을 보여주고 로드되면 교체
});

// 옵션:
// 'auto' - 브라우저가 결정
// 'block' - 짧은 블록 기간 후 교체
// 'swap' - 즉시 폴백, 준비되면 교체 (권장)
// 'fallback' - 짧은 블록, 짧은 교체, 이후 폴백
// 'optional' - 짧은 블록, 교체 없음 (폰트가 선택적일 때 사용)

// 잘못된 예: 수동 link 태그 (렌더링 차단, 최적화 없음)
<link href="https://fonts.googleapis.com/css2?family=Inter" rel="stylesheet" />

// 잘못된 예: display와 preconnect 누락
<link href="https://fonts.googleapis.com/css2?family=Inter" rel="stylesheet" />

// 올바른 예: next/font 사용 (셀프 호스팅, 레이아웃 시프트 제로)
import { Inter } from 'next/font/google'

const inter = Inter({ subsets: ['latin'] })

// 잘못된 예: 모든 컴포넌트에서 폰트 import
// components/Button.tsx
import { Inter } from "next/font/google";
const inter = Inter({ subsets: ["latin"] }); // 매번 새 인스턴스 생성!

// 올바른 예: 레이아웃에서 한 번 import 후 CSS 변수 사용
// app/layout.tsx
const inter = Inter({ subsets: ["latin"], variable: "--font-inter" });

/* 잘못된 예: CSS에서 @import 사용 (렌더링 차단) */
/* globals.css */
@import url("https://fonts.googleapis.com/css2?family=Inter");

// 올바른 예: next/font 사용 (셀프 호스팅, 네트워크 요청 없음)
import { Inter } from "next/font/google";

// 잘못된 예: 일부만 쓰는데 모든 두께를 로드
const inter = Inter({ subsets: ["latin"] }); // 모든 두께 로드

// 올바른 예: 필요한 두께만 지정 (가변 폰트가 아닌 경우)
const inter = Inter({ subsets: ["latin"], weight: ["400", "700"] });

// 잘못된 예: subset 누락 - 모든 문자를 로드
const inter = Inter({});

// 올바른 예: 항상 subset 지정
const inter = Inter({ subsets: ["latin"] });

// 컴포넌트별 폰트는 공유 파일에서 export
// lib/fonts.ts
import { Inter, Playfair_Display } from "next/font/google";

export const inter = Inter({ subsets: ["latin"], variable: "--font-inter" });
export const playfair = Playfair_Display({
  subsets: ["latin"],
  variable: "--font-playfair",
});

// components/Heading.tsx
import { playfair } from "@/lib/fonts";

export function Heading({ children }) {
  return <h1 className={playfair.className}>{children}</h1>;
}

ReferenceError: window is not defined
ReferenceError: document is not defined
ReferenceError: localStorage is not defined
Module not found: Can't resolve 'fs'

// 잘못된 예: 실패 - 패키지가 window 사용
import SomeChart from "some-chart-library";

export default function Page() {
  return <SomeChart />;
}

// 올바른 예: ssr: false로 dynamic import 사용
import dynamic from "next/dynamic";

const SomeChart = dynamic(() => import("some-chart-library"), {
  ssr: false,
});

export default function Page() {
  return <SomeChart />;
}

// next.config.js
module.exports = {
  serverExternalPackages: ["problematic-package"],
};

// components/ChartWrapper.tsx
"use client";

import { Chart } from "chart-library";

export function ChartWrapper(props) {
  return <Chart {...props} />;
}

// app/page.tsx (서버 컴포넌트)
import { ChartWrapper } from "@/components/ChartWrapper";

export default function Page() {
  return <ChartWrapper data={data} />;
}

// 잘못된 예: 수동 link 태그
<link rel="stylesheet" href="/styles.css" />;

// 올바른 예: CSS import
import "./styles.css";

// 올바른 예: CSS Modules
import styles from "./Button.module.css";