Configuration options for discovery.config.js

7 min read

The discovery.config.js is a configuration file for managing settings that control store behavior, appearance, and functionality. This file serves as a central hub for configuring key aspects of your FastStore website, including SEO, API connections, session management, analytics, and more.

This guide outlines the configuration options for tailoring your FastStore website using the discovery.config.js file.

Example file


_21module.exports = {
_21  contentSource: {
_21    type: "CP",
_21    project: "my-cms-project",
_21  },
_21  seo: {
_21    title: "FastStore Starter",
_21    description: "Fast Demo Store",
_21    titleTemplate: "%s | FastStore",
_21    author: "FastStore",
_21  },
_21  theme: "custom-theme",
_21  platform: "vtex",
_21  api: {
_21    storeId: "storeframework",
_21    workspace: "master",
_21    environment: "vtexcommercestable",
_21    hideUnavailableItems: false,
_21    incrementAddress: false,
_21  },
_21};

Check the full file example at discovery.config.js sample code.

As of December 16, 2024, discovery.config.js is the new filename for the legacy faststore.config.js file. If you're still using the legacy name, see this release note to update it.

Configuration options

Below is a description of each setting you can configure in the discovery.config.js file:

`contentSource`

Defines the CMS integration used by the FastStore project and the CMS project that stores its content.

Property	Type	Description	Example
`type`	`string`	CMS integration type. Use `CP` for CMS or `CMS` for Headless CMS (legacy).	`"CP"`
`project`	`string`	CMS project ID, also called the CMS store ID. If omitted, the default value is `faststore`.	`"my-cms-project"`

Set a custom project value when you need to isolate large content changes, test a different content model, or migrate content without creating a VTEX subaccount. The value must match the store ID used by the Content plugin when initializing and uploading your CMS schemas.


_10contentSource: {
_10  type: "CP",
_10  project: "my-cms-project",
_10},

`seo`

Sets default metadata related to Search Engine Optimization (SEO), influencing how your store appears in search results. Learn more in SEO.

Property	Type	Description	Example
`title`	`string`	Store headline displayed in search results (60 characters recommended).	`"FastStore Starter"`
`description`	`string`	Brief description of the store (150-160 characters optimal).	`"FastStore Demo Store"`
`titleTemplate`	`string`	Dynamic page title pattern. Use `%s` as a placeholder.	`"%s \| FastStore"`
`author`	`string`	Content author/owner for attribution.	`"FastStore"`
`minPriceAmountFractionDigits`	`number`	Minimum fraction digits used in the PDP `product:price:amount` meta tag.	`2`

`theme`

Defines the visual identity of your FastStore project, including color schemes, typography, and layout presets. This field is a string that specifies the name of the theme being used.

Every FastStore project starts with the Brandless theme by default. However, you can choose from available themes or develop a custom theme. Learn more in Themes - Overview.

`platform`

Defines the ecommerce platform being used. You must set vtex as a value to enable VTEX-specific features.

Only vtex is a valid value. Any other value will cause errors.

`api`

Contains settings related to the store's APIs, which link your FastStore storefront to backend services and manage environment-specific behavior.

Property	Type	Description	Example
`storeId`	`string`	VTEX account being used.	`"mystore"`
`workspace`	`string`	Workspace being used. Use `master` for the production environment, and other names for staging.	`"master"`
`environment`	`string`	API environment.	`"vtexcommercestable"`
`hideUnavailableItems`	`boolean`	Controls product display. When `true`, hides out-of-stock products. Default value is `false`.	`false`
`incrementAddress`	`boolean`	Enables automatic completion of address details during checkout using VTEX’s address API. When `true`, missing address fields (such as city, state, street, etc.) are automatically filled based on the provided postal code. Default value is `false`.	`false`
`customSortMap`	`object`	Maps extra `StoreSort` values to Intelligent Search sort strings. FastStore checks this map before the built-in values, and a matching key overrides a default sort. Available in FastStore `4.9.0` and later versions.	`{ rating_desc: "Rating:desc" }`
`preserveCartLines`	`boolean`	Keeps separate the cart lines of the same SKU that the store split in Checkout, instead of merging them into a single line. FastStore doesn't split lines on its own. Default value is `false`. Available in FastStore `4.10.3` and later versions. Learn more in Keeping split cart lines.	`true`

The following api excerpt maps a custom rating sort. Use the same key in the StoreSort extension and in registerCustomSortKeys. See Adding a custom search sort.


_10api: {
_10  customSortMap: {
_10    rating_desc: "Rating:desc",
_10  },
_10},

The following api excerpt keeps the lines that your store split in Checkout with the split item endpoint. See Keeping split cart lines.


_10api: {
_10  preserveCartLines: true,
_10},

`session`

Sets up user session defaults, controlling language, currency, location, and shopper attributes.

Property	Type	Description	Example
`currency`	`object`	Store’s transactional currency for prices, payment, and checkout.
├─ `code`	`string`	ISO currency code	`"USD"`
└─ `symbol`	`string`	Currency symbol	`"$"`
`locale`	`string`	Language or locale setting for all store text, dates, and numbers. Use standard locale format like `en-US` for English (US), `pt-BR` for Brazilian Portuguese, etc.	`"en-US"`
`channel`	`object`	Identifies the commercial and regional context for handling catalog, pricing, and logistics.
├─ `salesChannel`	`string`	Trade policy that handles catalog, prices, and fulfillment options (e.g.: different regions or seller-specific rules).	`"1"`
└─ `regionId`	`string`	Internal identifier used to define regional segmentation based on the user’s location for services such as catalog, shipping, pickup, and other logistics-related processes.
`country`	`string`	ISO country code for the current shopper’s session. This field informs VTEX services which country’s regulations, delivery logistics, and tax rules must be applied.	`"US"`
`deliveryMode`	`string`	Order fulfillment method, including delivery channel, selected courier or method, delivery window (start and end times), or pickup point.	`"delivery"`
`addressType`	`string`	Address format for fulfillment	`"residential"`
`postalCode`	`string`	User’s postal code	`"10001"`
`geoCoordinates`	`float[]`	User’s location as [latitude, longitude]	`[40.7128, -74.0060]`
`person`	`object`	Shopper identity attributes.
├─ `id`	`string`	Unique VTEX customer ID. VTEX Identity service may auto-populate these fields after sign-in.	`"12345"`
├─ `email`	`string`	Customer’s email address	`"user@email.com"`
├─ `firstName`	`string`	Customer’s first name.	`"Alex"`
└─ `lastName`	`string`	Customer’s last name.	`"Smith"`

`cart`

Contains the settings to manage the shopping cart’s contents and behavior.

Property	Type	Description	Example
`id`	`string`	Unique identifier of the cart.	`"cart-abc-123"`
`items`	`array`	Products added to the cart.	`[{"sku": "5678", "quantity": 2}]`
`messages`	`string[]`	System messages associated with the cart, such as shipping changes or other relevant information.	`["Shipping updated"]`
`shouldSplitItem`	`boolean`	If `true`, allows cart items from multiple sellers or differing stock locations to be shipped separately.	`true`

`storeUrl`

Defines the primary store domain as a string. Example: https://www.mystore.com.

`secureSubdomain`

Defines the HTTPS-enabled subdomain, if used, as a string. Example: https://secure.mystore.com.

`checkoutUrl`

Defines the URL for the checkout process as a string. Example: https://www.mystore.com/checkout.

`loginUrl`

Defines the URL for the login process as a string. Example: https://www.mystore.com/login.

`accountUrl`

Defines the URL for the customer's account management page as a string. Example: https://www.mystore.com/account.

Learn more about store domains in Associating your custom domain with your FastStore project.

`previewRedirects`

Maps redirect URLs for the following page types in preview mode.

Property	Type	Description	Example
`home`	`string`	Redirect URL for the homepage.	`"https://preview.mystore.com"`
`plp`	`string`	Redirect URL for product listing pages (PLP).	`"https://preview.mystore.com/category"`
`search`	`string`	Redirect URL for search results pages.	`"https://preview.mystore.com/search"`
`pdp`	`string`	Redirect URL for product detail pages (PDP).	`"https://preview.mystore.com/product"`

Learn more in Managing URLs with redirects and rewrite paths.

`lighthouse`

Includes settings for Lighthouse, a tool for auditing and improving the quality of web pages.

Property	Type	Description	Example
`server`	`string`	The server URL for running Lighthouse audits.	`process.env.BASE_SITE_URL \| 'http://localhost:3000'`
`pages`	`object`	Maps the URL of pages to be audited by Lighthouse.
├─ `home`	`string`	URL of the homepage.	`'/'`
├─ `pdp`	`string`	URL of a product detail page.	`"/headphone-white-10000006/p"`
└─ `collection`	`string`	URL of a collection page.	`"/headphones"`

Learn more in Lighthouse Scores.

`cypress`

Defines which pages Cypress should visit in end-to-end tests, ensuring predictable routes for the CI pipeline. Prefer relative URLs (for example, "/", /headphones) and deterministic scenarios with consistent data across runs.

Property	Type	Description	Example
`pages`	`object`	Maps the URLs of pages for end-to-end testing with Cypress, with each field defined as a string.
├─ `home`	`string`	URL of the homepage.	`"/"`
├─ `pdp`	`string`	URL of the product detail page.	`"/headphone-white-10000006/p"`
├─ `collection`	`string`	URL of a collection page.	`"/headphones"`
├─ `collection_2`	`string`	URL of a secondary collection page.	`"/audio"`
├─ `collection_filtered`	`string`	URL of a filtered collection page.	`"/headphones?priceRange=100-200"`
└─ `search`	`string`	URL of a search results page.	`"/s?q=headphone"`

Learn more in enableCypressExtension.

`analytics`

Defines the Google Tag Manager ID used by the site to collect events and trigger tags, allowing you to measure interactions, funnels, and conversions.

Property	Type	Description	Example
`gtmContainerId`	`string`	The Google Tag Manager container ID.	`"GTM-1234567"`

Learn more in Analytics.

`experimental`

Contains settings for experimental features.

Property	Type	Description	Example
`nodeVersion`	`string`	The Node.js version.	`"20"`
`cypressVersion`	`string`	The Cypress version.	`"13"`
`enableScriptsLogs`	`boolean`	Enables additional browser console logs for third-party scripts and analytics integrations while debugging.	`true`
`useIsGiftFromOrderForm`	`boolean`	When `true`, uses the `isGift` field from the VTEX Order Form item to detect gift items in the cart. When `false` or unset, uses the legacy behavior of checking `item.price === 0`.	`false`
`enableRedirects`	`boolean`	(Beta) When `true`, enables managing redirects through the Redirects feature in the VTEX Admin, allowing more than 1,024 redirects.	`true`
`noRobots`	`boolean`	When `true`, prevents the default `robots` meta tag from being added to pages.	`false`
`noindex`	`boolean`	When `true`, instructs search engines not to index store pages.	`false`
`nofollow`	`boolean`	When `true`, instructs search engines not to follow links on store pages.	`false`
`graphqlCacheControl`	`object`	Settings for GraphQL responses.
├─ `maxAge`	`number`	Maximum time (in seconds) that the response can be cached.	`300`
└─ `staleWhileRevalidate`	`number`	Time (in seconds) during which stale responses can be served while revalidating.	`60`

`account`

Specifies the VTEX account name used by the project as a string. Example: mystore.

`vtexHeadlessCms`

Configures webhook endpoints for VTEX Headless CMS to trigger publishing, cache invalidation, or content preview whenever changes occur in the CMS.

Property	Type	Description	Example
`webhookUrls`	`array of strings`	An array of strings that defines the webhook URLs used to interact with the Headless CMS.	`["https://mystore.myvtex.com/cms-releases/webhook-releases"]`

Example file.css-17dhml5{min-width:18px;min-height:18px;width:18px;height:18px;}

Configuration options

contentSource

seo

theme

platform

api

session

cart

storeUrl

secureSubdomain

checkoutUrl

loginUrl

accountUrl

previewRedirects

lighthouse

cypress

analytics

experimental

account

vtexHeadlessCms