AWS AmplifyでNuxt 3からNuxt 4への移行

backham
技術
Nuxt 3から4への移行とAWS AmplifyでのNode.js 22対応

目次

 

はじめに

Nuxt 3 から Nuxt 4 にアップグレードを試したら、AWS Amplify のデプロイで思わぬところでハマってしまいました。。 特に Node.js 22 のcrypto.hashエラーと pnpm の設定で苦戦したので、同じような問題に遭遇した方の参考になればと思い、解決までの道のりをまとめました。

 

概要

先に結論を書いておくと、AWS Amplify で Node.js 22.18.0 を明示的に指定して、pnpm をグローバルインストールすることがポイントでした。

Nuxt 4 移行自体は比較的スムーズでしたが、Vite 7 が要求する Node.js 20.12.0 以上のcrypto.hash API が AWS Amplify では使えず、ビルドエラーに悩まされました。 さらに pnpm のワークスペース設定でもつまずきましたが、最終的にはシンプルな設定で解決できました。

 

開発環境

本記事の内容は以下の環境で検証しています：

  • OS: macOS Sonoma 15.6
  • Node.js: 22.18.0 (Volta 管理)
  • pnpm: 9.15.4
  • Nuxt: 3.13.x → 4.0.2
  • AWS Amplify: Gen 2
  • ビルド時間: 約 3 分（改善前）→ 約 2 分（改善後）

 

発生した問題と解決方法

1. crypto.hash エラーの解決

Nuxt 4 にアップグレード後、ローカルでは問題なく動作するのに、AWS Amplify でビルドすると以下のエラーが発生しました。

crypto.hash is not a function

原因は Vite 7 が Node.js 20.12.0 以上で追加されたcrypto.hashメソッドを使用していたためです（参照：Node.js 20.12.0 リリースノート）。 AWS Amplify のデフォルト Node.js バージョンでは利用できないため、amplify.yml で明示的に Node.js 22.18.0 を指定する必要がありました。

Node.js バージョン選択の理由
  • Node.js 20 LTS: 2024 年 10 月〜2026 年 4 月（Active LTS）
  • Node.js 22: 2024 年 4 月リリース、2024 年 10 月から LTS
  • 参照：Node.js Release Schedule

長期的なメンテナンスを考慮し、Node.js 22 への移行を選択しました。

変更前後の amplify.yml

Before（変更前）：

# amplify_metroweather_bk20250731.yml
version: 1
frontend:
  phases:
    preBuild:
      commands:
        - "corepack enable"
        - "npx --yes nypm i"
    build:
      commands:
        - "pnpm run build"
  artifacts:
    baseDirectory: .amplify-hosting
    files:
      - "**/*"

After（変更後）：

# amplify.yml
version: 1
frontend:
  phases:
    preBuild:
      commands:
        # Node.js 22.18.0を明示的に指定
        - nvm install 22.18.0
        - nvm use 22.18.0
        - nvm alias default 22.18.0
        - "echo 'Node version:' && node --version"
        # crypto.hashが使えるか確認
        - "node -e 'console.log(typeof crypto.hash)'"

 

2. pnpm インストールエラーの解決

次に遭遇したのが pnpm の問題です。AWS Amplify には pnpm がプリインストールされていないため、以下のエラーが発生しました。

pnpm: command not found

さらに、pnpm をインストールしても今度は別のエラーが。。

ERROR packages field missing or empty

これは pnpm-workspace.yaml の設定が不足していたためでした。以下の設定で解決しました。

# pnpm-workspace.yaml
packages:
  - "."

ignoredBuiltDependencies:
  - "@tailwindcss/oxide"
  - vue-demi

onlyBuiltDependencies:
  - "@parcel/watcher"
  - esbuild

amplify.yml でも pnpm のインストールを追加しました。

# amplify.yml（続き）
        # pnpmをインストール
        - npm install -g pnpm@9.15.4
        - pnpm install
    build:
      commands:
        - pnpm run build

 

3. TypeScript peer dependency 警告の解決

複数のパッケージで TypeScript バージョンの不一致警告が発生しました。

✕ unmet peer typescript@">=4.8.4 <5.9.0": found 5.9.2

package.json の pnpm overrides で統一することで解決しました。

{
  "devDependencies": {
    "typescript": "~5.6.3"
  },
  "pnpm": {
    "overrides": {
      "typescript": "~5.6.3",
      "node-domexception": "^2.0.0"
    }
  }
}

 

最終的な設定ファイル

amplify.yml（完全版）
version: 1
frontend:
  phases:
    preBuild:
      commands:
        # Node.js 22.18.0を明示的に指定 (crypto.hash対応)
        - nvm install 22.18.0
        - nvm use 22.18.0
        - nvm alias default 22.18.0
        - "echo 'Node version after update:' && node --version"
        - "echo 'Verifying crypto.hash availability'"
        - "node -e 'console.log(typeof crypto.hash)'"
        # pnpmをインストール
        - npm install -g pnpm@9.15.4
        - "echo 'pnpm installed successfully'"
        - pnpm install
    build:
      commands:
        - pnpm run build
  artifacts:
    baseDirectory: .amplify-hosting
    files:
      - "**/*"
package.json（重要部分）
{
  "volta": {
    "node": "22.18.0",
    "pnpm": "9.15.4"
  },
  "devDependencies": {
    "nuxt": "^4.0.2",
    "typescript": "~5.6.3"
  },
  "pnpm": {
    "overrides": {
      "@nuxt/kit": "4.0.2",
      "typescript": "~5.6.3",
      "node-domexception": "^2.0.0"
    }
  }
}

 

トラブルシューティング

・crypto.hash エラーが続く場合 Node.js のバージョンが本当に 22.18.0 になっているか確認してください。nvm alias defaultを忘れるとビルド中に元のバージョンに戻ることがあります。

・pnpm install でエラーが出る場合 pnpm-workspace.yaml の packages フィールドが正しく設定されているか確認してください。最低限packages: ['.']が必要です。

・TypeScript エラーが解決しない場合 node_modules と pnpm-lock.yaml を削除して、再度pnpm installを実行してみてください。

・ビルドサイズが大きすぎる場合 Nuxt 4 では自動的にチャンク分割されますが、必要に応じて nuxt.config.ts で manualChunks を設定できます。

 

リファクタリング後の最適化

当初は.nvmrc ファイルで Node.js バージョンを管理していましたが、AWS Amplify では使用されないことが分かりました。 最終的に以下のような構成に最適化しました。

  • ローカル開発: Volta 設定（package.json）でバージョン管理
  • AWS Amplify: amplify.yml で明示的にバージョン指定
  • .nvmrc ファイルは削除（重複管理を避けるため）

この変更により、設定がシンプルになり保守性が向上しました。

 

まとめ

Nuxt 4 への移行と AWS Amplify でのデプロイは、主に以下の 3 つのポイントを押さえれば成功します：

  1. Node.js 22.18.0 への明示的なアップグレード（crypto.hash API 対応）
  2. pnpm のグローバルインストールとワークスペース設定
  3. TypeScript バージョンの統一（pnpm overrides 使用）

パフォーマンスも改善され、ビルド時間が約 3 分から約 2 分に短縮されました。

 

参考リンク

 

 

最後まで読んでいただき、ありがとうございました！
この記事が少しでもお役に立てれば嬉しいです。良い開発ライフを！