Set up Next.js renderer

Next.js

Overview

The following article describes how to set up Sitefinity CMS to work with a standalone Next.js application as the Renderer.

PREREQUISITES: To set up the Renderer application:

• You must have Node.js 20.9 or a higher version installed.
• You must have your Sitefinity CMS installed or upgraded to version 15.4 (latest product update).

In this mode, the standalone Next.js renderer handles the requests that it can process and serves as a proxy and forwards all other requests to Sitefinity CMS. This means that it is possible to display some pages via the Next.js rendering engine and the rest could be configured to fall back to the default Sitefinity CMS rendering. For more information, see Migrate from MVC to Next.js. This allows gradual page by page migration from the classic Sitefinity CMS pages to Next.js or having some of the pages rendered by Next.js and the rest handled by Sitefinity CMS.

You can also adopt a Cloud hosting or a mixed hosting configuration, which would require specific setup settings. For the supported hosting configurations, see Next.js hosting configurations.

Host Sitefinity CMS on IIS

If your project is hosted on a local IIS, you need to make some specific settings, so that your Sitefinity CMS can communicate with the Renderer application:

1. Download the Progress.Sitefinity.Cloud.AppGatewayHostRewriteModule NuGet package manually from NuGet.org.
2. Change the file extension from .nupkg to .zip and extract the files.
3. In the extracted folder, navigate to the Content folder.
4. Copy the HostRewriteModule.dll and paste it in a dedicated folder.

NOTE: The built-in Windows NETWORK SERVICE account must have permissions to access the folder. The file must remain in this folder for as long as the extension is used. Deleting the file or its folder can cause issues.

1. Open Internet Information Services (IIS) Manager.
2. At the top, select your server and click Modules.
3. Click Configure Native Modules » Register.
4. Set the name to AppGatewayHostRewriteModule.
5. In Path, navigate to the HostRewriteModule.dll, select it and click OK.
6. Ensure the checkbox next to AppGatewayHostRewriteModule is selected and click OK.

Create a Next.js application

To create your Next.js application, perform the following:

1. Open your terminal in the directory you want to create the application in.
2. Run the following command: npx create-next-app nextjs-sitefinity --example https://github.com/Sitefinity/nextjs-samples/tree/main/src/starter-template 
   This is the basic minimum code needed to bootstrap a standalone rendering application. Changes and updates to this would be reflected in the GitHub repository of the Next.js project.
3. In the console, type cd nextjs-sitefinity.
4. Open the env.development file and set the SF_CMS_URL variable to point to the URL of the Sitefinity CMS proxy.
5. In the console, type npm run dev.

To develop your website, you need access to the WYSIWYG editor and to the backend at the same time - to drop your widgets and configure them.

Running in development mode does not require installing additional software and works on any Node.js supported OS.

NOTE: The sample project runs under SSL by default and installs a default SSL certificate. To remove it, change the command configuration in the package.json file.

Configure Sitefinity CMS

After creating and configuring your Next.js Renderer application, you have to configure your Sitefinity CMS. Perform the following:

1. In Sitefinity CMS backend, navigate to Administration » Web services.
2. Open the Default web service.
3. Under Who can access the content by this service?, select Everyone.
4. Save your changes.

Proxy logic

To have seamless experience when using the standalone renderer application together with Sitefinity CMS, the Renderer is also working as a proxy and forwards every request it cannot handle to Sitefinity CMS. This way, the user does not have to switch between the two applications. This is done through the SF_CMS_URL environment variable. Setting this variable allows proxying any requests unhandled by the Next.js renderer to the CMS.

You host the Renderer at your public domain and your users use only this domain, without considering whether the Renderer or Sitefinity CMS handles their request.

Environment variables legend:

• (Required) SF_CMS_URL: The URL of Sitefinity CMS, used to proxy all requests that are not pages and to which all API calls will be made.
• (Required) SF_LOCAL_VALIDATION_KEY: The secret key to work with Sitefinity Cloud. Required only when working with Sitefinity Cloud for pages that are not handled by the Next.js renderer. For more information on the secret key, see Set up the project for local development (using Next.js Renderer).
• (Optional) NEXT_PUBLIC_SF_CMS_URL: The URL of the CMS for client-side calls, to which all API calls will be made. The default value is /.
• (Optional) SF_PROXY_ORIGINAL_HOST: Environment variable that controls the host header sent to the CMS. Useful for multisite testing locally.
• (Optional)SF_HOST_HEADER_NAME: Environment variable that controls the host header sent to the CMS. Useful for cloud hosting when the original host is sent via a custom header value.
• (Optional) SF_WHITELISTED_PATHS: Comma-separated URLs to pages made with the legacy frameworks (MVC / Web Forms) so that the requests can be proxied to Sitefinity for rendering. The default value is empty (not set).
• (Optional) SF_IS_HOME_PAGE_LEGACY: A flag indicating that the home page of the site is created with the legacy frameworks (MVC / Web Forms) and navigation to www.siteurl/ will proxy the request to Sitefinity. The default value is false.
• (Optional) SF_WHITELISTED_WEBSERVICES: A comma-separated list of URLs for Sitefinity web services that should be allowed through the proxy.
• (Optional) SF_WEBSERVICE_PATH: Change the web service that the Next.js renderer instance should use. Keep in mind that a custom one should be created first in Sitefinity via Administration » Web services. The service should be enabled and its access set to Everyone. The default value is api/default.
• (Optional) SF_WEBSERVICE_API_KEY: An access key for the Sitefinity web service (set it in Sitefinity via Settings » Web Services). Use it to restrict the web service so that it is accessible only from the Renderer application. If you set it in the renderer, also set it in the web service configuration.