envzod 1.0.1 → 1.1.1

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 1.1.1
+
+- Fix branding — error output now correctly shows `envzod` instead of `zod-env`
+
+## 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

@@ -1,62 +1,57 @@
 # envzod
 
-Universal, type-safe environment variable validation powered by [Zod](https://zod.dev).
+[![npm](https://img.shields.io/npm/v/envzod)](https://www.npmjs.com/package/envzod)
+[![license](https://img.shields.io/npm/l/envzod)](./LICENSE)
 
-Works with **Next.js, Express, Fastify, Remix, Bun** — any Node.js project.
+**Your app should crash at startup if the env is wrong — not three requests into production.**
 
----
-
-## Why
+`envzod` validates environment variables against a Zod schema at boot time. You get a typed object back. If anything is missing or invalid, it throws with a clear error that tells you exactly what's wrong.
 
-- `process.env` values are all `string | undefined` — no types, no validation
-- Errors surface at runtime deep in your app instead of at startup
-- `envzod` validates your env at boot and gives you a **fully typed object** — no casting needed
+- **Typed** — `env.PORT` is `number`, not `string | undefined`
+- **Fail-fast** — crashes at startup with a readable error, not deep in a request handler
+- **CLI check** — `npx envzod check` validates before deploy, works in CI/CD
+- **Next.js ready** — server/client split via `envzod/next`, no schema duplication
 
 ---
 
 ## Install
 
 ```bash
-npm install envzod
-# or
+npm install envzod   # zod is a peer dep — install it separately if you haven't
 pnpm add envzod
-# or
-yarn add envzod
 ```
 
-> `zod` is a peer dependency and is installed automatically (npm 7+, pnpm, yarn).
-
 ---
 
-## Basic Usage
+## Basic usage
 
 ```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']),
-  JWT_SECRET: z.string().min(32),
-})
-
-// Fully typed — no casting needed
-env.PORT         // number
-env.DATABASE_URL // string
-env.NODE_ENV     // "development" | "test" | "production"
+  PORT:         z.coerce.number().default(3000),
+  NODE_ENV:     z.enum(["development", "test", "production"]),
+  JWT_SECRET:   z.string().min(32),
+});
 ```
 
----
+```ts
+// anywhere in your app
+import { env } from "./env";
 
-## Error Output
+env.PORT          // number  — not string, not undefined
+env.DATABASE_URL  // string
+env.NODE_ENV      // "development" | "test" | "production"
+```
 
-When validation fails, `envzod` prints a clear, readable error and throws:
+If validation fails at startup you get this — not a runtime crash 10 minutes later:
 
 ```
 ╔════════════════════════════════════════════╗
-║  zod-env: Invalid Environment             ║
+║  envzod: Invalid Environment               ║
 ╚════════════════════════════════════════════╝
 
   ✗ DATABASE_URL
@@ -67,131 +62,173 @@ When validation fails, `envzod` prints a clear, readable error and throws:
     String must contain at least 32 character(s)
     Got: "tooshort"
 
-  ✗ NODE_ENV
-    Invalid enum value. Expected 'development' | 'test' | 'production'
-    Got: "prod"
-
   Fix the above and restart your server.
 ```
 
 ---
 
-## Options
+## CLI — validate before you deploy
 
-```ts
-const env = createEnv(schema, {
-  // Custom env source. Defaults to process.env
-  source: myCustomObject,
+```bash
+npx envzod check
+npx envzod check --env .env.production
+npx envzod check --config envzod.config    # tries .ts then .js
+```
 
-  // Log "✅ zod-env: N variables validated" on success (good for dev)
-  verbose: true,
+Reads your `envzod.config.ts` (or `.js`) and validates against your env file. Exits with code 1 on failure.
 
-  // Called with structured errors before throwing — use for Sentry, logging, etc.
-  onError: (errors) => {
-    Sentry.captureException(new Error('Invalid env'), { extra: { errors } })
-  },
-})
+**envzod.config.ts:**
+
+```ts
+import { z } from "zod";
+
+export default {
+  DATABASE_URL: z.string().url(),
+  PORT:         z.coerce.number().default(3000),
+  JWT_SECRET:   z.string().min(32),
+};
 ```
 
-### `onError` signature
+**GitHub Actions:**
 
-```ts
-type EnvValidationError = {
-  field: string
-  message: string
-  received: string | undefined
-}
+```yaml
+- name: Validate environment
+  run: npx envzod check --env .env.production
 ```
 
+The deploy fails here — not after the pod starts and serves broken responses.
+
 ---
 
-## Framework Examples
+## Next.js
+
+Next.js has a hard constraint: `NEXT_PUBLIC_*` variables must be referenced as literal strings (`process.env.NEXT_PUBLIC_FOO`) for webpack/Turbopack to inline them into the client bundle. Dynamic access doesn't work.
 
-### Next.js (App Router)
+`createNextEnv` handles this with a server/client split:
+- **Server vars** — auto-sourced from `process.env`, no repetition
+- **Client vars** — you provide explicit `process.env.KEY` references (unavoidable webpack requirement)
 
-> **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'
+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(),
+};
+```
+
+**Step 2 — wire it in `env.ts`:**
+
+```ts
+import { createNextEnv } from "envzod/next";
+import { server, client } from "./envzod.config";
+
+export const env = createNextEnv({
+  server,
+  client,
+  runtimeEnv: {
+    NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL,
+    // server keys are auto-sourced — only client keys go here
   },
-)
+  verbose: process.env.NODE_ENV === "development",
+  bail: true, // process.exit(1) instead of throwing — avoids Next.js stack trace noise
+});
+```
+
+The CLI reads from `envzod.config.ts` automatically — same schema, no duplication:
+
+```bash
+npx envzod check
 ```
 
-### Express
+---
+
+## Express / Node
 
 ```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),
+  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)
+  JWT_SECRET:   z.string().min(32),
+});
+
+app.listen(env.PORT);
 ```
 
-### Bun
+---
+
+## 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(),
+  },
+  { source: Bun.env },
+);
 ```
 
 ---
 
-## TypeScript
+## Options
+
+### `createEnv(schema, options?)`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `source` | `Record<string, string \| undefined>` | `process.env` | Custom env source |
+| `verbose` | `boolean` | `false` | Log `✅ envzod: N variables validated` on success |
+| `onError` | `(errors: EnvValidationError[]) => void` | — | Called before throwing — use for Sentry, logging |
+
+### `createNextEnv(options)` — `envzod/next`
 
-`envzod` uses the `InferEnv<T>` utility type to derive the return type from your schema. No manual type annotations needed.
+| 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 \| undefined }` | required | Explicit refs for each client key |
+| `verbose` | `boolean` | `false` | Log success summary |
+| `onError` | `(errors: EnvValidationError[]) => void` | — | Called before throwing |
+| `bail` | `boolean` | `false` | Call `process.exit(1)` instead of throwing |
+
+### Error shape
 
 ```ts
-import type { InferEnv } from 'envzod'
-import { z } from 'zod'
+type EnvValidationError = {
+  field:    string;
+  message:  string;
+  received: string | undefined;
+};
+```
+
+---
+
+## TypeScript
+
+```ts
+import type { InferEnv } from "envzod";
+import { z } from "zod";
 
 const schema = {
-  PORT: z.coerce.number(),
-  NODE_ENV: z.enum(['development', 'production']),
-}
+  PORT:     z.coerce.number(),
+  NODE_ENV: z.enum(["development", "production"]),
+};
 
-type Env = InferEnv<typeof schema>
+type Env = InferEnv<typeof schema>;
 // { PORT: number; NODE_ENV: "development" | "production" }
 ```
 
@@ -199,13 +236,19 @@ type Env = InferEnv<typeof schema>
 
 ## 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 |
+Both libraries solve the same problem. Key differences:
+
+| | envzod | t3-env |
+|--|--------|--------|
+| Works outside Next.js | Yes | Limited |
+| Next.js server/client split | `envzod/next` | Built-in |
+| Server var repetition | None (auto-sourced) | Required |
+| Client var repetition | Required (webpack constraint — same for both) | Required |
+| CLI pre-deploy check | Yes — TS + JS config | No |
+| Error output | Formatted box, field-level | Zod default |
+| Output formats | CJS + ESM | ESM only |
+
+The client var repetition (`runtimeEnv`) is a webpack/Turbopack hard requirement — no library can eliminate it.
 
 ---