@medusajs/http-types-generator

CLI tool that generates and validates TypeScript HTTP types from Zod validator schemas.

How it works

The tool scans validator files, extracts exported Zod schemas, resolves their TypeScript types, and emits interface declarations into output files. It can also check whether existing HTTP type files are structurally compatible with their corresponding Zod schemas.

Usage in the Medusa monorepo

Run from the repo root using the workspace scripts:

# Generate types for a domain
yarn generate:http-types --domain products --dry-run
yarn generate:http-types --domain products

# Validate all types
yarn validate:http-types

# Validate a single domain
yarn validate:http-types --domain products --verbose

The repo root's http-types.config.json configures the Medusa-specific paths automatically — no additional setup is needed.

Commands

generate

Generates TypeScript interface files from Zod schemas.

yarn generate:http-types [options]

| Option | Description | Default | |---|---|---| | --area <area> | Area to process. Must match a key in validatorGlobs (store or admin for monorepo), or all for every area. | all | | --domain <domain> | Limit to a specific domain (route directory name). | — | | --dry-run | Print what would be generated without writing files. | false | | --force | Overwrite existing files instead of merging. | false | | --verbose | Print each processed schema. | false |

validate

Checks that existing HTTP types are structurally compatible with their Zod schemas.

yarn validate:http-types [options]

| Option | Description | Default | |---|---|---| | --area <area> | Area to validate. | all | | --domain <domain> | Limit to a specific domain. | — | | --changed-files <paths> | Comma-separated list of changed validator files (CI optimisation). | — | | --lenient | Treat T \| null \| undefined as compatible with T \| undefined. | false | | --ci | Exit with code 1 if any failures are found. | false | | --verbose | Show passing types in addition to failures. | false |

General usage

Installation

npm install --save-dev @medusajs/http-types-generator
# or run without installing:
npx @medusajs/http-types-generator generate

Configuration

Place an http-types.config.json file in your project root. All fields are optional and are deep-merged over the defaults.

{
  "validatorGlobs": {
    "admin": "src/api/admin/*/validators.ts",
    "store": "src/api/store/*/validators.ts"
  },
  "outputBase": "src/types/http",
  "tsconfig": "tsconfig.json",
  "importSources": {
    "commonRequest": "@medusajs/framework/types",
    "dal": "@medusajs/framework/types"
  },
  "validatorPathPattern": "/api/([^/]+)/([^/]+)/validators\\.ts$",
  "publicPrefixes": ["Admin", "Store"]
}

| Field | Description | Default | |---|---|---| | validatorGlobs | Glob patterns (relative to project root) keyed by area name. | { admin: "**/api/admin/*/validators.ts", store: "**/api/store/*/validators.ts" } | | outputBase | Root directory for generated files, relative to project root. | "src/types/http" | | tsconfig | tsconfig filename at the project root used when creating the TypeScript program. | "tsconfig.json" | | importSources.commonRequest | Module that exports FindParams and SelectParams. | "@medusajs/framework/types" | | importSources.dal | Module that exports BaseFilterable and OperatorMap. | "@medusajs/framework/types" | | validatorPathPattern | Regex (no surrounding /) with two capture groups: (area, routeDir). | "/api/([^/]+)/([^/]+)/validators\\.ts$" | | publicPrefixes | Only schemas whose name starts with one of these prefixes are processed. | ["Admin", "Store"] |

The config file is found by searching upward from the working directory, so it works whether the CLI is invoked from the project root or a subdirectory.

Validator file conventions

Schemas must be exported from a validators.ts file whose path matches validatorPathPattern. The pattern must have two capture groups: area and route directory.

src/api/admin/products/validators.ts  →  area=admin, routeDir=products

Export names must start with one of the publicPrefixes. The suffix determines the output file:

• Matches Params, Filters → queries.ts
• Matches Create, Update, Batch, etc. → payloads.ts
• Everything else defaults to payloads.ts

Running with npx

# Generate
npx @medusajs/http-types-generator generate --dry-run
npx @medusajs/http-types-generator generate --domain products

# Validate
npx @medusajs/http-types-generator validate
npx @medusajs/http-types-generator validate --ci