- Last updated: December 9, 2024 (Strapi 5 era)
- 19 min read
Commonly Asked Questions: Transitioning from Strapi 4 to Strapi 5
December 9, 2024
With the release of Strapi 5, developers and users have been introduced to a range of new features, breaking changes, and enhancements aimed at improving the overall developer experience. However, change often brings questions.
This post addresses some of the most commonly asked questions (faq) around what has changed when transitioning from Strapi 4 to Strapi 5, helping you navigate the updates with ease.
Key Changes in Strapi 5
What are the most significant updates in Strapi 5 from Strapi 4?
Strapi 5 introduces several updates, including:
- Document System: A new concept for managing content variations (e.g., drafts, published states, and locales) in a unified way, enabling advanced features like content history and draft & publish.
- Plugin SDK: Simplifies plugin development and sharing by automating packaging, bundling, and compatibility checks.
- Refined API Response Format: Flattened data structure for more intuitive and efficient API interactions.
- Strapi Design System Updates: Improved UI consistency and maintainability.
- TypeScript Integration: Enhanced support for type safety and developer productivity.
The Document System
Why was the Document System introduced?
The Document System was introduced to unify content variations like drafts, published states, and locales under a single model. This approach simplifies content management while paving the way for new features such as content history and draft & publish. By consolidating variations, Strapi ensures better consistency across the application and provides a robust foundation for plugins and advanced functionalities.
Is everything now a Document?
No. Only entities that represent content types with multiple states or locales are considered Documents. For example, the Media Library and Users & Permissions (U&P) are not managed as Documents because their use cases do not align with this model.
How do I incorporate the Document System into my plugin?
Plugins can interact with the Document System using the new Document Service API. This API allows you to create, update, and manage content variations programmatically, ensuring seamless integration with the Document model.
TypeScript Integration
Why is TypeScript integration significant in Strapi 5?
TypeScript integration in Strapi 5 marks a major milestone, aiming to provide stronger type safety, better tooling support, and a smoother development experience. Here’s how Strapi 5 uses TypeScript to empower developers:
1. Stronger Type Safety:
With TypeScript, Strapi 5 enforces stricter type checks, reducing runtime errors and ensuring greater confidence when working with complex data structures. Developers can now benefit from autocomplete and error detection directly in their IDEs, leading to fewer bugs and faster debugging.
2. Improved Developer Productivity:
TypeScript integration brings features like type inference and IntelliSense, helping developers write code more efficiently. By knowing the shape of data and available methods, developers can focus on building functionality rather than guessing how things work under the hood.
3. Enhanced Plugin Development:
Plugins built using the new Plugin SDK can now leverage TypeScript types, ensuring better compatibility and fewer issues when integrating plugins into projects. Plugin developers can use the provided type definitions to build more robust and reliable extensions.
4. Improved Design System:
The design system's migration to TypeScript was a significant effort, exposing potential breaking changes that were carefully addressed. This effort resulted in better type definitions for UI components, making integration and customization easier for developers.
5. Backward Compatibility:
Strapi 5 continues to support JavaScript projects, ensuring that developers who are not ready to adopt TypeScript can still work seamlessly with the framework. However, adopting TypeScript is highly recommended for new projects to take full advantage of its benefits.
The Plugin SDK
Why was a Plugin SDK developed?
The Plugin SDK simplifies the process of creating, packaging, and sharing plugins by automating tasks like dependency management and bundling. It also aligns with industry standards, reducing the learning curve for developers familiar with SDK-based ecosystems.
What does the Plugin SDK offer?
The SDK provides:
- Streamlined project initialization (
npx @strapi/sdk-plugin init my-plugin) - Build tools for packaging plugins in CommonJS and ES Modules.
- Live development tools (
watchandwatch:link) for real-time updates. - Verification tools to ensure plugins are ready for production.
Why was the helper plugin removed?
The helper plugin was removed to reduce complexity and eliminate circular dependencies within the Strapi ecosystem. It was initially used to centralize shared components and hooks, such as notifications or tracking, but this approach led to several problems:
- Bloated API Surface: The helper plugin included too many unrelated features, causing confusion among developers.
- Dependency Issues: Many contexts and providers relied on by the admin panel were tied to the helper plugin, creating a backward relationship where the plugin depended on the admin package. This resulted in circular dependencies and complications during the TypeScript migration.
- Misleading Name: Despite its name, the helper plugin was not an actual plugin, which further confused developers.
- Better Hierarchy: By moving shared utilities directly into the
adminpackage, the system became more linear and easier to maintain, withadminserving as the base layer for all frontend code.
This restructuring improves clarity, simplifies the codebase, and ensures a cleaner separation of concerns. It also paves the way for easier maintenance and development, especially with the integration of TypeScript.
API Changes
Why Did the Response Format Change?
Strapi 5 introduced a flattened API response format to improve readability, simplify data access, and boost performance. By eliminating the excessive nesting of attributes and data keys, developers can now work with cleaner and more streamlined data structures. This update is especially beneficial for handling complex queries, as it reduces the overhead associated with navigating deeply nested objects.
To illustrate the difference, we’ll compare an example response from a Strapi 4 project with its updated equivalent in Strapi 5.
We will use an example from our archived Strapi Corporate Strater Project to see the comparison between the old response and new.
We will take a look at the data being fetched for our landing page.
Example Comparison
Strapi 4 Response (Nested Format)
In Strapi 4, the response format is deeply nested, with attributes and related data stored under separate keys. For example:
1{
2 "data": [
3 {
4 "id": 1,
5 "attributes": {
6 "shortName": "Home Page",
7 "slug": "home",
8 "contentSections": [
9 {
10 "__component": "sections.hero",
11 "title": "Strapi [Starter] with Next JS",
12 "picture": {
13 "data": {
14 "attributes": {
15 "url": "/uploads/undraw_woman_ffrd.svg"
16 }
17 }
18 }
19 }
20 ]
21 }
22 }
23 ]
24}This structure requires accessing multiple layers (e.g., data -> attributes -> contentSections) to retrieve information, making it cumbersome for developers and less performant.
Strapi 5 Response (Flattened Format)
In Strapi 5, the response has been streamlined. Attributes are now at the top level, and related data no longer requires navigating through a data or attributes wrapper:
1{
2 "data": [
3 {
4 "id": 10,
5 "shortName": "Home Page",
6 "slug": "home",
7 "contentSections": [
8 {
9 "__component": "sections.hero",
10 "title": "Strapi [Starter] with Next JS",
11 "picture": {
12 "id": 33,
13 "url": "/uploads/undraw_woman_ffrd.svg"
14 }
15 }
16 ]
17 }
18 ]
19}This flattened format makes it easier to extract data directly, improving code clarity and reducing the need for verbose queries.
Example Comparison: Full Response Strapi 4 vs Strapi 5
Strapi 4 Response:
1{
2 "data": [
3 {
4 "id": 1,
5 "attributes": {
6 "shortName": "Home Page",
7 "slug": "home",
8 "heading": "dfsgsg",
9 "description": "dfsgsdfg",
10 "createdAt": "2023-03-08T14:13:57.041Z",
11 "updatedAt": "2024-05-31T16:19:31.954Z",
12 "publishedAt": "2023-03-08T14:28:43.068Z",
13 "locale": "en",
14 "contentSections": [
15 {
16 "id": 1,
17 "__component": "sections.hero",
18 "title": "Strapi [Starter] with Next JS",
19 "description": "This is build with [Strapi] and [Next] JS. A match made in heaven.",
20 "picture": {
21 "data": {
22 "id": 11,
23 "attributes": {
24 "url": "/uploads/undraw_woman_ffrd_b3ac24fb06.svg",
25 "alternativeText": null,
26 "caption": null,
27 "width": 643,
28 "height": 700
29 }
30 }
31 },
32 "buttons": [
33 {
34 "id": 2,
35 "url": "https://discord.com/invite/strapi",
36 "newTab": true,
37 "text": "Discord",
38 "type": "secondary"
39 },
40 {
41 "id": 3,
42 "url": "https://strapi.io/events",
43 "newTab": true,
44 "text": "Events",
45 "type": "primary"
46 }
47 ]
48 },
49 {
50 "id": 1,
51 "__component": "sections.features",
52 "heading": "Features",
53 "description": "Welcome to Strapi Starter",
54 "feature": [
55 {
56 "id": 1,
57 "title": "Discover Next.js",
58 "description": "The React Framework for Production: Explore the future of web development with Next.js, the cutting-edge React framework.",
59 "showLink": true,
60 "newTab": true,
61 "url": "https://vercel.com/",
62 "text": "Learn more",
63 "media": {
64 "data": null
65 }
66 },
67 {
68 "id": 2,
69 "title": "Strapi",
70 "description": "Unleash the power of Strapi, the leading open-source headless CMS that lets you create, manage, and distribute your content across multiple platforms.",
71 "showLink": true,
72 "newTab": true,
73 "url": "https://strapi.io",
74 "text": "Learn more",
75 "media": {
76 "data": null
77 }
78 },
79 {
80 "id": 3,
81 "title": "Cloud",
82 "description": "Simplify your content management experience with Strapi Cloud, the fully-managed hosting solution for your Strapi projects.",
83 "showLink": true,
84 "newTab": true,
85 "url": "https://strapi.io/cloud",
86 "text": "Learn more",
87 "media": {
88 "data": null
89 }
90 }
91 ]
92 },
93 {
94 "id": 1,
95 "__component": "sections.pricing",
96 "title": "Our Plans",
97 "plans": [
98 {
99 "id": 1,
100 "name": "Free",
101 "description": "Features",
102 "isRecommended": false,
103 "price": 0,
104 "pricePeriod": "Monthly",
105 "product_features": {
106 "data": [
107 {
108 "id": 1,
109 "attributes": {
110 "name": "Example Feature 1",
111 "createdAt": "2023-03-10T15:45:14.988Z",
112 "updatedAt": "2023-03-28T15:45:07.118Z",
113 "publishedAt": "2023-03-10T15:45:16.468Z"
114 }
115 },
116 {
117 "id": 3,
118 "attributes": {
119 "name": "Example Feature 2",
120 "createdAt": "2023-03-10T15:46:27.207Z",
121 "updatedAt": "2023-03-28T15:45:18.540Z",
122 "publishedAt": "2023-03-10T15:46:27.565Z"
123 }
124 },
125 {
126 "id": 4,
127 "attributes": {
128 "name": "Example Feature 3",
129 "createdAt": "2023-03-10T15:46:39.431Z",
130 "updatedAt": "2023-03-28T15:45:28.608Z",
131 "publishedAt": "2023-03-10T15:46:40.548Z"
132 }
133 }
134 ]
135 }
136 },
137 {
138 "id": 2,
139 "name": "Pro",
140 "description": "Features",
141 "isRecommended": true,
142 "price": 9.99,
143 "pricePeriod": "monthly",
144 "product_features": {
145 "data": [
146 {
147 "id": 1,
148 "attributes": {
149 "name": "Example Feature 1",
150 "createdAt": "2023-03-10T15:45:14.988Z",
151 "updatedAt": "2023-03-28T15:45:07.118Z",
152 "publishedAt": "2023-03-10T15:45:16.468Z"
153 }
154 },
155 {
156 "id": 3,
157 "attributes": {
158 "name": "Example Feature 2",
159 "createdAt": "2023-03-10T15:46:27.207Z",
160 "updatedAt": "2023-03-28T15:45:18.540Z",
161 "publishedAt": "2023-03-10T15:46:27.565Z"
162 }
163 },
164 {
165 "id": 4,
166 "attributes": {
167 "name": "Example Feature 3",
168 "createdAt": "2023-03-10T15:46:39.431Z",
169 "updatedAt": "2023-03-28T15:45:28.608Z",
170 "publishedAt": "2023-03-10T15:46:40.548Z"
171 }
172 },
173 {
174 "id": 2,
175 "attributes": {
176 "name": "Example Feature 4",
177 "createdAt": "2023-03-10T15:45:47.489Z",
178 "updatedAt": "2023-03-28T15:46:00.360Z",
179 "publishedAt": "2023-03-10T15:46:10.561Z"
180 }
181 }
182 ]
183 }
184 },
185 {
186 "id": 3,
187 "name": "Enterprise ",
188 "description": "Features",
189 "isRecommended": false,
190 "price": 19.99,
191 "pricePeriod": "monthly",
192 "product_features": {
193 "data": [
194 {
195 "id": 1,
196 "attributes": {
197 "name": "Example Feature 1",
198 "createdAt": "2023-03-10T15:45:14.988Z",
199 "updatedAt": "2023-03-28T15:45:07.118Z",
200 "publishedAt": "2023-03-10T15:45:16.468Z"
201 }
202 },
203 {
204 "id": 3,
205 "attributes": {
206 "name": "Example Feature 2",
207 "createdAt": "2023-03-10T15:46:27.207Z",
208 "updatedAt": "2023-03-28T15:45:18.540Z",
209 "publishedAt": "2023-03-10T15:46:27.565Z"
210 }
211 },
212 {
213 "id": 4,
214 "attributes": {
215 "name": "Example Feature 3",
216 "createdAt": "2023-03-10T15:46:39.431Z",
217 "updatedAt": "2023-03-28T15:45:28.608Z",
218 "publishedAt": "2023-03-10T15:46:40.548Z"
219 }
220 },
221 {
222 "id": 2,
223 "attributes": {
224 "name": "Example Feature 4",
225 "createdAt": "2023-03-10T15:45:47.489Z",
226 "updatedAt": "2023-03-28T15:46:00.360Z",
227 "publishedAt": "2023-03-10T15:46:10.561Z"
228 }
229 },
230 {
231 "id": 5,
232 "attributes": {
233 "name": "Example Feature 5",
234 "createdAt": "2023-03-28T15:45:55.243Z",
235 "updatedAt": "2023-03-28T15:50:01.464Z",
236 "publishedAt": "2023-03-28T15:50:01.464Z"
237 }
238 }
239 ]
240 }
241 }
242 ]
243 },
244 {
245 "id": 1,
246 "__component": "sections.testimonials-group",
247 "title": "Testimonials",
248 "description": "Hello",
249 "testimonials": [
250 {
251 "id": 1,
252 "text": "ed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo.",
253 "authorName": "Paul Brats",
254 "picture": {
255 "data": {
256 "id": 20,
257 "attributes": {
258 "url": "/uploads/paul_brats_012832af74.jpg",
259 "alternativeText": null,
260 "caption": null,
261 "width": 200,
262 "height": 200
263 }
264 }
265 }
266 },
267 {
268 "id": 2,
269 "text": "ed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo.",
270 "authorName": "Kit Kat",
271 "picture": {
272 "data": {
273 "id": 22,
274 "attributes": {
275 "url": "/uploads/kit_kat_96feba6636.png",
276 "alternativeText": null,
277 "caption": null,
278 "width": 2000,
279 "height": 2000
280 }
281 }
282 }
283 }
284 ]
285 },
286 {
287 "id": 1,
288 "__component": "sections.lead-form",
289 "title": "Join our community.",
290 "emailPlaceholder": "Enter your email",
291 "location": "main page",
292 "description": "Doloribus consectetur quasi ipsa quo neque culpa blanditiis ducimus recusandae a veritatis optio cumque, in harum ad nam!",
293 "submitButton": {
294 "id": 1,
295 "text": "Submit",
296 "type": "primary"
297 }
298 }
299 ],
300 "seo": {
301 "id": 8,
302 "metaTitle": "dfgsdg",
303 "metaDescription": "dsfgsdf",
304 "shareImage": {
305 "data": null
306 }
307 }
308 }
309 }
310 ],
311 "meta": {
312 "pagination": {
313 "page": 1,
314 "pageSize": 25,
315 "pageCount": 1,
316 "total": 1
317 }
318 }
319}Strapi 5 Response:
1{
2 "data": [
3 {
4 "id": 10,
5 "shortName": "Home Page",
6 "slug": "home",
7 "heading": "Home Page",
8 "description": "This is the home page",
9 "createdAt": "2023-03-08T14:13:57.041Z",
10 "updatedAt": "2024-09-25T16:22:15.255Z",
11 "publishedAt": "2024-09-25T16:22:15.278Z",
12 "locale": "en",
13 "documentId": "jp9xgszv0fiebxygaonae4jr",
14 "contentSections": [
15 {
16 "__component": "sections.hero",
17 "id": 8,
18 "title": "Strapi [Starter] with Next JS",
19 "description": "This is build with [Strapi] and [Next] JS. A match made in heaven.",
20 "picture": {
21 "id": 33,
22 "name": "undraw_woman_ffrd.svg",
23 "alternativeText": null,
24 "caption": null,
25 "width": 643,
26 "height": 700,
27 "formats": null,
28 "hash": "undraw_woman_ffrd_b3ac24fb06",
29 "ext": ".svg",
30 "mime": "image/svg+xml",
31 "size": 6.76,
32 "url": "/uploads/undraw_woman_ffrd_b3ac24fb06.svg",
33 "previewUrl": null,
34 "provider": "local",
35 "provider_metadata": null,
36 "createdAt": "2023-03-09T18:10:31.642Z",
37 "updatedAt": "2024-12-07T22:01:43.508Z",
38 "documentId": "lojbt8nq3a7lbs1ket3s4ye2",
39 "locale": null,
40 "publishedAt": null
41 },
42 "buttons": [
43 {
44 "id": 9,
45 "url": "https://discord.com/invite/strapi",
46 "newTab": true,
47 "text": "Discord",
48 "type": "secondary"
49 },
50 {
51 "id": 10,
52 "url": "https://strapi.io/events",
53 "newTab": true,
54 "text": "Events",
55 "type": "primary"
56 }
57 ]
58 },
59 {
60 "__component": "sections.features",
61 "id": 4,
62 "heading": "Features",
63 "description": "Welcome to Strapi Starter",
64 "feature": [
65 {
66 "id": 10,
67 "title": "Discover Next.js",
68 "description": "The React Framework for Production: Explore the future of web development with Next.js, the cutting-edge React framework.",
69 "showLink": true,
70 "newTab": true,
71 "url": "https://vercel.com/",
72 "text": "Learn more"
73 },
74 {
75 "id": 11,
76 "title": "Strapi",
77 "description": "Unleash the power of Strapi, the leading open-source headless CMS that lets you create, manage, and distribute your content across multiple platforms.",
78 "showLink": true,
79 "newTab": true,
80 "url": "https://strapi.io",
81 "text": "Learn more"
82 },
83 {
84 "id": 12,
85 "title": "Cloud",
86 "description": "Simplify your content management experience with Strapi Cloud, the fully-managed hosting solution for your Strapi projects.",
87 "showLink": true,
88 "newTab": true,
89 "url": "https://strapi.io/cloud",
90 "text": "Learn more"
91 }
92 ]
93 },
94 {
95 "__component": "sections.pricing",
96 "id": 4,
97 "title": "Our Plans",
98 "plans": [
99 {
100 "id": 10,
101 "name": "Free",
102 "description": "Features",
103 "isRecommended": false,
104 "price": 0,
105 "pricePeriod": "Monthly",
106 "product_features": [
107 {
108 "id": 16,
109 "name": "Example Feature 1",
110 "createdAt": "2023-03-10T15:45:14.988Z",
111 "updatedAt": "2023-03-28T15:45:07.118Z",
112 "publishedAt": "2023-03-10T15:45:16.468Z",
113 "documentId": "ji45ovqy68cpuj9a8hgfb67v",
114 "locale": null
115 },
116 {
117 "id": 18,
118 "name": "Example Feature 2",
119 "createdAt": "2023-03-10T15:46:27.207Z",
120 "updatedAt": "2023-03-28T15:45:18.540Z",
121 "publishedAt": "2023-03-10T15:46:27.565Z",
122 "documentId": "wxim98n316kfqy54zsmdazkp",
123 "locale": null
124 },
125 {
126 "id": 19,
127 "name": "Example Feature 3",
128 "createdAt": "2023-03-10T15:46:39.431Z",
129 "updatedAt": "2023-03-28T15:45:28.608Z",
130 "publishedAt": "2023-03-10T15:46:40.548Z",
131 "documentId": "v6phofjnzfn0q2i9ham968mj",
132 "locale": null
133 }
134 ]
135 },
136 {
137 "id": 11,
138 "name": "Pro",
139 "description": "Features",
140 "isRecommended": true,
141 "price": 9.99,
142 "pricePeriod": "monthly",
143 "product_features": [
144 {
145 "id": 16,
146 "name": "Example Feature 1",
147 "createdAt": "2023-03-10T15:45:14.988Z",
148 "updatedAt": "2023-03-28T15:45:07.118Z",
149 "publishedAt": "2023-03-10T15:45:16.468Z",
150 "documentId": "ji45ovqy68cpuj9a8hgfb67v",
151 "locale": null
152 },
153 {
154 "id": 18,
155 "name": "Example Feature 2",
156 "createdAt": "2023-03-10T15:46:27.207Z",
157 "updatedAt": "2023-03-28T15:45:18.540Z",
158 "publishedAt": "2023-03-10T15:46:27.565Z",
159 "documentId": "wxim98n316kfqy54zsmdazkp",
160 "locale": null
161 },
162 {
163 "id": 19,
164 "name": "Example Feature 3",
165 "createdAt": "2023-03-10T15:46:39.431Z",
166 "updatedAt": "2023-03-28T15:45:28.608Z",
167 "publishedAt": "2023-03-10T15:46:40.548Z",
168 "documentId": "v6phofjnzfn0q2i9ham968mj",
169 "locale": null
170 },
171 {
172 "id": 17,
173 "name": "Example Feature 4",
174 "createdAt": "2023-03-10T15:45:47.489Z",
175 "updatedAt": "2023-03-28T15:46:00.360Z",
176 "publishedAt": "2023-03-10T15:46:10.561Z",
177 "documentId": "jykjv5t5h5kqh2u649un53ss",
178 "locale": null
179 }
180 ]
181 },
182 {
183 "id": 12,
184 "name": "Enterprise ",
185 "description": "Features",
186 "isRecommended": false,
187 "price": 19.99,
188 "pricePeriod": "monthly",
189 "product_features": [
190 {
191 "id": 16,
192 "name": "Example Feature 1",
193 "createdAt": "2023-03-10T15:45:14.988Z",
194 "updatedAt": "2023-03-28T15:45:07.118Z",
195 "publishedAt": "2023-03-10T15:45:16.468Z",
196 "documentId": "ji45ovqy68cpuj9a8hgfb67v",
197 "locale": null
198 },
199 {
200 "id": 18,
201 "name": "Example Feature 2",
202 "createdAt": "2023-03-10T15:46:27.207Z",
203 "updatedAt": "2023-03-28T15:45:18.540Z",
204 "publishedAt": "2023-03-10T15:46:27.565Z",
205 "documentId": "wxim98n316kfqy54zsmdazkp",
206 "locale": null
207 },
208 {
209 "id": 19,
210 "name": "Example Feature 3",
211 "createdAt": "2023-03-10T15:46:39.431Z",
212 "updatedAt": "2023-03-28T15:45:28.608Z",
213 "publishedAt": "2023-03-10T15:46:40.548Z",
214 "documentId": "v6phofjnzfn0q2i9ham968mj",
215 "locale": null
216 },
217 {
218 "id": 17,
219 "name": "Example Feature 4",
220 "createdAt": "2023-03-10T15:45:47.489Z",
221 "updatedAt": "2023-03-28T15:46:00.360Z",
222 "publishedAt": "2023-03-10T15:46:10.561Z",
223 "documentId": "jykjv5t5h5kqh2u649un53ss",
224 "locale": null
225 },
226 {
227 "id": 20,
228 "name": "Example Feature 5",
229 "createdAt": "2023-03-28T15:45:55.243Z",
230 "updatedAt": "2023-03-28T15:50:01.464Z",
231 "publishedAt": "2023-03-28T15:50:01.464Z",
232 "documentId": "vjmgoy0s7xvdgn1hlyk3wxhz",
233 "locale": null
234 }
235 ]
236 }
237 ]
238 },
239 {
240 "__component": "sections.testimonials-group",
241 "id": 4,
242 "title": "Testimonials",
243 "description": "Hello",
244 "testimonials": [
245 {
246 "id": 7,
247 "text": "ed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo.",
248 "authorName": "Paul Brats",
249 "picture": {
250 "id": 30,
251 "name": "undraw_male_avatar_g98d.svg",
252 "alternativeText": null,
253 "caption": null,
254 "width": 532,
255 "height": 532,
256 "formats": null,
257 "hash": "undraw_male_avatar_g98d_88c6a54b04",
258 "ext": ".svg",
259 "mime": "image/svg+xml",
260 "size": 3.17,
261 "url": "/uploads/undraw_male_avatar_g98d_88c6a54b04.svg",
262 "previewUrl": null,
263 "provider": "local",
264 "provider_metadata": null,
265 "createdAt": "2023-03-09T18:09:14.586Z",
266 "updatedAt": "2024-12-07T22:01:43.466Z",
267 "documentId": "xcrtk3vtw6zy6jls5taxoex5",
268 "locale": null,
269 "publishedAt": null
270 }
271 },
272 {
273 "id": 8,
274 "text": "ed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo.",
275 "authorName": "Kit Kat",
276 "picture": {
277 "id": 32,
278 "name": "undraw_female_avatar_efig.svg",
279 "alternativeText": null,
280 "caption": null,
281 "width": 532,
282 "height": 532,
283 "formats": null,
284 "hash": "undraw_female_avatar_efig_38ecf0db0c",
285 "ext": ".svg",
286 "mime": "image/svg+xml",
287 "size": 5.01,
288 "url": "/uploads/undraw_female_avatar_efig_38ecf0db0c.svg",
289 "previewUrl": null,
290 "provider": "local",
291 "provider_metadata": null,
292 "createdAt": "2023-03-09T18:10:31.630Z",
293 "updatedAt": "2024-12-07T22:01:43.491Z",
294 "documentId": "hn44xb0ixxzckz3nii5hgpld",
295 "locale": null,
296 "publishedAt": null
297 }
298 }
299 ]
300 },
301 {
302 "__component": "sections.lead-form",
303 "id": 4,
304 "title": "Join our community.",
305 "emailPlaceholder": "Enter your email",
306 "location": "main page",
307 "description": "Doloribus consectetur quasi ipsa quo neque culpa blanditiis ducimus recusandae a veritatis optio cumque, in harum ad nam!",
308 "submitButton": {
309 "id": 4,
310 "text": "Submit",
311 "type": "primary"
312 }
313 }
314 ],
315 "seo": {
316 "id": 36,
317 "metaTitle": "Home Page",
318 "metaDescription": "This is the home page",
319 "shareImage": {
320 "id": 41,
321 "name": "ai-prompt.jpg",
322 "alternativeText": null,
323 "caption": null,
324 "width": 5192,
325 "height": 3466,
326 "formats": {
327 "thumbnail": {
328 "name": "thumbnail_ai-prompt.jpg",
329 "hash": "thumbnail_ai_prompt_e43fe026b1",
330 "ext": ".jpg",
331 "mime": "image/jpeg",
332 "path": null,
333 "width": 234,
334 "height": 156,
335 "size": 8.15,
336 "url": "/uploads/thumbnail_ai_prompt_e43fe026b1.jpg"
337 },
338 "small": {
339 "name": "small_ai-prompt.jpg",
340 "hash": "small_ai_prompt_e43fe026b1",
341 "ext": ".jpg",
342 "mime": "image/jpeg",
343 "path": null,
344 "width": 500,
345 "height": 334,
346 "size": 24.77,
347 "url": "/uploads/small_ai_prompt_e43fe026b1.jpg"
348 },
349 "medium": {
350 "name": "medium_ai-prompt.jpg",
351 "hash": "medium_ai_prompt_e43fe026b1",
352 "ext": ".jpg",
353 "mime": "image/jpeg",
354 "path": null,
355 "width": 750,
356 "height": 500,
357 "size": 47.18,
358 "url": "/uploads/medium_ai_prompt_e43fe026b1.jpg"
359 },
360 "large": {
361 "name": "large_ai-prompt.jpg",
362 "hash": "large_ai_prompt_e43fe026b1",
363 "ext": ".jpg",
364 "mime": "image/jpeg",
365 "path": null,
366 "width": 1000,
367 "height": 667,
368 "size": 73.64,
369 "url": "/uploads/large_ai_prompt_e43fe026b1.jpg"
370 }
371 },
372 "hash": "ai_prompt_e43fe026b1",
373 "ext": ".jpg",
374 "mime": "image/jpeg",
375 "size": 2395.35,
376 "url": "/uploads/ai_prompt_e43fe026b1.jpg",
377 "previewUrl": null,
378 "provider": "local",
379 "provider_metadata": null,
380 "createdAt": "2023-03-28T17:06:52.873Z",
381 "updatedAt": "2024-12-07T22:01:45.567Z",
382 "documentId": "uucl140hzuga3r5tmgiow2db",
383 "locale": null,
384 "publishedAt": null
385 }
386 }
387 }
388 ],
389 "meta": {
390 "pagination": {
391 "page": 1,
392 "pageSize": 25,
393 "pageCount": 1,
394 "total": 1
395 }
396 }
397}Key Changes in Strapi 5 API Responses
- Flattened Structure:
- Attributes like
shortName,slug, andcontentSectionsare now at the top level within thedataobject, eliminating theattributeswrapper.
- Attributes like
- Simplified Media and Relations:
- Related media and entities, previously nested under additional
dataandattributeskeys, are now directly accessible with essential fields such asidandurl.
- Related media and entities, previously nested under additional
- Introduction of
documentId:- A new
documentIdfield has been added for better tracking and handling of documents in the response.
- A new
Backward Compatibility for Migration
Strapi 5 provides a retro-compatibility mode for developers migrating from Strapi 4. This mode allows continued use of the old response format by adding the following header to API requests:
1 Strapi-Response-Format: v4Migration Steps:
- Enable Retro-Compatibility:
- Start by enabling the v4 response format using the header mentioned above. This prevents immediate breaking changes in your frontend.
- Update Queries and Code:
- Gradually update your frontend code to accommodate the new flattened format.
- Validate Functionality:
- Test your application to ensure all updated queries and mutations are functioning correctly.
- Disable Retro-Compatibility:
- Once the transition is complete, remove the header and fully adopt the Strapi 5 response format.
GraphQL API Updates
The GraphQL API has also been updated to align with the new response format. While it remains backward-compatible during migration, queries and mutations may need adjustments to match the new flattened schema.
Why the Change Matters
The new response format in Strapi 5 simplifies frontend development by:
- Reducing unnecessary nesting and improving data readability.
- Enhancing performance with leaner responses.
- Streamlining code required to access API data.
By providing a retro-compatibility mode, Strapi ensures a smooth transition for projects migrating from version 4, allowing developers to take advantage of the improved format at their own pace.
Strapi Design System and Admin Panel
Why were there so many changes to the Strapi Design System?
The extensive changes to Strapi's design system stem from the need to address accumulated technical debt, enhance developer experience, and prepare the system for future scalability. Here are the key reasons:
- Framework Agnosticism: The original design system was tightly coupled to the CMS, limiting its flexibility. Making it framework-agnostic was essential for extending its use across projects like Strapi Cloud and other potential products.
- Developer Experience (DX): Minor inconveniences, such as manual
remcalculations and inconsistent imports, created friction for developers. These changes simplify usage and improve the overall DX. - TypeScript Migration: Migrating the design system to TypeScript highlighted potential breaking changes. Consolidating these into a single major release minimizes ongoing disruptions.
- SVG Overhaul: Hardcoded values for SVG icons caused significant issues with customization and responsiveness. The changes ensure more flexibility and consistent behavior.
- Composability and Flexibility: Many components were too rigid due to overly DRY (Don't Repeat Yourself) practices. Introducing more composability provides developers with greater freedom to adapt components to their needs.
- Modernization with Dot Notation: Adopting a consistent naming pattern for components, like the dot notation used in
radix-ui, creates a more intuitive API and aligns with modern best practices. - Accessibility and Documentation: Improving component testing, accessibility, and documentation ensures the design system is a first-class product that meets modern standards and user expectations.
- Breaking Changes for Long-term Gains: These changes set the foundation for a more robust, scalable, and user-friendly design system. Comprehensive migration guides and tools like codemods are planned to help developers transition smoothly.
In summary, the Strapi design system overhaul addresses past limitations, aligns with industry best practices, and prepares it for future scalability, even if it introduces short-term challenges for developers.
Why can’t we modify the admin panel anymore?
The reason it's no longer possible to modify the admin panel with tools like patch-package is due to a change in Strapi's build tooling, which now uses Vite and Rollup for bundling.
These tools create optimized bundles and generate file names with content-based hashes, which can change with each build. As a result, the structure of the bundled files makes it significantly harder to apply patches reliably, particularly across multiple releases.
It's important to clarify that this wasn't a deliberate decision to remove customization but rather a side effect of optimizing the build process. While patch-package was often used as a workaround to make modifications, it was always intended as a temporary fix rather than a sustainable customization method.
For users who need to modify the frontend, the recommended approach is to use Strapi's documented public APIs. Additionally, users can propose new APIs or contribute to implementing them after discussing their ideas with the Strapi team to ensure they align with the project and can be merged.
However, if users still want to use patch-package at their own risk, the process is as follows:
- Fork Strapi and check out the tag that matches the version you want to modify.
- Set it up for contributing by running yarn setup.
- Make the changes you need in the source code.
- Build the code by running yarn build.
- Use patch-package to generate the patch on the dist folder: npx patch-package dist. Apply the patch to your application.
Keep in mind that this approach requires maintaining and updating the patches for every release, and it carries risks, as it operates outside the intended customization framework.
Developer Tools
Why did lifecycles become less useful?
Lifecycles in Strapi 5 haven’t fundamentally changed—they still get triggered by database actions just as they did in Strapi 4. However, the introduction of the new Draft & Publish (D&P) system, Content History, and the document service has added significant complexity to data management.
In Strapi 5, a single document can now correspond to multiple database entries (e.g., drafts, historical versions, and different locales). This means that actions like publish, unpublish, or discardDraft can trigger multiple database lifecycles. For example:
- Publish/Unpublish: These actions result in multiple database operations, such as creating or deleting entries for each locale.
- Discard Draft: This triggers both
createanddeletelifecycles, which did not occur in earlier versions.
Because of this complexity, lifecycles written for Strapi 4 are likely to break in Strapi 5, especially for content types that utilize Draft & Publish, internationalization (i18n), or other advanced features.
Can You Still Use Lifecycles?
While it’s technically possible to use the old lifecycles, they are only recommended for very basic content types that do not use Draft & Publish, internationalization, or other features that add complexity or for parts of the Strapi application that does not use the document service (users-permissions plugin, upload package, or custom plugins).
For most cases, especially when dealing with more complex data structures, using document service middlewares is highly recommended. These provide a more reliable and powerful way to manage custom logic in Strapi 5.
Why Use Document Service Middlewares?
Document service middlewares offer significant advantages, including:
- Greater control over document-related operations.
- A more predictable and stable way to implement custom logic.
- Better compatibility with the Draft & Publish system and internationalization features.
- More agnostic programmatic API that allows for easier registration of middlewares from anywhere in the application including plugins.
For these reasons, the Strapi team encourages migrating to document service middlewares, as they provide more value and better align with the architectural improvements in Strapi 5.
Looking Ahead
Strapi 5 is a significant step forward in enhancing the developer experience. While it introduces some breaking changes in plugin development and the change from entity service to document service, these updates are designed to make Strapi more powerful, flexible, and easier to use.
By addressing common questions, improving TypeScript support, and providing robust tools like the Plugin SDK and Document System, Strapi 5 sets the stage for future improvements and features..
Have more questions? Drop them in the comments, or check out the official Strapi documentation for more insights into the latest version!