Next.js 15.5

https://nextjs.org/blog/next-15-5

Next.js 15.5에는 Turbopack 빌드(베타), 안정화된 Node.js 미들웨어, TypeScript 개선, ‎next lint⁠ 폐기, Next.js 16에 대한 폐기 경고가 포함되어 있습니다. 이번 릴리스의 주요 내용은 다음과 같습니다:

Turbopack 빌드(베타): 프로덕션 turbopack 빌드(next build --turbopack⁠)가 이제 베타로 제공됩니다
Node.js 미들웨어(안정화): 미들웨어의 Node.js 런타임 지원이 이제 안정화되었습니다
TypeScript 개선: 타입드 라우트, 라우트 내보내기 검증, 라우트 타입 헬퍼
next lint⁠: next lint⁠ 명령어 폐기
Next.js 16: Next.js 16에 대한 폐기 경고

지금 업그레이드하거나 다음과 같이 시작할 수 있습니다:

# 자동 업그레이드 CLI 사용
npx @next/codemod@canary upgrade latest

# ...또는 수동 업그레이드
npm install next@latest react@latest react-dom@latest

# ...또는 새 프로젝트 시작
npx create-next-app@latest

Turbopack 빌드(베타)

next build --turbopack⁠의 베타 출시를 알리게 되어 기쁩니다. Turbopack은 이제 vercel.com , v0.app, nextjs.org 등 Vercel 웹사이트의 배포 빌드를 가속화하여, 더 빠른 프리뷰 및 프로덕션 배포 빌드를 제공합니다.

Turbopack이 적용된 이 애플리케이션들은 롤아웃 이후 12억 건 이상의 요청을 처리하며 실전에서 검증되었습니다.

성능 및 프로덕션 결과

Turbopack의 원래 설계 목표 중 하나는 애플리케이션과 코드베이스가 커질수록 빌드 성능을 확장할 수 있도록 돕는 것이었습니다. 이를 위해 Turbopack은 빌드의 모든 단계에서 여러 CPU 코어를 최대한 활용하도록 처음부터 설계되었습니다.

Turbopack 빌드를 다양한 Vercel 제품에 배포한 결과, 컴파일 시간에서 일관된 개선을 확인했습니다:

고객 사이트: 4코어 머신에서 2배 빨라짐
고객 사이트: 14코어 머신에서 2.2배 빨라짐
소형 사이트(10K 모듈): 30코어 머신에서 4배 빨라짐
중형 사이트(40K 모듈): 30코어 머신에서 2.5배 빨라짐
대형 사이트(70K 모듈): 30코어 머신에서 5배 빨라짐

주요 웹 애플리케이션에 Turbopack을 적용하면서 프로덕션 성능 저하나 장애가 없는지 면밀히 모니터링했습니다.

Webpack과 비교했을 때, Turbopack으로 빌드된 사이트는 비슷하거나 더 적은 양의 JavaScript와 CSS를 더 적은 요청으로 제공하여, FCP, LCP, TTFB 지표에서 동등하거나 더 나은 결과를 보였습니다.

개발 환경에서 Turbopack을 도입한 팀에게는 이제 빌드에도 Turbopack 사용을 권장합니다.

알려진 차이점

소규모 프로젝트: 소형 머신이나 소규모 프로젝트에서는 Webpack의 내장 영속 캐시 덕분에 빌드 시간이 소폭 개선되거나 비슷한 수준임을 확인했습니다. 현재 Turbopack의 영속 캐싱 솔루션을 개발 중이며, 모든 빌드를 점진적이고 빠르게 만드는 설계 목표를 달성할 예정입니다.

번들 최적화: 일부 엣지 케이스에서는 webpack이 더 최적화된 번들을 생성하는 경우가 있었습니다. 해당 시나리오를 추적 중이며, 정식 릴리스 전까지 격차를 해소할 예정입니다. 자세한 내용은 번들 크기 문서를 참고하세요.

CSS 순서: Turbopack의 부작용 처리 방식이 달라 CSS 파일이 webpack과 다른 순서로 병합될 수 있어, 시각적 차이가 발생할 수 있습니다. 자세한 설명과 해결 방법은 문서를 참고하세요.

참고: 이러한 차이점은 문서화되어 있으며, 지속적으로 개선 중입니다. 자세한 정보와 우회 방법은 Turbopack 문서를 참고하세요.

정식 릴리스를 향해 나아가며, GitHub에 이슈를 보고해 주세요.

Node.js 미들웨어(안정화)

15.2 릴리스에서 Node.js 런타임의 실험적 지원을 도입하고, 프로덕션 애플리케이션에서 충분히 테스트한 결과, Node.js 미들웨어 런타임의 안정화 지원을 발표합니다.

이전에는 Next.js 미들웨어가 Edge Runtime만 지원하여, 성능과 격리 측면에서는 장점이 있었으나 Node.js 전용 라이브러리 및 API와의 통합에는 한계가 있었습니다.

middleware.ts

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

export const config = {
  runtime: "nodejs", // 이제 안정화!
};

export function middleware(request: NextRequest) {
  // 전체 Node.js API 및 npm 패키지 사용 가능
  const fs = require("fs");
  const crypto = require("crypto");
  // 복잡한 인증 로직
  const token = request.headers.get("authorization");
  if (!isValidToken(token)) {
    return NextResponse.redirect(new URL("/login", request.url));
  }
  return NextResponse.next();
}

function isValidToken(token: string | null): boolean {
  // Node.js crypto로 검증
  // 파일 시스템, 데이터베이스 등 접근 가능
  return true;
}

이 변경으로 미들웨어가 더 복잡한 사용 사례를 처리할 수 있으면서도 동일한 개발자 경험을 유지할 수 있습니다.

Node.js 런타임이 Next.js 16에서 기본값이 되지는 않지만, 커뮤니티 피드백과 사용 패턴을 바탕으로 Next.js 17부터 기본값 적용을 검토 중입니다.

TypeScript 개선

Next.js 15.5는 App Router에 대한 주요 TypeScript 개선을 도입하여, Turbopack과 완벽하게 호환되고 라우팅에 대한 포괄적인 타입 안전성을 제공합니다.

타입드 라우트(안정화)

타입드 라우트는 애플리케이션의 라우트에 대해 컴파일 타임 타입 안전성을 제공하여, 잘못된 링크가 프로덕션에 반영되기 전에 잡아냅니다. 이 기능은 파일 구조를 기반으로 자동으로 타입을 생성하여, 모든 <Link>⁠ 컴포넌트가 유효한 라우트를 가리키도록 보장합니다.

이 기능은 이전에는 실험적이었던 typedRoutes⁠ 플래그를 통해 제공되었으나, 이제 안정화되었습니다. 정적으로 타입드된 라우트는 Turbopack에서도 새로운 구현을 통해 동작하며, Webpack과 Turbopack 빌드 모두에서 타입 안전성을 제공합니다:

next.config.ts

const nextConfig = {
  typedRoutes: true, // Now stable!
};

export default nextConfig;

import Link from 'next/link'

// 라우트 경로에 대한 완전한 타입 안전성
<Link href="/blog/example-slug?ui=dark">Read Post</Link>

// 잘못된 라우트는 컴파일 타임에 TypeScript 에러 발생
<Link href="/invalid-route">Broken Link</Link> // ← 타입 에러

라우트 내보내기 검증(Turbopack)

라우트 내보내기 검증도 Turbopack에서 새로운 시스템을 통해 동작하며, TypeScript의 satisfies⁠ 연산자를 사용해 페이지, 레이아웃, 라우트 핸들러를 검증하는 타입 가드 파일을 생성합니다.

이로써 next build⁠ 실행 시 잘못된 dynamic⁠ 값 등 잘못된 내보내기를 컴파일 단계에서 잡아내며, 기존 Webpack 플러그인을 대체하는 더 성능 좋은 솔루션을 제공합니다.

라우트 Props 헬퍼

Next.js는 이제 전역적으로 사용할 수 있는 PageProps⁠, LayoutProps⁠, RouteContext⁠ 타입을 자동 생성하여, 전체 파라미터 타입 지정과 별도의 import 없이 사용할 수 있습니다:

이전: 수동 타입 지정 및 import 필요

import { Metadata } from "next";

interface Props {
  params: Promise<{ slug: string }>;
  children: React.ReactNode;
  analytics: React.ReactNode; // 병렬 라우트 수동 타입 지정
  team: React.ReactNode; // 병렬 라우트 수동 타입 지정
}

export default function DashboardLayout(props: Props) {
  return (
    <div>
      {props.children}
      {props.analytics} {/* 병렬 라우트에 타입 안전성 없음 */}
      {props.team} {/* 병렬 라우트에 타입 안전성 없음 */}
    </div>
  );
}

이후: 병렬 라우트 지원이 포함된 자동 타입 지정

// LayoutProps import 불필요 - 전역 사용 가능
export default function DashboardLayout(props: LayoutProps<"/dashboard">) {
  return (
    <div>
      {props.children}
      {props.analytics} {/* 병렬 라우트 슬롯에 완전한 타입 지정 */}
      {props.team} {/* 병렬 라우트 슬롯에 완전한 타입 지정 */}
    </div>
  );
}

이 시스템은 파일 구조에서 라우트를 자동으로 탐지하며, 동적 라우트, 병렬 라우트, next.config.js⁠의 커스텀 라우트도 지원합니다. 타입 생성은 개발 및 빌드 모드 모두에서 실행되며, 개발 중 파일 구조가 변경되면 즉시 타입을 재생성합니다. 또한, 이전 구현과 달리 많은 개별 파일 대신 최적화된 소수의 파일만 생성하여 대규모 프로젝트에도 효율적으로 확장됩니다.

next typegen⁠

next typegen⁠ 명령어가 추가되어, next dev⁠나 next build⁠를 실행하지 않고도 수동으로 타입을 생성할 수 있습니다. 이는 외부 타입 검증 시 특히 유용합니다.

next typegen [directory]

이전에는 라우트 타입이 ‎⁠next dev⁠나 next build⁠ 중에만 생성되어, tsc --noEmit⁠만 실행하면 라우트 타입 검증이 불가능했습니다. 이제 타입을 독립적으로 생성하고 외부에서 검증할 수 있습니다:

# 먼저 라우트 타입을 생성한 뒤 TypeScript로 검증
next typegen && tsc --noEmit

# 또는 빌드 없이 CI 워크플로에서 타입 체크
next typegen && npm run type-check

next lint⁠ 폐기

Next.js 15.5부터 next lint⁠ 명령어는 폐기 경고를 표시하며, Next.js 16에서 제거될 예정입니다. 이는 명시적 ESLint 설정으로 린팅 경험을 현대화하고, 빠른 대안인 Biome을 도입하기 위함입니다.

새로운 Next.js 프로젝트를 생성할 때, ESLint(포괄적 규칙), Biome(빠르지만 규칙 적음), 린터 없음 중에서 선택할 수 있습니다. ESLint 프로젝트는 이제 next lint⁠ 명령어 래퍼 대신 명시적인 eslint.config.mjs⁠ 파일을 생성하여, 린팅 규칙을 완전히 투명하게 관리할 수 있습니다.

Biome 프로젝트는 Next.js 및 React 규칙과 내장 포매팅 기능이 포함된 최적화된 설정을 받습니다. 생성된 package.json⁠ 스크립트는 이제 린터를 직접 호출합니다:

{
  scripts: {
    // ESLint 프로젝트
    lint: "eslint", // "next lint" 대신
    "lint:fix": "eslint --fix",
    // Biome 프로젝트
    lint: "biome check",
    format: "biome format --write",
  },
}

기존 프로젝트의 경우, 새로운 codemod가 next lint⁠에서 ESLint CLI로의 마이그레이션을 자동화합니다:

npx @next/codemod@latest next-lint-to-eslint-cli .

codemod는 Next.js 전용 플래그(--strict⁠ 등)를 --max-warnings 0⁠으로 매핑하고, 필요한 의존성을 자동 설치하는 등, 기능을 보존하면서 package.json⁠ 스크립트를 지능적으로 변환합니다.

이 전환을 통해 개발자는 린팅 설정을 직접 제어할 수 있으며, 생태계 호환성도 향상됩니다.

참고: next build⁠는 ESLint 설정이 있으면 여전히 린팅 검증 단계를 실행합니다. 이 자동 린팅은 Next.js 16에서 제거되어, 언제 어떻게 린팅을 실행할지 완전히 제어할 수 있게 됩니다.

Next.js 16 폐기 경고

Next.js 15.5는 다가오는 Next.js 16 릴리스를 대비할 수 있도록 폐기 경고를 도입합니다. 이 경고는 개발 및 빌드 로그에 표시되어, 해당 기능이 제거되기 전에 미리 마이그레이션할 시간을 제공합니다.

`next/link`⁠의 `legacyBehavior⁠`

next/link⁠의 legacyBehavior⁠ prop은 Next.js 16에서 제거됩니다. 이 prop은 Next.js 12에서 13으로 전환할 때 임시 호환 레이어로 도입되었습니다.

// ❌ Next.js 16에서 제거 예정
<Link href="/about" legacyBehavior>
  <a>About</a>
</Link>

// ✅ 최신 방식(변경 불필요)
<Link href="/about">About</Link>

마이그레이션: legacyBehavior⁠ prop과 자식 <a>⁠ 요소를 제거하세요. 이제 Link⁠ 컴포넌트가 스타일링과 접근성을 자동으로 처리합니다.

AMP 지원

Next.js AMP 지원은 Next.js 16에서 제거됩니다. AMP 채택이 크게 감소했고, 이 기능을 유지하는 것이 프레임워크의 복잡성을 높이기 때문입니다. 모든 AMP 관련 API와 설정이 제거됩니다.

pages/amp-page.js

// ❌ Next.js 16에서 제거 예정
import { useAmp } from "next/amp";

export const config = { amp: true };

export default function AmpPage() {
  const isAmp = useAmp();
  return <div>AMP Page: {isAmp ? "AMP" : "HTML"}</div>;
}

next.config.ts

const nextConfig = {
  amp: {
    // ❌ Next.js 16에서 제거 예정
    canonicalBase: "https://example.com",
  },
};

export default nextConfig;

마이그레이션: 다음을 포함한 모든 AMP 관련 코드를 제거하세요:

페이지의 export const config = { amp: true }⁠
next.config.ts⁠의 amp⁠ 설정
next/amp⁠ 훅 import 및 사용(useAmp⁠)
기타 AMP 전용 API

AMP가 여전히 필요한지 평가하세요. 대부분의 성능 이점은 이제 Next.js의 내장 최적화 및 최신 웹 표준으로 달성할 수 있습니다.

next/image⁠ 품질 설정

Next.js 16부터는 quality⁠ prop이 기본적으로 75⁠만 허용됩니다. 현재 Next.js 15에서는 1~100 사이의 임의 정수를 사용할 수 있지만, Next.js 16에서는 75 이외의 값을 사용하려면 명시적으로 설정해야 합니다.

// ⚠️ Next.js 15.5에서 폐기 경고 표시
// images.qualities가 정의되지 않고 quality !== 75인 경우
<Image src="/photo.jpg" quality={100} alt="Photo" />

next.config.ts

// ✅ Next.js 16을 위한 명시적 설정 필요

next.config.tsconst nextConfig = {
  images: {
    qualities: [75, 100], // quality={100} 허용
  },
};

export default nextConfig;

마이그레이션: 75 이외의 quality⁠ prop을 사용하는 경우, Next.js 16을 위해 next.config.ts⁠의 images.qualities⁠에 필요한 값을 명시적으로 추가하세요.

next/image⁠ 로컬 패턴

Next.js 16부터는 로컬 이미지 src⁠ 경로에 쿼리 문자열을 사용하는 경우, images.localPatterns⁠에 명시적으로 설정해야 합니다. 이는 캐시 무효화나 버전 관리 등 쿼리 파라미터가 포함된 이미지에 영향을 줍니다.

// ⚠️ Next.js 15.5에서 폐기 경고 표시
// images.localPatterns가 설정되지 않은 경우
<Image src="/photo.jpg?v=1" alt="Test" />

next.config.ts

// ✅ Next.js 16을 위한 명시적 설정 필요

next.config.tsconst nextConfig = {
  images: {
    localPatterns: [
      {
        pathname: '/photo.jpg', // 정확한 경로 허용
        // "search" 생략 시 모든 쿼리 파라미터 허용
      },
      {
        pathname: '/photo.jpg', // 정확한 경로 허용
        search: '?v=1', // 정확한 쿼리 파라미터 허용
      },
      {
        pathname: '/assets/**', // 와일드카드 경로 허용
        search: '', // 빈 search는 모든 쿼리 파라미터 차단
      },
    ],
  },
};

export default nextConfig;

마이그레이션: 이미지 경로에 쿼리 문자열을 허용하려면, next.config.ts⁠의 images.localPatterns⁠에 명시적으로 설정하세요. 이는 보안 및 성능 최적화에 도움이 됩니다.

타임라인

이러한 폐기 경고는 Next.js 15.5부터 표시됩니다. 해당 기능은 Next.js 16에서 완전히 제거될 예정이니, 업그레이드 시 문제가 없도록 미리 마이그레이션을 권장합니다.

Next.js 15.5

Turbopack 빌드(베타)

성능 및 프로덕션 결과

알려진 차이점

Node.js 미들웨어(안정화)

TypeScript 개선

타입드 라우트(안정화)

라우트 내보내기 검증(Turbopack)

라우트 Props 헬퍼

next typegen⁠

next lint⁠ 폐기

Next.js 16 폐기 경고

next/link⁠의 legacyBehavior⁠

AMP 지원

next/image⁠ 품질 설정

next/image⁠ 로컬 패턴

타임라인

On this Page

`next/link`⁠의 `legacyBehavior⁠`