🌾 OATS - OpenAPI TypeScript Sync

Automatically sync OpenAPI specs to TypeScript clients. No manual steps, just real-time updates.

🚀 Quick Start

# Install
npm install -D @tryloop/oats

# Initialize config
npx oats init

# Start development
npx oats start

🎯 What is OATS?

OATS eliminates the manual 6-step workflow of syncing OpenAPI changes:

1. Wait for backend to regenerate OpenAPI spec
2. Copy spec to client generator
3. Run generator
4. Build client
5. Link to frontend
6. Restart frontend

With OATS: Change your API → Everything syncs automatically ✨

📋 Configuration

OATS supports multiple configuration formats:

JSON Configuration

{
  "$schema": "node_modules/@tryloop/oats/schema/oats.schema.json",
  "services": {
    "backend": {
      "path": "./backend",
      "port": 8000,
      "startCommand": "npm run dev",
      "apiSpec": {
        "path": "/api/openapi.json"
      }
    },
    "client": {
      "path": "./api-client",
      "packageName": "@myorg/api-client",
      "generator": "@hey-api/openapi-ts"
    },
    "frontend": {
      "path": "./frontend",
      "port": 3000,
      "startCommand": "npm run dev"
    }
  }
}

TypeScript Configuration

import { defineConfig } from '@tryloop/oats'

export default defineConfig({
  services: {
    backend: {
      path: './backend',
      port: 8000,
      startCommand: 'npm run dev',
      apiSpec: {
        path: '/api/openapi.json'
      }
    },
    client: {
      path: './api-client',
      packageName: '@myorg/api-client',
      generator: '@hey-api/openapi-ts'
    },
    frontend: {
      path: './frontend',
      port: 3000,
      startCommand: 'npm run dev'
    }
  }
})

Note: TypeScript configs are fully supported. OATS includes esbuild for consistent transpilation across all environments.

JavaScript Configuration

const { defineConfig } = require('@tryloop/oats')

module.exports = defineConfig({
  // Same structure as TypeScript config
})

🌐 Supported Technologies

Backend Frameworks

Language	Frameworks	OpenAPI Support
Node.js	Express, Fastify, NestJS, Koa, Hapi	Static files or runtime generation
Python	FastAPI, Flask, Django REST	Runtime endpoints (e.g., /openapi.json)

Frontend Frameworks

All major frameworks: React, Vue, Angular, Svelte, Next.js, Nuxt, Remix

TypeScript Client Generators

• @hey-api/openapi-ts (Recommended)
• swagger-typescript-api
• openapi-generator-cli
• Custom generators (via generateCommand)

🔧 CLI Commands

Command	Description	Options
oats start	Start all services with auto-sync	--config, --quiet, --init-gen
oats init	Create configuration interactively	--force, --yes
oats validate	Validate configuration file	--config
oats detect	Auto-detect project structure	-

🎨 Key Features

🔄 Real-time Synchronization

• File watching with intelligent debouncing
• Smart change detection - ignores formatting changes
• Hash-based caching - skip unnecessary regeneration
• Concurrent sync prevention - no duplicate operations

🛠️ Developer Experience

• Auto port management - kills conflicting processes
• Cross-platform support - Windows, macOS, Linux
• Config hot-reload - changes restart services automatically
• IntelliSense support - JSON schema for autocompletion
• Multiple config formats - JSON, JS, or TypeScript (with built-in transpilation)
• Automatic backend URL injection - Frontend uses local API in dev, production in prod

🚀 Performance

• 45% faster sync than manual process
• Incremental builds when possible
• Parallel service startup
• Efficient polling for runtime API specs

📚 Examples

Python FastAPI + React

{
  "services": {
    "backend": {
      "path": "../backend",
      "port": 8000,
      "runtime": "python",
      "python": {
        "virtualEnv": ".venv"
      },
      "startCommand": ".venv/bin/uvicorn main:app --reload",
      "apiSpec": {
        "path": "/openapi.json"
      }
    },
    "client": {
      "path": "../api-client",
      "packageName": "@myapp/api",
      "generator": "@hey-api/openapi-ts"
    },
    "frontend": {
      "path": "./",
      "port": 3000,
      "startCommand": "npm start"
    }
  }
}

NestJS + Next.js Monorepo

{
  "services": {
    "backend": {
      "path": "./apps/api",
      "port": 3333,
      "startCommand": "nx serve api",
      "apiSpec": {
        "path": "swagger.json"
      }
    },
    "client": {
      "path": "./packages/api-client",
      "packageName": "@myapp/api-client",
      "generator": "custom",
      "generateCommand": "yarn openapi-ts"
    },
    "frontend": {
      "path": "./apps/web",
      "port": 4200,
      "startCommand": "nx serve web"
    }
  }
}

📖 Configuration Reference

Service Configuration

Property	Description	Required
path	Path to service directory	✅
port	Port number (backend/frontend)	⚠️
startCommand	Command to start service	✅
runtime	"node" or "python"	❌
apiSpec.path	Path to OpenAPI spec	✅

⚠️ Port is required for backend/frontend services, but not for client

Sync Options

Option	Default	Description
strategy	"smart"	"smart" or "aggressive"
debounceMs	1000	Delay before regenerating
autoLink	true	Auto-link packages
pollingInterval	5000	For runtime API specs

Log Options

Option	Default	Description
level	"info"	"debug", "info", "warn", "error"
colors	true	Enable colored output
timestamps	false	Show timestamps in logs
showServiceOutput	true	Display output from services

🛡️ Troubleshooting

Port conflicts

OATS automatically handles port conflicts. To disable:

{
  "services": {
    "backend": {
      "env": {
        "OATS_AUTO_KILL_PORTS": "false"
      }
    }
  }
}

Client not updating

1. Check package is linked: npm ls @myorg/api-client
2. For Vite: Exclude from optimization in vite.config.ts
3. Ensure packageName matches your client's package.json

Automatic Backend URL Injection

OATS automatically injects your backend URL into your frontend environment:

// Your frontend code
const API_URL = import.meta.env.VITE_OATS_BACKEND_BASE_URL || 'https://api.production.com'

How it works:

1. OATS detects your frontend framework (Vite, CRA, Next.js, etc.)
2. Injects the backend URL with the correct prefix:
   • Vite: VITE_OATS_BACKEND_BASE_URL
   • Create React App: REACT_APP_OATS_BACKEND_BASE_URL
   • Next.js: NEXT_PUBLIC_OATS_BACKEND_BASE_URL
   • Vue CLI: VUE_APP_OATS_BACKEND_BASE_URL
3. Your app uses local backend when running with OATS, production otherwise

No configuration needed - it just works!

TypeScript config issues

OATS fully supports TypeScript configs (.ts files) with built-in transpilation:

• Configs work consistently across all environments
• No additional setup or dependencies required
• Use ESM syntax: export default defineConfig({...})

Command not found

Use npx or add to scripts:

{
  "scripts": {
    "dev:sync": "oats start"
  }
}

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for details.

# Clone repo
git clone https://github.com/loopkitchen/oats.git

# Install dependencies
yarn install

# Run tests
yarn test

# Start development
yarn dev

📄 License

MIT © Hari Shekhar

---

GitHub • npm • Issues