TypeBox

1.1.36 verified Fri May 01 auth: no javascript

TypeBox is a runtime type system that constructs JSON Schema objects from TypeScript-like type definitions, automatically inferring static TypeScript types via Type.Static. The current stable version is 1.1.36, with frequent releases following semantic versioning. It differentiates itself by providing a unified type system that works both at compile time (TypeScript type checking) and runtime (JSON Schema validation), making it ideal for API validation, data serialization, and building type-safe protocols. Unlike standalone validators like Ajv or Zod, TypeBox focuses exclusively on schema generation and type inference, leaving validation to JSON Schema validators.

Common errors

error Cannot find name 'Type'. Did you mean the type 'Type'? ↓

cause Using Type before importing or using Type as a type instead of value.

fix

Ensure you have the correct import: import Type from 'typebox'. If you see this in a type annotation, you might have a naming conflict.

error TypeError: Type.String is not a function ↓

cause Using Type.String (or other builders) as a property access without calling it as a function.

fix

Call Type.String() with parentheses, even if no arguments: Type.String().

error Type 'typeof schema' does not satisfy the constraint 'TBoxSchema'. ↓

cause Using Type.Static with a non-TypeBox schema object (e.g., a plain object literal).

fix

Ensure the argument to Type.Static is a schema built with TypeBox builders: Type.Static<typeof mySchema> where mySchema is constructed via Type.*.

Warnings

gotcha Type.Static is a type, not a function. It can only be used in type positions, not runtime. ↓

fix Use Type.Static<typeof schema> as a type annotation, not a runtime value.

gotcha All type builders (e.g., Type.String()) must be called as functions, even without arguments. ↓

fix Always use parentheses: Type.String(), not Type.String.

gotcha Type.Object requires properties to be registered with Type.* builders, not plain objects. ↓

fix Use Type.Object({ key: Type.String() }) instead of Type.Object({ key: { type: 'string' } }).

Install

npm install typebox

yarn add typebox

pnpm add typebox

Imports

default (Type)
wrong
```
const Type = require('typebox').default
```
correct
```
import Type from 'typebox'
```
The package exposes a default export. In CommonJS, require returns the default export directly, so you can use const Type = require('typebox'). Do not use destructuring { Type } as it won't work.
Type.String
wrong
```
Type.String({ format: 'email' })
```
correct
```
Type.String({ format: 'email' })
```
Type.String is a function that returns a JSON Schema object. All type builders accept optional parameters for constraining the schema (e.g., format, minLength). Since typebox v1, all type definitions are function calls.
Type.Static
wrong
```
type T = Type.Static<schema>
```
correct
```
type T = Type.Static<typeof schema>
```
Type.Static is a generic type that extracts the inferred TypeScript type from a schema. It must be used with typeof schema, not the schema value directly. This is a type-level operation, not a runtime function.

Quickstart

Shows how to define an object schema with TypeBox, infer the TypeScript type using Type.Static, and validate data with Ajv.

import Type from 'typebox';

const User = Type.Object({
  id: Type.String(),
  name: Type.String(),
  email: Type.String({ format: 'email' }),
  age: Type.Optional(Type.Number({ minimum: 0 }))
});

type UserType = Type.Static<typeof User>;
// equivalent to: { id: string; name: string; email: string; age?: number }

// Validate with any JSON Schema validator (not included)
const Ajv = require('ajv');
const ajv = new Ajv();
const validate = ajv.compile(User);
const result = validate({ id: '1', name: 'Alice', email: 'alice@example.com' });
console.log(result); // true