Repository navigation
refactor: declare env variables once with envField helpers - #163
devs-rootstrap wants to merge 16 commits into
Conversation
There was a problem hiding this comment.
🟡 Changes recommended
Hardcoded app-name assertions fail in generated projects because setup replaces the name in env.js but leaves the test expectations unchanged.
1 open issue
What changed in this PR
Overall Review: ai:serious
This PR centralizes environment-variable declarations in typed envField helpers, simplifying the template’s shared build and runtime configuration.
Changes:
- Adds string, number, and boolean builders with optional values, defaults, and stricter parsing.
- Refactors environment loading to read schema keys automatically while preserving static-value precedence.
- Adds helper and integration tests and updates configuration documentation.
| File | Description |
|---|---|
env.js |
Adopts schema-driven loading and separates static values. |
env-fields.js |
Adds typed field builders and environment parsing helpers. |
docs/src/content/docs/recipes/sentry-setup.mdx |
Migrates Sentry configuration examples to envField. |
docs/src/content/docs/getting-started/environment-vars-config.mdx |
Documents single declarations, options, and parsing behavior. |
__tests__/env.test.ts |
Tests loading, validation modes, and static-value precedence. |
__tests__/env-fields.test.ts |
Tests builders, defaults, optional values, and parsing helpers. |
Review effort: Balanced
fernandatoledo
left a comment
There was a problem hiding this comment.
@devsrs I left a few comments on this PR, please take a look.
fernandatoledo
left a comment
There was a problem hiding this comment.
@devs-rootstrap I left a few comments on this PR, please take a look.
fernandatoledo
left a comment
There was a problem hiding this comment.
@devs-rootstrap thanks for the fixes, the four threads look good (error messages, case-insensitive booleans, upgrade note and the envField guard), and the env tests pass on the branch. Two small things below, plus the Copilot comment on __tests__/env.test.ts that's still open.
…helpers # Conflicts: # scripts/i18next-syntax-validation.js
| * @param {string} value | ||
| */ | ||
| function parseBoolean(value) { | ||
| if (value === 'true') { |
There was a problem hiding this comment.
Can we make this case-unsensitive just in case?
| const parseBoolean = (/** @type {string | undefined} */ value) => | ||
| value ? value === 'true' : undefined; | ||
|
|
||
| const clientEnvSchema = z.object({ |
There was a problem hiding this comment.
Why are some variables being parsed by the new envField but then others still being parsed by zod? We want to remove zod from env.js and just use envField.
If an new parser needs to be implemented in envField, that's okay.
There was a problem hiding this comment.
@asdolo Done in bb08b8c: env.js no longer imports zod. Every variable, including the static ones, is now declared with envField: APP_ENV uses a new envField.enum([...]) builder and the static strings use envField.string(). The schemas are built with a new envSchema() helper and typed with InferEnv, both exported from env-fields.js. The env vars docs (and the Sentry recipe) were updated to match, and the enum builder has tests.

Jira board reference:
What does this do?
Adds a small
envFieldinterface to declare environment variables once, with their type, instead of declaring them twice (zod schema + parsed value in_clientEnv/_buildTimeEnv).env-fields.jsmodule (CommonJS, next toenv.js) exposingenvField.string(),envField.number()andenvField.boolean(). Each builder returns a zod schema that receives the rawprocess.envstring, converts it to the declared type and validates it.optionalanddefaultoptions. Without options the variable is required, and an empty value (e.g.API_URL=) is treated as missing.env.jsnow declares each.envvariable only inclientEnvSchema/buildTimeEnvSchema. Values are read fromprocess.envfor every key declared in the schema (readEnv), and the static values defined inenv.js(NAME,BUNDLE_ID,EXPO_ACCOUNT_OWNER, ...) are kept inclientStaticValues/buildTimeStaticValuesand take precedence.parseString/parseNumber/parseBooleancalls and the hand-built_clientEnv/_buildTimeEnventries are removed. Exports (Env,ClientEnv,withEnvSuffix), when validation runs and the error output are the same as before.__tests__/env-fields.test.ts), plus tests that loadenv.jswith a mockedprocess.envin both validation modes (__tests__/env.test.ts).envField.Example:
Why did you do this?
Adding a variable meant writing its zod type in the schema and also remembering to add it to
_clientEnv/_buildTimeEnvwith the rightparseXcall. That repeated logic was easy to get out of sync. WithenvField, the schema is the only place to declare a variable, and the type conversion comes from the declared type.Who/what does this impact?
env.js(used byapp.config.tsand, throughextra, byEnvfrom@/lib/envinsrc). The variables and the exported types stay the same.envField.*instead ofz.*plus a_clientEnv/_buildTimeEnventry.Layer 2: Risk Classification
Author applies a risk label when opening the PR. When in doubt, escalate.
risk:lowrisk:mediumrisk:highLabel applied:
risk:medium(refactor of the shared env loading used by every build and run).How did you test this?
Verification
pnpm lintpnpm type-checkpnpm lint:translationspnpm testenv.jswith Node, with and without the variables setEnv/ClientEnvbuilt as expected;VAR_NUMBERandVAR_BOOLconverted to number / booleanNot verified on a device.
How to test locally
pnpm installpnpm test __tests__/env-fields.test.ts __tests__/env.test.ts.env.sampleto.env.development, fill it in and runpnpm start. The app should start as before.VAR_BOOL=yesorVAR_NUMBER=abc(or removeAPI_URL) and runpnpm startagain. It should fail with the usualInvalid environment variablesmessage listing the variable.Notes:
optionalanddefault, as described in the card's Tasks. The card'scontextidea (build time vs app) is already covered by the existing split betweenclientEnvSchemaandbuildTimeEnvSchema.accessoption (public / secret), similar to Astro'senvField..env.sample.trueandfalseare accepted. Before, any other value (e.g.TRUE,1,yes) was silently converted tofalse; now it fails validation.42,-3.5). Before, whitespace-only values became0and forms likeInfinity,0x10or1e3were accepted; now they fail validation.undefinedinstead of the raw or converted value.env.js(e.g.NAME) take precedence over a variable with the same name in the.envfile, as before.Screenshots / Previews
N/A, no UI changes.