JSS 22.11のNext.jsアプリをバージョン22.12にアップグレードしてください

既存のアプリでアプリケーション依存関係を更新する

アップグレードしたアプリケーションを正しく動作させるには、依存関係を更新する必要があります。

依存関係を更新するには:

1. 既存のアプリケーションのpackage.jsonでは、@sitecore-jssパッケージをバージョン ~22.12.0に更新してください。

2. 以下の依存関係を指定されたバージョンに更新します:

   • Next.jsはバージョン16にアップデートされました。ここで記載されていない変更を、Next.js 16のアップグレードガイドに基づいて適用する必要があるかもしれません。

     "next": "^16.1.1",

     !注JSX.Elementに関連するタイプエラー(例えばCdpPageViewのようなコンポーネント)があれば、JSX.Elementを使うところに以下のインポートを追加してください:

     import type { JSX } は 'react' から;

   • Node.jsはバージョン24にアップデートされました。ここで言及されていない変更を、Node.js 24のアップグレードガイドに基づいてアプリに適用する必要があるかもしれません。

     "@types/node": "^24.10.4",

3. 以下のコマンドで依存関係をインストールします:

   npm install

JSS 22.12 Next.jsアプリケーションを作成する

アップグレードのプロセスをできるだけ簡単にするために、JSS 22.12 Next.jsアプリケーションを作成しましょう。このアプリから既存のアプリにファイルをコピーできます。

JSS 22.12 Next.jsアプリケーションを作成するには:

1. コンソールでは、次のコマンドを実行します:

   npx [email protected] nextjs

2. [email protected]パッケージのインストールを促された場合は、yに答えてください。

3. JSS 22.12 Next.jsアプリのフォルダパスを入力します。例えば、./jss2212と入力すると、現在の作業ディレクトリにアプリフォルダを作成します。

4. 残りのプロンプトに従い、既存のアプリケーションと同じデータ取得(GraphQLまたはREST)とプリレンダリング(SSGまたはSSR)を選択してください。

5. Sitecore XM Cloudのために建築しているか尋ねられたら、n答えてください。

6. 既存のアプリケーションで使っている他のアドオンを選択し、Enterキーを押してください。

スクリプトはその後、アプリケーションの依存関係をインストールします。

!注XM Cloudは現在SitecoreAIですエンジニアリング資産が更新されている間、一部のコード例、画像、UIラベルは引き続きXM Cloudを使用する場合があります。

既存のアプリでNext.jsテンプレートファイルを更新してください

これは、既存のアプリケーション内のファイルを新しいJSS 22.12アプリの対応ファイルと同期する方法を説明しています。

Next.jsテンプレートファイルの更新:

1. ミドルウェアはその目的をよりよく反映するためにプロキシに改名されました。src/middleware.tssrc/proxy.ts

   • エクスポート関数を修正して、evパラメータを受け入れなくなるようにします:

     export default async function proxy(req: NextRequest) { return middleware(req); }

   • /src/lib/middleware/index.tsのメソッド署名を修正して、もはやNextFetchEventを使わないようにしてください:

     export interface MiddlewarePlugin { /** * Detect order when the plugin should be called, e.g. 0 - will be called first (can be a plugin which data is required for other plugins) */ order: number; /** * A middleware to be called, it's required to return @type {NextResponse} for other middlewares */ exec(req: NextRequest, res?: NextResponse): Promise; } ... export default async function middleware( req: NextRequest ): Promise { ...

     const finalRes = await (Object.values(plugins) as MiddlewarePlugin) .sort((p1, p2) => p1.order - p2.order) .reduce((p, plugin) => p.then((res) => plugin.exec(req, res)), Promise.resolve(response)); ... ...

   • NextFetchEventのインポートをすべて削除してください。

2. プレースホルダーでReact Suspenseを無効にすることで、コンポーネントは追加のSuspenseオーバーヘッドなしにより速くレンダリングされます。しかし、アプリが怠惰にロードされたコンポーネントを 内で使用し、ロードのフォールバックが現れることを期待している場合は、アップグレード時に以下の手順を実行する必要があります:
   • 動的または怠惰なコンポーネントがレンダリングされている使用状況 監査。
   • サスペンスベースの読み込み状態に依存するプレースホルダーに disableSuspense={false} を追加してください。

SXAアドオンの更新

SXAアドオンのアップデート:

1. sass-alias依存を取り除く:

   "sass-alias": "^1.0.5"

2. /src/lib/next-config/plugins/sass.jsを修正する:

   • すべてのsass-aliasインポートを探す:

     const SassAlias = require('sass-alias');

   • 次のものに置き換えてください:

     const fs = require('fs'); const { pathToFileURL, fileURLToPath } = require('url');

   • createAliasImporterという新しい関数を追加します。

     /** * Custom Sass importer compatible with Next.js 16's Sass API * Implements canonicalize and load methods as required by the new Sass JS API */ function createAliasImporter(aliases) { return { canonicalize(url, context) { // Check if the URL matches any of our aliases for (const alias, aliasPath of Object.entries(aliases)) { if (url.startsWith(alias)) { // Remove the alias prefix and resolve the path const relativePath = url.slice(alias.length); // Remove leading slash if present const cleanPath = relativePath.startsWith('/') ? relativePath.slice(1) : relativePath; const fullPath = path.resolve(aliasPath, cleanPath);

     // Try to find the file with common extensions const extensions = '.scss', '.sass', '.css'; for (const ext of extensions) { const filePath = fullPath + ext; if (fs.existsSync(filePath)) { return pathToFileURL(filePath); } }

     // Try as a directory with index file if (fs.existsSync(fullPath) && fs.statSync(fullPath).isDirectory()) { for (const ext of extensions) { const indexPath = path.join(fullPath, 'index' + ext); if (fs.existsSync(indexPath)) { return pathToFileURL(indexPath); } } }

     // Try with underscore prefix (Sass partials) const dir = path.dirname(fullPath); const basename = path.basename(fullPath); for (const ext of extensions) { const partialPath = path.join(dir, '_' + basename + ext); if (fs.existsSync(partialPath)) { return pathToFileURL(partialPath); } }

     // Return the path even if file doesn't exist yet, let Sass handle the error return pathToFileURL(fullPath); } }

     // Return null if no alias matches, let other importers handle it return null; },

     load(canonicalUrl) { if (canonicalUrl.protocol === 'file:') { // Convert file:// URL back to file path const filePath = fileURLToPath(canonicalUrl);

     if (fs.existsSync(filePath)) { const contents = fs.readFileSync(filePath, 'utf8'); // Determine syntax based on file extension const syntax = filePath.endsWith('.sass') ? 'indented' : 'scss'; return { contents, syntax, }; } } return null; }, }; }

   • sassPluginエクスポートを新しい実装に合わせて修正してください:

     const sassPlugin = (nextConfig = {}) => { const aliases = { '@sass': path.join(__dirname, '../../../assets', 'sass'), '@fontawesome': path.join(__dirname, '../../../../node_modules', 'font-awesome'), };

     return Object.assign({}, nextConfig, { sassOptions: { importers: createAliasImporter(aliases), // temporary measure until new versions of bootstrap and font-awesome released quietDeps: true, silenceDeprecations: "import", "legacy-js-api", }, webpack: (config, options) => { // Exclude Node.js built-in modules used by this plugin from client bundle if (!options.isServer) { config.resolve.fallback = { ...config.resolve.fallback, fs: false, path: false, url: false, }; }

     // Call existing webpack config if present if (typeof nextConfig.webpack === 'function') { return nextConfig.webpack(config, options); }

     return config; }, }); };

今後のステップ

アップグレードプロセスを最終決定するには、発生したエラーや警告を必ず解決してください。必要に応じて、JSS固有の問題に対してデバッグログを有効にしてください。