動的 API は非同期です

特定の API に同期的にアクセスすると警告が表示される理由について詳しく学びましょう。

この警告が発生した理由

コードのどこかで、動的レンダリングを選択する API を使用しました。

動的 API は

• ページ、レイアウト、メタデータ API、およびルートハンドラーに提供される params と searchParams のプロパティです。
• next/headers からの cookies()、draftMode()、および headers()

Next 15 では、これらの API は非同期になりました。詳細については、Next.js 15 のアップグレードガイドをお読みください。

たとえば、次のコードは警告を発行します。

function Page({ params }) {
  // direct access of `params.id`.
  return <p>ID: {params.id}</p>
}

これには、これらの API の戻り値の列挙 (例: {...params} または Object.keys(params)) や反復処理 (例: [...headers()] または for (const cookie of cookies())、または明示的に cookies()[Symbol.iterator]()) も含まれます。

この警告を発行した Next.js のバージョンでは、これらのプロパティへの直接アクセスはまだ可能ですが、警告が表示されます。将来のバージョンでは、これらの API は非同期になり、直接アクセスは期待どおりに機能しません。

考えられる修正方法

next-async-request-api codemod は、これらのケースの多くを自動的に修正できます。

$ npx @next/codemod@canary next-async-request-api .

codemod はすべてのケースをカバーできるわけではないため、一部のコードを手動で調整する必要がある場合があります。

警告がサーバー (例: ルートハンドラー、またはサーバーコンポーネント) で発生した場合は、動的 API のプロパティにアクセスするために await する必要があります。

function Page({ params }) {
  // asynchronous access of `params.id`.
  const { id } = await params
  return <p>ID: {id}</p>
}

警告が同期コンポーネント (例: クライアントコンポーネント) で発生した場合は、最初に Promise をアンラップするために React.use() を使用する必要があります。

'use client'
import * as React from 'react'
 
function Page({ params }) {
  // asynchronous access of `params.id`.
  const { id } = React.use(params)
  return <p>ID: {id}</p>
}

移行できないケース

Next.js codemod が codemod で移行できないものを見つけた場合は、@next-codemod-error プレフィックスと推奨されるアクションを含むコメントを残します。例: この場合、cookies() の呼び出しを手動で待機し、関数を async に変更する必要があります。次に、関数の使用箇所が適切に待機されるようにリファクタリングします。

export function MyCookiesComponent() {
  const c =
    /* @next-codemod-error Manually await this call and refactor the function to be async */
    cookies()
  return c.get('name')
}

Linter による強制移行

codemod によって残された @next-codemod-error で始まるコメントに対処しなかった場合、Next.js は開発時とビルド時の両方でエラーを発生させて、問題に対処するように強制します。変更を確認し、コメントの提案に従うことができます。必要な変更を行ってコメントを削除するか、コメントプレフィックス @next-codemod-error を @next-codemod-ignore に置き換えることができます。対処する必要がない場合は、コメントプレフィックス @next-codemod-ignore はビルドエラーをバイパスします。

- /* @next-codemod-error <suggested message> */
+ /* @next-codemod-ignore */

知っておくとよいこと:

実際に値を使用する必要があるまで、Promise のアンラップ (await または React.use のいずれか) を遅延させることができます。これにより、Next.js はページをより静的にレンダリングできるようになります。