Upgrade JSS 21.7 Next.js apps to version 22.0.0
This topic covers most of the changes you must make to your existing JSS 21.7 applications to take advantage of the new features in version 22.0.0. However, because of the nature of JavaScript and Next.js application development, this topic doesn't account for all the customization you might have in your existing application.
Several of the changes listed here repeat what's in the 21.6 and 21.7 upgrade guides. If you haven't already made all of these changes, you must now do so in order to prevent build errors when upgrading to 22.0.0.
While performing the upgrade, consider the JSS templates and add-ons you used when creating your Next.js application. You can find them in your package.json
file. For example, a JSS 21.7 application included in the XM Cloud starter foundation uses the following templates and add-ons:
-
nextjs
-
nextjs-xmcloud
-
nextjs-sxa
-
nextjs-multisite
-
If you haven't already done so, upgrade your app to JSS 21.7.
-
Familiarize yourself with the changelog. If your application is heavily customized, the changelog can provide guidance on what additional changes you need that are not covered in this topic.
This topic describes how to:
Update environment variables for your existing app
If the JSS_APP_NAME
environment variable is present, rename it to SITECORE_SITE_NAME
.
Update application dependencies in your existing app
For your upgraded application to work correctly, you must also update dependencies.
To update your dependencies:
-
In your existing application's
package.json
file, do the following:-
Update every
@sitecore-jss
package to version~22.0.0
. -
Update the
@sitecore-cloudsdk/events
package to version^0.3.0
.
-
-
Install the dependencies with the following command:
RequestResponsenpm install
Create a JSS 22.0.0 Next.js application
To simplify the upgrade process as much as possible, create a JSS 22.0.0 Next.js application with the XM Cloud add-on. You can then copy some files from this app into your existing app.
To create a JSS 22.0.0 Next.js application with the XM Cloud add-on included:
-
In a console, run the following command:
RequestResponsenpx create-sitecore-jss@^22.0.0 nextjs
-
If prompted to install the
[email protected]
package, answer y. -
Enter the folder path for the JSS 22.0.0 Next.js app. For example, enter
./jss22
, to create the app folder in your current working directory. -
Follow the remaining prompts, selecting the same options for data fetching (
GraphQL
orREST
) and prerendering (SSG
orSSR
) as in your existing application. -
When asked if you are building for Sitecore XM Cloud, answer y to install the XM Cloud add-on.
-
Select other add-ons used by your existing application and press Enter.
The script then installs the application dependencies.
Update the Next.js template files in your existing app
This explains how to synchronize files in your existing application with corresponding files from your new JSS 22.0.0 app.
To update the Next.js template files:
-
If you have not customized the
/src/lib/layout-service-factory.ts
file, replace it with the 22.0.0 version. Otherwise, modify the file as follows:-
Add the following import statement:
RequestResponseimport clientFactory from 'lib/graphql-client-factory';
-
Locate the following
GraphQLLayoutService
constructor options, if present:RequestResponseendpoint: config.graphQLEndpoint, apiKey: config.sitecoreApiKey,
-
Replace those options with the following:
RequestResponseclientFactory,
-
-
If you have not customized the
/src/lib/dictionary-service-factory.ts
file, replace it with the 22.0.0 version. Otherwise, modify the file as follows:-
Add the following import statement:
RequestResponseimport clientFactory from 'lib/graphql-client-factory';
-
Locate the following
GraphQLDictionaryService
constructor options, if present:RequestResponseendpoint: config.graphQLEndpoint, apiKey: config.sitecoreApiKey,
-
Replace those options with the following:
RequestResponseclientFactory,
-
-
If you're importing the
isEditorActive
,resetEditorChormes
,resolveUrl
,handleEditorFastRefresh
, orgetPublicUrl
functions in your custom code, ensure they are imported fromsitecore-jss-nextjs/utils
and notsitecore-jss-nextjs
.
Update the XM Cloud add-on
To update the XM Cloud add-on:
-
If you have not customized the
/src/lib/middleware/plugins/personalize.ts
file, replace it with the 22.0.0 version. Otherwise, modify it as follows:-
Import the GraphQL request client factory:
RequestResponseimport clientFactory from 'lib/graphql-client-factory';
-
In the
edgeConfig
object, locate the following options, if present:RequestResponseendpoint: config.graphQLEndpoint, apiKey: config.sitecoreApiKey,
-
Replace those options with the following:
RequestResponseclientFactory,
-
Update the SXA add-on
To upgrade the SXA add-on:
-
If you have not customized the
/src/lib/middleware/plugins/redirects.ts
file, replace it with the 22.0.0 version. Otherwise, modify it as follows:-
Add the following import statement:
RequestResponseimport clientFactory from 'lib/graphql-client-factory';
-
Locate the following
RedirectsMiddleware
constructor options:RequestResponseendpoint: config.graphQLEndpoint, apiKey: config.sitecoreApiKey,
-
Replace them with the following:
RequestResponseclientFactory,
-
-
If you have not customized the
/src/pages/404.tsx
and/src/pages/500.tsx
files, replace them with the 22.0.0 versions. Otherwise, modify them as follows:-
In the
getStaticProps
function, add the following import statement:RequestResponseimport clientFactory from 'lib/graphql-client-factory';
-
For the
GraphQLErrorPagesService
instantiation, locate the following options:RequestResponseendpoint: config.graphQLEndpoint, apiKey: config.sitecoreApiKey,
-
Replace them with the following:
RequestResponseclientFactory,
-
-
If you have not customized the
\src\pages\api\sitemap.ts
file, replace it with the 22.0.0 version. Otherwise, modify it as follows:-
Add the following import statement:
RequestResponseimport clientFactory from 'lib/graphql-client-factory';
-
For the
GraphQLSitemapXmlService
instantiation, locate the following options:RequestResponseendpoint: config.graphQLEndpoint, apiKey: config.sitecoreApiKey,
-
Replace them with the following:
RequestResponseclientFactory,
-
-
If you have not customized the
\src\pages\api\robots.ts
file, replace it with the 22.0.0 version. Otherwise, modify it as follows:-
Add the following import statement:
RequestResponseimport clientFactory from 'lib/graphql-client-factory';
-
Remove the
config
import:RequestResponseimport config from 'temp/config';
-
For the
GraphQLRobotsService
instantiation, locate the following options:RequestResponseendpoint: config.graphQLEndpoint, apiKey: config.sitecoreApiKey,
-
Replace them with the following:
RequestResponseclientFactory,
-
Update the Multisite add-on
To update the Multisite add-on:
-
If you have not customized the
/scripts/config/plugins/multisite.ts
file, replace it with the 22.0.0 version. Otherwise, do the following:-
Add the following import statement:
RequestResponseimport { createGraphQLClientFactory } from 'lib/graphql-client-factory/create';
-
Remove the following option from the
GraphQLSiteInfoService
constructor call:RequestResponseuseSiteQuery: true,
-
Also in the
GraphQLSiteInfoService
constructor call, locate the following options:RequestResponseendpoint: config.graphQLEndpoint, apiKey: config.sitecoreApiKey,
-
Replace those two options with the following:
RequestResponseclientFactory: createGraphQLClientFactory(config),
-
-
If you have not customized the
/src/lib/sitemap-fetcher/plugins/graphql-sitemap-service.ts
file, replace it with the 22.0.0 version. Otherwise, do the following:-
Add the following import statement:
RequestResponseimport clientFactory from 'lib/graphql-client-factory';
-
For the
MultisiteGraphQLSitemapService
instantiation, locate the following options:RequestResponseendpoint: config.graphQLEndpoint, apiKey: config.sitecoreApiKey,
-
Replace them with the following:
RequestResponseclientFactory,
-
Next steps
To finalize the upgrade process, make sure you resolve any errors and warnings you encounter. Enable debug logging for JSS specific issues to assist you if necessary.