Configuration Overview

GenX API reads a single JSON, YAML, or TypeScript configuration file and maps that unified interface onto the selected template. This page provides a narrative overview and links to the full schema reference.

• Supported files today: genxapi.config.json, genxapi.config.yaml, genxapi.config.yml, genxapi.config.ts, plus genxapirc* JSON/YAML/TS variants.
• Unified schema: One set of fields expresses generator intent (httpClient, client, mode, mock, plugin overrides). The CLI maps these options onto the selected template.
• Contract workflow: Use clients[].swagger for the shorthand form or clients[].contract when you need authenticated remote fetches, snapshots, and checksums.
• Template selection: project.template accepts the aliases "orval" and "kubb", full package names, or an explicit external template reference object.
• Per-client overrides: clients[].config can override any project-level option.
• CLI flags: --template, --http-client, --client, --mode, --mock-*, and --base-url mirror their config counterparts for one-off runs or CI jobs.

For the full JSON Schema, mapping tables, and advanced examples read the dedicated guide:

📘 Unified generator config

Below is a trimmed example highlighting the most common fields:

{
  "$schema": "https://raw.githubusercontent.com/genxapi/genxapi/main/packages/cli/schemas/genxapi.schema.json",
  "logLevel": "info",
  "project": {
    "name": "multi-client-demo",
    "directory": "../examples/multi-client-demo",
    "template": "orval",
    "output": "./src",
    "config": {
      "httpClient": "axios",
      "client": "react-query",
      "mode": "split",
      "mock": { "type": "msw", "delay": 250 }
    }
  },
  "clients": [
    {
      "name": "pets",
      "contract": {
        "source": "https://petstore3.swagger.io/api/v3/openapi.json",
        "snapshot": true,
        "checksum": true
      },
      "config": { "baseUrl": "https://api.pets.local" }
    },
    {
      "name": "store",
      "swagger": "https://petstore3.swagger.io/api/v3/openapi.json",
      "config": {
        "client": "axios",
        "httpClient": "axios",
        "mock": { "type": "off" }
      }
    }
  ],
  "hooks": {
    "beforeGenerate": ["npm run lint"],
    "afterGenerate": ["npm test"]
  }
}

Optional automation blocks such as project.repository and project.publish can be added when you want post-generation sync or publishing.

Response to CLI overrides

Any CLI flags you pass are merged after config parsing, so the following command:

npx genxapi generate \
  --template kubb \
  --http-client fetch \
  --mock-type msw \
  --mock-delay 1000

forces the kubb template, switches the HTTP client to fetch, and enables MSW mocks with a 1s delay—even if the config file requested different defaults.

Migrating from legacy configs

Earlier versions required template-specific sections (clients[].orval / clients[].kubb). Those blocks still work, but the generator now prefers the unified shape. To migrate:

• Move common options into project.config.
• Replace clients[].orval or clients[].kubb with clients[].config.
• Set project.template to "orval" or "kubb" (or an explicit external template reference if you own a custom template contract).
• Delete redundant output.workspace/target fields if you want the orchestrator to derive them from project.output.

The CLI will continue to resolve the legacy format, but new features (HTTP client overrides, advanced mock settings, plugin merges) are only available via the unified schema.

For secure remote contract auth, snapshotting, and manifest output, read Unified generator config and Generation manifest.