software

Next.js 16 타입 안전성: 비동기 PageProps 및 타입 지정 라우트

발행: (2025년 12월 23일 오전 05:57 GMT+9)
6 min read
원문: Dev.to

Source: Dev.to

소개

Next.js는 조용히 가장 타입‑안전한 풀‑스택 프레임워크 중 하나가 되었지만, 많은 팀이 그 기능의 일부만 사용하고 있습니다. 이 글에서는 최신 App Router에서 실무에 바로 적용할 수 있는 프로덕션‑레디 타입‑안전 기능들을 살펴봅니다. 포함 내용은 다음과 같습니다.

  • TypeScript 검사기 향상
  • 정적 타입 링크
  • 라우트 인식 타입 헬퍼
  • 환경 변수 자동 완성
  • 타입이 지정된 NextRequest와 NextResponse

이는 초보자용 가이드가 아니라, 실제 애플리케이션에서 버그를 방지하는 기능에 초점을 맞춘 글입니다.

TypeScript 검사기

Next.js는 기본 tsc 검사를 확장하는 맞춤형 TypeScript 플러그인을 제공합니다. 이 플러그인은 Next.js‑특화 개념을 이해합니다:

  • 파일 기반 라우팅
  • 서버와 클라이언트 컴포넌트 구분
  • 메타데이터 API
  • 레이아웃 및 페이지 규칙

VS Code에서 플러그인 활성화하기

  1. 명령 팔레트(Ctrl/Cmd + Shift + P)를 엽니다.
  2. TypeScript: Select TypeScript Version을 검색합니다.
  3. Use Workspace Version을 선택합니다.

VS Code는 이제 next-env.d.ts를 통해 Next.js‑특화 타입 규칙을 자동으로 적용하여 메타데이터 및 캐싱 옵션과 같은 API에 대한 IntelliSense와 인‑컨텍스트 문서를 제공합니다.

플러그인이 제공하는 추가 검사

  • "use client" 지시어의 올바른 사용 여부.
  • 서버 컴포넌트에서 클라이언트 전용 훅(예: useState) 사용 방지.
  • page.tsx, layout.tsx, route.ts에서의 잘못된 내보내기 감지.

정적 타입 링크

Next.js는 오타와 잘못된 탐색을 방지하기 위해 정적으로 타입이 지정된 라우트를 생성할 수 있습니다.

타입 라우트 활성화

// next.config.ts
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  typedRoutes: true,
};

export default nextConfig;

typedRoutes가 활성화되면 Next.js는 .next/types 내부에 라우트 정의를 생성합니다. TypeScript는 컴파일 시점에 링크와 탐색을 검증하여 다음을 제공합니다:

  • 잘못된 라우트에 대한 컴파일‑시간 오류
  • 더 안전한 리팩터링
  • 유효한 경로만 제안하는 IntelliSense

Source: …

라우트‑인식 헬퍼

App Router는 next dev, next build 또는 next typegen 실행 시 전역 헬퍼를 자동으로 생성합니다(임포트 필요 없음).

사용 가능한 헬퍼

  • PageProps – 페이지 컴포넌트용 타입이 지정된 props
  • LayoutProps – 레이아웃 컴포넌트용 타입이 지정된 props
  • RouteContext – API 라우트용 타입이 지정된 컨텍스트

PageProps 사용하기

// pages/details/[slotId]/page.tsx
export default function Details({
  params,
  searchParams,
}: {
  params: { slotId: string };
  searchParams: { name?: string };
}) {
  const { slotId } = params;
  const { name } = searchParams;

  return (
    <>
      Slot: {slotId}
      <br />
      Name: {name}
    </>
  );
}

보다 간결하고 타입‑안전한 버전:

export default async function Details(
  props: PageProps
) {
  const { slotId } = await props.params;
  const { name } = await props.searchParams;

  return (
    <>
      Slot: {slotId}
      <br />
      Name: {name}
    </>
  );
}

LayoutProps 사용하기

import type { ReactNode } from "react";

export default function RootLayout({
  children,
}: {
  children: ReactNode;
}) {
  return (
    <>
      {children}
    </>
  );
}

타입이 지정된 버전:

export default function RootLayout(
  props: LayoutProps
) {
  return (
    <>
      {props.children}
    </>
  );
}

API 라우트에서 RouteContext 사용하기

import { NextRequest, NextResponse } from "next/server";

export async function GET(
  _request: NextRequest,
  ctx: RouteContext
) {
  const { id } = await ctx.params;

  return NextResponse.json({ msg: `Hello, ${id}!` });
}

RouteContext는 라우트 매개변수에 대한 완전한 IntelliSense를 제공하여 수동 타이핑을 없애줍니다.

타입이 지정된 NextRequest와 NextResponse

두 클래스 모두 표준 Web API를 확장하여 Next‑전용 헬퍼를 제공합니다.

NextRequest

  • 타입이 지정된 쿠키
  • nextUrl을 통한 파싱된 URL
  • 미들웨어 친화적인 헬퍼

NextResponse

  • json() – JSON 응답 전송
  • redirect() – 리다이렉트 수행
  • 쿠키 헬퍼
  • 엣지 친화적인 API

예시:

import { NextRequest, NextResponse } from "next/server";

export async function GET(_request: NextRequest) {
  return NextResponse.json({ msg: "Hello!!!" });
}

결론

Next.js 타입 안전성은 더 많은 타입을 작성하는 것이 아니라, 오버헤드 없이 버그를 줄이는 가드레일로 TypeScript를 사용하는 것입니다. 내장 TypeScript 플러그인, 타입된 라우트, 라우트 인식 헬퍼를 활성화하면 컴파일 타임 보장과 풍부한 에디터 지원을 애플리케이션 전반에 걸쳐 얻을 수 있습니다.

Reference: Next.js – TypeScript documentation

Back to Blog

관련 글

더 보기 »