Getting Started

This guide will walk you through installing sparktype, creating your first configuration file, and generating types from an OpenAPI specification.

Installation

Choose your preferred installation method:

npm

npm install -D sparktype

pip

pip install sparktype

Homebrew

brew install hntrl/tap/sparktype

Go

go install github.com/hntrl/sparktype/cmd/sparktype@latest

Direct Download

You can also download pre-built binaries directly from the GitHub Releases page. Available for:

• macOS (Apple Silicon & Intel)
• Linux (x64 & ARM64)
• Windows (x64)

Prerequisites

You'll need an OpenAPI specification file (v3.0 or v3.1) in either YAML or JSON format. If you don't have one, here's a minimal example to get started:

# openapi.yaml
openapi: "3.0.3"
info:
  title: My API
  version: "1.0.0"
paths: {}
components:
  schemas:
    User:
      type: object
      required:
        - id
        - email
      properties:
        id:
          type: string
          description: Unique identifier
        email:
          type: string
          format: email
        name:
          type: string

Create a Configuration File

The fastest way to create a configuration file is with the init command:

sparktype init

This creates a typegen.jsonc file in your current directory with a basic template.

Alternatively, create typegen.jsonc manually:

{
  "$schema": "https://hntrl.github.io/sparktype/schema.json",
  
  // Define your OpenAPI spec sources
  "specs": {
    "api": {
      "path": "./openapi.yaml"
    }
  },
  
  // Define output files
  "outputs": [
    {
      "path": "./src/types/api.ts",
      "format": "typescript",
      "contents": ["api:*"]
    }
  ]
}

JSON with Comments

The .jsonc extension allows comments in your configuration file. Most editors recognize this format and provide proper syntax highlighting.

Generate Types

Run the generate command:

sparktype generate

You should see output like:

Generated: ./src/types/api.ts

Open the generated file to see your TypeScript types:

// Generated by an automated build step. Do not edit.

export interface User {
  /** Unique identifier */
  id: string;
  email: string;
  name?: string;
}

Watch Mode

During development, you can watch for changes and automatically regenerate:

sparktype generate --watch

sparktype will monitor your OpenAPI spec files and regenerate types whenever they change.

Multiple Output Formats

sparktype can generate multiple formats from the same spec. Update your config to add more outputs:

{
  "specs": {
    "api": { "path": "./openapi.yaml" }
  },
  "outputs": [
    {
      "path": "./src/types/api.ts",
      "format": "typescript",
      "contents": ["api:*"]
    },
    {
      "path": "./src/schemas/api.ts",
      "format": "zod",
      "contents": ["api:*"]
    },
    {
      "path": "./types/api.py",
      "format": "python",
      "contents": ["api:*"]
    }
  ]
}

CI/CD Integration

Use the check command in CI to ensure generated types stay in sync:

sparktype check

This compares existing generated files against what would be generated now. If there's any drift, it exits with code 1 and shows the differences.

See the CI/CD Integration guide for full examples.

Next Steps

• Learn about configuration options
• Explore output formats
• Set up CI/CD integration
• Work with multiple specs