Refactor Next.js adapter to include defineNextPublicEnv for client-only environment validation, update README for installation instructions, and ensure consistent dependency management across packages. Adjust contributing guidelines for clarity.

Author: hasansmadix

CONTRIBUTING.md

@@ -47,12 +47,12 @@ We **do not** use `NPM_TOKEN` in GitHub Actions. Releases use [npm Trusted Publi
 
 Trusted Publisher is configured **per package** on npm, but the **link is to one GitHub repo + one workflow file** (`release.yml`). For this repo you repeat the same publisher setup for each published package:
 
-| Package               | On npm → Package → Settings → Trusted publishing |
-| --------------------- | -------------------------------------------------- |
-| `@envra/core`         | GitHub: `hasansmadix/envra`, workflow `release.yml` |
-| `@envra/cli`          | same                                               |
-| `@envra/next`         | same                                               |
-| `@envra/eslint-plugin`| same                                               |
+| Package                | On npm → Package → Settings → Trusted publishing    |
+| ---------------------- | --------------------------------------------------- |
+| `@envra/core`          | GitHub: `hasansmadix/envra`, workflow `release.yml` |
+| `@envra/cli`           | same                                                |
+| `@envra/next`          | same                                                |
+| `@envra/eslint-plugin` | same                                                |
 
 All must live under an npm org/user that allows those publishes. The workflow filename must match **exactly** (e.g. `release.yml`, case-sensitive).
 
@@ -66,7 +66,7 @@ The Release job needs:
 
 #### Optional hardening (npm UI)
 
-After Trusted Publishing works, npm recommends restricting classic publish tokens for those packages. See npm docs: *Publishing access* → require 2FA / disallow tokens where appropriate.
+After Trusted Publishing works, npm recommends restricting classic publish tokens for those packages. See npm docs: _Publishing access_ → require 2FA / disallow tokens where appropriate.
 
 ### Release flow
 

README.md

@@ -32,13 +32,13 @@ Not just parsing `process.env`: envra gives you a **contract** (metadata + types
 
 Config breaks in production for boring, repeatable reasons:
 
-| Problem                         | How envra helps                                      |
-| ------------------------------- | ---------------------------------------------------- |
-| Missing or mistyped keys        | Validated schema, clear errors                       |
-| Wrong formats                 | Built-in parsers (URL, int, bool, JSON, …)          |
-| Stale `.env.example`          | `envra sync` from the same schema                    |
-| Leaked secrets to the client  | `secret()`, `serverOnly()`, Next client rules          |
-| Drift between environments    | `envra doctor` (undeclared vars, typos, deprecations) |
+| Problem                      | How envra helps                                       |
+| ---------------------------- | ----------------------------------------------------- |
+| Missing or mistyped keys     | Validated schema, clear errors                        |
+| Wrong formats                | Built-in parsers (URL, int, bool, JSON, …)            |
+| Stale `.env.example`         | `envra sync` from the same schema                     |
+| Leaked secrets to the client | `secret()`, `serverOnly()`, Next client rules         |
+| Drift between environments   | `envra doctor` (undeclared vars, typos, deprecations) |
 
 Other libraries validate well; envra adds **generated docs**, **`.env.example` sync**, **`doctor` hygiene**, and a **rich result object** (`values`, `get`, `has`, `meta`) instead of a plain map.
 
@@ -101,12 +101,12 @@ Export `defineEnv` as `default` / `env`, or export field builders as `schema`, `
 
 **`--json`** on `check` / `doctor` prints machine-readable output for CI.
 
-| Command   | Use case                          |
-| --------- | --------------------------------- |
-| `check`   | CI / preflight — validate merged env |
-| `sync`    | Regenerate `.env.example`         |
-| `docs`    | Regenerate `ENVIRONMENT.md`      |
-| `doctor`  | Undeclared vars, typos, deprecations, profile rules |
+| Command  | Use case                                            |
+| -------- | --------------------------------------------------- |
+| `check`  | CI / preflight — validate merged env                |
+| `sync`   | Regenerate `.env.example`                           |
+| `docs`   | Regenerate `ENVIRONMENT.md`                         |
+| `doctor` | Undeclared vars, typos, deprecations, profile rules |
 
 ---
 
@@ -116,9 +116,11 @@ Export `defineEnv` as `default` / `env`, or export field builders as `schema`, `
 | ---------------------- | ----------------------------------------------------------------- |
 | `@envra/core`          | Schema DSL, `defineEnv`, validation, generators, `doctor` helpers |
 | `@envra/cli`           | `envra` binary                                                    |
-| `@envra/next`          | `defineNextEnv({ server, client, runtimeEnv })`                   |
+| `@envra/next`          | `defineNextEnv` / `defineNextPublicEnv`; **peer** `@envra/core` — see [packages/next/README](packages/next/README.md) |
 | `@envra/eslint-plugin` | `envra/no-process-env`                                            |
 
+Install Next adapter with **`pnpm add @envra/next @envra/core`** so one `@envra/core` version is used (avoids TypeScript `FieldBuilder` clashes). On pnpm, use `overrides` if duplicates appear — [packages/next/README.md](packages/next/README.md#pnpm--duplicate-envracore).
+
 ---
 
 ## Comparison (high level)

examples/next-app-router/package.json

@@ -4,6 +4,7 @@
   "type": "module",
   "dependencies": {
     "@envra/cli": "workspace:*",
+    "@envra/core": "workspace:*",
     "@envra/next": "workspace:*"
   }
 }

packages/next/README.md

@@ -5,14 +5,14 @@ Next.js adapter for [envra](https://github.com/hasansmadix/envra): split **serve
 ## Install
 
 ```bash
-pnpm add @envra/next
+pnpm add @envra/next @envra/core
 # or
-npm install @envra/next
+npm install @envra/next @envra/core
 ```
 
-Peer: `next` >= 14 (optional peer for typing; install `next` in your app).
+**Peers:** `next` >= 14 (optional for typing in non-Next contexts), **`@envra/core` ^0.1.2** (install explicitly so a single copy is used — avoids duplicate `FieldBuilder` types in TypeScript).
 
-## Example
+## Example (full server + client)
 
 ```ts
 import { defineNextEnv, str, url, secret } from "@envra/next";
@@ -28,6 +28,51 @@ export const env = defineNextEnv({
 });
 ```
 
+## Client-only helper (`defineNextPublicEnv`)
+
+Use when you only validate `NEXT_PUBLIC_*` keys and want a module that is safe to import from **Client Components** (no server secrets in that file):
+
+```ts
+import { defineNextPublicEnv, url } from "@envra/next";
+
+export const publicEnv = defineNextPublicEnv({
+  client: {
+    NEXT_PUBLIC_APP_URL: url(),
+  },
+  runtimeEnv: process.env,
+});
+```
+
+For secrets and server-only variables, keep a separate module with `import "server-only"` and `defineNextEnv` (or `defineEnv` from `@envra/core`).
+
+## Next.js App Router: server vs client modules
+
+1. **Server env** — e.g. `lib/env.ts` with `import "server-only"` at the top, then `defineNextEnv` with both `server` and `client` (or server-only schema via `@envra/core`).
+2. **Public env** — e.g. `lib/env-public.ts` **without** `server-only`, using `defineNextPublicEnv` or only the `client` block patterns above.
+3. **Do not** import the server env module from code that is bundled for the client (Client Components, or shared `services/` / `lib/` pulled in by them). Use `publicEnv` for anything that needs env inside client bundles.
+
+## pnpm / duplicate `@envra/core`
+
+If TypeScript reports that `FieldBuilder` types are incompatible (*separate declarations of a private property*), you likely have **two versions** of `@envra/core` installed. Fix with a single version, for example:
+
+```json
+{
+  "pnpm": {
+    "overrides": {
+      "@envra/core": "0.1.2"
+    }
+  }
+}
+```
+
+## Re-exports
+
+`@envra/next` re-exports common builders (`str`, `int`, `secret`, …), **`FieldBuilder`**, **`InferSchema`**, and `defineEnv` from `@envra/core` so you can use **one import path** in Next apps:
+
+```ts
+import { defineNextEnv, str, type InferSchema } from "@envra/next";
+```
+
 ## Documentation
 
 [github.com/hasansmadix/envra](https://github.com/hasansmadix/envra)

packages/next/package.json

@@ -38,7 +38,8 @@
     "node": ">=18"
   },
   "peerDependencies": {
-    "next": ">=14"
+    "next": ">=14",
+    "@envra/core": "^0.1.2"
   },
   "peerDependenciesMeta": {
     "next": {
@@ -49,10 +50,8 @@
     "build": "tsup",
     "test": "vitest run"
   },
-  "dependencies": {
-    "@envra/core": "workspace:*"
-  },
   "devDependencies": {
+    "@envra/core": "workspace:*",
     "@types/node": "^22.10.2",
     "tsup": "^8.3.5",
     "typescript": "~5.7.2",

packages/next/src/define-next-env.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest'
-import { defineNextEnv } from './define-next-env'
+import { defineNextEnv, defineNextPublicEnv } from './define-next-env'
 import { str, url, secret } from '@envra/core'
 
 describe('defineNextEnv', () => {
@@ -22,7 +22,7 @@ describe('defineNextEnv', () => {
     expect(() =>
       defineNextEnv({
         server: {},
-        client: { NEXT_PUBLIC_X: secret(str()) } as never,
+        client: { NEXT_PUBLIC_X: secret(str()) },
         runtimeEnv: { NODE_ENV: 'test', NEXT_PUBLIC_X: 'a' },
       }),
     ).toThrow(/secret/)
@@ -38,3 +38,26 @@ describe('defineNextEnv', () => {
     ).toThrow(/NEXT_PUBLIC_/)
   })
 })
+
+describe('defineNextPublicEnv', () => {
+  it('validates client-only keys', () => {
+    const env = defineNextPublicEnv({
+      client: { NEXT_PUBLIC_APP_URL: url() },
+      runtimeEnv: {
+        NODE_ENV: 'test',
+        NEXT_PUBLIC_APP_URL: 'https://app.example',
+      },
+      profile: 'test',
+    })
+    expect(env.values.NEXT_PUBLIC_APP_URL).toBe('https://app.example')
+  })
+
+  it('rejects secret on client', () => {
+    expect(() =>
+      defineNextPublicEnv({
+        client: { NEXT_PUBLIC_X: secret(str()) },
+        runtimeEnv: { NODE_ENV: 'test', NEXT_PUBLIC_X: 'a' },
+      }),
+    ).toThrow(/secret/)
+  })
+})

packages/next/src/define-next-env.ts

@@ -1,19 +1,36 @@
-import { defineEnv, type DefineEnvOptions } from '@envra/core'
-import type { FieldBuilder } from '@envra/core'
-import type { InferSchema } from '@envra/core'
-import type { EnvraResult } from '@envra/core'
+import {
+  defineEnv,
+  type DefineEnvOptions,
+  type EnvraResult,
+  type FieldBuilder,
+  type InferSchema,
+} from '@envra/core'
+
+/**
+ * Schema object accepted by `defineNextEnv` / `defineNextPublicEnv`.
+ * Uses `FieldBuilder<any>` so concrete builders like `FieldBuilder<string | undefined>`
+ * stay assignable (avoids class variance issues with `FieldBuilder<unknown>`).
+ */
+export type NextEnvSchema = Record<string, FieldBuilder<any>>
 
 export interface DefineNextEnvOptions<
-  S extends Record<string, FieldBuilder<unknown>>,
-  C extends Record<string, FieldBuilder<unknown>>,
+  S extends NextEnvSchema,
+  C extends NextEnvSchema,
 > extends Pick<DefineEnvOptions, 'onValidationError'> {
   server: S
   client: C
   runtimeEnv: Record<string, string | undefined>
   profile?: string
 }
 
-function assertClientField(key: string, builder: FieldBuilder<unknown>): void {
+export interface DefineNextPublicEnvOptions<C extends NextEnvSchema>
+  extends Pick<DefineEnvOptions, 'onValidationError'> {
+  client: C
+  runtimeEnv: Record<string, string | undefined>
+  profile?: string
+}
+
+function assertClientField(key: string, builder: FieldBuilder<any>): void {
   const def = builder.build()
   if (def.secret || def.visibility === 'server') {
     throw new Error(
@@ -28,13 +45,13 @@ function assertClientField(key: string, builder: FieldBuilder<unknown>): void {
 }
 
 export function defineNextEnv<
-  S extends Record<string, FieldBuilder<unknown>>,
-  C extends Record<string, FieldBuilder<unknown>>,
+  S extends NextEnvSchema,
+  C extends NextEnvSchema,
 >(
   opts: DefineNextEnvOptions<S, C>,
 ): EnvraResult<InferSchema<S> & InferSchema<C>> {
   for (const [key, builder] of Object.entries(opts.client)) {
-    assertClientField(key, builder as FieldBuilder<unknown>)
+    assertClientField(key, builder)
   }
 
   const merged = {
@@ -48,3 +65,19 @@ export function defineNextEnv<
     onValidationError: opts.onValidationError,
   }) as EnvraResult<InferSchema<S> & InferSchema<C>>
 }
+
+/**
+ * Client-only Next.js env: same rules as the `client` block in `defineNextEnv`, without a server schema.
+ * Safe to import from modules used by Client Components (no server secrets in this path).
+ */
+export function defineNextPublicEnv<C extends NextEnvSchema>(
+  opts: DefineNextPublicEnvOptions<C>,
+): EnvraResult<InferSchema<C>> {
+  return defineNextEnv({
+    server: {},
+    client: opts.client,
+    runtimeEnv: opts.runtimeEnv,
+    profile: opts.profile,
+    onValidationError: opts.onValidationError,
+  }) as EnvraResult<InferSchema<C>>
+}

packages/next/src/index.ts

@@ -1,4 +1,10 @@
-export { defineNextEnv, type DefineNextEnvOptions } from './define-next-env'
+export {
+  defineNextEnv,
+  defineNextPublicEnv,
+  type DefineNextEnvOptions,
+  type DefineNextPublicEnvOptions,
+  type NextEnvSchema,
+} from './define-next-env'
 export {
   defineEnv,
   str,
@@ -13,4 +19,6 @@ export {
   secret,
   type EnvraResult,
   type DefineEnvOptions,
+  type FieldBuilder,
+  type InferSchema,
 } from '@envra/core'