S2T

Getting Started

Learn how to install and use swagger-to-tanstack to generate TypeScript code from your OpenAPI specifications in just a few minutes.

Prerequisites

Requirements: Node.js 16 or higher and a valid Swagger/OpenAPI specification file.

Installation

Install the CLI globally using your preferred package manager:

npm

bash

yarn

bash

pnpm

bash

Quick Start

Step 1: Initialize Your Project

Create the required boilerplate files:

bash

This creates:

  • lib/axios.ts - Axios instance configuration
  • lib/query-keys.ts - Query keys factory for TanStack Query

Step 2: Generate Your API Client

Generate TypeScript code from your Swagger specification:

bash
Tip: You can also use a URL instead of a local file: -i https://api.example.com/swagger.json

Step 3: Install Required Dependencies

Install the necessary packages for your chosen template:

TanStack Query (default)

bash

RTK Query

bash

SWR

bash

Generated Project Structure

After generation, your project will have this structure:

plaintext

Using Generated Code

With TanStack Query

Import and use the generated hooks in your React components:

typescript

Setup Query Provider

Wrap your app with the QueryClientProvider:

typescript

Common Use Cases

Generate Specific Tags Only

bash

Use Different Template

bash

Use Fetch Instead of Axios

bash

Watch Mode for Development

bash

Development Workflow

Option 1: Watch Mode (Recommended for Development)

Automatically regenerate when your Swagger file changes. Preserves your modifications automatically.

bash

✅ Safe: Skips files with custom modifications

Option 2: Update Mode (Recommended for Production)

Safely update generated files while preserving your modifications. Best for CI/CD pipelines.

bash

✅ Safe: Always preserves modifications

Option 3: Fresh Generation

Completely regenerate everything. Use this for first-time setup or when you want to start fresh.

bash

⚠️ Warning: Overwrites ALL files including modifications

Protecting Your Modifications

When you customize generated files, protect them by adding a comment marker:

typescript

Supported markers: // CUSTOM, // MODIFIED, // TODO, // KEEP, // USER:

Learn more about preserving modifications →

Validation

Validate your Swagger spec before generation:

bash

This command checks if your specification is valid and displays useful information about your API.

Next Steps

Now that you have the basics down, explore more advanced features:

Need Help?

If you run into any issues or have questions, check out our comprehensive CLI reference or explore the example projects.

CLI Reference →FAQ →

👋 Hello and welcome!

I'm Armel Dakayao, Front-End Developer & creator of swagger-to-tanstack CLI.

Armel Dakayao

Senior Front-End Developer. I build scalable, user-friendly web & mobile apps with React,React Native, Next.js, and TypeScript.