App Configuration API

Current version: 19.x

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 official templates, 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:

RequestResponse
<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 \App_Config\Sitecore\JavaScriptServices\Sitecore.JavaScriptServices.Apps.config file, 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 configuration.replaceConfigurationTokens pipeline. 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 for importing generated templates. If the path does not exist, it is created during the import process, including any ancestor folders.

Default: /sitecore/templates/$name

renderingsPath

The path for importing generated renderings. 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 for importing the main layout of the app. 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 for importing generated placeholder settings. 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 for importing app-level datasource items. 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 for importing media items. 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 applied 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 use a BulkUpdateContext and refresh indexes on import completion.

Default: true

datasourceStrategy

The name of the datasource import strategy. 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)

dictionaryPath

The item path or GUID for the dictionary domain item of the current app. If the path does not exist, it is created during the import process, including any ancestor folders. The import service creates dictionary domains and imports dictionary entries in this location.

Default : /sitecore/content/$name/$name Dictionary

layoutServiceConfiguration

The name of a named Layout Service configuration for integrated mode app rendering.

Possible values: jss, default

Default: jss

Note

Generally, you use the jss configuration for Sitecore Layout Service REST requests and the default configuration for Experience Edge for XM GraphQ queries.

Specifying the language is required for all Edge queries. When using integrated GraphQL queries against the Edge GraphQL schema, the default configuration ensures that a $language value is injected in all queries. The jss configuration does not provide the language value, keeping it backward compatible with version 18.0.0.

graphQLEndpoint

Enables integrated GraphQL queries. If you are not using integrated GraphQL, you can remove or omit this attribute.

serverSideRenderingEngine

Instructs Sitecore on which rendering engine 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 serverSideRenderingEngineEndpointUrl.

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

Default: ""

serverSideRenderingEngineEditOnly

Controls whether Sitecore must process requests to non-API routes when using an external rendering host.

Default: true.

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)

Note

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

Important

Do not commit this secret to source control. Use a unique secret for every environment. Possessing 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

Do you have some feedback for us?

If you have suggestions for improving this article,