Documentation

npm install -D snaptype

# TypeScript interfaces from a JSON file
npx snaptype from-json users.json -o src/types/user.ts

# Zod schema from a REST API response
npx snaptype from-url https://api.example.com/users -o src/schemas/user.ts --zod

# Both TypeScript and Zod at once
npx snaptype from-json data.json --zod --ts -o src/types.ts

npx snaptype from-json <file> [options]

[
  {
    "id": 1,
    "email": "alice@example.com",
    "role": "admin",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "score": 98.5
  },
  {
    "id": 2,
    "email": "bob@example.com",
    "role": "user",
    "createdAt": "2024-03-22T08:00:00.000Z",
    "score": 72.0
  }
]

# Single file
npx snaptype from-json data.json -o src/types/data.ts

# Override the root type name
npx snaptype from-json response.json --name ApiResponse -o src/types.ts

# Zod schema output
npx snaptype from-json data.json --zod -o src/schemas/data.ts

# Both TypeScript and Zod
npx snaptype from-json data.json --zod --ts -o src/types.ts

# Multiple files — merged into one unified type (Pro)
npx snaptype from-json sample1.json sample2.json sample3.json -o src/types.ts

npx snaptype from-url <url> [options]

# From a REST API
npx snaptype from-url https://api.github.com/users/octocat -o src/github.ts

# Custom root name
npx snaptype from-url https://api.example.com/me --name CurrentUser -o src/me.ts

# With authentication header
npx snaptype from-url https://api.example.com/me \
  -H "Authorization: Bearer $TOKEN" \
  -o src/me.ts

# Multiple endpoints merged — absent fields become optional (Pro)
npx snaptype from-url https://api.example.com/users/1 \
  https://api.example.com/users/2 \
  -o src/user.ts

npx snaptype from-csv <file> [options]

id,email,role,score,createdAt
1,alice@example.com,admin,98.5,2024-01-15T10:30:00.000Z
2,bob@example.com,user,72.0,2024-03-22T08:00:00.000Z
3,carol@example.com,user,88.3,2024-06-10T14:00:00.000Z
4,dave@example.com,moderator,,2024-09-01T09:00:00.000Z

# TypeScript interfaces from CSV
npx snaptype from-csv data.csv -o src/types/row.ts

# Snake case property names
npx snaptype from-csv data.csv --naming snake -o src/types/row.ts

# File without a header row — provide column names manually
npx snaptype from-csv data.csv \
  --columns id,name,score,active \
  -o src/types/row.ts

# Watch mode — regenerates on every file save (Pro)
npx snaptype from-csv data.csv --watch -o src/types/row.ts

npx snaptype from-stdin --name <TypeName> [options]

# Pipe from curl
curl https://api.example.com/me | npx snaptype from-stdin --name CurrentUser

# Pipe from another command
cat response.json | npx snaptype from-stdin --name ApiResponse -o src/types.ts

# With Zod output
curl https://api.example.com/products | npx snaptype from-stdin --name Product --zod

cat data.json | npx snaptype from-stdin --name User

npx snaptype from-openapi <source> [options]

openapi: "3.0.3"
info:
  title: My API
  version: "1.0.0"
components:
  schemas:
    User:
      type: object
      required: [id, email]
      properties:
        id:
          type: integer
        email:
          type: string
          format: email
        role:
          type: string
          enum: [admin, user, moderator]
        address:
          $ref: '#/components/schemas/Address'
    Address:
      type: object
      required: [street, city]
      properties:
        street:
          type: string
        city:
          type: string
        zip:
          type: string

# One file per schema (default) — output must be a directory
npx snaptype from-openapi ./openapi.yaml -o ./src/types/

# All schemas in a single file
npx snaptype from-openapi ./openapi.yaml --single-file -o ./src/api-types.ts

# Remote spec
npx snaptype from-openapi https://petstore3.swagger.io/api/v3/openapi.json -o ./types/

# With Zod schemas
npx snaptype from-openapi ./openapi.yaml --zod -o ./src/schemas/

npx snaptype from-graphql <endpoint> [options]

export interface User {
  id: string;
  email: string;
  role: "admin" | "user" | "moderator";
  posts: Post[];
  createdAt: string;
}

export interface Post {
  id: string;
  title: string;
  body: string;
  published: boolean;
  author: User;
}

# Public endpoint
npx snaptype from-graphql https://api.example.com/graphql -o src/graphql-types/

# With authentication header
npx snaptype from-graphql https://api.example.com/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -o src/graphql-types/

npx snaptype barrel <dir> [options]

# Default: outputs <dir>/index.ts
npx snaptype barrel ./src/types

# Custom output path
npx snaptype barrel ./src/types -o src/types/index.ts

# Watch mode — regenerates when files are added or removed
npx snaptype barrel ./src/types --watch

// Generated by snaptype — do not edit manually
export * from './user.js';
export * from './post.js';
export * from './product.js';

npx snaptype diff <old> <new> [options]

# Compare two versions
npx snaptype diff types-v1.ts types-v2.ts

# CI mode — exits with code 1 if breaking changes are found
npx snaptype diff old-types.ts new-types.ts --ci

Breaking changes (2):
  [breaking] User.email — field removed
  [breaking] User.role — type changed: string → "admin" | "editor"

Non-breaking changes (1):
  [ok]       User.nickname — field added

# GitHub Actions example
- name: Check for breaking type changes
  run: npx snaptype diff types/v1.ts types/v2.ts --ci
  env:
    SNAPTYPE_LICENSE_KEY: ${{ secrets.SNAPTYPE_LICENSE_KEY }}

npx snaptype mock <file> [options]

# JSON output (default)
npx snaptype mock schema.json -o mocks/data.json

# TypeScript const export
npx snaptype mock schema.json --ts -o mocks/data.ts

export const mockUser = {
  id: 0,
  email: "user@example.com",
  createdAt: "2024-01-01T00:00:00.000Z",
  active: true,
} as const;

npx snaptype to-zod <file> [options]

# Convert a file of interfaces to Zod
npx snaptype to-zod src/types/user.ts -o src/schemas/user.ts

# With readonly
npx snaptype to-zod src/types/user.ts --readonly -o src/schemas/user.ts

npx snaptype activate <key>

npx snaptype activate xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
# ✓ License activated (xxxxxxxx…)

npx snaptype deactivate

npx snaptype deactivate
# ✓ License deactivated

npx snaptype license

npx snaptype license
# ✓ Active  xxxxxxxx…  (cache valid until 02/05/2026 10:34:00)

export interface User {
  readonly id: number;
  email: string;       // email
  createdAt: string;   // ISO 8601
  role: "admin" | "user";
}

export interface Stats {
  labels: (string | number)[];  // 2 distinct types → union
  mixed: unknown[];              // 3+ types → unknown
}

import { z } from 'zod';

export const UserSchema = z.object({
  id: z.number(),
  email: z.email(),
  createdAt: z.iso.datetime(),
  role: z.enum(["admin", "user"]),
}).readonly();

// --emit interface (default)
export interface User { ... }

// --emit type
export type User = { ... }

{
  "naming": "pascal",
  "emit": "interface",
  "zod": true,
  "ts": true,
  "readonly": false,
  "zodImport": "named",
  "zodInfer": true,
  "outDir": "src/types",
  "baseUrl": "https://api.example.com",
  "headers": {
    "Authorization": "Bearer my-token"
  }
}

// emit: "interface"
export interface User { id: number; }

// emit: "type"
export type User = { id: number; };

export const UserSchema = z.object({ ... });
export type User = z.infer<typeof UserSchema>; // emitted when zodInfer: true

{ "zod": true, "ts": true, "zodInfer": false }

# .snaptyperc: { "baseUrl": "https://api.example.com" }
# resolves to https://api.example.com/users
npx snaptype from-url /users -o types.ts

{
  "headers": {
    "Authorization": "Bearer my-token",
    "X-Tenant": "acme"
  }
}

# .snaptyperc: { "outDir": "src/types" }
# writes to src/types/users.ts
npx snaptype from-json ./data/users.json

npx snaptype from-json ./data.json -o out.ts --config ./configs/snaptype.json

snaptype: invalid naming "kebab", using "camel"
snaptype: "zod" must be a boolean, ignoring

# Temporary (current session)
export SNAPTYPE_LICENSE_KEY=your-key-here

# Permanent (add to your shell profile)
echo 'export SNAPTYPE_LICENSE_KEY=your-key-here' >> ~/.zshrc