npm NuGet v1.0.0 MIT

@metaengine/openapi-fetch

OpenAPI 3.x → framework-agnostic TypeScript services over native Fetch. Zero dependencies, tree-shakeable, runs on Node, browsers, Vite, SvelteKit, and Next.js.

OpenAPI 3.xMetaEngine IRTypeScript · Fetch
Install

Pick your registry

The same generator, published to every ecosystem we support. Install however your project expects.

npmPrimary@metaengine/openapi-fetch
$npm install @metaengine/openapi-fetch
v1.0.0
NuGetMetaEngine.TypeScript.OpenApi.Fetch
$dotnet add package MetaEngine.TypeScript.OpenApi.Fetch
v1.0.0
Usage

Drive it from the CLI or programmatically

npm ships a zero-config CLI. NuGet ships the same generator as a C# fluent API — same options, same output.

npm · npx · CI-friendly

After install, point the CLI at your OpenAPI spec. It writes the generated tree to your chosen output directory.

Basic syntax
terminal
npx @metaengine/openapi-fetch <input> <output> [options]

Supports OpenAPI 3.0+ specifications in both JSON and YAML formats.

Quick examples
Generate from a local file
npx @metaengine/openapi-fetch api.yaml ./src/api
Generate from a URL
npx @metaengine/openapi-fetch https://api.example.com/openapi.json ./src/api
With Vite, result pattern and middleware
npx @metaengine/openapi-fetch api.yaml ./src/api \
  --import-meta-env \
  --base-url-env VITE_API_URL \
  --result-pattern \
  --middleware \
  --documentation
Production setup with auth, retries and timeout
npx @metaengine/openapi-fetch api.yaml ./src/api \
  --bearer-auth API_TOKEN \
  --custom-header X-Tenant-ID=TENANT_ID \
  --timeout 30 \
  --retries 3 \
  --error-handling
CLI options
Option
Description
--base-url-env <name>
Environment variable name for base URL [default: API_BASE_URL]
--service-suffix <suffix>
Service naming suffix [default: Api]
--options-threshold <n>
Parameter count to use options object [default: 4]
--documentation
Generate JSDoc comments
--import-meta-env
Use import.meta.env for env access (Vite, SvelteKit, Next.js 15+)
--result-pattern
Return ApiResult<T> instead of T for structured error handling
--middleware
Emit onRequest / onResponse / onError hooks in the generated client
--error-handling
Enable smart error handling based on HTTP status semantics
--bearer-auth <env-var-name>
Bearer token from env var (adds Authorization header to all requests)
--timeout <seconds>
Request timeout in seconds for all operations
--retries <max-attempts>
Enable retries with exponential backoff (status 429, 503)
--custom-header <header=envVarName>
Static header from env var. Repeatable (e.g. X-Tenant-ID=TENANT_ID)
--type-mapping <mapping>
Override TS type for an OpenAPI format. Repeatable. int64=bigint · decimal=string · date-time=string · date=string
--include-tags <tags>
Filter by OpenAPI tags (comma-separated, case-insensitive)
--strict-validation
Enable strict OpenAPI validation
--date-transformation
Convert date strings in responses to JavaScript Date objects
--clean
Clean output directory (remove files not in generation)
--verbose
Enable verbose logging
--help, -h
Show help message
Options reference

Every knob, documented

Every option is available on the CLI as a flag and on the programmatic C# API as a fluent method. Defaults shown in the right column.

Fetch Options

18
  • WithBaseUrlEnvVar(string)Environment variable name for base URL (default: "API_BASE_URL"). Enables getDefaultClient() lazy singleton.
  • WithImportMetaEnv()Use import.meta.env instead of process.env (Vite, SvelteKit, Next.js 15+)
  • WithResultPattern()Return ApiResult<T> for structured error handling without exceptions
  • WithMiddleware()Emit onRequest / onResponse / onError hooks in the generated client
  • WithErrorHandling()Enable smart error handling based on HTTP status semantics
  • WithErrorHandling(Action)Custom error handling per status code
  • WithBearerAuth(string)Bearer token from env var (default: "API_TOKEN") — adds Authorization header
  • WithBearerAuth(string, string)Bearer token with custom header name
  • WithCustomHeader(string, string)Static header from env var. Repeatable (e.g. X-Tenant-ID ← TENANT_ID)
  • WithTimeout(double)Request timeout in seconds for all operations
  • WithTimeout(double?, double?, ...)Granular timeout for connect / read / write / pool
  • WithRetries()Retries with exponential backoff (status 429, 503)
  • WithRetries(int)Retries with custom max attempts
  • WithRetries(int, double, double, int[])Retries with full custom settings
  • WithMethodNames(Func)Custom method naming rule
  • WithDocumentation()Enable JSDoc comments
  • WithOptionsObjectThreshold(int)Parameter count for options object (default: 4)
  • WithResponseDateTransformation()Convert date/date-time strings in responses to Date objects

OpenAPI Filtering

3
  • WithStrictValidation()Enable strict OpenAPI validation
  • WithOperationFilter(Func)Filter operations by predicate
  • WithHeaderFilter(Func)Filter header parameters

Naming Transformations

3
  • Types(Func)Transform type names
  • Paths(Func)Transform output paths
  • FileNames(Func)Transform file names

File Management

5
  • CleanDestination()Clean output directory before generation
  • AlwaysOverwrite()Always overwrite existing files
  • OnlyWhenModelChanged()Update only when model changes
  • OnlyWhenNew()Write only new files, preserve existing
  • CleanDirectories(...)Clean specific subdirectories

Diagnostics

1
  • EnableVerboseLogging()Enable detailed logging
Features

Why this package is different

Deterministic output
Same spec + same options produce byte-identical files. Safe to commit, safe to diff in review, safe to cache in CI.
Tree-shakeable
One file per tag (or per operation) means bundlers drop unused code at build time. No runtime dispatch table.
Zero runtime
Validation and clients opt in. The default emit is pure types with no dependency surface beyond your HTTP lib.
Flexible naming
Case conventions configurable per role — types, properties, operations, enums. Idiomatic in the target by default.
Type resolution
Discriminated unions for oneOf, proper nullability, bigint when the spec mandates it, refs flattened only when safe.
Semver-honest
Spec diff drives the version bump. Additive changes = minor, removed ops = major. Never a surprise in your lockfile.