feat(nextjs): codegen for runtimeEnv destructuring#1092
Merged
yamcodes merged 24 commits intoMay 31, 2026
Conversation
yamcodes
added
enhancement
Contributor
|
Pullfrog stalled The agent stopped emitting events for 304s and was killed by the activity-timeout watchdog. 295 events were processed before the failure. Recent agent stderr
|
🦋 Changeset detectedLatest commit: 9e034e8 The changes in this PR will be included in the next version bump. This PR includes changesets to release 5 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
github-actions
Bot
added
docs
arkenv
@arkenv/bun-plugin
@arkenv/cli
@arkenv/fumadocs-ui
@arkenv/nextjs
@arkenv/vite-plugin
commit: |
Contributor
📦 Bundle Size Report
✅ All size limits passed! |
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as resolved.
This comment was marked as resolved.
github-actions
Bot
added
www
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
…y and remove ts-nocheck from output
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
![pullfrog[bot]](https://avatars.githubusercontent.com/in/1768019?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Important
The new commits moved the default generated output to a generated/ subdirectory, but several documentation references still point to the old co-located ./env.gen path. Additionally, getUsageInstructions in the CLI scaffold utils is now dead code.
Reviewed changes — moved the default generated env factory from co-located env.gen.ts to generated/env.gen.ts (relative to the schema directory), removed // @ts-nocheck from generated output, and updated tests and CLI templates to match.
- Relocated default output path —
withArkEnvnow writes togenerated/env.gen.tsby default instead of co-locatedenv.gen.ts, keeping generated files organized in a dedicated folder. - Removed
// @ts-nocheck— the generated factory no longer suppresses TypeScript checks, improving type safety. - Updated CLI scaffolding — Next.js template now imports from
./generated/env.genand no longer emits manualruntimeEnvboilerplate. - Updated tests —
config.test.tsandenv-template.test.tsassertions reflect the new default path and removedts-nocheck.
⚠️ Stale documentation references to old default path
The default output path changed from env.gen.ts to generated/env.gen.ts, but the following docs still tell users to import from ./env.gen:
apps/www/content/docs/nextjs/index.mdx— step 1 example imports from./env.genpackages/nextjs/README.md— setup example imports from./env.gen.changeset/nextjs-codegen-helper.md— example usage imports from./env.gen
These should be updated to ./generated/env.gen (or note that the path depends on the outputPath option).
ℹ️ Nitpicks
packages/cli/src/features/scaffold/utils.ts—getUsageInstructionsis no longer called byexecutor.ts(replaced by inline logic ingetNextStepsNote). Consider removing the function and its tests to avoid dead code.
Note: 2 inline comment(s) dropped because they did not anchor to lines inside the PR diff:
packages/cli/src/features/scaffold/utils.ts:28(RIGHT) — line 28 (RIGHT) is not inside a diff hunkpackages/cli/src/features/scaffold/utils.test.ts:6(RIGHT) — line 6 (RIGHT) is not inside a diff hunk
Kimi K2 ｜ 𝕏
…move scaffold usage instructions utility
Owner
Author
|
LGTM |
… files across all templates
Contributor
There was a problem hiding this comment.
Important
The new commits add CLI bootstrap codegen and JSDoc, but documentation still references the old co-located ./env.gen path in several places. Additionally, getUsageInstructions remains dead code after being replaced by inline logic in getNextStepsNote.
Reviewed changes — added CLI post-scaffold codegen for Next.js, expanded planner bootstrap eligibility, and added detailed JSDoc to ArkEnvConfigOptions.
- Added Next.js bootstrap codegen in
executor.ts— after scaffolding, the CLI now runsrunCodegenvianode -eto generate the initialenv.gen.tsfor Next.js projects. - Expanded planner bootstrap framework list —
nextjsis now included alongsideviteandbun-fullstackas a framework that receives post-scaffold bootstrapping. - Added JSDoc to
ArkEnvConfigOptions— documentedschemaPathandoutputPathwith descriptions, defaults, and usage examples.
⚠️ Stale documentation references to old default path
The default output path changed to generated/env.gen.ts, but the following docs still tell users to import from ./env.gen:
apps/www/content/docs/nextjs/index.mdx— step 1 example imports from./env.genpackages/nextjs/README.md— setup example imports from./env.gen.changeset/nextjs-codegen-helper.md— example usage imports from./env.gen
These should be updated to ./generated/env.gen (or note that the path depends on the outputPath option).
ℹ️ Nitpicks
packages/cli/src/features/scaffold/utils.ts—getUsageInstructionsis no longer called bygetNextStepsNote(replaced by inline logic). Consider removing the function and its tests to avoid dead code.
Kimi K2 ｜ 𝕏
Owner
Author
|
Some people don't like codegen, we should have a way to opt out like in the CLI. |
Contributor
There was a problem hiding this comment.
✅ No new issues found.
Reviewed changes — addressed prior review feedback and added tsconfig paths resolution for Next.js scaffolding imports.
- Fixed stale documentation references — all docs, changeset, and README examples now correctly import from
./generated/env.geninstead of the old co-located./env.gen. - Removed dead code —
getUsageInstructionsand its test file were deleted after being replaced by inline logic ingetNextStepsNote. - Added tsconfig paths resolution for Next.js — the planner now detects
@/*path mappings intsconfig.jsonand generates an appropriate@/...import path for the scaffoldedenv.tswhen the generated directory falls inside the mapped folder. Falls back to a relative path otherwise. - Updated all validator templates —
arktypeTemplate,zodTemplate, andvalibotTemplatenow accept an optionalnextjsImportPathparameter, passed through from the planner.
Kimi K2 ｜ 𝕏
… in Next.js projects
Contributor
There was a problem hiding this comment.
✅ No new issues found.
Reviewed changes — added --no-codegen (-C) CLI flag, interactive prompt, and disableCodegen scaffolding path to let users opt out of automatic env.gen.ts generation.
- Added
--no-codegenflag and alias-C— parsed inCLI, passed throughInitInputto the wizard, and surfaced in help output and docs. - Added interactive
nextjsCodegenprompt — asks users whether to enable automated codegen during scaffolding, defaulting totrue. - Implemented
disableCodegenscaffolding branch — when opted out, templates fall back to manualruntimeEnv+ directarkenvimport; planner skips bootstrap; executor skips post-scaffold codegen. - Updated tests and docs — CLI parser tests, help alignment tests, planner tests, and www docs all reflect the new flag and flow.
Kimi K2 ｜ 𝕏
Owner
Author
|
Needs final QA but we're practically there |
This comment was marked as resolved.
This comment was marked as resolved.
yamcodes
commented
May 31, 2026
yamcodes
deleted the
1072-featnextjs-codegen-for-runtimeenv-destructuring-1
branch
Merged
yamcodes
pushed a commit
that referenced
this pull request
May 31, 2026
This PR was opened by the [Changesets release](https://github.com/changesets/action) GitHub action. When you're ready to do a release, you can merge this and the packages will be published to npm automatically. If you're not ready to do a release yet, that's fine, whenever you add more changesets to main, this PR will be updated. # Releases ## arkenv@0.11.1 ### Patch Changes - #### Add `Infer<T>` helper to resolve environment variable types _[`#1092`](#1092) [`c6c30ab`](c6c30ab) [@yamcodes](https://github.com/yamcodes)_ Introduce the `Infer<T>` type helper, allowing developers to extract the inferred output types of their environment schemas. It supports both declarative schema shapes and compiled schemas (like Zod or ArkType types). Usage: ```ts import { createEnv, type Infer } from "arkenv"; import { type } from "arktype"; const schema = { PORT: type.number, }; export type Env = Infer<typeof schema>; ``` ## @arkenv/bun-plugin@0.1.7 ### Patch Changes <details><summary>Updated 1 dependency</summary> <small> [`c6c30ab`](c6c30ab) </small> - `arkenv@0.11.1` </details> ## @arkenv/cli@0.2.6 ### Patch Changes - #### Implement Next.js separate files mode, shared entry point, and native extends API _[`#1084`](#1084) [`d921785`](d921785) [@yamcodes](https://github.com/yamcodes)_ Introduce dedicated entry points for `@arkenv/nextjs/server`, `@arkenv/nextjs/client`, and `@arkenv/nextjs/shared` to prevent metadata leakage and support compile-time bundler-enforced isolation. Add a native `extends` API to merge validated outputs of extended proxies while maintaining proxy-level protections. Also update the CLI `init` wizard to support interactive layout selection (Strict 3-file vs Simple 1-file) and `--strict` / `--simple` flags to bypass interactive selection. Example server usage: ```ts import { createEnv } from "@arkenv/nextjs/server"; import { env as clientEnv } from "./env.client"; export const env = createEnv( { DATABASE_URL: "string" }, { extends: [clientEnv] } ); ``` Example client usage: ```ts import { createEnv } from "@arkenv/nextjs/client"; export const env = createEnv( { NEXT_PUBLIC_API_URL: "string" }, { runtimeEnv: { NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL, }, } ); ``` - #### Update Next.js scaffolding template to use codegen workflow _[`#1092`](#1092) [`c6c30ab`](c6c30ab) [@yamcodes](https://github.com/yamcodes)_ Update the CLI `nextjs` scaffolding template to adopt the new `@arkenv/nextjs/config` codegen workflow. The generated `env.ts` file now imports the auto-generated `createEnv` factory from `env.gen.ts` instead of directly importing from `@arkenv/nextjs`, which eliminates the need to manually destructure `runtimeEnv` variables. Additionally, update the CLI usage instructions to guide developers on wrapping their Next.js configuration using the `withArkEnv` helper inside `next.config.ts`. #### Add `--no-codegen` CLI option and dedicated prompt for Next.js scaffolding Introduce a `--no-codegen` (or `-C`) option and an interactive prompt to allow developers to opt out of the Next.js automatic environment variable code generation workflow. When opted out, the CLI scaffolds the project to use standard runtimeEnv destructuring and skips post-scaffold code generation bootstrapping. ## @arkenv/nextjs@0.0.4 ### Patch Changes - #### Implement Next.js separate files mode, shared entry point, and native extends API _[`#1084`](#1084) [`d921785`](d921785) [@yamcodes](https://github.com/yamcodes)_ Introduce dedicated entry points for `@arkenv/nextjs/server`, `@arkenv/nextjs/client`, and `@arkenv/nextjs/shared` to prevent metadata leakage and support compile-time bundler-enforced isolation. Add a native `extends` API to merge validated outputs of extended proxies while maintaining proxy-level protections. Also update the CLI `init` wizard to support interactive layout selection (Strict 3-file vs Simple 1-file) and `--strict` / `--simple` flags to bypass interactive selection. Example server usage: ```ts import { createEnv } from "@arkenv/nextjs/server"; import { env as clientEnv } from "./env.client"; export const env = createEnv( { DATABASE_URL: "string" }, { extends: [clientEnv] } ); ``` Example client usage: ```ts import { createEnv } from "@arkenv/nextjs/client"; export const env = createEnv( { NEXT_PUBLIC_API_URL: "string" }, { runtimeEnv: { NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL, }, } ); ``` - #### Add `withArkEnv` configuration helper for Next.js _[`#1092`](#1092) [`c6c30ab`](c6c30ab) [@yamcodes](https://github.com/yamcodes)_ Add a Next.js configuration wrapper in `@arkenv/nextjs/config` that automates client-side and shared environment variable destructuring in the `runtimeEnv` block: ```typescript // next.config.ts import { withArkEnv } from "@arkenv/nextjs/config"; import type { NextConfig } from "next"; const nextConfig: NextConfig = { reactStrictMode: true, }; export default withArkEnv(nextConfig); ``` Key features: - **Zero-Boilerplate Destructuring**: Statically extract `client` and `shared` keys from your `env.ts` schema and generate a tailored `createEnv` factory in `generated/env.gen.ts` that pre-fills the `runtimeEnv` block. - **Development Watcher**: Automatically start a lightweight file watcher in development mode to regenerate `generated/env.gen.ts` on the fly when `env.ts` changes. - **Customizable Output**: Support custom schema and output paths, enabling developers to write generated files to a dedicated folder (e.g., `src/generated/env.gen.ts`). - **Deprecate Direct Exports**: Mark direct `createEnv` and default `arkenv` exports from the main and `react-server` entry points as deprecated to steer developers toward the new codegen workflow. Example usage in `env.ts`: ```typescript // env.ts import { createEnv } from "./generated/env.gen"; export const env = createEnv({ client: { NEXT_PUBLIC_API_URL: "string", }, shared: { NODE_ENV: "string", }, }); ``` <details><summary>Updated 1 dependency</summary> <small> [`c6c30ab`](c6c30ab) </small> - `arkenv@0.11.1` </details> ## @arkenv/vite-plugin@0.1.1 ### Patch Changes <details><summary>Updated 1 dependency</summary> <small> [`c6c30ab`](c6c30ab) </small> - `arkenv@0.11.1` </details> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #1072
Adds a new codegen helper
withArkEnv()inside@arkenv/nextjs/configthat runs during Next.js config loading. It automatically extracts keys from your schema (env.ts) and generates a tailoredcreateEnvfactory insideenv.gen.tsthat pre-fills theruntimeEnvblock.This removes the boilerplate and the need to manually destructure environment variables to satisfy Next.js's static client inlining rules.