SMART on FHIR JavaScript Client

If your request/response objects do not have a session property, or if you want to use an alternative storage mechanism, you must provide a custom storage object.

Your storage object must implement the following interface:

• get(key: string): Promise<any>: Returns the value or undefined.
• set(key: string, value: any): Promise<any>: Returns the value.
• unset(key: string): Promise<Boolean>: Returns true on success.

You can pass the storage object directly, or better yet, pass a storage factory function that receives { request, response } to allow for request-specific storage instantiation.

// Using a storage factory function (recommended)
function createStorage({ request, response }) {
    return new AwesomeCustomStorage(request, response);
}

// inside a route handler
smart(request, response, createStorage).authorize(options)

The SMART API provides methods for app authorization and launch (authorize, ready, init).

• In the Browser: The API is automatically available at window.FHIR.oauth2.
• In Node.js: The library exports a function that accepts request and response objects and returns the SMART API instance.

Important: When using authorize(), the browser will redirect to the authorization server. Do not add code to the returned promise chain that expects to execute immediately after the call, as the redirect may prevent execution.

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

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

Since version 2.6.0, the library has introduced a FhirClient base class. This class handles standard FHIR HTTP requests without requiring SMART authorization or launch context.

The standard Client instance returned after a successful SMART authorization is a subclass of FhirClient. If you are building an application that only interacts with open FHIR servers and does not need SMART features, you should use FhirClient directly to avoid unnecessary overhead.

In fhirclient v2+, FHIR.oauth2.ready() returns a Promise. While the old callback signature ready(onSuccess, onError) is still supported and converted internally, it is recommended to use the Promise-based syntax for clarity and better control over the execution chain.

Recommended usage:

FHIR.oauth2.ready().then(onSuccess).catch(onError);

Key changes to callback logic:

• onError is now a promise rejection handler. It will always receive a single argument: an Error instance.
• onSuccess is part of the promise chain. If you throw an error or return a rejected promise within onSuccess, it will propagate to the onError handler.
• You can return a Promise from onSuccess, and it will be awaited.

The library does not include fhir.js by default. If you need its MongoDB-like query syntax or legacy API support (client.api.*), you must include it manually.

Browser Integration

Include fhir.js (e.g., nativeFhir.js) via a script tag before the client. The library will automatically detect it.

<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>

Node.js Integration

In Node.js, you must manually link fhir.js using the client.connect() method.

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

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);
});

You can install the library via NPM or include it directly in the browser using a CDN.

NPM

npm i fhirclient

CDN

Include a <script> tag pointing to one of the following:

Latest version:

• https://cdn.jsdelivr.net/npm/fhirclient/build/fhir-client.js
• https://cdn.jsdelivr.net/npm/fhirclient/build/fhir-client.min.js

Specific version (e.g., 2.0.7):

• https://cdn.jsdelivr.net/npm/fhirclient@2.0.7/build/fhir-client.js
• https://cdn.jsdelivr.net/npm/fhirclient@2.0.7/build/fhir-client.min.js

The FHIR client is the primary interface for interacting with a FHIR server. It is typically obtained from the ready() call of the SMART API. You can also instantiate it manually depending on your environment.

In the Browser: Use FHIR.client(baseUrl).

On the Server (Node.js): Use smart(req, res).client(baseUrl).

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

// SERVER
const client = smart(req, res).client("https://r4.smarthealthit.org");

To avoid popup blockers or use custom UI (like an iframe with animations), you can pass a function to the target option. This function should return a string (the frame name), a Window object, or a Promise that resolves to one of those values.

// Example: Using a function that resolves to an iframe name after an animation
function openPopup() {
    return new Promise(resolve => {
        // Start opening animation
        document.getElementById("layer-popup").classList.add("open");

        // Reset the iframe
        document.getElementById("myPopupFrame").src = "about:blank";

        // Resolve with the frame name once transitions are done
        setTimeout(() => resolve("myPopupFrame"), 1000);
    });
}

FHIR.oauth2.authorize({
    target: openPopup,
    // ...
});

Install the SMART on FHIR JavaScript library via npm to connect SMART apps to FHIR servers. The library is compatible with browsers (including IE11+) and Node.js environments.

npm i fhirclient