// Environment variable management patterns. CRITICAL use when adding new environment variables (secrets, API keys, config), debugging "X not defined" or missing env var errors, tests passing locally but failing in CI, Turborepo not passing env vars to tasks, or troubleshooting deployment configuration errors.
| name | environment-variables |
| description | Environment variable management patterns. CRITICAL use when adding new environment variables (secrets, API keys, config), debugging "X not defined" or missing env var errors, tests passing locally but failing in CI, Turborepo not passing env vars to tasks, or troubleshooting deployment configuration errors. |
| allowed-tools | ["Read","Edit","Grep","Glob","Bash"] |
All environment variables are stored in Doppler. Never hardcode secrets or commit them to git.
When adding a new environment variable:
Add to the appropriate Doppler project and environment.
Map from GitHub Secrets in .github/workflows/ci.yml:
jobs:
test:
env:
CLICKHOUSE_URL: ${{ secrets.CLICKHOUSE_URL }}
API_KEY: ${{ secrets.API_KEY }}
Secrets must exist in repository settings → Secrets → Actions first.
VITE_* Variables (Dockerfile + CI Deploy)Frontend variables prefixed with VITE_ are baked into the web app at build time by Vite. They must be declared in two places:
A) Dockerfile — Add an ARG declaration so Docker receives the value:
ARG VITE_ADMIN_ORGANIZATION_ID=""
B) .github/workflows/ci.yml deploy step — Pass the value as a --build-arg:
- name: Deploy
run: |
flyctl deploy --remote-only \
--build-arg "VITE_ADMIN_ORGANIZATION_ID=${{ secrets.VITE_ADMIN_ORGANIZATION_ID }}"
If either is missing, the variable will be empty in the deployed frontend.
CRITICAL: Add to package-specific turbo.json, NOT root.
{
"extends": ["//"],
"tasks": {
"test": {
"passThroughEnv": ["CLICKHOUSE_URL", "API_KEY"]
}
}
}
.github/workflows/ci.yml (if used in CI)VITE_*: Add ARG in Dockerfile and --build-arg in CI deploy stepturbo.json → passThroughEnvCheck in order:
doppler secrets get VAR_NAMEcat packages/your-package/turbo.json | grep -A 10 passThroughEnv❌ Adding to root turbo.json instead of package-specific
❌ Adding a VITE_* var to CI deploy --build-arg but not as ARG in Dockerfile (or vice versa)
CRITICAL - Invoke BEFORE writing ANY test code. Use when creating new tests, adding test cases, modifying existing tests, writing `it()` or `describe()` blocks, or touching any `*.test.ts` or `*.spec.ts` file. Enforces no try-catch in positive tests, no early returns, no test skipping.
Test the local Rudel API with authenticated requests. Use when the user wants to test API endpoints, debug RPC calls, verify auth flows, or inspect API responses against the local dev server.
Use when creating a pull request. Runs verification, reviews changes, and creates the PR with correct metadata. Invoke BEFORE pushing code.
TypeScript coding standards. Use when writing TypeScript, reviewing code, or refactoring. Enforces named exports, no dynamic imports, discriminated unions, proper type safety.
Query ClickHouse databases using the chcli CLI tool. Use when the user wants to run SQL queries against ClickHouse, explore database schemas, inspect tables, or extract data from ClickHouse.
Code architecture patterns. Use when organizing code, refactoring classes, designing service structure, or extracting/moving code to new files. Enforces function ordering, service functions over classes, dependency injection.