Next.js 16 은 middleware 를 proxy 로 바꿨다

Next.js 16 으로 올리면서 가장 먼저 걸린 것이 이것이었다. middleware.ts 가 더 이상 쓰이지 않는다.

이름이 바뀌었다

파일 규칙이 middleware 에서 proxy 로 바뀌었다. src/middleware.ts 는 src/proxy.ts 가 된다. API 와 config.matcher 형태는 그대로다.

문서는 이름을 바꾼 이유를 이렇게 적는다. "middleware" 라는 말이 Express 의 미들웨어와 혼동을 일으켜 오용을 부추겼고, "proxy" 는 앱 앞의 네트워크 경계를 뜻하므로 이 기능이 실제로 하는 일에 더 가깝다는 것이다.

이게 더 중요한 변화다. 변경 이력에 이렇게 적혀 있다.

v16.0.0 | Middleware is deprecated and renamed to Proxy.
          Proxy defaults to the Node.js runtime

전에는 edge 런타임이 기본이라 쓸 수 있는 API 가 제한적이었다. 이제는 Node.js 가 기본이다.

그런데 runtime 옵션을 proxy 파일에서 바꾸는 것은 막혀 있다. 문서가 명시한다.

The runtime config option is not available in Proxy files. Setting the runtime config option in Proxy will throw an error.

"이제 Node 니까 명시해 두자" 하고 export const runtime = 'nodejs' 를 넣으면 빌드가 깨진다.

런타임이 Node.js 라는 건 proxy 에서 DB 클라이언트 같은 걸 물리적으로는 쓸 수 있다는 뜻이다. 나는 그래도 쓰지 않기로 했다.

같은 문서가 proxy 를 이렇게 규정하기 때문이다.

It can run outside of your application's main runtime and handle requests before they reach your app.

지금 Node.js 런타임으로 도는 것은 기본값일 뿐이고, proxy 라는 계층 자체가 앱 런타임과 분리될 수 있다는 전제 위에 있다. 요청마다 DB 를 깨우지 않는 편이 낫기도 하다.

그래서 인증 설정을 둘로 나눴다. proxy 가 쓰는 쪽에는 DB import 를 넣지 않고, DB 가 필요한 콜백은 다른 파일에 둔다.

이 글의 내용은 전부 node_modules/next/dist/docs/ 안에 있다. 설치된 버전의 문서가 함께 들어온다.

나는 처음에 "proxy 는 edge 런타임" 이라고 적힌 주석을 코드에 남겼다가 나중에 고쳤다. Next 15 시절의 지식을 그대로 옮긴 것이었고, 같은 문서의 두 줄 아래에 답이 있었다. 버전이 크게 오르는 프레임워크에서는 기억보다 설치된 문서가 낫다.