FHIRfly
Dashboard

SHL Quick Start

Build an International Patient Summary, encrypt it as a SMART Health Link, and generate a QR code — in under 20 lines of code.

Installation

npm install @fhirfly-io/shl

If using FHIRfly API enrichment (recommended):

npm install @fhirfly-io/shl @fhirfly-io/terminology

1. Build an IPS Bundle

import { IPS, SHL } from "@fhirfly-io/shl";
import Fhirfly from "@fhirfly-io/terminology";

const client = new Fhirfly({ apiKey: process.env.FHIRFLY_API_KEY });

const bundle = new IPS.Bundle({
  given: "Maria",
  family: "Garcia",
  birthDate: "1985-03-15",
  gender: "female",
});

// Add clinical data (FHIRfly enriches with SNOMED, display names, etc.)
bundle.addMedication({ byNDC: "00071015523", fhirfly: client.ndc });
bundle.addCondition({ byICD10: "E11.9", fhirfly: client.icd10 });
bundle.addAllergy({ bySNOMED: "387207008" });
bundle.addImmunization({ byCVX: "208", fhirfly: client.cvx });
bundle.addResult({
  byLOINC: "2339-0",
  fhirfly: client.loinc,
  value: 95,
  unit: "mg/dL",
});

const fhirBundle = await bundle.build();

2. Create an SHL

// Option A: FHIRfly hosted (zero infrastructure)
const storage = new SHL.FhirflyStorage({
  apiKey: process.env.FHIRFLY_API_KEY,
});

// Option B: Local storage (for development)
// const storage = new SHL.LocalStorage({
//   directory: "./shl-data",
//   baseUrl: "http://localhost:3456/shl",
// });

const result = await SHL.create({
  bundle: fhirBundle,
  storage,
  passcode: "1234",
  label: "Maria's Health Summary",
});

console.log(result.url);     // shlink:/eyJ...
console.log(result.qrCode);  // data:image/png;base64,...

FhirflyStorage is included free in all plans with per-plan limits on active SHLs and attachments. See Pricing and Storage Adapters for details.

3. Share

The result.url is a complete SMART Health Link. Share it by:

  • QR Code: Save result.qrCode as a PNG image for scanning
  • Deep Link: https://fhirfly.io/shl/viewer#shlink:/eyJ...
  • Text: Send the shlink:/ URL directly

4. View

Open the SHL Viewer and paste the link, or use the deep link format. All decryption happens in the browser.

CLI Alternative

For quick testing without writing code:

# Full demo with sample patient data
npx @fhirfly-io/shl demo

# Create from an existing FHIR Bundle file
npx @fhirfly-io/shl create my-bundle.json --passcode 1234

# Start a local server
npx @fhirfly-io/shl serve --dir ./shl-data --port 3456

# Validate a FHIR Bundle against IPS
npx @fhirfly-io/shl validate bundle.json

# Decode an SHL URL
npx @fhirfly-io/shl decode shlink:/eyJ...

Next Steps