Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ import Client from 'fhir-kit-client'
✗ import { Client } from 'fhir-kit-client'
The primary client class is a default export in ESM environments.
Client
✓ const Client = require('fhir-kit-client')
✗ const { Client } = require('fhir-kit-client')
In CommonJS environments, the Client class is the module.exports default.
fhir4.Resource
✓ import type { Resource, Patient } from '@types/fhir'
✗ import type { Resource, Patient } from 'fhir-kit-client'
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.
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);
Debug
Known issues
breakingThe 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.fixUpgrade your Node.js environment to version 16.0.0 or newer to ensure full compatibility and access to modern features.
affects: <16.0.0 (Node.js)
gotchaWhile 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.fixInstall 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.
affects: >=1.0.0
gotchaSetting 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.fixRefer 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.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: Client is not a constructor
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.
fixFor 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
The requested FHIR resource (e.g., Patient with a specific ID) does not exist on the server, or the ID is malformed.
fixVerify 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
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.
fixDouble-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.
Audit
Dependencies
No dependency data recorded yet.