{"id":15617,"library":"fhir-kit-client","title":"FHIRKit Client","description":"fhir-kit-client is a robust Node.js FHIR client library designed to facilitate interaction with FHIR servers. Currently at version 1.9.2, it maintains an active release cycle, frequently updating its 1.x.x branch to incorporate new features and fixes. This library supports a wide range of FHIR versions, including R4, STU3, and DSTU2, ensuring broad compatibility with various healthcare systems. It offers comprehensive support for all FHIR REST actions, operations, and advanced features like pagination, batch/transaction processing, and handling of absolute, in-bundle, and contained references. A key differentiator is its emphasis on modern JavaScript practices, utilizing a contemporary async/await structure and ES6 Classes, while also providing full TypeScript support. It includes features like metadata caching, SMART security integration, and capability-checking based on server statements. The library is built with minimal dependencies, aiming for efficiency and ease of integration into existing projects.","status":"active","version":"1.9.2","language":"javascript","source_language":"en","source_url":"https://github.com/Vermonster/fhir-kit-client","tags":["javascript","FHIR","SMART","CDS Hooks","HL7","typescript"],"install":[{"cmd":"npm install fhir-kit-client","lang":"bash","label":"npm"},{"cmd":"yarn add fhir-kit-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add fhir-kit-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary client class is a default export in ESM environments.","wrong":"import { Client } from 'fhir-kit-client'","symbol":"Client","correct":"import Client from 'fhir-kit-client'"},{"note":"In CommonJS environments, the Client class is the module.exports default.","wrong":"const { Client } = require('fhir-kit-client')","symbol":"Client","correct":"const Client = require('fhir-kit-client')"},{"note":"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.","wrong":"import type { Resource, Patient } from 'fhir-kit-client'","symbol":"fhir4.Resource","correct":"import type { Resource, Patient } from '@types/fhir'"}],"quickstart":{"code":"const Client = require('fhir-kit-client');\nconst fhirClient = new Client({\n  baseUrl: 'https://sb-fhir-stu3.smarthealthit.org/smartstu3/open'\n});\n\nasync function asyncExamples() {\n  // Get SMART URLs for OAuth\n  let response = await fhirClient.smartAuthMetadata();\n  console.log('SMART Auth Metadata:', response);\n\n  // Read a patient\n  response = await fhirClient.read({\n    resourceType: 'Patient',\n    id: '2e27c71e-30c8-4ceb-8c1c-5641e066c0a4'\n  });\n  console.log('Read Patient:', response);\n\n  // Search for patients with pagination\n  response = await fhirClient.search({ resourceType: 'Patient', searchParams: { _count: '1', gender: 'female' } });\n  console.log('Search Results (Page 1):', response);\n\n  if (response.link && response.link.find(l => l.relation === 'next')) {\n    const nextPageResponse = await fhirClient.nextPage(response);\n    console.log('Search Results (Next Page):', nextPageResponse);\n  }\n}\n\nasyncExamples().catch(console.error);","lang":"javascript","description":"Initializes the FHIR client, retrieves SMART authentication metadata, reads a specific patient resource, and demonstrates searching with pagination using async/await syntax."},"warnings":[{"fix":"Upgrade your Node.js environment to version 16.0.0 or newer to ensure full compatibility and access to modern features.","message":"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.","severity":"breaking","affected_versions":"<16.0.0 (Node.js)"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"For ESM, use `import Client from 'fhir-kit-client';`. For CommonJS, use `const Client = require('fhir-kit-client');`.","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.","error":"TypeError: Client is not a constructor"},{"fix":"Verify the `resourceType` and `id` provided in your `read` or `request` call against the actual resources available on your target FHIR server.","cause":"The requested FHIR resource (e.g., Patient with a specific ID) does not exist on the server, or the ID is malformed.","error":"Error: Resource not found for path: Patient/invalidId"},{"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.","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.","error":"Error: Not Found - The request could not be mapped to an existing operation"}],"ecosystem":"npm"}