{
  "compilerOptions": {
    "target": "ES2020",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "paths": {
      "zod": ["./src/zod/index.ts"],
      "zod/v3": ["./src/zod/v3/index.ts"],
      "zod/mini": ["./src/zod/mini/index.ts"],
      "zod/locales": ["./src/zod/locales/index.ts"]
    }
  }
}

3. Import from the path alias (or directly from the file):

import { z } from "zod";
// or directly:
import { z } from "./src/zod/index.ts";

4. No environment variables are required.

5. For the mini build (smaller bundle), import from zod/mini or src/zod/mini/index.ts.

Public API

z

import { z } from "./src/zod/index.ts";
// z is the full Zod v4 classic namespace

The z object is the primary namespace. Access all schema constructors (z.string(), z.object(), z.array(), etc.) and utilities through it. Use this for the standard developer experience identical to the published zod npm package.

default export

import z from "./src/zod/index.ts";
// Identical to the named `z` export

The default export is the same z namespace, allowing import z from "zod" style usage. Interchangeable with the named export; prefer whichever matches your team's conventions.

v3 compatibility namespace

import { z } from "./src/zod/v3/index.ts";
import z3 from "./src/zod/v3/index.ts";

The v3 entry provides the classic Zod 3.x API. Use this when migrating a codebase that relies on v3 semantics or when a dependency requires the v3 interface.

mini build

import { z } from "./src/zod/mini/index.ts";

The mini build exposes tree-shakeable schema constructors from v4/mini/external.ts. Use it in bundle-size-sensitive environments such as edge functions or browser SPAs.

Working examples

Scenario - Basic object validation

Parse and validate an incoming API request body with a strict schema, collecting all validation errors before returning.

import { z } from "./src/zod/index.ts";

const UserSchema = z.object({
  id: z.string().uuid(),
  name: z.string().min(1).max(100),
  age: z.number().int().min(0).max(150),
  email: z.string().email(),
});

type User = z.infer<typeof UserSchema>;

function parseUser(raw: unknown): User {
  return UserSchema.parse(raw);
}

try {
  const user = parseUser({
    id: "123e4567-e89b-12d3-a456-426614174000",
    name: "Alice",
    age: 30,
    email: "alice@example.com",
  });
  console.log(user);
} catch (err) {
  console.error(err);
}

Scenario - Safe parse with error handling

Use safeParse to avoid throwing, then inspect validation issues programmatically.

import { z } from "./src/zod/index.ts";

const ProductSchema = z.object({
  sku: z.string().regex(/^[A-Z]{3}-\d{4}$/),
  price: z.number().positive(),
  tags: z.array(z.string()).max(10),
});

const result = ProductSchema.safeParse({
  sku: "ABC-1234",
  price: -5,
  tags: ["sale", "featured"],
});

if (!result.success) {
  for (const issue of result.error.issues) {
    console.log(`Field: ${issue.path.join(".")} - ${issue.message}`);
  }
} else {
  console.log("Valid product:", result.data);
}

Scenario - v3 compatibility layer

Integrate with a legacy codebase that expects Zod v3 schemas.

import z3 from "./src/zod/v3/index.ts";

const AddressSchema = z3.object({
  street: z3.string(),
  city: z3.string(),
  zip: z3.string().length(5),
});

type Address = z3.infer<typeof AddressSchema>;

const result = AddressSchema.safeParse({
  street: "123 Main St",
  city: "Springfield",
  zip: "62701",
});

if (result.success) {
  console.log("Parsed address:", result.data);
} else {
  console.error(result.error.format());
}

Scenario - Localized error messages

Apply a non-English locale so validation errors are returned in the target language.

import { z } from "./src/zod/index.ts";
import { de } from "./src/zod/v4/locales/de.ts";
import { setGlobalConfig } from "./src/zod/v4/core/config.ts";

// Set German locale globally
setGlobalConfig({ locale: de });

const Schema = z.object({
  username: z.string().min(3),
});

const result = Schema.safeParse({ username: "ab" });
if (!result.success) {
  console.log(result.error.issues[0].message); // message in German
}

File walkthrough

• index.ts - Top-level entry; imports and re-exports the v4 classic external API; exposes z as both named and default export.
• locales/index.ts - Thin barrel that forwards all locale exports from v4/locales/index.ts.
• mini/index.ts - Entry for the mini build; mirrors the top-level entry but sources from v4/mini/external.ts for smaller bundles.
• v3/index.ts - Self-contained v3 API entry; exposes the full Zod 3.x surface via z and a default export.
• v3/ZodError.ts - Defines the ZodError class used throughout the v3 runtime.
• v3/errors.ts - Error formatting and message generation helpers for v3.
• v3/external.ts - The public API boundary for v3; aggregates all v3 exports.
• v3/standard-schema.ts - Implements the Standard Schema spec interface for v3 schemas.
• v3/types.ts - All v3 schema class definitions and type inference utilities.
• v3/helpers/enumUtil.ts - Enum value extraction utilities.
• v3/helpers/errorUtil.ts - Error message construction helpers.
• v3/helpers/parseUtil.ts - Low-level parse result types and helpers.
• v3/helpers/partialUtil.ts - Deep partial type transformation utilities.
• v3/helpers/typeAliases.ts - Convenience type aliases used internally.
• v3/helpers/util.ts - General internal utility functions.
• v3/locales/en.ts - English error message map for v3.
• v4/index.ts - v4 entry; re-exports the classic build and default-exports z4.
• v4/classic/ - Full v4 API: schema constructors, coercion, ISO date/time helpers, JSON Schema output, error formatting, and the external public surface.
• v4/core/ - Parsing engine, registry system, configuration, JSON Schema generation pipeline, Standard Schema compliance, and shared utilities shared between classic and mini builds.
• v4/locales/ - Translation files for 20+ languages; each exports an error map function.
• v4/mini/ - Stripped-down v4 build omitting method chaining sugar for smaller bundle footprint.

Common pitfalls and fixes

• .js extension imports fail in CommonJS projects - The source uses .js extensions for ESM compatibility; set "module": "NodeNext" and "moduleResolution": "NodeNext" in tsconfig.json.
• z.infer produces unknown instead of the expected type - Ensure "strict": true or at minimum "strictNullChecks": true is set in tsconfig.json.
• Locale not applying globally - Call setGlobalConfig before any schema is evaluated, not lazily inside a request handler.
• v3 and v4 ZodError instances are not interchangeable - Import error types from the same version entry (v3/ or v4/) to avoid instanceof mismatches.
• Mini build missing methods like .min() or .email() - The mini build exposes a reduced API; switch to the classic build (index.ts) when you need full method chaining.
• Bundle includes all locales - Import only the specific locale file you need (e.g. v4/locales/de.ts) rather than locales/index.ts to avoid bundling all translations.

Vibe-coding prompt template

I have dropped the Zod validation library source into `src/zod/` in my project.
The integration guide is in `USAGE.md`. The upstream package is `zod`.

Please help me integrate it step by step:
1. Read `USAGE.md` and `src/zod/index.ts` to understand the public API.
2. Update my `tsconfig.json` to add path aliases so `import { z } from "zod"` resolves to `src/zod/index.ts`.
3. Create a validation module in `src/validation/` that uses the `z` namespace from `src/zod/index.ts` to validate my [describe your data shapes here].
4. Add safe-parse wrappers that return typed results and human-readable error messages.
5. If I need v3 compatibility, wire `src/zod/v3/index.ts` and show me how to use it alongside v4.
6. Show me how to apply a locale (e.g. German) using `src/zod/v4/locales/de.ts`.
Do not install any npm packages; all Zod code is already in `src/zod/`.

License and credit

Zod is released under the MIT License. See source/LICENSE if present, or refer to the upstream repository at https://github.com/colinhacks/zod. This block vendors the Zod source as-is; credit belongs to Colin McDonnell and the Zod contributors.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

전체 설치 가이드와 연동 프롬프트는 구매 후 열람할 수 있습니다.

Automation, Utilities & Developer Tools

무료