@metaengine/openapi-react

Generate TypeScript/React services and models from OpenAPI specifications.

Features

• ✅ React 18+ - Modern React with hooks
• ✅ TypeScript - Fully typed API clients
• ✅ TanStack Query - Optional integration with useQuery/useMutation
• ✅ Fetch API - No dependencies, uses native fetch
• ✅ Monorepo Friendly - Configurable environment variables
• ✅ Framework Agnostic - Works with Vite, Next.js, Create React App

Installation

npm install --save-dev @metaengine/openapi-react

Or use directly with npx:

npx @metaengine/openapi-react <input> <output>

Requirements

• Node.js 14.0 or later
• .NET 8.0 or later runtime (Download)

Usage

With npm scripts (Recommended when installed locally)

If you installed the package with npm install, add a script to your package.json:

{
  "scripts": {
    "generate:api": "metaengine-openapi-react api.yaml ./src/api --tanstack-query --documentation"
  }
}

Then run:

npm run generate:api

With npx (One-off usage or without installation)

Use npx for trying out the tool or in CI/CD pipelines:

# Recommended (with documentation and TanStack Query)
npx @metaengine/openapi-react api.yaml ./src/api \
  --tanstack-query \
  --documentation

# Basic (minimal setup)
npx @metaengine/openapi-react api.yaml ./src/api

# Vite project
npx @metaengine/openapi-react api.yaml ./src/api \
  --base-url-env VITE_API_URL \
  --tanstack-query \
  --documentation

# Next.js project
npx @metaengine/openapi-react api.yaml ./src/api \
  --base-url-env NEXT_PUBLIC_API_URL \
  --tanstack-query \
  --documentation

# Filter by tags (only specific endpoints)
npx @metaengine/openapi-react api.yaml ./src/api \
  --include-tags users,auth \
  --documentation

# From URL
npx @metaengine/openapi-react https://api.example.com/openapi.json ./src/api \
  --tanstack-query \
  --documentation

Note: When the package is installed locally, npx will use that version instead of downloading a new one.

Environment Variables

Configure your base URL via environment variables. The generator creates an api-config.ts file that reads from the appropriate variable:

Vite (prefix: VITE_):

# .env
VITE_API_URL=http://localhost:3000/api

Next.js (prefix: NEXT_PUBLIC_):

# .env
NEXT_PUBLIC_API_URL=http://localhost:3000/api

Create React App (prefix: REACT_APP_):

# .env
REACT_APP_API_BASE_URL=http://localhost:3000/api

CLI Options

| Option | Description | Default | |--------|-------------|---------| | --include-tags <tags> | Filter by OpenAPI tags (comma-separated, case-insensitive) | - | | --base-url-env <name> | Environment variable name for base URL | REACT_APP_API_BASE_URL | | --service-suffix <suffix> | Service naming suffix | Api | | --options-threshold <n> | Parameter count for options object | 4 | | --documentation | Generate JSDoc comments | false | | --tanstack-query | Enable TanStack Query integration | false | | --strict-validation | Enable strict OpenAPI validation | false | | --verbose | Enable verbose logging | false | | --help, -h | Show help message | - |

Usage Examples

Basic API Calls

import { usersApi } from './api/users-api';

// Fetch users
const users = await usersApi.getUsers();

// Create a user
const newUser = await usersApi.createUser({ name: 'John', email: '[email protected]' });

With TanStack Query Hooks

import { useGetUsers, useCreateUser } from './api/users-api';

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

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      {users?.map(u => <div key={u.id}>{u.name}</div>)}
      <button onClick={() => createUser.mutate({ name: 'Jane', email: '[email protected]' })}>
        Add User
      </button>
    </div>
  );
}

Monorepo with Multiple APIs

# Users microservice
npx @metaengine/openapi-react users-api.yaml ./src/api/users \
  --base-url-env VITE_USERS_API_URL \
  --tanstack-query

# Orders microservice
npx @metaengine/openapi-react orders-api.yaml ./src/api/orders \
  --base-url-env VITE_ORDERS_API_URL \
  --tanstack-query

Then configure in .env:

VITE_USERS_API_URL=http://localhost:3001/api
VITE_ORDERS_API_URL=http://localhost:3002/api

License

MIT

Support

For issues and feature requests, please visit: https://github.com/meta-engine/openapi-react/issues