fix: (v1) Remove framework /shared exports; keep /client and /server for strict layout by yamcodes · Pull Request #1297 · yamcodes/arkenv

yamcodes · 2026-07-11T13:03:34Z

Remove the ./shared subpath export from @arkenv/nextjs and @arkenv/nuxt. Strict-layout internal schema modules now import type from core arkenv. /client and /server subpath exports are unchanged.

Changes

Add ADR 0014 documenting the export-surface decision
Delete packages/nextjs/src/shared.ts and packages/nuxt/src/shared.ts
Remove ./shared from package exports and size-limit configs
Update docs, examples, playgrounds, CLI scaffolding, and tests
Add major changeset for v1 release

Test plan

pnpm run typecheck
pnpm run test (758 tests passed)
pnpm run fix

Made with Cursor

changeset-bot · 2026-07-11T13:03:38Z

🦋 Changeset detected

Latest commit: fbfecc5

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

This PR includes changesets to release 2 packages

Name	Type
@arkenv/nextjs	Major
@arkenv/nuxt	Major

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-07-11T13:04:44Z

Open in StackBlitz

arkenv

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

@arkenv/build

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

@arkenv/bun-plugin

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

@arkenv/core

npm i https://pkg.pr.new/@arkenv/core@1297

@arkenv/fumadocs-ui

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

@arkenv/nextjs

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

@arkenv/nuxt

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

@arkenv/standard

npm i https://pkg.pr.new/@arkenv/standard@1297

@arkenv/vite-plugin

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

commit: fbfecc5

arkenv-bot · 2026-07-11T13:05:14Z

📦 Bundle Size Report

Package	Size	Limit	Diff	Status
`@arkenv/nextjs`	`1.31 kB`	`2.93 kB`	`-0.8%`	✅
`@arkenv/nextjs/server`	`1.2 kB`	`1.95 kB`	`-0.8%`	✅
`@arkenv/nextjs/client`	`1.2 kB`	`1.95 kB`	`-0.8%`	✅
`@arkenv/nextjs/config`	`3.46 kB`	`3.91 kB`	`0.0%`	✅

✅ All size limits passed!

arkenv-bot · 2026-07-11T13:08:03Z

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

Project	Deployment	Review	Updated (Asia/Almaty)
arkenv	Ready	Preview, Comment	Jul 11 2026, 7:31 PM (Asia/Almaty)

pullfrog

Caution

The new mock-server-only alias target is not emitted in the published build, which breaks strict-layout build-time validation. Details are inline on packages/nextjs/src/config.ts.

Reviewed changes — remove the ./shared subpath exports from @arkenv/nextjs and @arkenv/nuxt so strict-layout internal schema modules import type from core arkenv, while keeping /client and /server unchanged.

Drop ./shared exports from packages/nextjs/package.json and packages/nuxt/package.json (exports and size-limit entries).
Delete packages/nextjs/src/shared.ts and packages/nuxt/src/shared.ts and remove them from the tsdown entry arrays.
Update packages/nextjs/src/config.ts to alias server-only and ./script* to a new mock-server-only.ts stub.
Update docs, examples, playgrounds, CLI templates, and tests to import type from arkenv instead of @arkenv/{nextjs,nuxt}/shared.
Add ADR 0014 documenting the flat versus strict layout import mental model and the export-surface decision.
Add a major changeset for @arkenv/nextjs and @arkenv/nuxt.

ℹ️ Dead `isShared` branch in `create-env.ts`

Both framework createEnvInternal implementations still branch on context?.isShared, but the only call sites that passed isShared: true were deleted with shared.ts. The branch is now unreachable and should be removed in a follow-up so the internal boundary routing (strictLayout only) stays aligned with the documented mental model.

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

pullfrog

✅ The incremental change resolves the missing mock-server-only build artifact.

Reviewed changes since 742edc0 — one commit that adds src/mock-server-only.ts to the @arkenv/nextjs build entries.

Add src/mock-server-only.ts to packages/nextjs/tsdown.config.ts so the jiti alias target is emitted into dist/ for published builds.

I verified the build locally: dist/mock-server-only.js, .d.ts, and source maps are now produced alongside the other entry points.

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

pullfrog · 2026-07-11T13:35:09Z

✅ No new issues found.

Reviewed changes — removed the dead isShared routing branch from @arkenv/nextjs and @arkenv/nuxt createEnvInternal now that the ./shared subpath exports are deleted.

Removed isShared from createEnvInternal in packages/nextjs/src/create-env.ts and packages/nuxt/src/create-env.ts.
Simplified the server-only key guard by dropping the shared-entry-point check in both packages.
This resolves the prior Pullfrog feedback about the dead branch; the missing mock-server-only build artifact was already fixed in 404a44e1.

ℹ️ Nitpicks

The stale comment about being "explicitly inside the shared entry point" in packages/nextjs/src/create-env.ts (lines 191–192) and packages/nuxt/src/create-env.ts (lines 178–179) should be tightened now that isShared and ./shared are gone.

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

pullfrog · 2026-07-11T13:54:39Z

Run failed. View the logs →

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

Co-authored-by: Cursor <cursoragent@cursor.com>

Drop unreachable isShared context handling after removing the /shared subpath entry points, keeping strictLayout-only boundary routing. Co-authored-by: Cursor <cursoragent@cursor.com>

Remove stale shared-entry-point wording from createEnvInternal after dropping the /shared subpath exports. Co-authored-by: Cursor <cursoragent@cursor.com>

v1 still publishes ./standard/shared entry points that rely on isShared context routing. Restore that path while the ArkType ./shared exports remain removed. Co-authored-by: Cursor <cursoragent@cursor.com>

Add vfsRoot, baseUrl, and framework env path mappings so twoslash tests and docs snippets resolve @/env/client and ~~/env/client correctly. Co-authored-by: Cursor <cursoragent@cursor.com>

…lient-and-server-for-strict-layout

pullfrog

✅ No new issues found.

Reviewed changes since 404a44e — the author restored the isShared context routing in both framework arkenvInternal implementations so the ./standard/shared entry points continue to work, added twoslash path aliases for strict-layout documentation snippets, and fixed the test format for the shared schema import assertion.

Restored isShared routing in packages/nextjs/src/arkenv-internal.ts and packages/nuxt/src/arkenv-internal.ts after temporarily removing it, preserving ./standard/shared behavior while keeping the ArkType ./shared exports removed.
Added strict-layout path mappings to apps/www/lib/twoslash-options.ts so documentation snippets resolve @/env/client and ~~/env/client correctly.
Updated apps/www/lib/twoslash-options.test.ts to pass the twoslash options into the strict-layout resolution cases.
Autofix formatting in packages/arkenv/src/features/scaffold/planner.test.ts and docs/adr/0014-framework-subpath-exports.md.

I verified the changes locally: @arkenv/nextjs (66 tests), @arkenv/nuxt (16 tests), and the www twoslash-options test (3 tests) all pass after a fresh pnpm run build:packages.

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

Strict-layout fixtures now import type from @arkenv/core and drop the stale @arkenv/nuxt/shared jiti alias pointing at deleted shared.ts. Co-authored-by: Cursor <cursoragent@cursor.com>

pullfrog

✅ No new issues found.

Reviewed changes since 0ef55158 — one commit that updates the Nuxt validation tests after the /shared export removal.

Update packages/nuxt/src/validation.test.ts to remove the deleted @arkenv/nuxt/shared alias and import type from @arkenv/core in the strict-layout fixture snippets.

I verified the Nuxt test suite passes after a fresh pnpm run build:packages.

^{｜ 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 v1, this PR will be updated. ⚠️

⚠️

⚠️ `v1` is currently in **pre mode** so this branch has prereleases rather than normal releases. If you want to exit prereleases, run `changeset pre exit` on `v1`. ⚠️

⚠️

⚠️ # Releases ## @arkenv/nextjs@1.0.0-alpha.6 ### Major Changes - #### Remove framework `/shared` subpath exports _[`#1297`](#1297) [`68ed78e`](68ed78e) [@yamcodes](https://github.com/yamcodes)_ Drop the `./shared` export from `@arkenv/nextjs` and `@arkenv/nuxt`. Strict-layout internal schema modules should import `type` from `@arkenv/core` instead. `/client` and `/server` subpath exports are unchanged. **BREAKING CHANGE:** Remove `@arkenv/nextjs/shared` and `@arkenv/nuxt/shared` subpath exports. Migration: ```ts // Before import { type } from "@arkenv/nextjs/shared"; // After import { type } from "@arkenv/core"; ``` Import mental model: - **Flat layout:** `import arkenv from "@arkenv/nextjs"` (or `@arkenv/nuxt`) - **Strict layout:** `@arkenv/nextjs/client` and `@arkenv/nextjs/server` (or Nuxt equivalents) - **Internal schema modules:** `import { type } from "@arkenv/core"` ### Patch Changes <details><summary>Updated 1 dependency</summary> <small> [`90ac1e1`](90ac1e1) </small> - `@arkenv/build@0.0.2-alpha.0` </details> ## @arkenv/nuxt@1.0.0-alpha.4 ### Major Changes - #### Remove framework `/shared` subpath exports _[`#1297`](#1297) [`68ed78e`](68ed78e) [@yamcodes](https://github.com/yamcodes)_ Drop the `./shared` export from `@arkenv/nextjs` and `@arkenv/nuxt`. Strict-layout internal schema modules should import `type` from `@arkenv/core` instead. `/client` and `/server` subpath exports are unchanged. **BREAKING CHANGE:** Remove `@arkenv/nextjs/shared` and `@arkenv/nuxt/shared` subpath exports. Migration: ```ts // Before import { type } from "@arkenv/nextjs/shared"; // After import { type } from "@arkenv/core"; ``` Import mental model: - **Flat layout:** `import arkenv from "@arkenv/nextjs"` (or `@arkenv/nuxt`) - **Strict layout:** `@arkenv/nextjs/client` and `@arkenv/nextjs/server` (or Nuxt equivalents) - **Internal schema modules:** `import { type } from "@arkenv/core"` ### Minor Changes - #### Align Nuxt flat layout across CLI, examples, and build resolution _[`#1299`](#1299) [`90ac1e1`](90ac1e1) [@yamcodes](https://github.com/yamcodes)_ Forward-port flat layout support for Nuxt on v1 by aligning CLI scaffolding, build-time validation, runtime proxy behavior, and `@arkenv/build` layout resolution. Usage: ```ts // nuxt.config.ts export default defineNuxtConfig({ modules: ["@arkenv/nuxt/module"], arkenv: { layout: "flat" }, }); ``` ```ts // env.ts import arkenv from "@arkenv/nuxt"; export const env = arkenv({ DATABASE_URL: "string", NUXT_PUBLIC_API_URL: "string", NODE_ENV: "'development' | 'production' | 'test' = 'development'", }); ``` - `arkenv` init wizard presents "Flat (Recommended)" for Nuxt and scaffolds a flat `env.ts` - `@arkenv/build` `resolveLayout()` accepts `"flat"` as an alias for the single-file layout mode - Nuxt examples and playgrounds use flat layout conventions ### Patch Changes <details><summary>Updated 1 dependency</summary> <small> [`90ac1e1`](90ac1e1) </small> - `@arkenv/build@0.0.2-alpha.0` </details> ## arkenv@1.0.0-alpha.4 ### Minor Changes - #### Align Nuxt flat layout across CLI, examples, and build resolution _[`#1299`](#1299) [`90ac1e1`](90ac1e1) [@yamcodes](https://github.com/yamcodes)_ Forward-port flat layout support for Nuxt on v1 by aligning CLI scaffolding, build-time validation, runtime proxy behavior, and `@arkenv/build` layout resolution. Usage: ```ts // nuxt.config.ts export default defineNuxtConfig({ modules: ["@arkenv/nuxt/module"], arkenv: { layout: "flat" }, }); ``` ```ts // env.ts import arkenv from "@arkenv/nuxt"; export const env = arkenv({ DATABASE_URL: "string", NUXT_PUBLIC_API_URL: "string", NODE_ENV: "'development' | 'production' | 'test' = 'development'", }); ``` - `arkenv` init wizard presents "Flat (Recommended)" for Nuxt and scaffolds a flat `env.ts` - `@arkenv/build` `resolveLayout()` accepts `"flat"` as an alias for the single-file layout mode - Nuxt examples and playgrounds use flat layout conventions ### Patch Changes - #### Generate `.env` and `.env.example` files and configure pnpm approved builds whitelisting during initialization _[`#1292`](#1292) [`3cdbac9`](3cdbac9) [@yamcodes](https://github.com/yamcodes)_ - Generate default `.env` and `.env.example` files during initialization if they do not exist to prevent Node/tsx `--env-file` boot crashes. - Parse existing `.env` file and securely strip all values to generate `.env.example` when `.env.example` is missing to avoid leaking user credentials to source control. - Automatically check and update `.gitignore` in existing projects to ignore `.env` and `.env.local` files. - Skip overwriting pre-existing files when their scaffolding action is set to `"create"`. - Configure pnpm build whitelisting for `esbuild` during project scaffolding if `pnpm` is the detected package manager. This writes the `onlyBuiltDependencies` field to `package.json` and creates or updates a `pnpm-workspace.yaml` file with the `allowBuilds` configuration before running the installation phase. - Add a runtime guardrail to throw a friendly error when the CLI is imported as a library to guide upgrading library users to `@arkenv/core`. ## @arkenv/build@0.0.2-alpha.0 ### Patch Changes - #### Align Nuxt flat layout across CLI, examples, and build resolution _[`#1299`](#1299) [`90ac1e1`](90ac1e1) [@yamcodes](https://github.com/yamcodes)_ Forward-port flat layout support for Nuxt on v1 by aligning CLI scaffolding, build-time validation, runtime proxy behavior, and `@arkenv/build` layout resolution. Usage: ```ts // nuxt.config.ts export default defineNuxtConfig({ modules: ["@arkenv/nuxt/module"], arkenv: { layout: "flat" }, }); ``` ```ts // env.ts import arkenv from "@arkenv/nuxt"; export const env = arkenv({ DATABASE_URL: "string", NUXT_PUBLIC_API_URL: "string", NODE_ENV: "'development' | 'production' | 'test' = 'development'", }); ``` - `arkenv` init wizard presents "Flat (Recommended)" for Nuxt and scaffolds a flat `env.ts` - `@arkenv/build` `resolveLayout()` accepts `"flat"` as an alias for the single-file layout mode - Nuxt examples and playgrounds use flat layout conventions --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

yamcodes linked an issue Jul 11, 2026 that may be closed by this pull request

(v1) Remove framework /shared exports; keep /client and /server for strict layout #1296

Closed

16 tasks

yamcodes added @arkenv/cli Issues or Pull Requests involving the ArkEnv CLI @arkenv/nextjs Issues or Pull Requests involving the Next.js integration for ArkEnv @arkenv/nuxt Issues or Pull Requests involving the Nuxt integration for ArkEnv labels Jul 11, 2026

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 playground Issues or Pull Requests concerning a playground. (Found in the `apps/playgrounds/` directory) labels Jul 11, 2026

pullfrog Bot reviewed Jul 11, 2026

View reviewed changes

Comment thread packages/nextjs/src/config.ts

pullfrog Bot approved these changes Jul 11, 2026

View reviewed changes

yamcodes and others added 5 commits July 11, 2026 16:04

fix: tackle issue #1296

c6b3fd2

Co-authored-by: Cursor <cursoragent@cursor.com>

refactor(nextjs,nuxt): remove dead isShared routing branch

d302d58

Drop unreachable isShared context handling after removing the /shared subpath entry points, keeping strictLayout-only boundary routing. Co-authored-by: Cursor <cursoragent@cursor.com>

docs(nextjs,nuxt): tighten server-only key guard comment

9ff37bc

Remove stale shared-entry-point wording from createEnvInternal after dropping the /shared subpath exports. Co-authored-by: Cursor <cursoragent@cursor.com>

fix(nextjs,nuxt): keep isShared routing for standard/shared exports

c42ca0b

v1 still publishes ./standard/shared entry points that rely on isShared context routing. Restore that path while the ArkType ./shared exports remain removed. Co-authored-by: Cursor <cursoragent@cursor.com>

fix(www): configure twoslash path aliases for strict layout docs

7071b3c

Add vfsRoot, baseUrl, and framework env path mappings so twoslash tests and docs snippets resolve @/env/client and ~~/env/client correctly. Co-authored-by: Cursor <cursoragent@cursor.com>

yamcodes force-pushed the 1296-v1-remove-framework-shared-exports-keep-client-and-server-for-strict-layout branch from 31977ae to 7071b3c Compare July 11, 2026 14:08

yamcodes changed the base branch from dev to v1 July 11, 2026 14:08

github-actions Bot added arkenv Changes to the `arkenv` npm package. and removed @arkenv/cli Issues or Pull Requests involving the ArkEnv CLI labels Jul 11, 2026

autofix-ci Bot and others added 2 commits July 11, 2026 14:09

[autofix.ci] apply automated fixes

0ef5515

Merge branch 'v1' into 1296-v1-remove-framework-shared-exports-keep-c…

e80b338

…lient-and-server-for-strict-layout

pullfrog Bot approved these changes Jul 11, 2026

View reviewed changes

fix(nuxt): update validation tests after removing /shared export

fbfecc5

Strict-layout fixtures now import type from @arkenv/core and drop the stale @arkenv/nuxt/shared jiti alias pointing at deleted shared.ts. Co-authored-by: Cursor <cursoragent@cursor.com>

pullfrog Bot approved these changes Jul 11, 2026

View reviewed changes

yamcodes merged commit 68ed78e into v1 Jul 11, 2026
22 checks passed

yamcodes deleted the 1296-v1-remove-framework-shared-exports-keep-client-and-server-for-strict-layout branch July 11, 2026 14:54

arkenv-bot Bot mentioned this pull request Jul 11, 2026

Version Packages (alpha) #1293

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix: (v1) Remove framework /shared exports; keep /client and /server for strict layout#1297

fix: (v1) Remove framework /shared exports; keep /client and /server for strict layout#1297
yamcodes merged 8 commits into
v1from
1296-v1-remove-framework-shared-exports-keep-client-and-server-for-strict-layout

yamcodes commented Jul 11, 2026

Uh oh!

changeset-bot Bot commented Jul 11, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Jul 11, 2026 •

edited

Loading

Uh oh!

arkenv-bot Bot commented Jul 11, 2026 •

edited

Loading

Uh oh!

arkenv-bot Bot commented Jul 11, 2026 •

edited

Loading

Uh oh!

pullfrog Bot left a comment

Uh oh!

Uh oh!

pullfrog Bot left a comment

Uh oh!

pullfrog Bot commented Jul 11, 2026

Uh oh!

pullfrog Bot commented Jul 11, 2026

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 Jul 11, 2026

Changes

Test plan

Uh oh!

changeset-bot Bot commented Jul 11, 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 Jul 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

arkenv-bot Bot commented Jul 11, 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 Jul 11, 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

ℹ️ Dead isShared branch in create-env.ts

Uh oh!

Uh oh!

pullfrog Bot left a comment

Choose a reason for hiding this comment

Uh oh!

pullfrog Bot commented Jul 11, 2026

ℹ️ Nitpicks

Uh oh!

pullfrog Bot commented Jul 11, 2026

Uh oh!

pullfrog Bot left a comment

Choose a reason for hiding this comment

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 Jul 11, 2026 •

edited

Loading

pkg-pr-new Bot commented Jul 11, 2026 •

edited

Loading

arkenv-bot Bot commented Jul 11, 2026 •

edited

Loading

arkenv-bot Bot commented Jul 11, 2026 •

edited

Loading

ℹ️ Dead `isShared` branch in `create-env.ts`