Vite × React で発生した Node.js バージョンエラーとその対処法

はじめに

株式会社イノベーションのTaikiです。
絶賛、花粉症が爆発しています。

概要

Vite × React で開発中に、以下のようなエラーが発生することがありました。

UnhandledPromiseRejectionWarning: SyntaxError: Unexpected token '||='

使用環境
OS：macOS Sequoia 15.2
Node.js：14.17.0 → 18.20.4 にアップグレード
パッケージマネージャ：npm 6.14.13
バージョン管理ツール：Volta
フレームワーク：Vite × React

エラーの原因

このエラーは、ES2021 で導入された「論理 OR 代入演算子（||=）」が、使用している Node.js のバージョンでサポートされていないために発生しました。
つまり、プロジェクト内や依存ライブラリで最新の構文が使用されている一方、Node.js のバージョンが古い場合にパースエラーとなるようです。

対処法

1. Node.js のバージョン管理ツールを確認

which node

例えば、/Users/yourusername/.volta/bin/node と表示された場合、Volta が Node.js を管理している状態になります。
このように、使用するツールによって対処方法が変わるので、まずは現在の状態を把握しましょう。

2. Node.js のバージョンアップ

最新の構文を利用するため、Node.js のバージョンをアップデートする必要があります。
プロジェクトごとに異なるバージョンを使いたい場合、各ツールの方法で対応できます。

nvm を利用する場合

1. .nvmrc ファイルの作成
   プロジェクトのルートディレクトリに、使用したい Node.js のバージョンを記載します。
   例: Node.js 18 系の場合

# .nvmrc
18.20.4

2. nvm コマンドで切り替え

nvm install   # .nvmrc に記載されたバージョンがなければインストール
nvm use       # .nvmrc のバージョンに切り替え

3. PATH の設定確認
   which node で、nvm 経由のパス（通常は ~/.nvm/versions/node/…）が表示されることを確認します。

Volta を利用する場合

1. プロジェクトディレクトリに移動

cd /path/to/your/project

2. Node.js 18系をインストールする

volta install node@18.20.4

3. プロジェクト内でバージョンを固定（ピン）する

volta pin node@18.20.4

3. この操作により、プロジェクトの package.json に Volta 用の設定が追加され、ディレクトリに入ると自動的に Node.js 18.20.4 が利用されます。

3. ツールの競合を解消する（複数のバージョン管理ツールがインストールされている場合）

今回のように、nvm と Volta など、複数のバージョン管理ツールが同時にインストールされていると、どちらの設定が優先されるかにより予期しない挙動になることがあります。

まずは which node で実際に使用されている Node.js のパスを確認し、どのツールが動いているかを把握しましょう。
私の場合、nvm で管理されていると思い込んでいましたが、実際には Volta が管理している Node.js が使われており、切り替えがうまくいかず沼りました。

不要なツールの設定は、シェルの初期化ファイル（~/.bashrc, ~/.zshrc など）で PATH から除外するか、あるいは片方のツールをアンインストールするのも有効です。

まとめ

• エラー原因: ES2021 の新しい構文（||=）が、古い Node.js バージョンではサポートされないため発生。
• nvm 対処: .nvmrc に必要なバージョンを記述し、nvm install と nvm use でバージョンを切り替え。
• Volta 対処: プロジェクトディレクトリで volta install node@18.20.4 および volta pin node@18.20.4 を実行して、プロジェクト単位で Node.js バージョンを固定。