Next.js 16부터 미들웨어는 그 목적을 더 잘 반영하기 위해 이제 프록시라고 부른다. 기능은 동일하게 유지된다.

프록시는 요청이 완료되기 전에 코드를 실행할 수 있도록 한다.

이후, 수신되는 요청에 따라 재작성, 리다이렉트, 요청 또는 응답 헤더 수정, 또는 직접 응답을 통해 응답을 수정할 수 있다.

1. 주요 사용 사례 (Use cases)

프록시가 효과적인 시나리오들은 다음과 같다.

• 모든 페이지 또는 특정 페이지 집합에 대한 헤더 수정
• A/B 테스트 또는 실험을 기반으로 다른 페이지로의 재작성
• 수신 요청 속성을 기반으로 하는 프로그래밍 방식의 리다이렉트

단순한 리다이렉트의 경우, 먼저 next.config.ts의 redirects 설정을 사용하는 것을 고려하자.

프록시는 요청 데이터에 접근해야 하거나 더 복잡한 로직이 필요할 때 사용해야 한다.

프록시는 느린 데이터 가져오기를 위한 용도가 아니다.

프록시는 권한 기반 리다이렉트와 같은 낙관적인 검사에는 도움이 될 수 있지만, 전체 세션 관리 또는 인증 솔류션으로 사용되어서는 안된다.

fetch 사용 시 options.cache , options.next.revalidate , 또는 options.next.tags 옵션은 프록시 내에서 효과가 없다.

2. 컨벤션 (Convention)

proxy.ts (또는 .js ) 파일을 프로젝트 루트에 생성하거나, 해당되는 경우 pages 나 app 과 동일한 레벨에 위치하도록 src 내부에 생성한다.

프로젝트당 하나의 proxy.ts 파일만 지원되지만, 프록시 로직을 모듈로 구성할 수는 있다. 라우트별 프록시 기능을 별도의 .ts 또는 .js 파일로 분리한 후, 중앙 집중식 제어를 위해 메인 proxy.ts 파일로 import 하여 통합 관리할 수 있다. 단일 프록시 파일을 강제함으로써 구성을 단순화하고, 잠재적인 충돌을 방지하며, 여러 프록시 레이어를 피하여 성능을 최적화한다.