envzod 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 1.1.0
+
+### CLI
+- `npx envzod check` — validate env before deployment, works in CI/CD pipelines
+- `--env` flag — specify custom env file path (default: `.env`)
+- `--config` flag — specify custom config file path (default: `envzod.config`)
+- TypeScript config support — CLI auto-detects `envzod.config.ts` before `.js`
+
+### Next.js helper (`envzod/next`)
+- `createNextEnv` — Next.js-specific helper with server/client schema split
+- `server` schema — auto-sourced from `process.env`, no key repetition needed
+- `client` schema — explicit `runtimeEnv` only for `NEXT_PUBLIC_*` keys (webpack/Turbopack requirement)
+- `bail` option — call `process.exit(1)` instead of throwing to avoid Next.js stack trace noise (default: `false`)
+
+### Improvements
+- Validation errors now include full field details in the thrown error — visible in Next.js error overlays, not just terminal
+
+---
+
+## 1.0.1
+
+- Fixed Next.js support — added `source` option to explicitly pass `process.env` keys
+- Without `source`, Next.js/Turbopack could not statically inline `NEXT_PUBLIC_*` vars on the client side
+
+---
+
 ## 1.0.0 — Initial Release
 
 - `createEnv(schema, options?)` — validate environment variables against a Zod schema

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2024 Sridhar-C-25
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2024 Sridhar-C-25
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -32,20 +32,20 @@ yarn add envzod
 
 ```ts
 // env.ts
-import { createEnv } from 'envzod'
-import { z } from 'zod'
+import { createEnv } from "envzod";
+import { z } from "zod";
 
 export const env = createEnv({
   DATABASE_URL: z.string().url(),
   PORT: z.coerce.number().default(3000),
-  NODE_ENV: z.enum(['development', 'test', 'production']),
+  NODE_ENV: z.enum(["development", "test", "production"]),
   JWT_SECRET: z.string().min(32),
-})
+});
 
 // Fully typed — no casting needed
-env.PORT         // number
-env.DATABASE_URL // string
-env.NODE_ENV     // "development" | "test" | "production"
+env.PORT;         // number
+env.DATABASE_URL; // string
+env.NODE_ENV;     // "development" | "test" | "production"
 ```
 
 ---
@@ -56,7 +56,7 @@ When validation fails, `envzod` prints a clear, readable error and throws:
 
 ```
 ╔════════════════════════════════════════════╗
-║  zod-env: Invalid Environment             ║
+║  zod-env: Invalid Environment              ║
 ╚════════════════════════════════════════════╝
 
   ✗ DATABASE_URL
@@ -74,6 +74,8 @@ When validation fails, `envzod` prints a clear, readable error and throws:
   Fix the above and restart your server.
 ```
 
+The thrown error includes the full formatted details — visible in Next.js error overlays, server logs, and CI output.
+
 ---
 
 ## Options
@@ -88,92 +90,130 @@ const env = createEnv(schema, {
 
   // Called with structured errors before throwing — use for Sentry, logging, etc.
   onError: (errors) => {
-    Sentry.captureException(new Error('Invalid env'), { extra: { errors } })
+    Sentry.captureException(new Error("Invalid env"), { extra: { errors } });
   },
-})
+});
 ```
 
 ### `onError` signature
 
 ```ts
 type EnvValidationError = {
-  field: string
-  message: string
-  received: string | undefined
-}
+  field: string;
+  message: string;
+  received: string | undefined;
+};
 ```
 
 ---
 
 ## Framework Examples
 
-### Next.js (App Router)
+### Next.js (App Router) — `envzod/next`
+
+Use `createNextEnv` from `envzod/next` for the best Next.js experience:
+
+- **Server vars** are auto-sourced from `process.env` — no repetition needed
+- **Client vars** (`NEXT_PUBLIC_*`) still require explicit `process.env.KEY` references — this is a hard webpack/Turbopack requirement, not a library limitation
 
-> **Important:** Next.js only inlines `NEXT_PUBLIC_*` vars when referenced **explicitly** (e.g. `process.env.NEXT_PUBLIC_FOO`). Passing the whole `process.env` object doesn't work on the client side. Always use the `source` option and list each var individually.
+**Step 1 — Define schema once in `envzod.config.ts`:**
 
 ```ts
-// src/env.ts
-import { createEnv } from 'envzod'
-import { z } from 'zod'
+// envzod.config.ts
+import { z } from "zod";
 
-export const env = createEnv(
-  {
-    // Server-only vars
-    DATABASE_URL: z.string().url(),
-    JWT_SECRET: z.string().min(32),
-    NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
+export const server = {
+  DATABASE_URL: z.string().url(),
+  JWT_SECRET: z.string().min(32),
+  NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
+};
 
-    // Public vars (accessible in browser)
-    NEXT_PUBLIC_API_URL: z.string().url(),
-  },
-  {
-    // Must explicitly list each var so Next.js/Turbopack can statically inline them
-    source: {
-      DATABASE_URL: process.env.DATABASE_URL,
-      JWT_SECRET: process.env.JWT_SECRET,
-      NODE_ENV: process.env.NODE_ENV,
-      NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL,
-    },
-    verbose: process.env.NODE_ENV === 'development',
+export const client = {
+  NEXT_PUBLIC_API_URL: z.string().url(),
+  NEXT_PUBLIC_APP_NAME: z.string().default("My App"),
+};
+```
+
+**Step 2 — Wire it up in `env.ts`:**
+
+```ts
+// env.ts
+import { createNextEnv } from "envzod/next";
+import { server, client } from "./envzod.config";
+
+export const env = createNextEnv({
+  server,
+  client,
+  runtimeEnv: {
+    // Only NEXT_PUBLIC_* vars needed here — server vars auto-sourced
+    NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL,
+    NEXT_PUBLIC_APP_NAME: process.env.NEXT_PUBLIC_APP_NAME,
   },
-)
+  verbose: process.env.NODE_ENV === "development",
+  // bail: true  — clean process.exit(1) on error instead of throwing
+});
+```
+
+**Step 3 — CLI also reads `envzod.config.ts` automatically:**
+
+```bash
+npx envzod check
 ```
 
+#### `createNextEnv` options
+
+| Option       | Type                              | Default   | Description                                              |
+| ------------ | --------------------------------- | --------- | -------------------------------------------------------- |
+| `server`     | `EnvSchema`                       | `{}`      | Server-only vars, auto-sourced from `process.env`        |
+| `client`     | `EnvSchema`                       | `{}`      | Client vars, must all start with `NEXT_PUBLIC_`          |
+| `runtimeEnv` | `{ [K in keyof client]: string }` | required  | Explicit `process.env.KEY` refs for each client key      |
+| `verbose`    | `boolean`                         | `false`   | Log success summary                                      |
+| `onError`    | `(errors) => void`                | —         | Called with structured errors before throwing            |
+| `bail`       | `boolean`                         | `false`   | Call `process.exit(1)` instead of throwing — no Next.js stack trace noise |
+
+---
+
 ### Express
 
 ```ts
 // src/env.ts
-import { createEnv } from 'envzod'
-import { z } from 'zod'
+import { createEnv } from "envzod";
+import { z } from "zod";
 
-export const env = createEnv({
-  PORT: z.coerce.number().default(3000),
-  DATABASE_URL: z.string().url(),
-  JWT_SECRET: z.string().min(32),
-}, {
-  verbose: process.env.NODE_ENV === 'development',
-})
+export const env = createEnv(
+  {
+    PORT: z.coerce.number().default(3000),
+    DATABASE_URL: z.string().url(),
+    JWT_SECRET: z.string().min(32),
+  },
+  {
+    verbose: process.env.NODE_ENV === "development",
+  },
+);
 
 // app.ts
-import { env } from './env'
-app.listen(env.PORT)
+import { env } from "./env";
+app.listen(env.PORT);
 ```
 
 ### Bun
 
 ```ts
 // env.ts
-import { createEnv } from 'envzod'
-import { z } from 'zod'
+import { createEnv } from "envzod";
+import { z } from "zod";
 
-export const env = createEnv({
-  PORT: z.coerce.number().default(3000),
-  DATABASE_URL: z.string().url(),
-  JWT_SECRET: z.string().min(32),
-}, {
-  source: Bun.env,
-  verbose: Bun.env.NODE_ENV === 'development',
-})
+export const env = createEnv(
+  {
+    PORT: z.coerce.number().default(3000),
+    DATABASE_URL: z.string().url(),
+    JWT_SECRET: z.string().min(32),
+  },
+  {
+    source: Bun.env,
+    verbose: Bun.env.NODE_ENV === "development",
+  },
+);
 ```
 
 ---
@@ -183,29 +223,87 @@ export const env = createEnv({
 `envzod` uses the `InferEnv<T>` utility type to derive the return type from your schema. No manual type annotations needed.
 
 ```ts
-import type { InferEnv } from 'envzod'
-import { z } from 'zod'
+import type { InferEnv } from "envzod";
+import { z } from "zod";
 
 const schema = {
   PORT: z.coerce.number(),
-  NODE_ENV: z.enum(['development', 'production']),
-}
+  NODE_ENV: z.enum(["development", "production"]),
+};
 
-type Env = InferEnv<typeof schema>
+type Env = InferEnv<typeof schema>;
 // { PORT: number; NODE_ENV: "development" | "production" }
 ```
 
 ---
 
+## CLI — `npx envzod check`
+
+Validate your env before deploying — great for CI/CD pipelines.
+
+**Supports both `.ts` and `.js` config files** — TypeScript config is auto-detected.
+
+**1. Create `envzod.config.ts` (or `.js`) in your project root:**
+
+```ts
+// envzod.config.ts
+import { z } from "zod";
+
+export default {
+  DATABASE_URL: z.string().url(),
+  PORT: z.coerce.number().default(3000),
+  NODE_ENV: z.enum(["development", "test", "production"]),
+};
+```
+
+Or CommonJS:
+
+```js
+// envzod.config.js
+const { z } = require("zod");
+
+module.exports = {
+  DATABASE_URL: z.string().url(),
+  PORT: z.coerce.number().default(3000),
+  NODE_ENV: z.enum(["development", "test", "production"]),
+};
+```
+
+**2. Run the check:**
+
+```bash
+npx envzod check
+```
+
+**Options:**
+
+```bash
+npx envzod check --env .env.production   # custom env file (default: .env)
+npx envzod check --config my.config      # custom config file (tries .ts then .js)
+```
+
+**Add to CI (GitHub Actions example):**
+
+```yaml
+- name: Validate environment
+  run: npx envzod check --env .env.production
+```
+
+---
+
 ## vs t3-env
 
-| Feature | envzod | t3-env |
-|---|---|---|
-| Framework | Universal | Next.js focused |
-| Setup | `createEnv(schema)` | Separate client/server schemas |
-| Dependencies | zod only | Next.js types + more |
-| Bundle | CJS + ESM | ESM only |
-| Error output | Pretty box | Zod default |
+| Feature          | envzod                          | t3-env                         |
+| ---------------- | ------------------------------- | ------------------------------ |
+| Framework        | Universal                       | Next.js focused                |
+| Basic setup      | `createEnv(schema)`             | Separate client/server schemas |
+| Next.js helper   | `createNextEnv` via `envzod/next` | Built-in                     |
+| Server/client split | Yes — `server` + `client`    | Yes — `server` + `client`      |
+| Source repetition | Server: none, Client: required | Always required (`runtimeEnv`) |
+| CLI check        | `npx envzod check` (TS + JS)   | None                           |
+| Dependencies     | zod only                        | Next.js types + more           |
+| Bundle           | CJS + ESM                       | ESM only                       |
+| Error output     | Pretty box with field details   | Zod default                    |
 
 ---