FHIRKit Client

Common errors

• TypeError: Client is not a constructor

  cause Attempting to import `Client` as a named export (`import { Client } from 'fhir-kit-client'`) when it is a default export, or trying to access it as a property of the `require`d module.
  fix For ESM, use `import Client from 'fhir-kit-client';`. For CommonJS, use `const Client = require('fhir-kit-client');`.

• Error: Resource not found for path: Patient/invalidId

  cause The requested FHIR resource (e.g., Patient with a specific ID) does not exist on the server, or the ID is malformed.
  fix Verify the `resourceType` and `id` provided in your `read` or `request` call against the actual resources available on your target FHIR server.

• Error: Not Found - The request could not be mapped to an existing operation

  cause The FHIR server's base URL is incorrect, or the specific resource type or operation you are attempting to access is not supported or does not exist at the provided endpoint on the server.
  fix Double-check the `baseUrl` provided to the `Client` constructor. Consult the server's capability statement (available via `/metadata` endpoint) to confirm supported resource types and operations.

Warnings

• breaking The library explicitly requires Node.js version 16.0.0 or higher. Running in older Node.js environments may lead to unexpected errors or unsupported syntax.
  Fix: Upgrade your Node.js environment to version 16.0.0 or newer to ensure full compatibility and access to modern features.
• gotcha While fhir-kit-client supports multiple FHIR versions (R4, STU3, DSTU2), the TypeScript types from `@types/fhir` are version-specific (e.g., `fhir4.Patient`). Ensure that the types you import and use in your application match the FHIR version of the server you are connecting to, to avoid type mismatches and runtime errors.
  Fix: Install the correct version of `@types/fhir` (e.g., `@types/fhir@^4.0.0` for R4) and use type guards or version-agnostic patterns if your application connects to servers with different FHIR versions.
• gotcha Setting up SMART security can be complex, involving OAuth 2.0 flows. Incorrect configuration of client credentials, redirect URIs, scopes, or token exchange can lead to authentication failures.
  Fix: Refer to the SMART on FHIR documentation and the fhir-kit-client examples for detailed setup instructions. Double-check all OAuth parameters and ensure your FHIR server is correctly configured to accept the client's requests.

Install

• npm install fhir-kit-client npm
• yarn add fhir-kit-client yarn
• pnpm add fhir-kit-client pnpm

Imports

• Client
  wrong:

  import { Client } from 'fhir-kit-client'

  correct:

  import Client from 'fhir-kit-client'

  The primary client class is a default export in ESM environments.
• Client
  wrong:

  const { Client } = require('fhir-kit-client')

  correct:

  const Client = require('fhir-kit-client')

  In CommonJS environments, the Client class is the module.exports default.
• fhir4.Resource
  wrong:

  import type { Resource, Patient } from 'fhir-kit-client'

  correct:

  import type { Resource, Patient } from '@types/fhir'

  TypeScript type definitions for FHIR resources (e.g., fhir4.Patient) are typically provided by external packages like @types/fhir, not fhir-kit-client directly. Install '@types/fhir' as a dev dependency for type-checking.

Quickstart

Initializes the FHIR client, retrieves SMART authentication metadata, reads a specific patient resource, and demonstrates searching with pagination using async/await syntax.

const Client = require('fhir-kit-client');
const fhirClient = new Client({
  baseUrl: 'https://sb-fhir-stu3.smarthealthit.org/smartstu3/open'
});

async function asyncExamples() {
  // Get SMART URLs for OAuth
  let response = await fhirClient.smartAuthMetadata();
  console.log('SMART Auth Metadata:', response);

  // Read a patient
  response = await fhirClient.read({
    resourceType: 'Patient',
    id: '2e27c71e-30c8-4ceb-8c1c-5641e066c0a4'
  });
  console.log('Read Patient:', response);

  // Search for patients with pagination
  response = await fhirClient.search({ resourceType: 'Patient', searchParams: { _count: '1', gender: 'female' } });
  console.log('Search Results (Page 1):', response);

  if (response.link && response.link.find(l => l.relation === 'next')) {
    const nextPageResponse = await fhirClient.nextPage(response);
    console.log('Search Results (Next Page):', nextPageResponse);
  }
}

asyncExamples().catch(console.error);