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