envzod 1.1.0 → 1.1.1

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 1.1.1
+
+- Fix branding — error output now correctly shows `envzod` instead of `zod-env`
+
 ## 1.1.0
 
 ### CLI

package/README.md

@@ -1,34 +1,29 @@
 # 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
@@ -37,26 +32,26 @@ 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),
+  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"
 ```
 
----
+```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,77 +62,71 @@ 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.
 ```
 
-The thrown error includes the full formatted details — visible in Next.js error overlays, server logs, and CI output.
-
 ---
 
-## Options
-
-```ts
-const env = createEnv(schema, {
-  // Custom env source. Defaults to process.env
-  source: myCustomObject,
-
-  // Log "✅ zod-env: N variables validated" on success (good for dev)
-  verbose: true,
+## CLI — validate before you deploy
 
-  // Called with structured errors before throwing — use for Sentry, logging, etc.
-  onError: (errors) => {
-    Sentry.captureException(new Error("Invalid env"), { extra: { errors } });
-  },
-});
+```bash
+npx envzod check
+npx envzod check --env .env.production
+npx envzod check --config envzod.config    # tries .ts then .js
 ```
 
-### `onError` signature
+Reads your `envzod.config.ts` (or `.js`) and validates against your env file. Exits with code 1 on failure.
+
+**envzod.config.ts:**
 
 ```ts
-type EnvValidationError = {
-  field: string;
-  message: string;
-  received: string | undefined;
+import { z } from "zod";
+
+export default {
+  DATABASE_URL: z.string().url(),
+  PORT:         z.coerce.number().default(3000),
+  JWT_SECRET:   z.string().min(32),
 };
 ```
 
----
+**GitHub Actions:**
 
-## Framework Examples
+```yaml
+- name: Validate environment
+  run: npx envzod check --env .env.production
+```
+
+The deploy fails here — not after the pod starts and serves broken responses.
+
+---
 
-### Next.js (App Router) — `envzod/next`
+## Next.js
 
-Use `createNextEnv` from `envzod/next` for the best Next.js experience:
+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.
 
-- **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
+`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)
 
-**Step 1 — Define schema once in `envzod.config.ts`:**
+**Step 1 — define schema once in `envzod.config.ts`:**
 
 ```ts
-// envzod.config.ts
 import { z } from "zod";
 
 export const server = {
   DATABASE_URL: z.string().url(),
-  JWT_SECRET: z.string().min(32),
-  NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
+  JWT_SECRET:   z.string().min(32),
+  NODE_ENV:     z.enum(["development", "test", "production"]).default("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`:**
+**Step 2 — wire it in `env.ts`:**
 
 ```ts
-// env.ts
 import { createNextEnv } from "envzod/next";
 import { server, client } from "./envzod.config";
 
@@ -145,165 +134,121 @@ 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,
+    // server keys are auto-sourced — only client keys go here
   },
   verbose: process.env.NODE_ENV === "development",
-  // bail: true  — clean process.exit(1) on error instead of throwing
+  bail: true, // process.exit(1) instead of throwing — avoids Next.js stack trace noise
 });
 ```
 
-**Step 3 — CLI also reads `envzod.config.ts` automatically:**
+The CLI reads from `envzod.config.ts` automatically — same schema, no duplication:
 
 ```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
+## Express / Node
 
 ```ts
-// src/env.ts
 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),
+});
 
-// app.ts
-import { env } from "./env";
 app.listen(env.PORT);
 ```
 
-### Bun
+---
+
+## Bun
 
 ```ts
-// env.ts
 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),
-  },
-  {
-    source: Bun.env,
-    verbose: Bun.env.NODE_ENV === "development",
   },
+  { source: Bun.env },
 );
 ```
 
 ---
 
-## TypeScript
-
-`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";
-
-const schema = {
-  PORT: z.coerce.number(),
-  NODE_ENV: z.enum(["development", "production"]),
-};
-
-type Env = InferEnv<typeof schema>;
-// { PORT: number; NODE_ENV: "development" | "production" }
-```
+## Options
 
----
+### `createEnv(schema, options?)`
 
-## CLI — `npx envzod check`
+| 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 |
 
-Validate your env before deploying — great for CI/CD pipelines.
+### `createNextEnv(options)` — `envzod/next`
 
-**Supports both `.ts` and `.js` config files** — TypeScript config is auto-detected.
+| 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 |
 
-**1. Create `envzod.config.ts` (or `.js`) in your project root:**
+### Error shape
 
 ```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"]),
+type EnvValidationError = {
+  field:    string;
+  message:  string;
+  received: string | undefined;
 };
 ```
 
-**2. Run the check:**
-
-```bash
-npx envzod check
-```
+---
 
-**Options:**
+## TypeScript
 
-```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)
-```
+```ts
+import type { InferEnv } from "envzod";
+import { z } from "zod";
 
-**Add to CI (GitHub Actions example):**
+const schema = {
+  PORT:     z.coerce.number(),
+  NODE_ENV: z.enum(["development", "production"]),
+};
 
-```yaml
-- name: Validate environment
-  run: npx envzod check --env .env.production
+type Env = InferEnv<typeof schema>;
+// { PORT: number; NODE_ENV: "development" | "production" }
 ```
 
 ---
 
 ## vs t3-env
 
-| 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                    |
+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.
 
 ---
 

package/dist/cli.js

@@ -35538,7 +35538,7 @@ function pad(text, width) {
 }
 function formatErrors(errors) {
   const lines = [];
-  const title = "  zod-env: Invalid Environment         ";
+  const title = "  envzod: Invalid Environment          ";
   lines.push(`\u2554${"\u2550".repeat(BOX_WIDTH)}\u2557`);
   lines.push(`\u2551${pad(title, BOX_WIDTH)}\u2551`);
   lines.push(`\u255A${"\u2550".repeat(BOX_WIDTH)}\u255D`);
@@ -35555,7 +35555,7 @@ function formatErrors(errors) {
   return lines.join("\n");
 }
 function formatSuccess(count) {
-  return `\u2705 zod-env: ${count} variable${count === 1 ? "" : "s"} validated`;
+  return `\u2705 envzod: ${count} variable${count === 1 ? "" : "s"} validated`;
 }
 
 // src/cli.ts

package/dist/index.js

@@ -9,7 +9,7 @@ function pad(text, width) {
 }
 function formatErrors(errors) {
   const lines = [];
-  const title = "  zod-env: Invalid Environment         ";
+  const title = "  envzod: Invalid Environment          ";
   lines.push(`\u2554${"\u2550".repeat(BOX_WIDTH)}\u2557`);
   lines.push(`\u2551${pad(title, BOX_WIDTH)}\u2551`);
   lines.push(`\u255A${"\u2550".repeat(BOX_WIDTH)}\u255D`);
@@ -26,7 +26,7 @@ function formatErrors(errors) {
   return lines.join("\n");
 }
 function formatSuccess(count) {
-  return `\u2705 zod-env: ${count} variable${count === 1 ? "" : "s"} validated`;
+  return `\u2705 envzod: ${count} variable${count === 1 ? "" : "s"} validated`;
 }
 function validate(schema, source) {
   const shape = {};

package/dist/index.mjs

@@ -7,7 +7,7 @@ function pad(text, width) {
 }
 function formatErrors(errors) {
   const lines = [];
-  const title = "  zod-env: Invalid Environment         ";
+  const title = "  envzod: Invalid Environment          ";
   lines.push(`\u2554${"\u2550".repeat(BOX_WIDTH)}\u2557`);
   lines.push(`\u2551${pad(title, BOX_WIDTH)}\u2551`);
   lines.push(`\u255A${"\u2550".repeat(BOX_WIDTH)}\u255D`);
@@ -24,7 +24,7 @@ function formatErrors(errors) {
   return lines.join("\n");
 }
 function formatSuccess(count) {
-  return `\u2705 zod-env: ${count} variable${count === 1 ? "" : "s"} validated`;
+  return `\u2705 envzod: ${count} variable${count === 1 ? "" : "s"} validated`;
 }
 function validate(schema, source) {
   const shape = {};

package/dist/next.js

@@ -9,7 +9,7 @@ function pad(text, width) {
 }
 function formatErrors(errors) {
   const lines = [];
-  const title = "  zod-env: Invalid Environment         ";
+  const title = "  envzod: Invalid Environment          ";
   lines.push(`\u2554${"\u2550".repeat(BOX_WIDTH)}\u2557`);
   lines.push(`\u2551${pad(title, BOX_WIDTH)}\u2551`);
   lines.push(`\u255A${"\u2550".repeat(BOX_WIDTH)}\u255D`);
@@ -26,7 +26,7 @@ function formatErrors(errors) {
   return lines.join("\n");
 }
 function formatSuccess(count) {
-  return `\u2705 zod-env: ${count} variable${count === 1 ? "" : "s"} validated`;
+  return `\u2705 envzod: ${count} variable${count === 1 ? "" : "s"} validated`;
 }
 function validate(schema, source) {
   const shape = {};

package/dist/next.mjs

@@ -7,7 +7,7 @@ function pad(text, width) {
 }
 function formatErrors(errors) {
   const lines = [];
-  const title = "  zod-env: Invalid Environment         ";
+  const title = "  envzod: Invalid Environment          ";
   lines.push(`\u2554${"\u2550".repeat(BOX_WIDTH)}\u2557`);
   lines.push(`\u2551${pad(title, BOX_WIDTH)}\u2551`);
   lines.push(`\u255A${"\u2550".repeat(BOX_WIDTH)}\u255D`);
@@ -24,7 +24,7 @@ function formatErrors(errors) {
   return lines.join("\n");
 }
 function formatSuccess(count) {
-  return `\u2705 zod-env: ${count} variable${count === 1 ? "" : "s"} validated`;
+  return `\u2705 envzod: ${count} variable${count === 1 ? "" : "s"} validated`;
 }
 function validate(schema, source) {
   const shape = {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "envzod",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Universal, type-safe environment variable validation powered by Zod. Zero config, works everywhere.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",