Skip to content

README.md

Latest commit

 

History

History
264 lines (183 loc) · 9.12 KB

README.md

File metadata and controls

264 lines (183 loc) · 9.12 KB
Raw

MetaEngine GraphQL React

npm version npm downloads License: MIT

Generate React TypeScript hooks and models from GraphQL schemas.

Typed queries, mutations & subscriptions over the native Fetch API, with optional TanStack Query (useQuery/useMutation) hooks — generated straight from your schema (SDL).

Quick Links

Features

  • ✅ React 18+ — generated API functions plus optional hooks
  • ✅ TanStack Query — useQuery/useMutation hooks with --tanstack-query
  • ✅ Queries, mutations & subscriptions — typed operations generated straight from SDL
  • ✅ Native Fetch API — zero runtime dependencies in the generated client
  • ✅ Reusable fragments — opt into named fragment spreads with --fragments
  • ✅ @oneOf inputs — idiomatic tagged-union input types with --one-of-inputs
  • ✅ Custom scalar mapping — well-known scalars resolve to idiomatic TS types; override any with --custom-scalar
  • ✅ Smart error handling & retries — HTTP-status routing and exponential-backoff retries via ClientConfig
  • ✅ TypeScript — fully typed clients and models
  • ✅ Tree-shakeable — separate file per model and per operation type

Installation

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

Or use directly with npx:

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

Requirements

  • Node.js 18.0 or later
  • .NET 8.0 or later runtime (Download)
  • React 18+ (and @tanstack/react-query if you use --tanstack-query)

Quick Start

Basic

npx @metaengine/graphql-react schema.graphql ./src/api \
  --documentation \
  --tanstack-query

Production setup

npx @metaengine/graphql-react schema.graphql ./src/api \
  --tanstack-query \
  --retries 3 \
  --error-handling

With npm scripts

Add to your package.json:

{
  "scripts": {
    "generate:api": "metaengine-graphql-react schema.graphql ./src/api --tanstack-query --error-handling"
  }
}

Then run:

npm run generate:api

Runtime-specific examples

Vite:

npx @metaengine/graphql-react schema.graphql ./src/api --base-url-env VITE_API_URL

Next.js:

npx @metaengine/graphql-react schema.graphql ./src/api --base-url-env NEXT_PUBLIC_API_URL

Create React App:

npx @metaengine/graphql-react schema.graphql ./src/api --base-url-env REACT_APP_API_BASE_URL

CLI Options

Option Description Default
--fragments Emit reusable named fragments for object-type selections false
--one-of-inputs Generate idiomatic @oneOf input types (tagged-union inputs) false
--custom-scalar <Scalar=target> Map a GraphQL custom scalar to a TS type. Repeatable. See Custom scalar mappings -
--base-url-env <name> Environment variable name for base URL REACT_APP_API_BASE_URL
--tanstack-query Generate TanStack Query hooks (useQuery/useMutation) false
--error-handling Smart error handling based on HTTP status semantics false
--retries <max-attempts> Enable retries with exponential backoff (status codes 429, 503) -
--documentation Generate JSDoc comments from SDL descriptions false
--date-transformation Convert Date-typed scalar fields (e.g. DateTime) in responses to Date objects false
--options-threshold <n> Parameter count for options object 4
--service-suffix <suffix> Service naming suffix Api
--types-barrel Emit an index.ts barrel per folder plus a root index.ts false
--clean Clean output directory (remove files not in generation) false
--verbose Enable verbose logging false
--help, -h Show help message -

Generated Code Structure

output/
  ├── models/                       # One file per type (object, input, enum, union)
  │   ├── user.ts                   # export interface User { ... }
  │   ├── role.ts                   # export type Role = 'ADMIN' | 'MEMBER' | ...
  │   ├── scalars.ts                # custom scalar type aliases
  │   └── ...
  ├── services/                     # One file per root operation type
  │   ├── query.api.ts              # query operations (+ hooks with --tanstack-query)
  │   ├── mutation.api.ts           # mutation operations
  │   ├── subscription.api.ts       # subscription operations
  │   └── fragments.ts              # (with --fragments) reusable named fragments
  ├── client.ts                     # ApiClient, createClient, getDefaultClient, executeGraphQL<T>
  └── errors.ts                     # GraphQLError / HttpError helpers

Each operation collapses to a one-line call to the shared executeGraphQL<T> helper in client.ts, which owns the POST /graphql request and the data/errors envelope handling.

Features in depth

TanStack Query hooks

npx @metaengine/graphql-react schema.graphql ./src/api --tanstack-query

Generates useQuery/useMutation hooks in the services/*.api.ts files alongside the plain async functions. Requires @tanstack/react-query in your project.

Reusable fragments

npx @metaengine/graphql-react schema.graphql ./src/api --fragments

Emits services/fragments.ts with one named fragment per object type. Operation selections reference fragment spreads (...UserFields) instead of repeating field sets.

@oneOf inputs

npx @metaengine/graphql-react schema.graphql ./src/api --one-of-inputs

Renders @oneOf input types as idiomatic TypeScript discriminated unions where exactly one member may be set. Without the flag, the input renders as a plain interface with all-optional fields.

Subscriptions

Subscription operations are generated into services/subscription.api.ts. The generated client accepts the WebSocket endpoint at runtime via ClientConfig.graphqlWsUrl.

Smart error handling

npx @metaengine/graphql-react schema.graphql ./src/api --error-handling

Adds an errorHandling config to ClientConfig with smart HTTP-status routing — 403 / 404 resolve to null, 400 / 409 / 422 return the error body, 401 / 500 / 502 / 503 throw.

Retries

npx @metaengine/graphql-react schema.graphql ./src/api --retries 3

Adds a retry config to ClientConfig that reattempts retryable responses (429, 503) up to the given number of attempts with exponential backoff.

Custom scalar mappings

GraphQL custom scalars resolve to idiomatic TypeScript types. Well-known scalars are mapped out of the box; any other custom scalar defaults to string.

GraphQL scalar TypeScript type
DateTime, Date, Time, DateTimeOffset Date
Decimal, Long, BigInt, ULong, UInt, Short, Byte number
UUID, Guid, Email, URL, URI string

Use --custom-scalar to override the TS type emitted for a scalar. Repeatable. Unsupported targets are hard errors — no silent fallbacks.

Target Emitted TS type
string string
number number
boolean boolean
Date Date 
npx @metaengine/graphql-react schema.graphql ./src/api \
  --custom-scalar DateTime=string \
  --custom-scalar UUID=string

Integer-like scalars (Long, BigInt, ULong) map to number by design so values carried in request variables survive JSON.stringify. A bigint target is therefore not offered.

See it live

Try the generator with your own schema at https://www.metaengine.eu/converters.

Programmatic Usage

The NuGet package allows programmatic use in .NET projects. See the website documentation for full C# API reference.

Support

License

MIT License - see LICENSE file for details.

About This Repository

This is the documentation and issue tracking repository for MetaEngine GraphQL React. The compiled NPM package is available at @metaengine/graphql-react.

Source code is proprietary, but the package is free to use under MIT license.