@reasonhealth/fhir-ts-codegen

General-purpose CLI and library that reads FHIR NPM packages and emits either TypeScript .d.ts declarations or Zod schemas. Works with any FHIR IG package, not just the core specification.

Requirements

• Bun ≥ 1.0

CLI

Config-file mode

Point at a generate.config.ts to run multiple packages in one pass:

bun run src/cli.ts --config path/to/generate.config.ts

Single-shot mode

# TypeScript declarations
bun run src/cli.ts \
  --package hl7.fhir.r4.core \
  --package-version 4.0.1 \
  --fhir-version r4 \
  --emit typescript \
  --namespace fhir4 \
  --out ./r4.d.ts \
  --test-out ./tests/r4-tests.ts  # optional

# Zod schemas
bun run src/cli.ts \
  --package hl7.fhir.r4.core \
  --package-version 4.0.1 \
  --fhir-version r4 \
  --emit zod \
  --out ./r4-schemas.ts

| Flag | Description | |------|-------------| | --package | FHIR NPM package ID (e.g. hl7.fhir.r4.core) | | --package-version | Package version (e.g. 4.0.1) | | --fhir-version | One of r2 r3 r4 r4b r5 | | --emit | typescript or zod | | --out | Output file path | | --namespace | UMD namespace name (TypeScript emit only, e.g. fhir4) | | --test-out | DefinitelyTyped test file output path (TypeScript emit only) | | --profiles | Comma-separated profile canonical URLs — enables profile-only mode | | --import-base-from | Module path to import base schemas from (Zod profile mode, default: ./r4) | | --config | Path to a generate.config.ts (replaces all other flags) |

Profile mode

Generate types for a single FHIR profile without touching the base type files:

# Zod — imports base schemas from ./r4
bun run src/cli.ts \
  --package hl7.fhir.r4.core \
  --package-version 4.0.1 \
  --fhir-version r4 \
  --emit zod \
  --profiles "http://hl7.org/fhir/StructureDefinition/bp" \
  --out ./r4-bp.ts

# TypeScript — emits a declare namespace augmentation of fhir4
bun run src/cli.ts \
  --package hl7.fhir.r4.core \
  --package-version 4.0.1 \
  --fhir-version r4 \
  --emit typescript \
  --namespace fhir4 \
  --profiles "http://hl7.org/fhir/StructureDefinition/bp" \
  --out ./r4-bp.d.ts

Zod output (r4-bp.ts): imports base schemas from ./r4, exports ObservationBpSchema / ObservationBp with profile constraints applied (required fields required, array minimums enforced).

TypeScript output (r4-bp.d.ts): emits a declare namespace fhir4 { ... } block. Type references like Reference and CodeableConcept resolve to other members of the same namespace — no imports needed. Include alongside @types/fhir via a triple-slash reference:

/// <reference types="@types/fhir" />
/// <reference path="./r4-bp.d.ts" />

Config file format

import type { GenerateConfig } from '@reasonhealth/fhir-ts-codegen'

const config: GenerateConfig = {
  entries: [
    {
      packageId: 'hl7.fhir.r4.core',
      packageVersion: '4.0.1',
      fhirVersion: 'r4',
      emit: 'typescript',
      namespace: 'fhir4',          // required for typescript emit
      outFile: './r4.d.ts',
      testOutFile: './test/r4-tests.ts',  // optional
    },
    {
      packageId: 'hl7.fhir.r4.core',
      packageVersion: '4.0.1',
      fhirVersion: 'r4',
      emit: 'zod',
      outFile: './src/r4.ts',
    },
    // Profile-only entries
    {
      packageId: 'hl7.fhir.r4.core',
      packageVersion: '4.0.1',
      fhirVersion: 'r4',
      emit: 'zod',
      outFile: './src/r4-bp.ts',
      profilesOnly: true,
      includeProfiles: ['http://hl7.org/fhir/StructureDefinition/bp'],
      importBaseFrom: './r4',       // base schemas to import from (default: './r4')
    },
    {
      packageId: 'hl7.fhir.r4.core',
      packageVersion: '4.0.1',
      fhirVersion: 'r4',
      emit: 'typescript',
      namespace: 'fhir4',
      outFile: './r4-bp.d.ts',
      profilesOnly: true,
      includeProfiles: ['http://hl7.org/fhir/StructureDefinition/bp'],
    },
  ],
  // optional: generates an index.d.ts with /// <reference> entries for typescript emits
  indexOutFile: './index.d.ts',
}

export default config

Package resolution

Packages are resolved in this order — no manual download needed in most cases:

1. Project cache — .fhir-cache/ in the working directory
2. System cache — ~/.fhir/packages/ (populated by FHIR IG Publisher and other tools)
3. Download — fetched from https://packages.fhir.org and stored in the project cache

Library API

import { generate } from '@reasonhealth/fhir-ts-codegen'

await generate({
  packageId: 'hl7.fhir.r4.core',
  packageVersion: '4.0.1',
  fhirVersion: 'r4',
  emit: 'zod',
  outFile: '/tmp/r4-schemas.ts',
})

IR types are also exported for building custom emitters:

import type { IrModel, IrInterface, IrField } from '@reasonhealth/fhir-ts-codegen'

Architecture

StructureDefinition JSON (from FHIR NPM package)
        │
        ▼
   src/parser/
   ─ Backbone hoisting      PatientContact extends BackboneElement
   ─ Choice types [x]       deceasedBoolean + deceasedDateTime
   ─ Inline enum resolution  ('male'|'female'|'other'|'unknown')
   ─ contentReference        → isLazy: true
        │
        ▼
   Intermediary Representation (src/ir.ts)
        │
        ├──▶ src/emitter/typescript.ts  → .d.ts declarations
        └──▶ src/emitter/zod.ts         → z.object() schemas

Development

bun run typecheck

Supported By

This project is proudly supported by Vermonster / ReasonHealth.