# 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 (`>=5.2.0 <6`), so the host app owns the version
- **Type-safe FHIR client** — generated client extends [`@babelfhir-ts/client-r4`](https://www.npmjs.com/package/@babelfhir-ts/client-r4) / [`client-r4b`](https://www.npmjs.com/package/@babelfhir-ts/client-r4b) / [`client-r5`](https://www.npmjs.com/package/@babelfhir-ts/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
```bash
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
```bash
# 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
```
```ts
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] [ [output]]
babelfhir-ts install [--package] [--registry ] [options]
babelfhir-ts update [] [--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 Log destination: console (default) or file
--log-level Log verbosity: error, warn, info (default), or debug
--cache-dir 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 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 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 Output directory (alias for second positional argument)
--fhir-version FHIR version to target: r4, r4b, or r5 (auto-detected from package if omitted)
--package Download FHIR package from registry and process it (latest if no version)
--registry FHIR package registry URL (default: https://packages.simplifier.net)
--tx-server 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 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 # Install from custom registry
babelfhir-ts install --package hl7.fhir.us.core@8.0.0 --registry # 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/](https://max-health-inc.github.io/BabelFHIR-TS/docs/)**
- [Getting Started](https://max-health-inc.github.io/BabelFHIR-TS/docs/getting-started) — installation, quick start, first generation
- [CLI Reference](https://max-health-inc.github.io/BabelFHIR-TS/docs/cli-reference) — full list of commands and options
- [Generated Code Guide](https://max-health-inc.github.io/BabelFHIR-TS/docs/generated-code) — understanding the output, module resolution, FHIR type imports
- [FHIR Client](https://max-health-inc.github.io/BabelFHIR-TS/docs/fhir-client) — type-safe server interactions
- [Validation](https://max-health-inc.github.io/BabelFHIR-TS/docs/validation) — what validators check, CI pipelines, known Firely SDK issues
- [Limitations](https://max-health-inc.github.io/BabelFHIR-TS/docs/limitations) — edge cases, random() caveats
- [Contributing](https://max-health-inc.github.io/BabelFHIR-TS/docs/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`](./parity-matrix.json).
Each validated IG is also published as a ready-to-install package — `@max-health-inc/fhir-` — so you do not have to generate it yourself:
**[→ Browse the FHIR IG registry](https://github.com/orgs/Max-Health-Inc/packages?ecosystem=npm&q=fhir-)**
```bash
# 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](https://github.com/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](https://docs.fire.ly/projects/Firely-NET-SDK/validation.html) (`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
Per-IG results
