App Configuration API

Abstract

Overview of adding Sitecore configuration patches for your JSS application.

The Headless Services App Configuration API enables developers to configure the necessary settings to:

You can add configuration patches for your JSS applications to the following files:

  • For JSS applications based on officially supported samples, include the necessary <app /> configuration in the /sitecore/config directory of the application's source code.

  • In your Sitecore instance, you can rename and edit \App_Config\Sitecore\JavaScriptServices\Sitecore.JavaScriptServices.ExampleApp.config.example.

You must add the patches in the <apps> node of the <javaScriptServices> configuration node.

App Configuration API example

A minimal configuration contains the following required attributes:

  • name

  • sitecorePath

  • inherits

For example:

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
  <sitecore>
    <javaScriptServices>
      <apps>
        <app name="exampleApp"
             sitecorePath="/sitecore/content/ExampleApp"
             inherits="defaults"
        />
      </apps>
    </javaScriptServices>
  </sitecore>
</configuration>

App Configuration API attributes

The following table lists the available App Configuration attributes and their default values.

In the file \App_Config\Sitecore\JavaScriptServices\Sitecore.JavaScriptServices.Apps.config, in the defaults configuration patch, you can inspect any default values for some of the available attributes.

Tip

The App Configuration API includes a rudimentary token-replacement system, implemented by the pipeline configuration.replaceConfigurationTokens. By default, the pipeline only supports the $name token.

To configure apps in Sitecore, you can use the following attributes:

Attribute

Usage

name

Required. The unique name of the application.

sitecorePath

Required. The path to the application's content and routes when imported. It is created during the first import.

inherits

Required. Indicates the app from which to inherit other, non-specified settings. Inheritance cascades through multiple app definitions.

filesystemPath

The file system deployment path for the JavaScript Rendering SDK application. Must match the sitecoreDistPath in package.json.

Default: /dist/$name

serverBundle

The bundled file name of the application's server.js.

Default: server.bundle

importUser

The Sitecore user account to use during the import process. Specifying the user account allows restricting the actions of the import using security and workflow.

Default: sitecore\JssImport

importLanguage

The Sitecore fallback language to use during the import if the manifest does not contain a language value.

Default: en

importDatabase

The Sitecore database to use during import.

Default: master

importDevice

The device layer where the import process creates renderings.

Default: /sitecore/layout/Devices/Default

rootPlaceholders

A comma-delimited list of the placeholder names at the root of your app layout.

Default: main

templatesPath

The path to import generated templates to. If the path does not exist, it is created during the import process, including any ancestor folders.

Default: /sitecore/templates/$name

renderingsPath

The path to import generated renderings to. If the path does not exist, it is created during the import process, including any ancestor folders.

Default: /sitecore/layout/renderings/$name

layoutPath

The path where to import the app's main layout. If the path does not exist, it is created during the import process, including any ancestor folders.

Default: /sitecore/layout/Layouts/JavaScriptServices/$name

placeholdersPath

The path to import generated placeholder settings to. If the path does not exist, it is created during the import process, including any ancestor folders.

Default: /sitecore/layout/placeholder settings/$name

appDatasourcesPath

The path to import app-level datasource items to. If the path does not exist, it is created during the import process, including any ancestor folders.

Default: /sitecore/content/$name/Components

routeDatasourcesPath

The name of the child folder to create under route items for route-level datasource items.

Default: Page Components

mediaLibraryPath

The path to import media items to. If the path does not exist, it is created during the import process, including any ancestor folders.

Default: /sitecore/media library/$name

defaultWorkflow

The default workflow to apply to the standard values of generated templates.

Default: /sitecore/system/Workflows/JSS Development Workflow

appTemplate

The template of the generated root app item. If changed, this template must inherit from the default app template.

Default: /sitecore/templates/JavaScriptServices/App

routeBaseTemplate

The template the import process must use as a base for generating the app-specific route template. If changed, this template must inherit from the default route template.

Default: /sitecore/templates/JavaScriptServices/Route

routeTemplateName

The name to use for the generated route template.

Default: $name Route

layoutTemplate

The template for creating the app's main layout item. If changed, this must inherit from the JSS JavaScript Main Layout.

Default: /sitecore/templates/JavaScriptServices/JavaScript Main Layout

folderTemplate

The template for creating generic folders (for example, for datasource items).

Default: /sitecore/templates/Common/Folder

placeholderSettingsFolderTemplate

The template for creating placeholder setting folders.

Default: /sitecore/templates/System/Layout/Placeholder Settings Folder

renderingsFolderTemplate

The template for creating renderings folders.

Default: /sitecore/templates/System/Layout/Renderings/Rendering Folder

layoutFolderTemplate

The template for creating folders for the app's main layout.

Default: /sitecore/templates/System/Layout/Layout Folder

templateFolderTemplate

The template for creating template folders.

Default: /sitecore/templates/System/Templates/Template Folder

mediaLibraryFolderTemplate

The template for creating folders in the media library.

Default: /sitecore/templates/System/Media/Media folder

protectDeveloperItems

Boolean value indicating whether developer items, such as template and layout items, must have their read-only/protected flag turned on by the import process.

Default: true

optimizeImportIndexing

Boolean value indicating whether the import must utilize a BulkUpdateContext and refresh indexes on import completion.

Default: true

datasourceStrategy

The name of the datasource import strategy to use. The setting must reference the name of an IDatasourceStrategy configured in the /javaScriptServices/datasourceStrategies config section.

Default: preferRouteLevel

analyzeAllowedControls

Boolean value indicating whether the import must attempt to populate the Allowed Controls field on placeholder settings based on rendering usage within the imported routes.

Default: true

dictionaryDomain

The name or GUID of the Sitecore Dictionary Domain used with the app. If not configured, the application dictionary will fall back to the default dictionary of the context database.

Default: (none)

layoutServiceConfiguration

The name of a named Layout Service configuration for integrated mode app rendering. If not running in integrated mode, the app must reference this configuration explicitly.

Default: jss

serverSideRenderingEngine

Instructs Sitecore which rendering engines to use when rendering the JSS app server-side.

Possible values: nodejs and http.

Default: nodejs

serverSideRenderingFunctionName

Name of the exported JS function on your serverBundle to call when rendering in integrated mode.

Only relevant when you set the value of serverSideRenderingEngine to nodejs.

Default: renderView

serverSideRenderingEngineEndpointUrl

Defines an HTTP endpoint for a remote rendering host.

Only relevant when you set the value of serverSideRenderingEngine to http.

Default: ""

serverSideRenderingEngineApplicationUrl

Defines the URL for creating absolute links for any relative links in the rendered HTML, necessary for the Experience Editor. If not specified (default), the import process extracts the hostname from the serverSideRenderingEngineApplicationUrl.

Only relevant when you set the value of serverSideRenderingEngine to http.

Default: ""

deploymentSecret

Configures the app import shared secret.

The secret must be 32+ randomly generated characters, and it must match the secret in the JSS app's scjssconfig.json to work.

Default: (none)

Notice

When using the Sitecore-first development workflow, you do not need to configure the deploymentSecret.

Danger

Do not commit this secret to source control. Use a unique secret for every environment. Possession of this secret effectively grants you the ability to create and modify Sitecore items administratively.

debugSecurity

Boolean value to enable/disable security debugging. Set to true if you have app import connection issues to log details about the server-side processing of the shared secret. Do not use unless debugging a connection issue. Use it together with --debugSecurity CLI flag to diagnose client-side security issues.

Default: false