Medplum v5 is Released
We are pleased to announce the Release of Medplum v5, the next major version of the open source healthcare developer platform.
As outlined in our preparatory post in May, Medplum v5 represents a comprehensive and necessary modernization of our core stack. This release ensures our platform maintains the highest standards of performance, security, and developer experience by aligning with the latest stable versions of our critical runtime and tooling dependencies.
As with all major releases, our goal is to provide a stable, predictable, and future-proof platform for building healthcare solutions.
Core Platform Modernization
The bulk of the work in v5 involved essential dependency upgrades and technical debt reduction.
Runtime and Infrastructure
Medplum v5 now requires and is rigorously tested against modern runtime environments:
- Node.js: We have deprecated Node 20 and now continuously test on Node 22 and 24. This upgrade enables access to the latest JavaScript features and performance improvements, including Node 22's Maglev compiler.
- PostgreSQL: We have ended support for Postgres 13 and now continuously test on Postgres 14 and 18. Users benefit from major database performance features, such as Postgres 18's asynchronous I/O subsystem.
- Redis: Support for Redis 6 has been dropped; we now continuously test on Redis 7.
New Capabilities
We are excited to release several major new features in Medplum v5:
- Full FHIR Terminology Validation. Medplum now includes comprehensive, built-in terminology support covering major code systems like SNOMED, ICD, CPT, and others. Crucially, this functionality also includes hierarchy support (e.g., "descendant of"). This advanced validation logic contributes directly to better data hygiene, improves data quality, and increases confidence in the integrity of the data managed by the Medplum platform.
- FHIR GraphQL Patch support. The Medplum GraphQL API now supports FHIR Patch operations, enabling more efficient and flexible updates to FHIR resources via GraphQL mutations. This enhancement allows developers to perform partial updates, reducing payload sizes and improving performance for applications that require frequent resource modifications.
Frontend and Developer Tooling
We have streamlined the frontend stack to improve build times, component quality, and overall developer experience:
- React: We've dropped support for React 18 and now require React 19, which simplifies our component maintenance moving forward.
- UI Components: Upgraded all usage from Mantine v7 to v8, which features improved date handling and enhanced TypeScript support.
- Core Frameworks: Successfully upgraded Express from v4 to v5 and Storybook from v8 to v9.
Strategic Update: ESM by Default
A key architectural shift in v5 is the move to ES Modules (ESM) by default.
This aligns Medplum with the modern JavaScript module standard, offering benefits like improved tree-shaking and better future compatibility. For a smooth transition, we will dual-publish certain SDK packages as CJS+ESM. We strongly recommend that all custom applications migrate to ESM for optimal compatibility and performance moving forward.
Planning Your Migration (Breaking Changes)
Medplum v5 includes a few minor breaking changes, primarily involving the deprecation of long-standing features and updates to API signatures for better consistency and modern patterns.
API and SDK Changes
| Old Feature/Component | New Feature/Component | Note |
|---|---|---|
Non-standard usage of ?param:in=... and ?param:not-in=... | Strict FHIR compliance | Invalid usage of the :in and :not-in search modifiers now throws an error. For simple inclusion checks, remove the modifier: Patient?_id=uuid1,uuid2. |
PasswordChangeRequest resource | UserSecurityRequest resource | PasswordChangeRequest was deprecated for over a year; UserSecurityRequest is a superset of its functionality. |
Hl7Server.start and Hl7Server.stop methods | Same methods, now async | These methods must now be used with await or promise chains. |
ProjectSecret type definition | ProjectSetting type | Use the ProjectSetting type instead. |
MemoizedSearchControl React component | SearchControl React component | Use the standard component directly. |
Infrastructure Changes
- AWS Container Insights: Updated from v1 to Container Insights v2.
- CloudWatch Logs for Audit Events: Audit logging now utilizes AWS FireLens log routing for improved log management.
The Value of Upgrading
While a major version upgrade requires planning, Medplum v5 delivers concrete benefits that justify the effort:
- Performance: Immediate and substantial performance gains across the stack, from the database and runtime to frontend tooling.
- Security: Access to the latest security features and patches across all dependencies.
- Future-Proofing: Setting your healthcare solutions on a stable, supported platform that is aligned with industry best practices.
Next Steps for Self-Hosted Customers
We encourage self-hosted customers to begin planning their upgrade immediately.
- Consult our detailed migration guides on the documentation site.
- Schedule database and runtime environment upgrades with your DevOps team.
- Review your custom application codebase for compatibility with newer dependencies and the breaking changes listed above.
For technical questions or feedback, please join the conversation on Discord or submit issues on GitHub.
Medplum v5 is ready to power your next generation of healthcare applications.