BabelFHIR-TS

Generate production-ready TypeScript from FHIR® StructureDefinitions — typed interfaces, runtime validators, and FHIR clients.

BabelFHIR-TS transforms FHIR® StructureDefinitions into production-ready TypeScript code with full type safety and built-in validation. BabelFHIR-TS generates profile-aware interfaces that understand your Implementation Guide's constraints, extensions, and slicing rules.

What you get

• Strongly typed interfaces that merge profile constraints with base FHIR types (types come from @types/fhir)
• Compiled output by default — packages ship JavaScript (.js) plus TypeScript declarations (.d.ts)
• Runtime validation using FHIRPath expressions from the profile—no external validator required for basic checks
• Type-safe extension handling with proper slicing and nested extension support
• Random data builders for testing and development (when class generation is enabled)
• Zero manual mapping—consume any FHIR package or Implementation Guide directly from registries
• Fast and lightweight—the CLI pulls no FHIRPath engine of its own; generated packages declare fhirpath as a peer dependency (>=4.9.1 <6), so the host app owns the version
• Type-safe FHIR client — generated client extends @babelfhir-ts/client-r4 / client-r4b / client-r5 with profile-specific methods (e.g., .uSCorePatientProfile(), .pASClaim()) on top of base resource accessors
• Install any FHIR profile as a node module—use babelfhir-ts install to add Implementation Guides (FHIR Packages) directly to your project

Installation

npm install -g babelfhir-ts

Or on-demand: npx babelfhir-ts --help

Requirements: Node.js 18+ and an internet connection for remote registries.

Quick Start

# Generate from a local folder
babelfhir-ts input/ output/

# Download and process from a registry
babelfhir-ts --package hl7.fhir.us.core@8.0.0

# Install as a project dependency
babelfhir-ts install hl7.fhir.us.core@8.0.0

import { USCorePatientProfileClass } from "./output/USCorePatientProfileClass";

const patient = USCorePatientProfileClass.random();
const { errors, warnings } = await patient.validate();

CLI Reference

BabelFHIR-TS: Generate TypeScript interfaces from FHIR StructureDefinitions

Usage:
  babelfhir-ts [options] [<input> [output]]
  babelfhir-ts install [--package] <pkg[@version]|path> [--registry <url>] [options]
  babelfhir-ts update [<pkg@version>] [--recursive] [options]

Arguments:
  input   Input can be:
          - Canonical URL of a FHIR profile (http://... or https://...)
          - Directory containing FHIR packages (.tgz/.zip files)
          - Single FHIR package (.tgz/.zip file)
          - Single StructureDefinition (.json file)
          - Directory containing StructureDefinition files
  output  Output directory or archive name (optional)

Commands:
  install                Download, process, and npm install package as dependency
  update                 Regenerate all installed packages (or a specific one) with current babelfhir-ts

Options:
  -h, --help               Show this help message
  -v, --version            Show version number
  --log <dest>             Log destination: console (default) or file
  --log-level <level>      Log verbosity: error, warn, info (default), or debug
  --cache-dir <path>       Custom cache directory (default: ~/.fhir/packages for FHIR packages, .cache for working files)
  --no-cache               Delete .cache working folder after generation (does not affect shared ~/.fhir/packages)
  --no-classes             Only generate interfaces and types (skip class generation)
  --no-client              Skip FHIR client generation (client generated by default)
  --schema <format>        Generate schema files alongside outputs (supported: zod)
  --zod-invariants         Emit FHIRPath invariants into Zod schemas (fuller checking, slower parse)
  --dicomweb               Generate DICOMweb helpers typed to ImagingStudy profiles in the IG
  --prefab                 Generate Prefab UI render functions per profile (@maxhealth.tech/prefab)
  --prefab-styles <path>   Path to styles module (.ts/.js) copied into the generated prefab/ folder
  --recursive              (update only) Recursively search subdirectories for lib/ folders
  --force                  (update only) Force regeneration even if version and flags haven't changed
  --skip-install           (install only) Generate tarball without running package manager install
  --outDir <dir>           Output directory (alias for second positional argument)
  --fhir-version <ver>     FHIR version to target: r4, r4b, or r5 (auto-detected from package if omitted)
  --package <pkg[@version]>  Download FHIR package from registry and process it (latest if no version)
  --registry <url>         FHIR package registry URL (default: https://packages.simplifier.net)
  --tx-server <url>        Terminology server URL for ValueSet expansion (e.g., https://tx.fhir.org/r4)
                           When set, expands ValueSets without explicit codes using $expand operation
  --display-language <lang> BCP-47 language(s) for display terms (e.g., de or de,fr,en).
                           Single value replaces concept displays. Comma-separated values
                           also generate a multi-language display map with getDisplay() helper.

Examples:
  babelfhir-ts                                             # Process ./input to ./output
  babelfhir-ts http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient  # Generate from profile URL
  babelfhir-ts package.tgz                                 # Process package to current directory
  babelfhir-ts package.tgz modified-package.tgz            # Embed interfaces in package
  babelfhir-ts profiles/ generated/                        # Process directory to directory
  babelfhir-ts --package hl7.fhir.us.core@8.0.0            # Download and process from default registry
  babelfhir-ts --package hl7.fhir.us.core@8.0.0 output/    # Download and output to directory
  babelfhir-ts --package pkg@version --log console --log-level debug  # With verbose logging
  babelfhir-ts install de.gematik.isik-basismodul                           # Download latest, process, and install
  babelfhir-ts install de.gematik.isik-basismodul@3.1.0                   # Download specific version
  babelfhir-ts install ./package.tgz                                      # Install from local package file
  babelfhir-ts install hl7.fhir.us.core@8.0.0 --registry <url>            # Install from custom registry
  babelfhir-ts install --package hl7.fhir.us.core@8.0.0 --registry <url>  # Alternative syntax
  babelfhir-ts update                                                      # Regenerate all packages in ./lib
  babelfhir-ts update hl7.fhir.us.core@8.0.0                               # Regenerate a specific package
  babelfhir-ts update --recursive                                          # Regenerate packages in all subdirectories

Documentation

Full documentation is available at max-health-inc.github.io/BabelFHIR-TS/docs/

• Getting Started — installation, quick start, first generation
• CLI Reference — full list of commands and options
• Generated Code Guide — understanding the output, module resolution, FHIR type imports
• FHIR Client — type-safe server interactions
• Validation — what validators check, CI pipelines, known Firely SDK issues
• Limitations — edge cases, random() caveats
• Contributing — dev setup, scripts, project structure

Continuous Validation

Every push to develop and main runs the parity pipeline, which validates generated code against real-world FHIR Implementation Guides. (Pull requests run the faster CI workflow: typecheck, unit tests, and generated-artifact drift checks.) For each IG, the pipeline:

1. Downloads the FHIR package from a registry
2. Generates TypeScript interfaces, validators, and classes
3. Compiles the output with tsc (zero errors required)
4. Generates empty() and random() test resources for every profile
5. Validates those resources against two independent external FHIR validators

Validated Implementation Guides (31)

Every parity run validates 31 real-world IGs (29 R4, 2 R5). The list is not duplicated here — it is generated from the parity suite's own source of truth into parity-matrix.json.

Each validated IG is also published as a ready-to-install package — @max-health-inc/fhir-<name> — so you do not have to generate it yourself:

→ Browse the FHIR IG registry

# GitHub Packages needs the scope mapped, and a token with read:packages
echo "@max-health-inc:registry=https://npm.pkg.github.com" >> .npmrc
npm install @max-health-inc/fhir-us-core

Published by Max-Health-Inc/fhir-igs, which pins a babelfhir-ts version and republishes an IG only when the IG version, the pinned generator, or the generation flags actually change.

Validation with the Firely SDK Validator

The firely job validates generated resources using the Firely SDK Validator (Firely.Fhir.Validation, v3.x) running on the Firely .NET SDK (Hl7.Fhir, v6.x) — two separately versioned packages. Results are published as live badges:

Per-IG results

Validation with HL7 Java Validator

The hl7 job validates the same artifacts using the official HL7 FHIR Validator, the reference implementation for FHIR conformance checking:

Per-IG results

External-validator badges cover the 29 R4/R4B IGs. R5 packages are generated and typechecked, but neither external validator publishes R5 badges yet.

Terminology validation requires a tx server. The pipeline uses --tx-server https://tx.fhir.org/{r4|r5} (matching the package's FHIR version) during generation to expand ValueSets and produce valid codes.

📊 Full Report

License

ISC © Maximilian Nussbaumer

Changelog

Release notes are published automatically on GitHub Releases: View all releases

Contributing

Contributions are welcome! See the Contributing guide for dev setup, scripts, and how to submit changes.

Security

For security issues, please see SECURITY.md for our security policy and how to report vulnerabilities.

Links

• npm package — babelfhir-ts
• npm package — @babelfhir-ts/client-r4 / client-r4b / client-r5
• npm package — @babelfhir-ts/zod
• GitHub repository
• Validation report
• Issue tracker
• Changelog / Releases