📘 A lightweight JavaScript/React client for FHIR servers

The purpose of this project is to demonstrate how a frontend application can interact with a FHIR server using a simple React + JavaScript client. To keep the example easy to understand, I also created a companion project that shows how to connect to a FHIR server through a backend service:

https://github.com/jozcar1/fhir-integration-service

In real-world healthcare applications, frontend code typically does not connect directly to a FHIR server. Instead, communication happens through a backend service. This approach provides several benefits:

• Protects the FHIR server behind secure backend logic
• Allows you to control and customize what data the frontend can access
• Enables authentication, authorization, auditing, and rate limiting
• Lets you shape the data returned to the UI (aggregation, filtering, transformations)

In the companion backend project, the API endpoints do not strictly follow the FHIR REST API naming conventions. This is intentional. Backend services in production systems often expose their own domain-specific routes rather than mirroring the FHIR API directly. Both approaches are valid:

• You can mirror the FHIR REST API (e.g., /Patient, /Observation)
• Or you can expose custom endpoints that better fit your application's needs

The important part is that the backend acts as a secure façade in front of the FHIR server, controlling access and defining the contract your frontend relies on.

This project focuses on the frontend perspective, while the companion project demonstrates the backend pattern commonly used in production FHIR integrations.

---

🚀 Features

• Lightweight JavaScript client for interacting with FHIR servers
• Environment‑based configuration for switching between FHIR endpoints
• Simple REST helpers for GET, search, create, update, and delete
• Ideal for learning, prototyping, and testing against public FHIR servers
• Complements the backend integration pattern shown in the companion project
• Demonstrates how frontend code can call FHIR directly, while explaining why production systems typically use a backend layer instead

---

📦 Installation

Clone the repository:

git clone https://github.com/jozcar1/fhir-client-js.git
cd fhir-client-js

Install dependencies

npm install 

Enviroment setup

This project uses environment variables to configure the FHIR server endpoint

Public FHIR Servers

You can test this client against publicly available FHIR servers. These are useful for learning, prototyping, and experimenting with FHIR interactions.

Available Public Servers

• HAPI FHIR Public Server (R4)
  https://hapi.fhir.org/baseR4

• HAPI FHIR Public Server (R5)
  https://hapi.fhir.org/baseR5

• Firely (R4)

  https://server.fire.ly

Important Notes About Public Servers

Public FHIR servers periodically reset their data. Any resources you create (Patients, Observations, etc.) may be deleted at any time as part of routine cleanup. This is normal behavior for open test servers and helps keep them stable for all users.

Recommended Architecture

While this project allows the frontend to connect directly to a public FHIR server for demonstration purposes, the ideal production setup is different:

• The backend should be configured with the public (or private) FHIR server URL
• The frontend should call your backend service, not the FHIR server directly

This approach provides better security, stability, and control over the data your application exposes. The companion backend project demonstrates this recommended pattern:

https://github.com/jozcar1/fhir-integration-service

Postman Collection (Sample Data)

This repository includes a Postman collection that you can use to populate sample FHIR data for testing.
The collection contains example requests for:

• Creating a fake patient
• Adding lab results (Observations)
• Searching for patients
• Viewing a patient's lab history

These examples make it easy to test the frontend search functionality and demonstrate how FHIR resources relate to each other.

Download the Collection

You can find the Postman collection here: /postman/PopulatePublicHapiFHIRServer.postman_collection.json

How to Use

1. Open Postman
2. Import the collection file
3. Set the base_url environment variable to your backend API (recommended) or a public FHIR server
4. Run the requests to seed your test data

This gives you a realistic dataset to use when testing the search and lab‑viewing features in the frontend.

Vite/React (.env)

When using the recommended backend architecture, your frontend should not point directly to a FHIR server.
Instead, configure the .env file to point to your backend API:

VITE_FHIR_BASE_URL=https://localhost:7283/api/v1/

This tells the frontend to send all FHIR-related requests to your backend service, which then communicates with the actual FHIR server.

What This Project Demonstrates

This project provides a minimal, easy-to-understand client that highlights:

• REST interactions
• Resource modeling
• Environment-driven configuration
• Clean, reusable architecture

When to Use This Client

This project is ideal for:

• Learning how FHIR REST interactions work
• Prototyping UI components that depend on FHIR data
• Testing against public FHIR servers
• Demonstrating frontend-to-FHIR interactions in a simple environment

For production applications, you should use the backend pattern shown in the companion project.

Contributing

Pull requests are welcome. If you'd like to add resource helpers, tests, or TypeScript support, feel free to open an issue or submit a PR.

License

MIT License — free to use, modify, and distribute