feat(nuxt): core API & flat layout support by yamcodes · Pull Request #1248 · yamcodes/arkenv

yamcodes · 2026-06-27T14:25:33Z

Fixes #1242

This PR adds core API and flat layout support to @arkenv/nuxt, aligning it with the Next.js integration features.

Changes:

Extended ModuleOptions.layout type to support "flat", treating "simple" as a deprecated alias with dev-time warnings.
Refactored build-time key extraction helper in @arkenv/build to support parameterized framework prefixes, avoiding duplicate AST RegExp parsing in @arkenv/nuxt and @arkenv/nextjs.
Updated createEnvInternal to support runtime key categorization and proxy shielding under the flat layout using NUXT_PUBLIC_, NODE_ENV, and exposeToClient.
Added flat signature overloads and runtime handlers to the main createEnv entrypoint in @arkenv/nuxt with robust TypeScript type inference.

changeset-bot · 2026-06-27T14:25:37Z

🦋 Changeset detected

Latest commit: 3330c83

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@arkenv/nuxt	Patch
@arkenv/build	Patch
@arkenv/nextjs	Patch

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

pkg-pr-new · 2026-06-27T14:26:37Z

Open in StackBlitz

arkenv

npm i https://pkg.pr.new/arkenv@1248

@arkenv/build

npm i https://pkg.pr.new/@arkenv/build@1248

@arkenv/bun-plugin

npm i https://pkg.pr.new/@arkenv/bun-plugin@1248

@arkenv/cli

npm i https://pkg.pr.new/@arkenv/cli@1248

@arkenv/fumadocs-ui

npm i https://pkg.pr.new/@arkenv/fumadocs-ui@1248

@arkenv/nextjs

npm i https://pkg.pr.new/@arkenv/nextjs@1248

@arkenv/nuxt

npm i https://pkg.pr.new/@arkenv/nuxt@1248

@arkenv/vite-plugin

npm i https://pkg.pr.new/@arkenv/vite-plugin@1248

commit: 3330c83

arkenv-bot · 2026-06-27T14:27:03Z

📦 Bundle Size Report

Package	Size	Limit	Diff	Status
`@arkenv/nextjs`	`1.32 kB`	`2.93 kB`	`0.0%`	✅
`@arkenv/nextjs/shared`	`1.15 kB`	`1.46 kB`	`0.0%`	✅
`@arkenv/nextjs/server`	`1.21 kB`	`1.95 kB`	`0.0%`	✅
`@arkenv/nextjs/client`	`1.21 kB`	`1.95 kB`	`0.0%`	✅
`@arkenv/nextjs/config`	`3.46 kB`	`3.91 kB`	`+0.6%`	✅

✅ All size limits passed!

arkenv-bot · 2026-06-27T14:29:06Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (Asia/Almaty)
arkenv	Ready	Preview, Comment	Jun 29 2026, 9:24 PM (Asia/Almaty)

pullfrog

Important

The new flat createEnv(schema, options) overload in @arkenv/nuxt declares an options.runtimeEnv field, but createEnvInternal never consumes it, so passing runtimeEnv silently does nothing. This is inconsistent with @arkenv/nextjs and is likely to mislead users migrating to the flat layout.

Reviewed changes — Nuxt flat-layout support and build-package extraction refactor.

Add a createEnv(schema, options) overload to @arkenv/nuxt (universal, server, client, and shared entry points) with flat-layout TypeScript inference.
Refactor @arkenv/build so extractKeys accepts a framework public prefix and detects both the legacy nested layout and the flat layout.
Update @arkenv/nextjs to use the shared @arkenv/build extraction logic instead of duplicating the parser.
Update the Nuxt module to recognize "flat" as a layout option and emit a one-time deprecation warning for "simple".
Add runtime and build-time extraction tests for the Nuxt flat layout.

ℹ️ Nitpicks

.changeset/nuxt-flat-layout.md bumps both packages as patch, but the changeset adds a new public API (createEnv(schema, options) and a new module layout option). Under semantic-versioning conventions that usually warrants minor.
packages/nuxt/src/type-regression.test-d.ts only exercises the legacy createEnv({ server, client, shared }) signature; consider adding type-level coverage for the new flat overload so inference regressions are caught by pnpm --filter @arkenv/nuxt typecheck.

Note: 1 inline comment(s) dropped because they did not anchor to lines inside the PR diff:

packages/nuxt/src/type-regression.test-d.ts:88 (RIGHT) — line 88 (RIGHT) is not inside a diff hunk

^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}

pullfrog

✅ No new issues found.

Reviewed changes — the new commits address the prior review feedback by wiring runtimeEnv through the Nuxt flat layout, adding flat type-regression coverage, and bumping the changeset severity.

Wired options.runtimeEnv into createEnvInternal for both legacy and flat layouts, with validation that every key exists in the schema.
Added runtime tests in packages/nuxt/src/index.test.ts verifying that runtimeEnv overrides process.env and rejects unknown keys.
Added a flat-layout type-regression test in packages/nuxt/src/type-regression.test-d.ts covering exposeToClient and runtimeEnv inference.
Bumped @arkenv/nuxt to minor in .changeset/nuxt-flat-layout.md.

^{｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}

…pelling update

pullfrog

✅ No new issues found.

Reviewed changes — the new commits refactor the shared build-time extraction parsers and tidy the changeset/comment wording.

Refactored @arkenv/build parsers to a regex token scanner — extractCallArguments, extractBlock, parseBlockKeys, and extractArkenvBlock now share a single tokenizer that skips comments, strings, and template literals while matching braces/parens/brackets. @arkenv/nextjs and @arkenv/nuxt now delegate to extractKeys with their public prefixes (NEXT_PUBLIC_ / NUXT_PUBLIC_).
Switched the changeset severity to patch and updated the description to use "typesafe" instead of "type-safe".
Updated Nuxt strict entry points to pass strictLayout: "client" / "server" so the flat schema is interpreted as client-only/server-only in those dedicated entry points.
Standardized "typesafe" spelling in Nuxt entry-point JSDoc comments.

ℹ️ `@arkenv/build` extractors have no dedicated tests

The extraction logic is now the single implementation behind both Next.js and Nuxt codegen, but packages/build has no unit tests of its own. Both framework packages cover it indirectly through their config tests, and those pass. Adding focused tests for the token scanner directly in @arkenv/build would make future parser changes cheaper to validate and catch cross-framework edge cases earlier.

^{｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}

pullfrog

✅ No new issues found.

Reviewed changes — the latest commit cleans up lint-in-expression patterns in the shared parser and suppresses intentional deprecation warnings.

Refactored regex token-scanner loops in packages/build/src/index.ts to avoid assignment-in-expression patterns.
Added // biome-ignore lint/suspicious/noConsole annotations before deliberate dev-time deprecation warnings in packages/nuxt/src/create-env.ts and packages/nuxt/src/module.ts.

No new issues found; existing Nuxt/Next.js config and runtime tests pass, and @arkenv/nuxt typecheck passes.

^{｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}

@yamcodes

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 dev, this PR will be updated. # Releases ## @arkenv/build@0.0.2 ### Patch Changes - #### Add flat layout support to `@arkenv/nuxt` _[`#1248`](#1248) [`be8034f`](be8034f) [@yamcodes](https://github.com/yamcodes)_ Introduce flat layout schema support and typesafe `createEnv` signature overloads to `@arkenv/nuxt`. - Add `"flat"` layout mode to `ModuleOptions` and auto-detect it when a single `env.ts` file is configured. - Emit a deprecation warning in development when using the legacy `"simple"` layout option. - Expose flat `createEnv(schema, options)` overload with type inference for `NUXT_PUBLIC_` prefixes, `NODE_ENV`, and custom `exposeToClient` variables. ## @arkenv/nextjs@0.1.3 ### Patch Changes <details><summary>Updated 1 dependency</summary> <small> [`be8034f`](be8034f) </small> - `@arkenv/build@0.0.2` </details> ## @arkenv/nuxt@0.0.2 ### Patch Changes - #### Add flat layout support to `@arkenv/nuxt` _[`#1248`](#1248) [`be8034f`](be8034f) [@yamcodes](https://github.com/yamcodes)_ Introduce flat layout schema support and typesafe `createEnv` signature overloads to `@arkenv/nuxt`. - Add `"flat"` layout mode to `ModuleOptions` and auto-detect it when a single `env.ts` file is configured. - Emit a deprecation warning in development when using the legacy `"simple"` layout option. - Expose flat `createEnv(schema, options)` overload with type inference for `NUXT_PUBLIC_` prefixes, `NODE_ENV`, and custom `exposeToClient` variables. <details><summary>Updated 1 dependency</summary> <small> [`be8034f`](be8034f) </small> - `@arkenv/build@0.0.2` </details> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

fix: tackle issue #1242

6502e62

yamcodes added enhancement New feature or improvement @arkenv/nuxt Issues or Pull Requests involving the Nuxt integration for ArkEnv labels Jun 27, 2026

yamcodes linked an issue Jun 27, 2026 that may be closed by this pull request

feat(nuxt): core API & flat layout support #1242

Closed

6 tasks

github-actions Bot added docs Adds or changes documentation, or acts as documentation in and of itself tests This issue or PR is about adding, removing or changing tests @arkenv/nextjs Issues or Pull Requests involving the Next.js integration for ArkEnv labels Jun 27, 2026

pullfrog Bot requested changes Jun 27, 2026

View reviewed changes

Comment thread packages/nuxt/src/index.ts

fix: address PR reviews for runtimeEnv support and flat type check

95d34ee

pullfrog Bot approved these changes Jun 27, 2026

View reviewed changes

fix: simplify changeset description and bump type to patch

91318c3

yamcodes commented Jun 27, 2026

View reviewed changes

Comment thread packages/build/src/index.ts

yamcodes commented Jun 27, 2026

View reviewed changes

Comment thread packages/build/src/index.ts

fix: address PR reviews for regex token-scanner parser refactor and s…

545efeb

…pelling update

pullfrog Bot approved these changes Jun 27, 2026

View reviewed changes

yamcodes added 2 commits June 29, 2026 21:13

fix: address all biome check lint errors and add ignore overrides

12af19e

test: add dedicated extractor tests in packages/build

3330c83

pullfrog Bot approved these changes Jun 29, 2026

View reviewed changes

yamcodes merged commit be8034f into dev Jun 29, 2026
22 checks passed

yamcodes deleted the 1242-featnuxt-core-api-flat-layout-support branch June 29, 2026 16:29

arkenv-bot Bot mentioned this pull request Jun 29, 2026

Version Packages #1252

Merged

yamcodes mentioned this pull request Jul 11, 2026

Forward-port flat layout from dev to v1 branch #1298

Closed

8 tasks

Navigation Menu

feat(nuxt): core API & flat layout support - #1248

feat(nuxt): core API & flat layout support#1248
yamcodes merged 6 commits into
devfrom
1242-featnuxt-core-api-flat-layout-support

yamcodes commented Jun 27, 2026

Uh oh!

changeset-bot Bot commented Jun 27, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Jun 27, 2026 •

edited

Loading

Uh oh!

arkenv-bot Bot commented Jun 27, 2026 •

edited

Loading

Uh oh!

arkenv-bot Bot commented Jun 27, 2026 •

edited

Loading

Uh oh!

pullfrog Bot left a comment

Uh oh!

Uh oh!

pullfrog Bot left a comment

Uh oh!

Uh oh!

Uh oh!

pullfrog Bot left a comment

Uh oh!

pullfrog Bot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

yamcodes commented Jun 27, 2026

Changes:

Uh oh!

changeset-bot Bot commented Jun 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

pkg-pr-new Bot commented Jun 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

arkenv-bot Bot commented Jun 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📦 Bundle Size Report

Uh oh!

arkenv-bot Bot commented Jun 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pullfrog Bot left a comment

Choose a reason for hiding this comment

ℹ️ Nitpicks

Uh oh!

Uh oh!

pullfrog Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

pullfrog Bot left a comment

Choose a reason for hiding this comment

ℹ️ @arkenv/build extractors have no dedicated tests

Uh oh!

pullfrog Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

changeset-bot Bot commented Jun 27, 2026 •

edited

Loading

pkg-pr-new Bot commented Jun 27, 2026 •

edited

Loading

arkenv-bot Bot commented Jun 27, 2026 •

edited

Loading

arkenv-bot Bot commented Jun 27, 2026 •

edited

Loading

ℹ️ `@arkenv/build` extractors have no dedicated tests