[中文] | [English]

Valype 🐉

TypeScript Runtime Validator - Generate validation from type definitions

Warning

Valype is currently under active development. APIs may change in future releases. Please follow Semver to avoid breaking changes.

• 🎯 Type-safe validation with TypeScript type inference
• 🔌 Seamless unplugin integration (Vite/Rollup/esbuild/Astro/Farm/Nuxt/Rspack/Webpack)
• 🛡️ Unified type validation
• 💻 TypeScript plugin for IDE support
• 🛠️ IDE/editor extension support

Valype = Validate + Type. Automatically generates runtime validators from TypeScript type definitions.

🚀 Getting Started

1. Install plugin:

# for npm users
npm add zod@latest
npm add -D unplugin-valype

# for yarn users
yarn add zod@latest
yarn add -D unplugin-valype

# for pnp users
pnpm add zod@latest
pnpm add -D unplugin-valype

# for bun users
bun add zod@latest
bun add -D unplugin-valype

zod's version should be 3.25.0 at least, but we recommend using zod v4 for the best experience, because valype generates zod v4 schema

2. Configure plugin for your build tool following unplugin-valype docs

3. For TypeScript language support, see Editor Integration below.

4. Define your types (use .valype.ts extension):

// user.valype.ts
export interface User {
  name: string
  age: number
}

5. Use the generated validator:

import { validateUser } from './user.valype'

const issues = validateUser(data) // Returns ZodIssue[] or undefined
if (issues) {
  // Handle validation errors
}

📖 Usage

unplugin-valype generates validators for types exported from *.valype.ts files. The validator type signature is:

export declare function validateSome(data: unknown): ZodIssue[] | undefined

• Returns undefined when validation passes
• Returns ZodIssue[] with error details when validation fails

Note

You typically don't need to use valype package directly, just use the generated validators.

📦 Packages

Package	Version	Description
valype		Core schema generation logic
unplugin-valype		Build tool plugin

🧑‍💻 Editor Integration

VSCode Extension

You can get instant type hints, code completion, and go-to-definition for .valype.ts files by installing the Valype VSCode extension.

• No manual tsconfig plugin configuration required
• Works out of the box for all .valype.ts files
• Supports type checking, completion, navigation, and more

Just search for "Valype" in the VSCode Extensions Marketplace and install.

The extension is also available on openVSX for use in editors like Cursor.

TypeScript Language Service Plugin

If you want to manually configure or use in other editors, you can install the TypeScript language service plugin:

npm install -D @valype/typescript-plugin

Then add to your tsconfig.json:

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "@valype/typescript-plugin"
      }
    ]
  }
}

This enables type hints, completion, and navigation for .valype.ts files in any editor that supports TypeScript plugins.

Tip

If you use this plugin in VSCode, for the best type experience, set VSCode to use the workspace TypeScript version:

1. Open a TypeScript file in VSCode
2. Click the TypeScript version number in the status bar
3. Select "Use Workspace Version"

💡 Motivation

While TypeScript ensures compile-time type safety, runtime data validation remains essential. Traditional solutions like Zod require duplicate type definitions and lose valuable tsdoc information. Valype solves this by:

• Single Source of Truth - Define types once, get both static and runtime validation
• Full Type Information - Preserves all tsdoc documentation and editor hints
• Seamless Integration - Works natively with TypeScript tooling

const userSchema = z.object({
  name: z.string(),
  age: z.number(),
})

type User = z.infer<typeof userSchema>
// And `User['name'] does not have tsdoc info

Using valype:

export interface User {
  /**
   * name of user
   */
  name: string
  age: number
}

// Validator is generated automatically!
const result = validateUser(data)

// Also `User['name'] has tsdoc info

Valype lets you define types once and get runtime validation automatically!

🥰 Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

🪪 License

MIT

🙏 Inspired By

Valype draws inspiration from these excellent projects:

• ts-to-zod
• Zod
• @sinclair/typebox

🌟 Star History