Configuration

A backend service reads its configuration from environment variables. A storefront project has one file,evolve.config.ts, for the evolve commands that work on it.

Services

Each commerce engine and service package ships a config class with the variables it needs. Your service extends that class with its own variables and loads it once at startup. Loading fails and names the variable when a required one is missing. The classes are built on @evolve-framework/config.

import { type EnviConfig, envfield } from "@evolve-framework/config";
import { CommercetoolsConfig } from "@evolve-framework/commercetools";

class Config extends CommercetoolsConfig {
  readonly HTTP_PORT = 8080;

  config(): EnviConfig {
    return { ...super.config(), HTTP_PORT: envfield.number() };
  }
}

export const config = new Config();
await config.load();

A secret is removed from process.env once it is read. A list is one variable with its values separated, such as a,b.

CommercetoolsConfig

From @evolve-framework/commercetools. The commercetools project a service talks to, and the API clients it uses: one for the service itself, and one for the anonymous and customer tokens a storefront's shoppers get. Extend it with the service's own settings.

Variable	Description
CTP_API_URLrequired	The region's API host, such as https://api.europe-west1.gcp.commercetools.com.
CTP_AUTH_URLrequired	The region's auth host, such as https://auth.europe-west1.gcp.commercetools.com.
CTP_CLIENT_IDrequired	The service's own API client, used for system-scoped requests.
CTP_CLIENT_SECREToptional · secret	That client's secret. Removed from the environment once read.
CTP_PROJECT_KEYrequired	The commercetools project's key.
CTP_SCOPESrequired · list, ","	The service client's scopes, comma-separated in the environment.
CTP_USER_CLIENT_IDoptional	The API client that issues anonymous and customer tokens.
CTP_USER_CLIENT_SECREToptional · secret	That client's secret. Removed from the environment once read.
CTP_USER_SCOPESoptional · list, ","	The scopes of anonymous and customer tokens. Defaults to DEFAULT_USER_SCOPES.Default view_published_products,manage_my_shopping_lists,manage_my_profile,manage_my_orders,manage_my_payments,manage_my_business_units,manage_my_quote_requests

MCPCoreConfig

From @evolve-framework/mcp-core. Base configuration class for MCP services. Services should extend this class and override COMPONENT_NAME (and HTTP_PORT if needed).

Variable	Description
COMPONENT_NAMEoptional	The service's name, which a service overrides. Defaults to mcp-server.Default mcp-server
COMPONENT_VERSIONoptional	The service's version, for the service to report. Unset by default.
HTTP_HOSToptional	The address the HTTP server binds to. Defaults to 0.0.0.0.Default 0.0.0.0
HTTP_PORToptional · number	The port the HTTP server listens on. Defaults to 6000.Default 6000
MCP_ENDPOINT_PATHoptional	The path MCP clients post to. Defaults to /mcp.Default /mcp
GATEWAY_ENDPOINToptional	The GraphQL gateway the tools call, as the storefront does.Default http://localhost:4000/graphql
ACCOUNT_SERVICE_ENDPOINToptional	The account service's URL, for a service that calls it directly.Default http://localhost:4001
DEFAULT_STORE_KEYoptional	The store a request is scoped to when it names none.Default evolve
DEFAULT_LOCALEoptional	The locale a request uses when it names none.Default nl-NL
DEFAULT_CURRENCYoptional	The currency a request uses when it names none.Default EUR
JWT_ISSUERoptional · list, ","	The issuers a bearer token may come from; comma-separated for several.Default http://localhost:4000
JWT_AUDIENCEoptional · list, ","	The audiences a bearer token may be for; comma-separated for several.Default http://localhost:4000
PROXY_AUTH_ENABLEDoptional · boolean	When true, a trusted proxy may forward a pre-authenticated session via the X-Access-Token / X-Data-Token / X-Refresh-Token headers. These take precedence over Authorization: Bearer and skip JWT pre-validation — token validity is enforced by the downstream gateway. Leave disabled unless this service sits behind a trusted proxy (e.g. the chat backend).Default false
MCP_PUBLIC_URLoptional	The canonical address clients connect to, which tokens are bound to.Default http://localhost:6000/mcp
MCP_LOGIN_URLoptional	The storefront's login page, for customers connecting a client.Default http://localhost:3000/account/login
MCP_OAUTH_SECRETSoptional · secret	Comma-separated secrets of at least 32 bytes, which seal every token. Stays with this service. OAuth is off while this is unset.Default
MCP_INTERACTION_SECREToptional · secret	What the login page authenticates with on the interaction routes. At least 32 bytes.Default
TOKEN_REFRESH_THRESHOLD_SECONDSoptional · number	A token with less than this many seconds left is refreshed. Defaults to 300.Default 300
RATE_LIMIT_MAXoptional · number	The requests a client may make per rate-limit window. Defaults to 100.Default 100
RATE_LIMIT_ADDRESS_MAXoptional · number	With OAuth, the requests per IP address per window, for those without a valid token. Clients in the cloud share addresses. Defaults to 1000.Default 1000
RATE_LIMIT_WINDOW_SECONDSoptional · number	The rate-limit window, in seconds. Defaults to 60.Default 60

MedusaConfig

From @evolve-framework/medusa. Everything the adapter needs to talk to Medusa — and nothing that would let it act as an administrator.

Variable	Description
MEDUSA_API_URLrequired	The Medusa server's URL, the base of its Store API.
MEDUSA_STORESrequired · object	The stores this service serves, as JSON keyed by store key, each with its publishableKey. A store without one fails the load.
MEDUSA_REQUEST_TIMEOUToptional · number	Milliseconds a request to Medusa may take, reading the response included, before it is aborted with a TimeoutError. Default 10000; 0 means no limit.Default 10000

CommerceCloudConfig

From @evolve-framework/sfcc. The Salesforce Commerce Cloud instance a service talks to, through a SLAS client. Extend it with the service's own settings.

Variable	Description
SFCC_CLIENT_IDrequired	The SLAS client's id.
SFCC_CLIENT_SECRETrequired · secret	The SLAS client's secret. Removed from the environment once read.
SFCC_SITE_IDrequired	The storefront site, as Business Manager names it.
SFCC_ORGANIZATION_IDrequired	The organization id, such as f_ecom_zzzz_001.
SFCC_SHORT_CODErequired	The short code in the instance's API host.

Storefront project

evolve.config.ts in the project root tells commands such as evolve messages which locales the project has and where its files are. It comes with @evolve-storefront/commands.

import { routing } from "./src/lib/i18n/routing";
import { defineEvolveConfig } from "@evolve-storefront/commands/config";

export default defineEvolveConfig({
  locales: routing.locales,
  sourceLocale: "en",
  messagesDir: "./messages",
  srcDir: "./src",
});

Field	Type	Description
locales	readonly string[]	Every locale the project serves. More Point this at the project's routing.locales rather than repeating the list. A second copy drifts, and the failure is quiet: add a locale to routing, forget it here, and that locale has no message file until a user lands on it.
sourceLocale	string	The locale strings are authored in. Only this locale is scanned for keys in project code — in any other, a missing key would be written as its own key name and sent to translators as if it were copy.
messagesDir	string	Where the per-locale message files live. Relative to the project root.
srcDir	string	Project source to scan for useTranslations / getTranslations.