The Sitecore configuration file

Content SDK includes the sitecore.config.ts file, which is the central configuration point for your app, found in the app's root folder.

Apps built using a Content SDK starter template include a lightweight version of the config file containing mandatory parameters only. You can expand the file to add further configuration as needed.

To access any value from the configuration file, you can import it into your code as shown in the following example:

RequestResponse

import scConfig from 'sitecore.config'

Several of the properties described in this topic have a corresponding environment variable; where they do, that variable is listed here alongside the property's description. If a property is not given an explicit value, it will take the value from the corresponding environment variable where available. If a value is not defined in either place, the property will use a default value instead.

The base configuration

Property	Type	Description	Corresponding environment variable
`api`	object	Connection credentials required to connect to your SitecoreAI instance.	n/a
`defaultSite`	string	The name of your default site. Behaves differently depending on whether you have the multisite feature enabled: If multisite is enabled, this defines the fallback site. If multisite is not enabled, this defines the site loaded for your visitors. default: `''`	`NEXT_PUBLIC_DEFAULT_SITE_NAME`
`defaultLanguage`	string	optional The default locale for your site, used as a fallback (for functionality such as API requests, site resolution, middleware, and so on) when a language is not otherwise provided. You must ensure this aligns with framework-specific settings (such as Next.js i18n) throughout your application. default: `'en'`	`NEXT_PUBLIC_DEFAULT_LANGUAGE`
`editingSecret`	string	optional Editing secret required by SitecoreAI editing and preview functionality. Provide this if you want to use your local or deployed application as an editing host. default: `'editing-secret-missing'`	`SITECORE_EDITING_SECRET`

api properties

Provide exactly one of the following, depending on whether you are connecting to a SaaS instance of SitecoreAI or a local instance running in Docker.

Property	Type	Description	Corresponding environment variable
`edge`	object	optional Edge endpoint credentials used to connect to a SaaS instance of SitecoreAI.	n/a
`local`	object	optional API endpoint credentials used to connect to a local instance of SitecoreAI running in a Docker container.	n/a

Property

Type

Description

Corresponding environment variable

edge

object

optional

Edge endpoint credentials used to connect to a SaaS instance of SitecoreAI.

n/a

local

object

optional

API endpoint credentials used to connect to a local instance of SitecoreAI running in a Docker container.

n/a

edge properties

Property	Type	Description	Corresponding environment variable
`contextId`	string	The unique identifier used to connect to and retrieve data from your SitecoreAI instance. default: `''`	`SITECORE_EDGE_CONTEXT_ID` (on the server) `NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID` (on the client. Also used on the server if `SITECORE_EDGE_CONTEXT_ID` is not defined)
`clientContextId`	string	optional Identifier used to connect to and retrieve data from your SitecoreAI instance in client-side operations. default: `''`	`NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID`
`edgeUrl`	string	optional URL of the SitecoreAI endpoint that your Content SDK app will communicate with. default: `https://edge-platform.sitecorecloud.io`	`NEXT_PUBLIC_SITECORE_EDGE_URL`

Property

Type

Description

Corresponding environment variable

contextId

string

The unique identifier used to connect to and retrieve data from your SitecoreAI instance.

default: ''

SITECORE_EDGE_CONTEXT_ID (on the server)

NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID (on the client. Also used on the server if SITECORE_EDGE_CONTEXT_ID is not defined)

clientContextId

string

optional

Identifier used to connect to and retrieve data from your SitecoreAI instance in client-side operations.

default: ''

NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID

edgeUrl

string

optional

URL of the SitecoreAI endpoint that your Content SDK app will communicate with.

default: https://edge-platform.sitecorecloud.io

NEXT_PUBLIC_SITECORE_EDGE_URL

local properties

Property	Type	Description	Corresponding environment variable
`apiKey`	string	Your Sitecore API key used to connect to the GraphQL endpoint. default: `''`	`NEXT_PUBLIC_SITECORE_API_KEY`
`apiHost`	string	Sitecore API hostname that your app will connect to and retrieve data from. default: `''`	`NEXT_PUBLIC_SITECORE_API_HOST`
`path`	string	optional A GraphQL endpoint path that will be appended to `apiHost` to form a full endpoint URL, like `apiHost/path`. default: `/sitecore/api/graph/edge`	n/a

Property

Type

Description

Corresponding environment variable

apiKey

string

Your Sitecore API key used to connect to the GraphQL endpoint.

default: ''

NEXT_PUBLIC_SITECORE_API_KEY

apiHost

string

Sitecore API hostname that your app will connect to and retrieve data from.

default: ''

NEXT_PUBLIC_SITECORE_API_HOST

path

string

optional

A GraphQL endpoint path that will be appended to apiHost to form a full endpoint URL, like apiHost/path.

default: /sitecore/api/graph/edge

n/a

Services configuration

These settings provide additional configuration for various Content SDK services.

Property	Type	Description	Corresponding environment variable
`layout`	object	Extra settings for the layout service.	n/a
`dictionary`	object	Extra settings for the dictionary service.	n/a
`retries`	object	Retry configuration that affects the layout, dictionary, and `ErrorPages` services by default. It is enabled by default and is designed to keep the app stable at times when the connection to Sitecore Edge is not.	n/a

layout properties

Property	Type	Description	Corresponding environment variable
`formatLayoutQuery`	function	optional Accepts `siteName`, `itemPath`, and `locale`. Returns the first part of the GraphQL query for the layout service. default: the function returns a string in the following format: RequestResponse `layout(site:"${siteName}", routePath:"${itemPath}", language:"${language}")`	n/a

Property

Type

Description

Corresponding environment variable

formatLayoutQuery

function

optional

Accepts siteName, itemPath, and locale. Returns the first part of the GraphQL query for the layout service.

default: the function returns a string in the following format:

RequestResponse

layout(site:"${siteName}", routePath:"${itemPath}", language:"${language}")

n/a

dictionary properties

Property	Type	Description	Corresponding environment variable
`caching`	object	optional Configuration for local memory caching of dictionary service requests.	n/a

Property

Type

Description

Corresponding environment variable

caching

object

optional

Configuration for local memory caching of dictionary service requests.

n/a

caching properties

Property	Type	Description	Corresponding environment variable
`enabled`	boolean	optional Whether local memory caching is used for the dictionary service. default: `true`	n/a
`timeout`	number	optional The length of time, in seconds, to keep cached entries in local memory. default: `60`	n/a

Property

Type

Description

Corresponding environment variable

enabled

boolean

optional

Whether local memory caching is used for the dictionary service.

default: true

n/a

timeout

number

optional

The length of time, in seconds, to keep cached entries in local memory.

default: 60

n/a

retries properties

Property	Type	Description	Corresponding environment variable
`count`	number	optional The maximum number of retries attempted by the GraphQL client if the first one fails. Set this to `0` if you don't want to use retries. default: `3`	n/a
`retryStrategy`	`RetryStrategy`	optional Retry strategy implementation for the GraphQL client, imported from `@sitecore-content-sdk/nextjs/client`. default: `DefaultRetryStrategy`, which uses an exponential back-off factor of 2 for response codes 429, 502, 503, 504, 520, 521, 522, 523, and 524.	n/a

Property

Type

Description

Corresponding environment variable

count

number

optional

The maximum number of retries attempted by the GraphQL client if the first one fails. Set this to 0 if you don't want to use retries.

default: 3

n/a

retryStrategy

RetryStrategy

optional

Retry strategy implementation for the GraphQL client, imported from @sitecore-content-sdk/nextjs/client.

default: DefaultRetryStrategy, which uses an exponential back-off factor of 2 for response codes 429, 502, 503, 504, 520, 521, 522, 523, and 524.

n/a

Extra middleware and other configurations

These settings configure functionality that is provided by middleware in Next.js, but might be implemented differently in other framework implementations.

redirects

Property	Type	Description	Corresponding environment variable
`enabled`	boolean	optional Whether the redirects feature is enabled globally. default: `true` (in production), `false` (in development).	n/a
`locales`	string[]	optional List of locales that the redirect strategy can work with. The names of these locales must match the framework-specific configuration of your app (for example, `next.config` for Next.js apps). default: `['en']`	n/a

Property

Type

Description

Corresponding environment variable

enabled

boolean

optional

Whether the redirects feature is enabled globally.

default: true (in production), false (in development).

n/a

locales

string[]

optional

List of locales that the redirect strategy can work with. The names of these locales must match the framework-specific configuration of your app (for example, next.config for Next.js apps).

default: ['en']

n/a

Important

SitecoreAI does not support redirect items. You can only create and use redirect maps.

multisite

Property	Type	Description	Corresponding environment variable
`enabled`	boolean	optional Whether the multisite feature is enabled for normal site rendering mode. Multisite is always on for preview mode to ensure all data can be previewed. default: `true`	n/a
`useCookieResolution`	function	optional Whether the app accepts a `req: RequestInit` parameter to conditionally enable site resolution from a `sc_site` cookie. default: `true` in a Vercel preview environment, otherwise `false`.	n/a

Property

Type

Description

Corresponding environment variable

enabled

boolean

optional

Whether the multisite feature is enabled for normal site rendering mode.

Multisite is always on for preview mode to ensure all data can be previewed.

default: true

n/a

useCookieResolution

function

optional

Whether the app accepts a req: RequestInit parameter to conditionally enable site resolution from a sc_site cookie.

default: true in a Vercel preview environment, otherwise false.

n/a

personalize

Property	Type	Description	Corresponding environment variable
`enabled`	boolean	optional Whether the personalize feature is enabled. default: `true` (in production), `false` (in development).	n/a
`edgeTimeout`	number	optional The timeout duration, in seconds, for personalization requests to Experience Edge. default: `400`	`PERSONALIZE_MIDDLEWARE_EDGE_TIMEOUT`
`cdpTimeout`	number	optional The timeout duration, in seconds, for personalization requests to Sitecore CDP. default: `400`	`PERSONALIZE_MIDDLEWARE_CDP_TIMEOUT`
`scope`	string	optional The Sitecore Personalize scope identifier, which allows you to isolate your personalization data between SitecoreAI environments. default: `''`	`NEXT_PUBLIC_PERSONALIZE_SCOPE`
`channel`	string	optional The CDP channel to use for events. default: `WEB`	n/a
`currency`	string	optional The currency type to use for CDP requests. default: `USD`	n/a

other properties

Property	Type	Description	Corresponding environment variable
`generateStaticPaths`	boolean	optional In a Next.js app, whether the `getStaticPaths` SSG function pre-renders any pages. If set to `false`, static path generation is disabled and incremental static regeneration (ISR) is used for all pages. If the application is deployed as a SitecoreAI editing host, set this property to `false`. default: `true`	`GENERATE_STATIC_PATHS`
`disableCodeGeneration`	boolean	optional If your application doesn't use AI component generation or you want to opt out of code extraction, set this property to `true`. When set to `true`, component code extraction is skipped entirely.	n/a
`sitecoreInternalEditingHostUrl`	string	optional The internal editing host url used to render the page in editing scenarios in Next.js apps. This may be required only in non-standard local deployment setups. Available in Content SDK 1.1 and higher. default: For SitecoreAI deployments: `http://localhost:3000` For all other cases, it uses the request Host header of the incoming request.	`SITECORE_INTERNAL_EDITING_HOST_URL`

Property

Type

Description

Corresponding environment variable

generateStaticPaths

boolean

optional

In a Next.js app, whether the getStaticPaths SSG function pre-renders any pages. If set to false, static path generation is disabled and incremental static regeneration (ISR) is used for all pages.

If the application is deployed as a SitecoreAI editing host, set this property to false.

default: true

GENERATE_STATIC_PATHS

disableCodeGeneration

boolean

optional

If your application doesn't use AI component generation or you want to opt out of code extraction, set this property to true.

When set to true, component code extraction is skipped entirely.

n/a

sitecoreInternalEditingHostUrl

string

optional

The internal editing host url used to render the page in editing scenarios in Next.js apps. This may be required only in non-standard local deployment setups. Available in Content SDK 1.1 and higher.

default:

For SitecoreAI deployments: http://localhost:3000

For all other cases, it uses the request Host header of the incoming request.

SITECORE_INTERNAL_EDITING_HOST_URL

Do you have some feedback for us?

If you have suggestions for improving this article,