npm package: @metaengine/openapi-react
Description: Generate TypeScript/React services and models from OpenAPI specifications with TanStack Query (React Query) hooks, useQuery, useMutation, and native fetch API for React 18+
Author: José A. Saldaña Perez
Latest version: 1.0.3

# @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

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

Or use directly with npx:

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

## Requirements

- Node.js 14.0 or later
- .NET 8.0 or later runtime ([Download](https://dotnet.microsoft.com/download))

## Usage

### With npm scripts (Recommended when installed locally)

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

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

Then run:
```bash
npm run generate:api
```

### With npx (One-off usage or without installation)

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

```bash
# 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_`):
```bash
# .env
VITE_API_URL=http://localhost:3000/api
```

**Next.js** (prefix: `NEXT_PUBLIC_`):
```bash
# .env
NEXT_PUBLIC_API_URL=http://localhost:3000/api
```

**Create React App** (prefix: `REACT_APP_`):
```bash
# .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` |
| `--date-transformation` | Convert date strings in responses to Date objects | `false` |
| `--clean` | Clean output directory (remove files not in generation) | `false` |
| `--verbose` | Enable verbose logging | `false` |
| `--type-mapping <slug=target>` | Override TS type for an OpenAPI format. Repeatable. See [Type mapping overrides](#type-mapping-overrides) | - |
| `--help, -h` | Show help message | - |

### Type mapping overrides

Use `--type-mapping` to override the TS type emitted for a given OpenAPI `(type, format)` pair. Repeatable. Unknown slugs and unknown targets are hard errors.

| Slug | OpenAPI `(type, format)` | Default | `--type-mapping` value |
|------|--------------------------|---------|------------------------|
| `int64` | `(integer, int64)` | `number` | `int64=bigint` |
| `decimal` | `(number, decimal)` | `number` | `decimal=string` |
| `date-time` | `(string, date-time)` | `Date` | `date-time=string` |
| `date` | `(string, date)` | `Date` | `date=string` |

```bash
npx @metaengine/openapi-react api.yaml ./src/api \
  --type-mapping int64=bigint \
  --type-mapping date-time=string
```

## Usage Examples

### Basic API Calls

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

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

// Create a user
const newUser = await usersApi.createUser({ name: 'John', email: 'john@example.com' });
```

### With TanStack Query Hooks

```typescript
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: 'jane@example.com' })}>
        Add User
      </button>
    </div>
  );
}
```

### Monorepo with Multiple APIs

```bash
# 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`:
```bash
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