Setup Next.js renderer

PREREQUISITES: You must have Node.js version 18 or higher installed.

NOTE: To install Sitefinity CMS using NuGet, you must use Visual Studio 2017 or later. This article uses Visual Studio 2019 as a reference.

To install Sitefinity CMS in a blank web application using a NuGet package, perform the following:

To do this, perform the following:

1. Open Visual Studio.
2. In the toolbar, click File » New Project…
   The Create a new project window appears.
3. In the All languages dropdown, select C#.
4. In the All platforms dropdown, select Windows.
5. And in the All project types dropdown, select Web.
6. From the list of projects, select ASP.NET Web Application (.NET Framework).
7. In Project name, enter a name of your project.
   For example, enter SitefinityWebApp
8. Choose a location to store your project.
9. Enter a name for the solution.
   For example, enter SitefinityWebApp
10. In Framework, select .NET Framework 4.8.
11. Click Create.
12. In the window that appears, select Empty and click Create.

In Visual Studio, perform the following:

1. In the toolbar, click Tools » NuGet Package Manager » Package Manager Settings.
2. In the left pane, expand NuGet Package Manager.
3. Select Package Sources.
4. Add a new source by clicking the plus button.
5. In Name, enter Sitefinity Nuget
6. In Source, enter https://nuget.sitefinity.com/nuget
7. Click OK.

In Visual Studio, perform the following:

1. In the toolbar, click Tools » NuGet Package Manager » Package Manager Console.
   The Package Manager Console opens.
2. In Package source, select Sitefinity Nuget.
3. In Default project, select the empty project that you have created.
4. Install the Progress.Sitefinity.Headless package by entering in the console: Install-Package Progress.Sitefinity.Headless

   NOTE: With these commands, you install the latest patch build. If you want to install a specific version, you must use the command followed by -Version and the version number.

   For example, enter Install-Package Progress.Sitefinity.Headless -Version 14.4.8100.0 

5. Wait until Sitefinity CMS is installed on your empty project.
6. Build your solution.

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 NuGet package Progress.Sitefinity.Cloud.AppGatewayHostRewriteModule.
   
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 in a dedicated folder.
   

NOTE: IIS's NETWORK SERVICE 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.

1. Open the project in Visual Studio.
2. In the Solution Explorer, open the context menu of your newly created project.
3. Click View » View in browser.
   Your project starts in a browser.
4. Install your license.
   After the project initialized in the browser, the License activation page appears.
   Perform procedure Activate a license.
5. Setup the project.
   After you activate your license, the Project Startup page appears.
   Perform procedure Setup the project.
   Sitefinity CMS Dashboard appears.

Next, you have to configure the access to the default web service endpoint in Sitefinity CMS:

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.  
   

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 
   
3. In the console, type cd nextjs-sitefinity 
   
4. 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. The development mode enables this by using the HTTP-proxy-middleware package to proxy any Sitefinity CMS related requests to Sitefinity CMS and allows the Next.js renderer to handle only the frontend rendering of the pages. 

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

1. Open the console in the application folder. 
   
2. Run npm i 
   
3. Open the .env.development file. 
   
4. Set the PROXY_URL variable to point to the URL of Sitefinity CMS. 
   
5. Depending on where your Sitefinity CMS project is hosted you might need additional configurations. For more information, see Next.js hosting configurations.
   
6. (Optional) Generate an access key and set the SF_ACCESS_KEY environment variable. For more information, see Generate access key. The access key is identified for staging or dev environments, where page editing will be done.
   
7. In the console, run npm run dev.
   

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. 

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.

NOTE: The proxy logic facilitates the migration of Sitefinity CMS pages that are created with ASP.NET MVC to the new Next.js pages, created with the renderer application.

Environment variables legend:

• (Required)'SF_CMS_URL': The URL of the CMS, where to proxy all of the requests that are not pages and to which all of the API call will be made.
  
• (Required)'SF_LOCAL_VALIDATION_KEY': The secret key to work with Sitefinity Cloud. Required only when working with Sitefinity cloud.
  
• (Optional)'NEXT_PUBLIC_SF_CMS_URL': The URL of the CMS for client-side calls, to which all of the API call will be made. Defaults to '/'.
  
• (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 (MVC/Web forms) frameworks so that the requests can be proxied to Sitefinity for them. Defaults to ''.
  
• (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. Defaults to 'false'.