BabelFHIR-TS

BabelFHIR-TS transforms FHIR® StructureDefinitions into production-ready TypeScript code with full type safety and built-in validation. Unlike generic FHIR type definitions, 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—minimal runtime deps; only fhirpath is required for validators
• Type-safe FHIR client — generated client extends @babelfhir-ts/client-r4 / client-r4b / client-r5 with profile-specific methods (e.g., .usCorePatient(), .pASClaim()) on top of base resource accessors
• Install any FHIR profile as a node module—use babelfhir-ts install to add Implementation Guides directly to your project

Continuous Validation

Every pull request runs two independent CI pipelines that validate generated code against real-world FHIR Implementation Guides. 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 external FHIR validators

Tested Implementation Guides (30 packages)

| Category | Implementation Guide | Package | FHIR | |---|---|---|---| | US | US Core | [email protected] | R4 | | US | QI-Core | [email protected] | R4 | | US | mCODE | [email protected] | R4 | | US | SDOH Clinical Care | [email protected] | R4 | | US | NDH (National Directory) | [email protected] | R4 | | US | CARIN BB | [email protected] | R4 | | US | CQF Measures | [email protected] | R4 | | US | Physical Activity | [email protected] | R4 | | DaVinci | PAS | [email protected] | R4 | | DaVinci | CDex | [email protected] | R4 | | DaVinci | PDex | [email protected] | R4 | | DaVinci | DTR | [email protected] | R4 | | DaVinci | Alerts | [email protected] | R4 | | DaVinci | DEQM | [email protected] | R4 | | DaVinci | Drug Formulary | [email protected] | R4 | | Universal | IPS | [email protected] | R4 | | Universal | SMART App Launch | [email protected] | R4 | | Universal | SDC (Structured Data Capture) | [email protected] | R4 | | Universal | Genomics Reporting | [email protected] | R4 | | Universal | CPG (Clinical Practice Guidelines) | [email protected] | R4 | | DE | ISiK Basis | [email protected] | R4 | | DE | KBV eRezept | [email protected] | R4 | | DE | DE Basisprofil | [email protected] | R4 | | DE | ISiK Medikation | [email protected] | R4 | | CH | CH Core (Switzerland) | [email protected] | R4 | | AU | AU Core (Australia) | [email protected] | R4 | | IHE | PIXm | [email protected] | R4 | | IHE | MHD | [email protected] | R4 | | R5 | AE Research (R5) | [email protected] | R5 | | R5 | eMedicinal Product (R5) | [email protected] | R5 |

Validation with Firely .NET SDK

The first pipeline validates generated resources using the Firely .NET SDK validator. Results are published as live badges:

Validation with HL7 Java Validator

The second pipeline validates using the official HL7 FHIR Validator, the reference implementation for FHIR conformance checking:

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

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 [email protected]

# Install as a project dependency
babelfhir-ts install [email protected]

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

const patient = USCorePatientClass.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)
  --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
  --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 [email protected]            # Download and process from default registry
  babelfhir-ts --package [email protected] 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 [email protected]                   # Download specific version
  babelfhir-ts install ./package.tgz                                      # Install from local package file
  babelfhir-ts install [email protected] --registry <url>            # Install from custom registry
  babelfhir-ts install --package [email protected] --registry <url>  # Alternative syntax
  babelfhir-ts update                                                      # Regenerate all packages in ./lib
  babelfhir-ts update [email protected]                               # 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

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