Overview
Upgrading from Strapi v4 to v5 is a major step—not a routine dependency update.
Strapi v5 introduces a more modern, production-oriented architecture with improvements such as a Vite-powered Admin UI, first-class TypeScript support, and clearer build workflows. At the same time, it brings significant breaking changes that directly impact how Strapi projects are built, configured, and deployed.
This first article focuses on understanding the differences between Strapi v4 and v5.
Rather than diving into implementation details or troubleshooting, the goal here is to give you a clear mental model of what changed and where those changes affect existing projects. In the next article, we will dive into real-world upgrade pitfalls and lessons learned from a production migration.
High-Level Differences
| Area | Strapi v4 | Strapi v5 |
|---|---|---|
| Admin UI bundler | Webpack | Vite |
| Admin UI build | Built at runtime | Pre-build required |
| Configuration files | JavaScript | TypeScript |
| Node.js support | 14 / 16 | 18 / 20 recommended |
| Environment variables | Mostly runtime | Separated by build vs runtime |
| Plugin ecosystem | Broad | Many plugins not yet compatible |
| Production workflow | Flexible | Explicit and strict |
Admin UI Architecture Changes
Strapi v4
In v4, the Admin UI is bundled with Webpack and built automatically when the Strapi server starts.
This makes development convenient, but the build process is largely implicit.
Environment variables affecting the Admin UI are often picked up at runtime, which can hide configuration issues until later.
Strapi v5
In v5, the Admin UI is powered by Vite.
Key changes:
- The Admin UI must be explicitly built using:
yarn build
- The output is a set of static assets
- Admin UI configuration is locked in at build time
This makes the behavior faster and more predictable, but also far less forgiving.
Build vs Start: A Clear Separation
One of the most important conceptual changes in Strapi v5 is the separation between build time and runtime.
Strapi v4
yarn start
├─ Admin UI is built
└─ API server starts
Strapi v5
yarn build # Admin UI
↓
yarn start # API server
This separation is foundational to how Strapi v5 is designed and affects everything from environment variables to containerization.
Environment Variable Handling
Strapi v4
- Environment variables are mostly read at runtime
- Restarting the server is usually enough to apply changes
Strapi v5
Environment variables are evaluated at different phases:
| Phase | Affects |
|---|---|
| Build time | Admin UI |
| Runtime | API / server |
This design is more explicit and production-friendly, but it requires careful planning—especially for containerized deployments.
Configuration Files: JavaScript → TypeScript
Strapi v4
- Configuration files are written in JavaScript
- CommonJS (
module.exports) syntax - Flexible but loosely structured
Strapi v5
- Configuration files are written in TypeScript
- ES module syntax (
export default) - Clearer structure and better tooling support
This change improves maintainability but increases the initial migration cost.
Plugin Ecosystem Differences
Strapi v4
- Large plugin ecosystem
- Many community plugins available
- Compatibility issues are relatively rare
Strapi v5
- Many plugins are not yet v5-compatible
- Some plugins install successfully but fail at runtime
- Plugin compatibility must be verified in advance
This is one of the biggest unknowns during upgrades.
Node.js and Runtime Expectations
| Area | v4 | v5 |
|---|---|---|
| Node.js versions | 14 / 16 | 18 / 20 |
| ESM support | Partial | Effectively required |
| TypeScript | Optional | Practically mandatory |
Strapi v5 assumes a modern Node.js and tooling environment by default.
What This Means for Upgrades
Strapi v5 is clearly designed for:
- Modern JavaScript / TypeScript stacks
- Explicit build pipelines
- Containerized and cloud-native deployments
However, this also means:
Upgrading from v4 to v5 is closer to a controlled migration than a simple upgrade.
Understanding these differences upfront is critical before touching any production code.
What’s Next
This article focused on what changed between Strapi v4 and v5.
In the next article, we will cover:
- Common upgrade pitfalls in real projects
- Admin UI build failures and environment variable traps
- CORS issues in frontend/API split architectures
- Docker and Kubernetes (AKS)–specific problems and solutions
If you’re planning a v4 → v5 upgrade, those practical lessons can save you a lot of trial and error.
This article focuses on practical differences and real-world implications.
For detailed API references and official migration guidance, please refer to the Strapi v5 documentation: