super-productivity/docs/wiki/2.16-Set-Up-Development-Environment.md

Set Up Development Environment

How to configure environment variables and generated config for development and builds.

The app uses static environment files for flags (dev/prod/stage) and a .env file for secrets and dynamic values. Values from .env are turned into TypeScript constants so you use type-safe imports, not process.env.

One-time Setup

cp .env.example .env

Edit .env and add any keys you need (e.g. API keys for optional integrations). Do not commit .env; the generated file src/app/config/env.generated.ts is gitignored.

Using Variables in Code

import { ENV } from './app/config/env.generated';

const value = ENV.SOME_KEY;

Or with helpers:

import { getEnv, getEnvOrDefault } from './app/util/env';

const value = getEnv('SOME_KEY');
const withDefault = getEnvOrDefault('SOME_KEY', 'default');

Types and keys are derived from .env when you run any build or serve command.

Adding a New Variable

1. Add the key and value to .env.
2. Run ng serve or a build command so env.generated.ts is regenerated.
3. Use ENV.NEW_KEY or getEnv('NEW_KEY') in code.

Static Vs Dynamic Config

• Static: src/environments/environment.ts, environment.prod.ts, environment.stage.ts (production/stage flags, version).
• Dynamic: .env → src/app/config/env.generated.ts (secrets and per-developer values).

Related

• ENV_SETUP.md (full reference in the repo)
• 2.11-Run-the-Development-Server

Unit Test Browser (Chrome)

The unit tests run in headless Chrome via Karma (npm test, npm run test:file). The pre-push git hook runs npm run lint && npm run test, so a Chrome binary must be resolvable or git push will fail with the following error:

ERROR [launcher]: No binary for Chrome browser on your platform.
  Please, set "CHROME_BIN" env variable.

Karma's karma-chrome-launcher locates the browser via the CHROME_BIN environment variable, falling back to a system Chrome install. There are two paths you can take:

Option A — Use a system Google Chrome

Install Google Chrome through your OS package manager. The karma config uses karma-chrome-launcher's Chrome launcher (base: 'Chrome' in src/karma.conf.js), which on Linux only auto-detects real Google Chrome — it probes for google-chrome / google-chrome-stable, not chromium / chromium-browser. So a distro Chromium package is generally not picked up automatically; for anything other than Google Chrome (or a Chrome in a non-standard location) set CHROME_BIN explicitly, as in Option B.

Snap / Flatpak Caveat

karma-chrome-launcher execs the browser binary directly with its own flags (including a temp --user-data-dir), so sandboxed packages need extra care:

Snap works, but isn't auto-detected (the launcher doesn't probe /snap/bin/chromium). Set it explicitly in your shell profile: export CHROME_BIN=/snap/bin/chromium

Flatpak is not recommended. There's no plain executable to point CHROME_BIN at — you'd have to wrap flatpak run org.chromium.Chromium "$@" in a script — and even then the sandbox blocks Karma's temp profile directory, so it typically fails to launch. Prefer a native Google Chrome package (this option) or Chrome for Testing (Option B).

Option B — Install Chrome for Testing and set CHROME_BIN

Install a pinned Chrome for Testing build into a folder of your choice (all examples below use ~/.cache/puppeteer), then point CHROME_BIN at it:

npx @puppeteer/browsers install chrome@stable --path "$HOME/.cache/puppeteer"

The --path flag is recommended: the standalone @puppeteer/browsers CLI defaults its download location to the current working directory so without it you'd get an untracked ./chrome/ folder inside the repo and the find below would match nothing.

Add the resolved path to your shell profile (~/.zshrc, ~/.bashrc, …) so it's set for every session — including the non-interactive shell the git hook runs in:

# Looks for the Chrome for Testing binary in ~/.cache/puppeteer/chrome, sorted by version so the latest version is picked if you happen to have multiple
export CHROME_BIN="$(find "$HOME/.cache/puppeteer/chrome" -name chrome -type f | sort -V | tail -n1)"

On macOS the binary is named Google Chrome for Testing inside an .app bundle, so the -name chrome filter above matches nothing. Use this instead:

# Same idea, but matches the macOS executable inside the .app bundle
export CHROME_BIN="$(find "$HOME/.cache/puppeteer/chrome" -type f -name 'Google Chrome for Testing' -path '*Contents/MacOS*' | sort | tail -n1)"

Reload your shell (or source the profile) and verify:

echo "$CHROME_BIN"        # should print a path
"$CHROME_BIN" --version   # should print a Chrome version

With CHROME_BIN set, npm test and git push (via the hook) work without further configuration.