🚀 swagger-to-tanstack

📚 Documentation · 🐛 Report Bug · ✨ Request Feature

✨ Features

• 🎯 Multiple Templates: TanStack Query, RTK Query, SWR, React Query Kit, and basic hooks
• 🔄 Smart Updates: Preserves your custom modifications automatically
• 📦 TypeScript First: Fully typed API clients with Zod/Yup validation
• 🛡️ Safe by Default: Watch and update modes protect your changes
• ⚡ Fast & Flexible: HTTP clients (Axios/Fetch), multiple validators
• 🎨 Clean Code: Generates production-ready, well-organized code

📦 Installation

npm install -g swagger-to-tanstack

Or use with npx:

npx swagger-to-tanstack generate -i ./swagger.json

🚀 Quick Start

1. Initialize your project

swagger-to-tanstack init

This creates:

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

2. Generate your API client

swagger-to-tanstack generate -i ./swagger.json

3. Install dependencies

npm install @tanstack/react-query axios zod

4. Use in your React app

import { useGetUsers, useCreateUser } from '@/api/users/hooks'

function UserList() {
  const { data: users, isLoading } = useGetUsers()
  const createUser = useCreateUser()

  if (isLoading) return <div>Loading...</div>

  return (
    <div>
      <button onClick={() => createUser.mutate({ name: 'John' })}>
        Add User
      </button>
      <ul>
        {users?.map(user => (
          <li key={user.id}>{user.name}</li>
        ))}
      </ul>
    </div>
  )
}

📖 Commands

generate

Generate TypeScript code from Swagger/OpenAPI spec.

swagger-to-tanstack generate -i ./swagger.json -o ./src/api

Options:

• -i, --input <path> - Swagger spec path or URL (required)
• -o, --output <dir> - Output directory (default: ./src/api)
• -t, --template <name> - Template: tanstack-query, rtk-query, swr, react-query-kit, basic
• --http-client <client> - HTTP client: axios or fetch
• --validator <validator> - Validator: zod or yup
• --include-tags <tags> - Only generate specific tags
• --exclude-tags <tags> - Exclude specific tags
• --preserve-modified - Skip overwriting modified files
• -u, --username <username> - Basic auth username
• -p, --password <password> - Basic auth password

init

Initialize boilerplate files.

swagger-to-tanstack init

watch

Watch for changes and regenerate automatically (local files only).

swagger-to-tanstack watch -i ./swagger.json

Safety: Automatically preserves your modifications.

update

Safely update files while preserving custom modifications.

swagger-to-tanstack update -i ./swagger.json

Safety: ALWAYS preserves modifications. Files with changes are skipped.

validate

Validate Swagger spec and display API info.

swagger-to-tanstack validate -i ./swagger.json

list-templates

List all available templates and options.

swagger-to-tanstack list-templates

🎨 Templates

TanStack Query (Recommended)

swagger-to-tanstack generate -i ./swagger.json -t tanstack-query

Modern data synchronization with automatic caching and refetching.

Install: npm install @tanstack/react-query axios zod

RTK Query

swagger-to-tanstack generate -i ./swagger.json -t rtk-query

Redux Toolkit Query with powerful caching and state management.

Install: npm install @reduxjs/toolkit react-redux axios zod

SWR

swagger-to-tanstack generate -i ./swagger.json -t swr

Lightweight by Vercel with stale-while-revalidate strategy.

Install: npm install swr axios zod

React Query Kit

swagger-to-tanstack generate -i ./swagger.json -t react-query-kit

Enhanced TanStack Query with improved type inference.

Install: npm install react-query-kit @tanstack/react-query axios zod

Basic

swagger-to-tanstack generate -i ./swagger.json -t basic

Simple useState/useEffect hooks with no external dependencies.

🛡️ Protecting Your Modifications

Add comment markers to preserve your custom code:

// CUSTOM - Added pagination support
export function useGetUsers(page: number) {
  return useQuery({
    queryKey: ['users', page],
    queryFn: () => getUsers({ page })
  })
}

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

Files with these markers are automatically skipped during updates.

📝 Examples

Generate with specific tags

swagger-to-tanstack generate -i ./swagger.json --include-tags users,auth

Use fetch instead of axios

swagger-to-tanstack generate -i ./swagger.json --http-client fetch

Generate from protected URL

swagger-to-tanstack generate -i https://api.example.com/swagger.json -u admin -p secret

Development workflow

# Terminal 1: Watch for changes
swagger-to-tanstack watch -i ./swagger.json

# Terminal 2: Your dev server
npm run dev

📂 Generated Structure

src/api/
├── users/
│   ├── api.ts         # API functions
│   ├── hooks.ts       # React hooks
│   └── types.ts       # TypeScript types
├── posts/
│   ├── api.ts
│   ├── hooks.ts
│   └── types.ts
└── lib/
    ├── axios.ts        # Axios config
    └── query-keys.ts   # Query keys factory

🔧 Configuration

HTTP Clients

• axios (default) - Full-featured with interceptors
• fetch - Native API, smaller bundle

Validators

• zod (default) - TypeScript-first validation
• yup - Popular schema builder

🤝 Best Practices

1. Use version control - Always commit before regenerating
2. Add markers - Protect custom modifications with comment markers
3. Use update mode - Safer than generate when you have changes
4. Separate custom code - Create *.custom.ts files for extensive modifications
5. Watch mode for dev - Automatic regeneration during development

📚 Documentation

Full documentation available at: https://swagger2tanstack.vercel.app/

🐛 Issues & Support

Found a bug or have a question? Open an issue

📄 License

MIT © Armel DAKAYAO

🙏 Acknowledgments

Built with:

• Commander.js - CLI framework
• OpenAPI TypeScript - OpenAPI parser
• Chalk - Terminal styling

Made with ❤️ for the React community