Configuration

Configuration for typed-fetch is defined in typed-fetch.config.json at your project root.

Default Configuration

{
  "registryPath": ".typed-fetch/registry.json",
  "generatedPath": "src/generated/typed-fetch.d.ts",
  "include": [],
  "exclude": [],
  "dynamicSegmentPatterns": ["numeric", "uuid", "hash"],
  "maxDepth": 8,
  "maxArraySample": 32,
  "ignoreFieldNames": ["password", "token", "secret", "authorization"],
  "strictPrivacyMode": true,
  "observerMode": "auto",
  "observerPort": 7779
}

Options

registryPath

Type: string
Default: .typed-fetch/registry.json

Path where response shape observations are stored. This file tracks all observed endpoints and their response structures.

generatedPath

Type: string
Default: src/generated/typed-fetch.d.ts

Output path for generated TypeScript type definitions. Must be within a directory covered by your tsconfig include paths — running typed-fetch init auto-detects the correct path for your project.

include

Type: string[]
Default: []

Glob patterns to include for observation. If empty, all endpoints are included. Example:

{
  "include": ["**/api/**", "**/graphql/**"]
}

exclude

Type: string[]
Default: []

Glob patterns to exclude from observation. Example:

{
  "exclude": ["**/health/**", "**/metrics/**"]
}

dynamicSegmentPatterns

Type: string[]
Default: ["numeric", "uuid", "hash"]

Patterns used to automatically normalize dynamic segments in URLs. Supported patterns:

• numeric: Matches numeric IDs (e.g., /user/123 → /user/:id)
• uuid: Matches UUID patterns
• hash: Matches hash-like strings

maxDepth

Type: number
Default: 8

Maximum depth when inferring nested object structures. Prevents deeply nested types from becoming unwieldy.

maxArraySample

Type: number
Default: 32

Maximum number of array items to sample when inferring array element types. Prevents sampling very large arrays.

ignoreFieldNames

Type: string[]
Default: ["password", "token", "secret", "authorization"]

Field names that should be ignored when observing responses. Useful for privacy — these fields are not analyzed or tracked.

strictPrivacyMode

Type: boolean
Default: true

When enabled (default), raw observed request paths are not stored in the registry — only the structure is recorded. This protects against leaking sensitive URL patterns.

observerMode

Type: "auto" | "file" | "http" | "none"
Default: "auto"

Controls how observations are recorded:

• "auto": Node.js writes directly to the registry file; browsers POST to the local observer server
• "file": Always write to file (Node.js only)
• "http": Always POST to the observer server (explicit browser mode)
• "none": Disable observation entirely (use in production)

observerPort

Type: number
Default: 7779

Port for the local HTTP observer server started by typed-fetch watch. Browser runtimes post observations here when observerMode is "auto" or "http". Change this if port 7779 is already in use on your machine.

Using Custom Config Path

All CLI commands accept a --config flag for custom config locations:

npx typed-fetch generate --config ./config/typed-fetch.json

This is useful for monorepos or when you need multiple configurations.

Example: Monorepo Setup

{
  "registryPath": "./api/.typed-fetch/registry.json",
  "generatedPath": "./api/src/generated/types.d.ts",
  "include": ["**/api/**"],
  "exclude": ["**/test/**", "**/node_modules/**"]
}

Example: Privacy-First Production Setup

{
  "registryPath": "./.typed-fetch/registry.json",
  "generatedPath": "./src/generated/typed-fetch.d.ts",
  "strictPrivacyMode": true,
  "observerMode": "none",
  "ignoreFieldNames": [
    "password",
    "token",
    "secret",
    "authorization",
    "creditCard",
    "ssn",
    "apiKey"
  ]
}

Next: CLI Commands

Learn about available CLI Commands.