babelfhir-ts
Advanced tools
BabelFHIR-TS: generate TypeScript interfaces, validators, and helper classes from FHIR R4/R4B/R5 StructureDefinitions (profiles) directly inside package archives.
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. Unlike generic FHIR type definitions, BabelFHIR-TS generates profile-aware interfaces that understand your Implementation Guide's constraints, extensions, and slicing rules.
@types/fhir).js) plus TypeScript declarations (.d.ts)fhirpath is required for validators@babelfhir-ts/client-r4 / client-r4b / client-r5 with profile-specific methods (e.g., .usCorePatient(), .pASClaim()) on top of base resource accessorsbabelfhir-ts install to add Implementation Guides directly to your projectEvery pull request runs two independent CI pipelines that validate generated code against real-world FHIR Implementation Guides. For each IG, the pipeline:
tsc (zero errors required)empty() and random() test resources for every profile| Category | Implementation Guide | Package | FHIR |
|---|---|---|---|
| US | US Core | hl7.fhir.us.core@8.0.0 | R4 |
| US | QI-Core | hl7.fhir.us.qicore@6.0.0 | R4 |
| US | mCODE | hl7.fhir.us.mcode@4.0.0 | R4 |
| US | SDOH Clinical Care | hl7.fhir.us.sdoh-clinicalcare@2.2.0 | R4 |
| US | NDH (National Directory) | hl7.fhir.us.ndh@1.0.0 | R4 |
| US | CARIN BB | hl7.fhir.us.carin-bb@2.1.0 | R4 |
| US | CQF Measures | hl7.fhir.us.cqfmeasures@4.0.0 | R4 |
| US | Physical Activity | hl7.fhir.us.physical-activity@1.0.0 | R4 |
| DaVinci | PAS | hl7.fhir.us.davinci-pas@2.0.1 | R4 |
| DaVinci | CDex | hl7.fhir.us.davinci-cdex@2.1.0 | R4 |
| DaVinci | PDex | hl7.fhir.us.davinci-pdex@2.1.0 | R4 |
| DaVinci | DTR | hl7.fhir.us.davinci-dtr@2.1.0 | R4 |
| DaVinci | Alerts | hl7.fhir.us.davinci-alerts@1.0.0 | R4 |
| DaVinci | DEQM | hl7.fhir.us.davinci-deqm@4.0.0 | R4 |
| DaVinci | Drug Formulary | hl7.fhir.us.davinci-drug-formulary@2.1.0 | R4 |
| Universal | IPS | hl7.fhir.uv.ips@2.0.0 | R4 |
| Universal | SMART App Launch | hl7.fhir.uv.smart-app-launch@2.2.0 | R4 |
| Universal | SDC (Structured Data Capture) | hl7.fhir.uv.sdc@3.0.0 | R4 |
| Universal | Genomics Reporting | hl7.fhir.uv.genomics-reporting@3.0.0 | R4 |
| Universal | CPG (Clinical Practice Guidelines) | hl7.fhir.uv.cpg@2.0.0 | R4 |
| DE | ISiK Basis | de.gematik.isik-basismodul@4.0.3 | R4 |
| DE | KBV eRezept | kbv.ita.erp@1.1.1 | R4 |
| DE | DE Basisprofil | de.basisprofil.r4@1.5.0 | R4 |
| DE | ISiK Medikation | de.gematik.isik-medikation@4.0.1 | R4 |
| CH | CH Core (Switzerland) | ch.fhir.ig.ch-core@5.0.0 | R4 |
| AU | AU Core (Australia) | hl7.fhir.au.core@1.0.0 | R4 |
| IHE | PIXm | ihe.iti.pixm@3.0.4 | R4 |
| IHE | MHD | ihe.iti.mhd@4.2.2 | R4 |
| R5 | AE Research (R5) | hl7.fhir.uv.ae-research-ig@1.0.1 | R5 |
| R5 | eMedicinal Product (R5) | hl7.fhir.uv.emedicinal-product-info@1.0.0 | R5 |
The first pipeline validates generated resources using the Firely .NET SDK validator. Results are published as live badges:
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.
npm install -g babelfhir-ts
Or on-demand: npx babelfhir-ts --help
Requirements: Node.js 18+ and an internet connection for remote registries.
# 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 { USCorePatientClass } from "./output/USCorePatientClass";
const patient = USCorePatientClass.random();
const { errors, warnings } = await patient.validate();
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 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
Full documentation is available at max-health-inc.github.io/BabelFHIR-TS/docs/
ISC © Maximilian Nussbaumer
Release notes are published automatically on GitHub Releases: View all releases
Contributions are welcome! See the Contributing guide for dev setup, scripts, and how to submit changes.
For security issues, please see SECURITY.md for our security policy and how to report vulnerabilities.
FAQs
BabelFHIR-TS: generate TypeScript interfaces, validators, and helper classes from FHIR R4/R4B/R5 StructureDefinitions (profiles) directly inside package archives.
The npm package babelfhir-ts receives a total of 150 weekly downloads. As such, babelfhir-ts popularity was classified as not popular.
We found that babelfhir-ts demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
OSV withdrew 157 OSV malware reports after automated false positives incorrectly flagged trusted npm and PyPI packages, sending bad records into tools that rely on OSV data.
Research
/Security News
TrapDoor crypto stealer hits 36 malicious packages across npm, PyPI, and Crates.io, targeting crypto, DeFi, AI, and security developers.
Research
/Security News
Laravel Lang packages were compromised with an RCE backdoor across hundreds of versions, exposing cloud, CI/CD, and developer secrets.