Configuration Schema

Complete reference for all configuration options in typed-fetch.config.json.

Full Schema

{
  "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
}

Property Reference

`registryPath`

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

Path where response observations are stored.

{
  "registryPath": ".typed-fetch/registry.json"
}

Notes:

Relative path from project root
Stores endpoint observations and response shapes
Safe to commit to version control
Contains no raw response data

Examples:

{ "registryPath": ".typed-fetch/registry.json" }

{ "registryPath": "./api/.typed-fetch/registry.json" }

{ "registryPath": "/var/typed-fetch/registry.json" }

`generatedPath`

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

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 by reading your tsconfig chain.

{
  "generatedPath": "src/generated/typed-fetch.d.ts"
}

Notes:

Relative path from project root
Generated by npx typed-fetch generate or automatically during typed-fetch watch
Contains TypeScript module augmentation
Should be committed to version control

Examples:

{ "generatedPath": "src/generated/typed-fetch.d.ts" }

{ "generatedPath": "./src/types/api.d.ts" }

{ "generatedPath": "app/generated/typed-fetch.d.ts" }

`include`

Type: string[]
Default: [] (include all)
Required: No

Glob patterns for endpoints to include in observations.

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

When empty, all endpoints are included. When specified, only matching endpoints are observed.

Examples:

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

{ "include": ["https://api.example.com/**"] }

{ "include": ["**"] }

`exclude`

Type: string[]
Default: [] (exclude nothing)
Required: No

Glob patterns for endpoints to exclude from observations.

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

Useful for:

Excluding health check endpoints
Skipping metrics/monitoring endpoints
Avoiding internal endpoints

Examples:

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

{ "exclude": ["**/test/**"] }

`dynamicSegmentPatterns`

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

Patterns used to normalize dynamic URL segments.

{
  "dynamicSegmentPatterns": ["numeric", "uuid", "hash"]
}

Available patterns:

"numeric": Matches numbers (e.g., /user/123 → /user/:id)
"uuid": Matches UUID format (e.g., /post/550e8400-e29b-41d4-a716-446655440000)
"hash": Matches hash-like strings (e.g., /file/abc123def)

Purpose:

Prevent registry pollution with unique-per-request segments
Group similar requests under one endpoint pattern
Improve type stability

`maxDepth`

Type: number
Default: 8
Required: No

Maximum depth when inferring nested object structures.

{
  "maxDepth": 8
}

Notes:

Minimum recommended: 2
Maximum recommended: 20
Increase if you have deeply nested API responses
Decrease if types are too complex

`maxArraySample`

Type: number
Default: 32
Required: No

Maximum number of array items to sample when inferring array element types.

{
  "maxArraySample": 32
}

Notes:

Minimum: 1
Only first N items are examined
Doesn't limit returned array sizes, only sampling during inference

`ignoreFieldNames`

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

Field names that should be ignored during observation.

{
  "ignoreFieldNames": ["password", "token", "secret"]
}

Purpose:

Privacy: Exclude sensitive fields
Security: Prevent credentials from being tracked
Compliance: Meet data handling regulations

Common fields to ignore:

{
  "ignoreFieldNames": [
    "password",
    "token",
    "secret",
    "authorization",
    "creditCard",
    "ssn",
    "apiKey",
    "privateKey",
    "refreshToken",
    "sessionId"
  ]
}

Behavior:

Ignored fields are not analyzed during observation
Do not appear in generated types
Not stored in the registry

`strictPrivacyMode`

Type: boolean
Default: true
Required: No

When enabled, raw observed request paths are not stored.

{
  "strictPrivacyMode": true
}

Enabled (true):

Only response structure is stored
Exact URLs are normalized to patterns
Safe for projects with sensitive URLs
Recommended default

Disabled (false):

Full URL paths are stored
More detailed debugging information
Use only in internal/private environments

`observerMode`

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

Controls how observations are recorded.

{
  "observerMode": "auto"
}

Options:

"auto": Node.js writes directly to the registry file; browsers POST observations to the local observer server (started by typed-fetch watch)
"file": Always write to file. Node.js only — browser calls are silently skipped
"http": Always POST to the observer server. Useful when you want to explicitly force the HTTP path
"none": Disable all observation. Use in production where types are already generated

Use cases:

Standard development (recommended):

{ "observerMode": "auto" }

Node.js-only backend:

{ "observerMode": "file" }

Production — generated types only, no new observations:

{ "observerMode": "none" }

`observerPort`

Type: number
Default: 7779
Required: No

Port for the local HTTP observer server started by typed-fetch watch.

{
  "observerPort": 7779
}

When observerMode is "auto" or "http", browser runtimes POST observations to http://localhost:{observerPort}/__typed-fetch/observe. The watch command starts this server automatically — no separate setup required.

Change this if port 7779 conflicts with another service on your machine:

{
  "observerPort": 8888
}

Validation

Configuration is validated by CLI commands:

npx typed-fetch check

Returns errors if:

Required fields are missing
Invalid values (wrong types)
Invalid glob patterns
File paths that don't exist (for registryPath)

Examples

Basic Setup

{
  "registryPath": ".typed-fetch/registry.json",
  "generatedPath": "src/generated/typed-fetch.d.ts"
}

Privacy-First Production

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

Monorepo with API Isolation

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

Custom Observer Port

{
  "registryPath": ".typed-fetch/registry.json",
  "generatedPath": "src/generated/typed-fetch.d.ts",
  "observerMode": "auto",
  "observerPort": 8888
}

Next: Examples

Explore practical React Integration examples.

Configuration Schema

On this page