@metaengine/graphql-fetch

Generate TypeScript services and models from GraphQL schemas using the native Fetch API.

Typed queries, mutations & subscriptions — framework-agnostic, runs on Node, browsers, Vite, SvelteKit, Next.js, and any TS runtime that ships fetch.

Install

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

Or use directly with npx:

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

Requirements

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

Quick start

npx @metaengine/graphql-fetch schema.graphql ./src/api \
  --documentation \
  --fragments

Production setup

npx @metaengine/graphql-fetch schema.graphql ./src/api \
  --bearer-auth API_TOKEN \
  --timeout 30 \
  --retries 3 \
  --custom-header X-Tenant-ID=TENANT_ID \
  --error-handling

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 (e.g. VITE_API_URL, NEXT_PUBLIC_API_URL) | API_BASE_URL | | --import-meta-env | Use import.meta.env for env access (Vite, SvelteKit) | false | | --result-pattern | Return ApiResult<T> instead of T for structured error handling | false | | --middleware | Emit middleware hooks (onRequest, onResponse, onError) in client | false | | --error-handling | Smart error handling based on HTTP status semantics | false | | --retries <max-attempts> | Enable retries with exponential backoff (status codes 429, 503) | - | | --bearer-auth <env-var-name> | Bearer token from env var (adds Authorization: Bearer <token>) | - | | --timeout <seconds> | Request timeout in seconds for all operations | - | | --custom-header <header=envVarName> | Static header from env var. Repeatable. | - | | --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 | Service | | --types-barrel | Emit an index.ts barrel per folder plus a root index.ts re-exporting everything | false | | --clean | Clean output directory (remove files not in generation) | false | | --verbose | Enable verbose logging | false | | --help, -h | Show help message | - |

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.

| Target | Emitted TS type | |--------|-----------------| | string | string | | number | number | | boolean | boolean | | Date | Date |

npx @metaengine/graphql-fetch schema.graphql ./src/api \
  --custom-scalar DateTime=string \
  --custom-scalar UUID=string

Integer-like scalars (Long, BigInt, ULong) map to number by design so request variables survive JSON.stringify.

See it live

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

License

MIT

Support

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