Next.js 14.2.x 系 build 時、shiki でシンタックスハイライトが反映されない

エラーメッセージと原因

Next.js 14.2.x 系で Shiki を使用した際、ビルド時に以下のようなエラーが発生することがあります。

このエラーの原因は、Shiki がエクスポートする JSON.parse を含むテンプレート文字列が Next.js のバンドラーによって不正に変換されてしまうことです。特に、Shiki ライブラリの v1.18.0 と Next.js v14.2.x 以降の組み合わせで発生しやすくなります。この問題は、Next.js 15 のカナリア版では修正されています。

一時的な解決策: Next.js のバージョンをダウングレード

このバグの一時的な解決策として、Next.js のバージョンをダウングレードする方法があります。

• npm install next@14.1.0 で、バージョン 14.1.0 にダウングレード
• 再びアップデートしたい場合は、npm install next@14.2.13 で元に戻すことが可能です

恒久的な解決策: Shiki バージョンをアップデート

Shiki のバージョンを 1.21.0 にアップデートすることで、この問題は修正されます。修正内容にはビルドパフォーマンスの改善も含まれており、アセットのバンドリングをスキップするように変更されています。この変更により、Next.js の v14.2.x 以降で発生していたバンドルエラーが解消される可能性があります。

修正に関する PR:

Shiki のバージョン 1.21.0 をインストールすることで、問題を解決できます。

Shiki の修正内容について

Shiki バージョン 1.21.0 では、以下のような変更が加えられています。

• packages/shiki/src/assets 以下の langs や themes および *.json がバンドリング対象から除外されました。
• 新しく追加された packages/shiki/src/langs や packages/shiki/src/themes のディレクトリもバンドリング対象から除外されています。

これにより、アセットファイルを再バンドルせず、そのまま dist にコピーする方式に変更されています。この修正は、ビルド時のパフォーマンス向上だけでなく、ビルドエラーの解決にも寄与しています。

次回、同様の問題が発生した場合の対策

次回同様の問題が発生した場合、Shiki の修正が反映された最新版の Next.js にアップデートすることを検討してください。特に、次の安定版となる Next.js 14.3 系のリリースを待つのが良いでしょう。

Next.js のパッケージアップデート手順

まず、Next.js の最新版がリリースされているかを確認します。

Next.js 14.x の最新バージョンがリリースされている場合、以下のコマンドでその最新バージョンにアップデートします。

公式リリース情報については、Next.js GitHub リポジトリで確認することができます。

ダウングレードする場合の手順

Next.js のバージョンを 14.1.x にダウングレードする場合、以下のコマンドを使用します。

14.1.0 版の場合:

14.1.1 版の場合:

これにより、Shiki と Next.js の互換性の問題を回避し、シンタックスハイライトが正しく機能するようになります。