---
title: "The Sitecore configuration file"
slug: "the-sitecore-configuration-file"
abstract: "Content SDK apps include a standard config file with various mandatory properties that you can modify as needed. You can also add optional properties to control aspects of your app's behaviour, including how it interacts with services and middleware."
---
# 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:

```ts
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

<table style="width:100%;" class="informaltable frame-void rules-rows"><thead><tr><th class="th"><p>Property</p></th><th class="th"><p>Type</p></th><th class="th"><p>Description</p></th><th class="th"><p>Corresponding environment variable</p></th></tr></thead><tbody><tr><td class="td"><p><code class="code">api</code></p></td><td class="td"><p><a class="link" href="https://doc.sitecore.com/sai/en/developers/content-sdk/20/the-sitecore-configuration-file.html#UUID-62ef3d45-c0f5-0949-be7b-f28b9d388be3_section-idm234863164682385" title="api properties">object</a></p></td><td class="td"><p>Connection credentials required to connect to your SitecoreAI instance.</p></td><td class="td"><p><span class="emphasis"><em>n/a</em></span></p></td></tr><tr><td class="td"><p><code class="code">defaultSite</code></p></td><td class="td"><p>string</p></td><td class="td"><p>The name of your default site. Behaves differently depending on whether you have the multisite feature enabled:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>If multisite is enabled, this defines the fallback site.</p></li><li class="listitem"><p>If multisite is not enabled, this defines the site loaded for your visitors.</p></li></ul></div><p>default: <code class="code">''</code></p></td><td class="td"><p><code class="code">NEXT_PUBLIC_DEFAULT_SITE_NAME</code></p></td></tr><tr><td class="td"><p><code class="code">defaultLanguage</code></p></td><td class="td"><p>string</p></td><td class="td"><p><span class="emphasis"><em>optional</em></span></p><p>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.</p><p>You must ensure this aligns with framework-specific settings (such as Next.js i18n) throughout your application.</p><p>default: <code class="code">'en'</code></p></td><td class="td"><p><code class="code">NEXT_PUBLIC_DEFAULT_LANGUAGE</code></p></td></tr><tr><td class="td"><p><code class="code">editingSecret</code></p></td><td class="td"><p>string</p></td><td class="td"><p><span class="emphasis"><em>optional</em></span></p><p>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.</p><p>default: <code class="code">'editing-secret-missing'</code></p></td><td class="td"><p><code class="code">SITECORE_EDITING_SECRET</code></p></td></tr></tbody></table>

### 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.

<table style="width:100%;" class="informaltable frame-void rules-rows"><thead><tr><th class="th"><p>Property</p></th><th class="th"><p>Type</p></th><th class="th"><p>Description</p></th><th class="th"><p>Corresponding environment variable</p></th></tr></thead><tbody><tr><td class="td"><p><code class="code">edge</code></p></td><td class="td"><p><a class="link" href="https://doc.sitecore.com/sai/en/developers/content-sdk/20/the-sitecore-configuration-file.html#UUID-62ef3d45-c0f5-0949-be7b-f28b9d388be3_section-idm234863194092122" title="edge properties">object</a></p></td><td class="td"><p><span class="emphasis"><em>optional</em></span></p><p>Edge endpoint credentials used to connect to a SaaS instance of SitecoreAI.</p></td><td class="td"><p><span class="emphasis"><em>n/a</em></span></p></td></tr><tr><td class="td"><p><code class="code">local</code></p></td><td class="td"><p><a class="link" href="https://doc.sitecore.com/sai/en/developers/content-sdk/20/the-sitecore-configuration-file.html#UUID-62ef3d45-c0f5-0949-be7b-f28b9d388be3_section-idm1853486323773808" title="local properties">object</a></p></td><td class="td"><p><span class="emphasis"><em>optional</em></span></p><p>API endpoint credentials used to connect to a local instance of SitecoreAI running in a Docker container.</p></td><td class="td"><p><span class="emphasis"><em>n/a</em></span></p></td></tr></tbody></table>

### edge properties

<table style="width:100%;" class="informaltable frame-void rules-rows"><thead><tr><th class="th"><p>Property</p></th><th class="th"><p>Type</p></th><th class="th"><p>Description</p></th><th class="th"><p>Corresponding environment variable</p></th></tr></thead><tbody><tr><td class="td"><p><code class="code">contextId</code></p></td><td class="td"><p>string</p></td><td class="td"><p>The unique identifier used to connect to and retrieve data from your SitecoreAI instance.</p><p>default: <code class="code">''</code></p></td><td class="td"><p><code class="code">SITECORE_EDGE_CONTEXT_ID</code> (on the server)</p><p><code class="code">NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID</code> (on the client. Also used on the server if <code class="code">SITECORE_EDGE_CONTEXT_ID</code> is not defined)</p></td></tr><tr><td class="td"><p><code class="code">clientContextId</code></p></td><td class="td"><p>string</p></td><td class="td"><p><span class="emphasis"><em>optional</em></span></p><p>Identifier used to connect to and retrieve data from your SitecoreAI instance in client-side operations.</p><p>default: <code class="code">''</code></p></td><td class="td"><p><code class="code">NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID</code></p></td></tr><tr><td class="td"><p><code class="code">edgeUrl</code></p></td><td class="td"><p>string</p></td><td class="td"><p><span class="emphasis"><em>optional</em></span></p><p>URL of the SitecoreAI endpoint that your Content SDK app will communicate with.</p><p>default: <code class="code">https://edge-platform.sitecorecloud.io</code></p></td><td class="td"><p><code class="code">NEXT_PUBLIC_SITECORE_EDGE_URL</code></p></td></tr></tbody></table>

### local properties

<table style="width:100%;" class="informaltable frame-void rules-rows"><thead><tr><th class="th"><p>Property</p></th><th class="th"><p>Type</p></th><th class="th"><p>Description</p></th><th class="th"><p>Corresponding environment variable</p></th></tr></thead><tbody><tr><td class="td"><p><code class="code">apiKey</code></p></td><td class="td"><p>string</p></td><td class="td"><p>Your Sitecore API key used to connect to the GraphQL endpoint.</p><p>default: <code class="code">''</code></p></td><td class="td"><p><code class="code">NEXT_PUBLIC_SITECORE_API_KEY</code></p></td></tr><tr><td class="td"><p><code class="code">apiHost</code></p></td><td class="td"><p>string</p></td><td class="td"><p>Sitecore API hostname that your app will connect to and retrieve data from.</p><p>default: <code class="code">''</code></p></td><td class="td"><p><code class="code">NEXT_PUBLIC_SITECORE_API_HOST</code></p></td></tr><tr><td class="td"><p><code class="code">path</code></p></td><td class="td"><p>string</p></td><td class="td"><p><span class="emphasis"><em>optional</em></span></p><p>A GraphQL endpoint path that will be appended to <code class="code">apiHost</code> to form a full endpoint URL, like <code class="code"><span class="code-placeholder">apiHost</span>/<span class="code-placeholder">path</span></code>.</p><p>default: <code class="code">/sitecore/api/graph/edge</code></p></td><td class="td"><p><span class="emphasis"><em>n/a</em></span></p></td></tr></tbody></table>

## Services configuration

These settings provide additional configuration for various Content SDK services.

<table style="width:100%;" class="informaltable frame-void rules-rows"><thead><tr><th class="th"><p>Property</p></th><th class="th"><p>Type</p></th><th class="th"><p>Description</p></th><th class="th"><p>Corresponding environment variable</p></th></tr></thead><tbody><tr><td class="td"><p><code class="code">layout</code></p></td><td class="td"><p><a class="link" href="https://doc.sitecore.com/sai/en/developers/content-sdk/20/the-sitecore-configuration-file.html#UUID-62ef3d45-c0f5-0949-be7b-f28b9d388be3_section-idm1853486327855194" title="layout properties">object</a></p></td><td class="td"><p>Extra settings for the layout service.</p></td><td class="td"><p><span class="emphasis"><em>n/a</em></span></p></td></tr><tr><td class="td"><p><code class="code">dictionary</code></p></td><td class="td"><p><a class="link" href="https://doc.sitecore.com/sai/en/developers/content-sdk/20/the-sitecore-configuration-file.html#UUID-62ef3d45-c0f5-0949-be7b-f28b9d388be3_section-idm1853486327900838" title="dictionary properties">object</a></p></td><td class="td"><p>Extra settings for the dictionary service.</p></td><td class="td"><p><span class="emphasis"><em>n/a</em></span></p></td></tr><tr><td class="td"><p><code class="code">retries</code></p></td><td class="td"><p><a class="link" href="https://doc.sitecore.com/sai/en/developers/content-sdk/20/the-sitecore-configuration-file.html#UUID-62ef3d45-c0f5-0949-be7b-f28b9d388be3_section-idm1853486327910930" title="retries properties">object</a></p></td><td class="td"><p>Retry configuration that affects the layout, dictionary, and <code class="code">ErrorPages</code> 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.</p></td><td class="td"><p><span class="emphasis"><em>n/a</em></span></p></td></tr></tbody></table>

### layout properties

<table style="width:100%;" class="informaltable frame-void rules-rows"><thead><tr><th class="th"><p>Property</p></th><th class="th"><p>Type</p></th><th class="th"><p>Description</p></th><th class="th"><p>Corresponding environment variable</p></th></tr></thead><tbody><tr><td class="td"><p><code class="code">formatLayoutQuery</code></p></td><td class="td"><p>function</p></td><td class="td"><p><span class="emphasis"><em>optional</em></span></p><p>Accepts <code class="code">siteName</code>, <code class="code">itemPath</code>, and <code class="code">locale</code>. Returns the first part of the GraphQL query for the layout service.</p><p>default: the function returns a string in the following format:</p><pre class="programlisting json" data-language="json" id="UUID-62ef3d45-c0f5-0949-be7b-f28b9d388be3_programlisting-idm234863288654158"><code class="language-json" data-language="json">layout(site:"${siteName}", routePath:"${itemPath}", language:"${language}")</code></pre></td><td class="td"><p><span class="emphasis"><em>n/a</em></span></p></td></tr></tbody></table>

### dictionary properties

<table style="width:100%;" class="informaltable frame-void rules-rows"><thead><tr><th class="th"><p>Property</p></th><th class="th"><p>Type</p></th><th class="th"><p>Description</p></th><th class="th"><p>Corresponding environment variable</p></th></tr></thead><tbody><tr><td class="td"><p><code class="code">caching</code></p></td><td class="td"><p><a class="link" href="https://doc.sitecore.com/sai/en/developers/content-sdk/20/the-sitecore-configuration-file.html#UUID-62ef3d45-c0f5-0949-be7b-f28b9d388be3_section-idm1853486329447260" title="caching properties">object</a></p></td><td class="td"><p><span class="emphasis"><em>optional</em></span></p><p>Configuration for local memory caching of dictionary service requests.</p></td><td class="td"><p><span class="emphasis"><em>n/a</em></span></p></td></tr></tbody></table>

### caching properties

<table style="width:100%;" class="informaltable frame-void rules-rows"><thead><tr><th class="th"><p>Property</p></th><th class="th"><p>Type</p></th><th class="th"><p>Description</p></th><th class="th"><p>Corresponding environment variable</p></th></tr></thead><tbody><tr><td class="td"><p><code class="code">enabled</code></p></td><td class="td"><p>boolean</p></td><td class="td"><p><span class="emphasis"><em>optional</em></span></p><p>Whether local memory caching is used for the dictionary service.</p><p>default: <code class="code">true</code></p></td><td class="td"><p><span class="emphasis"><em>n/a</em></span></p></td></tr><tr><td class="td"><p><code class="code">timeout</code></p></td><td class="td"><p>number</p></td><td class="td"><p><span class="emphasis"><em>optional</em></span></p><p>The length of time, in seconds, to keep cached entries in local memory.</p><p>default: <code class="code">60</code></p></td><td class="td"><p><span class="emphasis"><em>n/a</em></span></p></td></tr></tbody></table>

### retries properties

<table style="width:100%;" class="informaltable frame-void rules-rows"><thead><tr><th class="th"><p>Property</p></th><th class="th"><p>Type</p></th><th class="th"><p>Description</p></th><th class="th"><p>Corresponding environment variable</p></th></tr></thead><tbody><tr><td class="td"><p><code class="code">count</code></p></td><td class="td"><p>number</p></td><td class="td"><p><span class="emphasis"><em>optional</em></span></p><p>The maximum number of retries attempted by the GraphQL client if the first one fails. Set this to <code class="code">0</code> if you don't want to use retries.</p><p>default: <code class="code">3</code></p></td><td class="td"><p><span class="emphasis"><em>n/a</em></span></p></td></tr><tr><td class="td"><p><code class="code">retryStrategy</code></p></td><td class="td"><p><code class="code">RetryStrategy</code></p></td><td class="td"><p><span class="emphasis"><em>optional</em></span></p><p>Retry strategy implementation for the GraphQL client, imported from <code class="code">@sitecore-content-sdk/nextjs/client</code>.</p><p>default: <code class="code">DefaultRetryStrategy</code>, which uses an exponential back-off factor of 2 for response codes 429, 502, 503, 504, 520, 521, 522, 523, and 524.</p></td><td class="td"><p><span class="emphasis"><em>n/a</em></span></p></td></tr></tbody></table>

## 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

<table style="width:100%;" class="informaltable frame-void rules-rows"><thead><tr><th class="th"><p>Property</p></th><th class="th"><p>Type</p></th><th class="th"><p>Description</p></th><th class="th"><p>Corresponding environment variable</p></th></tr></thead><tbody><tr><td class="td"><p><code class="code">enabled</code></p></td><td class="td"><p>boolean</p></td><td class="td"><p><span class="emphasis"><em>optional</em></span></p><p>Whether the redirects feature is enabled globally.</p><p>default: <code class="code">true</code> (in production), <code class="code">false</code> (in development).</p></td><td class="td"><p><span class="emphasis"><em>n/a</em></span></p></td></tr><tr><td class="td"><p><code class="code">locales</code></p></td><td class="td"><p>string[]</p></td><td class="td"><p><span class="emphasis"><em>optional</em></span></p><p>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, <code class="code">next.config</code> for Next.js apps).</p><p>default: <code class="code">['en']</code></p></td><td class="td"><p><span class="emphasis"><em>n/a</em></span></p></td></tr></tbody></table>

> [!important]
> SitecoreAI does not support redirect items. You can only create and use redirect maps.

### multisite

<table style="width:100%;" class="informaltable frame-void rules-rows"><thead><tr><th class="th"><p>Property</p></th><th class="th"><p>Type</p></th><th class="th"><p>Description</p></th><th class="th"><p>Corresponding environment variable</p></th></tr></thead><tbody><tr><td class="td"><p><code class="code">enabled</code></p></td><td class="td"><p>boolean</p></td><td class="td"><p><span class="emphasis"><em>optional</em></span></p><p>Whether the multisite feature is enabled for normal site rendering mode.</p><p>Multisite is always on for preview mode to ensure all data can be previewed.</p><p>default: <code class="code">true</code></p></td><td class="td"><p><span class="emphasis"><em>n/a</em></span></p></td></tr><tr><td class="td"><p><code class="code">useCookieResolution</code></p></td><td class="td"><p>function</p></td><td class="td"><p><span class="emphasis"><em>optional</em></span></p><p>Whether the app accepts a <code class="code">req: RequestInit</code> parameter to conditionally enable site resolution from a <code class="code">sc_site</code> cookie.</p><p>default: <code class="code">true</code> in a Vercel preview environment, otherwise <code class="code">false</code>.</p></td><td class="td"><p><span class="emphasis"><em>n/a</em></span></p></td></tr></tbody></table>

### personalize

<table style="width:100%;" class="informaltable frame-void rules-rows"><thead><tr><th class="th"><p>Property</p></th><th class="th"><p>Type</p></th><th class="th"><p>Description</p></th><th class="th"><p>Corresponding environment variable</p></th></tr></thead><tbody><tr><td class="td"><p><code class="code">enabled</code></p></td><td class="td"><p>boolean</p></td><td class="td"><p><span class="emphasis"><em>optional</em></span></p><p>Whether the personalize feature is enabled.</p><p>default: <code class="code">true</code> (in production), <code class="code">false</code> (in development).</p></td><td class="td"><p><span class="emphasis"><em>n/a</em></span></p></td></tr><tr><td class="td"><p><code class="code">edgeTimeout</code></p></td><td class="td"><p>number</p></td><td class="td"><p><span class="emphasis"><em>optional</em></span></p><p>The timeout duration, in seconds, for personalization requests to Experience Edge.</p><p>default: <code class="code">400</code></p></td><td class="td"><p><code class="code">PERSONALIZE_MIDDLEWARE_EDGE_TIMEOUT</code></p></td></tr><tr><td class="td"><p><code class="code">cdpTimeout</code></p></td><td class="td"><p>number</p></td><td class="td"><p><span class="emphasis"><em>optional</em></span></p><p>The timeout duration, in seconds, for personalization requests to Sitecore CDP.</p><p>default: <code class="code">400</code></p></td><td class="td"><p><code class="code">PERSONALIZE_MIDDLEWARE_CDP_TIMEOUT</code></p></td></tr><tr><td class="td"><p><code class="code">scope</code></p></td><td class="td"><p>string</p></td><td class="td"><p><span class="emphasis"><em>optional</em></span></p><p>The Sitecore Personalize scope identifier, which allows you to isolate your personalization data between SitecoreAI environments.</p><p>default: <code class="code">''</code></p></td><td class="td"><p><code class="code">NEXT_PUBLIC_PERSONALIZE_SCOPE</code></p></td></tr><tr><td class="td"><p><code class="code">channel</code></p></td><td class="td"><p>string</p></td><td class="td"><p><span class="emphasis"><em>optional</em></span></p><p>The CDP channel to use for events.</p><p>default: <code class="code">WEB</code></p></td><td class="td"><p><span class="emphasis"><em>n/a</em></span></p></td></tr><tr><td class="td"><p><code class="code">currency</code></p></td><td class="td"><p>string</p></td><td class="td"><p><span class="emphasis"><em>optional</em></span></p><p>The currency type to use for CDP requests.</p><p>default: <code class="code">USD</code></p></td><td class="td"><p><span class="emphasis"><em>n/a</em></span></p></td></tr></tbody></table>

### other properties

<table style="width:100%;" class="informaltable frame-void rules-rows"><thead><tr><th class="th"><p>Property</p></th><th class="th"><p>Type</p></th><th class="th"><p>Description</p></th><th class="th"><p>Corresponding environment variable</p></th></tr></thead><tbody><tr><td class="td"><p><code class="code">generateStaticPaths</code></p></td><td class="td"><p>boolean</p></td><td class="td"><p><span class="emphasis"><em>optional</em></span></p><p>In a Next.js app, whether the <code class="code">getStaticPaths</code> SSG function pre-renders any pages. If set to <code class="code">false</code>, static path generation is disabled and incremental static regeneration (ISR) is used for all pages.</p><p>If the application is deployed as a SitecoreAI editing host, set this property to <code class="code">false</code>.</p><p>default: <code class="code">true</code></p></td><td class="td"><p><code class="code">GENERATE_STATIC_PATHS</code></p></td></tr><tr><td class="td"><p><code class="code">disableCodeGeneration</code></p></td><td class="td"><p>boolean</p></td><td class="td"><p><span class="emphasis"><em>optional</em></span></p><p>If your application doesn't use AI component generation or you want to opt out of code extraction, set this property to <code class="code">true</code>.</p><p>When set to <code class="code">true</code>, component code extraction is skipped entirely.</p></td><td class="td"><p><span class="emphasis"><em>n/a</em></span></p></td></tr><tr><td class="td"><p><code class="code">sitecoreInternalEditingHostUrl</code></p></td><td class="td"><p>string</p></td><td class="td"><p><span class="emphasis"><em>optional</em></span></p><p>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.</p><p>default:</p><p>For SitecoreAI deployments: <code class="code">http://localhost:3000</code></p><p>For all other cases, it uses the request Host header of the incoming request.</p></td><td class="td"><p><code class="code">SITECORE_INTERNAL_EDITING_HOST_URL</code></p></td></tr><tr><td class="td"><p><code class="code">rewriteMediaUrls</code></p></td><td class="td"><p>boolean or function</p></td><td class="td"><p><span class="emphasis"><em>optional</em></span></p><p>Whether media URLs pointing to the production Experience Edge host are rewritten.</p><p>Setting it to <code class="code">true</code> rewrites media URLs using the custom host defined in <code class="code">SITECORE_EXPERIENCE_EDGE_HOSTNAME</code>.</p><p>You can also use a function in the format <code class="code">transformer(s: string) =&gt; string</code>, where <code class="code">s</code> is the image URL to be transformed and the return value is the transformed URL: See example:</p><pre class="programlisting ts" data-language="ts" id="UUID-62ef3d45-c0f5-0949-be7b-f28b9d388be3_programlisting-id135577012520997"><code class="language-ts" data-language="ts">function rewriteEdgeHostInString(str: string): string {
  const customEdgeUrl = 'my-custom.com';
  const EDGE_HOST_PATTERN = new RegExp(
    `custom-matcher-here`,
    'gi'
  );
  return str.replace(EDGE_HOST_PATTERN, customEdgeUrl);
}</code></pre><p>default: <code class="code">false</code></p></td><td class="td"><p><span class="emphasis"><em>n/a</em></span></p></td></tr></tbody></table>