コンテンツにスキップ
GuidesUpgradingCodemods

Codemods

Codemodは、コードベースにプログラムで実行される変換です。これにより、すべてのファイルを個別に確認することなく、多数の変更をプログラムで適用できます。

Next.jsは、APIが更新または非推奨になったときにNext.jsコードベースをアップグレードするのに役立つCodemod変換を提供します。

使用方法

ターミナルで、プロジェクトのフォルダーにcdして移動し、次を実行します。

ターミナル
npx @next/codemod <transform> <path>

<transform> と <path> を適切な値に置き換えます。

  • transform - 変換の名前
  • path - 変換するファイルまたはディレクトリ
  • --dry ドライランを実行します。コードは編集されません
  • --print 変更された出力を印刷して比較します

Codemods

16.0

App Routerのページとレイアウトからexperimental_ppr Route Segment Config を削除

remove-experimental-ppr
ターミナル
npx @next/codemod@latest remove-experimental-ppr .

このCodemodは、App Routerのページとレイアウトからexperimental_ppr Route Segment Configを削除します。

app/page.tsx
- export const experimental_ppr = true;

安定化されたAPIからunstable_プレフィックスを削除

remove-unstable-prefix
ターミナル
npx @next/codemod@latest remove-unstable-prefix .

このCodemodは、安定化されたAPIからunstable_プレフィックスを削除します。

例:

import { unstable_cacheTag as cacheTag } from 'next/cache'
 
cacheTag()

〜に変換

import { cacheTag } from 'next/cache'
 
cacheTag()

非推奨のmiddleware規約をproxyに移行

middleware-to-proxy
ターミナル
npx @next/codemod@latest middleware-to-proxy .

このCodemodは、非推奨のmiddleware規約を使用しているプロジェクトをproxy規約を使用するように移行します。これは

  • middleware.<extension> を proxy.<extension> にリネームします (例: middleware.ts を proxy.ts に)
  • 名前付きエクスポート middleware を proxy にリネームします
  • Next.js設定プロパティ experimental.middlewarePrefetch を experimental.proxyPrefetch にリネームします
  • Next.js設定プロパティ experimental.middlewareClientMaxBodySize を experimental.proxyClientMaxBodySize にリネームします
  • Next.js設定プロパティ experimental.externalMiddlewareRewritesResolve を experimental.externalProxyRewritesResolve にリネームします
  • skipMiddlewareUrlNormalize を skipProxyUrlNormalize にリネームします

例:

middleware.ts
import { NextResponse } from 'next/server'
 
export function middleware() {
  return NextResponse.next()
}

〜に変換

proxy.ts
import { NextResponse } from 'next/server'
 
export function proxy() {
  return NextResponse.next()
}

next lint から ESLint CLI への移行

next-lint-to-eslint-cli
ターミナル
npx @next/codemod@canary next-lint-to-eslint-cli .

このCodemodは、next lintを使用しているプロジェクトを、ローカルESLint設定を使用したESLint CLIを使用するように移行します。これは

  • Next.js推奨設定を含むeslint.config.mjsファイルを作成します
  • package.jsonスクリプトをnext lintの代わりにeslint .を使用するように更新します
  • 必要なESLint依存関係をpackage.jsonに追加します
  • 既存のESLint設定が見つかった場合は保持します

例:

package.json
{
  "scripts": {
    "lint": "next lint"
  }
}

〜になる

package.json
{
  "scripts": {
    "lint": "eslint ."
  }
}

そして作成する

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', 'next/typescript'),
  {
    ignores: [
      'node_modules/**',
      '.next/**',
      'out/**',
      'build/**',
      'next-env.d.ts',
    ],
  },
]
 
export default eslintConfig

15.0

App RouterのRoute Segment Configのruntime値をexperimental-edgeからedgeに変換

app-dir-runtime-config-experimental-edge

注: このCodemodはApp Router固有です。

ターミナル
npx @next/codemod@latest app-dir-runtime-config-experimental-edge .

このCodemodは、Route Segment Configruntimeの値をexperimental-edgeからedgeに変換します。

例:

export const runtime = 'experimental-edge'

〜に変換

export const runtime = 'edge'

非同期Dynamic APIへの移行

動的レンダリングをオプトインしたAPIは、以前は同期アクセスをサポートしていましたが、現在は非同期になりました。この破壊的変更については、アップグレードガイドで詳細を読むことができます。

next-async-request-api
ターミナル
npx @next/codemod@latest next-async-request-api .

このCodemodは、非同期になった動的API（next/headersのcookies()、headers()、draftMode()）を、適切にawaitされるか、該当する場合はReact.use()でラップするように変換します。自動移行が不可能な場合、Codemodは型キャストを追加するか、ユーザーに手動で確認・更新が必要であることを通知するコメントを追加します。

例:

import { cookies, headers } from 'next/headers'
const token = cookies().get('token')
 
function useToken() {
  const token = cookies().get('token')
  return token
}
 
export default function Page() {
  const name = cookies().get('name')
}
 
function getHeader() {
  return headers().get('x-foo')
}

〜に変換

import { use } from 'react'
import {
  cookies,
  headers,
  type UnsafeUnwrappedCookies,
  type UnsafeUnwrappedHeaders,
} from 'next/headers'
const token = (cookies() as unknown as UnsafeUnwrappedCookies).get('token')
 
function useToken() {
  const token = use(cookies()).get('token')
  return token
}
 
export default async function Page() {
  const name = (await cookies()).get('name')
}
 
function getHeader() {
  return (headers() as unknown as UnsafeUnwrappedHeaders).get('x-foo')
}

ページ/ルートエントリ（page.js、layout.js、route.js、またはdefault.js）のparamsまたはsearchParamsプロパティへのプロパティアクセスを検出すると、コールサイトを同期関数から非同期関数に変換し、プロパティアクセスをawaitしようとします。非同期にできない場合（クライアントコンポーネントなど）、React.useを使用してPromiseをアンラップします。

例:

// page.tsx
export default function Page({
  params,
  searchParams,
}: {
  params: { slug: string }
  searchParams: { [key: string]: string | string[] | undefined }
}) {
  const { value } = searchParams
  if (value === 'foo') {
    // ...
  }
}
 
export function generateMetadata({ params }: { params: { slug: string } }) {
  const { slug } = params
  return {
    title: `My Page - ${slug}`,
  }
}

〜に変換

// page.tsx
export default async function Page(props: {
  params: Promise<{ slug: string }>
  searchParams: Promise<{ [key: string]: string | string[] | undefined }>
}) {
  const searchParams = await props.searchParams
  const { value } = searchParams
  if (value === 'foo') {
    // ...
  }
}
 
export async function generateMetadata(props: {
  params: Promise<{ slug: string }>
}) {
  const params = await props.params
  const { slug } = params
  return {
    title: `My Page - ${slug}`,
  }
}

知っておくと良いこと: このCodemodが手動介入が必要な可能性のある場所を特定しても、正確な修正を判断できない場合、コードにコメントまたは型キャストを追加して、手動で更新する必要があることをユーザーに通知します。これらのコメントは@next/codemodで、型キャストはUnsafeUnwrappedでプレフィックスが付けられます。これらのコメントを明示的に削除するまで、ビルドはエラーになります。詳細はこちら。

NextRequestのgeoおよびipプロパティを@vercel/functionsに置き換え

next-request-geo-ip
ターミナル
npx @next/codemod@latest next-request-geo-ip .

このCodemodは@vercel/functionsをインストールし、NextRequestのgeoおよびipプロパティを対応する@vercel/functions機能に変換します。

例:

import type { NextRequest } from 'next/server'
 
export function GET(req: NextRequest) {
  const { geo, ip } = req
}

〜に変換

import type { NextRequest } from 'next/server'
import { geolocation, ipAddress } from '@vercel/functions'
 
export function GET(req: NextRequest) {
  const geo = geolocation(req)
  const ip = ipAddress(req)
}

14.0

ImageResponseのインポートを移行

next-og-import
ターミナル
npx @next/codemod@latest next-og-import .

このCodemodは、動的なOG画像生成の使用のために、next/serverからのインポートをnext/ogに移動させます。

例:

import { ImageResponse } from 'next/server'

〜に変換

import { ImageResponse } from 'next/og'

viewportエクスポートを使用

metadata-to-viewport-export
ターミナル
npx @next/codemod@latest metadata-to-viewport-export .

このCodemodは、特定のviewportメタデータをviewportエクスポートに移行します。

例:

export const metadata = {
  title: 'My App',
  themeColor: 'dark',
  viewport: {
    width: 1,
  },
}

〜に変換

export const metadata = {
  title: 'My App',
}
 
export const viewport = {
  width: 1,
  themeColor: 'dark',
}

13.2

組み込みフォントを使用

built-in-next-font
ターミナル
npx @next/codemod@latest built-in-next-font .

このCodemodは@next/fontパッケージをアンインストールし、@next/fontのインポートを組み込みのnext/fontに変換します。

例:

import { Inter } from '@next/font/google'

〜に変換

import { Inter } from 'next/font/google'

13.0

Next Image のインポート名を変更

next-image-to-legacy-image
ターミナル
npx @next/codemod@latest next-image-to-legacy-image .

Next.js 10、11、または12アプリケーションのnext/imageインポートを、Next.js 13のnext/legacy/imageに安全にリネームします。また、next/future/imageをnext/imageにリネームします。

例:

pages/index.js
import Image1 from 'next/image'
import Image2 from 'next/future/image'
 
export default function Home() {
  return (
    <div>
      <Image1 src="/test.jpg" width="200" height="300" />
      <Image2 src="/test.png" width="500" height="400" />
    </div>
  )
}

〜に変換

pages/index.js
// 'next/image' becomes 'next/legacy/image'
import Image1 from 'next/legacy/image'
// 'next/future/image' becomes 'next/image'
import Image2 from 'next/image'
 
export default function Home() {
  return (
    <div>
      <Image1 src="/test.jpg" width="200" height="300" />
      <Image2 src="/test.png" width="500" height="400" />
    </div>
  )
}

新しいImageコンポーネントに移行

next-image-experimental
ターミナル
npx @next/codemod@latest next-image-experimental .

インラインスタイルを追加し、未使用のプロパティを削除することで、next/legacy/imageから新しいnext/imageへの危険な移行を行います。

  • layoutプロパティを削除し、styleを追加します。
  • objectFitプロパティを削除し、styleを追加します。
  • objectPositionプロパティを削除し、styleを追加します。
  • lazyBoundaryプロパティを削除します。
  • lazyRootプロパティを削除します。
ターミナル
npx @next/codemod@latest new-link .

Link Components内の<a>タグを削除します。

例:

<Link href="/about">
  <a>About</a>
</Link>
// transforms into
<Link href="/about">
  About
</Link>
 
<Link href="/about">
  <a onClick={() => console.log('clicked')}>About</a>
</Link>
// transforms into
<Link href="/about" onClick={() => console.log('clicked')}>
  About
</Link>

11

CRAからの移行

cra-to-next
ターミナル
npx @next/codemod cra-to-next

Create React AppプロジェクトをNext.jsに移行します。Pages Routerと、動作を一致させるための必要な設定を作成します。SSR中のwindowの使用による互換性の問題を回避するために、最初はクライアントサイドのみのレンダリングが使用され、Next.js固有の機能への段階的な採用を可能にするためにシームレスに有効化できます。

この変換に関するフィードバックは、こちらのディスカッションで共有してください。

10

Reactのインポートを追加

add-missing-react-import
ターミナル
npx @next/codemod add-missing-react-import

Reactをインポートしていないファイルを変換し、新しいReact JSX transformが機能するようにインポートを追加します。

例:

my-component.js
export default class Home extends React.Component {
  render() {
    return <div>Hello World</div>
  }
}

〜に変換

my-component.js
import React from 'react'
export default class Home extends React.Component {
  render() {
    return <div>Hello World</div>
  }
}

9

匿名コンポーネントを名前付きコンポーネントに変換

name-default-component
ターミナル
npx @next/codemod name-default-component

バージョン9以降。

匿名コンポーネントを名前付きコンポーネントに変換し、Fast Refreshで動作するようにします。

例:

my-component.js
export default function () {
  return <div>Hello World</div>
}

〜に変換

my-component.js
export default function MyComponent() {
  return <div>Hello World</div>
}

コンポーネントは、ファイル名に基づいたキャメルケースの名前を持ち、アロー関数とも連携します。

8

注: 組み込みのAMPサポートとこのCodemodはNext.js 16で削除されました。

AMP HOC をページ設定に変換

withamp-to-config
ターミナル
npx @next/codemod withamp-to-config

withAmp HOC を Next.js 9 のページ設定に変換します。

例:

// Before
import { withAmp } from 'next/amp'
 
function Home() {
  return <h1>My AMP Page</h1>
}
 
export default withAmp(Home)
// After
export default function Home() {
  return <h1>My AMP Page</h1>
}
 
export const config = {
  amp: true,
}

6

withRouterを使用

url-to-withrouter
ターミナル
npx @next/codemod url-to-withrouter

トップレベルページに自動的に注入される非推奨のurlプロパティを、withRouterとそれが注入するrouterプロパティを使用するように変換します。詳細はこちら: https://nextjs.dokyumento.jp/docs/messages/url-deprecated

例:

〜から
import React from 'react'
export default class extends React.Component {
  render() {
    const { pathname } = this.props.url
    return <div>Current pathname: {pathname}</div>
  }
}
〜へ
import React from 'react'
import { withRouter } from 'next/router'
export default withRouter(
  class extends React.Component {
    render() {
      const { pathname } = this.props.router
      return <div>Current pathname: {pathname}</div>
    }
  }
)

これは1つのケースです。(テスト済みの)変換されるすべてのケースは、__testfixtures__ ディレクトリで見つけることができます。