できない.dev

Next.js を 15 から 16 に上げると動かなくなること

Next.js を 15 から 16 に上げると、webpack の設定や default.js の無い並列ルートでビルドが止まり、next lint は消え、await しない cookies() は 500 になる。
15.5 と 16.4 で打ち比べた 8 つの変更点と直し方をまとめる。

公開: 更新:

next@15 を入れたプロジェクトと next@16 を入れたプロジェクトを並べ、変更点ごとに同じファイルを置いて同じコマンドを打ち比べた。
各節の出力は「v15 では」「v16 に上げると」「v16 で直すと」の 3 段で並ぶ。
旧版は 15.x の最新の 15.5.29、新版は 16.x の最新の 16.4.5 で、React・TypeScript・ESLint は両方のプロジェクトに同じ指定(react@19・typescript@5・eslint@9)で入れた。
サーバーは npx next start > server.log 2>&1 & でバックグラウンドに起動し、curl で叩いた。
params と cookies() の節は、エラー文を読める形で見るために npx next dev で起動した。
画質の節の v15 でも、開発サーバーが出す警告を見るために npx next dev を打った。

8 つのうち、next build が止まるのは 3 つである。
webpack の設定、default.js の無い並列ルート、TypeScript のプロジェクトで引数が 1 つの revalidateTag() が当てはまる。
next lint はコマンドごと無くなった。
params と cookies() を await せずに読むコードは、開発サーバーではリクエストを受けた時点で空の値か 500 になった(next build では打っていない)。
画像の画質はエラーを出さずに変わる。
middleware と next.config の 2 つは、16 でもビルドが通り、警告が出る。

このページで打ったコマンドのうち、15.5.29 が前もって知らせたのは 3 つだった。
next lint は 16 で消えると表示する。
開発サーバーは、await していない params と cookies() をエラー文で示し、一覧に無い画質を「16 から設定が必要になる」と警告する。
残りの 5 つは、15 では next build と next start で打っており、その出力に 15.5.29 の警告は出ていない。
15 の next dev での出方は見ていない。

公式の codemod(npx @next/codemod@canary upgrade latest)は、Turbopack の設定の移動・next lint から ESLint の CLI への移行・middleware から proxy への改名を受け持つ。
安定した API の unstable_ の接頭辞を外すことと、experimental_ppr の削除もこの codemod が行う。
params と cookies() の書き換えは、別の codemod(next-async-request-api)が受け持つ。

16 は Node.js 20.9 以上と TypeScript 5.1 以上で動く。
AMP と serverRuntimeConfig・publicRuntimeConfig も 16 で消えたが、主に Pages Router で使う機能なので、App Router のプロジェクトで打ったこのページでは扱っていない。

公式の移行ガイドにある次の変更も、このページでは打っていない。

  • Turbopack は、Sass の @import '~bootstrap/…' のような ~ で始まる読み込みを解決しない。
    sass-loader は 16 になった。
  • next/image は、ローカルの IP の画像を既定で最適化しなくなり(images.dangerouslyAllowLocalIP)、画像の転送を 3 回までしか追わなくなった(images.maximumRedirects)。
    next/legacy/image は非推奨になった。
  • next dev の出力先が .next/dev に分かれ、同じプロジェクトで next dev や next build を二重に動かさないためのロックファイルが入った。
  • next dev のとき、next.config の中で見る process.argv に 'dev' が入らなくなった。
  • <html> に書いた scroll-behavior: smooth を、画面を移るあいだ上書きしなくなった。
  • devIndicators の一部のオプション、experimental.ppr、unstable_rootParams は無くなった。
    16.3 で experimental.viewTransition、16.4 で experimental.appNewScrollHandler も無くなった。
  • 対応するブラウザは Chrome・Edge・Firefox の 111 以上と、Safari 16.4 以上になった。

webpack の設定があると next build が止まるようになった

16 の next build は、既定で webpack ではなく Turbopack を使う。
next.config に webpack の関数を書いたプロジェクトは、Turbopack の設定が無いとコンパイルを始める前に止まる。
ここで書いた resolve.fallback で fs を空にする設定は、ブラウザ向けのバンドルで Module not found: Can't resolve 'fs' を消すためによく使われていた。

v15 では

$ cat next.config.mjs
/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack: (config, { isServer }) => {
    // ブラウザ向けのバンドルでは fs を空のモジュールにする
    if (!isServer) {
      config.resolve.fallback = { ...config.resolve.fallback, fs: false };
    }
    return config;
  },
};
 
export default nextConfig;
$ npx next build
   ▲ Next.js 15.5.29
 
   Creating an optimized production build ...
 ✓ Compiled successfully in 2.2s
   Linting and checking validity of types ...
   Collecting page data ...
   Generating static pages (0/4) ...
   Generating static pages (1/4) 
   Generating static pages (2/4) 
   Generating static pages (3/4) 
 ✓ Generating static pages (4/4)
   Finalizing page optimization ...
   Collecting build traces ...
 
Route (app)                                 Size  First Load JS
┌ ○ /                                      127 B         103 kB
└ ○ /_not-found                            993 B         104 kB
+ First Load JS shared by all             103 kB
  ├ chunks/255-73938ce8a8eac1ad.js       46.6 kB
  ├ chunks/4bd1b696-c023c6e3521b1417.js  54.2 kB
  └ other shared chunks (total)          1.88 kB
 
○  (Static)  prerendered as static content
$ echo $?
0

v16 に上げると

$ npx next build
▲ Next.js 16.4.5 (Turbopack)
✓ Running next.config.mjs took 14ms
 
  Creating an optimized production build ...
⨯ ERROR: This build is using Turbopack, with a `webpack` config and no `turbopack` config.
   This may be a mistake.
 
   As of Next.js 16 Turbopack is enabled by default and
   custom webpack configurations may need to be migrated to Turbopack.
 
   NOTE: your `webpack` config may have been added by a configuration plugin.
 
   To configure Turbopack, see https://nextjs.org/docs/app/api-reference/next-config-js/turbopack
 
   TIP: Many applications work fine under Turbopack with no configuration,
   if that is the case for you, you can silence this error by passing the
   `--turbopack` or `--webpack` flag explicitly or simply setting an 
   empty turbopack config in your Next config file (e.g. `turbopack: {}`).
$ echo $?
1

v16 で直すと

$ npx next build --webpack
▲ Next.js 16.4.5 (webpack)
✓ Running next.config.mjs took 12ms
 
  Creating an optimized production build ...
✓ Compiled successfully in 2.1s
  Running TypeScript ...
  Finished TypeScript in 1ms ...
  Collecting page data using 4 workers ...
  Generating static pages using 4 workers (0/3) ...
✓ Generating static pages using 4 workers (3/3) in 274ms
  Finalizing page optimization ...
  Collecting build traces ...
 
Route (app)
┌ ○ /
└ ○ /_not-found
 
○  (Static)  prerendered as static content
$ echo $?
0

next build --webpack で webpack に戻すと、15 と同じ設定のままビルドできる。
package.json の build も next build --webpack に書き換えておく。
移行ガイドによると、16 は next dev も既定で Turbopack を使う。
開発サーバーでも同じ webpack の設定が要るなら、dev も next dev --webpack にする。
next dev の側は、このページでは打っていない。

Turbopack に移るなら、webpack の中身を turbopack の設定に書き直す。
公式の移行ガイドは、fs を空にする設定を turbopack.resolveAlias に fs: { browser: "./empty.ts" } と書く例を載せている。
エラー文の TIP によると turbopack: {} を足すだけでもこのエラーは出なくなるが、公式の移行ガイドによると、Turbopack で build すると webpack の設定は使われない。

自分で書いた覚えが無いのにこのエラーが出るなら、next.config で使っているプラグインが webpack を足している見込みが高い。
エラー文の NOTE と公式の移行ガイドが、どちらもそう書いている。

16 のビルドの出力からは、ページごとの Size と First Load JS の列が無くなった。
webpack で打った「v16 で直すと」の出力にも出ていない。

default.js の無い並列ルートでビルドが止まるようになった

@modal のように @ で始まるフォルダは並列ルート(parallel routes)のスロットになり、レイアウトに modal という props で渡る。
ここでは /login にだけモーダルを出すつもりで、app/@modal/login/page.js だけを置いた。
スロットに、今の URL に合うページも default.js も無いときの扱いが変わった。

v15 では

$ find app -type f | sort
app/@modal/login/page.js
app/layout.js
app/login/page.js
app/page.js
$ cat app/layout.js
export default function RootLayout({ children, modal }) {
  return (
    <html lang="ja">
      <body>
        {children}
        {modal}
      </body>
    </html>
  );
}
$ npx next build
   ▲ Next.js 15.5.29
 
   Creating an optimized production build ...
 ✓ Compiled successfully in 2.4s
   Linting and checking validity of types ...
   Collecting page data ...
   Generating static pages (0/5) ...
   Generating static pages (1/5) 
   Generating static pages (2/5) 
   Generating static pages (3/5) 
 ✓ Generating static pages (5/5)
   Finalizing page optimization ...
   Collecting build traces ...
 
Route (app)                                 Size  First Load JS
┌ ○ /                                      133 B         103 kB
├ ○ /_not-found                            995 B         104 kB
└ ○ /login                                 133 B         103 kB
+ First Load JS shared by all             103 kB
  ├ chunks/255-73938ce8a8eac1ad.js       46.6 kB
  ├ chunks/4bd1b696-c023c6e3521b1417.js  54.2 kB
  └ other shared chunks (total)          1.88 kB
 
○  (Static)  prerendered as static content
$ echo $?
0
$ npx next start > server.log 2>&1 &
$ curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3000/
404
$ curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3000/login
200

v16 に上げると

$ npx next build
▲ Next.js 16.4.5 (Turbopack)
✓ Running next.config took 9ms
 
  Creating an optimized production build ...
⚠ Strict route matching is enabled by default. This validation indicates a bug in your app's route structure, but you can temporarily restore loose route matching by setting `deprecated.looseRouteMatching` to `true` in your Next.js config.
 
> Build error occurred
Error: Turbopack build failed with 2 errors:
./app/layout.js
Error: Parallel route slots cannot render the same URLs
The following layouts have parallel route slots that cannot render the same URLs:
app/layout.js
- / is missing a matching page or default.tsx in @modal
 
Every URL matched by one slot must have a matching page or default.tsx in every sibling slot.
 
./app/page.js
Error: Unmatched app pages
The following page files do not match any complete route:
- app/page.js
 
Every page must be part of at least one complete route. Add matching pages or default files for the sibling parallel route slots, or remove the unreachable pages.
 
    at ignore-listed frames
$ echo $?
1

v16 で直すと

$ cat app/@modal/default.js
export default function Default() {
  return null;
}
$ npx next build
▲ Next.js 16.4.5 (Turbopack)
✓ Running next.config took 10ms
 
  Creating an optimized production build ...
✓ Compiled successfully in 422ms
  Running TypeScript ...
  Finished TypeScript in 2ms ...
  Collecting page data using 5 workers ...
  Generating static pages using 5 workers (0/4) ...
  Generating static pages using 5 workers (1/4) 
  Generating static pages using 5 workers (2/4) 
  Generating static pages using 5 workers (3/4) 
✓ Generating static pages using 5 workers (4/4) in 226ms
  Finalizing page optimization ...
 
Route (app)
┌ ○ /
├ ○ /_not-found
└ ○ /login
 
○  (Static)  prerendered as static content
$ echo $?
0
$ npx next start > server.log 2>&1 &
$ curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3000/
200
$ curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3000/login
200

15.5.29 はビルドが通り、/ を開くと 404 を返した。
/login は 200 である。
スロットに合うものが無い URL を直接開くと、15 は 404 にしていた。

16.4.5 はこれをビルドの時点で見つけ、Parallel route slots cannot render the same URLs で止まる。
同時に出る Strict route matching is enabled by default の警告によると、deprecated.looseRouteMatching を true にすれば一時的に元の判定に戻せる。
この設定は公式の移行ガイドには載っていない。

app/@modal/default.js を置き、null を返す。
スロットに合うページが無い URL では何も描かれず、/ も 200 になった。
公式の移行ガイドは、notFound() を呼ぶか null を返す default.js で以前の動きを保てると書いている。
ただしこの構成では、null を返すと 15 で 404 だった / が 200 に変わった。
合うページが無い URL を 404 のままにしたいなら、ガイドの例のとおり default.js で notFound() を呼ぶ(このページでは打っていない)。
エラー文は default.tsx と書くが、JavaScript のプロジェクトでは default.js でよい。

引数が 1 つの revalidateTag が型エラーになった

revalidateTag() に 2 つ目の引数が足され、キャッシュの寿命の設定(cacheLife のプロファイル)を渡すようになった。
引数が 1 つの書き方は非推奨になり、型の定義から外れた。
TypeScript のプロジェクトでは、next build の型の検査で止まる。
tsconfig.json は create-next-app 15 が作るものと同じにした。

v15 では

$ cat app/actions.ts
"use server";
 
import { revalidateTag } from "next/cache";
 
export async function publishPost() {
  // 記事を保存したあと、posts のタグが付いたキャッシュを古いものにする
  revalidateTag("posts");
}
$ npx next build
   ▲ Next.js 15.5.29
 
   Creating an optimized production build ...
 ✓ Compiled successfully in 2.2s
   Linting and checking validity of types ...
   Collecting page data ...
   Generating static pages (0/4) ...
   Generating static pages (1/4) 
   Generating static pages (2/4) 
   Generating static pages (3/4) 
 ✓ Generating static pages (4/4)
   Finalizing page optimization ...
   Collecting build traces ...
 
Route (app)                                 Size  First Load JS
┌ ○ /                                      127 B         103 kB
└ ○ /_not-found                            995 B         104 kB
+ First Load JS shared by all             103 kB
  ├ chunks/255-73938ce8a8eac1ad.js       46.6 kB
  ├ chunks/4bd1b696-c023c6e3521b1417.js  54.2 kB
  └ other shared chunks (total)          1.88 kB
 
○  (Static)  prerendered as static content
$ echo $?
0

v16 に上げると

$ npx next build
▲ Next.js 16.4.5 (Turbopack)
✓ Running next.config took 10ms
 
  Creating an optimized production build ...
✓ Compiled successfully in 1256ms
  Running TypeScript ...
 
  We detected TypeScript in your project and reconfigured your tsconfig.json file for you.
  The following suggested values were added to your tsconfig.json. These values can be changed to fit your project's needs:
 
  	- include was updated to add '.next/dev/types/**/*.ts'
 
  The following mandatory changes were made to your tsconfig.json:
 
  	- jsx was set to react-jsx (next.js uses the React automatic runtime)
 
app/actions.ts(7,3): error TS2554: Expected 2 arguments, but got 1.
Failed to type check.
$ echo $?
1

v16 で直すと

$ cat app/actions.ts
"use server";
 
import { revalidateTag } from "next/cache";
 
export async function publishPost() {
  // 記事を保存したあと、posts のタグが付いたキャッシュを古いものにする
  revalidateTag("posts", "max");
}
$ npx next build
▲ Next.js 16.4.5 (Turbopack)
✓ Running next.config took 9ms
 
  Creating an optimized production build ...
✓ Compiled successfully in 262ms
  Running TypeScript ...
  Finished TypeScript in 724ms ...
  Collecting page data using 4 workers ...
  Generating static pages using 4 workers (0/3) ...
✓ Generating static pages using 4 workers (3/3) in 244ms
  Finalizing page optimization ...
 
Route (app)
┌ ○ /
└ ○ /_not-found
 
○  (Static)  prerendered as static content
$ echo $?
0

2 つ目に "max" を渡す。
公式のブログによると、タグの付いたキャッシュは古いものとして扱われ、次のリクエストには古いデータを返しながら裏で作り直す。
保存した本人にすぐ新しいデータを見せたい Server Action では、16 で足された updateTag() を使う。
この節は TypeScript のプロジェクトで打った。
JavaScript のプロジェクトで引数が 1 つのまま動かしたときの挙動は打っていない。

16 の最初のビルドは、tsconfig.json の jsx を react-jsx にし、include に .next/dev/types/**/*.ts を足して書き換えた。
この書き換えはビルドを止めないが、tsconfig.json に差分が出るので、16 に上げたコミットに含めておく。

next lint が無くなり、FlatCompat の設定も読めなくなった

15.5 で非推奨になった next lint が、16 で無くなった。
next build も lint をしなくなった。
eslint.config.mjs は create-next-app 15 が作る形で、FlatCompat を通して eslint-config-next の従来の形式の設定を読む。
TypeScript 用の next/typescript は外した。

v15 では

$ cat eslint.config.mjs
import { dirname } from "path";
import { fileURLToPath } from "url";
import { FlatCompat } from "@eslint/eslintrc";
 
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);
 
const compat = new FlatCompat({
  baseDirectory: __dirname,
});
 
const eslintConfig = [
  ...compat.extends("next/core-web-vitals"),
  {
    ignores: ["node_modules/**", ".next/**", "out/**", "build/**"],
  },
];
 
export default eslintConfig;
$ npx next lint
`next lint` is deprecated and will be removed in Next.js 16.
For new projects, use create-next-app to choose your preferred linter.
For existing projects, migrate to the ESLint CLI:
npx @next/codemod@canary next-lint-to-eslint-cli .
 
./app/page.js
2:10  Warning: Using `<img>` could result in slower LCP and higher bandwidth. Consider using `<Image />` from `next/image` or a custom image loader to automatically optimize images. This may incur additional usage or cost from your provider. See: https://nextjs.org/docs/messages/no-img-element  @next/next/no-img-element
 
info  - Need to disable some ESLint rules? Learn more here: https://nextjs.org/docs/app/api-reference/config/eslint#disabling-rules
$ echo $?
0
$ npx eslint .
/work/v15/next-lint/app/page.js
  2:10  warning  Using `<img>` could result in slower LCP and higher bandwidth. Consider using `<Image />` from `next/image` or a custom image loader to automatically optimize images. This may incur additional usage or cost from your provider. See: https://nextjs.org/docs/messages/no-img-element  @next/next/no-img-element
 
✖ 1 problem (0 errors, 1 warning)
$ echo $?
0

v16 に上げると

$ npx next lint
Invalid project directory provided, no such directory: /work/v16/next-lint/lint
$ echo $?
1
$ npx eslint .
Oops! Something went wrong! :(
 
ESLint: 9.39.5
 
TypeError: Converting circular structure to JSON
    --> starting at object with constructor 'Object'
    |     property 'configs' -> object with constructor 'Object'
    |     property 'flat' -> object with constructor 'Object'
    |     ...
    |     property 'plugins' -> object with constructor 'Object'
    --- property 'react' closes the circle
Referenced from: 
    at JSON.stringify (<anonymous>)
    at file:///work/v16/next-lint/node_modules/@eslint/eslintrc/lib/shared/config-validator.js:308:45
    at Array.map (<anonymous>)
    at ConfigValidator.formatErrors (file:///work/v16/next-lint/node_modules/@eslint/eslintrc/lib/shared/config-validator.js:299:23)
    at ConfigValidator.validateConfigSchema (file:///work/v16/next-lint/node_modules/@eslint/eslintrc/lib/shared/config-validator.js:330:84)
    at ConfigArrayFactory._normalizeConfigData (file:///work/v16/next-lint/node_modules/@eslint/eslintrc/lib/config-array-factory.js:676:19)
    at ConfigArrayFactory._loadConfigData (file:///work/v16/next-lint/node_modules/@eslint/eslintrc/lib/config-array-factory.js:641:21)
    at ConfigArrayFactory._loadExtendedShareableConfig (file:///work/v16/next-lint/node_modules/@eslint/eslintrc/lib/config-array-factory.js:946:21)
    at ConfigArrayFactory._loadExtends (file:///work/v16/next-lint/node_modules/@eslint/eslintrc/lib/config-array-factory.js:814:25)
    at ConfigArrayFactory._normalizeObjectConfigDataBody (file:///work/v16/next-lint/node_modules/@eslint/eslintrc/lib/config-array-factory.js:752:25)
$ echo $?
2

v16 で直すと

$ cat eslint.config.mjs
import { defineConfig, globalIgnores } from "eslint/config";
import nextVitals from "eslint-config-next/core-web-vitals";
 
const eslintConfig = defineConfig([
  ...nextVitals,
  globalIgnores([".next/**", "out/**", "build/**"]),
]);
 
export default eslintConfig;
$ npx eslint .
/work/v16/next-lint/app/page.js
  2:10  warning  Using `<img>` could result in slower LCP and higher bandwidth. Consider using `<Image />` from `next/image` or a custom image loader to automatically optimize images. This may incur additional usage or cost from your provider. See: https://nextjs.org/docs/messages/no-img-element  @next/next/no-img-element
 
✖ 1 problem (0 errors, 1 warning)
$ echo $?
0

16 の next には lint のコマンドが無く、lint をプロジェクトのディレクトリの名前として読んで止まった。
lint と関係の無さそうな no such directory のエラーになるのはそのためである。

ESLint を直接打つと、同じ eslint.config.mjs が Converting circular structure to JSON で落ちる。
ESLint と @eslint/eslintrc は両方に同じ指定で入れたので、変わったのは eslint-config-next(15.5.29 → 16.4.5)とその依存である。
16 の eslint-config-next は flat config の形で設定を出す。
スタックによると、FlatCompat はそれを従来の形式の設定として検査して通らず、その指摘を文に整える途中の JSON.stringify で落ちている。

16 では eslint-config-next/core-web-vitals を import し、配列に展開して並べる。
create-next-app 16 が作る eslint.config.mjs もこの形で、TypeScript のプロジェクトは eslint-config-next/typescript も並べる。

package.json の "lint": "next lint" は "lint": "eslint ." に書き換える。
公式の移行ガイドには、ESLint の CLI へ移す codemod(npx @next/codemod@canary next-lint-to-eslint-cli .)も載っている。
next.config に eslint の設定を書いていたら、最後の節のとおり 16 では警告が出て読まれない。

params や cookies() を await せずに読めなくなった

15 は、ページの params と searchParams、cookies()・headers()・draftMode() の戻り値を Promise に変えた。
移行のために、await せずに読む書き方も一時的に動くようにしてあった。
16 ではそれが無くなった。
TypeScript では 15 の時点で型が Promise になっているので、await せずに読めるのは JavaScript のプロジェクトか、型を書き換えて読んでいるコードである。

v15 では

$ cat "app/blog/[slug]/page.js"
export default function Page({ params }) {
  return <h1>slug: {params.slug}</h1>;
}
$ cat app/page.js
import { cookies } from "next/headers";
 
export default function Page() {
  const theme = cookies().get("theme")?.value ?? "light";
  return <p>theme: {theme}</p>;
}
$ npx next dev > server.log 2>&1 &
$ curl -s http://localhost:3000/blog/hello | grep -o '<h1>.*</h1>'
<h1>slug: <!-- -->hello</h1>
$ curl -s -o /dev/null -w '%{http_code}\n' -H "Cookie: theme=dark" http://localhost:3000/
200
$ cat server.log
   ▲ Next.js 15.5.29
   - Local:        http://localhost:3000
   - Network:      http://172.17.0.10:3000
 
 ✓ Starting...
 ✓ Ready in 862ms
 ○ Compiling /blog/[slug] ...
 ✓ Compiled /blog/[slug] in 1456ms (529 modules)
Error: Route "/blog/[slug]" used `params.slug`. `params` should be awaited before using its properties. Learn more: https://nextjs.org/docs/messages/sync-dynamic-apis
    at Page (app/blog/[slug]/page.js:2:28)
  1 | export default function Page({ params }) {
> 2 |   return <h1>slug: {params.slug}</h1>;
    |                            ^
  3 | }
  4 |
 GET /blog/hello 200 in 1823ms
 ✓ Compiled / in 136ms (536 modules)
Error: Route "/" used `cookies().get('theme')`. `cookies()` should be awaited before using its value. Learn more: https://nextjs.org/docs/messages/sync-dynamic-apis
    at createCookiesAccessError (../../../src/server/request/cookies.ts:529:10)
    at syncIODev (../../../src/server/request/cookies.ts:517:3)
    at Promise.get (../../../src/server/request/cookies.ts:332:9)
    at Page (app/page.js:4:27)
  527 | ) {
  528 |   const prefix = route ? `Route "${route}" ` : 'This route '
> 529 |   return new Error(
      |          ^
  530 |     `${prefix}used ${expression}. ` +
  531 |       `\`cookies()\` should be awaited before using its value. ` +
  532 |       `Learn more: https://nextjs.org/docs/messages/sync-dynamic-apis`
 GET / 200 in 240ms

v16 に上げると

$ npx next dev > server.log 2>&1 &
$ curl -s http://localhost:3000/blog/hello | grep -o '<h1>.*</h1>'
<h1>slug: </h1>
$ curl -s -o /dev/null -w '%{http_code}\n' -H "Cookie: theme=dark" http://localhost:3000/
500
$ cat server.log
▲ Next.js 16.4.5 (Turbopack)
- Local:         http://localhost:3000
- Network:       http://172.17.0.10:3000
✓ Ready in 209ms
✓ Running next.config took 12ms
 
Error: Route "/blog/[slug]" used `params.slug`. `params` is a Promise and must be unwrapped with `await` or `React.use()` before accessing its properties. Learn more: https://nextjs.org/docs/messages/sync-dynamic-apis
    at Page (app/blog/[slug]/page.js:2:28)
  1 | export default function Page({ params }) {
> 2 |   return <h1>slug: {params.slug}</h1>;
    |                            ^
  3 | }
  4 |
 GET /blog/hello 200 in 346ms (next.js: 245ms, application-code: 100ms)
Error: Route "/" used `cookies().get`. `cookies()` returns a Promise and must be unwrapped with `await` or `React.use()` before accessing its properties. Learn more: https://nextjs.org/docs/messages/sync-dynamic-apis
    at Page (app/page.js:4:24)
  2 |
  3 | export default function Page() {
> 4 |   const theme = cookies().get("theme")?.value ?? "light";
    |                        ^
  5 |   return <p>theme: {theme}</p>;
  6 | }
  7 |
⨯ TypeError: {imported module ./nodemodules/next/headers.js}.cookies(...).get is not a function
    at Page (app/page.js:4:27)
  2 |
  3 | export default function Page() {
> 4 |   const theme = cookies().get("theme")?.value ?? "light";
    |                           ^
  5 |   return <p>theme: {theme}</p>;
  6 | }
  7 | {
  digest: '1475007201'
}
 GET / 500 in 34ms (next.js: 5ms, application-code: 30ms)

v16 で直すと

$ cat "app/blog/[slug]/page.js"
export default async function Page({ params }) {
  const { slug } = await params;
  return <h1>slug: {slug}</h1>;
}
$ cat app/page.js
import { cookies } from "next/headers";
 
export default async function Page() {
  const cookieStore = await cookies();
  const theme = cookieStore.get("theme")?.value ?? "light";
  return <p>theme: {theme}</p>;
}
$ npx next dev > server.log 2>&1 &
$ curl -s http://localhost:3000/blog/hello | grep -o '<h1>.*</h1>'
<h1>slug: <!-- -->hello</h1>
$ curl -s -o /dev/null -w '%{http_code}\n' -H "Cookie: theme=dark" http://localhost:3000/
200
$ cat server.log
▲ Next.js 16.4.5 (Turbopack)
- Local:         http://localhost:3000
- Network:       http://172.17.0.10:3000
✓ Ready in 173ms
✓ Running next.config took 10ms
 
 GET /blog/hello 200 in 321ms (next.js: 238ms, application-code: 83ms)
 GET / 200 in 23ms (next.js: 5ms, application-code: 18ms)

16.4.5 では、ページは 200 のまま slug: と空で描かれた。
cookies().get() は TypeError で 500 になった。

開発サーバーのエラー文も、「await するべき」(15)から「Promise なので await か React.use() で取り出す」(16)に変わっている。
この節は next dev だけで打ち、next build と next start では打っていない。

ページを async 関数にして、await params・await cookies() と書く。
Client Component は async にできないので、React.use(params) で取り出す。

15 のうちに next-async-request-api の codemod を走らせたプロジェクトには、await にできなかった箇所に、codemod のコメントや UnsafeUnwrapped の型への書き換えが残る。
公式の移行ガイドの確認項目は、16 に上げるときにこれらを解消するよう求めている。
このページでは、codemod を走らせたプロジェクトを 16 でビルドしてはいない。

公式の移行ガイドによると、opengraph-image などの画像を作る関数が受け取る params と id も Promise に変わった。
generateSitemaps が返した id を sitemap の関数が受け取るときも、Promise で渡る。

next/image の quality が 75 に丸められるようになった

images.qualities の既定が、1〜100 のすべてから [75] だけになった。
quality={90} のように一覧に無い値を渡すと、エラーを出さずに一覧のいちばん近い値に丸められる。

v15 では

$ cat app/page.js
import Image from "next/image";
 
export default function Page() {
  return <Image src="/photo.png" alt="photo" width={64} height={64} quality={90} />;
}
$ npx next build > build.log
$ echo $?
0
$ npx next start > server.log 2>&1 &
$ curl -s http://localhost:3000/ | grep -o 'srcSet="[^"]*"'
srcSet="/_next/image?url=%2Fphoto.png&amp;w=64&amp;q=90 1x, /_next/image?url=%2Fphoto.png&amp;w=128&amp;q=90 2x"
$ curl -s -o /dev/null -w '%{http_code}\n' "http://localhost:3000/_next/image?url=%2Fphoto.png&w=128&q=90"
200
$ npx next dev > server.log 2>&1 &
$ curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3000/
200
$ cat server.log
   ▲ Next.js 15.5.29
   - Local:        http://localhost:3000
   - Network:      http://172.17.0.10:3000
 
 ✓ Starting...
 ✓ Ready in 850ms
 ○ Compiling / ...
 ✓ Compiled / in 1501ms (575 modules)
Image with src "/photo.png" is using quality "90" which is not configured in images.qualities. This config will be required starting in Next.js 16.
Read more: https://nextjs.org/docs/messages/next-image-unconfigured-qualities
 GET / 200 in 1667ms

v16 に上げると

$ npx next build > build.log
$ echo $?
0
$ npx next start > server.log 2>&1 &
$ curl -s http://localhost:3000/ | grep -o 'srcSet="[^"]*"'
srcSet="/_next/image?url=%2Fphoto.png&amp;w=64&amp;q=75 1x, /_next/image?url=%2Fphoto.png&amp;w=128&amp;q=75 2x"
$ curl -s -o /dev/null -w '%{http_code}\n' "http://localhost:3000/_next/image?url=%2Fphoto.png&w=128&q=90"
400
$ curl -s "http://localhost:3000/_next/image?url=%2Fphoto.png&w=128&q=90"
"q" parameter (quality) of 90 is not allowed

v16 で直すと

$ cat next.config.mjs
/** @type {import('next').NextConfig} */
const nextConfig = {
  images: {
    qualities: [75, 90],
  },
};
 
export default nextConfig;
$ npx next build > build.log
$ echo $?
0
$ npx next start > server.log 2>&1 &
$ curl -s http://localhost:3000/ | grep -o 'srcSet="[^"]*"'
srcSet="/_next/image?url=%2Fphoto.png&amp;w=64&amp;q=90 1x, /_next/image?url=%2Fphoto.png&amp;w=128&amp;q=90 2x"
$ curl -s -o /dev/null -w '%{http_code}\n' "http://localhost:3000/_next/image?url=%2Fphoto.png&w=128&q=90"
200

15.5.29 は q=90 のまま配った。
開発サーバーで同じページを開くと、90 が images.qualities に無く、16 からはこの設定が必要になるという警告が出た。

16 では HTML の srcSet が q=75 を指すようになった。
/_next/image に q=90 を直接渡したリクエストは 400 になる。
CDN の設定やほかのページで /_next/image の URL を組み立てていると、その画像は表示されなくなる。

使う画質を images.qualities に並べる。
quality を書かない <Image> は既定の 75 を使うので、[75, 90] のように 75 も残しておく。

公式の移行ガイドには、画像の設定のほかの変更も載っている(このページでは打っていない)。
ローカルの画像の src に ?v=1 のようなクエリを付けるには、images.localPatterns に search を書く必要がある。
images.minimumCacheTTL の既定は 60 秒から 4 時間に延び、images.imageSizes の既定からは 16 が外れた。

middleware.js が非推奨になり proxy.js に名前が変わった

16 で middleware のファイル名が非推奨になり、proxy に変わった。
16.4.5 でも middleware.js はそのまま動き、ビルドが警告を出す。

v15 では

$ cat middleware.js
import { NextResponse } from "next/server";
 
export function middleware(request) {
  return NextResponse.redirect(new URL("/new", request.url));
}
 
export const config = {
  matcher: "/old",
};
$ npx next build
   ▲ Next.js 15.5.29
 
   Creating an optimized production build ...
 ✓ Compiled successfully in 2.6s
   Linting and checking validity of types ...
   Collecting page data ...
   Generating static pages (0/4) ...
   Generating static pages (1/4) 
   Generating static pages (2/4) 
   Generating static pages (3/4) 
 ✓ Generating static pages (4/4)
   Finalizing page optimization ...
   Collecting build traces ...
 
Route (app)                                 Size  First Load JS
┌ ○ /_not-found                            990 B         104 kB
└ ○ /new                                   127 B         103 kB
+ First Load JS shared by all             103 kB
  ├ chunks/255-73938ce8a8eac1ad.js       46.6 kB
  ├ chunks/4bd1b696-c023c6e3521b1417.js  54.2 kB
  └ other shared chunks (total)          1.88 kB
 
ƒ Middleware                               34 kB
 
○  (Static)  prerendered as static content
$ echo $?
0
$ npx next start > server.log 2>&1 &
$ curl -s -o /dev/null -w '%{http_code} %{redirect_url}\n' http://localhost:3000/old
307 http://localhost:3000/new

v16 に上げると

$ npx next build
▲ Next.js 16.4.5 (Turbopack)
✓ Running next.config took 9ms
 
⚠ The "middleware" file convention is deprecated. Please use "proxy" instead.
 
  To migrate automatically, run:
  npx @next/codemod@canary middleware-to-proxy .
 
  Learn more: https://nextjs.org/docs/messages/middleware-to-proxy
  Creating an optimized production build ...
✓ Compiled successfully in 1162ms
  Running TypeScript ...
  Finished TypeScript in 1ms ...
  Collecting page data using 4 workers ...
  Generating static pages using 4 workers (0/3) ...
✓ Generating static pages using 4 workers (3/3) in 247ms
  Finalizing page optimization ...
 
Route (app)
┌ ○ /_not-found
└ ○ /new
 
ƒ Proxy (Middleware)
 
○  (Static)  prerendered as static content
$ echo $?
0
$ npx next start > server.log 2>&1 &
$ curl -s -o /dev/null -w '%{http_code} %{redirect_url}\n' http://localhost:3000/old
307 http://localhost:3000/new

v16 で直すと

$ mv middleware.js proxy.js
$ cat proxy.js
import { NextResponse } from "next/server";
 
export function proxy(request) {
  return NextResponse.redirect(new URL("/new", request.url));
}
 
export const config = {
  matcher: "/old",
};
$ npx next build
▲ Next.js 16.4.5 (Turbopack)
✓ Running next.config took 13ms
 
  Creating an optimized production build ...
✓ Compiled successfully in 444ms
  Running TypeScript ...
  Finished TypeScript in 1ms ...
  Collecting page data using 4 workers ...
  Generating static pages using 4 workers (0/3) ...
✓ Generating static pages using 4 workers (3/3) in 228ms
  Finalizing page optimization ...
 
Route (app)
┌ ○ /_not-found
└ ○ /new
 
ƒ Proxy (Middleware)
 
○  (Static)  prerendered as static content
$ echo $?
0
$ npx next start > server.log 2>&1 &
$ curl -s -o /dev/null -w '%{http_code} %{redirect_url}\n' http://localhost:3000/old
307 http://localhost:3000/new

16 のビルドの出力では、middleware.js のままでも ƒ Proxy (Middleware) と表示される。
ファイルを proxy.js に改名し、export する関数の名前も proxy にすると、ビルドの警告が消えた。
/old は 15 と同じく /new へ 307 で転送される。
警告にある codemod(npx @next/codemod@canary middleware-to-proxy .)でも書き換えられる。

公式の移行ガイドによると、proxy は Node.js のランタイムだけで動き、Edge のランタイムを選べない。
Edge のランタイムで動かし続けたいときは、非推奨のまま middleware.js を使う。
15 の middleware は、ランタイムを書かなければ Edge のランタイムで動く(15 の middleware のリファレンス)。
このページの middleware.js もランタイムを書いていないので、15 では Edge で動いていたことになり、proxy.js に改名すると Node.js で動くように変わる。
どちらのランタイムで動いたかは、このページの出力では見ていない。

移行ガイドの確認項目も、Edge の middleware を確かめずに proxy へ改名しないよう求めている。
改名の前に、デプロイ先が Edge を前提にしていないか、Edge だけで使える API を呼んでいないかを確かめる。

名前に middleware を含む next.config の設定も改名された。
公式の移行ガイドは、skipMiddlewareUrlNormalize が skipProxyUrlNormalize になった例を挙げている。

next.config の eslint と images.domains に警告が出るようになった

next build が lint をしなくなったので、next.config の eslint(ignoreDuringBuilds など)は読まれなくなった。
外部の画像を許可する images.domains は非推奨になった。
15.5.29 はどちらにも警告を出さず、eslint.ignoreDuringBuilds に従って Skipping linting と表示した。

v15 では

$ cat next.config.mjs
/** @type {import('next').NextConfig} */
const nextConfig = {
  eslint: {
    ignoreDuringBuilds: true,
  },
  images: {
    domains: ["images.example.com"],
  },
};
 
export default nextConfig;
$ npx next build
   ▲ Next.js 15.5.29
 
   Creating an optimized production build ...
 ✓ Compiled successfully in 2.2s
   Skipping linting
   Checking validity of types ...
   Collecting page data ...
   Generating static pages (0/4) ...
   Generating static pages (1/4) 
   Generating static pages (2/4) 
   Generating static pages (3/4) 
 ✓ Generating static pages (4/4)
   Finalizing page optimization ...
   Collecting build traces ...
 
Route (app)                                 Size  First Load JS
┌ ○ /                                      127 B         103 kB
└ ○ /_not-found                            993 B         104 kB
+ First Load JS shared by all             103 kB
  ├ chunks/255-73938ce8a8eac1ad.js       46.6 kB
  ├ chunks/4bd1b696-c023c6e3521b1417.js  54.2 kB
  └ other shared chunks (total)          1.88 kB
 
○  (Static)  prerendered as static content
$ echo $?
0

v16 に上げると

$ npx next build
▲ Next.js 16.4.5 (Turbopack)
⚠ `eslint` configuration in next.config.mjs is no longer supported. See more info here: https://nextjs.org/docs/app/api-reference/cli/next#next-lint-options
⚠ `images.domains` is deprecated in favor of `images.remotePatterns`. Please update next.config.mjs to protect your application from malicious users.
⚠ Invalid next.config.mjs options detected: 
⚠     Unrecognized key(s) in object: 'eslint'
⚠ See more info here: https://nextjs.org/docs/messages/invalid-next-config
✓ Running next.config.mjs took 16ms
 
  Creating an optimized production build ...
✓ Compiled successfully in 1157ms
  Running TypeScript ...
  Finished TypeScript in 1ms ...
  Collecting page data using 4 workers ...
  Generating static pages using 4 workers (0/3) ...
✓ Generating static pages using 4 workers (3/3) in 278ms
  Finalizing page optimization ...
 
Route (app)
┌ ○ /
└ ○ /_not-found
 
○  (Static)  prerendered as static content
$ echo $?
0

v16 で直すと

$ cat next.config.mjs
/** @type {import('next').NextConfig} */
const nextConfig = {
  images: {
    remotePatterns: [{ protocol: "https", hostname: "images.example.com" }],
  },
};
 
export default nextConfig;
$ npx next build
▲ Next.js 16.4.5 (Turbopack)
✓ Running next.config.mjs took 17ms
 
  Creating an optimized production build ...
✓ Compiled successfully in 300ms
  Running TypeScript ...
  Finished TypeScript in 1ms ...
  Collecting page data using 4 workers ...
  Generating static pages using 4 workers (0/3) ...
✓ Generating static pages using 4 workers (3/3) in 234ms
  Finalizing page optimization ...
 
Route (app)
┌ ○ /
└ ○ /_not-found
 
○  (Static)  prerendered as static content
$ echo $?
0

16 はどちらも警告だけでビルドを続け、終了コードは 0 だった。
eslint は Unrecognized key として、設定の誤りの警告にも数えられる。
eslint の設定は消し、lint は eslint . を別に打つ(next lint の節)。
images.domains は images.remotePatterns に書き換える。
remotePatterns は protocol と hostname に加えて、pathname でも絞れる。

公式の移行ガイドによると、experimental.dynamicIO と experimental.useCache は 16 で無くなった。
Cache Components を使っていたなら最上位の cacheComponents に移し、使っていなかったならフラグを消す。
このページでは、この 2 つを書いた next.config を打っていない。

検証環境Node.js 24.22.2 / npm 11.19.1 / Python 3.11.2 / 2026-11-08 検証(ほか 11 件)
検証日
実行環境
node:24 Debian GNU/Linux 12 (bookworm)
バージョン
  • Node.js 24.22.2
  • npm 11.19.1
  • Python 3.11.2
  • Git 2.39.5
  • Next.js(旧) 15.5.29
  • eslint-config-next(旧) 15.5.29
  • Next.js(新) 16.4.5
  • eslint-config-next(新) 16.4.5
  • React 19.3.1
  • TypeScript 5.9.3
  • ESLint 9.39.5
  • @eslint/eslintrc 3.3.7
  • sharp 0.35.5
  • curl 7.88.1

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。