Limitations and workarounds for static generation of MVC apps with JSS

Abstract

Limitations and workarounds for statically generating MVC applications with JSS and Headless Services

The process of converting an existing MVC application to a headless JSS application has some limitations.

Exporting Next.js applications

All the limitations that apply to using the static export functionality provided by Next.js with next export apply.

Because next export does not support multilingual apps, you must disable languageEmbedding.

To disable languageEmbedding:

  • Modify your Sitecore configuration and set the value for languageEmbedding to never:

    <configuration>    
      <sitecore>          
        <links>        
          <urlBuilder>                    
            <languageEmbedding>never</languageEmbedding>        
          </urlBuilder>           
        </links>    
      </sitecore>
    <configuration>

Furthermore, if you have MVC components that render images, you must provide the full path to the media files on the Sitecore server.

Note

Sitecore Experience Edge provides a CDN for your media files and already embeds the server URL for images.

To include the server URL in the media source URL:

  • Modify your Sitecore configuration for Media.AlwaysIncludeServerUrl:

    <setting name="Media.AlwaysIncludeServerUrl" set:value="true" />

Sitecore Analytics and Personalization

All the limitations for Sitecore analytics and personalization in JSS apps apply.

Session-based features

Any features relying on session information (ASP.NET or cookies) on the server-side, such as account login, cart information, or GDPR compliance, cannot be used with Next.js static generation.

To use session-based features, you must do one of the following:

  • Use a Next.js server-side rendering route. This approach does not work with Experience Edge.

  • Use Next.js rewrites to allow complete pass-through to Sitecore CD as an incremental strategy. For example, you can defer the entire account section of the site:

    {
      source: '/account/:path*',
      destination: `${jssConfig.sitecoreApiHost}/account/:path*`,
    }
  • Refactor the application to use a client-side approach. This is likely the preferred approach for components that appear on every page of the site, such as conditional Login/Logout in the header or GDPR compliance acceptance.

Sitecore Forms

For existing MVC forms to work in a JSS application, you must make some adjustments so that MVC form wrappers render as HTML and the Next.js application has the necessary redirects for forms.

Important

Sitecore Forms only work with Next.js when using the REST Layout Service and server-side rendering.

To render MVC form wrappers as HTML:

To configure form-specific redirects:

  • In the Next.js JSS app, in the next.config.js file, in the redirects section, add the following rules:

    // Sitecore forms
    {
      source: '/sitecore%20modules/:path*',
      destination: `${jssConfig.sitecoreApiHost}/sitecore%20modules/:path*`,
    },
    {
      source: '/formbuilder',
      destination: `${jssConfig.sitecoreApiHost}/formbuilder`,
    },