Single-page application routing and hosting conventions


How to host Angular applications in a SItecore instance, and route requests

You can host an Angular CLI application within a Sitecore instance and you can use conventions for routing requests to the application.

This topic describes:

An Angular-CLI application normally contains a set of related files:

  • The application entry point file (index.html). This file references the JavaScript files the application uses.

  • A set of compiled and bundled JavaScript files, including main.bundle.js, inline.js, and styles.bundle.js. The set of JavaScript files varies depending on the compilation engine. The JavaScript files contain the application logic.

By default, Angular-CLI applications run in the root of the server. However, you cannot run Angular applications this way in Sitecore, so you must change the root path for your application.

Normally, an Angular-CLI application contains inner routing, resolved by the Angular client side. Users access any given page through the combination of the virtual path to the entry point of the application (index.html) and the inner client side route, configured inside the application.

Consider this scenario:

  • The application is hosted under: [your instance]\website\sitecore\shell\client\Applications\MyAwesomeApp\

  • When a user accesses this URL, the web server automatically retrieves the application files and returns them to the browser. The browser displays the index.html file.

  • The application routing is configured to show the dashboard page by retrieving the /dashboard route.

  • When a user accesses the dashboard page from within the application, the browser displays this URL: http://[your instance]/sitecore/shell/client/Applications/MyAwesomApplication/dashboard, but the browser just automatically displays the appropriate file already retrieved from the server.

  • If, however, the user enters the dashboard URL into the browser manually, the server does not find the file and it returns error 404 (File Not Found). This happens because the dashboard route does not correspond directly to a file on the server with that path.

To solve this problem, you use routing conventions.

When you use routing and hosting conventions, you define a folder for each application. You set up Sitecore so that the server responds appropriately to requests for client-side routes.

The conventions are:

  • Each application must have a unique application name ([AppName]).

  • You define an application host folder for each application in the file system: /sitecore/shell/client/Applications/[AppName].

  • You use the ng-sc module's build task to generate the Sitecore entry-point based on the Angular entry-point. As a result of this task, you will have an index.aspx page instead of an index.html. You must do this to make your application Sitecore authentication compliant andenable Anti-CSRF protection for your application.

You use the ng-sc cli tool to change the index.html file to index.aspx. You can use the tool as a post-build step for Angular projects. When the tool renames to .aspx, it also adds one line of code at the top of the file. This code enables SPEAK 3 features when the application runs inside Sitecore. These features include Anti-CSRF tokens, entry-point user authentication, and so on.

You use ng-sc --entry ./dist/index.html with the following parameters:



Default value

--entry, -e

The name of the file to create an aspx file from (the input file). In a standard Angular-CLI setup, this is ./dist/index.html.

This argument is required and there is no default value.

--out, -o

The name of the output file, relative to the input file.

The default value is index.aspx.

--keep, -k

A Boolean value. If set (true), the tool does not remove the input file

Removes the entry file by default because we do not recommend that you ship your entry .html file with the Sitecore application.

The Sitecore.Speak.Integration module handles requests in the following way:

  • The module reads the config file.

  • The module extends the preprocessRequest pipeline so it listens to all requests.

  • When the module detects that a URL request corresponds to one of the application folders, it rewrites the URL to redirect the request to the index.aspx file of the correct application.

By default, the ng-sc cli tool creates an ASP.NET Web Forms page that inherits the Sitecore.Speak.Integration.Spa.SecureSpaPage class.

After redirecting to the index.aspx file, the Sitecore integration sets up backend logic in the following way:

  • It sets the Anti-CSRF cookies.

  • It tries to find the corresponding application Sitecore item.

  • It checks if the current user is allowed to access this item. If there is no item, it does not check access permissions.

  • It reads the EntryPoint field of this item (by default index.aspx). If there is no application item, it uses index.aspx as the entry point.

  • It tries to find the application folder following the convention.

  • If the EntryPoint file exists in the application folder, the URL is rewritten to point to this file.

There is also an Sitecore.Speak.Integration.Spa.SpaPage class. This class does not do the ShellPage.IsLoggedIn() check. If you do not need Sitecore authentication in your application, you can use this class for your application entry point.

You can switch the context language in Sitecore in the sc_lang=language query string parameter. SPEAK 3 does not support this feature for applications that use the entry point solution.