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.

Supersedes the file-based direction in #1304 as the preferred end state. Related precursor: #1307 (Nuxt virtual alias — ships on dev, additive).

Problem

Next.js strict layout still requires manual server wiring:

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
• Flattening internal/shared.ts → env/shared.ts is a DX footgun (invites @/env/shared imports); app code should only import from client or server

Vision (v1)

User-facing tree (unchanged intent)

env/
  client.ts
  server.ts
  internal/
    shared.ts   # private composition only — not a public import surface

internal/ stays on purpose: awkward path as a guardrail so shared schema is not consumed directly.

Machine-owned factories (new)

Codegen writes outside the schema tree (e.g. .arkenv/ or equivalent tool cache) and is exposed via stable virtual imports registered by withArkEnv:

// env/client.ts
import arkenv from "arkenv/gen/client";

// env/server.ts
import arkenv from "arkenv/gen/server";

export const env = arkenv({
  DATABASE_URL: "string",
});

Desired properties:

• Users almost never open generated files (folder collapsed / searchable-exclude friendly)
• One “generated” marker (tool directory), no .gen suffix in the public import path
• Server factory bakes in extends: [clientEnv] (same DX goal as Generate server.gen.ts factory to eliminate manual extends: [clientEnv] in Next.js strict layout #1304 / (v1) Auto-extend client env in Nuxt strict layout via virtual module alias #1307)
• Client factory keeps today’s baked runtimeEnv behavior
• Flat layout gets the same pattern (arkenv/gen or arkenv/gen/env) rather than generated/env.gen.ts in-tree

Exact specifier spelling (arkenv/gen/* vs #arkenv/* vs @arkenv/nextjs/gen/*), on-disk cache location, and commit-vs-gitignore policy are open judgment calls for this RFC.

Relationship to #1307

Does not contradict — sets the stage.

	#1307 (Nuxt, → dev)	This RFC (Next.js, → v1)
Mechanism	Virtual module alias	Virtual module (+ tool-owned artifacts)
What the alias points at	User’s env/client.ts	Generated client/server factories
Import in server.ts	Still @arkenv/nuxt/server	Prefer arkenv/gen/server (or similar)
Compatibility	Additive / non-breaking	Likely breaking import-path migration
Files on disk in env/	None added	None added (goal)

#1307 proves the host-plugin can own resolution and auto-merge without committing factories next to schemas. v1 extends that idea to Next.js, where we still need some generated factory (for runtimeEnv), but it should not live in the user-facing tree.

Ship #1307 on dev as-is. Do not block it on this RFC. When this lands in v1, consider converging naming (#arkenv/… vs arkenv/gen/…) across hosts as a separate consistency pass.

Relationship to #1304

#1304 remains the original problem statement and a valid interim file-based approach if we ever need a smaller step. This issue is the preferred v1 end state. Prefer implementing this over #1304’s server.gen.ts under env/generated/.

Open questions (human judgment)

1. Specifier namespace — arkenv/gen/client, #arkenv/gen/client, or @arkenv/nextjs/gen/client?
2. On-disk location — .arkenv/, node_modules/.arkenv/, or another cache? Committed for CI types, or always regenerated in withArkEnv / build?
3. Flat layout — same virtual surface, or keep a simpler single-module story?
4. Migration — soft compat for ./generated/env.gen imports in v1, or hard cut?
5. Cross-host alignment — how closely should Next.js match (v1) Auto-extend client env in Nuxt strict layout via virtual module alias #1307’s #arkenv/client-env auto-extend model vs explicit generated server factory imports?

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 before it merges to dev
• Removing env/internal/shared.ts or making shared a public import
• Nuxt file-based codegen

Success sketch

• Strict env/ contains only user-authored modules (client, server, internal/*)
• Next.js strict server.ts needs no manual extends: [clientEnv]
• Generated artifacts are not siblings of editable schema files
• Docs/CLI scaffolds teach virtual imports as canonical

[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