RFC(v1): Virtual codegen modules for Next.js strict layout (env/ stays user-authored only)

[yamcodes]

Summary

Exploratory vision for v1: keep the user-facing strict layout tree small and intentional, and move Next.js codegen artifacts out of env/ into tool-owned virtual modules under root .arkenv/.

Supersedes the file-based direction in #1304 as the preferred end state. Related: #1307 / #1401 (Nuxt virtual alias), #1403 (Next auto-extend track), ADR 0016, #1109 (dot-folder rule — not reversed).

Problem

Next.js strict layout still requires manual server wiring and puts generated factories beside editable schemas:

import arkenv from "@arkenv/nextjs/server";
import { env as clientEnv } from "./client";

export const env = arkenv(
  { DATABASE_URL: "string" },
  { extends: [clientEnv] },
);

#1304 proposed generating server.gen.ts beside env.gen.ts to fix that. Design review found deeper issues with putting more machine output under env/:

• env.gen.ts + server.gen.ts naming is asymmetric and easy to misread
• generated/ + .gen is redundant marking
• Colocating *.gen.ts next to editable schemas invites misclicks
• env/internal/ + env/generated/ together makes env/ feel like a mini-package, not an env validator
• Awkward-path guardrails (internal/shared.ts) are a weak substitute for an explicit client-exposure API

Locked decisions

1. Phase out internal/shared.ts (concept shift)

Adapt the flat-layout exposeToClient: [...] array into strict layout. Client-safe variables are tagged on the single source of truth (e.g. env/server.ts) instead of living in a separately importable shared file. Exact transition / relationship to #1448 still under human mapping (ready for human).

2. On-disk location: root .arkenv/ ✅

Generated factories write to a root .arkenv/ directory (gitignored; regenerate via withArkEnv / arkenv generate).

Not .next/cache/arkenv — Next’s .next/cache is an ephemeral build-performance cache (CI Build Caching); the ecosystem routinely wipes .next / .next/cache to troubleshoot. Not node_modules/.arkenv/ — brittle for monorepos / edge (Prisma’s lesson).

Meta-framework parallel: .nuxt/, .svelte-kit/ are first-class tool codegen dirs; host bundler caches are a different job.

#1109 defense (canonical): #1109 forbids importable code in dot-folders. Because public access is via virtual specifiers, .arkenv/ is cache-only backing — users never import from ".arkenv/...". This does not reverse #1109.

Scaffolding: CLI must add .arkenv/ to .gitignore.

3. Module resolution via withArkEnv

Codegen outputs physical files under .arkenv/; withArkEnv maps the public specifier to that path and injects Webpack resolve.alias + Turbopack resolveAlias. User next.config stays clean.

4. CI typecheck

Scaffold "postinstall": "arkenv generate" so tsc --noEmit succeeds before next build runs the plugin.

5. Security guardrail

Generated server artifacts inject "server-only"; so accidental Client Component imports fail the App Router build.

6. No generated server factory (ADR 0016)

Server DX follows #1403 (Nuxt-style auto-extend on @arkenv/nextjs/server), not arkenv/gen/server / server.gen.ts. Client virtual factory remains for Next’s runtimeEnv tax only.

Vision (v1) — directional

User-facing tree (target)

env/
  client.ts
  server.ts   # exposeToClient: [...] tags client-safe keys (shared file phased out)

Machine-owned client factory

// env/client.ts
import arkenv from "arkenv/gen/client"; // exact specifier TBD — see open questions

Desired properties:

• Users almost never open generated files (.arkenv/ collapsed / searchable-exclude friendly)
• One “generated” marker (tool directory), no .gen suffix in the public import path
• Client factory keeps today’s baked runtimeEnv behavior
• Server auto-extend owned by (v1) Auto-extend client env in Next.js strict layout via virtual module alias #1403 / package entry, not a second generated factory

Relationship to #1307 / #1403

	#1307 / #1401 (Nuxt)	#1403 (Next auto-extend)	This RFC (client factory placement)
Mechanism	Virtual alias → user’s env/client.ts	Same pattern on Next	Virtual import → generated client factory in .arkenv/
What it solves	Manual extends	Manual extends	runtimeEnv codegen out of env/
Blocks the other?	No	No	No

Relationship to #1304

#1304 closed as superseded for end-state (in-tree server factory). This RFC + #1403 are the preferred v1 shape.

Open questions (still ready for human)

1. Specifier namespace — lean package-style (arkenv/gen/client or @arkenv/nextjs/gen/client); exact string deferred to implementation PR. Optional cross-host rename with Nuxt #arkenv/… later.
2. Flat layout — same virtual surface, or keep a simpler single-module story?
3. Migration — soft compat for ./generated/env.gen imports in v1, or hard cut?
4. exposeToClient ↔ strict transition — how fully it replaces internal/shared / Make env/internal/shared.ts optional in strict layout (dev/v0) #1448; docs & scaffold mapping.

On-disk location — locked: root .arkenv/ (gitignore + regenerate).
Generated server factory / cross-host gen/server — out: #1403 + ADR 0016.

Non-goals (for this RFC)

• Implementing Generate server.gen.ts factory to eliminate manual extends: [clientEnv] in Next.js strict layout #1304’s in-tree server.gen.ts as the final design
• Blocking or redesigning (v1) Auto-extend client env in Nuxt strict layout via virtual module alias #1307 / feat(v1): Auto-extend client env in Nuxt strict layout via virtual module alias #1401
• Nesting factories under .next/cache or node_modules/
• Nuxt file-based codegen
• Locking the exact virtual specifier string before the PR

Success sketch

• Strict env/ is user-authored only (no sibling *.gen.ts)
• Generated client factory lives in .arkenv/, reached only via virtual import
• #1109 remains intact (cache-only + virtual import, not hidden app modules)
• Next strict server needs no manual extends (via (v1) Auto-extend client env in Next.js strict layout via virtual module alias #1403)
• Docs/CLI scaffolds teach virtual imports, .gitignore for .arkenv/, and postinstall generate

[pullfrog]

This run croaked 😵

The workflow encountered an error before any progress could be reported. Please check the link below for details.

  ^{｜ Rerun failed job ➔ ｜ View workflow run ｜ via Pullfrog ｜ 𝕏}

[yamcodes]

This was generated by AI during triage.

Agent Brief

Category: enhancement (RFC)
Summary: Design v1 Next.js strict-layout codegen so factories are virtual/tool-owned modules, keeping env/ user-authored only (client / server / internal/shared)

Why ready for human (not agent):
This is an exploratory architecture RFC. Specifier namespace, cache location, commit policy, migration hardness, and cross-host alignment with #1307 all need maintainer judgment before anyone implements. Do not treat the sketch below as an implementation contract until those calls are made.

Current behavior:

• Next.js strict layout codegen writes an in-tree client factory (env/generated/env.gen.ts) with baked runtimeEnv
• env/server.ts still manually imports @arkenv/nextjs/server and extends: [clientEnv]
• Generate server.gen.ts factory to eliminate manual extends: [clientEnv] in Next.js strict layout #1304 proposed a second in-tree factory (server.gen.ts) — parked pending this design
• (v1) Auto-extend client env in Nuxt strict layout via virtual module alias #1307 (Nuxt) adds a virtual #arkenv/client-env alias so server auto-extends without file codegen — additive, intended for dev

Desired behavior (directional — subject to open questions in the issue body):

• User-facing strict tree stays env/{client,server,internal/shared}.ts only
• Next.js registers virtual imports (e.g. arkenv/gen/client + arkenv/gen/server) from withArkEnv
• Server virtual factory eliminates manual extends: [clientEnv]
• Client virtual factory preserves today’s runtimeEnv codegen semantics
• Artifacts live in a tool-owned location, not beside editable schemas
• (v1) Auto-extend client env in Nuxt strict layout via virtual module alias #1307 remains unblocked; this RFC may later converge naming across hosts

Key interfaces (to design, not yet implement):

• Public virtual module specifiers for client/server factories
• withArkEnv / codegen registration surface for those specifiers
• Server factory contract: auto-include client env; explicit extends escape hatch TBD
• Compatibility story for existing ./generated/env.gen imports

Acceptance criteria (for closing the RFC / promoting to implementation):

• Maintainer decisions recorded for: specifier namespace, on-disk cache location, commit-vs-gitignore, flat-layout story, migration hardness
• Explicit statement whether Generate server.gen.ts factory to eliminate manual extends: [clientEnv] in Next.js strict layout #1304 is superseded, deferred as interim, or closed as wontfix-for-end-state
• Relationship to (v1) Auto-extend client env in Nuxt strict layout via virtual module alias #1307 documented (complementary precursor vs future rename/convergence)
• Follow-up implementation issue(s) opened with concrete acceptance criteria once judgment calls land — or this issue upgraded to ready for agent with a narrowed brief

Out of scope (until RFC resolves):

• Implementing in-tree server.gen.ts from Generate server.gen.ts factory to eliminate manual extends: [clientEnv] in Next.js strict layout #1304 as the v1 end state
• Blocking (v1) Auto-extend client env in Nuxt strict layout via virtual module alias #1307 on dev
• Removing or publicizing env/internal/shared
• Nuxt file-based codegen

[yamcodes]

This was generated by AI during triage.

Learning from #1307 / #1401 (Nuxt → this RFC)

#1401 does not need changes for this RFC — but it does teach a design simplification we should bake into the v1 judgment calls.

Key insight: Next’s hard codegen constraint is client runtimeEnv static inlining, not server-side extends: [clientEnv]. Nuxt already solved the server DX without a generated server factory:

• virtual alias → user’s env/client.ts
• @arkenv/nuxt/server auto-extends when extends is omitted
• user import stays the package entry; explicit extends remains the escape hatch

Revised directional preference for this RFC:

1. Server: copy the Nuxt model on Next (@arkenv/nextjs/server + client-env alias / strict-layout flag). Do not assume we need arkenv/gen/server (or server.gen.ts) just to bake extends.
2. Client: keep a virtual/tool-owned factory only where Next uniquely needs it (baked runtimeEnv) — e.g. arkenv/gen/client or equivalent — so artifacts still leave the user-facing env/ tree.
3. Reuse mechanics from feat(v1): Auto-extend client env in Nuxt strict layout via virtual module alias #1401 where they fit: fail-fast if client.ts missing, typed typeof import("…"), custom unresolved-alias errors, build-time injection where the bundler alias isn’t visible (Jiti), explicit extends overrides auto-merge.
4. Host-idiomatic specifiers > one global name for now; optional cross-host rename later.

Nuxt ← Next (non-blocking): treat #arkenv/client-env as a stable internal contract, not an app import surface (same privacy instinct as env/internal/shared). No change required in #1401 before merge to dev.

Open question to resolve in this RFC: confirm whether Next server can fully follow Nuxt’s auto-extend path, or whether some Next-specific constraint still forces a generated server factory.

[yamcodes]

This was generated by AI during triage.

Scope update (aligned with ADR 0016)

Decision recorded in docs/adr/0016-strict-layout-complexity-budget.md.

Drop as centerpiece: generated server factory (server.gen.ts / arkenv/gen/server) only to bake extends. #1304 closed as superseded.

Still in scope for this RFC (judgment / v1 as needed):

1. Whether Next client codegen should move to tool-owned / virtual modules so env/ stays user-authored only (client.ts, server.ts, internal/shared.ts)
2. Specifier / cache / commit policy for that client factory only

Extracted to a separate implementation track: Next.js port of the #1307/#1401 auto-extend pattern (cheap slice, additive — prefer dev if non-breaking). See the follow-up issue linked next.

Open questions in the original body about arkenv/gen/server are obsolete unless package-entry auto-extend proves impossible on Next.

[yamcodes]

Follow-up for the cheap Next auto-extend track: #1403