Admin

name	type	size	perms	modified	actions
[parent directory]
locales/	dir	-	0775	2026-09-15 05:26:24
mini/	dir	-	0775	2026-09-15 05:26:24
src/	dir	-	0775	2026-09-15 05:26:24
v3/	dir	-	0775	2026-09-15 05:26:24
v4/	dir	-	0775	2026-09-15 05:26:24
v4-mini/	dir	-	0775	2026-09-15 05:26:24
index.cjs	file	1,486 B	0664	2026-08-05 08:12:09	edit
index.d.cts	file	123 B	0664	2026-08-05 08:12:10	edit
index.d.ts	file	121 B	0664	2026-08-05 08:12:10	edit
index.js	file	121 B	0664	2026-08-05 08:12:10	edit
LICENSE	file	1,072 B	0664	2026-08-05 08:12:09	edit
package.json	file	3,796 B	0664	2026-08-05 08:12:10	edit
README.md	file	5,582 B	0664	2026-08-05 08:12:10	edit

editing: README.md

<img src="logo.svg" width="200px" align="center" alt="Zod logo" />
 <h1 align="center">Zod</h1>
 
 TypeScript-first schema validation with static type inference
 
 by <a href="https://x.com/colinhacks">@colinhacks</a>

<div align="center">
 <a href="https://zod.dev/api">Docs</a>
 &nbsp;&nbsp;•&nbsp;&nbsp;
 <a href="https://discord.gg/RcG33DQJdf">Discord</a>
 &nbsp;&nbsp;•&nbsp;&nbsp;
 <a href="https://twitter.com/colinhacks">𝕏</a>
 &nbsp;&nbsp;•&nbsp;&nbsp;
 <a href="https://bsky.app/profile/zod.dev">Bluesky</a>
 
</div>

### [Read the docs →](https://zod.dev/api)

## What is Zod?

Zod is a TypeScript-first validation library. Define a schema and parse some data with it. You'll get back a strongly typed, validated result.

```ts
import * as z from "zod";

const User = z.object({
  name: z.string(),
});

// some untrusted data...
const input = {
  /* stuff */
};

// the parsed result is validated and type safe!
const data = User.parse(input);

// so you can use it with confidence :)
console.log(data.name);
```

## Features

- Zero external dependencies
- Works in Node.js and all modern browsers
- Tiny: `2kb` core bundle (gzipped)
- Immutable API: methods return a new instance
- Concise interface
- Works with TypeScript and plain JS
- Built-in JSON Schema conversion
- Extensive ecosystem

## Installation

```sh
npm install zod
```

## Basic usage

Before you can do anything else, you need to define a schema. For the purposes of this guide, we'll use a simple object schema.

```ts
import * as z from "zod";

const Player = z.object({
  username: z.string(),
  xp: z.number(),
});
```

### Parsing data

Given any Zod schema, use `.parse` to validate an input. If it's valid, Zod returns a strongly-typed _deep clone_ of the input.

```ts
Player.parse({ username: "billie", xp: 100 });
// => returns { username: "billie", xp: 100 }
```

**Note** — If your schema uses certain asynchronous APIs like `async` [refinements](https://zod.dev/api#refinements) or [transforms](https://zod.dev/api#transforms), you'll need to use the `.parseAsync()` method instead.

```ts
const schema = z.string().refine(async (val) => val.length <= 8);

await schema.parseAsync("hello");
// => "hello"
```

### Handling errors

When validation fails, the `.parse()` method will throw a `ZodError` instance with granular information about the validation issues.

```ts
try {
  Player.parse({ username: 42, xp: "100" });
} catch (err) {
  if (err instanceof z.ZodError) {
    err.issues;
    /* [
      {
        expected: 'string',
        code: 'invalid_type',
        path: [ 'username' ],
        message: 'Invalid input: expected string'
      },
      {
        expected: 'number',
        code: 'invalid_type',
        path: [ 'xp' ],
        message: 'Invalid input: expected number'
      }
    ] */
  }
}
```

To avoid a `try/catch` block, you can use the `.safeParse()` method to get back a plain result object containing either the successfully parsed data or a `ZodError`. The result type is a [discriminated union](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions), so you can handle both cases conveniently.

```ts
const result = Player.safeParse({ username: 42, xp: "100" });
if (!result.success) {
  result.error; // ZodError instance
} else {
  result.data; // { username: string; xp: number }
}
```

```ts
const schema = z.string().refine(async (val) => val.length <= 8);

await schema.safeParseAsync("hello");
// => { success: true; data: "hello" }
```

### Inferring types

Zod infers a static type from your schema definitions. You can extract this type with the `z.infer<>` utility and use it however you like.

```ts
const Player = z.object({
  username: z.string(),
  xp: z.number(),
});

// extract the inferred type
type Player = z.infer<typeof Player>;

// use it in your code
const player: Player = { username: "billie", xp: 100 };
```

In some cases, the input & output types of a schema can diverge. For instance, the `.transform()` API can convert the input from one type to another. In these cases, you can extract the input and output types independently:

```ts
const mySchema = z.string().transform((val) => val.length);

type MySchemaIn = z.input<typeof mySchema>;
// => string

type MySchemaOut = z.output<typeof mySchema>; // equivalent to z.infer<typeof mySchema>
// number
```

cancel