TypeBox for TypeScript: Complete Guide with Examples

What is TypeBox and why is it needed?

\n\n

TypeBox is a powerful library for TypeScript that allows you to define data schemas compatible with the JSON Schema standard, and simultaneously derive correct static TypeScript types from them. In simple terms, it is a bridge between runtime data validation (when your application is running and checking data on the fly) and compile-time types (when TypeScript checks code correctness before execution).

\n\n

Why is this needed? In modern web development, data often comes from untrusted sources: API requests, website forms, configuration files. Without validation, you risk getting runtime errors that are difficult to catch. TypeBox solves this problem elegantly: you describe the schema once, and you get:

\n

\n
• Runtime validator — checks whether an object matches the schema during program execution.
\n
• Static type — TypeScript automatically infers the type that can be used for annotations.
\n
• JSON Schema — the schema can be serialized to JSON and used in other tools (e.g., for generating UI forms or documentation).
\n

\n\n

TypeBox is ideal for: creating API endpoints with request body validation, working with configuration files, building complex forms with field validation, and any scenario where type safety is important at all stages.

\n\n

Installing TypeBox

\n\n

TypeBox is a library for Node.js/TypeScript, so it is installed via npm (or yarn/pnpm).

\n\n

npm install @sinclair/typebox

\n\n

After installation, you can import it into your project:

\n\n

import { Type } from '@sinclair/typebox';

\n\n

To work with validation, you will also need a validator itself. TypeBox does not include one by default to leave the choice to the developer. It is recommended to use @sinclair/typebox/compiler (built-in compiler) or ajv (popular JSON Schema validator). Let's install the compiler:

\n\n

npm install @sinclair/typebox-compiler

\n\n

Or, if you prefer AJV:

\n\n

npm install ajv ajv-formats

\n\n

Note: the library is called @sinclair/typebox, not just typebox. This is important for correct installation.

\n\n

Quick Start with Code Example

\n\n

Let's create a simple schema for a user and validate it.

\n\n

import { Type } from '@sinclair/typebox';\nimport { TypeCompiler } from '@sinclair/typebox/compiler';\n\n// 1. Define the user schema\nconst UserSchema = Type.Object({\n    id: Type.Number(),\n    name: Type.String({ minLength: 2 }),\n    email: Type.String({ format: 'email' }),\n    age: Type.Optional(Type.Number({ minimum: 0, maximum: 120 })),\n});\n\n// 2. Create a compiler for validation\nconst validator = TypeCompiler.Compile(UserSchema);\n\n// 3. Test data\nconst validUser = {\n    id: 1,\n    name: 'Alice',\n    email: 'alice@example.com',\n    age: 30,\n};\n\nconst invalidUser = {\n    id: 'not-a-number',\n    name: 'A',\n    email: 'invalid-email',\n};\n\n// 4. Validation\nconsole.log(validator.Check(validUser));   // true\nconsole.log(validator.Check(invalidUser)); // false\n\n// 5. Get the static type\ntype UserType = Static<typeof UserSchema>;\n// Now UserType is { id: number; name: string; email: string; age?: number; }\n

\n\n

In this example, we defined a schema, compiled it into a validator, and checked two objects. Note the use of Type.Optional for the age field — it can be absent. We also used format: 'email' to validate the email format.

\n\n

Main Methods and Functions of TypeBox

\n\n

TypeBox provides a rich set of functions for creating schemas. Let's look at the most important ones.

\n\n

1. Type.String