App Configuration API

Version: 21.x

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

Import a Sitecore JavaScript Rendering SDKs (JSS) application into Sitecore or run the JSS application in integrated mode.
Integrate the advanced Sitecore editors with applications built with the ASP.NET Rendering SDK and JSS for Next.js.

You can add configuration patches for your JSS application in your Sitecore instance by renaming and editing the \App_Config\Sitecore\JavaScriptServices\Sitecore.JavaScriptServices.ExampleApp.config.example file.

Alternatively, for JSS applications based on official templates, you can include the necessary <app /> configuration in the /sitecore/config directory of the application's source code.

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. If not running in integrated mode, the app must reference this configuration explicitly. 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 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 `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`. Important To use the Experience Editor explore mode, you must change the value to `false`,
`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,