commands

@evolve-storefront/commands · v1.0.0

Build-time commands for a storefront project, contributed to the evolve CLI.

Get started

1. Install the package with the peer dependencies it needs. It comes from the Evolve registry, which needs a one-time sign-in.

   pnpm add @evolve-storefront/commands @evolve-framework/cli

   Requirements2

   node	>=24.8
   @evolve-framework/cli	>=0.2.0

Then render it on a page:

evolve messages build              # regenerate every configured locale
evolve messages build --locale nl  # filter to one, for a fast loop
evolve messages build --check      # CI: writes nothing, non-zero if not ready

Commands

Installing this package adds these commands to the evolve CLI.

• evolve add: Add a piece of Evolve wiring to this project (e2e, brand-contrast)
• evolve messages: Generate the project's message files from its packages

Functions

assertConfigValidate the shape by hand rather than with Zod: this package is imported by the CLI in a consumer's install, so every dependency it adds is one the consumer pays for, and four fields do not justify one.

import { assertConfig } from "@evolve-storefront/commands/config";

function assertConfig(value: unknown, source: string): EvolveConfig

Returns EvolveConfig

defineEvolveConfigIdentity helper, for typing evolve.config.ts:

import { defineEvolveConfig } from "@evolve-storefront/commands/config";

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",
});

function defineEvolveConfig(config: EvolveConfig): EvolveConfig

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

Returns EvolveConfig

loadConfigRead evolve.config.* from a project root.

import { loadConfig } from "@evolve-storefront/commands/config";

Imported rather than parsed, because the whole point of the locales field is that it can be routing.locales — a value the project computes.

Loading a .ts config depends on the runtime stripping types, which Node has done natively since 22.6 and unflagged since 23.6. The package requires >=24.8, so that holds; the error below says so rather than surfacing Node's own Unknown file extension if someone runs it on something older.

function loadConfig(cwd: string): Promise<EvolveConfig>

Returns Promise<EvolveConfig>

resolveLocalesNarrow the configured locales to what --locale asked for.

import { resolveLocales } from "@evolve-storefront/commands/config";

A locale that is not configured is an error, not an extension. Allowing it would make the flag a second source of truth by the back door, which is the thing keeping locales in config is meant to prevent.

function resolveLocales(
  config: EvolveConfig,
  requested: string | undefined,
): readonly string[]

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

Returns readonly string[]

Types

EvolveConfig

import { type EvolveConfig } from "@evolve-storefront/commands/config";

type EvolveConfig = {
  locales: readonly string[];
  sourceLocale: string;
  messagesDir: string;
  srcDir: string;
};