Migrating from Strapi 4 to Strapi 5 is an important step to keep your project up-to-date and leverage the latest improvements.

This guide covers everything you should consider before starting your migration process. From Strapi 5's new features, plugin considerations, and tools available to you, we've included commonly asked questions to help you make this transition as smooth as possible.

Benefits of Switching to Strapi 5

Upgrading to Strapi 5 offers numerous benefits for both developers and content teams:

• Access to New Features: By switching to v5, you can take advantage of the latest features like conditional fields, live preview, easier relation management, and the improved content editing UX that are simply not available in v4.
• Improved Developer Experience: Strapi 5’s modernized stack (TypeScript support, Vite bundler, official client library, plugin SDK) makes development smoother and more efficient.

You’ll benefit from faster builds and reloads, better tooling (thanks to TS types and updated libraries), and more straightforward plugin customization.

• Better Performance: Projects running on Strapi 5 will see performance improvements. For instance, the flattening of API responses simplifies data parsing and can boost API performance.

The switch to faster underlying packages (like better-sqlite3 for SQLite and Vite for the admin) reduces overhead. Overall, v5 is optimized for more scalability and speed than v4.

• Security and Bug Fixes: As the latest version, Strapi 5 receives all new security patches and bug fixes. Strapi 4 will only receive critical fixes until its end-of-support date and no new features. Running on v5 ensures you have the most secure and stable base, with timely updates from the Strapi team.
• Long-Term Support and Community Ecosystem: Strapi 5 is the focus of ongoing development and community activity. The plugin ecosystem has moved to v5, with most popular plugins and providers updated to ensure compatibility.

In short, staying on Strapi 4 long-term is not advisable due to its upcoming end-of-life and lack of new features. Migrating to Strapi 5 provides immediate functional benefits and positions your project for continued support and innovation.

Have questions? Join us at Strapi's Discord

Strapi Open Office Hours Monday - Friday 12:30PM CST.

• Join Us

New Features of Strapi 5

Strapi 5 introduces significant new features and enhancements that make it a major upgrade over Strapi 4:

Document System & Content Versioning: Strapi 5 implements a new Document System that unifies content variations (drafts, published versions, and i18n locales) under a single model. Learn more about Draft and Publish.

Conditional Fields: In the content manager, allowing form fields to be shown or hidden dynamically based on user input. Learn more about conditional fields.

Checkout this demo, of how to use conditional fields from our recent community call.

Live Preview: Editors can now preview the website side-by-side with the content editor in the Strapi admin panel.

Note:_ The basic Preview feature is free for all users, while the fully integrated side-by-side Live Preview UI is available on certain paid plans.

You can tryit out in our (Launchpad demo)https://strapi.io/demo or checkout this blog post which will cover the steps of how you can set it up yourself in a Next.js application.

On-the-Fly Relation Creation: Content editors no longer need to leave a form to create a related entry. Strapi 5 lets you create and edit related content on the fly from within an edit page.

Official Strapi Client Library: Strapi 5 delivers a new Client Library to easily consume the Strapi API from frontend app. Learn more about Strapi Client](https://docs.strapi.io/cms/api/client).

To interact with your Strapi backend, initialize the client with your Strapi API base URL:

1import { strapi } from '@strapi/client';
2const client = strapi({ baseURL: 'http://localhost:1337/api' });

Strpai Client GitHub

Enhanced API Responses: The default JSON response format of the Content API is simpler and flatter in Strapi 5. Strapi 4 wrapped content in a nested data.attributes structure, but Strapi 5 returns attributes at the top level of the data object.

Built-in Internationalization (i18n): In Strapi 4, internationalization was provided by an optional plugin. In Strapi 5, i18n is integrated into the core of Strapi. Learn more about Strapi Internationalization (i18n)

Stronger TypeScript Support: Strapi 5’s codebase is almost entirely written in TypeScript, greatly improving the type definitions and developer experience for those using TypeScript.

New Plugin SDK: Developing custom Strapi plugins is easier in v5 thanks to the new Plugin SDK – a CLI tool for scaffolding and building plugins. Learn more about Strapi's Plugin SDK.

Here some helpfull tutorial to get you started on building your own plugins:

• How To Build Your First Strapi 5 Plu
• How To Build A Truck Tracker Custom Field and Map Widget for Strapi Admin
• Build a Custom Strapi Plugin with Medium and Dev.to APIs

Performance and Infrastructure Improvements: Under the hood, Strapi 5 brings updates that boost performance and modernize the stack:

• The admin panel bundler is now Vite instead of webpack, yielding faster dev server startup and Hot Module Reloading. Vite speeds up development and reduces build times.
• Default SQLite usage now relies on Better SQLite3 (replacing the older sqlite3 package) for improved stability and performance.
• Numerous dependency upgrades (e.g., React 18, React Router v6, Koa v2 to v3, Apollo Server 4 for GraphQL, etc.) ensure Strapi 5 is up-to-date with the latest stable libraries. These upgrades provide better performance and long-term support.
• The Strapi admin UI/Design System was refactored (with removal of the legacy helper plugin) to improve consistency and maintainability. While this is mostly behind-the-scenes, it means a more cohesive and stable admin interface, and it necessitated some breaking changes in how the admin is customized or extended.

In summary, Strapi 5 is a major step forward with improvements for both content editors (e.g. conditional fields, live preview, smoother relations) and developers (better API, TypeScript, plugin SDK, faster tooling). Next, we'll compare features between v4 and v5 in a summary table.

Strapi 4 vs Strapi 5: Feature Comparison

The table below highlights key feature differences and changes between Strapi 4 and Strapi 5:

Note: When migrating to v5, review the official breaking changes to understand all differences. Many breaking changes (especially around API responses, i18n, and certain deprecated APIs) are handled by Strapi’s upgrade tool automatically, but some manual updates may be required.

Plugin Ecosystem and Compatibility in v5

Strapi’s plugin ecosystem is an important consideration when migrating to v5. Most official and community plugins have been updated for Strapi 5, but you will need to ensure you use the correct version of each plugin:

• When planning the migration, audit your Strapi 4 project’s plugins. For each plugin, check if a Strapi 5 compatible release is available (on NPM or the Strapi Marketplace).

The Strapi team recommends verifying plugin compatibility as a prerequisite to upgrading. The Strapi Marketplace (market.strapi.io) lists plugins and often indicates which Strapi version they support.

• Install the v5 versions of your plugins after you upgrade Strapi. Strapi 4 plugins are generally not directly compatible with Strapi 5 due to changes in plugin APIs and removed dependencies.
• The good news is that most popular plugins have released Strapi 5 updates. For instance, the GraphQL plugin, Commerce and SEO plugins, SSO, and others had Strapi 5-ready versions around the time v5 was launched.

Custom plugins or very old plugins might require more attention. If a plugin you rely on doesn’t have a v5 version, you have a few options:

Look for an alternative plugin that provides similar functionality on v5, update the plugin code yourself (using Strapi 5’s Plugin SDK and documentation), or reach out to the plugin maintainer/community for guidance.

• During migration, it’s recommended to remove or disable any deprecated/incompatible plugins before upgrading, then add them back (or their replacements) after the core upgrade.

We suggests uninstalling plugins that are not yet compatible prior to migrating, to avoid issues during the upgrade.

• After upgrading, reinstall v5 supported plugins via your package manager, ensuring the version matches Strapi 5.

Check each plugin’s docs for any breaking changes or new configuration required in v5. For example, some plugin options might have moved or changed between major versions.

In summary, plan your plugin upgrades alongside the core migration. By using the updated v5 plugins from the marketplace and following their guidance, you can retain all your project’s functionality in Strapi 5.

Strapi 4 End-of-Life (EOL) and Support Status

If you are currently on Strapi 4, be aware of its support timeline. Strapi 4 is now in a maintenance phase and will reach end-of-life soon:

• Support Until March 2026: The Strapi team has announced that Strapi v4 will continue to be supported only until March 2026.

“Supported” in this context generally means critical bug fixes and security patches may be provided until that date. No new features or enhancements are being developed on v4 now that v5 is released.

• No New Features: As mentioned, Strapi 4 won’t receive new features. All innovation (like content editing improvements, performance upgrades, etc.) is happening in Strapi 5.
• Maintenance Mode: Between now and March 2026, you can expect only limited updates to Strapi 4 (if any). After the EOL date, even security fixes will likely stop, which could leave projects on v4 vulnerable or unsupported on newer server environments. Community help will also dwindle as most users move on to v5.
• Migration Encouraged: Given this timeline, it’s highly recommended to plan your migration to Strapi 5 well before Strapi 4’s EOL.

The Strapi documentation encourages users to upgrade whenever ready and provides resources to help Strapi Docs Migration Guide.

In summary, Strapi 4’s end-of-life is imminent in the next year or so. For a production project that you plan to maintain into 2026 and beyond, staying on v4 is not sustainable.

Upgrading to Strapi 5 will put you on the supported path and eliminate the risks associated with running an unsupported CMS version.

Migration Resources and Tools (Strapi v4 → v5)

Migrating from v4 to v5 is a significant version jump, but Strapi provides official tools and guides to simplify the process:

• Official Upgrade Guide: Start by reading the Strapi v4 to v5 Upgrade Guide in the documentation docs.strapi.io. It provides a step-by-step walkthrough, from preparation to post-migration steps.

Key steps include backing up your database and code, updating to the latest v4 patch version, and checking your plugins for compatibility (as discussed earlier).

• Strapi Upgrade Tool (Migration Script): Strapi offers a command-line upgrade tool that automates many of the code modifications needed for v5. You can run it using NPX: npx @strapi/upgrade major. This tool will:
  • Install the Strapi 5 packages (core and any official plugins you use) and update your package.json to the new versions.

  • Execute a series of codemods (code transformations) on your project to handle known breaking changes docs.strapi.io.

    These automated changes cover a lot of the repetitive work, saving you time.

  • After running the tool, your project should be partially migrated. You will still need to manually review and test everything, but the tool significantly reduces the manual effort.

• Breaking Changes Reference: Review the breaking changes documentation which lists each breaking change, its impact, and whether the upgrade codemod handles it.
• Data Migration: The content database itself usually doesn’t require a complex migration when going from v4 to v5. Strapi 5 includes automatic data migration scripts that run on first startup to adjust your database data as needed.
• Frontend/API Consumer Migration: If you have a frontend (React, Next.js, etc.) or other consumers of the Strapi API, be mindful that Strapi 5’s default API responses have changed (as described).

Plan to update your frontend code to handle the new response format (e.g., no more data.attributes wrapping). Strapi 5 allows returning v4 format JSON by using a special header during requests, which can serve as a temporary workaround while you update your front-end in phases.

Additionally, if your frontend interacts with certain endpoints (like GraphQL or uses specific query params), check the Strapi 5 docs for any changes (GraphQL plugin v5 might have some differences, REST endpoints are largely compatible except for the JSON shape and the new documentId usage).

• Community Guides and Examples: In addition to official docs, there are blog posts and videos from the Strapi community detailing migration experiences.

For example, the Strapi team published a blog “How To Migrate Your Project From Strapi 4 to Strapi 5” strapi.io

There are also community forum threads and a dedicated Strapi Discord where you can ask questions if you run into issues.

• Testing the Migration: It’s highly recommended to try the migration in a local or staging environment first. Do not upgrade your production server directly.

Instead, create a copy of your project and database, run the upgrade there, and test all functionality: - Verify content types and data have migrated properly (no missing fields or data). - Test all custom backend code (controllers, services, lifecycle hooks now possibly using document middleware, etc.). - Test the admin UI for any errors (especially if you had admin customizations or used community plugins). - Test your frontend or API clients against the new v5 backend to ensure they still function as expected (adjusting for any changes in API as needed). - Only once you're confident everything works, apply the upgrade to production (after taking final backups).

• Migration Scripts for Cloud (if applicable): If you are using Strapi Cloud or a CI/CD pipeline, consult Strapi’s resources on deploying updates. For Strapi Cloud, the procedure is to update your code locally following the guide and then trigger a deployment.

Strapi Cloud will handle running the necessary data migrations on deploy.

By leveraging the upgrade tool and following the official guides docs.strapi.io, the process of migrating to Strapi 5 can be performed methodically and with reduced risk.

The key is preparation (backups, checking plugins) and thorough testing. Now, let’s address some frequently asked questions about the migration:

FAQ: Strapi 4 to 5 Migration

1. What are the main differences between Strapi 4 and Strapi 5?

Strapi 5 introduces major improvements:

• Document System: Combines drafts, publish states, and localization into one model and supports content history.
• Plugin SDK: Makes it easier to build and maintain plugins.
• Flattened API Response: Removes nested attributes from JSON.
• Admin UI Redesign: Built with Vite, faster and more consistent.
• Full TypeScript Support: Improved developer experience.

2. How long is Strapi 4 supported, and why upgrade?

Strapi 4 is under maintenance until March 2026. It won't receive new features, only critical fixes. Upgrading to Strapi 5 ensures continued support, access to new features, and improved performance.

3. Is there an official migration tool?

Yes. Run:

npx @strapi/upgrade major

This CLI tool updates dependencies and runs codemods to automate many changes. You’ll still need to manually test and apply some fixes after the tool finishes.

4. What breaking changes should I expect?

Key breaking changes:

• REST API: No more attributes nesting.
• Document Service: Replaces many usages of entityService.
• File Upload: Now requires separate steps for file and entry creation.
• Node 18+ required.
• Removed/renamed internal packages: e.g., @strapi/utils, helper plugin.

5. Will my data migrate safely?

Yes, your data will migrate automatically. On first run, v5 will adjust your database schema. Always back up your database and media files before upgrading.

6. Are plugins and custom code compatible?

You must update all plugins to their Strapi 5 versions. Official plugins are available. For custom or community plugins, check for v5 support or update using the new SDK. Remove or disable plugins before migration, then add back compatible versions.

7. Will my frontend/API clients need updates?

Likely yes. Changes include:

• JSON structure changes (res.data.title instead of res.data.attributes.title).
• Use of documentId instead of id in some contexts.
• GraphQL schema updates.
• Recommended: use the new Strapi Client Library.

8. What changed with media and file uploads?

Media remains in public/uploads and is migrated. However, file upload via API is now a two-step process:

1. Upload to /upload
2. Create entry with file ID Ensure you update your frontend to match.

9. What new features does Strapi 5 include?

• Conditional Fields
• Live Preview
• Content Versioning & History
• Improved Internationalization
• Better Performance
• Full TypeScript & Plugin SDK

These make both content editing and development significantly better.

10. Where can I find help and resources?

• Migration Guide
• Upgrade Steps
• Top 10 Changes
• How to Migrate Blog
• Conditional Fields
• Live Preview
• Plugin Migration Forum
• Strapi Discord, GitHub examples, and community threads

Tip: Set up a test environment and backup everything before migrating.

By carefully planning your migration and utilizing the resources above, you can smoothly transition your project from Strapi 4 to Strapi 5. The new features and long-term support will make the effort worthwhile. Good luck with your Strapi 5 migration, and happy coding!

If you haven’t already, stop by our open office hours, held Monday–Friday at 12:30 PM CST on Discord. It’s a great way to connect, get help, and share your feedback directly with the team.