Installation

Clone your fork

git clone <your-fork-url>
cd front-web-<your-brand>

Install dependencies

pnpm install

This will install all dependencies including @cactus-agents/* packages from GitHub Packages. If it fails with a 404 on @cactus-agents/*, your .npmrc is missing the scope→registry line — see Prerequisites.

Configure environment variables

Local development needs two files in the project root, .env and .dev.vars. They carry the same keys; only the reader differs.

The repository ships one tracked template, .env.example, which documents every variable the app reads. Copy it to both filenames:

cp .env.example .env
cp .env.example .dev.vars

Then edit both files and fill in your real values (at minimum API_BASE_URL and ORIGIN_DOMAIN).

:::info Why two files with the same content .dev.vars is read by the Cloudflare Workers runtime that performs SSR; .env is read by Vite, the build tool. Neither reads the other's file, so a variable you only put in one of them will be missing on the other side. Both are gitignored — they never leave your machine. :::

:::note No .dev.vars.example Older instructions told you to run cp .dev.vars.example .dev.vars. That file is not in the repository — the command fails with "No such file or directory". Use .env.example as the source for both files, as shown above. :::

Variable reference

.env.example is the live, authoritative list — it stays in sync with the code and carries inline comments for the less obvious keys. The table below covers the ones you must set to get a first run working:

Variable	Description	Example
API_BASE_URL	Backend API base URL	https://api.example.com/v2
ORIGIN_DOMAIN	Your brand's domain	mybrand.com
BRAND_LANGUAGE	Default language code	pt-br
BRAND_COUNTRY	Country ISO code	BRA
BRAND_CURRENCY	Currency code	BRL
BRAND_TIMEZONE	Timezone	America/Sao_Paulo

You will receive the correct values from the Cactus team.

ORIGIN_DOMAIN does double duty: besides identifying your brand to the API, the build derives your brand-override key from it by normalizing the domain (minhamarca.com → minhamarca-com). That key is the folder name under overrides/ where your per-brand configuration lives.

Beyond the six above, .env.example also ships local-development defaults for captcha test keys, the casino mode, the cache-purge secret and the gamification salt key. You can leave those at their sample values for a first run. Production values are set per environment and are covered in Deployment.

BRAND_COUNTRY also drives money display precision: Nigeria (NGA) and Chile (CHL) render values without decimals (₦1,000, $50.000), all other countries render with two decimals (R$ 1.000,00). The choice is wired through CountryConfig.displayDecimalDigits and applied automatically by the useFormatMoney / useTransactions / useBalance hooks.