From 1136e55ebf6a2301ce82bd09c7cde7069293bbe4 Mon Sep 17 00:00:00 2001 From: Amiram_se Date: Mon, 5 Oct 2026 19:01:39 +0400 Subject: [PATCH] chore(skill): forbid hard-coded env values No project hard-codes a value that changes between environments: no literal address, key, ID or flag, no fallback, and no schema default. Every env value comes from the .env of the app that serves it, and only apps have .env files. Adds the rule to the env lib spec, the env flow, the refactoring smells, and the Definition of Done. Co-Authored-By: Claude Opus 5.5 --- .claude/skills/front-end-architect/SKILL.md | 4 +++- .../front-end-architect/references/lib-env.md | 16 +++++++++++----- .../references/project-structure.md | 2 +- .../references/refactoring.md | 3 ++- 4 files changed, 17 insertions(+), 8 deletions(-) diff --git a/.claude/skills/front-end-architect/SKILL.md b/.claude/skills/front-end-architect/SKILL.md index c3e4718..e803289 100644 --- a/.claude/skills/front-end-architect/SKILL.md +++ b/.claude/skills/front-end-architect/SKILL.md @@ -39,7 +39,7 @@ Read the playbook before designing or writing code: [references/b2c-b2b.md](refe | Server state | TanStack Query | Configured in `configs/react-query.ts`; query keys live in the repository's `constants.ts`; queries don't retry on their own, because the HTTP lib does, and a failed first load throws to its error boundary, where the user retries | | Toasts | sonner | After every completed or failed action; never for reads | | i18n | i18next + react-i18next | No hard-coded UI text | -| Env | @t3-oss/env-core + valibot | The app validates its variables with `createClientEnv` and `createServerEnv` from `packages/libs/env`; other projects read only their own `env/` | +| Env | @t3-oss/env-core + valibot | The app validates its variables with `createClientEnv` and `createServerEnv` from `packages/libs/env`; other projects read only their own `env/`. No hard-coded env values | | Lint and format | oxlint, prettier | ESLint runs module-boundary rules only | | TS scripts and configs | jiti | Runs `tools/` scripts and TypeScript config files without a build step | | Icons | svgo | Through island's `icon-sprite-plugin` | @@ -113,6 +113,7 @@ Error handling, patterns, and refactoring have their own references. Read each o **Env, HTTP, cookies, and storage** - Env (`packages/libs/src/env`): only the app's `env/` files read `process.env`, through `createClientEnv` (public) and `createServerEnv` (server only). Other projects read their own values with `getEnv`, filled by the app's bootstrap. Libs never read env; the bootstrap passes their settings through `configure`. + - No project hard-codes an env value: a value that changes between environments, such as a service or CDN address, a key, a third-party ID, or a feature flag. Not as a literal, a fallback (`?? 'http://localhost:3000'`), or a schema default. Every env value comes from the `.env` of the app that serves it, and only apps have `.env` files. Values that are the same in every environment stay in `constants/`. - HTTP (`packages/libs/http`): one root `http` client, configured in the app's bootstrap, and one client per feature made with `http.extend(...)`, so every feature shares one token refresh, the interceptors, and error normalization. - Auth is cookie-based. On a 401, one refresh runs for the whole app, the waiting requests replay once, and a failed refresh triggers logout. The server side never refreshes and never sends the auth cookies. - Retry covers only idempotent requests, with backoff. Every request is abortable, and aborted requests are silent. Uploads report progress. @@ -187,6 +188,7 @@ Structure [ ] Repositories have no client-side dependencies; UI and stores use *Payload types only [ ] Repositories send requests only through their feature's http.ts client; no fetch outside the HTTP lib [ ] Env is read only in the app's env/ files and through each project's getEnv(); no process.env elsewhere +[ ] No hard-coded env value, fallback, or schema default; every env value comes from the app's .env, and only apps have .env files [ ] Every action emits its event when it succeeds, unless called with { emit: false } [ ] No tokens or personal data in cookies or local storage; neither is read during render [ ] Every new pattern answers a named signal and sits where design-patterns.md puts it; none is on its "Not used here" list diff --git a/.claude/skills/front-end-architect/references/lib-env.md b/.claude/skills/front-end-architect/references/lib-env.md index c8e4a51..c5cd33b 100644 --- a/.claude/skills/front-end-architect/references/lib-env.md +++ b/.claude/skills/front-end-architect/references/lib-env.md @@ -4,6 +4,8 @@ Validates the app's environment variables and gives apps typed, read-only values Only apps call it. Every other project gets its values from the app's bootstrap through its own `env/` (`setEnv` and `getEnv`), so no project below the app reads the environment. +No project hard-codes an env value. An env value is a value that changes between environments: a service or CDN address, a key, a third-party ID, a feature flag. Every env value comes from the `.env` of the app that serves it, and only apps have `.env` files. + Contents: Structure · Types · API · Validation · The app's env · Project env · Bootstrap · Implementation · Usage · Acceptance checklist ## Structure @@ -52,8 +54,8 @@ export type ServerEnvOptions = { - It has no `skipValidation`: public variables are inlined when the app is built, so they must be present at build time anyway. - `createServerEnv(options)` returns `EnvValues`. It is server-only, so a client import fails the build, and it reads `runtimeEnv: process.env` at runtime. - Both: - - Empty strings count as missing (`emptyStringAsUndefined`), so `API_URL=` in a `.env` file fails instead of passing as `''`, and an optional variable gets its default. - - The values are the schema outputs, so defaults and transforms apply: `v.optional(v.pipe(v.string(), v.transform(Number), v.integer()), '24')` gives the number `24`. + - Empty strings count as missing (`emptyStringAsUndefined`), so `API_URL=` in a `.env` file fails instead of passing as `''`. + - The values are the schema outputs, so transforms apply: `v.pipe(v.string(), v.transform(Number), v.integer())` turns `'24'` into the number `24`. - On failure they throw one `Error` that lists every invalid variable and why: ``` @@ -68,7 +70,7 @@ export type ServerEnvOptions = { - Validation runs when the app's env module first loads. Both bootstraps import it first, so a bad variable stops the app with one clear error before any page renders. - Next.js: to fail the build instead, load `env/env.client.ts` from `next.config.ts` (with jiti when the config can't resolve it). Never load `env.server.ts` there: `server-only` throws outside the React server graph. -- `skipValidation` (server env only) is for steps that run without the real env: lint, type-check, and a Docker image build without runtime secrets. The app sets it from a flag (`SKIP_ENV_VALIDATION=true`). Skipped validation returns the raw strings without defaults or transforms, so a running app never sets it. +- `skipValidation` (server env only) is for steps that run without the real env: lint, type-check, and a Docker image build without runtime secrets. The app sets it from a flag (`SKIP_ENV_VALIDATION=true`). Skipped validation returns the raw strings without transforms, so a running app never sets it. - Messages come from the schemas, and valibot's default messages repeat the received value. Give every secret's schema its own message (`v.minLength(32, 'Use at least 32 characters')`), and never log env values. ## The app's env @@ -83,6 +85,8 @@ apps//src/env/ - These files are the only code in the repo that reads `process.env`. - App code (bootstrap, configs) reads `clientEnv` and `serverEnv` directly. Only server code imports `../env/server`. +- Every value comes from the app's `.env` files. Only apps that serve in production have `.env` files; platforms, island, libs, integrations, and tools have none. +- Every variable is required. Never give a schema a default (`v.optional(schema, 'http://localhost:3000')`) or add a fallback in code (`clientEnv.NEXT_PUBLIC_API_URL ?? '...'`). A default or a fallback is a hard-coded value that hides a missing variable. ## Project env @@ -99,7 +103,8 @@ Every project except apps that reads env has: - The type uses the project's own names (`cdnUrl`, `catalogApiUrl`), not variable names. The bootstrap maps one to the other, so renaming a variable only touches the app. - Read `getEnv()` inside functions, never at module top level, because bootstrap may not have run yet: `baseUrl: () => getEnv().catalogApiUrl`. - The project never imports the app or reads the raw environment, so the dependency graph stays acyclic. -- Libs have no project env; they never read env. The bootstrap passes their settings through `configure`: `http.configure({ baseUrl })`, `configureServerHttp({ baseUrl, getCookieHeader })`, `cookie.configure({ secure })`. +- The project never hard-codes an env value: no literal address, key, ID, or flag, and no fallback for a `getEnv()` value. A new env value goes in the project's env type, and the app fills it from its `.env`. +- Libs have no project env; they never read env. The bootstrap passes their settings through `configure`: `http.configure({ baseUrl })`, `configureServerHttp({ baseUrl, getCookieHeader })`, `cookie.configure({ secure })`. A lib never has a default address, key, or ID; it gets them through `configure`. ## Bootstrap @@ -268,7 +273,7 @@ export const catalogHttp = http.extend({ baseUrl: () => getEnv().catalogApiUrl } For building or changing the lib: ``` -[ ] createClientEnv and createServerEnv return typed, read-only values; defaults and transforms apply +[ ] createClientEnv and createServerEnv return typed, read-only values; transforms apply [ ] A public variable without the prefix, or a declared variable missing from runtimeEnv, is a type error [ ] A missing, empty, or invalid variable throws one Error that lists every invalid variable and why [ ] Importing @project/libs/env/server outside the React server graph throws (server-only), so a client import fails the build @@ -276,4 +281,5 @@ For building or changing the lib: [ ] skipValidation returns the raw values without validating [ ] A project's getEnv throws the clear error before setEnv and returns the values after it [ ] No process.env outside the app's env/ files +[ ] No hard-coded env value, fallback, or schema default; every env value comes from the app's .env, and only apps have .env files ``` diff --git a/.claude/skills/front-end-architect/references/project-structure.md b/.claude/skills/front-end-architect/references/project-structure.md index ca545c8..07034d0 100644 --- a/.claude/skills/front-end-architect/references/project-structure.md +++ b/.claude/skills/front-end-architect/references/project-structure.md @@ -321,7 +321,7 @@ Fundamental libs have full specs: ## Env flow -1. The app declares its variables in `apps//src/env/` and validates them with the env lib: `createClientEnv` for public variables and `createServerEnv` for server variables. These files are the only code that reads `process.env`, and a bad variable stops the app with one error that lists every problem. +1. The app declares its variables in `apps//src/env/` and validates them with the env lib: `createClientEnv` for public variables and `createServerEnv` for server variables. These files are the only code that reads `process.env`, and a bad variable stops the app with one error that lists every problem. The values come only from the app's `.env` files; only apps have `.env` files, and no project hard-codes an env value, a fallback, or a schema default. 2. Every other project that reads env has `src/env/` (`env.ts`, `types.ts`, `index.ts`) with `setEnv`, which stores its own values, and `getEnv`, which returns them and throws a clear error before `setEnv` has run. Its code reads env only through `getEnv`, inside functions, never at module top level. 3. At startup the app's bootstrap calls each project's `setEnv` with the values that project needs. Projects never import the app, so the dependency graph stays acyclic. Libs never read env: the bootstrap passes their settings through `configure`. 4. `bootstrap.server.ts` fills the server module graph and may pass server-side values, such as an internal service address; `bootstrap.client.ts` fills the client module graph with public values only. Public variables use the `NEXT_PUBLIC_` prefix and are listed one by one in `runtimeEnv`, because Next.js inlines only literal `process.env.NEXT_PUBLIC_*` references. diff --git a/.claude/skills/front-end-architect/references/refactoring.md b/.claude/skills/front-end-architect/references/refactoring.md index a0e84fe..4ea0da1 100644 --- a/.claude/skills/front-end-architect/references/refactoring.md +++ b/.claude/skills/front-end-architect/references/refactoring.md @@ -162,8 +162,9 @@ The catalog doesn't name these, but this stack has them. Each line gives the sme - An action that runs another action as one of its steps, emits its own event, and still lets the inner action emit → pass `{ emit: false }` to the inner action, so listeners hear one event per operation ([code-patterns.md](code-patterns.md#action)). - An event subscription in a component or at module top level, or one without an unsubscribe → subscribe once in an effect of the `AppShell` and unsubscribe in its cleanup ([code-patterns.md](code-patterns.md#action)). - `process.env` outside the app's `env/` → the app's env, or the project's `getEnv()` inside a function ([lib-env.md](lib-env.md#project-env)). +- A hard-coded env value (an address, key, third-party ID, or flag), a fallback such as `?? 'http://localhost:3000'`, a schema default, or a `.env` file outside an app → a required variable in the app's `.env`, read through the app's env or the project's `getEnv()` ([lib-env.md](lib-env.md#the-apps-env)). -Many of these show up in a plain text search, which makes a quick first pass in review: `export *`, `'use client'` in a `page.tsx` or `layout.tsx`, `process.env` outside `env/`, `fetch(` outside the HTTP lib, and `key={index}`. +Many of these show up in a plain text search, which makes a quick first pass in review: `export *`, `'use client'` in a `page.tsx` or `layout.tsx`, `process.env` outside `env/`, `localhost` or `http` address literals outside an app's `.env`, `fetch(` outside the HTTP lib, and `key={index}`. ## Techniques used most