Walkthrough: Statically generating an MVC application
Using headless rendering solutions provided by Sitecore, such as Sitecore Headless Services and the Sitecore JavaScript Rendering SDKs (JSS), you can statically generate your MVC application using a JSS Next.js app.
Before starting the process of statically generating your MVC application using JSS, you must meet the following prerequisites:
-
You have access to a Sitecore instance with Sitecore XM/XP version 10.2+ and Sitecore Headless Services module version 19+.
-
You have some familiarity with the Sitecore JavaScript Rendering SDKs (JSS), Next.js, and the Sitecore JavaScript Rendering SDK (JSS) for Next.js.
-
You must install the JSS CLI version 19+.
-
You must create an API key.
When following these instructions, keep in mind that you might want to support both existing MVC and static MVC pages if you are taking an incremental approach to conversion, which would require multiple Layout items or customization.
This walkthrough describes how to:
-
Adapt the MVC application for static HTML generation.
-
Include placeholders for MVC layouts in the Layout Service response.
-
Configure the Sitecore Layout Service to output HTML for MVC renderings.
-
Prepare a JSS Next.js application for rendering an MVC application.
-
Adapt the Next.js application to serve your layouts and assets from existing MVC apps
-
Start the Next.js application.
This conversion process, depending on your choices for the JSS application and your existing setup for Sitecore and the MVC application has some limitations.
Adapt the MVC application for static HTML generation
Your MVC application might require some changes to be compatible with static HTML generation using a JSS app.
To adapt the MVC application:
-
To enable editing and static generation support in the JSS app, ensure your site root inherits /sitecore/templates/Foundation/JavaScript Services/App template.
-
To enable editing support, ensure the layouts for your pages use or inherit the template /sitecore/templates/Foundation/JavaScript Services/JSS Layout . The
Path
value is not used, it must only be a valid file path. By default JSS uses/Views/JssApp.cshtml
. -
The JSS Dictionary API requires specific templates and configuration, such as the
dictionaryDomain
attribute for the<app>
configuration. You might have to adjust your MVC solution for compatibility.
Include placeholders for MVC layouts in the Layout Service response
To render your MVC layouts in a JSS application, the placeholders available for the layouts must be included in the Layout Service response.
In this walkthrough, we use REST Layout Service endpoint examples but the procedure works equally well with GraphQL and Experience Edge and you can access the data with the help of a layout query.
To inspect the Layout Service response, visit the endpoint at <cm_server>/sitecore/api/layout/render?item=/&sc_apikey=<api_key>
. You can see JSON output for the configured site start item /
.
For multisite solutions, add the sc_site
query parameter. Disable editing mode layout data with the sc_mode=normal
query parameter.
If the placeholder information is missing in the JSON data structure under sitecore > route > placeholders
, for every one of your layouts, you must configure the Layout Service Placeholders field. This field determines which placeholder information to include in the Layout Service response data.
Configure the Sitecore Layout Service to output HTML for MVC renderings
Following the configuration of the Layout Service Placeholders field for your Layouts, you obtain JSON-formatted placeholder information.
To statically render the MVC application to HTML before converting all the components to JavaScript, the component information must be converted to HTML before reaching the JSS application.
Prepare a JSS Next.js application for rendering an MVC application
To statically generate the MVC application, we recommend you use the JSS for Next.js to create a basic JSS Next.js application.
Before creating the application based on the sample Next.js application provided by JSS, consider whether you want to use GraphQL or REST services for fetching data and the pre-rendering method to use when the MVC application has been migrated to JavaScript.
We recommend GraphQL for compatibility with Experience Edge for XM.
To create a Next.js JSS application for rendering the HTML output of your MVC app:
-
In a terminal, create a Next.js application with JSS by running the following command:
RequestResponsenpx create-sitecore-jss nextjs
ImportantThe
<app-name>
must match your MVC site name, but you must be aware of app name formatting restrictions. For example,MyMvcApp
is a valid MVC site name, but the JSS initializer allows only lower-case letters. When creating the JSS application, provide a lower-case app name, for example,my-mvc-app
. When the process finishes, in thepackage.json
file, update theconfig.appName
property toMyMvcApp
. -
In the root directory of the Next.js application, review the Sitecore configuration patch file
/sitecore/config/<app-name>.config
. This configuration must be deployed to your Sitecore instance.NoteBecause you already have a matching
<site/>
configuration for your existing MVC site, you might want to merge the site configuration attributes.
Adapt the Next.js application to serve your layouts and assets from existing MVC apps
To render a Sitecore MVC application in a JSS Next.js app, you must have matching layouts and access to the resources of the MVC app - such as styles and scripts.
To adapt the Next.js application:
-
If your app requires customizations to the
html
and/orbody
elements of the page, in thesrc/pages
directory, define a customDocument component
. -
Adapt the
src/Layout.tsx
file, defining the root layout for your application, including base markup and root placeholders, to match your MVC-based layout. -
Modify the
src/pages/_app.tsx
and/orsrc/Layout.tsx
files to include your front-end assets.TipConsider migrating to the CSS solutions with built-in support in Next.js and loading external scripts using the
next/script
component.NoteThe generated app uses Bootstrap and custom CSS. For details refer to the directory
src/assets/
. -
Place the files that you want to remain untouched during the build process in the
public
directory, located in the root directory of the Next.js application. For more information, refer to the Next.js documentation on serving static files. -
Adjust your existing JavaScript code that depends on
DOMContentLoaded
or document-ready events to use something like event delegation, because those events are no longer guaranteed with client-side route changes. -
Configure rewrites for any requests that you want to be sent back to Sitecore Content Management or Content Delivery servers. The JSS application comes preconfigured with common redirects (Sitecore, media) but you must configure redirects for any customizations you might have in your MVC solution.
TipNext.js includes robust functionality for configuring rewrites to allow incremental adoption, especially for site functionality that you do not want to convert immediately to a Jamstack architecture.
-
If your MVC application does not use Sitecore Dictionaries at this time, you can temporarily remove Dictionary usage from the Next.js app. In the
src/lib/page-props-factory.ts
file, remove dictionary calls. -
If your MVC application is multilingual, you must configure internationalization in the Next.js application to match your Sitecore setup. Otherwise, remove content translation functionality from the JSS Next.js app.
-
You must refactor any C# code injecting markup directly into your Razor view to use layout data instead. For example, add dynamic
<meta/>
tags to a head placeholder.
Start the Next.js application
You can start the Next.js application in development or production mode.
To start the application and continue developing:
-
In a terminal, in the root directory of your JSS Next.js app, run the following script:
RequestResponsejss start:connected
To start the application and preview its production behavior:
-
In a terminal, in the root directory of your JSS Next.js app, run the following script:
RequestResponsejss start:production
When you have completed these procedures, you can deploy your Next.js JSS application.
You can also start the process of incrementally converting components from MVC/Razor to React/Next.js.