Next.js 크로스 플랫폼: 어댑터, OpenNext, 그리고 우리의 약속

Next.js Across Platforms: Adapters, OpenNext, and Our Commitments

📅 2026-03-29 📰 Next.js Blog

요약

Next.js 16.2는 OpenNext, Netlify, Cloudflare, AWS Amplify, Google Cloud와 협력하여 안정적인 Adapter API를 출시했습니다. 이 API는 Next.js 빌드 출력을 타입화된 버전으로 제공하여 모든 플랫폼이 공통의 계약을 기반으로 배포할 수 있으며, 공유 테스트 스위트와 검증된 어댑터로 모든 제공자가 동일한 정확성 기준을 따르도록 합니다.

핵심 포인트

Adapter API는 타입화되고 버전 관리되는 Next.js 애플리케이션 설명으로, 라우트, 사전 렌더 페이지, 정적 자산, 런타임 대상, 의존성, 캐싱 규칙, 라우팅 결정을 포함합니다. 어댑터는 modifyConfig(설정 로드 시)와 onBuildComplete(전체 출력 준비 시) 두 개의 훅을 구현하며, Breaking changes는 Next.js의 새로운 메이저 버전을 필요로 합니다.
OpenNext는 Next.js 빌드 출력을 제공자의 기반 인프라에 매핑하는 호환성 계층으로 시작했으나, AWS에서 프로덕션 등급 어댑터로 발전했고, 2025년 4월 Build Adapters RFC 발표와 함께 Netlify, Cloudflare, AWS Amplify, Google Cloud 엔지니어와의 광범위한 협력이 이루어졌습니다.
공유 테스트 스위트는 어댑터 저자가 스트리밍 동작, 캐싱 상호작용, 클라이언트 네비게이션, 실제 엣지 케이스를 포함한 테스트를 실행하고 통과/실패를 얻을 수 있습니다. Vercel의 어댑터도 이 동일한 테스트 스위트를 사용하므로 모든 제공자가 동일한 정확성 기준을 만족합니다.
검증된 어댑터(Next.js GitHub 조직 아래 호스팅되고 배포 문서에 나열)가 되려면 오픈소스이고 전체 테스트 스위트를 통과해야 하며, 이는 커뮤니티 주도의 투명한 검증 프로세스입니다.
Vercel의 어댑터는 공개 API를 사용하며 개인 훅이나 특수 통합 경로가 없으므로, 모든 플랫폼이 동등하게 취급됩니다.
렌더링 철학, 플랫폼 배포 기능 매트릭스, PPR 플랫폼 가이드, 재검증 작동 방식, CDN 캐싱 등 플랫폼 통합 관련 문서가 광범위하게 재정리되어 제공자들이 정확히 이해할 수 있습니다.

왜 중요한가

Adapter API의 안정화와 공유 테스트 스위트는 Next.js가 모든 플랫폼에서 일관되게 작동함을 보장하며, 개발자는 배포 플랫폼을 선택해도 동일한 기능과 성능을 기대할 수 있습니다. 또한 OpenNext 같은 커뮤니티 프로젝트의 기여가 공식 인프라에 통합되는 모델은 오픈소스 생태계의 건강성을 보여줍니다.

📄 전문 번역

Next.js 16.2: 모든 플랫폼을 지원하기 위한 어댑터 API의 도입

Next.js 16.2에서 안정적인 어댑터 API를 공개했습니다. OpenNext, Netlify, Cloudflare, AWS Amplify, Google Cloud와의 협업을 통해 만들어진 이 API는 모든 배포 플랫폼에서 Next.js가 잘 작동하도록 보장하는 데 목표를 두고 있습니다.

핵심 내용을 먼저 정리하면 다음과 같습니다:

어댑터 API (안정화): 타입이 정의되고 버전이 관리되는 애플리케이션 명세로, 모든 플랫폼이 이를 바탕으로 구현할 수 있습니다.
테스트 스위트: Vercel을 포함한 모든 어댑터가 통과해야 하는 공통 검증 테스트입니다.
검증된 어댑터: Next.js 조직 하에서 관리하는 오픈소스 어댑터들입니다.
생태계 워킹그룹: 여러 제공자 간의 변경사항을 조율하기 위한 정기적인 포럼입니다.

이 과정까지 어떻게 왔을까요?

대부분의 Next.js 애플리케이션은 next start로 실행하는 단일 Node.js 서버로 배포됩니다. 현재 수백만 개의 팀이 다양한 플랫폼에서 이렇게 운영하고 있죠.

그런데 앱을 키우다 보면 여러 개의 서버 인스턴스를 실행하게 됩니다. 이때부터는 기본적으로 잘 작동해야 하는 것들이 생깁니다. 캐시된 콘텐츠가 인스턴스 간에 동기화되어야 하고, 온디맨드 재검증이 전파되어야 하며, 스트리밍이 안정적으로 작동해야 한다는 뜻입니다. 이건 선택적인 최적화가 아니라 필수 기능입니다.

거기에 성능 최적화까지 더하면 복잡도가 한층 올라갑니다. 전 세계 CDN에서 캐시된 콘텐츠를 제공한다거나, 엣지에서 컴퓨팅을 실행한다거나, 서버리스 함수로 콜드 스타트를 줄이는 같은 선택지들이 생기니까요.

플랫폼과 아키텍처에 따라 지원해야 하는 기능들이 쌓입니다. 스트리밍, Server Components, Partial Prerendering, 미들웨어, Cache Components, 온디맨드 재검증 등등. 각 기능이 서로 어떻게 상호작용하는지가 제대로 문서화된 적이 없었습니다.

플랫폼 제공자 입장에서는 여러 테넌트 환경에서 계속 변하는 Next.js 릴리스를 완벽하게 지원해야 했으니, 이런 문제들이 눈덩이처럼 불어났습니다.

> Next.js 팀이 Netlify의 어려움에 대해 얘기해보자고 제안했을 때, 우리는 구체적인 문제점들을 길게 나열하려고 했습니다. 그런데 정리하다 보니 이 중 90% 정도가 같은 근본 원인이었어요. 빌드 결과물을 설정하고 읽을 수 있는 공식적이고 안정적인 메커니즘이 없다는 것이었죠. 결국 그게 가장 필요한 것이었고, Jimmy에게 그렇게 말했습니다. 잘한 결정이었어요.

> — Netlify 엔지니어, Philippe Serhal

결국 필요했던 건 간단했습니다. 플랫폼 제공자들이 구축할 수 있는 공식적이고 안정적인 인터페이스가 필요했습니다.

OpenNext가 다리를 놓다

OpenNext가 이 공백을 채웠습니다. Next.js 빌드 결과물을 플랫폼이 소비할 수 있는 형태로 변환했거든요. 각 플랫폼의 고유한 방식에 맞게 프레임워크의 의미를 매핑해주는 것이죠. 처음엔 호환성 레이어였지만, 특히 AWS에서 프로덕션 환경에서도 쓸 수 있는 수준의 어댑터가 되었습니다. Cloudflare와 Netlify도 나중에 이 노력에 합류했습니다.

OpenNext는 중요한 깨달음을 줬습니다. Next.js 빌드 결과물 자체가 어댑터들이 직접 구현할 수 있는 안정적이고 정의된 인터페이스가 될 수 있다는 것이었습니다.

이 인사이트가 Next.js 팀과 OpenNext 유지보수자, 그리고 Netlify, Cloudflare, AWS Amplify, Google Cloud의 엔지니어들을 한데 모으게 했습니다. 2025년 4월에 Build Adapters RFC를 공개했고, 워킹그룹을 조직한 뒤, 이 모든 파트너와 함께 API를 설계하고 테스트하고 검증해왔습니다.

어댑터 API

Next.js 16.2에는 공식적이고 안정적인 어댑터 API가 포함되어 있습니다.

빌드할 때 Next.js는 이제 타입이 정의되고 버전이 관리되는 애플리케이션 명세를 만듭니다. 여기엔 라우트, 사전 렌더링, 정적 자산, 런타임 대상, 의존성, 캐싱 규칙, 라우팅 결정 등이 담깁니다. 어댑터가 이 결과물을 받아서 플랫폼의 인프라에 맞게 변환하는 방식입니다.

어댑터는 두 가지 훅을 구현합니다:

modifyConfig: 설정이 로드될 때
onBuildComplete: 빌드가 완료되었을 때

Next.js의 메이저 버전이 올라갈 때만 breaking changes가 생깁니다.

Vercel의 어댑터도 이 공개 API를 그대로 사용합니다. 특별한 private 훅이나 특수한 통합 경로는 없습니다. 그리고 오픈소스입니다.

워킹그룹의 피드백을 반영해서, 플랫폼 통합 부분에 대한 문서도 대대적으로 정비했습니다. 이제 렌더링 철학, 플랫폼별 배포 기능 매트릭스, PPR 플랫폼 가이드, 재검증 작동 방식, CDN 캐싱 등을 다루는 새로운 가이드들이 있습니다.

테스트 스위트

Next.js 테스트 스위트를 어댑터 개발자들이 사용할 수 있게 공개했습니다. 스트리밍 동작, 캐싱 상호작용, 클라이언트 네비게이션, 그리고 실제 상황의 엣지 케이스들을 다룹니다. 새로운 기능이 출시될 때마다 그 동작이 이 테스트들에 인코딩됩니다.

더 자세한 내용은 어댑터 테스팅 문서에서 확인할 수 있습니다.

어댑터 개발자는 어떤 어댑터로든 이 스위트를 실행할 수 있고, 각 기능에 대해 통과/실패 결과를 얻습니다. 이건 Vercel이 자신의 어댑터를 검증할 때 사용하는 것과 동일한 테스트 스위트입니다. 즉, 모든 제공자가 동일한 기준을 적용하는 것이죠.

검증된 어댑터

Next.js GitHub 조직 아래에 호스팅되고 "플랫폼별 배포" 문서에 등록되려면 두 가지 조건을 만족해야 합니다. 오픈소스여야 하고, 전체 테스트 스위트를 통과해야 합니다. 어댑터를 오픈소스로 공개함으로써 커뮤니티가 기여하고 유지보수할 수 있게 하는 거죠.

🔗 원문 보기 👍 유용해요