SMART on FHIR JavaScript Library

This is a JavaScript library for connecting SMART apps to FHIR servers. It works both in browsers (IE 10+) and on the server (Node 18+).

This is the documentation for version 2+. If you want to migrate from older versions, please check out what’s new in v2 and migration instructions.

NodeJS Tests Browser Tests Coverage Status npm version types node downloads

Table of Contents



Installation

From NPM

npm i fhirclient

From CDN

Include it with a script tag from one of the following locations:

From NPM (latest version):

From NPM (specific version):

Latest development builds from GitHub:

Browser Usage

In the browser you typically have to create two separate pages that correspond to your launch_uri (Launch Page) and redirect_uri (Index Page).

As Library

Launch Page

<!-- launch.html -->
<script src="./node_module/fhirclient/build/fhir-client.js"></script>
<script>
FHIR.oauth2.authorize({
    "client_id": "my_web_app",
    "scope": "patient/*.read"
});
</script>

Index Page

<!-- index.html -->
<script src="./node_module/fhirclient/build/fhir-client.js"></script>
<script>
FHIR.oauth2.ready()
    .then(client => client.request("Patient"))
    .then(console.log)
    .catch(console.error);
</script>

As Module

Launch Page

import FHIR from "fhirclient"
FHIR.oauth2.authorize({
    "client_id": "my_web_app",
    "scope": "patient/*.read"
});

Index Page

import FHIR from "fhirclient"
FHIR.oauth2.ready()
    .then(client => client.request("Patient"))
    .then(console.log)
    .catch(console.error);

NOTE: When the library is used as module it will not polyfill the global namespace and will not create a global FHIR object as it does when included as script. If you want to be able to use it globally, you can export it yourself like so:

import FHIR from "fhirclient";

// in JavaScript:
window.FHIR = FHIR;

// In TypeScript:
(window as any).FHIR = FHIR;

Server Usage

The server is fundamentally different environment than the browser but the API is very similar. Here is a simple Express example:

const fhirClient = require("fhirclient");

// This is what the EHR will call
app.get("/launch", (req, res) => {
    fhirClient(req, res).authorize({
        "client_id": "my_web_app",
        "scope": "patient/*.read"
    });
});

// This is what the Auth server will redirect to
app.get("/", (req, res) => {
    fhirClient(req, res).ready()
        .then(client => client.request("Patient"))
        .then(res.json)
        .catch(res.json);
});

Read more at the NodeJS API Details.

SMART API

The SMART API is a collection of SMART-specific methods (authorize, ready, init) for app authorization and launch. If you are working in a browser, the SMART API is automatically created, and available at window.FHIR.oauth2. In NodeJS, the library exports a function that should be called with a http request and response objects, and will return the same SMART API as in the browser.

// BROWSER
const smart = FHIR.oauth2;
smart.authorize(options);

// SERVER
const smart = require("fhirclient");
smart(request, response).authorize(options);

Read the SMART API Documentation

Client

This is a FHIR client that is returned to you from the ready() or the init() SMART API calls. You can also create it yourself if needed. For example, there is no need to authorize against an open FHIR server. You can skip that and start by creating a client instance:

// BROWSER
const client = FHIR.client({
    serverUrl: "https://r4.smarthealthit.org"
});

// SERVER
const client = fhirClient(req, res).client({
    serverUrl: "https://r4.smarthealthit.org"
});

The client instance exposes a super-powered request method that you use to query the FHIR server and a bunch of other useful utilities and methods. Read the full Client API docs.

Fhir.js Integration

Since v2.0 this library no longer includes fhir.js. That architecture was extremely difficult to maintain. Fhir.js is now an optional dependency, meaning that it is not available by default, unless you include it in the page. Our goal is to provide a simple alternative to fhir.js - most of it should be possible via client.request. Please see the Examples.

You are now free to choose what version of fhir.js to include. For backward compatibility try our fork of fhir.js. It is not maintained any more, and it would require Jquery to be included in the page. Newer versions of fhir.js work fine, but might have different API or return result objects with different shape.

Reasons to use fhir.js

  1. If you have old apps using legacy API like client.api.anyFhirJsMethod() or client.patient.api.anyFhirJsMethod()
  2. If you prefer the mongodb-like query syntax.
  3. If you are trying to do something specific that can only be done with fhir.js

Reasons not to use fhir.js

  1. If you prefer to build the fhir queries yourself using fhir syntax.
  2. If you encounter fhir-version-specific issues with fhir.js
  3. If you want to keep things simpler and smaller

Browser Integration

You just need to include fhir.js (nativeFhir.js) in the page via script tag. We will detect that and make the necessary linking. You can then use it via client.api and client.patient.api, just like it used to work with older versions of this library. The latest build of fhir.js that we have tested with is available at lib/nativeFhir.js.

<!-- index.html -->
<script src="/path/to/nativeFhir.js"></script>
<script src="/path/to/fhir-client.js"></script>
<script>
FHIR.oauth2.ready().then(client => client.api.search({ type: "Patient" }))
</script>

NodeJS Integration

There are no global variables to detect so you’ll have to link it manually using the dedicated connect(fhirJs) method of the client:

const fhirJs = require("fhir.js");

// Inside a route handler
app.get("/", async (req, res) => {
    const client = await smart(req, res).ready();
    client.connect(fhirJs);
    client.api.search({ type: "Patient" }).then(res.json).catch(res.json);
});

Debugging

This library uses the debug module.

To enable debug logging in Node use the DEBUG env variable:

DEBUG='FHIR.*' node my-app

In the browser execute this in the console and then reload the page:

localStorage.debug = "FHIR.*"