Upgrade Content SDK 0.2.0 Next.js apps to version 0.3.0

This guide covers most of the changes you must make to your existing Content SDK 0.2.0 applications to take advantage of the improvements in version 0.3.0.

This version of the Content SDK updates references to replace mentions of jss, updates the scaffolding script, and renames the SitecoreContext component, related APIs, and some environment variables to align with common conventions. This version also introduces the option to automatically generate component maps.

Because of the nature of JavaScript and Next.js application development, this guide doesn't account for all the customization you might have in your existing application.

Before you begin

  • If you have a JSS app that you want to convert into a Content SDK app, follow the migration guide. Then, follow the upgrade guide to upgrade from 0.1.0 to 0.2.0, before you upgrade from 0.2.0 to 0.3.0.

  • 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:

  1. Update references to JSS

  2. Update environment variables

  3. Update application dependencies in your existing app

  4. Create a template 0.3.0 Content SDK application for Next.js

  5. Update the Next.js template files in your existing app

  6. (OPTIONAL) Use automatic component map generation

Update references to JSS

This version of the Content SDK replaces all mentions of jss in class names, IDs, and package scopes with Content SDK-centric names. There're no changes to the run time behaviour, so your application will work as before after updating the names.

To update references to jss:

  1. Rename references to the following:

    Old

    New

    Type

    sc-jss-editing-error

    sc-content-sdk-editing-error

    CSS class

    sc-jss-placeholder-error

    sc-content-sdk-placeholder-error

    CSS class

    ReactJssComponent

    ReactContentSdkComponent

    type

    NextjsJssComponent

    NextjsContentSdkComponent

    type

    JssLayoutQuery

    ContentSdkLayoutQuery

    GraphQL layout query

    getJssPagesClientData()

    getContentSdkPagesClientData()

    utility function

    SitecoreTemplateId.JssApp

    SitecoreTemplateId.ContentSdkApp

    template ID constant

  2. Rename references of the core debug namespace to content-sdk.

    For example: Rename DEBUG=core:... to DEBUG=content-sdk:....

Update environment variables

Update references to the following environment variables in your .env files, deployment configurations, and CI/CD pipelines.

Old

New

JSS_EDITING_SECRET

SITECORE_EDITING_SECRET

NEXT_PUBLIC_SITECORE_SITE_NAME

NEXT_PUBLIC_DEFAULT_SITE_NAME

DISABLE_SSG_FETCH

GENERATE_STATIC_PATHS

Update application dependencies in your existing app

For your upgraded application to work correctly, you must update dependencies.

To update your dependencies:

  1. In your existing application's package.json file:

    • Update every @sitecore-content-sdk package to version 0.3.0.

    • Update the @sitecore-feaas/clientside package to version ^0.6.0.

    • Update the @sitecore/components package to version ~2.1.0.

  2. Install the dependencies with the following command:

    RequestResponse
    npm install

Create a template 0.3.0 Content SDK application for Next.js

To simplify the upgrade process as much as possible, create a Content SDK 0.3.0 Next.js application. You can then copy some files from this app into your existing app.

To create a 0.3.0 Content SDK Next.js application:

  1. In a console, run the following command:

    RequestResponse
    npx [email protected] nextjs

  2. If prompted to install the [email protected] package, answer y.

  3. Enter the folder path for the new app. For example, enter ./content-sdk-030, to create the app folder in your current working directory.

  4. When prompted, choose the same prerendering method (SSG or SSR) as used in your existing Content SDK application.

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 Content SDK 0.3.0 template app.

To update the Next.js template files:

  1. Update references and imports for the following component, interfaces, hook, higher-order component, and properties:

    Old

    New

    Type

    SitecoreContext

    SitecoreProvider

    component

    SitecoreContextProps

    SitecoreProviderProps

    interface

    SitecoreContextState

    SitecoreProviderState

    interface

    SitecoreContextValue

    SitecoreProviderPageContext

    interface

    SitecoreContextReactContext

    SitecoreProviderReactContext

    interface

    WithSitecoreContextOptions

    WithSitecoreOptions

    interface

    WithSitecoreContextProps

    WithSitecoreProps

    interface

    WithSitecoreContextHocProps

    WithSitecoreHocProps

    interface

    useSitecoreContext()

    useSitecore()

    hook

    withSitecoreContext()

    withSitecore()

    higher-order component

    context

    pageContext

    property (the page context provided by SitecoreProvider)

    updateSitecoreContext

    updateContext

    property

    sitecoreContext

    pageContext

    property

  2. Remove the sitecoreEdgeUrl property from the EditingScripts component. The component now uses the Edge URL configuration from SitecoreProvider.

  3. Update references to the component-level getServerSideProps and getStaticProps methods to getComponentServerProps without changing the existing method signature.

    If your component contains code that's executed based on static or server side Next.js context, import the isServerSidePropsContext helper method and implement it based on the following example:

    RequestResponse
    import { isServerSidePropsContext } from '@sitecore-content-sdk/nextjs/utils'; 
 
... 
 
export const getComponentServerProps: GetComponentServerProps = async ( 
  rendering, 
  layoutData, 
  context 
) => { 
  if (isServerSidePropsContext(context)) { 
    // function implementation 
  } 
};

  4. Create a folder named content-sdk in src/components. Move the following components into the content-sdk folder and update their imports:

    Moved file

    Affects

    Updated import

    SitecoreStyles.tsx

    src/Layout.tsx
    RequestResponse
    import SitecoreStyles from 'src/components/content-sdk/SitecoreStyles';

    CdpPageView.tsx

    src/Scripts.tsx
    RequestResponse
    import CdpPageView from 'components/content-sdk/CdpPageView';

    FEAASScripts.tsx

    src/Scripts.tsx
    RequestResponse
    import FEAASScripts from 'components/content-sdk/FEAASScripts';

  5. Create another folder named sxa in src/components. Move the following components into the sxa folder and update their imports:

    • ColumnSplitter.tsx

    • Container.tsx

    • ContentBlock.tsx

    • Image.tsx

    • LinkList.tsx

    • Navigation.tsx

    • PageContent.tsx

    • PartialDesignDynamicPlaceholder.tsx

    • Promo.tsx

    • RichText.tsx

    • RowSplitter.tsx

    • Title.tsx

  6. This version of the Content SDK removes the GraphQL introspection data (GraphQLIntrospectionResult.json). If you're using the Next.js starter, you must remove the tsconfig.scripts.json file, /scripts and /src/temp folders. Then, make the following changes to your package.json:

    • In devDependencies, remove the following dependencies:

      RequestResponse
      "chalk": "~4.1.2",
"chokidar": "~4.0.3",
"graphql": "~16.11.0",

    • Update the lint script with the following:

      RequestResponse
      "lint": "eslint ./src/**/*.tsx ./src/**/*.ts,
      Note

      If you wish to set up automatic GraphQL code generation for your Content SDK app, see Implement GraphQL code generation for more information.

  7. In your existing application's sitecore.cli.config.ts file:

    • Locate the following defineCliConfig import statement:

      RequestResponse
      import { defineCliConfig } from '@sitecore-content-sdk/nextjs/config';

    • Replace it with the following:

      RequestResponse
      import { defineCliConfig } from '@sitecore-content-sdk/nextjs/config-cli';

Use automatic component map generation

You can optionally set up automatic component map generation for your workspace. If you wish to manage the component-map.ts file yourself, you can skip this section.

To set up automatic component map generation:

  1. In your existing application's sitecore.cli.config.ts file, in defineCliConfig, add the following section below the build section:

    RequestResponse
    build: {
  ...
},
// Add this section 
componentMap: {
  paths: ['src/components'],
  // Exclude content-sdk auxillary components
  exclude: ['src/components/content-sdk/*'],
},

  2. Move src/lib/component-map.ts file into the .sitecore folder.

    Modify all the imports to use .sitecore/component-map instead of src/lib/component-map.

  3. In your app’s package.json file:

    • In the scripts section, add the following:

      RequestResponse
      "sitecore-tools:generate-map": "sitecore-tools project component generate-map",
"sitecore-tools:generate-map:watch": "sitecore-tools project component generate-map --watch",

    • Modify the build script to include a sitecore-tools:generate-map call:

      RequestResponse
      "build": "cross-env NODE_ENV=production npm-run-all --serial sitecore-tools:generate-map sitecore-tools:build next:build",

    • Modify the dev script to include a sitecore-tools:generate-map:watch call:

      RequestResponse
      "dev": "cross-env NODE_ENV=development npm-run-all --serial sitecore-tools:build --parallel next:dev sitecore-tools:generate-map:watch",

Next steps

To finalize the upgrade process, make sure you resolve any errors and warnings you encounter. Enable debug logging for Content SDK specific issues to assist you if necessary.

Do you have some feedback for us?

If you have suggestions for improving this article,