Forem: Strapi

Strapi release roundup: everything that changed between January and February 2026

Strapi — Fri, 13 Mar 2026 10:19:01 +0000

Certain product updates don't make headlines but quietly transform the day-to-day experience of using a tool. It's not flashy features, it's fixing many little issues that were negatively impacting Strapi users' satisfaction.

Between January 2026 and February 2026, across releases v5.33 through v5.39, that's the kind of work Strapi shipped. The Strapi team invested more time reviewing community proposals and addressing long-standing requests. The numbers speak for themselves: 49 GitHub pull requests from the community, over 150 issues closed. A release window built together, shaped by what the community flagged, fixed by people inside and outside the core team alike.
Here's what changed.

Admin UI & mobile experience

Mobile support in the Strapi admin has been a consistent focus across this release window. The Content Manager's edit view, list view, content history forms, subnav, and main navigation have all received targeted improvements for smaller screens. Together, they add up to an admin who no longer fights you when you're not at a desk.

Content Manager

Your list view remembers you
It's one of those things you only notice because you had to redo it so often. Every time you returned to the Content Manager, your column preferences, filters, and sorting were gone, reset to defaults, waiting to be reconfigured again. As of v5.36, those settings persist across sessions. The list view you left is the list view you come back to.

You can now filter by publication status
If you work with Draft & Publish enabled, the Content Manager list view now has a status filter built in. Before v5.39, finding all your unpublished drafts or verifying what was live meant scrolling through everything. Now you can filter by Draft, Published (all), Published and modified, or Published and unmodified.

Bulk publishing no longer interrupts itself
A frustrating bug in bulk publishing caused the confirmation modal to close mid-operation during API refetches, forcing you to start over, uncertain of what had actually been published. That's fixed in v5.35. The operation now runs to completion without interrupting itself.

Cloning an entry now includes its relations
When you cloned a content entry, its relational fields weren't being correctly re-populated in the clone. The result was entries that looked complete but were silently missing their connections. v5.36 fixes the root cause, so relations are fetched and repopulated as expected.
<div
style="
display:grid;
grid-template-columns:repeat(2, minmax(0, 1fr));
gap:16px;
"

You can now control how relation fields open
v5.38 introduces a relationOpenMode setting that lets developers configure how relation fields behave when clicked — opening in a modal, a full page, or a new tab. Before this, the behavior was fixed and couldn't be adapted to the content structure or team workflow. It's a small configuration option with a meaningful impact on how editors navigate complex content.

Media Library

Your images now stay in frame
Before v5.35, when an image was cropped or resized to fit a layout, Strapi had no way of knowing which part of the image mattered. A portrait could lose its subject. A product photo could lose the product. Now we've added a focal-point picker to the Media Library: you click the point that matters, and Strapi uses it as the anchor when your image is adapted to different sizes or formats.

Your existing media library can now be AI-enriched, retroactively (Growth Plan License required)
AI-powered metadata generation (automatic alt text and captions) was already available for new uploads. But for teams who had been building up a media library for months or years, the benefit stopped at the door. With v5.34, you can now trigger AI metadata generation on files that are already in your library. If you've been accumulating assets without structured metadata, you no longer have to choose between leaving them untagged or manually going back through hundreds of files.

File type restrictions now actually restrict
This one is worth naming plainly: before v5.33.3, upload file type restrictions configured in Strapi could be bypassed through the Content API. That gap is closed. The restriction you set is now enforced consistently, regardless of how the upload request is made.

Media can now be imported directly from a URL
The upload system now supports importing assets directly from a URL, no need to download a file locally before uploading it to Strapi. A practical time-saver for content teams working with external media sources.

Developer experience

The email provider has been upgraded
The email-nodemailer provider has been upgraded to Nodemailer v8, bringing with it support for advanced email features and new Admin UI capabilities. If you're using Strapi's email provider for transactional emails, this upgrade expands what's configurable and addressable directly from the admin, without dropping into code.

S3-compatible storage is now a first-class option
The AWS S3 upload provider has been extended to support the full configuration surface of S3-compatible storage services. In practice, this means you can now connect Strapi to Cloudflare R2, MinIO, Backblaze B2, DigitalOcean Spaces, and other S3-compatible providers using the official provider, without needing custom workarounds or third-party plugins. If you've been running one of these services alongside Strapi, the path just got significantly cleaner.

Project scaffolding now works in fully automated environments
create-strapi-app now supports a --non-interactive flag, allowing you to scaffold a new Strapi project without any prompts. For CI pipelines, infrastructure-as-code setups, and any automated environment where human input isn't an option, this removes the last manual step from project initialization.

Changing a password now ends active sessions
Before v5.33.3, updating a user's password in Strapi didn't automatically invalidate their existing sessions. That meant a compromised account couldn't be fully locked out by a password change alone, active tokens remained valid. Session revocation on password change is now implemented.

API parameter handling is more secure by default
v5.37 introduces strictParam, addQueryParams, and addInputParams controls, tightening how query and input parameters are handled at the API layer. This is a defensive improvement, less visible than a feature, but meaningful for teams with security requirements or public-facing APIs.

What's next

This post covers the most significant changes across the latest releases, but dozens of additional bug fixes and smaller improvements shipped alongside everything described here. The release notes have the complete picture, and they're worth a look.

A meaningful share of this work came from the community. Pull requests, bug reports, feature requests that turned into merged code. Strapi is an open-source project, and that means its quality is a collective responsibility. The more people who report issues, propose fixes, and submit pull requests, the better Strapi gets for everyone. We're counting on that to continue. There's always more to fix, more to improve, more to build. And we'll do it, together.

To see the full list of changes, visit the release notes:

Demystifying Strapi's Populate & Filtering

Strapi — Fri, 13 Mar 2026 10:15:25 +0000

Introduction

Hello everyone! This discussion is based on Richard's Strapi Conf talk on demystifying Strapi's populated filtering which was originally based in Strapi 4. Now that we are on Strapi 5, I've updated this blog post to cover what has changed and highlight the key differences you need to know.

This blog post serves as a quick refresher on effectively consuming data in Strapi using field selection, population, and filtering.

What's New in Strapi 5?

Strapi 5 introduces several significant changes to the REST API, most notably a flattened response format and the introduction of documentId as the primary identifier. We'll highlight these changes throughout the post with callout boxes like this one.

Why is This Discussion Necessary?

Over the years, Strapi has evolved significantly, and the most noticeable change has been in how we interact with our content. Content consumption is a crucial part of the data interaction experience. This post aims to help you become comfortable with the tools you need to interact with your data efficiently.

You can learn about these topics in our documentation. Check out the following sections, populate and filtering, as well as, this video where we discuss the topic in more details.

Setting Up the Example Project

To follow along with the examples in this post, we'll use a starter project that includes both a Strapi 5 backend and a Next.js frontend. You can find the project here.

Clone the Repository

Start by cloning the project:

git clone https://github.com/PaulBratslavsky/strapi-5-next-js-starter-project.git

Install Dependencies

Navigate into the project directory and run the setup script to install all dependencies:

cd strapi-5-next-js-starter-project
npm run setup

Seed the Database

Next, populate the database with example data by running the seed command:

npm run seed

You should see output similar to the following, confirming that the data has been imported:

┌─────────────────────────────────────────┬───────┬───────────────┐
│ Type                                    │ Count │ Size          │
├─────────────────────────────────────────┼───────┼───────────────┤
│ entities                                │    50 │      51.9 KB  │
├─────────────────────────────────────────┼───────┼───────────────┤
│ -- api::category.category               │     4 │ (       1 KB) │
├─────────────────────────────────────────┼───────┼───────────────┤
│ -- api::global.global                   │     2 │ (     2.1 KB) │
├─────────────────────────────────────────┼───────┼───────────────┤
│ -- api::landing-page.landing-page       │     2 │ (       8 KB) │
├─────────────────────────────────────────┼───────┼───────────────┤
│ -- api::page.page                       │     2 │ (       3 KB) │
├─────────────────────────────────────────┼───────┼───────────────┤
│ -- api::post.post                       │    10 │ (    20.6 KB) │
├─────────────────────────────────────────┼───────┼───────────────┤
│ -- plugin::upload.file                  │     6 │ (     9.6 KB) │
├─────────────────────────────────────────┼───────┼───────────────┤
│ assets                                  │    30 │       4.9 MB  │
├─────────────────────────────────────────┼───────┼───────────────┤
│ Total                                   │   230 │       5.1 MB  │
└─────────────────────────────────────────┴───────┴───────────────┘
Import process has been completed successfully!

Start the Application

Now you're ready to start both the frontend and backend:

npm run dev

Strapi Admin Panel: http://localhost:1337/admin — You'll be prompted to create your first admin user.
Next.js Frontend: http://localhost:3000

Once you've created your admin account, you'll see the Strapi admin panel:

And the frontend will be running at:

Getting Started with Population and Field Selection

Now let's explore how population and field selection work. For this, we will focus on populating our post with the following documentId cqaabo4pxlrhrjjhxbima0hq.

If you make a GET request to the post endpoint at http://localhost:1337/api/posts/cqaabo4pxlrhrjjhxbima0hq, you'll see this response:

{
  "data": {
    "id": 23,
    "documentId": "cqaabo4pxlrhrjjhxbima0hq",
    "title": "How to Choose the Right CMS for Your Business",
    "description": "A comprehensive guide to help businesses select the best CMS to meet their needs, whether they require a simple website builder or a custom headless CMS solution.",
    "slug": "how-to-choose-the-right-cms-for-your-business",
    "content": "Choosing the right CMS (Content Management System) for your business is crucial...",
    "createdAt": "2024-07-20T15:42:31.381Z",
    "updatedAt": "2026-01-27T05:09:55.493Z",
    "publishedAt": "2026-01-27T05:09:55.502Z"
  },
  "meta": {}
}

Notice that the response only includes the top-level fields: title, description, slug, and content.

What are top-level fields? By default, Strapi's REST API only returns scalar field types — the simple values stored directly on the content type. According to the Strapi documentation, these include:

String types: string, text, richtext, enumeration, email, password, uid
Date types: date, time, datetime, timestamp
Number types: integer, biginteger, float, decimal
Generic types: boolean, array, JSON

Relations, media fields, components, and dynamic zones are not included by default. These require explicit population because they involve additional database queries to fetch data from related tables.

This explains why our API response only returned the basic fields. If you look at the Post collection in the Strapi Admin UI, you'll see additional items — relations, media, components, and dynamic zones — that weren't included in the response.

For instance, above we can see that we have an image, but this was not returned in our API request.

This is by design. Strapi does not automatically populate relations, components, or dynamic zones. You must explicitly request them.

This approach helps optimize performance by reducing unnecessary database queries and keeping API responses lean.

Permissions Matter

To access any content type via the API, you need to enable the appropriate permissions. In our case, the find and findOne permissions are already enabled for the post collection:

Without these permissions, you'd receive a 403 Forbidden error:

{
  "data": null,
  "error": {
    "status": 403,
    "name": "ForbiddenError",
    "message": "Forbidden",
    "details": {}
  }
}

Key Takeaways

When working with populate and filtering in Strapi, keep these points in mind:

Relations are not populated by default — you must explicitly request them
Permissions must be enabled for any content type you want to populate
Deep population impacts performance — the more levels deep you populate, the longer queries take

This design gives you granular control over your API responses and helps prevent over-fetching unnecessary data.

Exploring Population and Field Selection with Examples

Let's go through some examples using our local project that we just setup.

To help with this, we will be using Strapi's Query Builder tool, which you can find here.

Here is a helpful Chrome extension to make your JSON more beautiful when viewing in the browser. JSON Viewer

In my Strapi application, I have created several collection types and relations, which I will explain as we proceed. We have top-level relations, top-level fields, dynamic zones, and components within those dynamic zones.

top-level-fields.png

Let's take a look at some examples of population and field selection.

Populate Everything First Level Deep with the Wildcard Operator

Before looking at the wildcard * operator, let's look at what we get as a response when querying our posts without passing and populating or filtering options.

You can run this GET query in Postman, but we will just look at it in the browser for brevity.

Post Query: http://localhost:1337/api/posts/cqaabo4pxlrhrjjhxbima0hq

As we saw earlier, this returns only the top-level fields — no relations, components, or dynamic zones:

{
  "data": {
    "id": 23,
    "documentId": "cqaabo4pxlrhrjjhxbima0hq",
    "title": "How to Choose the Right CMS for Your Business",
    "description": "A comprehensive guide to help businesses select the best CMS...",
    "slug": "how-to-choose-the-right-cms-for-your-business",
    "content": "Choosing the right CMS (Content Management System)...",
    "createdAt": "2024-07-20T15:42:31.381Z",
    "updatedAt": "2026-01-27T05:09:55.493Z",
    "publishedAt": "2026-01-27T05:09:55.502Z"
  },
  "meta": {}
}

Strapi 5 Change: Flattened Response Format

In Strapi 4, the response wrapped all fields inside a data.attributes object:

{
  "data": {
    "id": 1,
    "attributes": {
      "title": "My Article",
      "slug": "my-article"
    }
  }
}

In Strapi 5, the response is flattened — fields like title and slug are directly on the data object. Strapi 5 also introduces documentId as the primary identifier for API calls.

This means you no longer need to access data.attributes.title — you can simply use data.title. This simplifies frontend code significantly.

You can learn more about the changes between Strapi 4 to Strapi 5 here

If you want to bring back as much information as possible, use the wildcard * operator.

{
  populate: "*",
}

What is LHS Notation?

Throughout this post, you'll see queries written in two formats: object notation (the JavaScript object above) and LHS Bracket notation (the URL query string below).

LHS (Left-Hand Side) Bracket notation is the format used in URL query strings to represent nested objects. For example, populate[author][fields][0]=name represents { populate: { author: { fields: ["name"] } } }.

Strapi uses the qs library to parse these query strings. You can use Strapi's Interactive Query Builder to convert between object notation and LHS notation — it's a helpful tool for constructing complex queries.

Alternatively, you can use the official Strapi Client on your frontend, which handles query building and a way to interact with your Strapi API.

LHS Notation: http://localhost:1337/api/posts/cqaabo4pxlrhrjjhxbima0hq?populate=*

Remember that some details may not be visible, such as image in our SEO component due to limited population depth.

{
  "data": {
    "id": 23,
    "documentId": "cqaabo4pxlrhrjjhxbima0hq",
    "title": "How to Choose the Right CMS for Your Business",
    "description": "A comprehensive guide to help businesses select the best CMS to meet their needs, whether they require a simple website builder or a custom headless CMS solution.",
    "slug": "how-to-choose-the-right-cms-for-your-business",
    "content": "Choosing the right CMS (Content Management System) for your business is crucial for your online success. With so many options available, it can be overwhelming to make the right choice. This guide will help you navigate the various types of CMS and select the one that best fits your needs.\n\n### Types of CMS\n1. **Traditional CMS**: Ideal for small to medium-sized websites. Examples include WordPress and Joomla.\n2. **Website Builders**: Perfect for those who need a quick setup with minimal technical knowledge. Examples include Wix and Squarespace.\n3. **Headless CMS**: Suitable for businesses requiring a custom solution with more flexibility and scalability. Examples include Strapi and Contentful.\n\n### Factors to Consider\n- **Ease of Use**: Consider the learning curve associated with each CMS.\n- **Flexibility**: Determine if the CMS can handle your business's growth and evolving needs.\n- **Cost**: Evaluate your budget and the total cost of ownership, including maintenance and scalability.\n\n### Conclusion\nSelecting the right CMS requires careful consideration of your business's specific needs and goals. By understanding the different types of CMS and their features, you can make an informed decision that will support your business's online presence.\n",
    "createdAt": "2024-07-20T15:42:31.381Z",
    "updatedAt": "2026-01-27T05:09:55.493Z",
    "publishedAt": "2026-01-27T05:09:55.502Z",
    "image": {
      "id": 10,
      "documentId": "nld6jhxi2jlu95hkb8wv28zv",
      "name": "pexels-cottonbro-4855327.jpg",
      "alternativeText": null,
      "caption": null,
      "width": 3500,
      "height": 2333,
      "formats": {
        "thumbnail": {
          "name": "thumbnail_pexels-cottonbro-4855327.jpg",
          "hash": "thumbnail_pexels_cottonbro_4855327_5fb6b05354",
          "ext": ".jpg",
          "mime": "image/jpeg",
          "path": null,
          "width": 234,
          "height": 156,
          "size": 8.81,
          "sizeInBytes": 8808,
          "url": "/uploads/thumbnail_pexels_cottonbro_4855327_5fb6b05354.jpg"
        },
        "small": {
          "name": "small_pexels-cottonbro-4855327.jpg",
          "hash": "small_pexels_cottonbro_4855327_5fb6b05354",
          "ext": ".jpg",
          "mime": "image/jpeg",
          "path": null,
          "width": 500,
          "height": 333,
          "size": 28.39,
          "sizeInBytes": 28392,
          "url": "/uploads/small_pexels_cottonbro_4855327_5fb6b05354.jpg"
        },
        "medium": {
          "name": "medium_pexels-cottonbro-4855327.jpg",
          "hash": "medium_pexels_cottonbro_4855327_5fb6b05354",
          "ext": ".jpg",
          "mime": "image/jpeg",
          "path": null,
          "width": 750,
          "height": 500,
          "size": 54.32,
          "sizeInBytes": 54324,
          "url": "/uploads/medium_pexels_cottonbro_4855327_5fb6b05354.jpg"
        },
        "large": {
          "name": "large_pexels-cottonbro-4855327.jpg",
          "hash": "large_pexels_cottonbro_4855327_5fb6b05354",
          "ext": ".jpg",
          "mime": "image/jpeg",
          "path": null,
          "width": 1000,
          "height": 666,
          "size": 84.83,
          "sizeInBytes": 84826,
          "url": "/uploads/large_pexels_cottonbro_4855327_5fb6b05354.jpg"
        }
      },
      "hash": "pexels_cottonbro_4855327_5fb6b05354",
      "ext": ".jpg",
      "mime": "image/jpeg",
      "size": 593.5,
      "url": "/uploads/pexels_cottonbro_4855327_5fb6b05354.jpg",
      "previewUrl": null,
      "provider": "local",
      "provider_metadata": null,
      "createdAt": "2024-08-20T15:29:58.080Z",
      "updatedAt": "2025-05-01T04:45:33.508Z",
      "publishedAt": "2024-08-20T15:29:58.086Z"
    },
    "category": {
      "id": 8,
      "documentId": "kbumsa4dtqk7v2jqlfehjrfx",
      "text": "strapi",
      "description": "All posts about Strapi.",
      "createdAt": "2024-07-20T19:35:02.052Z",
      "updatedAt": "2024-07-20T19:35:02.052Z",
      "publishedAt": "2024-07-20T19:35:02.055Z"
    },
    "blocks": [
      {
        "__component": "blocks.video",
        "id": 13,
        "title": "Strapi 5 Crashcourse",
        "description": "Everything you need to get started with Strapi 5",
        "videoUrl": "https://www.youtube.com/watch?v=t1iUuap7vhw",
        "video": {
          "videoId": "t1iUuap7vhw",
          "start": "",
          "end": ""
        }
      },
      {
        "__component": "blocks.text",
        "id": 13,
        "content": "**The standard Lorem Ipsum passage, used since the 1500s**\"\n\nLorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.\"\n\n**Section 1.10.32 of \"de Finibus Bonorum et Malorum\", written by Cicero in 45 BC\"**\n\nSed 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. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt. Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem. Ut enim ad minima veniam, quis nostrum exercitationem ullam corporis suscipit laboriosam, nisi ut aliquid ex ea commodi consequatur? Quis autem vel eum iure reprehenderit qui in ea voluptate velit esse quam nihil molestiae consequatur, vel illum qui dolorem eum fugiat quo voluptas nulla pariatur?\"\n\n"
      }
    ],
    "seo": {
      "id": 6,
      "metaTitle": "How to Choose the Right CMS for Your Business",
      "metaDescription": "Choosing the right CMS (Content Management System) for your business.",
      "keywords": null,
      "metaRobots": null,
      "metaViewport": null,
      "canonicalURL": null,
      "structuredData": null
    }
  },
  "meta": {}
}

When using the wildcard * operator, you will only populate relations, dynamic zones, and components to a depth of one.

You can learn more in our documentation on the wildcard operator here.

Why You Shouldn't Always Use populate=*

While the wildcard operator is convenient for quick testing, it's not recommended for production use. Here's why:

Performance impact — It fetches all relations, media, components, and dynamic zones, even if you don't need them. This increases database query time and response payload size.
Only one level deep — It doesn't populate nested relations, so you may still need explicit population for deeper data.
Security concerns — You might accidentally expose data that shouldn't be public.

Instead, explicitly populate only the fields you need. This gives you better performance, smaller payloads, and more predictable API responses.

populate: true vs populate: "*" on Dynamic Zones

When populating specific fields, you might use populate: true or populate: "*" — for most relations and components these behave similarly. However, there is an important difference when working with dynamic zones:

populate: { blocks: true } — Populates the dynamic zone one level deep (returns component fields but not their nested relations).
populate: { blocks: { populate: "*" } } — Populates the dynamic zone and its nested relations one level deeper. This works.
populate: { blocks: { populate: true } } — This causes a 500 error on dynamic zones. Strapi cannot resolve which components to populate generically with true.

For dynamic zones, always use "*" or the explicit on syntax (shown later) when you need to go deeper than one level. The populate: true shorthand only works on regular relations and components.

Populate Specific Relations

To populate specific relations, we must specify which fields we want to populate in Strapi. Let's take a look at the following example.

Instead of using the wildcard, we will build out the query manually. Here is what our current query looks like without any options being passed in Strapi's interactive query builder that you can find here.

Let's add this populate query. We can use this array populate notation to specify which fields we want to populate. The following will get the same data as when we used the wildcard and populated one level deep for all the specified items.

{
  populate: [
    "image",
    "category",
    "seo",
    "blocks"
  ],
}

or using the object notation

{
  populate: {
    image: true,
    category: true,
    seo: true,
    blocks: true,
  },
}

{
  populate: {
    image: {
      populate: true
    },
    category: {
      populate: true
    },
    seo: {
      populate: true
    },
    blocks: true
  },
}

In most complex queries, object notation is preferred because of this flexibility.

LHS Notation: http://localhost:1337/api/posts/cqaabo4pxlrhrjjhxbima0hq?populate[image]=true&populate[category]=true&populate[seo]=true&populate[blocks]=true

Before looking at how we can populate nested relations, let's look at how we can populate specific fields.

Populate Nested Relations

Let's look at how we can populate our nested relationships. We will use the above query as a starting point.

We will look at how to populate the metaImage media field nested inside our seo component.

When we used populate=* earlier, the seo component was populated one level deep — but the metaImage inside it was not returned because it requires an additional level of population.

{
  populate: [
    "image",
    "category",
    "blocks",
    "seo.metaImage"
  ],
}

or using the object notation

{
  populate: {
    image: true,
    category: true,
    blocks: true,
    seo: {
      populate: ["metaImage"]
    }
  },
}

LHS Notation: http://localhost:1337/api/posts/cqaabo4pxlrhrjjhxbima0hq?populate[image]=true&populate[category]=true&populate[blocks]=true&populate[seo][populate][metaImage]=true

In the response below, we can see the seo component now includes the nested metaImage relation:

{
  "data": {
    "id": 23,
    "documentId": "cqaabo4pxlrhrjjhxbima0hq",
    "title": "How to Choose the Right CMS for Your Business",
    "seo": {
      "id": 6,
      "metaTitle": "How to Choose the Right CMS for Your Business",
      "metaDescription": "Choosing the right CMS (Content Management System) for your business.",
      "keywords": null,
      "metaImage": {
        "id": 10,
        "documentId": "nld6jhxi2jlu95hkb8wv28zv",
        "name": "pexels-cottonbro-4855327.jpg",
        "alternativeText": null,
        "url": "/uploads/pexels_cottonbro_4855327_5fb6b05354.jpg"
      }
    }
  }
}

Notice how the metaImage is now fully populated with all its fields. Without the nested populate, the seo component would only show its scalar fields and the metaImage would be missing.

Strapi 5 Change: Flattened Relations

In Strapi 4, related data was nested inside data.attributes:

{
  "seo": {
    "id": 6,
    "metaTitle": "My Title",
    "metaImage": {
      "data": {
        "id": 10,
        "attributes": {
          "url": "/uploads/image.jpg"
        }
      }
    }
  }
}

In Strapi 5, relations are flattened and use documentId:

{
  "seo": {
    "id": 6,
    "metaTitle": "My Title",
    "metaImage": {
      "documentId": "nld6jhxi2jlu95hkb8wv28zv",
      "url": "/uploads/image.jpg"
    }
  }
}

There are a lot of fields. What if we wanted to populate selected fields only. That is exactly what I will show you in the next section.

Populate and Field Select

We will now see how you can tell Strapi only to return specific fields. We will also see where the object notation is useful since array notation does not allow you to do this.

Array notation example:

{
  populate: [
    "image",
    "category",
    "blocks",
    "seo.metaImage"
  ],
}

Object notation example:

{
  populate: {
    image: true,
    category: true,
    blocks: true,
    seo: {
      populate: ["metaImage"]
    }
  },
}

Let's refactor our object notation example to see how to populate only specific fields. We will focus on the image media field.

When we populated image earlier, it returned all of its fields — name, alternativeText, caption, width, height, formats, hash, ext, mime, size, url, and more. That's a lot of data we may not need.

Let's now only return the name, alternativeText, and url.

To accomplish this, let's make the following changes to our query.

{
  populate: {
    image: {
      fields: [
        "name",
        "alternativeText",
        "url"
      ]
    },
    category: true,
    blocks: true,
    seo: {
      populate: {
        metaImage: {
          fields: ["url", "alternativeText"]
        }
      }
    }
  },
}

LHS Notation: http://localhost:1337/api/posts/cqaabo4pxlrhrjjhxbima0hq?populate[image][fields][0]=name&populate[image][fields][1]=alternativeText&populate[image][fields][2]=url&populate[category]=true&populate[seo][populate][metaImage][fields][0]=url&populate[seo][populate][metaImage][fields][1]=alternativeText&populate[blocks]=true

Notice in the response below we returned all of our data from before, but only the specified fields for our image and seo.metaImage:

{
  "data": {
    "id": 23,
    "documentId": "cqaabo4pxlrhrjjhxbima0hq",
    "title": "How to Choose the Right CMS for Your Business",
    "image": {
      "id": 10,
      "documentId": "nld6jhxi2jlu95hkb8wv28zv",
      "name": "pexels-cottonbro-4855327.jpg",
      "alternativeText": null,
      "url": "/uploads/pexels_cottonbro_4855327_5fb6b05354.jpg"
    },
    "seo": {
      "id": 6,
      "metaTitle": "How to Choose the Right CMS for Your Business",
      "metaDescription": "Choosing the right CMS (Content Management System) for your business.",
      "metaImage": {
        "id": 10,
        "documentId": "nld6jhxi2jlu95hkb8wv28zv",
        "url": "/uploads/pexels_cottonbro_4855327_5fb6b05354.jpg",
        "alternativeText": null
      }
    }
  }
}

Instead of getting all the image format data (thumbnail, small, medium, large), we only get exactly what we need — a much leaner response.

In the next section, we will look at complex population and field selection.

Complex Population and Field Selection

In this example, instead of getting our posts, we will look to populate our landing page. The landing page is a single type (accessed at /api/landing-page) that uses a blocks dynamic zone with several different components:

layout.hero — heading, text, topLink (link component), buttonLink (repeatable link component), image (media)
layout.section-heading — subHeading, heading, text (all scalar fields)
layout.card-grid — cardItems (repeatable card component with icon, heading, text)
layout.content-with-image — heading, subHeading, text, image (media), reverse (boolean)
layout.price-grid — priceCard (repeatable price-card component with heading, description, price, feature[], link)

We will build this query in steps.

Step 1: Basic Wildcard Populate

First, let's see what the landing page looks like with a simple wildcard populate:

{
  populate: "*",
}

LHS Notation: http://localhost:1337/api/landing-page?populate=*

This returns all blocks populated one level deep. We can see the different components in the blocks dynamic zone, but nested relations like the image inside the hero or cardItems inside card-grid are not included.

Step 2: Populate All Nested Data with `on`

To get all the data from every component in the dynamic zone, we need to use the on option to target each component and populate its nested relations.

You can see our docs for additional information here.

{
  populate: {
    blocks: {
      on: {
        "layout.hero": {
          populate: {
            topLink: true,
            buttonLink: true,
            image: {
              fields: ["url", "alternativeText"]
            }
          }
        },
        "layout.card-grid": {
          populate: {
            cardItems: true
          }
        },
        "layout.section-heading": {
          populate: "*"
        },
        "layout.content-with-image": {
          populate: {
            image: {
              fields: ["url", "alternativeText"]
            }
          }
        },
        "layout.price-grid": {
          populate: {
            priceCard: {
              populate: {
                feature: true,
                link: true
              }
            }
          }
        }
      }
    }
  }
}

LHS Notation: http://localhost:1337/api/landing-page?populate[blocks][on][layout.hero][populate][topLink]=true&populate[blocks][on][layout.hero][populate][buttonLink]=true&populate[blocks][on][layout.hero][populate][image][fields][0]=url&populate[blocks][on][layout.hero][populate][image][fields][1]=alternativeText&populate[blocks][on][layout.card-grid][populate][cardItems]=true&populate[blocks][on][layout.section-heading][populate]=*&populate[blocks][on][layout.content-with-image][populate][image][fields][0]=url&populate[blocks][on][layout.content-with-image][populate][image][fields][1]=alternativeText&populate[blocks][on][layout.price-grid][populate][priceCard][populate][feature]=true&populate[blocks][on][layout.price-grid][populate][priceCard][populate][link]=true

This returns all the landing page data with every component fully populated. Here's a condensed view of the response showing each component type:

{
  "data": {
    "id": 4,
    "documentId": "l6etcff49lp5c1v21lpv3vwd",
    "title": "Landing Page",
    "description": "This is the main landing page.",
    "blocks": [
      {
        "__component": "layout.hero",
        "id": 6,
        "heading": "Next.js 15 and Strapi 5 Starter Project",
        "text": "Give Strapi 5 and Next.js a spin with this starter project...",
        "topLink": {
          "id": 49,
          "href": "https://github.com/PaulBratslavsky/strapi-5-next-js-starter-project",
          "text": "GitHub Project Repo",
          "isExternal": true,
          "isPrimary": false
        },
        "buttonLink": [
          { "id": 50, "href": "https://strapi.io/five", "text": "Strapi 5", "isExternal": true, "isPrimary": false },
          { "id": 51, "href": "https://docs-next.strapi.io/dev-docs/whats-new", "text": "Strapi 5 Docs", "isExternal": true, "isPrimary": true }
        ],
        "image": { "id": 9, "documentId": "sg6vq9j5il16fl8y38dob4c8", "url": "/uploads/strapi_dashboard_d4cf37208d.png", "alternativeText": null }
      },
      {
        "__component": "layout.section-heading",
        "id": 7,
        "subHeading": "Strapi 5 Features",
        "heading": "Build fast and stay flexible",
        "text": "Strapi 5 brings many new features and improvements.\n"
      },
      {
        "__component": "layout.card-grid",
        "id": 6,
        "cardItems": [
          { "id": 16, "icon": "Frame", "heading": "DRAFT & PUBLISH", "text": "Reduce the risk of publishing errors..." },
          { "id": 17, "icon": "Download", "heading": "CONTENT HISTORY", "text": "Overcome the risks of data loss..." },
          { "id": 18, "icon": "Globe", "heading": "100% TYPESCRIPT", "text": "Easier bug detection..." }
        ]
      },
      {
        "__component": "layout.content-with-image",
        "id": 7,
        "heading": "Designed to build fast",
        "subHeading": "BUILD FAST",
        "text": "Strapi is designed to be highly customizable out of the box...",
        "reverse": true,
        "image": { "id": 9, "documentId": "sg6vq9j5il16fl8y38dob4c8", "url": "/uploads/strapi_dashboard_d4cf37208d.png", "alternativeText": null }
      },
      {
        "__component": "layout.price-grid",
        "id": 4,
        "priceCard": [
          {
            "id": 10,
            "selected": false,
            "heading": "Developer",
            "description": "Perfect for getting started",
            "price": "29",
            "feature": [
              { "id": 67, "description": "1 seat" },
              { "id": 68, "description": "1000 CMS Entries" }
            ],
            "link": { "id": 52, "href": "https://strapi.io/cloud", "text": "Get started", "isExternal": true, "isPrimary": true }
          }
        ]
      }
    ]
  },
  "meta": {}
}

Notice the different levels of nesting: the price-grid component has priceCard items, each containing feature components and a link component — that's three levels deep from the landing page root. Without the explicit on population, none of this nested data would be returned.

Step 3: Selective Population with `on`

But what if you only need specific components from the dynamic zone? The on option also lets you exclude components you don't need. For example, if you only want the hero and card-grid:

{
  populate: {
    blocks: {
      on: {
        "layout.hero": {
          fields: ["heading", "text"],
          populate: {
            image: {
              fields: ["url", "alternativeText"]
            },
            buttonLink: true
          }
        },
        "layout.card-grid": {
          populate: {
            cardItems: {
              fields: ["heading", "text"]
            }
          }
        }
      }
    }
  }
}

LHS Notation: http://localhost:1337/api/landing-page?populate[blocks][on][layout.hero][fields][0]=heading&populate[blocks][on][layout.hero][fields][1]=text&populate[blocks][on][layout.hero][populate][image][fields][0]=url&populate[blocks][on][layout.hero][populate][image][fields][1]=alternativeText&populate[blocks][on][layout.hero][populate][buttonLink]=true&populate[blocks][on][layout.card-grid][populate][cardItems][fields][0]=heading&populate[blocks][on][layout.card-grid][populate][cardItems][fields][1]=text

Now the response only includes the hero and card-grid components — all other components (section-heading, content-with-image, price-grid) are excluded. Combined with field selection, this gives you a much leaner response:

{
  "data": {
    "id": 4,
    "documentId": "l6etcff49lp5c1v21lpv3vwd",
    "title": "Landing Page",
    "description": "This is the main landing page.",
    "blocks": [
      {
        "__component": "layout.hero",
        "id": 6,
        "heading": "Next.js 15 and Strapi 5 Starter Project",
        "text": "Give Strapi 5 and Next.js a spin with this starter project...",
        "image": { "id": 9, "documentId": "sg6vq9j5il16fl8y38dob4c8", "url": "/uploads/strapi_dashboard_d4cf37208d.png", "alternativeText": null },
        "buttonLink": [
          { "id": 50, "href": "https://strapi.io/five", "text": "Strapi 5", "isExternal": true, "isPrimary": false },
          { "id": 51, "href": "https://docs-next.strapi.io/dev-docs/whats-new", "text": "Strapi 5 Docs", "isExternal": true, "isPrimary": true }
        ]
      },
      {
        "__component": "layout.card-grid",
        "id": 6,
        "cardItems": [
          { "id": 16, "heading": "DRAFT & PUBLISH", "text": "Reduce the risk of publishing errors..." },
          { "id": 17, "heading": "CONTENT HISTORY", "text": "Overcome the risks of data loss..." },
          { "id": 18, "heading": "100% TYPESCRIPT", "text": "Easier bug detection..." }
        ]
      }
    ]
  },
  "meta": {}
}

The on option gives you precise control over which dynamic zone components are returned and what data they include. This is incredibly useful for building frontend pages where you only need specific sections.

Now that we know how to populate individual components from our dynamic zones, we will look at how to apply filtering to our query in the next section.

Filtering Data

Filtering allows you to retrieve specific information from your application. However, note that deep filtering is not available in dynamic zones, and complex filters may cause performance issues. You can learn more about filtering here.

Strapi 5 Change: New Filter Operators

Strapi 5 introduces several new case-insensitive operators that weren't available in Strapi 4:

New Operator Description

$eqi Equal (case-insensitive)

$nei Not equal (case-insensitive)

$containsi Contains (case-insensitive)

$notContainsi Does not contain (case-insensitive)

$startsWithi Starts with (case-insensitive)

$endsWithi Ends with (case-insensitive)

$between Between two values (range)

These new operators make filtering much more flexible, especially for user-facing search functionality.

New Operator	Description
`$eqi`	Equal (case-insensitive)
`$nei`	Not equal (case-insensitive)
`$containsi`	Contains (case-insensitive)
`$notContainsi`	Does not contain (case-insensitive)
`$startsWithi`	Starts with (case-insensitive)
`$endsWithi`	Ends with (case-insensitive)
`$between`	Between two values (range)

Here are some filtering examples:

Top-level Filtering Example

Let's filter our posts by slug to find a specific post.

{
  filters: {
    slug: "how-to-choose-the-right-cms-for-your-business"
  }
}

LHS Notation: http://localhost:1337/api/posts?filters[slug]=how-to-choose-the-right-cms-for-your-business

By default, the above notation uses the $eq operator; we can also write this with the following.

{
  filters: {
    slug: {
      '$eq': "how-to-choose-the-right-cms-for-your-business"
    }
  }
}

LHS Notation: http://localhost:1337/api/posts?filters[slug][$eq]=how-to-choose-the-right-cms-for-your-business

Here are some examples of common operators.

Operator	Description
`$eq`	Equal
`$eqi`	Equal (case-insensitive) - New in Strapi 5
`$ne`	Not equal
`$nei`	Not equal (case-insensitive) - New in Strapi 5
`$lt`	Less than
`$lte`	Less than or equal to
`$gt`	Greater than
`$gte`	Greater than or equal to
`$in`	Included in an array
`$notIn`	Not included in an array
`$contains`	Contains
`$notContains`	Does not contain
`$containsi`	Contains (case-insensitive) - New in Strapi 5
`$notContainsi`	Does not contain (case-insensitive) - New in Strapi 5
`$startsWith`	Starts with
`$startsWithi`	Starts with (case-insensitive) - New in Strapi 5
`$endsWith`	Ends with
`$endsWithi`	Ends with (case-insensitive) - New in Strapi 5
`$null`	Is null
`$notNull`	Is not null
`$between`	Between two values - New in Strapi 5
`$or`	Joins the filters in an "or" expression
`$and`	Joins the filters in an "and" expression
`$not`	Joins the filters in an "not" expression

You can see the complete list here

Let's look for posts where the seo component has not been filled in (is null). In our dataset, 4 out of 5 posts don't have SEO data.

We can run the following query.

{
  filters: {
    seo: {
      "$null": true
    }
  },
  fields: ["title", "slug"]
}

LHS Notation: http://localhost:1337/api/posts?filters[seo][$null]=true&fields[0]=title&fields[1]=slug

In the response, we can see only the posts without SEO data are returned:

{
  "data": [
    {
      "id": 17,
      "documentId": "tlqsaexq8gshcyzq44z761t4",
      "title": "The Benefits of Using a Headless CMS for Your Website",
      "slug": "benefits-of-using-a-headless-cms-for-your-website"
    },
    {
      "id": 18,
      "documentId": "phsnnk9tf9s9r8lqfn2l1paf",
      "title": "Top 10 Headless CMS Platforms for 2024",
      "slug": "top-10-headless-cms-platforms-for-2024"
    }
  ],
  "meta": {
    "pagination": { "page": 1, "pageSize": 25, "pageCount": 1, "total": 4 }
  }
}

Filtering by Relation Example

You can filter based on relations, like listing all the posts that belong to a specific category. We will filter our posts based on the text field in the category relation.

{
  fields: ["title"],
  populate: {
    category: {
      fields: ["text"]
    }
  },
  filters: {
    category: {
      text: {
        "$eq": "strapi"
      }
    }
  }
}

Strapi 5 Change: No More id in Field Selection

In Strapi 5, you no longer need to explicitly request the id field. The documentId is automatically included in responses. When selecting specific fields, focus on the actual content fields you need.

LHS Notation: http://localhost:1337/api/posts?filters[category][text][$eq]=strapi&populate[category][fields][0]=text&fields[0]=title

In the response below, we can see only posts in the "strapi" category:

{
  "data": [
    {
      "id": 22,
      "documentId": "jzo7u6rxoai6lgrstylj51fz",
      "title": "Testing video custom field",
      "category": {
        "id": 8,
        "documentId": "kbumsa4dtqk7v2jqlfehjrfx",
        "text": "strapi"
      }
    },
    {
      "id": 23,
      "documentId": "cqaabo4pxlrhrjjhxbima0hq",
      "title": "How to Choose the Right CMS for Your Business",
      "category": {
        "id": 8,
        "documentId": "kbumsa4dtqk7v2jqlfehjrfx",
        "text": "strapi"
      }
    }
  ],
  "meta": {
    "pagination": { "page": 1, "pageSize": 25, "pageCount": 1, "total": 2 }
  }
}

Complex Filtering

You can use complex filters, like combining multiple conditions using the $and operator. Let's refactor the above query to see this in action.

In the following query, we would only like to return posts that belong to the strapi category and have CMS in the title (case-insensitive) using our $and operator. Notice how it takes an array as an argument.

{
  fields: ["title"],
  populate: {
    category: {
      fields: ["text"]
    }
  },
  filters: {
    $and: [
      { category: { text: { "$eq": "strapi" } } },
      { title: { "$containsi": "CMS" } }
    ]
  }
}

LHS Notation: http://localhost:1337/api/posts?fields[0]=title&populate[category][fields][0]=text&filters[$and][0][category][text][$eq]=strapi&filters[$and][1][title][$containsi]=CMS

In the following response, you can see that we only return posts that belong to the strapi category and contain CMS in the title:

Strapi 5 Response Format

Notice the flattened structure — no more attributes wrapper:

{
  "data": [
    {
      "id": 23,
      "documentId": "cqaabo4pxlrhrjjhxbima0hq",
      "title": "How to Choose the Right CMS for Your Business",
      "category": {
        "id": 8,
        "documentId": "kbumsa4dtqk7v2jqlfehjrfx",
        "text": "strapi"
      }
    }
  ],
  "meta": {
    "pagination": { "page": 1, "pageSize": 25, "pageCount": 1, "total": 1 }
  }
}

Notice how we used $containsi (the case-insensitive contains operator, new in Strapi 5) to match "CMS" regardless of casing in the title.

Migrating from Strapi 4 to Strapi 5

If you're upgrading from Strapi 4, here's a summary of the key changes you need to be aware of:

Migration Checklist: Strapi 4 to Strapi 5

Response Format Changes

Remove attributes accessor — Change data.attributes.title to data.title

Use documentId instead of id — The primary identifier is now a string-based documentId

Update relation access patterns — Relations are flattened, no more relation.data.attributes

Temporary Compatibility

If you need time to update your frontend code, you can use the compatibility header:
curl -H 'Strapi-Response-Format: v4' 'https://your-api.com/api/articles'
This will return responses in the old Strapi 4 format while you migrate.

New Features to Leverage

Use the new case-insensitive operators ($eqi, $containsi, etc.) for better search

Use $between operator for date and number range queries

The documentId provides better document tracking across locales

Quick Reference: Response Format Comparison

Aspect	Strapi 4	Strapi 5
Field Access	`data.attributes.title`	`data.title`
ID Field	`data.id` (number)	`data.documentId` (string)
Relation Data	`relation.data.attributes.name`	`relation.name`
Array Response	`data[0].attributes.title`	`data[0].title`

Conclusion

To conclude, today, we demystified populate and filtering in Strapi 5.

We strongly recommend that you are the one who writes the populate and filtering logic in your app and not rely on external plugins such as Populate Deep.

Yes, it is an easy solution, but it comes at the cost of performance since it will populate all the data to the depth specified.

From what we covered above, Strapi's populate and filtering gives you granular control of what data you want to return from your API.

This allows you to only get the data that you need. You can also add the populate and filtering inside a route middleware, allowing you to write less code on your front end.

Here is an excellent article written by Kellen Bolger that you should check out here.

Hope you enjoyed this article. If you want to deploy your own Strapi project, check out Strapi Cloud.

As always, thank you for stopping by, and remember to join the Strapi community on Discord to discuss and learn more.

We have daily open office hours Monday - Friday from 12:30 PM CST to 1:30 PM CST.

Thanks for reading!

Additional Resources

Starter Project (GitHub) — The Strapi 5 + Next.js project used in this post
Strapi 5 Populate & Select Documentation
Strapi 5 Filtering Documentation
Strapi 5 Migration Guide: New Response Format
Interactive Query Builder
Transitioning from Strapi 4 to Strapi 5 FAQ

Fixing ISR Revalidation Across Kubernetes Replicas on strapi.io

Strapi — Fri, 13 Mar 2026 10:12:55 +0000

There's this button in our Strapi admin panel. It says "Revalidate". When you click it, it's supposed to clear the cached version of a page so the fresh content shows up. Simple enough.

For a long time, clicking that button did almost nothing. You'd press it, check the page — old content. Press it again — old content. Try a different browser, incognito mode, clear your local cache — old content. It wasn't that the button was broken in any obvious way. It just didn't seem to have any visible effect most of the time.

The fix took us down a rabbit hole of Next.js caching internals, Kubernetes networking, and a Redis Pub/Sub setup that works great but lives in a file where it probably shouldn't. Here's the whole story.

Context

Quick recap of the stack. The strapi.io frontend is a Next.js 13 app using the Pages Router with ISR. We have over 1000 statically generated pages. Content comes from Strapi CMS, and editors use the strapi-plugin-revalidate-button to push updates. The app runs on Kubernetes in 3 replicas behind a load balancer, with CloudFront as the CDN layer.

If you want the background on how we set up ISR originally, there's an earlier article covering that. This one is about what happens when that setup meets horizontal scaling.

The Cache That Nobody Else Knew About

This is actually a well-known limitation of Next.js ISR in self-hosted multi-instance deployments. It comes up frequently in GitHub discussions, but unless you've been burned by it, it's easy to overlook.

The core issue: res.revalidate() only clears the ISR cache on the instance where it runs. Each Next.js pod keeps its own copy of every static page — in memory and on the filesystem. When the revalidation request arrives through the load balancer, one pod out of three gets the call. That pod regenerates the page. The other two keep serving the old version.

Now here's where it gets really frustrating. When the content editor clicks the button multiple times, the load balancer tends to route their requests to the same pod — the one that was already revalidated. So they're re-revalidating a pod that's already fresh, while the other two stay stale. Clicking more doesn't help.

CloudFront made this even more unpredictable. The CDN invalidation request itself worked fine — CloudFront would clear its edge cache as expected. But then it needs to refetch the page from the origin. The origin is our load balancer, which routes to one of three pods. If it hits the one that was revalidated, great — fresh content gets cached at the edge. If it hits one of the other two, stale content goes right back into CloudFront.

In practice it was often worse than pure probability, because the load balancer routing isn't purely random. Depending on connection reuse and pod health checks, you could end up in situations where the same stale pod kept getting picked. Content editors had essentially lost trust in the button.

To visualize what was happening:

Three Approaches That Didn't Work

cacheHandler with Redis — Next.js lets you swap the cache backend via configuration. Sounds perfect for sharing state across pods. Except this feature applies to the App Router's Data Cache, not to the Pages Router's res.revalidate() mechanism. Different caching layers, different APIs. Didn't apply to our setup.
instrumentation.ts — The clean answer. A file that runs once at server startup, ideal for setting up background processes like Redis subscriptions. Two issues: it was experimental in Next.js 13, and it had a known bug where it didn't execute at all in standalone output mode. We use standalone for Docker. Spent a few hours wondering why our code never fired before finding the GitHub issue. Classic.
Shared PVC across pods — Mount the same filesystem volume so all pods share the .next/cache directory. Sounds reasonable until you learn that Next.js keeps an in-memory LRU cache on top of the filesystem. Shared disk doesn't clear the other pods' RAM. Next.

What Actually Worked: Redis Pub/Sub

Redis wasn't running in our cluster at the time, so we spun up a new instance for this. Its Pub/Sub feature lets you broadcast messages to all subscribers on a channel. The pattern we landed on:

Revalidation request arrives at any pod
That pod publishes to a Redis channel instead of revalidating directly
All pods are subscribed to that channel
Each pod receives the message and revalidates its own cache
Once all pods are revalidated, CloudFront cache gets invalidated too

Step 4 deserves a bit more explanation. When a pod receives the Redis message, it needs to call res.revalidate(path) to clear its own ISR cache. The problem is that res.revalidate() is only available inside a Next.js API route handler — it's a method on the response object, not something you can import and call from anywhere in the codebase. There's no nextjs.revalidate(path) function you can use in a background process or a Redis subscriber callback. If instrumentation.ts had worked, we might have had access to the server internals in a way that could bypass this. But with that option gone, we needed another way in.

Our workaround: each pod makes an HTTP request to itself (http://127.0.0.1/api/internal-revalidate) when it receives a Redis message. A pod calling its own API endpoint to trigger revalidation. It's a roundabout way to get access to res.revalidate(), but it works reliably.

If Redis is unavailable, the endpoint falls back to direct revalidation on just the one pod — the old behavior. Not great, but it doesn't crash.

Here's how the flow looks after the fix:

Walking Through the Implementation

Let's look at the key pieces. These snippets are simplified from our production code — just enough to see the logic, nothing you'd copy-paste directly.

The core of the solution is a Pub/Sub client singleton that manages Redis connections. Since Redis requires separate clients for publishing and subscribing, and different parts of the app only need one or the other, we split the connection into two methods. The revalidation endpoint only connects a publisher, while the subscriber setup in _app.js only connects a subscriber. If Redis isn't reachable, the application continues without it:

class PubSubClient {
  static #instance = null
  #publisher = null
  #subscriber = null

  static getInstance() {
    if (!PubSubClient.#instance) {
      PubSubClient.#instance = new PubSubClient()
    }
    return PubSubClient.#instance
  }

  async connectPublisher() {
    if (this.#publisher) return
    this.#publisher = new Redis(redisOptions)
    await this.#publisher.connect()
  }

  async connectSubscriber() {
    if (this.#subscriber) return
    this.#subscriber = new Redis(redisOptions)
    await this.#subscriber.connect()
  }

  get publisher() { return this.#publisher }
  get subscriber() { return this.#subscriber }
}

The main revalidation endpoint — the one the Strapi plugin hits — only needs the publisher side. It publishes a message to Redis instead of calling res.revalidate() directly. If Redis is down, it falls back to the old single-pod behavior:

// /api/revalidate.js
export default async function handler(req, res) {
  // ... auth check, resolve pageToRevalidate from request ...

  const client = PubSubClient.getInstance()
  await client.connectPublisher()

  if (client.publisher) {
    await client.publisher.publish(
      'strapi-web:revalidate',
      JSON.stringify({ path: pageToRevalidate, timestamp: Date.now() })
    )
  } else {
    await res.revalidate(pageToRevalidate)
  }

  return res.json({ revalidated: true, page: pageToRevalidate })
}

Then there's the internal endpoint that each pod calls on itself. It's secured with a shared secret and only accessible from localhost — its only purpose is to give the Redis subscriber a way to trigger res.revalidate():

// /api/internal-revalidate.js — only accessible from localhost
export default async function handler(req, res) {
  // ... validate shared secret ...

  const path = req.query.path
  await res.revalidate(path)
  return res.json({ revalidated: true, path })
}

And finally, the part we're least proud of. With instrumentation.ts broken in standalone mode, the only reliable place to run server-side initialization in Next.js 13 Pages Router was the module scope of _app.js. When this file loads on the server, the top-level code runs once — and that's where we set up the Redis subscription. This side only needs the subscriber connection:

// _app.js — server-side module initialization
if (typeof window === 'undefined') {
  const revalidatePath = async (path) => {
    const port = process.env.PORT || 3000
    await fetch(
      `http://127.0.0.1:${port}/api/internal-revalidate?path=${encodeURIComponent(path)}`,
      { headers: { /* shared secret for auth */ } }
    )
  }

  const { PubSubClient } = await import('src/lib/redis/pubsub-client.js')
  const client = PubSubClient.getInstance()
  await client.connectSubscriber()

  client.subscriber.on('message', (channel, message) => {
    if (channel !== 'strapi-web:revalidate') return
    const { path } = JSON.parse(message)
    revalidatePath(path)
  })

  await client.subscriber.subscribe('strapi-web:revalidate')
}

Module-level side effect. Persistent Redis connection initialized from a React entry point. Not the kind of code you show off at a conference talk, but it's been doing its job without issues.

What We Learned

The problem we ran into is well-documented if you know where to look, but poorly surfaced otherwise. If you search for "Next.js ISR multiple instances" you'll find GitHub issues and discussions going back years. The official docs mention it almost as an aside. It's the kind of thing you discover in production, not during development.

What surprised us most was how much the framework constraints shaped the final architecture. The reason we have a pod calling itself via HTTP, the reason we initialize Redis in _app.js, the reason we need a second API endpoint — all of these exist because of specific limitations in Next.js 13's Pages Router and the broken instrumentation.ts in standalone mode. The solution matches the constraints we had, not any textbook pattern.

One design decision we're glad we made early was the graceful degradation. When Redis is down, revalidation still works on one pod. When the internal endpoint fails, it logs and moves on. The system never fully breaks. This has been a deliberate choice and it gives us peace of mind that a Redis hiccup won't cascade into content editors losing the ability to publish at all.

The good news is that this is getting easier for everyone else. Next.js 15 stabilized instrumentation.ts and fixed the standalone mode bug. The cacheHandler API has matured, and libraries like @neshca/cache-handler handle shared Redis caching across instances properly. If you're starting a new project today, you have much better options. But if you're maintaining a Next.js 13 Pages Router app on Kubernetes and need on-demand revalidation to actually work — we can confirm this approach holds up. It's been running on strapi.io for weeks now and content editors have stopped complaining. Which, if you've ever worked with content teams, you know is the real metric that matters.

References

Let's Build A Strapi Plugin To Integrate Vercel’s AI SDK In Our Next.js 16 Project

Strapi — Fri, 13 Mar 2026 10:07:33 +0000

What We're Building

Want to try something different? Let’s build a custom Strapi plugin that integrates Vercel’s AI SDK, giving our backend native AI capabilities we can securely expose to our Next.js app.

Here is a complimentary video to go along with the post.

Instead of wiring AI logic directly into the frontend, we’ll centralize it inside Strapi—so we can:

🔐 Keep API keys secure
🧠 Standardize prompts and AI workflows
🔌 Expose clean, reusable endpoints to Next.js
🚀 Scale and iterate without touching frontend logic

Think of it as turning Strapi into our AI control center—while Next.js becomes the experience layer.

If we do this right, we won’t just “add AI.” We’ll build an extensible AI layer into our architecture.

We will cover three following examples

Simple Ask - Send a prompt, receive a complete response
Streaming Response - Real-time token-by-token streaming via Server-Sent Events (SSE)
Multi-turn Chat - Full conversational interface with message history

Key Features

Modular Plugin Architecture - Reusable Strapi plugin for AI capabilities
Multiple Streaming Patterns - SSE and UI Message Stream protocols

Architecture Overview

System Architecture

Request Flow Patterns

Project Structure

ai-sdk/
├── server/                          # Strapi Backend
│   ├── config/
│   │   ├── plugins.ts               # Plugin configuration
│   │   ├── database.ts              # Database settings
│   │   └── server.ts                # Server settings
│   ├── src/
│   │   └── plugins/
│   │       └── ai-sdk/              # Our AI SDK Plugin
│   │           ├── admin/           # Admin UI components
│   │           └── server/          # Backend logic
│   │               ├── src/
│   │               │   ├── controllers/
│   │               │   ├── services/
│   │               │   ├── routes/
│   │               │   └── lib/     # AI SDK integration
│   │               └── package.json
│   ├── .env                         # Environment variables
│   └── package.json
│
├── next-client/                     # Next.js Frontend
│   ├── app/
│   │   ├── layout.tsx               # Root layout
│   │   └── page.tsx                 # Home page
│   ├── components/
│   │   ├── AskExample.tsx           # Non-streaming demo
│   │   ├── AskStreamExample.tsx     # SSE streaming demo
│   │   └── ChatExample.tsx          # Chat interface demo
│   ├── hooks/
│   │   ├── useAsk.ts                # Non-streaming hook
│   │   └── useAskStream.ts          # Streaming hook
│   ├── lib/
│   │   └── api.ts                   # API client functions
│   └── package.json
│
└── docs/                            # Documentation
    └── TUTORIAL.md                  # This file

Technology Stack

Backend (Strapi Server)

Technology	Version	Purpose
Strapi	5.33.3	Headless CMS framework
AI SDK	6.0.39	Vercel's unified AI SDK
@ai-sdk/anthropic	3.0.15	Anthropic provider for AI SDK
TypeScript	5.x	Type-safe development
SQLite	-	Default database (configurable)

Frontend (Next.js Client)

Technology	Version	Purpose
Next.js	16.1.3	React framework
React	19.2.3	UI library
@ai-sdk/react	3.0.41	React hooks for AI SDK
Tailwind CSS	4.x	Utility-first styling
TypeScript	5.x	Type-safe development

AI Services

Service	Model	Purpose
Anthropic Claude	claude-sonnet-4-20250514	Primary LLM

Important: UIMessage vs ModelMessage (AI SDK v6)

In AI SDK v6, there are two distinct message formats:

Format	Used By	Structure
UIMessage	`useChat` hook, frontend state	`{ id, role, parts: [{ type: "text", text }] }`
ModelMessage	`streamText`, `generateText`	`{ role, content }`

The useChat hook manages conversation state using UIMessage format (richer, includes IDs and parts). However, the AI SDK's streamText function expects ModelMessage format.

Use convertToModelMessages(uiMessages) to convert between them:

import { convertToModelMessages, type UIMessage } from "ai";

// In your service layer
async chat(messages: UIMessage[]) {
  const modelMessages = await convertToModelMessages(messages);
  return streamText({ model, messages: modelMessages });
}

Note: convertToModelMessages is async in AI SDK v6 to support async Tool.toModelOutput().

Part 1: Setting Up Strapi

Note: make sure to use Node 22 (lts version)

Note: This tutorial uses npm for all commands. If you prefer yarn or pnpm, the commands are interchangeable (e.g., npm run dev → yarn dev, npm install → yarn add).

Step 1.1: Create a New Strapi Project

# Create a new Strapi project
npx create-strapi@latest server

Complete the following questions:

paul@dev test npx create-strapi-app@latest server

 Strapi   v5.33.3 🚀 Let's create your new project

🚀 Welcome to Strapi! Ready to bring your project to life?

Create a free account and get:
30 days of access to the Growth plan, which includes:
✨ Strapi AI: content-type builder, media library and translations
✅ Live Preview
✅ Single Sign-On (SSO) login
✅ Content History
✅ Releases

? Please log in or sign up. Skip
? Do you want to use the default database (sqlite) ? Yes
? Start with an example structure & data? No
? Start with Typescript? Yes
? Install dependencies with npm? Yes
? Initialize a git repository? Yes
? Participate in anonymous A/B testing (to improve Strapi)? No

 Strapi   Creating a new application at /Users/paul/test/server

# Navigate to the project
cd server

Step 1.2: Project Structure After Creation

server/
├── config/
│   ├── admin.ts
│   ├── api.ts
│   ├── database.ts
│   ├── middlewares.ts
│   ├── plugins.ts
│   └── server.ts
├── database/
├── public/
├── src/
│   └── admin/
├── types/
├── .env
├── .env.example
├── package.json
└── tsconfig.json

Step 1.3: Configure Environment Variables

Create or update your .env file:

# Server
HOST=0.0.0.0
PORT=1337

# Secrets (generate with: openssl rand -base64 32)
APP_KEYS=your-app-keys-here
API_TOKEN_SALT=your-api-token-salt
ADMIN_JWT_SECRET=your-admin-jwt-secret
TRANSFER_TOKEN_SALT=your-transfer-token-salt
JWT_SECRET=your-jwt-secret

# Database (for SQLite)
DATABASE_CLIENT=sqlite
DATABASE_FILENAME=.tmp/data.db

# AI SDK Configuration ( you can use any provider, I chose to use Anthropic)
ANTHROPIC_API_KEY=sk-ant-your-api-key-here
ANTHROPIC_MODEL=claude-sonnet-4-20250514

Step 1.4: Verify Strapi Installation

# Start the development server
cd server
npm run dev

Visit http://localhost:1337 to create your admin account.

Once you have created your Admin User you will be greeted by the Strapi Admin area.

If you have never used Strapi checkout this Crash Course Tutorial that I have created.

Part 2: Building the AI SDK Plugin (Our first Strapi Plugin)

This is the core of our implementation - a Strapi plugin that integrates the Vercel AI SDK with Anthropic Claude.

Plugin Architecture

Step 2.1: Using Strapi Plugin SDK to Scaffold Our Plugin

We'll use the official Strapi Plugin SDK to scaffold our plugin. This CLI toolkit provides a complete project structure with all necessary configuration files.

# From the server directory, run the plugin init command
cd server
npx @strapi/sdk-plugin@latest init ai-sdk

You'll be prompted with several questions. Here are the recommended answers for our AI SDK plugin:

npx @strapi/sdk-plugin@latest init ai-sdk
[INFO]  Creating a new package at:  src/plugins/ai-sdk
✔ plugin name … ai-sdk
✔ plugin display name … AI SDK
✔ plugin description … Integrate AI capabilities using Vercel AI SDK
✔ plugin author name … Paul Bratslavsky
✔ plugin author email … paul.bratslavsky@strapi.io
✔ git url …
✔ plugin license … MIT
✔ register with the admin panel? … yes
✔ register with the server? … yes
✔ use editorconfig? … yes
✔ use eslint? … yes
✔ use prettier? … yes
✔ use typescript? … yes

Important: Make sure to answer Yes to both "register with the admin panel" and "register with the server" since our plugin needs backend API routes.

Troubleshooting: Peer Dependency Error During Scaffolding

The @strapi/sdk-plugin init command automatically runs npm install at the end of scaffolding. You may encounter a peer dependency conflict like this:
npm error ERESOLVE unable to resolve dependency tree
npm error peer react@"19" from react-intl@8.1.3
This happens because the scaffolded plugin template includes react-intl@^8.1.3 (which requires React 19) but sets react@^18.3.1 as a devDependency. Don't worry - the plugin files are still generated successfully, only the npm install step failed.

To fix this, navigate to the plugin directory and install dependencies manually:
cd src/plugins/ai-sdk
npm install --legacy-peer-deps
Alternatively, if you're using Yarn or pnpm, you can install with those instead, as they handle peer dependency conflicts more gracefully:
cd src/plugins/ai-sdk
yarn install  # or: pnpm install

Once this process is done, you will see the following message:

You can now enable your plugin by adding the following in ./config/plugins.ts
───────────────────────────────────
export default {
  // ...
  'ai-sdk': {
    enabled: true,
    resolve: './src/plugins/ai-sdk'
  },
  // ...
}
───────────────────────────────────

[INFO] Plugin generated successfully.

Go ahead and do that now.

Now let's install our dependencies and build out plugin for the first time.

# Navigate to the plugin directory
cd src/plugins/ai-sdk
npm run build

You can also start your plugin in watch mode with the following command:

npm run watch

Then restart your Strapi application by running npm run dev in the root and you should see the following.

Should show up in Menu

Should show up in Settings

Now that we know our basic plugin structure is set up, lets start by installing all the required dependencies.

Step 2.2 Install the AI SDK dependencies

Make sure to run this in the src/plugins/ai-sdk folder:

npm install @ai-sdk/anthropic ai

Note: If you encounter the same ERESOLVE peer dependency error from Step 2.1, use the --legacy-peer-deps flag:
npm install @ai-sdk/anthropic ai --legacy-peer-deps

Note: Don't forget to rebuild your plugin and restart the Strapi application to apply the changes.

Step 2.3: Plugin Structure Overview

After scaffolding, your plugin structure will look like this:

src/plugins/ai-sdk/
├── admin/
│   └── src/
│       ├── components/          # Admin UI components (generated)
│       ├── pages/               # Admin pages (generated)
│       └── index.ts             # Admin entry point
├── server/
│   └── src/
│       ├── controllers/         # We'll add our API controllers here
│       ├── services/            # We'll add our service layer here
│       ├── routes/              # We'll add our routes here
│       └── index.ts             # Server entry point
├── package.json
├── tsconfig.json
└── README.md

Now let's create the additional directories we need for our implementation.

Run the following in the root folder of your plugin:

# Create the lib directory for our core AI SDK integration
mkdir -p server/src/lib
mkdir -p server/src/routes/content-api

We will cover these in detail in a bit.

Phase 1: Plugin Configuration & Initialization

Let's update plugin config to initialize and connect to the Anthropic API. We'll verify it works before adding any endpoints.

Step 2.4: Configure the Plugin in Strapi

First, let's tell Strapi about our plugin and pass it the API key. Update config/plugins.ts in your Strapi root:

export default ({ env }) => ({
  "ai-sdk": {
    enabled: true,
    resolve: "./src/plugins/ai-sdk",
    config: {
      anthropicApiKey: env("ANTHROPIC_API_KEY"),
      chatModel: env("ANTHROPIC_MODEL", "claude-sonnet-4-20250514"),
    },
  },
});

Make sure your .env file has the API key:

ANTHROPIC_API_KEY=sk-ant-your-api-key-here
ANTHROPIC_MODEL=claude-sonnet-4-20250514

Step 2.5: Create Basic Types

Create src/plugins/ai-sdk/server/src/lib/types.ts with just what we need for initialization:

/**
 * Supported Claude model names
 */
export const CHAT_MODELS = [
  "claude-sonnet-4-20250514",
  "claude-opus-4-20250514",
  "claude-3-5-sonnet-20241022",
  "claude-3-5-haiku-20241022",
  "claude-3-haiku-20240307",
] as const;

export type ChatModelName = (typeof CHAT_MODELS)[number];
export const DEFAULT_MODEL: ChatModelName = "claude-sonnet-4-20250514";

/**
 * Plugin configuration interface
 */
export interface PluginConfig {
  anthropicApiKey: string;
  chatModel?: ChatModelName;
  baseURL?: string;
}

We'll add more types as we need them in later phases.

Step 2.6: Create the AI SDK Manager (Basic Version)

Create src/plugins/ai-sdk/server/src/lib/init-ai-sdk.ts. We'll start with just initialization - no AI calls yet:

import { createAnthropic, type AnthropicProvider } from "@ai-sdk/anthropic";
import {
  CHAT_MODELS,
  DEFAULT_MODEL,
  type PluginConfig,
  type ChatModelName,
} from "./types";

/**
 * AISDKManager - Core class for AI SDK integration
 * We'll add AI methods in the next phase
 */
class AISDKManager {
  private provider: AnthropicProvider | null = null;
  private model: ChatModelName = DEFAULT_MODEL;

  /**
   * Initialize the manager with plugin configuration
   * Returns false if config is missing required fields
   */
  initialize(config: unknown): boolean {
    const cfg = config as Partial<PluginConfig> | undefined;

    if (!cfg?.anthropicApiKey) {
      return false;
    }

    this.provider = createAnthropic({
      apiKey: cfg.anthropicApiKey,
      baseURL: cfg.baseURL,
    });

    if (cfg.chatModel && CHAT_MODELS.includes(cfg.chatModel)) {
      this.model = cfg.chatModel;
    }

    return true;
  }

  getChatModel(): ChatModelName {
    return this.model;
  }

  isInitialized(): boolean {
    return this.provider !== null;
  }
}

export const aiSDKManager = new AISDKManager();

Step 2.7: Create the Register Hook

Create src/plugins/ai-sdk/server/src/register.ts. This runs when Strapi starts:

import type { Core } from "@strapi/strapi";
import { aiSDKManager } from "./lib/init-ai-sdk";

const register = ({ strapi }: { strapi: Core.Strapi }) => {
  const config = strapi.config.get("plugin::ai-sdk");
  const initialized = aiSDKManager.initialize(config);

  if (!initialized) {
    strapi.log.warn(
      "AI SDK plugin: anthropicApiKey not configured, plugin will not be initialized",
    );
    return;
  }

  strapi.log.info(
    `AI SDK plugin initialized with model: ${aiSDKManager.getChatModel()}`,
  );
};

export default register;

Step 2.8: Verify Plugin Initialization

Rebuild and start Strapi:

npm run build
npm run develop

Check the console. You will see:

[2026-01-18 16:10:49.069] warn: AI SDK plugin: anthropicApiKey not configured, plugin will not be initialized

We need to add our credentials to our .env file:

ANTHROPIC_API_KEY=your_api_key

Now, restart and you should see the following message:

[2026-01-18 16:15:50.508] info: AI SDK plugin initialized with model: claude-sonnet-4-20250514

Phase 2: Basic Text Generation (Non-Streaming)

Now let's add our first AI endpoint.

Step 2.9: Add generateText to AISDKManager

Update src/plugins/ai-sdk/server/src/lib/init-ai-sdk.ts to add text generation capabilities.

Add to imports:

import { generateText, type LanguageModel } from "ai";

Add these methods to the AISDKManager class (before getChatModel()):

  private getLanguageModel(): LanguageModel {
    if (!this.provider) {
      throw new Error('AI SDK Manager not initialized');
    }
    return this.provider(this.model);
  }

  async generateText(prompt: string, options?: { system?: string }) {
    const result = await generateText({
      model: this.getLanguageModel(),
      prompt,
      system: options?.system,
    });
    return { text: result.text };
  }

Your file should now look like this:

import { createAnthropic, type AnthropicProvider } from "@ai-sdk/anthropic";
import { generateText, type LanguageModel } from "ai"; // ← Added
import {
  CHAT_MODELS,
  DEFAULT_MODEL,
  type PluginConfig,
  type ChatModelName,
} from "./types";

class AISDKManager {
  private provider: AnthropicProvider | null = null;
  private model: ChatModelName = DEFAULT_MODEL;

  initialize(config: unknown): boolean {
    const cfg = config as Partial<PluginConfig> | undefined;

    if (!cfg?.anthropicApiKey) {
      return false;
    }

    this.provider = createAnthropic({
      apiKey: cfg.anthropicApiKey,
      baseURL: cfg.baseURL,
    });

    if (cfg.chatModel && CHAT_MODELS.includes(cfg.chatModel)) {
      this.model = cfg.chatModel;
    }

    return true;
  }

  // ↓ New method
  private getLanguageModel(): LanguageModel {
    if (!this.provider) {
      throw new Error("AI SDK Manager not initialized");
    }
    return this.provider(this.model);
  }

  // ↓ New method
  async generateText(prompt: string, options?: { system?: string }) {
    const result = await generateText({
      model: this.getLanguageModel(),
      prompt,
      system: options?.system,
    });
    return { text: result.text };
  }

  getChatModel(): ChatModelName {
    return this.model;
  }

  isInitialized(): boolean {
    return this.provider !== null;
  }
}

export const aiSDKManager = new AISDKManager();

Step 2.10: Create the Service

Create src/plugins/ai-sdk/server/src/services/service.ts:

import type { Core } from "@strapi/strapi";
import { aiSDKManager } from "../lib/init-ai-sdk";

const service = ({ strapi }: { strapi: Core.Strapi }) => ({
  async ask(prompt: string, options?: { system?: string }) {
    const result = await aiSDKManager.generateText(prompt, options);
    return result.text;
  },

  isInitialized() {
    return aiSDKManager.isInitialized();
  },
});

export default service;

Step 2.11: Create the Controller

Create src/plugins/ai-sdk/server/src/controllers/controller.ts:

import type { Core } from "@strapi/strapi";
import type { Context } from "koa";

const controller = ({ strapi }: { strapi: Core.Strapi }) => ({
  async ask(ctx: Context) {
    const { prompt, system } = (ctx.request as any).body as {
      prompt?: string;
      system?: string;
    };

    if (!prompt || typeof prompt !== "string") {
      ctx.badRequest("prompt is required and must be a string");
      return;
    }

    const service = strapi.plugin("ai-sdk").service("service");
    if (!service.isInitialized()) {
      ctx.badRequest("AI SDK not initialized");
      return;
    }

    const result = await service.ask(prompt, { system });
    ctx.body = { data: { text: result } };
  },
});

export default controller;

Step 2.12: Create the Route

Create src/plugins/ai-sdk/server/src/routes/content-api/index.ts:

export default {
  type: "content-api",
  routes: [
    {
      method: "POST",
      path: "/ask",
      handler: "controller.ask",
      config: { policies: [] },
    },
  ],
};

Create src/plugins/ai-sdk/server/src/routes/index.ts:

import contentApi from "./content-api";

export default {
  "content-api": contentApi,
};

Step 2.13: Test with curl

Rebuild, restart, and test:

curl -X POST http://localhost:1337/api/ai-sdk/ask \
  -H "Content-Type: application/json" \
  -d '{"prompt": "What is 2 + 2? Reply with just the number."}'

You will get the Forbidden message:

{
  "data": null,
  "error": {
    "status": 403,
    "name": "ForbiddenError",
    "message": "Forbidden",
    "details": {}
  }
}

We need to first enable our API in Strapi:

Now, try again.

Expected response:

{ "data": { "text": "4" } }

Step 2.14: Write a Test for the Ask Endpoint

Create tests/test-ask.mjs in your Strapi project root:

const API_URL = "http://localhost:1337/api/ai-sdk";

async function testAsk() {
  console.log("Testing /ask endpoint...\n");

  const response = await fetch(`${API_URL}/ask`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      prompt: "What is Strapi and why should I use it?",
    }),
  });

  if (!response.ok) {
    console.error("Request failed:", response.status, response.statusText);
    const error = await response.text();
    console.error(error);
    process.exit(1);
  }

  const data = await response.json();
  console.log("Response:", JSON.stringify(data, null, 2));

  if (data.data?.text) {
    console.log("\n✅ Test passed!");
  } else {
    console.error("\n❌ Test failed: unexpected response format");
    process.exit(1);
  }
}

testAsk().catch(console.error);

Add the test script to your package.json:

{
  "scripts": {
    "test:ask": "node tests/test-ask.mjs"
  }
}

Run the test:

npm run test:ask

Expected output:

Testing /ask endpoint...

Response: {
  "data": {
    "text": "Strapi is an open-source headless CMS..."
  }
}

✅ Test passed!

Phase 3: Next.js Frontend

Now let's build a simple frontend to interact with our API.

Step 3.1: Create Next.js App

In a separate directory (outside your Strapi project):

npx create-next-app@latest next-client

paul@dev test npx create-next-app@latest next-client
? Would you like to use the recommended Next.js defaults? › - Use arrow-keys. Return to submit.
❯   Yes, use recommended defaults
    TypeScript, ESLint, Tailwind CSS, App Router
    No, reuse previous settings
    No, customize settings

    Using npm.

Initializing project with template: app-tw


Installing dependencies:
- next
- react
- react-dom

Installing devDependencies:
- @tailwindcss/postcss
- @types/node
- @types/react
- @types/react-dom
- eslint
- eslint-config-next
- tailwindcss
- typescript

added 357 packages, and audited 358 packages in 30s

142 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities

Generating route types...
✓ Types generated successfully

Initialized a git repository.

Success! Created next-client at /Users/paul/test/next-client

Step 3.2: Create the API Client

Create the lib folder and add lib/api.ts:

const API_BASE = process.env.NEXT_PUBLIC_API_URL || "http://localhost:1337/api/ai-sdk";

// Simple fetch wrapper
export async function askAI(prompt: string, options?: { system?: string }) {
  const res = await fetch(`${API_BASE}/ask`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ prompt, ...options }),
  });

  if (!res.ok) {
    throw new Error(`API error: ${res.status}`);
  }

  const data = await res.json();
  return data.data?.text as string;
}

export { API_BASE };

Step 3.3: Create the useAsk Hook

Create the hooks folder and add hooks/useAsk.ts:

"use client";

import { useState, useCallback } from "react";
import { askAI } from "@/lib/api";

export function useAsk() {
  const [response, setResponse] = useState("");
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<Error | null>(null);

  const ask = useCallback(async (prompt: string, options?: { system?: string }) => {
    setLoading(true);
    setError(null);
    setResponse("");

    try {
      const text = await askAI(prompt, options);
      setResponse(text);
      return text;
    } catch (err) {
      const error = err instanceof Error ? err : new Error(String(err));
      setError(error);
      throw error;
    } finally {
      setLoading(false);
    }
  }, []);

  const reset = useCallback(() => {
    setResponse("");
    setError(null);
  }, []);

  return { ask, response, loading, error, reset };
}

Create hooks/index.ts to export the hook:

export { useAsk } from "./useAsk";

Step 3.4: Create the AskExample Component

Create the components folder and add components/AskExample.tsx:

"use client";

import { useState, type SubmitEvent } from "react";
import { useAsk } from "@/hooks";

export function AskExample() {
  const [prompt, setPrompt] = useState("What is the capital of France?");
  const { ask, response, loading, error } = useAsk();

  const handleSubmit = async (e: SubmitEvent) => {
    e.preventDefault();
    await ask(prompt);
  };

  return (
    <section className="bg-white dark:bg-zinc-900 rounded-lg p-6 shadow">
      <h2 className="text-xl font-semibold mb-4 text-black dark:text-white">
        /ask - Non-streaming
      </h2>
      <form onSubmit={handleSubmit} className="space-y-4">
        <input
          type="text"
          value={prompt}
          onChange={(e) => setPrompt(e.target.value)}
          className="w-full p-3 border rounded-lg dark:bg-zinc-800 dark:border-zinc-700 dark:text-white"
          placeholder="Enter your prompt..."
        />
        <button
          type="submit"
          disabled={loading}
          className="px-4 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700 disabled:opacity-50"
        >
          {loading ? "Loading..." : "Ask"}
        </button>
      </form>
      {error && (
        <div className="mt-4 p-4 bg-red-100 dark:bg-red-900 rounded-lg">
          <p className="text-red-700 dark:text-red-200">{error.message}</p>
        </div>
      )}
      {response && (
        <div className="mt-4 p-4 bg-zinc-100 dark:bg-zinc-800 rounded-lg">
          <p className="text-black dark:text-white whitespace-pre-wrap">{response}</p>
        </div>
      )}
    </section>
  );
}

Create components/index.ts to export the component:

export { AskExample } from "./AskExample";

Step 3.5: Update the Home Page

Replace app/page.tsx:

import { AskExample } from "@/components";

export default function Home() {
  return (
    <div className="min-h-screen bg-zinc-50 dark:bg-black p-8">
      <main className="max-w-4xl mx-auto space-y-8">
        <h1 className="text-3xl font-bold text-center text-black dark:text-white">
          AI SDK Test
        </h1>

        <div className="grid gap-8">
          <AskExample />
        </div>
      </main>
    </div>
  );
}

Step 3.6: Run the Frontend

npm run dev

Open http://localhost:3000, type a prompt, and click Ask. You should see the AI response appear.

Phase 4: Add Streaming (Enhancement)

Now let's enhance our app with streaming responses for a better user experience. Instead of waiting for the entire response, users will see text appear token-by-token in real time.

Step 4.1: Add streamText to AISDKManager

Update src/plugins/ai-sdk/server/src/lib/init-ai-sdk.ts to add streaming capabilities.

Update the import to add streamText:

import { generateText, streamText, type LanguageModel } from "ai"; // ← Added streamText

Add this method to the AISDKManager class (after generateText()):

  async streamText(prompt: string, options?: { system?: string }) {
    const result = streamText({
      model: this.getLanguageModel(),
      prompt,
      system: options?.system,
    });
    return { textStream: result.textStream };
  }

Your full file should now look like this:

import { createAnthropic, type AnthropicProvider } from "@ai-sdk/anthropic";
import { generateText, streamText, type LanguageModel } from "ai"; // ← Added streamText
import {
  CHAT_MODELS,
  DEFAULT_MODEL,
  type PluginConfig,
  type ChatModelName,
} from "./types";

class AISDKManager {
  private provider: AnthropicProvider | null = null;
  private model: ChatModelName = DEFAULT_MODEL;

  initialize(config: unknown): boolean {
    const cfg = config as Partial<PluginConfig> | undefined;

    if (!cfg?.anthropicApiKey) {
      return false;
    }

    this.provider = createAnthropic({
      apiKey: cfg.anthropicApiKey,
      baseURL: cfg.baseURL,
    });

    if (cfg.chatModel && CHAT_MODELS.includes(cfg.chatModel)) {
      this.model = cfg.chatModel;
    }

    return true;
  }

  private getLanguageModel(): LanguageModel {
    if (!this.provider) {
      throw new Error("AI SDK Manager not initialized");
    }
    return this.provider(this.model);
  }

  async generateText(prompt: string, options?: { system?: string }) {
    const result = await generateText({
      model: this.getLanguageModel(),
      prompt,
      system: options?.system,
    });
    return { text: result.text };
  }

  // ↓ New method
  async streamText(prompt: string, options?: { system?: string }) {
    const result = streamText({
      model: this.getLanguageModel(),
      prompt,
      system: options?.system,
    });
    return { textStream: result.textStream };
  }

  getChatModel(): ChatModelName {
    return this.model;
  }

  isInitialized(): boolean {
    return this.provider !== null;
  }
}

export const aiSDKManager = new AISDKManager();

Step 4.2: Install Koa Types

The SSE utility we're about to create uses Koa's Context type. Install the type definitions in your plugin directory:

cd src/plugins/ai-sdk
npm install --save-dev @types/koa --legacy-peer-deps

Note: After installing, if your editor still shows a "Cannot find module 'koa'" error, don't worry - this is just your IDE not picking up the newly installed types. Reload VS Code (Cmd+Shift+P → "Developer: Reload Window") and the error will disappear. The build itself will work fine.

Step 4.3: Create SSE Utilities

We need a helper to set up Server-Sent Events (SSE) on Koa's response. Create src/plugins/ai-sdk/server/src/lib/utils.ts:

import type { Context } from "koa";
import { PassThrough } from "node:stream";

export function createSSEStream(ctx: Context): PassThrough {
  ctx.set({
    "Content-Type": "text/event-stream",
    "Cache-Control": "no-cache, no-transform",
    Connection: "keep-alive",
    "X-Accel-Buffering": "no",
  });

  const stream = new PassThrough();
  ctx.body = stream;
  ctx.res.flushHeaders();

  return stream;
}

export function writeSSE(stream: PassThrough, data: unknown): void {
  stream.write(`data: ${JSON.stringify(data)}\n\n`);
}

Step 4.4: Add askStream to Service

Update src/plugins/ai-sdk/server/src/services/service.ts to add streaming support.

Add this method (after ask()):

  async askStream(prompt: string, options?: { system?: string }) {
    const result = await aiSDKManager.streamText(prompt, options);
    return result.textStream;
  },

Your full service file should now look like this:

import type { Core } from "@strapi/strapi";
import { aiSDKManager } from "../lib/init-ai-sdk";

const service = ({ strapi }: { strapi: Core.Strapi }) => ({
  async ask(prompt: string, options?: { system?: string }) {
    const result = await aiSDKManager.generateText(prompt, options);
    return result.text;
  },

  // ↓ New method
  async askStream(prompt: string, options?: { system?: string }) {
    const result = await aiSDKManager.streamText(prompt, options);
    return result.textStream;
  },

  isInitialized() {
    return aiSDKManager.isInitialized();
  },
});

export default service;

Step 4.5: Add askStream to Controller

Update src/plugins/ai-sdk/server/src/controllers/controller.ts.

Add the import for our SSE utilities at the top:

import { createSSEStream, writeSSE } from "../lib/utils";

Add this method (after ask()):

  async askStream(ctx: Context) {
    const { prompt, system } = (ctx.request as any).body as { prompt?: string; system?: string };

    if (!prompt || typeof prompt !== 'string') {
      ctx.badRequest('prompt is required');
      return;
    }

    const service = strapi.plugin('ai-sdk').service('service');
    if (!service.isInitialized()) {
      ctx.badRequest('AI SDK not initialized');
      return;
    }

    const textStream = await service.askStream(prompt, { system });
    const stream = createSSEStream(ctx);

    void (async () => {
      try {
        for await (const chunk of textStream) {
          writeSSE(stream, { text: chunk });
        }
        stream.write('data: [DONE]\n\n');
      } catch (error) {
        strapi.log.error('AI SDK stream error:', error);
        writeSSE(stream, { error: 'Stream error' });
      } finally {
        stream.end();
      }
    })();
  },

Your full controller file should now look like this:

import type { Core } from "@strapi/strapi";
import type { Context } from "koa";
import { createSSEStream, writeSSE } from "../lib/utils";

const controller = ({ strapi }: { strapi: Core.Strapi }) => ({
  async ask(ctx: Context) {
    const { prompt, system } = (ctx.request as any).body as {
      prompt?: string;
      system?: string;
    };

    if (!prompt || typeof prompt !== "string") {
      ctx.badRequest("prompt is required and must be a string");
      return;
    }

    const service = strapi.plugin("ai-sdk").service("service");
    if (!service.isInitialized()) {
      ctx.badRequest("AI SDK not initialized");
      return;
    }

    const result = await service.ask(prompt, { system });
    ctx.body = { data: { text: result } };
  },

  // ↓ New method
  async askStream(ctx: Context) {
    const { prompt, system } = (ctx.request as any).body as {
      prompt?: string;
      system?: string;
    };

    if (!prompt || typeof prompt !== "string") {
      ctx.badRequest("prompt is required");
      return;
    }

    const service = strapi.plugin("ai-sdk").service("service");
    if (!service.isInitialized()) {
      ctx.badRequest("AI SDK not initialized");
      return;
    }

    const textStream = await service.askStream(prompt, { system });
    const stream = createSSEStream(ctx);

    void (async () => {
      try {
        for await (const chunk of textStream) {
          writeSSE(stream, { text: chunk });
        }
        stream.write("data: [DONE]\n\n");
      } catch (error) {
        strapi.log.error("AI SDK stream error:", error);
        writeSSE(stream, { error: "Stream error" });
      } finally {
        stream.end();
      }
    })();
  },
});

export default controller;

Step 4.6: Add Streaming Route

Update src/plugins/ai-sdk/server/src/routes/content-api/index.ts to add the new endpoint:

export default {
  type: "content-api",
  routes: [
    {
      method: "POST",
      path: "/ask",
      handler: "controller.ask",
      config: { policies: [] },
    },
    {
      method: "POST",
      path: "/ask-stream",
      handler: "controller.askStream",
      config: { policies: [] },
    },
  ],
};

Step 4.7: Test Streaming with curl

Rebuild and restart your plugin, then test:

curl -X POST http://localhost:1337/api/ai-sdk/ask-stream \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Count from 1 to 5"}'

Important: Don't forget to enable the new endpoint in Strapi Admin: Settings → Users & Permissions → Roles → Public → Ai-sdk → ask-stream.

You should see SSE events streaming in:

data: {"text":"1"}
data: {"text":","}
data: {"text":" 2"}
...

data: [DONE]

Step 4.8: Write a Test for the Stream Endpoint

Create tests/test-stream.mjs in your Strapi project root:

const API_URL = "http://localhost:1337/api/ai-sdk";

async function testStream() {
  console.log("Testing /ask-stream endpoint...\n");

  const response = await fetch(`${API_URL}/ask-stream`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ prompt: "Count from 1 to 5" }),
  });

  if (!response.ok) {
    console.error("Request failed:", response.status, response.statusText);
    const error = await response.text();
    console.error(error);
    process.exit(1);
  }

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    process.stdout.write(decoder.decode(value));
  }

  console.log("\n\n✅ Stream test passed!");
}

testStream().catch(console.error);

Add the test script to your package.json:

{
  "scripts": {
    "test:ask": "node tests/test-ask.mjs",
    "test:stream": "node tests/test-stream.mjs"
  }
}

Run the test:

npm run test:stream

Step 4.9: Add Streaming to the Frontend

Now let's add streaming support to our Next.js app. We'll create a dedicated hook and component that sits alongside the existing non-streaming ones.

Add the `askStreamAI` function to `lib/api.ts`:

export async function askStreamAI(
  prompt: string,
  options?: { system?: string }
): Promise<Response> {
  const res = await fetch(`${API_BASE}/ask-stream`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ prompt, ...options }),
  });

  if (!res.ok) {
    throw new Error(`API error: ${res.status}`);
  }

  return res;
}

Create `hooks/useAskStream.ts`:

"use client";

import { useState, useCallback } from "react";
import { askStreamAI } from "@/lib/api";

export function useAskStream() {
  const [response, setResponse] = useState("");
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<Error | null>(null);

  const askStream = useCallback(
    async (prompt: string, options?: { system?: string }) => {
      setLoading(true);
      setError(null);
      setResponse("");

      try {
        const res = await askStreamAI(prompt, options);
        const reader = res.body?.getReader();
        const decoder = new TextDecoder();

        if (!reader) throw new Error("No reader available");

        while (true) {
          const { done, value } = await reader.read();
          if (done) break;

          const chunk = decoder.decode(value);
          const lines = chunk.split("\n");

          for (const line of lines) {
            if (line.startsWith("data: ") && line !== "data: [DONE]") {
              try {
                const data = JSON.parse(line.slice(6));
                if (data.text) {
                  setResponse((prev) => prev + data.text);
                }
              } catch {
                // Skip invalid JSON
              }
            }
          }
        }
      } catch (err) {
        const error = err instanceof Error ? err : new Error(String(err));
        setError(error);
        throw error;
      } finally {
        setLoading(false);
      }
    },
    []
  );

  const reset = useCallback(() => {
    setResponse("");
    setError(null);
  }, []);

  return { askStream, response, loading, error, reset };
}

Update `hooks/index.ts`:

export { useAsk } from "./useAsk";
export { useAskStream } from "./useAskStream";

Create `components/AskStreamExample.tsx`:

"use client";

import { useState, type SubmitEvent } from "react";
import { useAskStream } from "@/hooks";

export function AskStreamExample() {
  const [prompt, setPrompt] = useState("Count from 1 to 10 and explain each number.");
  const { askStream, response, loading, error } = useAskStream();

  const handleSubmit = async (e: SubmitEvent) => {
    e.preventDefault();
    await askStream(prompt);
  };

  return (
    <section className="bg-white dark:bg-zinc-900 rounded-lg p-6 shadow">
      <h2 className="text-xl font-semibold mb-4 text-black dark:text-white">
        /ask-stream - SSE Streaming
      </h2>
      <form onSubmit={handleSubmit} className="space-y-4">
        <input
          type="text"
          value={prompt}
          onChange={(e) => setPrompt(e.target.value)}
          className="w-full p-3 border rounded-lg dark:bg-zinc-800 dark:border-zinc-700 dark:text-white"
          placeholder="Enter your prompt..."
        />
        <button
          type="submit"
          disabled={loading}
          className="px-4 py-2 bg-green-600 text-white rounded-lg hover:bg-green-700 disabled:opacity-50"
        >
          {loading ? "Streaming..." : "Ask (Stream)"}
        </button>
      </form>
      {error && (
        <div className="mt-4 p-4 bg-red-100 dark:bg-red-900 rounded-lg">
          <p className="text-red-700 dark:text-red-200">{error.message}</p>
        </div>
      )}
      {response && (
        <div className="mt-4 p-4 bg-zinc-100 dark:bg-zinc-800 rounded-lg">
          <p className="text-black dark:text-white whitespace-pre-wrap">{response}</p>
        </div>
      )}
    </section>
  );
}

Update `components/index.ts`:

export { AskExample } from "./AskExample";
export { AskStreamExample } from "./AskStreamExample";

Update `app/page.tsx` to include both examples:

import { AskExample, AskStreamExample } from "@/components";

export default function Home() {
  return (
    <div className="min-h-screen bg-zinc-50 dark:bg-black p-8">
      <main className="max-w-4xl mx-auto space-y-8">
        <h1 className="text-3xl font-bold text-center text-black dark:text-white">
          AI SDK Test
        </h1>

        <div className="grid gap-8">
          <AskExample />
          <AskStreamExample />
        </div>
      </main>
    </div>
  );
}

Step 4.10: Run and Test

Start both your Strapi server and Next.js client:

# Terminal 1 - Strapi
cd server
npm run develop

# Terminal 2 - Next.js
cd next-client
npm run dev

Open http://localhost:3000. You should now see two sections - the original non-streaming "Ask" and the new "Ask (Stream)". Try the streaming version and watch the response appear token-by-token in real time.

Congratulations! You now have both non-streaming and streaming AI responses working end-to-end.

Phase 5: Add Chat with useChat Hook (Enhancement)

This final phase adds full multi-turn chat support compatible with the useChat hook from @ai-sdk/react. Unlike our previous endpoints that take a single prompt, chat maintains conversation history and streams responses using the UI Message Stream protocol.

Step 5.1: Update Types for Chat

We need to add types for handling chat messages. Update src/plugins/ai-sdk/server/src/lib/types.ts:

import type { ModelMessage } from "ai";

export const CHAT_MODELS = [
  "claude-sonnet-4-20250514",
  "claude-opus-4-20250514",
  "claude-3-5-sonnet-20241022",
  "claude-3-5-haiku-20241022",
  "claude-3-haiku-20240307",
] as const;

export type ChatModelName = (typeof CHAT_MODELS)[number];
export const DEFAULT_MODEL: ChatModelName = "claude-sonnet-4-20250514";
export const DEFAULT_TEMPERATURE = 0.7;

export interface PluginConfig {
  anthropicApiKey: string;
  chatModel?: ChatModelName;
  baseURL?: string;
}

export interface GenerateOptions {
  system?: string;
  temperature?: number;
  maxOutputTokens?: number;
}

export interface PromptInput extends GenerateOptions {
  prompt: string;
}

export interface MessagesInput extends GenerateOptions {
  messages: ModelMessage[];
}

export type GenerateInput = PromptInput | MessagesInput;

export function isPromptInput(input: GenerateInput): input is PromptInput {
  return "prompt" in input;
}

Step 5.2: Add streamRaw to AISDKManager

Update src/plugins/ai-sdk/server/src/lib/init-ai-sdk.ts to support the useChat hook.

Update the imports from ./types to include the new types:

import {
  CHAT_MODELS,
  DEFAULT_MODEL,
  DEFAULT_TEMPERATURE, // ← Added
  isPromptInput, // ← Added
  type PluginConfig,
  type ChatModelName,
  type GenerateInput, // ← Added
} from "./types";

Add this interface before the AISDKManager class:

export interface StreamTextRawResult {
  readonly textStream: AsyncIterable<string>;
  toUIMessageStreamResponse(): Response;
}

Add these methods to the AISDKManager class (after getLanguageModel()):

  private buildParams(input: GenerateInput) {
    const base = {
      model: this.getLanguageModel(),
      system: input.system,
      temperature: input.temperature ?? DEFAULT_TEMPERATURE,
      maxOutputTokens: input.maxOutputTokens,
    };

    return isPromptInput(input)
      ? { ...base, prompt: input.prompt }
      : { ...base, messages: input.messages };
  }

Add this method (after streamText()):

  streamRaw(input: GenerateInput): StreamTextRawResult {
    return streamText(this.buildParams(input)) as StreamTextRawResult;
  }

Your full file should now look like this:

import { createAnthropic, type AnthropicProvider } from "@ai-sdk/anthropic";
import { generateText, streamText, type LanguageModel } from "ai";
import {
  CHAT_MODELS,
  DEFAULT_MODEL,
  DEFAULT_TEMPERATURE,
  isPromptInput,
  type PluginConfig,
  type ChatModelName,
  type GenerateInput,
} from "./types";

export interface StreamTextRawResult {
  readonly textStream: AsyncIterable<string>;
  toUIMessageStreamResponse(): Response;
}

class AISDKManager {
  private provider: AnthropicProvider | null = null;
  private model: ChatModelName = DEFAULT_MODEL;

  initialize(config: unknown): boolean {
    const cfg = config as Partial<PluginConfig> | undefined;

    if (!cfg?.anthropicApiKey) {
      return false;
    }

    this.provider = createAnthropic({
      apiKey: cfg.anthropicApiKey,
      baseURL: cfg.baseURL,
    });

    if (cfg.chatModel && CHAT_MODELS.includes(cfg.chatModel)) {
      this.model = cfg.chatModel;
    }

    return true;
  }

  private getLanguageModel(): LanguageModel {
    if (!this.provider) {
      throw new Error("AI SDK Manager not initialized");
    }
    return this.provider(this.model);
  }

  // ↓ New method
  private buildParams(input: GenerateInput) {
    const base = {
      model: this.getLanguageModel(),
      system: input.system,
      temperature: input.temperature ?? DEFAULT_TEMPERATURE,
      maxOutputTokens: input.maxOutputTokens,
    };

    return isPromptInput(input)
      ? { ...base, prompt: input.prompt }
      : { ...base, messages: input.messages };
  }

  async generateText(prompt: string, options?: { system?: string }) {
    const result = await generateText({
      model: this.getLanguageModel(),
      prompt,
      system: options?.system,
    });
    return { text: result.text };
  }

  async streamText(prompt: string, options?: { system?: string }) {
    const result = streamText({
      model: this.getLanguageModel(),
      prompt,
      system: options?.system,
    });
    return { textStream: result.textStream };
  }

  // ↓ New method
  streamRaw(input: GenerateInput): StreamTextRawResult {
    return streamText(this.buildParams(input)) as StreamTextRawResult;
  }

  getChatModel(): ChatModelName {
    return this.model;
  }

  isInitialized(): boolean {
    return this.provider !== null;
  }
}

export const aiSDKManager = new AISDKManager();

Step 5.3: Add Chat to Service

Update src/plugins/ai-sdk/server/src/services/service.ts.

Update the imports:

import type { Core } from "@strapi/strapi";
import type { UIMessage } from "ai"; // ← Added
import { convertToModelMessages } from "ai"; // ← Added
import { aiSDKManager, type StreamTextRawResult } from "../lib/init-ai-sdk"; // ← Added type

Add this method (after askStream()):

  async chat(messages: UIMessage[], options?: { system?: string }): Promise<StreamTextRawResult> {
    const modelMessages = await convertToModelMessages(messages);
    return aiSDKManager.streamRaw({
      messages: modelMessages,
      system: options?.system,
    });
  },

Your full service file should now look like this:

import type { Core } from "@strapi/strapi";
import type { UIMessage } from "ai";
import { convertToModelMessages } from "ai";
import { aiSDKManager, type StreamTextRawResult } from "../lib/init-ai-sdk";

const service = ({ strapi }: { strapi: Core.Strapi }) => ({
  async ask(prompt: string, options?: { system?: string }) {
    const result = await aiSDKManager.generateText(prompt, options);
    return result.text;
  },

  async askStream(prompt: string, options?: { system?: string }) {
    const result = await aiSDKManager.streamText(prompt, options);
    return result.textStream;
  },

  // ↓ New method
  async chat(messages: UIMessage[], options?: { system?: string }): Promise<StreamTextRawResult> {
    const modelMessages = await convertToModelMessages(messages);
    return aiSDKManager.streamRaw({
      messages: modelMessages,
      system: options?.system,
    });
  },

  isInitialized() {
    return aiSDKManager.isInitialized();
  },
});

export default service;

Step 5.4: Add Chat to Controller

Update src/plugins/ai-sdk/server/src/controllers/controller.ts.

Add the import for Readable at the top:

import { Readable } from "node:stream";

Add this method (after askStream()):

  async chat(ctx: Context) {
    const { messages, system } = (ctx.request as any).body as {
      messages?: any[];
      system?: string;
    };

    if (!messages || !Array.isArray(messages) || messages.length === 0) {
      ctx.badRequest("messages is required and must be a non-empty array");
      return;
    }

    const service = strapi.plugin("ai-sdk").service("service");
    if (!service.isInitialized()) {
      ctx.badRequest("AI SDK not initialized");
      return;
    }

    const result = await service.chat(messages, { system });
    const response = result.toUIMessageStreamResponse();

    ctx.status = 200;
    ctx.set("Content-Type", "text/event-stream; charset=utf-8");
    ctx.set("Cache-Control", "no-cache, no-transform");
    ctx.set("Connection", "keep-alive");
    ctx.set("X-Accel-Buffering", "no");
    ctx.set("x-vercel-ai-ui-message-stream", "v1");

    ctx.body = Readable.fromWeb(
      response.body as import("stream/web").ReadableStream
    );
  },

Your full controller file should now look like this:

import type { Core } from "@strapi/strapi";
import type { Context } from "koa";
import { Readable } from "node:stream";
import { createSSEStream, writeSSE } from "../lib/utils";

const controller = ({ strapi }: { strapi: Core.Strapi }) => ({
  async ask(ctx: Context) {
    const { prompt, system } = (ctx.request as any).body as {
      prompt?: string;
      system?: string;
    };

    if (!prompt || typeof prompt !== "string") {
      ctx.badRequest("prompt is required and must be a string");
      return;
    }

    const service = strapi.plugin("ai-sdk").service("service");
    if (!service.isInitialized()) {
      ctx.badRequest("AI SDK not initialized");
      return;
    }

    const result = await service.ask(prompt, { system });
    ctx.body = { data: { text: result } };
  },

  async askStream(ctx: Context) {
    const { prompt, system } = (ctx.request as any).body as {
      prompt?: string;
      system?: string;
    };

    if (!prompt || typeof prompt !== "string") {
      ctx.badRequest("prompt is required");
      return;
    }

    const service = strapi.plugin("ai-sdk").service("service");
    if (!service.isInitialized()) {
      ctx.badRequest("AI SDK not initialized");
      return;
    }

    const textStream = await service.askStream(prompt, { system });
    const stream = createSSEStream(ctx);

    void (async () => {
      try {
        for await (const chunk of textStream) {
          writeSSE(stream, { text: chunk });
        }
        stream.write("data: [DONE]\n\n");
      } catch (error) {
        strapi.log.error("AI SDK stream error:", error);
        writeSSE(stream, { error: "Stream error" });
      } finally {
        stream.end();
      }
    })();
  },

  // ↓ New method
  async chat(ctx: Context) {
    const { messages, system } = (ctx.request as any).body as {
      messages?: any[];
      system?: string;
    };

    if (!messages || !Array.isArray(messages) || messages.length === 0) {
      ctx.badRequest("messages is required and must be a non-empty array");
      return;
    }

    const service = strapi.plugin("ai-sdk").service("service");
    if (!service.isInitialized()) {
      ctx.badRequest("AI SDK not initialized");
      return;
    }

    const result = await service.chat(messages, { system });
    const response = result.toUIMessageStreamResponse();

    ctx.status = 200;
    ctx.set("Content-Type", "text/event-stream; charset=utf-8");
    ctx.set("Cache-Control", "no-cache, no-transform");
    ctx.set("Connection", "keep-alive");
    ctx.set("X-Accel-Buffering", "no");
    ctx.set("x-vercel-ai-ui-message-stream", "v1");

    ctx.body = Readable.fromWeb(
      response.body as import("stream/web").ReadableStream
    );
  },
});

export default controller;

Step 5.5: Add Chat Route

Update src/plugins/ai-sdk/server/src/routes/content-api/index.ts to add the chat endpoint:

export default {
  type: "content-api",
  routes: [
    {
      method: "POST",
      path: "/ask",
      handler: "controller.ask",
      config: { policies: [] },
    },
    {
      method: "POST",
      path: "/ask-stream",
      handler: "controller.askStream",
      config: { policies: [] },
    },
    {
      method: "POST",
      path: "/chat",
      handler: "controller.chat",
      config: { policies: [] },
    },
  ],
};

Step 5.6: Test Chat with curl

Rebuild your plugin, restart Strapi, and test:

curl -X POST http://localhost:1337/api/ai-sdk/chat \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "id": "1",
      "role": "user",
      "parts": [{"type": "text", "text": "Hello!"}]
    }]
  }'

Important: Don't forget to enable the new endpoint in Strapi Admin: Settings → Users & Permissions → Roles → Public → Ai-sdk → chat.

Step 5.7: Write a Test for the Chat Endpoint

Create tests/test-chat.mjs in your Strapi project root:

/**
 * Test chat endpoint with UIMessage format
 *
 * In AI SDK v6, the useChat hook sends UIMessage format:
 * - id: unique message identifier
 * - role: "user" | "assistant" | "system"
 * - parts: array of content parts (text, tool calls, etc.)
 */
const API_URL = "http://localhost:1337/api/ai-sdk";

async function testChat() {
  console.log("Testing /chat endpoint...\n");

  const response = await fetch(`${API_URL}/chat`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      messages: [
        {
          id: "msg-1",
          role: "user",
          parts: [{ type: "text", text: "Hello! What is Strapi?" }],
        },
      ],
    }),
  });

  if (!response.ok) {
    console.error("Request failed:", response.status, response.statusText);
    const error = await response.text();
    console.error(error);
    process.exit(1);
  }

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    process.stdout.write(decoder.decode(value));
  }

  console.log("\n\n✅ Chat test passed!");
}

testChat().catch(console.error);

Add the test script to your package.json:

{
  "scripts": {
    "test:ask": "node tests/test-ask.mjs",
    "test:stream": "node tests/test-stream.mjs",
    "test:chat": "node tests/test-chat.mjs"
  }
}

Run the test:

npm run test:chat

Step 5.8: Add Chat to the Frontend

Now let's add a full chat interface using the useChat hook from @ai-sdk/react.

Install the AI SDK React package in your Next.js app:

cd next-client
npm install @ai-sdk/react

Create `components/ChatExample.tsx`:

"use client";

import { useState, type SubmitEvent } from "react";
import { useChat } from "@ai-sdk/react";
import { DefaultChatTransport } from "ai";

const transport = new DefaultChatTransport({
  api: "http://localhost:1337/api/ai-sdk/chat",
});

export function ChatExample() {
  const [input, setInput] = useState("");
  const { messages, sendMessage, status } = useChat({ transport });

  const isLoading = status === "submitted" || status === "streaming";

  const handleSubmit = async (e: SubmitEvent) => {
    e.preventDefault();
    if (!input.trim() || isLoading) return;

    const text = input;
    setInput("");
    await sendMessage({ text });
  };

  return (
    <section className="bg-white dark:bg-zinc-900 rounded-lg p-6 shadow">
      <h2 className="text-xl font-semibold mb-4 text-black dark:text-white">
        /chat - Multi-turn Chat
      </h2>

      <div className="space-y-3 mb-4 max-h-96 overflow-y-auto">
        {messages.map((message) => (
          <div
            key={message.id}
            className={`p-3 rounded-lg ${
              message.role === "user"
                ? "bg-blue-100 dark:bg-blue-900 ml-auto max-w-[80%]"
                : "bg-zinc-100 dark:bg-zinc-800 mr-auto max-w-[80%]"
            }`}
          >
            <p className="text-xs font-semibold mb-1 text-zinc-500 dark:text-zinc-400">
              {message.role === "user" ? "You" : "AI"}
            </p>
            <p className="text-black dark:text-white whitespace-pre-wrap">
              {message.parts
                .filter((part) => part.type === "text")
                .map((part) => part.text)
                .join("")}
            </p>
          </div>
        ))}
      </div>

      <form onSubmit={handleSubmit} className="flex gap-2">
        <input
          value={input}
          onChange={(e) => setInput(e.target.value)}
          placeholder="Type a message..."
          className="flex-1 p-3 border rounded-lg dark:bg-zinc-800 dark:border-zinc-700 dark:text-white"
          disabled={isLoading}
        />
        <button
          type="submit"
          disabled={isLoading || !input.trim()}
          className="px-4 py-2 bg-purple-600 text-white rounded-lg hover:bg-purple-700 disabled:opacity-50"
        >
          {isLoading ? "..." : "Send"}
        </button>
      </form>
    </section>
  );
}

Note: In AI SDK v6, useChat no longer manages input state internally. You manage the input with useState yourself and use sendMessage({ text }) instead of the old handleSubmit. The status property ('ready' | 'submitted' | 'streaming' | 'error') replaces isLoading.

Update `components/index.ts`:

export { AskExample } from "./AskExample";
export { AskStreamExample } from "./AskStreamExample";
export { ChatExample } from "./ChatExample";

Update `app/page.tsx` to include all three examples:

import { AskExample, AskStreamExample, ChatExample } from "@/components";

export default function Home() {
  return (
    <div className="min-h-screen bg-zinc-50 dark:bg-black p-8">
      <main className="max-w-4xl mx-auto space-y-8">
        <h1 className="text-3xl font-bold text-center text-black dark:text-white">
          AI SDK Test
        </h1>

        <div className="grid gap-8">
          <AskExample />
          <AskStreamExample />
          <ChatExample />
        </div>
      </main>
    </div>
  );
}

Step 5.9: Run and Test

Start both your Strapi server and Next.js client:

# Terminal 1 - Strapi
cd server
npm run develop

# Terminal 2 - Next.js
cd next-client
npm run dev

Open http://localhost:3000. You should now see all three sections:

Ask - Non-streaming, waits for full response
Ask (Stream) - SSE streaming, tokens appear in real time
Chat - Full multi-turn conversation with message history

Try sending multiple messages in the Chat section - the conversation history is maintained, so the AI remembers context from previous messages.

Nice—we did it! Great job. So what’s next? I’d love to see the AI integrations you build based on what you’ve learned.

As for me, I might have gone a bit overboard. I kept building and ended up adding AI chat directly into the Strapi Admin, with the ability to call tools and expose everything via MCP. It’s still a work in progress, but it’s coming together nicely.

[why.mp4](https://delicate-dawn-ac25646e6d.media.strapiapp.com/why_cb2dd1c9a5.mp4) Your browser does not support the video tag.

Project repo: https://github.com/PaulBratslavsky/fun-strapi-ai-plugin

Did you know?
Strapi hosts Open Office Hours on Discord Monday through Friday at 12:30 PM CST (running until about 1:30 PM CST). It's a great way to connect, get help, and share your feedback directly with the team.

Why SQLite Is a Poor Fit for Production Strapi Applications

Strapi — Fri, 13 Mar 2026 10:03:46 +0000

SQLite is often described as a “toy database” — and that description is both unfair and unhelpful.

SQLite is an extremely capable, well-engineered piece of software. It powers mobile apps, desktop software, embedded systems, and countless internal tools. In the right context, it’s fast, reliable, and elegant.

But Strapi is not that context.

While Strapi supports SQLite for development and testing, it is not a suitable choice for production Strapi applications. This isn’t about scale, traffic volume, or whether SQLite is “good enough”. It’s about architectural fit, operational risk, and long-term correctness.

Let’s break down why.

SQLite is an embedded database — Strapi is a server platform

SQLite is designed to be embedded. That means:

The database lives alongside the application
A single process controls access
Operational concerns are deliberately minimal
The database is not treated as an independent system

This design is a feature, not a flaw. It’s exactly why SQLite works so well for:

Desktop applications
Mobile apps
Local tools
Automated tests
Prototypes

Strapi, however, is a long-running server application. Even in its simplest production form, a Strapi instance typically involves:

Concurrent admin users
Public API traffic
Background work (cron jobs, webhooks, releases)
Regular restarts during deployments
Content that becomes business-critical over time

These characteristics introduce operational demands that SQLite is intentionally not designed to solve.

File-based databases introduce real operational risk

SQLite stores all data in a single file. In production environments, this becomes a liability.

As write activity increases — even modestly — SQLite relies on file-level locking. Overlapping admin actions, background tasks, and API writes can result in:

Slow requests
Timeouts
Failed writes
Intermittent, hard-to-reproduce bugs

These issues rarely show up immediately. They tend to surface gradually, once a project is live and actively used.

Restarts and deployments are another pressure point. In modern hosting environments, processes restart. Containers are replaced. Infrastructure is upgraded. When all states live in a single file, unexpected interruptions increase the risk of database corruption or an inconsistent state.

Recovering from these situations is far more fragile than with a server-based database designed for long-running workloads.

“But my site is small” is the wrong question

One of the most common arguments in favour of SQLite is that it works fine for “small” sites.

The problem is that production risk is not driven by traffic volume alone.

For CMS-driven applications like Strapi, risk comes from:

Editorial workflows
Content correctness
Uptime expectations
Deployment frequency
The cost of data loss or corruption

A Strapi project with five editors and a modest API footprint can hit SQLite’s limits faster than a read-heavy public website.

Once content becomes the source of truth for a business, “mostly works” is no longer good enough.

Data integrity and foreign key constraints matter more than you think

Another subtle but important issue is data integrity.

SQLite is more permissive by default than databases like PostgreSQL. Historically, foreign key constraints were disabled by default, and even today, SQLite’s type system and constraint enforcement are looser than what most production teams expect.

In practice, this means:

Invalid or inconsistent data can be written without errors
Migrations behave differently across environments
Bugs may remain hidden until a later database switch
Issues surface late, when fixing them is expensive

PostgreSQL (and similar databases) enforce stricter constraints by default. They fail fast when data is incorrect, which is exactly what you want in a system managing structured content.

For Strapi projects, this difference alone is often enough reason to avoid SQLite in production.

Workarounds exist — but they miss the point

There are tools that attempt to add replication, backups, or higher availability on top of SQLite. They can be impressive pieces of engineering.

But needing to add layers of infrastructure just to make your database safe is a strong signal that you’re using the wrong tool for the job.

Strapi does not test, document, or support these setups. Adding them increases complexity, creates unclear failure modes, and pushes responsibility entirely onto the application team.

Production systems benefit from boring, well-understood foundations.

The recommended approach

For production deployments, Strapi strongly recommends using a server-based relational database, such as PostgreSQL (recommended) or MySQL/MariaDB.

These databases are designed to:

Handle concurrent workloads safely
Enforce data integrity consistently
Support reliable backups and recovery
Behave predictably during restarts and deployments

SQLite remains an excellent choice for:

Local development
Automated testing
Proof-of-concept or demo environments

But once your Strapi application goes live, switching early to a production-grade database will save time, reduce risk, and avoid painful migrations later.

Want the easiest way to run Strapi with a production-ready database?

If you’re looking for a simple, low-friction way to run Strapi with a production-grade database, Strapi Cloud is the easiest option.

Strapi Cloud provisions and manages a production-ready database for you, with sensible defaults and best practices already in place. You don’t need to worry about database setup, configuration, or ongoing maintenance — everything is designed to work seamlessly with Strapi out of the box.

This allows teams to:

Start with a production-safe database from day one
Avoid risky SQLite-based deployments
Focus on content modelling and application logic rather than infrastructure
Scale confidently as usage grows

If you’d prefer to self-host, PostgreSQL or MySQL/MariaDB remain the recommended choices. But if you want the fastest path to a stable production setup, Strapi Cloud removes much of the operational overhead.

Learn more about running Strapi on Cloud: https://strapi.io/cloud

Final thought

SQLite is not “bad”. It’s just not the right tool for production Strapi applications.

Choosing infrastructure that aligns with how your system actually behaves — not how you hope it behaves — is one of the simplest ways to avoid long-term pain.

Shipping Faster with Strapi AI Translations & More Homepage Customizations

Strapi — Thu, 13 Nov 2025 13:37:27 +0000

Automate Multilingual Content with Strapi AI Translations

Ship multilingual content faster with Strapi AI Translations. Build once. Publish in all languages. As of v5.30, Strapi auto‑translates your content using Strapi AI. No extra services to wire up. No webhooks. No background jobs.

With AI translations, your content now stays automatically in sync across locales. Every time you edit and save in the default locale, Strapi AI updates all other locales to match—removing the manual burden from editors. It also translates dynamic zones and blocks on the fly!

Outcome: Launch new markets in hours, not weeks
Reliability: Preserve schema, relations, and media across languages
Simplicity: Works out of the box once enabled from the Internationalization Settings pages

Why it matters

Teams waste time exporting content, managing third-party translation loops, and resolving broken relationships per locale. Strapi AI Translations removes that overhead so you can:

Scale to new regions without rewriting pipelines
Keep editorial flow in Strapi, not spreadsheets or other 3rd party services
Maintain design and data integrity across locales

Your browser does not support the video tag.

How it works

For detailed instructions on using AI-powered internationalization, refer to the official documentation.

Availability & Billing

Plan: Growth
Trial: Included in 30‑day Growth trial
Credits: 1000 monthly AI translation credits
Billing: Usage‑based beyond quota

Homepage Customization Layout Control

As of Strapi v5.30, every Strapi user can now customize the layout of the homepage widgets with:

Drag-and-drop reordering: Arrange widgets to match your workflow priorities
Flexible sizing: Resize widgets to emphasize what matters most
Full control: Remove clutter or restore widgets as your needs evolve

Why is it needed?

Enhance the user experience on the homepage to fit their needs and roles.

Editors and developers can rearrange, resize, or remove widgets to make the dashboard fit their daily workflow. Using drag-and-drop, you can change the widget order, hide non-essential ones, or add them back at any time.

This small UX improvement adds flexibility and focus — whether you want to track releases, review workflow activity, or monitor content updates at a glance.

Your browser does not support the video tag.

Try Strapi Today

New to Strapi? Run the following command in your terminal:

npx create-strapi-app@latest

And, follow the Quick Start guide.

Ready to implement the new improvements in your project? Upgrade to the latest Strapi version and start using all the latest features today!

How To Build a Frontend with Lovable.dev for Your Strapi Backend

Strapi — Thu, 13 Nov 2025 13:20:00 +0000

This is my first time using Lovable to build a frontend for a Strapi backend. Here's what I learned.

AI tools like Lovable.dev and Claude Code help you bring ideas to life faster. They're great for quick prototypes and trying new approaches. But they're not magic—they're tools.

Like any tool, they have strengths and weaknesses. Success comes from knowing what each tool does well and using it appropriately.

You still need to understand what you're building. You need to know your data structure, the problems you're solving, and your tech stack. And yes—you still need to know how to code.

These tools are powerful, but they sometimes hallucinate or create errors. The better you understand your project structure and how AI tools work, the better your results will be.

In this post, I'll walk you through building a frontend with Lovable.dev that connects to a Strapi backend.

TLDR: Summary at a Glance

What This Covers: Using Lovable.dev (AI coding tool) to build a frontend for your Strapi backend

Key Insights:

AI tools aren't magic—you still need to understand your data, API, and how to code
Backend-first approach: Start with Strapi + OpenAPI spec, let Lovable build from real data
Two strategies: One-shot (not recommended) vs. Iterative (recommended approach )

Critical Success Factors:

Context is everything: Real API responses, Strapi v5 patterns, exact field names
Use Knowledge files, Chat Mode, version pinning, and guardrails
Test after each feature, not at the end

Common Mistakes:

Vague prompts → Generic code
Missing version info → Wrong Strapi patterns
No real data examples → Incorrect field names

4. Testing too late → Bugs compound

What is Lovable.dev?

Lovable.dev is a browser-based AI development platform. You describe what you want in plain English, and Lovable writes the code for you.

Your browser does not support the video tag.

What is Vibe Coding?

Vibe coding is a relaxed, creative way to build applications using AI tools. Instead of writing every line of code yourself, you describe what you want and let the AI handle the heavy lifting. Then you guide and refine the work step by step.

The "vibe" is about maintaining momentum—trying ideas quickly without getting stuck on setup or syntax.

These tools have their place, especially when you want to prototype or iterate on initial ideas quickly.

Why Use Lovable.dev with Strapi?

Here's why this combination works:

Your rubber ducky (that codes)
Talk to Lovable like you'd talk through a problem with a teammate. It helps you think out loud, propose structures, and generate a first pass so you're not staring at a blank file.

Quick iteration loops
Change a prompt, regenerate, test against your Strapi API, repeat. It's great for exploring layouts, components, and flows without hand-wiring every detail upfront.

Fast POCs and trying new ideas
Need a demo by this afternoon? Lovable can scaffold the UI and basic logic while Strapi gives you real content types, draft/publish workflow, and an API you can trust.

Boilerplate handled
Forms, lists, detail pages, basic CRUD—Lovable generates the scaffolding so you can focus on the parts that actually need your expertise.

Content-first development
With Strapi defining the schema and relationships, you can point Lovable at the API and have it build around your real data shape instead of lorem ipsum.

Backend First vs Frontend First

When building an application that manages content, you have three main approaches:

Frontend first - Design your user interface, then build the backend to support it
Backend first - Set up your data and API, then build the frontend to display it
Both at once - Build frontend and backend simultaneously (this often leads to mismatches and extra work)

For this tutorial, we're starting with the backend using Strapi. Here's why:

Your data shapes your design - When you know what content you have, deciding what components and pages you need becomes easier
Catch errors early - TypeScript types generated from your API help prevent bugs before they happen
Work with real content - Test your app with actual data instead of fake placeholders
AI-friendly documentation - Strapi creates an OpenAPI spec that tells AI tools exactly how your API works
Teamwork made easy - Content editors can start adding material while you're building the frontend

Downsides to Consider

Planning required - You need to think through your data structure before you see anything visual
Risk of overthinking - It's tempting to add extra fields and connections you might not actually need
Delayed gratification - You won't see the interface come together until later

Even with these tradeoffs, starting with your data first (using Strapi) is the most practical approach.

What is OpenAPI and Why Should You Use It?

OpenAPI Specification (formerly Swagger) is a standard way to describe how your API works. Think of it as a detailed instruction manual that explains:

What endpoints are available and what they do (GET, POST, PUT, DELETE, etc.)
What parameters each endpoint accepts and what data types they expect
What data comes back in responses
How authentication works
What error messages you might encounter

Here's a simple example:

openapi: 3.0.0
paths:
  /api/articles:
    get:
      summary: Get all articles
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Article"
components:
  schemas:
    Article:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
        content:
          type: string

How OpenAPI Helps When Building with AI

OpenAPI provides a way to document your API that makes it a useful reference when prompting AI tools.

One limitation: Lovable has a context window, and if your specification.json file is too large, it may not fit. But you can still add it as an attachment.

Either way, it's a valuable reference worth including.

How it helps:

Stops the AI from guessing - The AI gets exact details about your API instead of making assumptions
Creates matching code - The AI generates TypeScript types that perfectly align with your backend
Makes accurate requests - The AI knows exactly which endpoints exist, what data they need, and what they return
Works as documentation - Both humans and AI can read and understand the specification
Catches mistakes - You can verify if your requests and responses match expectations

Generating OpenAPI Spec in Strapi

Strapi makes this simple with one command:

# Generate OpenAPI spec
npx strapi openapi generate

# This creates an specification.json file in your project root

Your browser does not support the video tag.

This file contains everything about your API—all your content types, components, and endpoints with their exact data structures. It's exactly what AI tools like Lovable.dev need to understand your backend.

Pro tip: I use the OpenAPI extension in VS Code to browse through the endpoints visually.

We'll explore how to use this specification in detail as we go through the tutorial.

Let's Start: Building a Frontend with Lovable.dev for Your Strapi Backend

Now we'll walk through building a frontend with Lovable.dev that connects to a Strapi backend.

Before We Begin

Let's check what you need:

✅ Do you have a Strapi project? (Don't worry if you don't—we'll set one up)
✅ Have you created content types in Strapi? (We'll use ours from our demo project)
✅ Can you access your Strapi API? (Either running locally or deployed online)

Step 1: Set Up Your Strapi Project

Don't have a Strapi project yet? No problem. We'll use a pre-built one from my Strapi Crash Course. If you want to learn how the backend was created, check out the video tutorial.

Since this guide focuses on the frontend, let's grab the ready-made backend project:

git clone https://github.com/PaulBratslavsky/pauls-strapi-crashcourse server

Change into the server folder:

cd server

Install all the dependencies using either yarn or npm:

yarn

npm install

Create a .env file in the root of the project. Copy the configuration from the .env.example file:

HOST=0.0.0.0
PORT=1337
APP_KEYS="toBeModified1,toBeModified2"
API_TOKEN_SALT=tobemodified
ADMIN_JWT_SECRET=tobemodified
TRANSFER_TOKEN_SALT=tobemodified
JWT_SECRET=tobemodified
ENCRYPTION_KEY=tobemodified

Replace each placeholder string with a unique value of your choice.

Seed the project with initial data:

yarn strapi import -f ./seed-data.tar.gz

When prompted, type y for Yes:

➜  server git:(main) yarn strapi import -f ./seed-data.tar.gz
yarn run v1.22.22
$ strapi import -f ./seed-data.tar.gz
? The import will delete your existing data! Are you sure you want to proceed? (y/N) y

Type y again:

[2025-10-24 10:09:33.381] warn: (Schema Integrity) admin::session does not exist on source
? There are differences in schema between the source and destination, and the data listed above will be lost. Are you sure you want
to continue? (y/N)

This is just a warning about a schema mismatch. It's safe to ignore.

Once the import finishes, you should see:

Starting import...
✔ entities: 55 transferred (size: 46.7 KB) (elapsed: 64 ms) (729.6 KB/s)
✔ assets: 8 transferred (size: 300 KB) (elapsed: 21 ms) (13.9 MB/s)
✔ links: 171 transferred (size: 32.2 KB) (elapsed: 11 ms) (2.9 MB/s)
✔ configuration: 47 transferred (size: 135.4 KB) (elapsed: 8 ms) (16.5 MB/s)
┌─────────────────────────────────────────┬───────┬───────────────┐
│ Type                                    │ Count │ Size          │
├─────────────────────────────────────────┼───────┼───────────────┤
│ entities                                │    55 │      46.7 KB  │
├─────────────────────────────────────────┼───────┼───────────────┤
│ -- api::article.article                 │    12 │ (    22.3 KB) │
├─────────────────────────────────────────┼───────┼───────────────┤
│ -- api::author.author                   │     2 │ (     534 B ) │
├─────────────────────────────────────────┼───────┼───────────────┤
│ -- api::global.global                   │     2 │ (     3.3 KB) │
├─────────────────────────────────────────┼───────┼───────────────┤
│ -- api::landing-page.landing-page       │     2 │ (     7.9 KB) │
├─────────────────────────────────────────┼───────┼───────────────┤
│ -- api::page.page                       │     4 │ (     1.6 KB) │
├─────────────────────────────────────────┼───────┼───────────────┤
│ -- api::tag.tag                         │     3 │ (     820 B ) │
├─────────────────────────────────────────┼───────┼───────────────┤
│ -- plugin::i18n.locale                  │     1 │ (     253 B ) │
├─────────────────────────────────────────┼───────┼───────────────┤
│ -- plugin::upload.file                  │     8 │ (     4.1 KB) │
├─────────────────────────────────────────┼───────┼───────────────┤
│ -- plugin::upload.folder                │     2 │ (     519 B ) │
├─────────────────────────────────────────┼───────┼───────────────┤
│ -- plugin::users-permissions.permission │    16 │ (     4.4 KB) │
├─────────────────────────────────────────┼───────┼───────────────┤
│ -- plugin::users-permissions.role       │     2 │ (     656 B ) │
├─────────────────────────────────────────┼───────┼───────────────┤
│ -- plugin::users-permissions.user       │     1 │ (     464 B ) │
├─────────────────────────────────────────┼───────┼───────────────┤
│ assets                                  │     8 │       300 KB  │
├─────────────────────────────────────────┼───────┼───────────────┤
│ -- .avif                                │     3 │ (   292.1 KB) │
├─────────────────────────────────────────┼───────┼───────────────┤
│ -- .svg                                 │     5 │ (     7.9 KB) │
├─────────────────────────────────────────┼───────┼───────────────┤
│ links                                   │   171 │      32.2 KB  │
├─────────────────────────────────────────┼───────┼───────────────┤
│ configuration                           │    47 │     135.4 KB  │
├─────────────────────────────────────────┼───────┼───────────────┤
│ Total                                   │   281 │     514.2 KB  │
└─────────────────────────────────────────┴───────┴───────────────┘
Import process has been completed successfully!
✨  Done in 15.24s.

Start your Strapi project:

yarn dev

Navigate to http://localhost:1337

You'll see the admin login screen. Create your first Admin user:

After creating your user, you'll see the Strapi dashboard:

Great! Now let's look at what content types we have available.

Here's how the articles content type works and how to get its data from the API:

Your browser does not support the video tag.

The Strapi backend has several content types in /server/src/api. For this tutorial, we'll build three main pages:

Landing Page - A flexible homepage built with customizable content blocks
Articles Listing Page - Shows all your published articles
Article Detail Page - Displays a single article with all its content

Here are the main content types:

Global Content Type (api::global.global):

title (Text)
description (Text)
banner (Component - layout.banner)
header (Component - layout.header)
footer (Component - layout.footer)

Article Content Type (api::article.article):

title (Text)
description (Text)
slug (UID based on title)
content (Rich Text)
featuredImage (Media - Single)
author (Relation to Author - manyToOne)
contentTags (Relation to Tag - oneToMany)
blocks (Dynamic Zone - for flexible content sections)
relatedArticles (Relation to Article - oneToMany)

Landing Page Content Type (api::landing-page.landing-page):

title (Text)
description (Text)
blocks (Dynamic Zone with components):
- Hero
- Section Heading
- Card Grid
- Content with Image
- Markdown
- Person Card
- FAQs
- Newsletter
- Featured Articles

Author Content Type (api::author.author):

name (Text)
bio (Text)
avatar (Media - Single)
articles (Relation to Article - oneToMany)

Tag Content Type (api::tag.tag):

name (Text)
slug (UID based on name)

Enabling Public API Access

The seed data we imported already has public access configured, so anyone can read your content without authentication. If you're building your own Strapi project from scratch, you'll need to enable this yourself.

Here's how:

Go to Settings → Users & Permissions Plugin → Roles → Public
Open each content type (Article, Landing Page, Author, Tag)
Check the boxes next to find and findOne
Click Save

The API Endpoints You'll Use

We'll work with four main endpoints:

Global Settings (Single Type): GET http://localhost:1337/api/global

Gets your site-wide settings like header navigation, footer, and banner. You'll use this data on every page.

Landing Page (Single Type): GET http://localhost:1337/api/landing-page

Gets your homepage content with all its customizable blocks.

Articles List (Collection Type): GET http://localhost:1337/api/articles

Gets all your published articles with their authors, tags, and images.

Single Article (Collection Type): GET http://localhost:1337/api/articles?filters[slug][$eq]=why-java-script-is-still-the-most-popular-programming-language

Gets one specific article by its slug (the URL-friendly version of the title).

Page By Slug (Collection Type): GET http://localhost:1337/api/pages?filters[slug][$eq]=about

Gets one specific page by its slug. Pages use the same block system as the landing page, allowing you to create dynamic content pages like About, Contact, etc.

Things to note:

The filters[slug][$eq] part is how Strapi filters data by specific field values
All URLs use port 1337 (Strapi's default)
You can test these URLs in your browser or with tools like Postman before building your frontend

Step 2: Generate Your OpenAPI Specification

Now that your content types are set up, let's create the OpenAPI specification file:

# In your Strapi project directory
yarn strapi openapi generate

This creates a specification.json file with all your API details. Want to browse it visually? Install the OpenAPI VS Code extension.

Your browser does not support the video tag.

Step 3: Deploy Strapi (Optional but Recommended)

While you can keep Strapi running locally, deploying it makes working with Lovable.dev much easier. We'll use Strapi Cloud, which has a free tier.

Want to keep Strapi running on your computer? You can use ngrok to create a temporary public URL:

# Install ngrok first from https://ngrok.com/download
# Then run this command to expose your local Strapi instance
ngrok http 1337

You'll get a public URL (like https://abc123.ngrok.io) that Lovable.dev can use to reach your local Strapi.

But I'll show you how to deploy to Strapi Cloud for free. You can choose which path to take.

Deploy to Strapi Cloud (Recommended)

For a more permanent solution, deploy to Strapi Cloud:

Navigate to Strapi Cloud and create an account if you don't already have one:

In your dashboard, click the create project button:

Choose the Free Plan:

Select your account and project:

Name your Cloud project and select your region.

I'll call mine lovable-example and pick US East region:

Click Create Project to deploy:

Your browser does not support the video tag.

Once deployment finishes, navigate to your Strapi instance and create your first admin user. Notice we don't have any data yet—we'll add it using the transfer command.

First, create a Transfer Token in Strapi.

Navigate to Setting => Transfer Token and click Add new transfer token:

Create your token:

Name: initial transfer
Token duration: 7 days
Token type: full access

Now use the CLI to transfer your data to Strapi Cloud.

Your browser does not support the video tag.

Run this command in your local server directory:

yarn strapi transfer

When prompted, enter your project URL (in my case it was https://inviting-cheese-ce66d3b9e0.strapiapp.com/admin). Make sure to include the /admin path.

Enter your transfer token, then type y to confirm:

➜  server git:(main) yarn strapi transfer
yarn run v1.22.22
$ strapi transfer
ℹ️  Data transfer documentation: https://docs.strapi.io/dev-docs/data-management/transfer
ℹ️  No transfer configuration found in environment variables
   → Add STRAPI_TRANSFER_URL and STRAPI_TRANSFER_TOKEN environment variables to make the transfer process faster for future runs
? Choose transfer direction: Push local data to remote Strapi
? Enter the URL of the remote Strapi instance to send data to:
https://inviting-cheese-ce66d3b9e0.strapiapp.com/admin
? Enter the transfer token for the remote Strapi destination:
[hidden]
? The transfer will delete existing data from the remote Strapi! Are
 you sure you want to proceed? Yes
Starting transfer...
✔ entities: 58 transferred (size: 48.1 KB) (elapsed: 4207 ms) (11.4 KB/s)
✔ assets: 8 transferred (size: 300 KB) (elapsed: 1964 ms) (152.7 KB/s)
✔ links: 174 transferred (size: 32.6 KB) (elapsed: 1987 ms) (16.4 KB/s)
✔ configuration: 48 transferred (size: 141.8 KB) (elapsed: 1318 ms) (107.6 KB/s)
┌─────────────────────────────────────────┬───────┬───────────────┐
│ Type                                    │ Count │ Size          │
├─────────────────────────────────────────┼───────┼───────────────┤
│ entities                                │    58 │      48.1 KB  │
├─────────────────────────────────────────┼───────┼───────────────┤
│ -- admin::session                       │     3 │ (     1.4 KB) │
├─────────────────────────────────────────┼───────┼───────────────┤
│ -- api::article.article                 │    12 │ (    22.3 KB) │
├─────────────────────────────────────────┼───────┼───────────────┤
│ -- api::author.author                   │     2 │ (     534 B ) │
├─────────────────────────────────────────┼───────┼───────────────┤
│ -- api::global.global                   │     2 │ (     3.3 KB) │
├─────────────────────────────────────────┼───────┼───────────────┤
│ -- api::landing-page.landing-page       │     2 │ (     7.8 KB) │
├─────────────────────────────────────────┼───────┼───────────────┤
│ -- api::page.page                       │     4 │ (     1.6 KB) │
├─────────────────────────────────────────┼───────┼───────────────┤
│ -- api::tag.tag                         │     3 │ (     820 B ) │
├─────────────────────────────────────────┼───────┼───────────────┤
│ -- plugin::i18n.locale                  │     1 │ (     253 B ) │
├─────────────────────────────────────────┼───────┼───────────────┤
│ -- plugin::upload.file                  │     8 │ (     4.1 KB) │
├─────────────────────────────────────────┼───────┼───────────────┤
│ -- plugin::upload.folder                │     2 │ (     519 B ) │
├─────────────────────────────────────────┼───────┼───────────────┤
│ -- plugin::users-permissions.permission │    16 │ (     4.4 KB) │
├─────────────────────────────────────────┼───────┼───────────────┤
│ -- plugin::users-permissions.role       │     2 │ (     656 B ) │
├─────────────────────────────────────────┼───────┼───────────────┤
│ -- plugin::users-permissions.user       │     1 │ (     464 B ) │
├─────────────────────────────────────────┼───────┼───────────────┤
│ assets                                  │     8 │       300 KB  │
├─────────────────────────────────────────┼───────┼───────────────┤
│ -- .avif                                │     3 │ (   292.1 KB) │
├─────────────────────────────────────────┼───────┼───────────────┤
│ -- .svg                                 │     5 │ (     7.9 KB) │
├─────────────────────────────────────────┼───────┼───────────────┤
│ links                                   │   174 │      32.6 KB  │
├─────────────────────────────────────────┼───────┼───────────────┤
│ configuration                           │    48 │     141.8 KB  │
├─────────────────────────────────────────┼───────┼───────────────┤
│ Total                                   │   288 │     522.5 KB  │
└─────────────────────────────────────────┴───────┴───────────────┘
Transfer process has been completed successfully!
✨  Done in 76.51s.
➜  server git:(main)

Your data should now appear in your Strapi Cloud instance. Navigate to the api/articles endpoint to verify:

Example: https://inviting-cheese-ce66d3b9e0.strapiapp.com/api/articles

Your API is now live and accessible! Whether you used ngrok or Strapi Cloud, you're ready to build the frontend.

Why did we set up the backend first? Because now Lovable can build your frontend based on real API responses and actual data structures. This means more accurate code and fewer errors.

Understanding Prompting Strategies for Lovable.dev

I'm not a prompting expert, and each platform has its own best practices. Mostly, you should experiment to see what gives you the best results.

While building my project, I tried different prompts—some worked better than others. I'll discuss this more later.

Here's a great guide from Lovable.

Part 1: One-Shot Attempt

You might think: stick all the requirements into one prompt—done!

But unlike a human who can read between the lines, AI can't. You need to provide lots of context, and even then it may not be enough.

I tried one-shot prompting but don't recommend it. We'll still try it for learning purposes, but none of my one-shot attempts produced a working version without follow-up prompts.

However, the better your initial prompt, the fewer follow-ups you'll need.

Why do people try the one-shot approach?

Because it's tempting:

✅ Fast initial output (looks productive immediately)
✅ All requirements in one place
✅ Feels efficient

But in reality, it creates more problems than it solves:

❌ Generates 30+ files at once (impossible to review thoroughly)
❌ AI loses track of requirements and makes assumptions
❌ Field-name errors get buried in large codebases
❌ Hard to test incrementally—bugs compound
❌ Difficult to isolate what went wrong
❌ Large commits make version control messy
❌ Debugging takes longer than building incrementally

We'll walk through BOTH approaches so you can try them yourself.

Part 2: Iterative Approach (Recommended)

After experiencing the limitations of one-shot prompting, I tried building with small, focused prompts:

Start Small - Project setup → API layer → One feature at a time
Use Knowledge Files - Set context once, reference forever
Test After Each Step - Validate before moving forward
Build Incrementally - Layout → Landing page → Articles → Search → Polish
Review and Test - Check each change, test and refine before continuing

Why Iterative Prompting Wins:

Review code as it's created (catch errors early)
Easy to spot which prompt caused issues
Test each feature independently
Give targeted feedback
Roll back single features, not entire projects
Cleaner code that's easier to maintain
Better version control with focused commits

For a proof-of-concept to show stakeholders, one-shot might work. But for production or anything substantial, incremental prompting is the way to go.

For this post, I want to use the Strapi Client SDK. Since Lovable isn't familiar with it, we'll pass as much context as possible directly in the prompt.

We can also create a knowledge file with that context—we'll try that later with incremental prompting.

Understanding the Strapi Client SDK

Before we write our prompt, let's discuss the @strapi/client SDK—an official package that simplifies working with Strapi APIs.

It provides clean methods for API requests, filtering, pagination, and loading related content.

We'll include this SDK in our Lovable prompt for an important reason: it's relatively new.

Since Lovable's AI may not be familiar with its syntax and implementation patterns, we need to provide complete context.

This is a perfect example of when to be explicit in your prompts—give the AI concrete code examples for tools it might not know well, rather than letting it guess or hallucinate the API.

Basic setup example:

import { strapi } from '@strapi/client';

// Initialize the Strapi client
const client = strapi({
  baseURL: 'https://inviting-cheese-ce66d3b9e0.strapiapp.com',
  // No authentication needed for public endpoints
});

// 1. Fetch Global settings (single type)
const globalData = await client.single('global').find();
// Returns: { data: { id, documentId, attributes: { title, description, banner, header, footer } } }

// 2. Fetch Landing Page (single type)
const landingPage = await client.single('landing-page').find();
// Returns: { data: { id, documentId, attributes: { title, description, blocks: [...] } } }

// 3. Fetch all Articles with pagination
const articles = await client.collection('articles').find({
  pagination: { page: 1, pageSize: 6 }
});
// Returns: { data: [...], meta: { pagination: { page, pageSize, pageCount, total } } }

// 4. Search articles by title using filters (case-insensitive)
const searchResults = await client.collection('articles').find({
  filters: {
    title: { $containsi: 'javascript' }
  },
// Common Strapi v5 filter operators:
// $eq: equals
// $ne: not equals
// $containsi: contains (case-insensitive)
// $startsWith: starts with
// $endsWith: ends with

// 5. Fetch single article by slug
const article = await client.collection('articles').find({
  filters: {
    slug: {
      $eq: 'why-java-script-is-still-the-most-popular-programming-language'
    }
  }
});
// Returns: { data: [{ id, documentId, attributes: {...} }], meta: {} }
// Note: Returns array with single item - extract first item: article.data[0]

Important Note About Population:

In our Strapi backend, we're already populating all content via a route middleware, so you don't need to add populate parameters in your frontend API calls. The only additional params you'll need are:

filter - To filter articles by slug or other fields
pagination - To implement pagination

Example of our route middleware:

Here's how we configured the articles route to automatically populate all relations:

// server/src/api/article/routes/article.ts
import { factories } from "@strapi/strapi";

export default factories.createCoreRouter("api::article.article", {
  config: {
    find: {
      middlewares: ["api::article.article-populate"],
    },
  },
});

The populate middleware:

// server/src/api/article/middlewares/article-populate.ts
import type { Core } from "@strapi/strapi";

const populate = {
  featuredImage: {
    fields: ["url", "alternativeText"],
  },
  author: {
    populate: {
      image: {
        fields: ["url", "alternativeText"],
      },
      articles: {
        fields: ["documentId", "title"],
      },
    },
  },
  contentTags: true,
  blocks: {
    on: {
      "blocks.hero": {
        populate: {
          links: true,
          image: { fields: ["alternativeText", "url"] },
        },
      },
      "blocks.section-heading": true,
      "blocks.card-grid": { populate: { cards: true } },
      "blocks.content-with-image": {
        populate: { link: true, image: { fields: ["alternativeText", "url"] } },
      },
      "blocks.markdown": true,
      "blocks.person-card": {
        populate: { image: { fields: ["alternativeText", "url"] } },
      },
      "blocks.faqs": { populate: { faq: true } },
      "blocks.newsletter": true,
    },
  },
  relatedArticles: {
    populate: {
      featuredImage: { fields: ["alternativeText", "url"] },
      author: true,
    },
  },
};

export default (config, { strapi }: { strapi: Core.Strapi }) => {
  return async (ctx, next) => {
    ctx.query.populate = populate;
    await next();
  };
};

This means when you call /api/articles, all relations, images, and dynamic zone blocks are automatically populated—you don't need to add ?populate=deep or specify individual fields.

While we'll include this SDK in our prompt to Lovable, you could also use a simple fetch wrapper or libraries like Axios. The SDK is recommended but not required.

The Complete Lovable.dev Prompt

Here is the complete prompt you can paste into Lovable.dev.

I was able to generate this whole project with one prompt. but it took few tries.

Your browser does not support the video tag.

But in general you would use incrimental prompting when building your project.

It's massive, but my goal was to give as much context to Lovable as possible using the one-shot approach.

Why This Prompt Ended Up Working Best For Me

After multiple iterations and testing different approaches, this prompt structure worked best. Here's how each section contributed:

Opening Line (Role Definition)

You are a senior frontend developer experienced with TypeScript, React, and building dynamic content-driven websites that consume Strapi RESTful APIs.

Sets the expertise level and domain.

Task

Single, clear objective: "Build a blog platform frontend that consumes a Strapi v5 backend API."

The "v5" specification matters—it prevents the AI from using outdated Strapi v3/v4 patterns.

Critical Rule: Type-First Development

This became the most important section. The three-step rule forces the AI to:

Review actual API response examples first
Generate TypeScript interfaces matching EXACT field names
NOT assume or guess anything

By being explicit with "MUST" and "DO NOT assume," I tried to eliminate guesswork, but it didn't eliminate it completely. Since LLMs generate statistically likely responses, they're not deterministic by nature.

Backend Configuration

Provides the exact API URL and Strapi v5 response format. The note about "Direct field access (no .attributes nesting)" is crucial—Strapi v5 changed this from v3/v4.

Tech Stack

Lists every library explicitly. No room for the AI to substitute alternatives or use outdated versions.

API Endpoints & Real Response Examples

This is where I went all-in on context. I included 5 complete JSON responses from actual API calls:

Global Settings (155 lines)
Landing Page with 9 block types (160 lines)
Articles (62 lines)
Paginated Articles (50 lines)
Single Page by Slug (38 lines)

Not sanitized examples—the real data with IDs, timestamps, nulls, nested objects, everything.

Why this mattered: Instead of the AI guessing field names like fullName vs name or image.url vs featuredImage.url, it could see the exact structure. This alone eliminated most potential errors.

Implementation Requirements

Six subsections covering Setup, API Layer, Hooks, Types, Pages, and Development Standards.

The key decision: I provided complete SDK code for @strapi/client because it's new and AI doesn't know it well. But I only provided requirements for React Query because that's standard and AI already knows it.

This balance lets the AI use its strengths while constraining its weaknesses with unfamiliar tools.

Project Structure

A visual file tree showing exactly where code should go. This prevents the AI from creating utils/api/strapi/client.ts when you wanted lib/strapi.ts.

Key Implementation Notes

Shows exact data access patterns:

article.title
article.featuredImage.url
article.author.fullName

Specifications & Acceptance Criteria

Five features with clear "done" criteria and checkboxes. Not vague like "build an articles page" but specific like "articles must display in 3/2/1 column grid, search must debounce 300ms, pagination must update URL."

Each criterion is testable and objective.

Implementation TODO Checklist

47 tasks broken down across 8 sequential phases: Foundation → API Layer → Hooks → Layout → Components → Pages → Routing → Polish.

Each task is specific and actionable (like "Create components/Header.tsx" rather than "build the header").

Verification Checkpoints

Checkpoints after phases 1-3, 4, 5, 6-7, and final verification. Encourages incremental testing—catch errors early before they compound.

Important Reminders

Seven key points repeated at the end (Strapi v5 patterns, exact field names, no populate needed, etc.).

Repetition matters because AI context windows can "forget" early instructions. Repeating critical constraints at the end keeps them active.

What Made This Work for Me

Here's what I learned through trial and error:

The Human-Readable Principle

I wrote the prompt as if I were handing it to another developer, not just an AI. This meant:

Clear, sequential instructions
Specific examples instead of vague descriptions
Visual structures (file trees, JSON responses)
Testable criteria ("should display in 3-column grid" not "make it look good")

The Checklist Experiment

Adding the TODO checklist was an experiment. I wasn't sure if or how Lovable would use it.

But I included it for a few reasons:

It forced me to think through the build order (what depends on what?)
If I handed this to a developer, they'd have a clear roadmap
Even if the AI didn't check boxes, the structure might still guide the sequence
If debugging was needed, I'd know which phase broke

Did it work? Hard to say definitively, but the code did appear in a logical order—foundation first, then data layer, then UI components, then pages. The incremental build felt more organized than previous attempts.

Finding the Balance

After trying prompts that were too vague ("build a blog"), too detailed (specifying every line), and everything in between, this version hit a workable middle ground:

Detailed where it matters (real API responses, unfamiliar SDKs)
General where AI excels (standard React patterns, component structure)
Specific about constraints (Strapi v5 patterns, field names)
Flexible on implementation details (let AI handle styling, component organization)

Your Mileage May Vary

This structure worked well for my project, but it's not gospel. Depending on your backend complexity, team preferences, and what you're building, you might need more or less detail. The key insight: show the AI your actual data structure, and be specific about constraints that prevent common mistakes.

The Context Problem with AI Tools

AI tools like Lovable.dev are powerful, but they have one big limitation: they don't know anything about YOUR specific project unless you tell them.

What the AI knows:

✅ General React patterns
✅ Standard TypeScript
✅ Popular libraries like TanStack Query
✅ How REST APIs usually work

What the AI doesn't know:

❌ Your Strapi backend's URL
❌ Your custom data formatting
❌ Your exact content structure
❌ That you're using Strapi Client SDK
❌ Your specific filter syntax

What Happens Without Good Context

Say "build a blog with Strapi" without details, and the AI will:

Make up endpoints - Creates /api/posts when yours is /api/articles
Access data wrong - Tries article.attributes.title when yours is article.title
Use wrong syntax - Tries unsupported search parameters
Miss features - Doesn't know about your dynamic blocks
Create fake data - Builds a UI that looks good but doesn't connect to your real backend

This leads to additional debugging and prompting to fix what the AI guessed wrong. Remember, you're paying for each prompt you make.

The Strapi SDK: Why We Gave You the Code

Notice how we provided complete SDK code but not React Query code? Here's why:

Strapi-Specific (AI needs this):

// This is Strapi-specific - AI needs the exact syntax
const client = strapiClient({
  baseURL: "https://your-strapi.strapiapp.com",
});

// How to use client.single() vs client.collection()
const response = await client.single("global").find();
const articles = await client.collection("articles").find({
  filters: { slug: { $eq: slug } },
});

Standard React (AI knows this):

// This is standard React Query - AI knows this pattern
const { data, isLoading } = useQuery({
  queryKey: ["articles"],
  queryFn: getArticles,
});

Why we provided the Strapi code:

Library-specific - AI needs to know exactly how @strapi/client works
Unusual syntax - Filter operators like $containsi aren't obvious
Your backend is unique - Your URL, endpoints, and data structure are specific to you
Custom formatting - Your middleware formats data differently than standard Strapi

Finding the Right Balance

Our prompt balances specific details with general instructions:

Be Specific About (Strapi stuff):

✅ Complete SDK code
✅ Your actual API URLs
✅ Real response examples
✅ Filter syntax rules
✅ Content type structure
✅ Component names

Be General About (React stuff):

✅ "Create React Query hooks" (let AI decide how)
✅ "Responsive grid" (AI knows Tailwind)
✅ "Loading skeletons" (AI knows patterns)
✅ "Debounced search" (AI knows how)

This gives the AI:

Facts about your unique backend
Freedom to use React best practices it already knows

Why Real API Responses Matter

Including real JSON responses from the API was crucial. Even though I shared the endpoints, Lovable didn't consistently call them to fetch the actual data:

{
  "data": [
    {
      "id": 12,
      "title": "Article Title", // ← Strapi v5 structure!
      "author": {
        // ← Direct object (no .attributes)
        "fullName": "Jane Doe"
      },
      "featuredImage": {
        // ← Direct media object
        "url": "https://..."
      }
    }
  ]
}

This shows Lovable:

Exact field names - fullName not name, featuredImage not coverImage
Data structure - Strapi v5 format, not old v3/v4 data.attributes.title nesting
Null handling - Which fields might be null (like alternativeText)
Array structures - How relations like contentTags are returned

Without these examples, the AI might generate code for older Strapi versions (v3/v4 with nested .attributes), which wouldn't work with Strapi v5.

The Cost of Vague Prompts

Let's compare:

Vague Prompt:

"Build a blog frontend for my Strapi backend"

Result:

Generic blog with fake data
Wrong API structure assumptions
Hours of manual debugging
Frustration and re-work

Specific Prompt (What We Created):

Includes: Backend URL, SDK code, filter syntax, real responses, content types, block components, Strapi v5 data structure

Result:

Working blog connected to real Strapi
Correct data access patterns
Minimal debugging needed
Fast iteration on features

Limitations of the One-Shot Approach

While our checkpoint-based one-shot prompt seemed better than traditional one-shot prompting, I still don't think it's the best approach.

Issue #1: Overwhelming Scope
Asking the AI to build an entire blog platform in one go led to:

Over 30 files created at once
Difficult to review all the code generated
Hard to spot subtle bugs buried in large commits
Challenging to provide focused feedback

Issue #2: Context Overload
The comprehensive prompt, while detailed, tried to cover:

9 different block components
3 major pages
API utilities and hooks
Global layout and navigation
All in a single conversation thread

This caused the AI to sometimes lose track of specific requirements or make assumptions despite our safeguards.

Issue #3: Testing Bottlenecks
When everything is generated at once:

You can't test incrementally
Bugs compound on top of each other
Rolling back means losing hours of work
Hard to isolate which prompt caused which issue

Issue #4: Knowledge File Not Utilized
In this one-shot approach we didn't leverage Lovable's Knowledge file feature, which means:

Context isn't persisted across sessions
Every new prompt may require full context again
AI memory limitations become problematic
Can't build on previous validated work effectively

The Iterative Approach

We tried one-shot prompting, now let's try the iterative approach.

Here's what Lovable recommends (and what we should have done from the start):

Lovable Best Practices for Building Production Apps

1. Start with a Knowledge File

Why it matters: The Knowledge file is your project's brain. It gets sent with every prompt and helps the AI understand the full context without repeating yourself.

What to include:

# Project Knowledge File

## Product Vision

{{One-sentence goal}} - Build a blog platform that consumes Strapi v5 CMS

## Core Features

- Dynamic landing page with 9 block types
- Articles listing with search and pagination
- Single article view with related articles
- Responsive navigation and footer

## Tech Stack

- React 18 + TypeScript (strict mode)
- Tailwind CSS + shadcn/ui
- React Router v6
- TanStack Query v5
- Strapi Client SDK (@strapi/client)

## Backend Context

- Strapi v5 backend at: https://inviting-cheese-ce66d3b9e0.strapiapp.com
- Direct field access (NO .attributes nesting)
- Auto-populated relations via middleware
- Filter syntax: { filters: { field: { $eq: value } } }

## Data Model

[Include your actual API field names from Phase 1 discovery]

- Article: title, description, slug, content, featuredImage, author, contentTags, blocks, relatedArticles
- Author: fullName (NOT name), bio, image
- Landing Page Blocks: section-heading (heading, text NOT subheading), content-with-image (links NOT buttons, reversed NOT imagePosition), etc.

## Design System

- Mobile-first responsive
- Tailwind config: [colors, fonts, spacing]
- shadcn/ui components: Button, Card, Input, etc.

## Coding Standards

- TypeScript strict mode
- ESLint + Prettier
- Component pattern: function components with hooks
- File structure: /components, /pages, /hooks, /lib, /types

## Non-Goals (This Version)

- User authentication
- Comments system
- Article editing (read-only frontend)

You can auto-generate a Knowledge file by asking:

Generate a knowledge file for my project based on the features already implemented.

2. Break Work into Small, Testable Chunks

Instead of "build everything," break your project into milestones:

Milestone 0: Foundation

Project setup and dependencies
API utilities and types (verified against actual API)

Milestone 1: Core Data Layer

Strapi client configuration
React Query hooks for each endpoint
TypeScript interfaces (with verification)

Milestone 2: Layout & Navigation

Global layout component
Header with navigation
Footer
Mobile menu

Milestone 3: Landing Page

BlockRenderer infrastructure
Implement 2-3 block components
Test rendering

Milestone 4: Articles Listing

Article card component
Grid layout
Basic pagination

Milestone 5: Article Detail

Single article page
Markdown rendering
Related articles

Milestone 6: Search & Filters

Search with debouncing
Pagination controls
Loading states

Milestone 7: Polish

Error boundaries
404 pages
Accessibility audit
Performance optimization

3. Use Chat Mode for Planning (60-70% of Your Time)

When to use Chat Mode:

After 2-3 failed "Try to Fix" attempts
When debugging complex logic
When planning new features
BEFORE implementing anything complex

Chat Mode Workflow:

You: "I need to implement search functionality for articles.
     What's the best approach using React Query and the Strapi Client SDK?"

AI: [Suggests 3 approaches]

You: "I like option 2. Can you create a detailed implementation plan
     with file structure and key code snippets?"

AI: [Creates plan]

You: "This looks good. Implement the plan."

Pro tip: Use Chat Mode to investigate without writing code:

"Investigate but don't write code yet. Show me what needs to change."

4. Write Clear, Scoped Prompts

Bad Prompt (too broad):

Build the articles page with search, pagination, and filters.

Good Prompt (specific and scoped):

On page /articles, implement article listing with these requirements:

SCOPE:
- Display articles in a responsive grid (3 cols desktop, 2 tablet, 1 mobile)
- Use the useArticles() hook from /hooks/useStrapi.ts
- Each article card shows: title, description, featuredImage, author.fullName, contentTags

CONSTRAINTS:
- Do not modify /lib/strapi.ts or /hooks/useStrapi.ts
- Use ArticleCard component (to be created in /components/ArticleCard.tsx)
- Follow Tailwind spacing from design system
- Use loading skeleton, not spinner

ACCEPTANCE TESTS:
- Articles load and display correctly
- Grid is responsive across breakpoints
- Loading state shows skeleton cards
- Error state shows user-friendly message

DELIVERABLES:
- /pages/ArticlesPage.tsx
- /components/ArticleCard.tsx
- Update /App.tsx routing if needed

5. Add Guardrails to Every Prompt

Tell the AI what NOT to touch:

CONSTRAINTS:
- Do not modify /lib/strapi.ts (API layer is stable)
- Do not change /types/strapi.ts (types are verified)
- Do not edit /components/Layout.tsx (working correctly)
- Keep existing ArticleCard API - only modify internals

6. Define Roles Clearly (If Applicable)

If your app has multiple user roles, always specify:

As an Admin, I want to see an "Edit" button on each article card.
As a Guest, I should only see the "Read More" link.

Please isolate this feature and add role-based conditional rendering.

7. The Power of Repetition

Important note: The AI's memory can be limited. Don't assume it remembers your Knowledge file perfectly.

Repeat critical instructions in prompts:

Reminder: We're using Strapi v5 with direct field access (article.title, NOT article.attributes.title).
Reminder: author field is "fullName" not "name"
Reminder: blocks.section-heading uses "text" not "subheading"

8. Validate After Each Step

After the AI generates code:

Review the changes - Use Lovable's diff view
Test in preview - Does it work?
Check console - Any errors?
Pin the version if it works

If something breaks:

Switch to Chat Mode
Paste error screenshot
Say: "Investigate without breaking other features. If needed, revert to last working version."

9. Use Visual Edit for Quick Tweaks

For simple changes (text, colors, spacing), use Visual Edit instead of prompts:

It's free (no credits)
Instant changes
Easy to undo
Perfect for minor UI adjustments

10. Pin Stable Versions

After every working feature:

Pin it in version history
This creates a fallback point
Easy to compare: "What changed between T-5 and T-0?"

The Modular Multi-Prompt Strategy

Based on Lovable's best practices, here's the recommended approach for building the Strapi blog:

Phase 0: Foundation & Discovery

Prompt 0.1: Generate Knowledge File

Generate a knowledge file for a blog platform project that:
- Consumes Strapi v5 backend at https://inviting-cheese-ce66d3b9e0.strapiapp.com
- Uses React, TypeScript, Tailwind CSS, React Router, TanStack Query
- Has landing page, articles listing, and article detail pages
- Implements 9 dynamic zone block components

Include: product vision, tech stack, data model, coding standards, and non-goals.

Prompt 0.2: Setup Project & Dependencies

CONTEXT: Starting a new Vite + React + TypeScript project

TASK: Initialize project with these dependencies:
- @strapi/client
- @tanstack/react-query
- react-router-dom
- tailwindcss
- Include shadcn/ui setup

DELIVERABLES:
- package.json with correct versions
- vite.config.ts
- tailwind.config.js
- tsconfig.json with strict mode
- Basic folder structure: /components, /pages, /hooks, /lib, /types

Do not create any components yet.

Phase 1: API Discovery & Type Definition

Prompt 1.1: Fetch & Document API Structure

ROLE: You are a senior TypeScript developer

TASK: API Discovery for Strapi v5 backend

STEP 1: Fetch these endpoints and save responses:
- https://inviting-cheese-ce66d3b9e0.strapiapp.com/api/global
- https://inviting-cheese-ce66d3b9e0.strapiapp.com/api/landing-page
- https://inviting-cheese-ce66d3b9e0.strapiapp.com/api/articles?pagination[page]=1&pagination[pageSize]=6

STEP 2: Create a field name reference document listing:
- All field names by content type
- Nested object structures
- Note any common naming pitfalls (e.g., "text" not "subheading", "fullName" not "name")

STEP 3: Present findings and WAIT for confirmation

DO NOT create TypeScript interfaces yet.

Prompt 1.2: Create Verified TypeScript Types

CONTEXT: Field names verified in previous step

TASK: Create TypeScript interfaces in /types/strapi.ts

REQUIREMENTS:
- Use EXACT field names from API responses
- Add JSDoc comments with field source
- Include: Article, Author, Tag, Global, LandingPage, and all 9 block type interfaces
- Create verification table for each interface

DELIVERABLES:
- /types/strapi.ts
- Verification tables for all interfaces

WAIT for confirmation before proceeding.

Phase 2: API Layer

Prompt 2.1: Strapi Client Configuration

TASK: Setup Strapi Client SDK in /lib/strapi.ts

SPEC:
- Import strapiClient from '@strapi/client'
- Configure baseURL: https://inviting-cheese-ce66d3b9e0.strapiapp.com
- Create utility functions:
  - getGlobal() - fetch global settings
  - getLandingPage() - fetch landing page
  - getArticles(params?) - fetch articles with optional search, page, pageSize
  - getArticleBySlug(slug) - fetch single article

CONSTRAINTS:
- Do not add populate params (auto-populated by backend)
- Use Strapi v5 filter syntax: { filters: { field: { $eq: value } } }
- Return clean data (unwrap response.data)

DELIVERABLES:
- /lib/strapi.ts with 4 functions
- Include inline comments explaining filter syntax

Prompt 2.2: React Query Hooks

TASK: Create React Query hooks in /hooks/useStrapi.ts

REQUIREMENTS:
- Wrap each /lib/strapi.ts function with useQuery or useMutation
- Use appropriate query keys
- Handle loading, error, and success states
- Enable proper caching

FUNCTIONS TO CREATE:
- useGlobal()
- useLandingPage()
- useArticles(search?, page?)
- useArticle(slug)

CONSTRAINTS:
- Do not modify /lib/strapi.ts
- Do not modify /types/strapi.ts

DELIVERABLES:
- /hooks/useStrapi.ts
- Setup QueryClientProvider in /App.tsx if not already done

Phase 3: Layout & Navigation

Prompt 3.1: Global Layout Structure

TASK: Create global layout in /components/Layout.tsx

SCOPE:
- Use useGlobal() hook to fetch header and footer data
- Create Header component with navigation
- Create Footer component
- Add mobile hamburger menu

CONSTRAINTS:
- Do not implement banner yet (next prompt)
- Use shadcn/ui components where appropriate
- Mobile-first responsive design

DELIVERABLES:
- /components/Layout.tsx
- /components/Header.tsx
- /components/Footer.tsx

ACCEPTANCE TESTS:
- Header renders navigation links from API
- Footer renders footer data from API
- Mobile menu toggles correctly
- Layout wraps all pages

Prompt 3.2: Add Dismissible Banner

TASK: Add dismissible banner to /components/Layout.tsx

REQUIREMENTS:
- Render global.banner data
- Add dismiss functionality (localStorage)
- Show banner only if not dismissed
- Style with Tailwind (top of page, full width)

CONSTRAINTS:
- Do not modify Header or Footer components
- Use existing Layout structure

ACCEPTANCE TEST:
- Banner shows on first visit
- Dismiss button hides banner
- Banner stays hidden after refresh

Phase 4: Landing Page (Iterative Block Implementation)

Prompt 4.1: Landing Page Foundation

TASK: Create landing page structure at /pages/LandingPage.tsx

REQUIREMENTS:
- Use useLandingPage() hook
- Render page title and description
- Create BlockRenderer component skeleton
- Map __component to block components

CONSTRAINTS:
- Do not implement actual block components yet
- Create placeholder components for each block type
- Focus on the rendering infrastructure

DELIVERABLES:
- /pages/LandingPage.tsx
- /components/BlockRenderer.tsx (with placeholders)

Prompt 4.2: Implement Hero Block

TASK: Implement HeroBlock component at /components/blocks/HeroBlock.tsx

SPEC (from API response):
- heading: string
- text: string
- links: array of {label, url, variant}
- image: {url, alternativeText}

DESIGN:
- Full-width hero section
- Background image with overlay
- Centered content
- CTA buttons in flex row

CONSTRAINTS:
- Do not modify other block components
- Use verified TypeScript interface from /types/strapi.ts
- Reference API field names in comments

ACCEPTANCE TEST:
- Hero renders with actual data from landing page
- Image loads with correct alt text
- CTA buttons link to correct URLs

Prompt 4.3: Implement Section Heading Block

TASK: Implement SectionHeadingBlock at /components/blocks/SectionHeadingBlock.tsx

CRITICAL: Use exact API field names:
- block.heading (NOT block.title)
- block.text (NOT block.subheading)

DESIGN:
- Centered text section
- Large heading + smaller descriptive text
- Responsive typography

CONSTRAINTS:
- Do not modify other components
- Use Tailwind typography classes

DELIVERABLES:
- /components/blocks/SectionHeadingBlock.tsx

VERIFICATION:
Confirm you're using block.heading and block.text (not title/subheading)

Continue this pattern for remaining blocks: CardGrid, ContentWithImage, Markdown, PersonCard, FAQs, Newsletter, FeaturedArticles

Phase 5: Articles Listing

Prompt 5.1: Article Card Component

TASK: Create reusable ArticleCard component

SPEC:
- Props: article (Article type)
- Display: featuredImage, title, description, author.fullName, contentTags
- Click navigates to /articles/:slug

DESIGN:
- Card with image on top
- Hover effect
- Tag pills
- Author attribution

CONSTRAINTS:
- Do not create ArticlesPage yet
- Use verified Article interface
- Add "Read More" link

DELIVERABLES:
- /components/ArticleCard.tsx

Prompt 5.2: Articles Listing Page

TASK: Create /pages/ArticlesPage.tsx

REQUIREMENTS:
- Use useArticles() hook
- Render ArticleCard grid (3 cols desktop, 2 tablet, 1 mobile)
- Add loading skeleton
- Add empty state

CONSTRAINTS:
- Do not add search or pagination yet (next prompts)
- Use ArticleCard component (don't modify it)

DELIVERABLES:
- /pages/ArticlesPage.tsx
- Update /App.tsx routing

Prompt 5.3: Add Search Functionality

TASK: Add search to /pages/ArticlesPage.tsx

REQUIREMENTS:
- Search input with 300ms debounce
- Pass search query to useArticles hook
- Show "No results" state
- Clear search button

CONSTRAINTS:
- Do not modify ArticleCard component
- Do not modify useArticles hook (it already supports search param)

ACCEPTANCE TESTS:
- Typing searches articles by title/description
- Debouncing prevents excessive API calls
- Results update correctly

Prompt 5.4: Add Pagination Controls

TASK: Add pagination to /pages/ArticlesPage.tsx

REQUIREMENTS:
- Show current page, total pages
- Previous/Next buttons
- Jump to page input
- Update URL query params: ?page=2

CONSTRAINTS:
- Do not modify useArticles hook
- Pagination data comes from meta.pagination in API response

ACCEPTANCE TESTS:
- Pagination controls work correctly
- URL updates with page number
- Direct URL navigation works (/articles?page=3)

Phase 6: Single Article Page

Prompt 6.1: Article Detail Foundation

TASK: Create /pages/ArticlePage.tsx

REQUIREMENTS:
- Get slug from URL params
- Use useArticle(slug) hook
- Display: featuredImage, title, description, author (with image), contentTags
- Render markdown content
- Show 404 if article not found

CONSTRAINTS:
- Do not render blocks yet (next prompt)
- Do not render related articles yet (next prompt)

DELIVERABLES:
- /pages/ArticlePage.tsx
- Update /App.tsx routing: /articles/:slug

Prompt 6.2: Render Article Blocks

TASK: Add block rendering to /pages/ArticlePage.tsx

REQUIREMENTS:
- Reuse BlockRenderer component from landing page
- Render article.blocks array
- Use same block components

CONSTRAINTS:
- Do not modify block components
- Do not modify BlockRenderer

ACCEPTANCE TEST:
- Article blocks render correctly
- All block types display properly

Prompt 6.3: Add Related Articles

TASK: Add related articles section to /pages/ArticlePage.tsx

REQUIREMENTS:
- Render article.relatedArticles array
- Use ArticleCard component in grid
- "Related Articles" heading
- Show only if relatedArticles exist

CONSTRAINTS:
- Do not modify ArticleCard

ACCEPTANCE TEST:
- Related articles display at bottom of page
- Cards link to correct articles

Phase 7: Polish & Optimization

Prompt 7.1: Error Boundaries

TASK: Add error boundaries

REQUIREMENTS:
- Create ErrorBoundary component
- Wrap each page with error boundary
- User-friendly error messages
- "Try again" button

DELIVERABLES:
- /components/ErrorBoundary.tsx
- Update page wrappers

Prompt 7.2: Accessibility Audit

TASK: Accessibility improvements

REQUIREMENTS:
- Add proper ARIA labels
- Ensure keyboard navigation works
- Check color contrast
- Add skip links
- Alt text on all images

ACCEPTANCE:
- Lighthouse accessibility score > 95

Prompt 7.3: Performance Optimization

TASK: Performance optimization

REQUIREMENTS:
- Lazy load images
- Code splitting for routes
- Optimize bundle size
- Add meta tags for SEO

ACCEPTANCE:
- Lighthouse performance score > 90

Comparison: One-Shot vs. Iterative Approach

Aspect	One-Shot (Even with Checkpoints)	Iterative Multi-Prompt
Initial Time	Fast first output	Slower start
Total Time	Often slower (more debugging)	Faster to working product
Code Quality	Variable, hard to review	Consistently higher
Testing	Test everything at once	Test each piece
Debugging	Hard to isolate issues	Easy to pinpoint problems
AI Context	Context overload	Focused context
Knowledge Reuse	Limited	Knowledge file persists
Flexibility	Rigid structure	Adaptable as you learn
Learning Curve	Steep (all at once)	Gradual
Version Control	Large commits	Small, focused commits
Rollback	Lose all work	Rollback single feature

Key Takeaways

Start Small - Bootstrap the project → Add features one by one
Use Knowledge Files - Set context once, reference forever
Chat Mode is Your Friend - Plan in chat, implement when ready
Test After Each Prompt - Don't stack unverified changes
Pin Working Versions - Create safety nets
Be Specific - Scoped prompts = predictable output
Add Guardrails - Tell AI what not to touch
Repeat Important Info - Don't assume AI remembers everything

When to Use Which Approach

Use Checkpoint One-Shot When:

You're creating a proof-of-concept
You have a very clear, simple spec
You're experienced and can review large codebases quickly
You're just exploring what's possible

Use Iterative Multi-Prompt When:

You're building for production
You're learning the tech stack
The project has multiple complex features
Code quality and maintainability matter
You want to minimize debugging time

For our Strapi blog project, the iterative approach is strongly recommended.

Key Takeaway: Context is Everything

When using AI coding tools:

Share what only you know - Your backend details, API structure, custom setup
Let AI use what it knows - Standard React, UI components, popular libraries
Show, don't just tell - Include real API responses, not just descriptions
Point out customizations - If you've changed how Strapi works, say so clearly

The more accurate details you give about your Strapi backend, the better code you'll get.

Step 6: Build with Lovable.dev

Create a new project in Lovable.dev
Copy the complete prompt above (the entire ```txt block)
Paste the sample API responses into the placeholders:
- Get actual responses from your Strapi endpoints
- Replace [Paste actual response from /api/global...] with real JSON
- Do this for global, landing-page, articles, and single article
Paste the OpenAPI spec (optional but recommended)
- Run yarn strapi openapi generate in your server
- Copy contents of specification.json
- Paste into the <openapi-spec> section
Submit the prompt to Lovable
Let Lovable generate your entire frontend - It will create all files, components, hooks, and pages
Iterate with focused prompts if needed:
- "Add infinite scroll instead of pagination"
- "Improve mobile navigation UX"
- "Add article reading time estimate"

Step 7: Test and Refine

As Lovable builds your application:

Test API connectivity - Ensure CORS is properly configured in Strapi
Verify data rendering - Check that all fields display correctly
Test error handling - Try invalid slugs, network failures, etc.
Check responsive design - Test on mobile, tablet, and desktop viewports
Optimize performance - Look for unnecessary re-renders or API calls

Step 8: Deploy Your Frontend

Lovable.dev provides integrated deployment options:

Click the Deploy button in Lovable.dev
Configure environment variables (your Strapi API URL)
Deploy to production - Lovable typically uses Vercel or similar platforms

Best Practices for AI-Powered Development with Strapi

1. Always Include Real API Responses

Don't just provide the OpenAPI spec—include actual API responses from your endpoints. This ensures the AI understands your specific data structure (especially if you've customized it with middleware).

Fetch real responses:


bash
# Get actual responses from your deployed Strapi
curl https://your-strapi.strapiapp.com/api/global
curl https://your-strapi.strapiapp.com/api/articles

2. Be Clear About Your Strapi Version

Specify you're using Strapi v5 in your prompt. Strapi v5 changed the data structure from v4—it no longer uses nested data.attributes, which makes your frontend code much cleaner.

3. Update Your Spec When Content Types Change

Whenever you modify Strapi content types:


bash
yarn strapi openapi generate

Then update your Lovable prompt with the new spec.

4. Document Your Custom Middleware

If your Strapi has custom middleware (like our auto-populate middleware), document this clearly. In our case:

Middleware auto-populates all relations and media
This means you don't need populate params in your frontend API calls
All related data comes back automatically

5. Test with Real Data Early

Don't wait until the frontend is "done" to test with real Strapi data:

Get Lovable to generate the basic structure
Test API connectivity immediately
Verify data rendering with actual content
Iterate on styling and features once data flow works

Common Pitfalls and How to Avoid Them

Pitfall 1: Vague Prompts Lead to Generic Code

Problem: Asking Lovable to "build a blog" without context results in generic code that doesn't match your API.

Solution: Provide OpenAPI spec, real API responses, and specific requirements about data structure and features.

Pitfall 2: Mixing Strapi Versions

Problem: AI generates code for older Strapi versions (v3/v4) with nested data.attributes structure when you're using Strapi v5's simpler structure.

Solution: Clearly specify you're using Strapi v5 in your prompt. Include actual API responses showing the v5 structure. Give examples of correct data access: article.title not article.attributes.title.

Pitfall 3: Over-fetching or Under-fetching Data

Problem: Not populating relations results in missing data, or populating everything causes performance issues.

Solution: Be specific about which relations to populate:



For article listing: populate=coverImage,category,author
For article detail: populate=*

Pitfall 4: Runaway API Calls

Problem: AI-generated code may create infinite loops or excessive API calls.

Solution: Implement debouncing, proper dependency arrays in useEffect, and rate limiting on your API:


typescript
// Add to your prompt:
"Implement search with 300ms debounce to prevent excessive API calls.
Ensure useEffect hooks have proper dependency arrays to avoid infinite loops.
Add request caching where appropriate."

Conclusion

AI tools like Lovable.dev aren't replacing developers. They're making us faster and more creative. But you still need to understand your data, your API, and your app's structure to use them well.

Start with a clear Strapi backend, create your OpenAPI spec, write a detailed prompt, and let Lovable.dev speed up your work. Just remember: the AI is your coding partner, not your replacement.

Want to learn more? Join me Mon-Fri at 12:30 PM CST for Strapi's open office hours on Discord, or find me @codingthirty on X.

Resources:

How QBurst Migrated a Luxury Brand from Strapi v4 to Strapi 5

Strapi — Thu, 13 Nov 2025 13:07:35 +0000

Overview

QBurst Technologies, a digital engineering company, partnered with a global luxury retail brand to elevate their content management capabilities. Over a focused three-month project, the team migrated the brand’s digital ecosystem from Strapi v4 to v5, enhancing performance, scalability, and editorial workflows. Leveraging a modern tech stack including Strapi, Next.js, Node.js, and AWS, QBurst helped the client future-proof their CMS infrastructure while delivering a seamless upgrade experience.

The Challenge

The client, a global luxury retail brand, had successfully used Strapi v4 to manage content across its website. While v4 had been a stable foundation, the upcoming transition to Strapi v5 opened up a valuable opportunity to strengthen their digital ecosystem:

Future Support & Security: Migrating to v5 ensured ongoing access to official support, security patches, and new feature updates, keeping the platform resilient and secure.
Roadmap Alignment: By moving to v5, the brand could immediately benefit from Strapi’s latest innovations and stay aligned with its long-term product roadmap.
Operational Readiness: Replacing deprecated plugins and legacy APIs with modern alternatives created a stronger foundation for future integrations.
Enhanced Editorial Experience: Business teams gained access to modern workflows like live preview, content history, and streamlined internationalization (i18n), enabling faster and more accurate content delivery.

To ensure long-term stability, scalability, and future-proofing, the client made the strategic decision to migrate to Strapi v5.

The Solution

We migrated the client’s CMS from Strapi v4 to v5 while ensuring uninterrupted business operations.

Key improvements delivered:

Live Preview: Content editors could preview pages before publishing, reducing errors.
Unified Document System: Drafts, published versions, and translations are consolidated under a single document model, simplifying consistency and version history.
Flatter API Responses: APIs became cleaner and more efficient. Replacing nested attributes with flatter responses simplified integration with the frontend.
Built-in Internationalization (i18n): In v5, i18n is built into the core (no plugin required), simplifying setup and making translation workflows more consistent.
Official Strapi Client Library: v5 introduces an official client library, making it easier and more reliable to consume the Strapi API from frontend applications.
Better Developer Experience: Stronger TypeScript support, a Plugin SDK, and faster admin UI bundling with Vite streamlines development.
Support & Maintenance: v4 is moving toward end-of-life. Upgrading ensures access to security patches, updates, and the evolving plugin ecosystem.

The Implementation Process

We followed a structured migration approach to minimize risks:

Audit Plugins and Custom Code: Check all plugins for v5 compatibility. Review custom controllers, services, and middleware for deprecated API usage (entityService). Note that the Document Service API replaces the Entity Service API used in Strapi v4.
Full Backup: Database snapshots, media libraries, and customized codebases were secured prior to migration.
Upgrade Tool & Manual Adjustments: We used the official CLI upgrade tool and manually updated models, relations, and custom controllers.
Refactoring: Adjusted models, controllers, and bulk import logic to work with the new Document Service API.
Incremental Migration Strategy: A compatibility header (Strapi-Response-Format: v4) allowed the backend (running on v5) to return responses in the older v4 format. This ensured that existing frontends continued working while frontend applications were progressively updated to consume the new v5 response format.

Migration Results & Impact

The migration delivered measurable improvements:

Editorial Efficiency: Preview and live preview features reduced publishing errors and made listing reviews faster.
Performance Gains: API responses for searches became leaner, improving page load times.
Code Quality: Cleaner backend architecture with Document Service reduced technical debt.
Future Scalability: The CMS is now aligned with Strapi’s roadmap, ensuring supportability, plugin compatibility, and long-term maintainability.

Technical Deep Dive

1. Model Alignment

Content types and components were verified for v5 compatibility, and relational models (category, subcategory, brand) were adjusted to align with v5’s documentId-based relation handling.

2. CSV Import & Bulk Upsert

After upgrading to Strapi v5, the CSV import logic and bulk upsert controller broke due to the new Document Service API (which replaces the Entity Service) and changes in how relations and i18n translations are handled. To fix this :

We refactored the Node.js CSV script and bulk upsert controller to use the Document Service API with documentId.
Create base documents first and then attach translations.
Adapt to the new i18n model.
Manage relations with the new connection, disconnect, and set parameters.
Pass documentIds instead of numeric IDs, and handle Strapi v5’s flattened relation response format.

3. Custom Controllers

Wishlist/account-related custom controllers required changes due to documentId and relation population changes in v5. All Entity Service APIs were migrated to Document Service APIs, and queries and update logic were refactored with normalized responses to maintain frontend compatibility.

4. BFF Layer

Strapi 5 introduced improved response structures and relation handling, which created an opportunity to modernize the BFF middleware. We refactored it to normalize v5 responses, adjust population logic, and ensure backward-compatible contracts with the FE. To make the transition smooth, we adopted an incremental migration strategy: initially serving all APIs with the Strapi-Response-Format: v4 header so the FE and BFF continued working without disruption, then gradually migrating APIs to the new v5 document service and response format while progressively removing the compatibility header.

5. Plugins

Some plugins were incompatible with Strapi v5, so we replaced them with supported alternatives and customized certain functionalities using the Plugin SDK (eg, SEO plugin, Content Versioning plugin).

6. Testing & Validation

Testing involved importing test CSVs (multi-locale), verifying BFF response contracts with the FE team, and ensuring personalization endpoints worked without FE changes.

Lessons Learned & Best Practices

For organizations considering the same migration, here are our key lessons:

Always maintain backups and a rollback plan before touching production.
Use compatibility headers to reduce disruption for frontend consumers.
Validate new preview and draft workflows with content editors early.
Keep plugins audited and avoid reliance on unsupported community packages.
Pay extra attention to relations and i18n—these are the most complex parts of migration.

About QBurst

QBurst is a digital engineering company that crafts delightful client experiences through AI-driven software engineering and data solutions. They support clients in driving digital transformation that helps them innovate, scale, and succeed.

They are a High AI-Q company offering differentiated digital experiences to clients and their end-customers by infusing AI into every aspect of their delivery and operations.

Build a PDF Generation Engine with Next.js, Puppeteer, and Strapi

Strapi — Thu, 13 Nov 2025 13:04:46 +0000

Introduction & What You'll Build

In many industries, PDF generation has become a core requirement, whether it's for invoices, reports, or certificates, which are very important.

In this article, you will learn how to use Next.js, Puppeteer, and Strapi to build a PDF generation engine. The engine seamlessly integrates content from the Strapi backend, server-side rendering using Next.js, and web to PDF using Puppeteer.

Prerequisites

You are expected to be familiar with Node.js and Next.js.
Node.js version requirements (e.g., "Node.js 18.x or higher")
npm or yarn version
Basic TypeScript knowledge
Understanding of REST APIs
Familiarity with React hooks
Terminal/command line basics
A code editor (VS Code recommended)

What you will learn

By the end of this article, you will be able to easily build the frontend pages below, populate them with data from Strapi, and serve them to your users as PDFs.

How to fetch Strapi data dynamically
How to render print-optimized pages in Next.js
How to automate PDF generation with Puppeteer
How to document the API with Swagger & Zod

Your browser does not support the video tag.

Setting up Project Folder

Open up your terminal and create a pdf-engine folder to store your project files.

mkdir pdf-engine

Navigate into the pdf-engine directory.

cd pdf-engine

Strapi 5 Backend Setup

Create your Strapi app in a folder named backend.

npx create-strapi-app@latest backend --quickstart

The --quickstart flag sets up your Strapi app with an SQLite database and automatically starts your server on port 1337.

If the server is not already running in your terminal, cd into the backend folder and run npm develop to launch it.

Visit http://localhost:1337/admin in your browser and register in the Strapi Admin Registration Form.

Design the Content Model for the PDF generation engine

Now that your Strapi application is set up and running, fill the form with your personal information to get authenticated to the Strapi Admin Panel.

From your admin panel, click on Content-Type Builder > Create new collection type tab to create a collection and its field types for your application. In this case, you are creating the following collections: About, Article, Graph, topfeature, topstat, and report. These collections will help us create types for the Strapi report PDF.

Collections Overview

Here is a table showing all collection types, their fields, and relations.

Collection Type	Field	Type	Relation	Notes
About	Description	Long Text	–
	Funded	Boolean	–
	Size	Short Text	–
	Returns	Enum	–	Options: daily, weekly, monthly, quarterly
	Report	Relation	One to One with Report	Each About entry belongs to one Report
Article	Picture	Media	–
	Title	Text	–
	Report	Relation	Many to One with Report	Each Report can have many Articles
Graph	Year	Number	–
	Ratio	Number	–
	Report	Relation	Many to One with Report	Each Report can have many Graphs
Topfeature	Icon	Media	–
	Title	Short Text	–
	Description	Long Text	–
	Report	Relation	Many to One with Report	Each Report can have many Topfeatures
Topstat	Title	Text	–
	Description	Long Text	–
	Report	Relation	Many to One with Report	Each Report can have many Topstats
Report	Title	Short Text	–
	Articles	Relation	One to Many with Article	A Report can have many Articles
	Graphs	Relation	One to Many with Graph	A Report can have many Graphs
	Topfeatures	Relation	One to Many with Topfeature	A Report can have many Topfeatures
	Topstats	Relation	One to Many with Topstat	A Report can have many Topstats
	About	Relation	One to One with About	A Report has one About section

For more on this, see Understanding and Using Relations in Strapi to learn more.

Allowing Public API Access in Strapi

Now, let's allow API access to your blog to allow you to access the blog posts via your API on the frontend. To do that, click on Settings > Roles > Public.

Then expand the Report and click on find and findOne.

Scroll downwards and do the same for the media library Permission tab to enable us to upload images to our Strapi backend.

Next.js Frontend Setup

Strapi supports frontend frameworks including React, Next.js, Gatsby, Svelte, Vue.js etc. but for this application you will be making use of Next.js.

In a new terminal session, change the directory to pdf-engine and run the following command:

npx create-next-app@latest

On installation, you'll see some prompts. Name your project frontend and select Typescript, app router with Tailwind, and other config of your choice.

Install Necessary Dependencies

Add the following dependencies to your Next.js frontend app, you will use them later:

cd frontend
npm install zod puppeteer recharts @asteasolutions/zod-to-openapi

Zod: A TypeScript schema validation library that ensures data matches expected structures.
Puppeteer: A Node.js library for automating and controlling Chrome/Chromium, ideal for tasks like scraping, PDF generation, and automated testing.
Recharts: A composable charting library for React, built with SVG, perfect for creating interactive and responsive data visualizations.
@asteasolutions/zod-to-openapi: A tool that converts Zod schemas into OpenAPI specifications, keeping API documentation in sync with your validation logic

Folder Structure

The directory structure looks like this:

.
├── README.md
├── app
│   ├── api
│   │   ├── docs
│   │   │   └── route.ts
│   │   └── pdf
│   │       └── route.ts
│   ├── favicon.ico
│   ├── globals.css
│   ├── layout.tsx
│   └── page.tsx
├── component
│   ├── annual-returns.tsx
│   ├── article-count-ratio.tsx
│   ├── details-card.tsx
│   ├── last-page.tsx
│   ├── page.tsx
│   └── portfolio-about.tsx
├── eslint.config.mjs
├── lib
│   ├── http.ts
│   ├── openapi.ts
│   ├── schemas
│   │   └── pdf.ts
│   └── util.ts
├── modules
│   ├── about-page.tsx
│   ├── front-page.tsx
│   └── return-details-page.tsx
├── next-env.d.ts
├── next.config.ts
├── package-lock.json
├── package.json
├── postcss.config.mjs
├── public
│   ├── file.svg
│   ├── globe.svg
│   ├── next.svg
│   ├── vercel.svg
│   └── window.svg
└── tsconfig.json

Set Up your Frontend CSS Rules

Open the app/globals.css file in your Next.js project and replace its contents with the following code:

1. Import Tailwind

@import 'tailwindcss'

Brings in Tailwind CSS so you can use its utility classes along with your custom print styles.

2. Set Print Page

@page {
  size: A4;
  margin: 0;
}

The size: A4; sets the print page size to standard A4 dimensions (210mm × 297mm). And the margin: 0; removes default printer margins so your content fills the page edge-to-edge (printer permitting).

3. HTML & Body reset

html,
body {
  width: 210mm;
  height: 297mm;
  margin: 0;
  padding: 0;
  counter-reset: page;
}

The width/height forces the document’s physical dimensions to A4 size for accurate print scaling. The margin:0; padding: 0; Removes browser default spacing. And counter-reset: page; Initializes a CSS counter named page at zero, so you can number pages.

4. Page number counter

.pageNumber::after {
  counter-increment: page;
  content: counter(page);
}

The style above targets elements with .pageNumber and appends the current page number using CSS counters. The counter-increment: page; increases the page counter each time the element appears. And content: counter(page); inserts the counter’s value into the document.

5. Page break handling

.print-page {
  break-after: page;
  page-break-after: always;
}

.print-page:last-of-type {
  page-break-after: auto;
}

The .print-page forces a hard page break after this element when printing. And the .print-page:last-of-type Removes the page break for the very last page, so you don’t get an empty page at the end.

6. @media print rules

@media print {
  html,
  body {
    width: 210mm;
    height: 297mm;
  }

  * {
    -webkit-print-color-adjust: exact !important;
    print-color-adjust: exact !important;
  }

  .pageNumber::after {
    counter-increment: page;
    content: counter(page);
  }
}

The html and body elements enforce the A4 size specifically for print mode. The -webkit-print-color-adjust: exact / print-color-adjust: exact: ensures colors are printed exactly as defined, preventing browsers from lightening or ignoring background colors. And .pageNumber::after Repeats the counter rule inside @media print to ensure page numbering still works during print rendering.

Set up environment variables

Create a .env file in the root of your frontend directory and add the following environment variables:

NEXT_PUBLIC_STRAPI_URL=http://localhost:1337/

Building Core Application Components and Data Flow

This section explains how the application’s core components work together to manage data, display dynamic content, and generate PDFs.

1. Content Management with Strapi

The application integrates with Strapi CMS running on localhost:1337 to fetch dynamic content:

// Path: ./lib/http.ts

export const getAllReports = async () => {
  const res = await fetch(`http://localhost:1337/api/reports?populate=*`);
  return res.json();
};

export const getSingleReport = async (id: number | string) => {
  const res = await fetch(
    `http://localhost:1337/api/reports/${id}?populate[0]=articles.picture&populate[1]=topfeature.icon&populate[2]=graphs&populate[3]=topstats&populate[4]=about`
  );
  return res.json();
};

//lib/util.ts
export const getImageUrl = (url: string) => {
  return `${process.env.NEXT_PUBLIC_STRAPI_URL}${url}`;
};

This design allows content editors to manage reports, articles, and statistics through Strapi's intuitive interface, while the Next.js application consumes this content via REST API calls.

2. Dynamic Page Composition

This is the main page (app/page.tsx) where you will put all the pages together, with each wrapped in the page component.

Each page section is a modular component that receives specific data from Strapi, enabling flexible content layouts and easy maintenance.

// Path: ./app/page.tsx

import { LastPage } from '@/component/last-page';
import { Page } from '@/component/page';
import { getSingleReport } from '@/lib/http';
import { AboutPage } from '@/modules/about-page';
import { FrontPage } from '@/modules/front-page';
import { ReturnDetailsPage } from '@/modules/return-details-page';

export default async function Home({
  searchParams,
}: {
  searchParams: { documentId: string };
}) {
  const singleReport = await getSingleReport(searchParams?.documentId);

  return (
    <>
      <Page noPadding>
        <FrontPage
          title={singleReport?.data?.title}
          about={singleReport?.data?.about}
        />
      </Page>
      <Page>
        <AboutPage
          about={singleReport?.data?.about}
          articles={singleReport?.data?.articles}
        />
      </Page>
      <Page>
        <ReturnDetailsPage
          topStats={singleReport?.data?.topstats}
          graph={singleReport?.data?.graphs}
          topFeatures={singleReport?.data?.topfeature}
        />
      </Page>
      <Page noPadding>
        <LastPage />
      </Page>
    </>
  );
}

3. PDF Generation Engine

The heart of the application lies in the PDF generation API (app/api/pdf/route.ts), which leverages Puppeteer for high-quality document creation. See code in the "Next.js + Puppeteer: Generate and Download PDFs via API Routes" section of "PDF Generation Implementation" heading.

Key Features of the PDF Engine

Route-based Generation: Accepts a route query parameter to generate PDFs from any frontend route
Print-Optimized Rendering: Uses page.emulateMediaType('print') for optimal PDF output
A4 Format Support: Configures viewport and page settings for standard document formats
Font Loading Optimization: Ensures all fonts are loaded before PDF generation
Error Handling: Comprehensive error handling with proper browser cleanup

Browser Configuration:

The application uses optimized Puppeteer arguments for production environments:

Disables unnecessary features for performance
Sets specific window dimensions (595x842 for A4)
Configures font rendering and color profiles
Disables audio and speech APIs

Building Application Data Visualization

This section shows how the UI is brought together from small, reusable components and how they come to be a printable report. Skim the visuals, then check the code to see props and structure.

What’s below:

Reusable chart/content blocks built with Recharts and simple React components
Page-level modules that assemble those blocks into A4-ready sections
Short, high-signal explanations for every image and code sample

1. App layout

In the code block below, we gave our app its default layout and set Geist as the font; this layout here affects other pages in the Next app.

// Path: ./app/layout.tsx

import type { Metadata } from 'next';
import { Geist, Geist_Mono } from 'next/font/google';
import './globals.css';

const geistSans = Geist({
  variable: '--font-geist-sans',
  subsets: ['latin'],
});

const geistMono = Geist_Mono({
  variable: '--font-geist-mono',
  subsets: ['latin'],
});

export const metadata: Metadata = {
  title: 'Create Next App',
  description: 'Generated by create next app',
};

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang='en'>
      <body
        className={`${geistSans.variable} ${geistMono.variable} antialiased`}
      >
        {children}
      </body>
    </html>
  );
}

2. Article count ratio Component

Explanation

Purpose: Small, focused chart for “Article Count Ratio by Year”.
Props: { data: { year: string; ratio: number }[] }.
Notes: Self-contained sizing and style to keep print output consistent.

Code walkthrough

"use client": Recharts renders on the client; needed for this chart.
ResponsiveContainer: Keeps the chart responsive on screen and stable in print.
BarChart/Bar: Plots ratio; rounded corners (radius) look better when printed.
XAxis/YAxis: Minimal axis labels; unit='%' adds a percent suffix.
Tooltip: Helpful in the browser; ignored by Puppeteer when generating PDF.

// Path: ./component/article-count-ratio

'use client';

import {
  BarChart,
  Bar,
  XAxis,
  YAxis,
  Tooltip,
  ResponsiveContainer,
} from 'recharts';

export type IArticleRatioData = {
  year: string;
  ratio: number;
};

export default function ArticleCountRatioChart({
  data,
}: {
  data: IArticleRatioData[];
}) {
  return (
    <div className='w-full h-[400px] bg-white p-10 rounded-2xl shadow'>
      <h2 className='text-xl font-bold mb-4'>Article Count Ratio by Year</h2>
      <ResponsiveContainer width='100%' height='100%'>
        <BarChart data={data}>
          <XAxis dataKey='year' />
          <YAxis unit='%' />
          <Tooltip />
          <Bar dataKey='ratio' fill='#4845fe' radius={[8, 8, 0, 0]} />
        </BarChart>
      </ResponsiveContainer>
    </div>
  );
}

3. Annual returns Component

Explanation

Purpose: Section wrapper around the chart with heading and spacing.
Use: Drop into pages to present annual performance.

Code walkthrough

Branding row: Simple logo above the chart for visual anchoring.
Composition: Forwards data to the chart without transforming it.

// Path: ./component/annual-returns

import ArticleCountRatioChart, {
  IArticleRatioData,
} from '@/component/article-count-ratio';
import React from 'react';

export const AnnualReturns = ({ data }: { data: IArticleRatioData[] }) => {
  return (
    <div className='w-full'>
      <div className='flex items-center mb-10'>
        <img
          src='https://strapi.io/assets/strapi-logo-dark.svg'
          height={42}
          alt=''
        />
      </div>

      <ArticleCountRatioChart data={data} />
    </div>
  );
};

4. Details card component

Explanation

Purpose: Compact card for an item (e.g., article) with image and dates.
Notes: Fixed image box ensures alignment in print; date formatting handled locally.

Code walkthrough

formatDate(...): Shared function for human-readable dates.
Left column: Fixed-size media box prevents uneven rows when images vary.
Right column: Title and small, muted meta details for clean print hierarchy.

// Path: ./component/details-card

import React from 'react';

export const DetailsCard = ({
  title,
  img,
  createdAt,
  updatedAt,
}: {
  title: string;
  img?: string;
  updatedAt: Date;
  createdAt: Date;
}) => {
  const formatDate = (date: Date) => {
    return new Intl.DateTimeFormat('en-US', {
      month: 'long',
      day: 'numeric',
      year: 'numeric',
    }).format(new Date(date));
  };

  return (
    <div className='flex gap-2 my-2 bg-white border border-gray-200 rounded-md overflow-hidden'>
      <div className='w-[200px] h-[100px] flex-shrink-0'>
        {img && (
          <img src={img} alt='img-fd' className='w-full h-full object-cover' />
        )}
      </div>
      <div className='p-3 text-[#032b69] flex flex-col justify-center'>
        <h3 className='text-lg font-semibold'>{title}</h3>
        <p className='text-[10pt] text-gray-500'>
          {formatDate(createdAt)} · Updated {formatDate(updatedAt)}
        </p>
      </div>
    </div>
  );
};

5. Last page component

Explanation

Purpose: Closing page with brand CTA and supportive copy.
Notes: Uses brand artwork, single CTA, and supportive bullet blocks.

Code walkthrough

Background block: Inline backgroundImage keeps the hero visual in print mode.
CTA: High-contrast button for clear calls-to-action.
Benefit items: Repeated pattern (icon + heading + paragraph) improves skimmability.

// Path: ./component/last-page

import Link from 'next/link';
import React from 'react';

export const LastPage = () => {
  return (
    <div className='h-full w-full bg-[#f6f6ff] relative overflow-hidden'>
      <div className='p-8'>
        <img
          src='https://strapi.io/assets/strapi-logo-dark.svg'
          height={42}
          alt=''
        />
        <div
          style={{
            backgroundImage:
              'url(https://strapi.io/assets/use-case/strapi5_hero.svg)',

            backgroundColor: '#181826',
          }}
          className='text-white my-8 p-4 rounded-md'
        >
          <h4 className='text-[25pt] font-bold leading-normal'>
            Build modern websites with the most customizable Headless CMS
          </h4>
          <p className='text-sm leading-5 mt-3 w-[90%]'>
            Open-source Headless CMS for developers that makes API creation
            easy, and supports your favorite frameworks. Customize and host your
            projects in the cloud or on your own servers.
          </p>
          <Link
            href='https://strapi.io/'
            className='cursor-pointer'
            target='_blank'
          >
            <button className='bg-[#4845fe] text-white p-2 px-4 mt-4 rounded-md font-[500]'>
              Get started
            </button>
          </Link>
        </div>
        <div>
          {[
            {
              title: 'Improved Productivity',
              description:
                'An intuitive interface simplifies content creation, so your marketing team can work more efficiently, freeing up your time for more complex development tasks.',
            },
            {
              title: 'Simplify Content Editing and Layouts',
              description:
                'Dynamic zones allow marketers to create adaptable and creative designs. This means less back-and-forth with developers for frontend changes.',
            },
            {
              title: 'Internationalization and Media Management',
              description:
                'Publish content in multiple languages with I18N and organize media files using the Media Library.',
            },
          ].map((item) => (
            <div
              key={item?.title}
              className='bg-[#fff] border border-[#e9e9ff] mb-3 p-6 rounded-md'
            >
              <div className='flex gap-2'>
                <img
                  src='https://delicate-dawn-ac25646e6d.media.strapiapp.com/Check_5f2ef36f5a.svg'
                  alt=''
                />
                <h4 className='text-[#292875] text-[15pt] font-bold'>
                  {item?.title}
                </h4>
              </div>
              <p className='text-[10pt] text-[#292875]'>{item?.description}</p>
            </div>
          ))}
        </div>
      </div>

      <img
        src='https://delicate-dawn-ac25646e6d.media.strapiapp.com/Customization_6abc7697f5.png'
        alt=''
        className='absolute'
        style={{ bottom: -370 }}
      />
    </div>
  );
};

6. Page component

Explanation

Purpose: Print-friendly A4 wrapper. Every section lives inside Page.
Prop: noPadding for full-bleed layouts when needed.

Code walkthrough

A4 canvas sizing: w-[210mm] h-[297mm] aligns with the print CSS rules.
Page counter: .pageNumber leverages counters set in global CSS.
Padding control: Avoids clipping edge-to-edge artwork.

// Path: ./component/page

import React, { ReactNode } from 'react';

export const Page = ({
  children,
  noPadding,
}: {
  children: ReactNode;
  noPadding?: boolean;
}) => {
  return (
    <div
      className={
        'print-page bg-[#f6f6ff] relative w-[210mm] h-[297mm] box-border ' +
        (noPadding ? 'p-0' : 'p-8')
      }
    >
      <div className='h-full w-full'>{children}</div>

      <div className='pageNumber absolute bottom-4 right-8 text-xs text-gray-500 print:block'>
        Page <span className='inline-block'></span>
      </div>
    </div>
  );
};

7. About component

Explanation

Purpose: Shows “About” description and key attributes in a neat card.
Inputs: about object; values formatted for compact print.

Code walkthrough

Info sub-component: Centralizes label/value alignment to avoid duplication.
Truncation + max width: Prevents long values from overflowing in print.

// Path: ./component/portfolio-about

import React, { FC } from 'react';

export const PortfolioAbout: FC<{
  about: {
    description: string;
    funded: boolean;
    returns: string;
    size: string;
  };
}> = async ({ about }) => {
  return (
    <div className='mt-10 p-6 bg-white rounded-lg'>
      <h2 className='text-2xl font-bold text-blue-900 mb-4'>About</h2>
      <p className='text-gray-500 mb-6 leading-relaxed'>{about?.description}</p>

      <div className='space-y-4'>
        <Info label='Funded' value={about?.funded ? 'Yes' : 'No'} />
        <Info label='Fund Size' value={`₦ ${about?.size}`} />
        <Info label='Returns Payment' value='Quarterly' />
      </div>
    </div>
  );
};

const Info = ({ label, value }: { label: string; value: string }) => (
  <div className='flex justify-between text-gray-500'>
    <span>{label}</span>
    <span className='text-blue-900 font-medium truncate max-w-[150px] text-right'>
      {value}
    </span>
  </div>
);

8. Front page module

You’ll assemble these into full pages via the modules folder.

Explanation

Purpose: Hero/front page of the PDF with title, short description, and CTA.
Notes: Background artwork declared in inline style for print stability.

Code walkthrough

Inline background style: Ensures Puppeteer includes the hero image.
Large display title: Establishes typographic hierarchy for first-page impact.
CTA via Link: Easy to replace with your own destination.

// Path: ./modules/front-page.tsx

import Link from 'next/link';
import React from 'react';

interface IFrontPageProps {
  title: string;
  about: {
    description: string;
    funded: boolean;
    returns: string;
    size: string;
  };
}

export const FrontPage = ({ title, about }: IFrontPageProps) => {
  return (
    <div
      style={{
        backgroundImage:
          'url(https://strapi.io/assets/use-case/strapi5_hero.svg)',
      }}
      className='bg-[#181826] text-white w-full h-full relative overflow-hidden'
    >
      <div className='p-8'>
        <h4 className='text-[48pt] pt-[100px] font-bold leading-16'>{title}</h4>
        <p className='text-sm leading-5 mt-3 w-[80%]'>{about?.description}</p>
        <Link
          href='https://strapi.io/'
          className='cursor-pointer'
          target='_blank'
        >
          <button className='bg-[#4845fe] text-white p-2 px-4 mt-4 rounded-md font-[500]'>
            Get started
          </button>
        </Link>
      </div>
      <img
        src='https://delicate-dawn-ac25646e6d.media.strapiapp.com/Content_Management_cfd037fcc2.png'
        alt='cowry-test'
        style={{
          //  scale: 2.5,
          position: 'absolute',
          bottom: -150,
          right: 0,
        }}
      />
    </div>
  );
};

9. About page module

Explanation

Purpose: Combines “About” with a list of article cards under a section header.
Flow: Logo → About card → “Top articles” list using DetailsCard.

Code walkthrough

getImageUrl(...): Resolves Strapi media URLs to absolute paths.
Mapping articles: Each item becomes a stable-width DetailsCard row.

// Path: ./modules/about-page.tsx

import { DetailsCard } from '@/component/details-card';
import { PortfolioAbout } from '@/component/portfolio-about';
import { getImageUrl } from '@/lib/util';
import React from 'react';

export const AboutPage = ({
  articles,
  about,
}: {
  articles: Array<{
    title: string;
    createdAt: Date;
    updatedAt: Date;
  }>;
  about: {
    description: string;
    funded: boolean;
    returns: string;
    size: string;
  };
}) => {
  return (
    <div>
      <div className='flex items-center'>
        <img
          src='https://strapi.io/assets/strapi-logo-dark.svg'
          height={28}
          alt=''
        />
      </div>
      <PortfolioAbout about={about} />
      <h2 className='text-2xl font-bold text-blue-900 mt-8 my-4'>
        Top articles last year
      </h2>
      <div className='grid grid-cols-1'>
        {articles?.map((details: any, item) => (
          <DetailsCard
            img={getImageUrl(details?.picture?.url as string)}
            {...details}
            key={item}
          />
        ))}
      </div>
    </div>
  );
};

10. Return Details Page

Explanation

Purpose: Composite section featuring the returns chart, key stats, and top features.
Notes: Simple grid layouts that also print cleanly on A4.

Code walkthrough

Chart first: Reuses AnnualReturns to set context with a quick visual.
2-col stats grid: Clear, compact layout for key metrics.
3-col features grid: Icon + title + description blocks; images via getImageUrl.

// Path: ./modules/return-details-page

import { AnnualReturns } from '@/component/annual-returns';
import { IArticleRatioData } from '@/component/article-count-ratio';
import { getImageUrl } from '@/lib/util';
import React from 'react';

export const ReturnDetailsPage = ({
  topStats,
  graph,
  topFeatures,
}: {
  topStats: Array<{ title: string; description: string }>;
  graph: Array<IArticleRatioData>;
  topFeatures: Array<{
    icon: {
      url: string;
    };
    title: string;
    description: string;
  }>;
}) => {
  return (
    <div>
      <AnnualReturns data={graph} />
      <h2 className='text-2xl font-bold text-blue-900 mt-8 mb-2'>Top stats</h2>
      <div className='grid grid-cols-2 gap-4'>
        {topStats?.map((item) => (
          <div
            key={item?.title}
            className='bg-white p-2 rounded-md border border-gray-100'
          >
            <h4 className='text-[#ac56f5] text-xl font-black'>
              {item?.description}
            </h4>
            <p className='text-[#666687] text-[10pt]'>{item?.title}</p>
          </div>
        ))}
      </div>
      <h2 className='text-2xl font-bold text-blue-900 mt-6 mb-2'>
        Top features
      </h2>
      <div className='grid grid-cols-3 gap-4'>
        {topFeatures?.map((feature, item) => (
          <div key={item} className='bg-white p-3 rounded-md'>
            <div className='flex gap-2 items-center mb-3'>
              <img
                src={getImageUrl(feature?.icon?.url)}
                alt=''
                width={30}
                height={30}
              />
              <h6 className='text-[12pt] text-[#292875] font-bold'>
                {feature?.title}
              </h6>
            </div>
            <p className='text-[#666687] text-[8pt]'>{feature?.description}</p>
          </div>
        ))}
      </div>
    </div>
  );
};

PDF Generation Implementation: Next.js API/Server modules for PDF Generation

PDF Generation Flow

You will be building a dummy Strapi end-of-year report PDF with top articles, top stats, etc.

TLDR; A request comes in → Next.js figures out the target page → Puppeteer renders it → PDF gets generated → PDF gets sent back.

API Entry point (Swagger UI): The flow starts when a request hits our API endpoint in the Next.js app. The request usually carries parameters like which page (route) you want to render and the specific data (e.g., document ID).
Next.js Handler: Next.js provides the handler that interprets the request and prepares the environment. Here, you extract query parameters (route and document ID) and build the target URL that Puppeteer should load.
Puppeteer Loads the Page: Puppeteer opens the target URL you built earlier. That page itself pulls content from Strapi (our CMS), so Puppeteer is effectively loading a fully dynamic webpage just like a real user’s browser would. Puppeteer waits until the page has finished loading all fonts, styles, and data before moving forward.
Puppeteer Prints the Page: Once the page looks exactly like it should, Puppeteer switches into “print mode.” It then generates a PDF version of the page, keeping things like layout, fonts, and background colors intact. This is equivalent to you (Ctrl P) Print - Save as PDF in Chrome, but automated.
Download Link Sent to User: Finally, the server responds with the PDF file as an attachment. The browser prompts the user to download it (output.pdf).

Next.js + Puppeteer: Generate and Download PDFs via API Routes

In this module, you will use Next.js api features to process the Puppeteer, create a route for generating the API, and send it back to the users.

Let's dive into the PDF generation route.

// Path: ./app/api/pdf/route.ts

import { NextRequest } from 'next/server';
import puppeteer from 'puppeteer';

const browserArgs = [
  '--no-sandbox',
  '--disable-setuid-sandbox',
  '--disable-dev-shm-usage',
  '--disable-gpu',
  '--disable-software-rasterizer',
  '--disable-extensions',
  '--disable-features=IsolateOrigins,site-isolation-trials',
  '--no-zygote',
  '--font-render-hinting=medium',
  '--force-color-profile=srgb',
  '--window-size=595,842',
  '--hide-scrollbars',
  '--mute-audio',
  '--disable-speech-api',
];

export async function GET(req: NextRequest) {
  const url = new URL(req.url);
  const route = url.searchParams.get('route') || '/';
  const documentId = url.searchParams.get('documentId') || '';
  const targetUrl = `http://localhost:3000${route}?documentId=${documentId}`;

  const browser = await puppeteer.launch({
    headless: 'shell',
    args: browserArgs,
    userDataDir: '/tmp/puppeteer-cache',
  });
  try {
    const page = await browser.newPage();
    await page.emulateMediaType('print');
    await page.setViewport({ width: 595, height: 842 });
    await page.evaluate(() => document.fonts.ready);
    await page.goto(targetUrl, {
      waitUntil: 'networkidle0',
      timeout: 5 * 60 * 6000,
    });

    const pdfBuffer = await page.pdf({
      format: 'A4',
      printBackground: true,
      margin: { top: 0, right: 0, bottom: 0, left: 0 },
      preferCSSPageSize: true,
    });

    await browser.close();

    return new Response(pdfBuffer, {
      headers: {
        'Content-Type': 'application/pdf',
        'Content-Disposition': `attachment; filename="output.pdf"`,
      },
    });
  } catch (err) {
    await browser.close();
    return new Response(`Error generating PDF: ${err}`, { status: 500 });
  } finally {
    await browser?.close();
  }
}

Our function in the API route exposes a GET endpoint in the Next.js app (App Router) then it;

Reads the route (e.g. /invoice) and a documentId query param.
Launches Puppeteer with a hardened set of Chromium flags tailored for server/cloud environments.
Opens a real, headless Chrome page at http://localhost:3000{route}?documentId=.
Forces print media rules, waits for fonts and network to settle, and then prints to PDF on an A4 canvas with background graphics.
Streams the resulting PDF back to the client with proper response headers.

Why these Chromium flags?

Serverless and containerized setups can behave unpredictably. These flags help Chrome run more reliably while keeping it lightweight.

Visit Chromium Commandline Flags to learn more.

The `print-to-PDF` Flow Configurations

page.emulateMediaType('print'): Forces CSS @media print rules—vital for page breaks, print-specific layouts, and hiding UI.
page.setViewport({ width: 595, height: 842 }): Aligns the rendering area with A4 dimensions at 72 DPI. This prevents layout reflow between screen and print.
Ensure that webfonts have fully loaded before rendering. Without this, you’ll get FOUT/FOIT or incorrect text metrics in the PDF:

await page.evaluate(() => document.fonts.ready);

networkidle0 waits until there are 0 network connections for at least 500 ms—useful when your page fetches data (e.g., from Strapi) before rendering.

await page.goto(targetUrl, {
  waitUntil: 'networkidle0',
  timeout: 5 * 60 * 6000,
});

Generate a PDF in A4 format that includes backgrounds and colors, uses zero margins since the layout handles its own spacing, respects any CSS @page size rules (falling back to A4 if none are set), and return it with headers specifying Content-Type: application/pdf and Content-Disposition: attachment; filename="output.pdf" to prompt a downloadable file with a friendly name.

await page.pdf({
  format: 'A4',
  printBackground: true,
  margin: { top: 0, right: 0, bottom: 0, left: 0 },
  preferCSSPageSize: true,
});

API Documentation with Swagger: PDF Routes

In this section, you will be documenting the routes using Swagger to make this engine accessible and serve it via the API route.

Validation and Documentation with Zod

You are defining a Zod schema for query parameters in a Next.js API endpoint. This schema is also annotated so it can be turned into an OpenAPI spec for documentation.

// Path: ./lib/schema/pdf.ts

import { z } from 'zod';
import { extendZodWithOpenApi } from '@asteasolutions/zod-to-openapi';

extendZodWithOpenApi(z);

export const PdfQuerySchema = z.object({
  route: z.string().openapi({
    description: 'Frontend route to render as PDF',
    example: '/invoice',
  }),
  documentId: z.string().openapi({
    description: 'Document ID',
    example: '123',
  }),
});

This code does the following:

Zod: A TypeScript-first schema validation library. Let's define the shape of data and validate it at runtime.
@asteasolutions/zod-to-openapi: A library that lets us convert Zod schemas into OpenAPI-compatible schemas, so your validation rules automatically become API documentation.
extendZodWithOpenApi(z);: This function extends Zod so can attach .openapi({...}) metadata to your schemas. Without this, Zod wouldn’t know how to output OpenAPI descriptions/examples.
z.object({...}) defines an object schema. In this case, the query parameters must include:
route: must be a string, with OpenAPI description and example provided. Example: /invoice
documentId: must be a string, also documented with OpenAPI metadata. E.g. 123.

Create Utility function to Generate OpenAPI 3.0 Specification

The code below defines a utility function generateOpenApiSpec() that automatically generates the OpenAPI 3.0 specification document for your endpoint that creates PDFs.

It uses the @asteasolutions/zod-to-openapi library, which converts Zod schemas into OpenAPI-compliant documentation.

// Path: ./lib/openapi.ts

import {
  OpenAPIRegistry,
  OpenApiGeneratorV3,
} from '@asteasolutions/zod-to-openapi';
import { PdfQuerySchema } from '@/lib/schemas/pdf';

export function generateOpenApiSpec() {
  const registry = new OpenAPIRegistry();

  registry.registerPath({
    method: 'get',
    path: '/api/pdf',
    request: {
      query: PdfQuerySchema,
    },
    responses: {
      200: {
        description: 'PDF generated successfully',
        content: {
          'application/pdf': {
            schema: { type: 'string', format: 'binary' },
          },
        },
      },
      400: {
        description: 'Invalid request',
      },
    },
    summary: 'Generate PDF from frontend route',
    tags: ['PDF'],
  });

  const generator = new OpenApiGeneratorV3(registry.definitions);

  return generator.generateDocument({
    openapi: '3.0.0',
    info: {
      title: 'PDF Generation API',
      version: '1.0.0',
    },
    servers: [{ url: 'http://localhost:3000' }],
  });
}

The code above contains the following:

OpenAPIRegistry: Lets you register schemas, routes, and responses.
OpenApiGeneratorV3: Converts the registry into a valid OpenAPI v3 document.
PdfQuerySchema: The Zod schema you created earlier for query validation.
Method & Path: Defines a GET /api/pdf route.
request.query: Uses your Zod schema (PdfQuerySchema) for validation + documentation.
responses: 200 → A successful response returns a PDF (application/pdf) in binary format. 400 → Client error (invalid query params).
summary & tags: Human-readable info for Swagger UI.
Swagger UI: This creates a JSON object that represents your API in OpenAPI 3.0 format.

You can now properly define our documentation schema here. And export the generateOpenApiSpec to be used as our spec in the SwaggerUIBundle, as seen below.

// Path: ./app/api/docs/route.ts

import { generateOpenApiSpec } from '@/lib/openapi';
import { NextResponse } from 'next/server';

export async function GET() {
  const openApiSpec = generateOpenApiSpec();

  const htmlContent = `
    <!doctype html>
    <html>
      <head>
        <title>PDF Generation engine</title>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <link rel="stylesheet" type="text/css" href="https://unpkg.com/swagger-ui-dist@5.10.5/swagger-ui.css" />
        <style>
          html {
            box-sizing: border-box;
            overflow: -moz-scrollbars-vertical;
            overflow-y: scroll;
          }
          *, *:before, *:after {
            box-sizing: inherit;
          }
          body {
            margin:0;
            background: #fafafa;
          }
        </style>
      </head>
      <body>
        <div id="swagger-ui"></div>
        <script src="https://unpkg.com/swagger-ui-dist@5.10.5/swagger-ui-bundle.js"></script>
        <script src="https://unpkg.com/swagger-ui-dist@5.10.5/swagger-ui-standalone-preset.js"></script>
        <script>
          window.onload = function() {
            const ui = SwaggerUIBundle({
              spec: ${JSON.stringify(openApiSpec)},
              dom_id: '#swagger-ui',
              deepLinking: true,
              presets: [
                SwaggerUIBundle.presets.apis,
                SwaggerUIStandalonePreset
              ],
              plugins: [
                SwaggerUIBundle.plugins.DownloadUrl
              ],
              layout: "StandaloneLayout"
            });
          };
        </script>
      </body>
    </html>
  `;

  return new NextResponse(htmlContent, {
    headers: {
      'Content-Type': 'text/html',
    },
  });
}

You will use the Swagger HTML and serve our openApiSpec to the spec key in the script, and return the htmlContent as what the route resolves to.

Testing Your Application

Here is a demo of what our application does.

Your browser does not support the video tag.

Hosting Your Strapi Application With Strapi Cloud

Check out the official documentation to read up on hosting your Strapi application to Strapi Cloud.

GitHub Repository

Feel free to clone the application from the GitHub repository and extend its functionality.

Conclusion

In this guide, you went through the steps of creating a PDF generation engine using Strapi, how you could build it as pages, and then use Next.js routes to serve them as pages. You also learned how to use Swagger and Zod to document the PDF generation endpoint.

This setup can be extended for invoices, receipts, certificates, and reports and deployed to Strapi Cloud for production scalability.

To learn more about Strapi and its other impressive features, you can visit the official documentation.

Strapi Community Call: Strapi AI, Media Library AI, Plugin Generators (with Boaz) & Q&A

Strapi — Thu, 13 Nov 2025 13:02:43 +0000

We just wrapped a jam-packed Strapi community call, and if you couldn’t make it live, here’s a recap with the big updates, why they matter, and how to try them. Strapi AI, Plugin Generators, Cloud Upgrades, and New Starters.

TL;DR

Strapi AI can now generate content types from Figma files, existing project code, or plain prompts. Media Library AI can auto-create image alt text and captions.
Plugin generators (demoed by Boaz) make building plugins way faster by scaffolding content types, controllers, routes, and services—right inside your plugin.
Strapi Cloud added project transfer, downloadable SQL backups, and a smoother multi-environment flow.
Admin UX got better: homepage widgets (now draggable), first steps toward a responsive admin, and conditional fields support in custom fields.
OpenAPI specs can be generated from your Strapi app to power docs, tooling, and AI-assisted UI generation.
The team is doubling down on stability and GitHub issue resolution.
Two solid starter projects to jump-start your builds: a community TanStack Start + Strapi starter, and NOTM’s Next.js + Strapi monorepo starter.

What’s New in Strapi

1) Strapi AI (a.k.a. the Architect)

Strapi AI helps you define your content structure faster:

Import from Figma: Point to a design and let Strapi suggest collection types and components.
Import from a project: Zip up your front-end code, upload it, and Strapi AI proposes a model that matches your UI.
Prompt it: Describe what you want in plain English and refine with follow-up prompts before you save anything.

This is great when you’re unsure how to structure content. You can prototype, compare options, and commit only when it looks right.

Media Library AI is also available. Turn it on in settings and Strapi will auto-generate alt text and captions for images on upload—huge time saver and better accessibility.

On the horizon: automatic AI translations (text and media) to speed up multi-locale work.

2) Admin UX & Productivity

Homepage widgets: Drag, drop, and position. Better yet, build your own widget as a plugin so clients see exactly the metrics or shortcuts they need when they log in.

Responsive admin (first pass): Early steps toward a better experience on iPad and mobile.

Conditional fields (now in custom fields too): Show/hide fields based on toggles or rules to keep editors focused on only what they need.

3) OpenAPI Spec Generation

Run a single command and get a machine-readable spec of your API. This is perfect for:

Quickly exploring endpoints in Swagger-like tools
Sharing precise API contracts with teammates and services
Feeding AI tools a structured map of your endpoints (handy for codegen or UI generation)

4) Strapi Cloud Improvements

Transfer ownership: Move a project to a client with a couple of clicks.
Downloadable backups: Grab a raw SQL backup and inspect locally.
Multi-environment flow: Keep dev, staging, and prod separate—especially databases. Golden rule: pull production data down for testing, never push dev DBs up.

Also: there’s a Free tier, and the Growth Plan includes live preview, release management, content history, basic support, and Strapi AI features.

5) Stability Focus

The team is actively closing GitHub issues and prioritizing the “paper cuts.” New features are great, but the near-term push is polishing the experience you already use daily.

You can find the full recording👇 highly recommend checking out the Plugin Deep Dive with Boaz.

Deep Dive: Plugins with Boaz

Boaz (Strapi Ecosystem Developer Advocate) joined to talk plugins—what’s possible, how the docs are improving, and how to build faster with plugin generators.

Why Plugins?

Plugins are like mini Strapi apps: a React admin frontend + a Node backend. They’re perfect for:

Custom dashboards and homepage widgets
Data ingest pipelines (e.g., social mentions → Strapi)
Admin-only tools (internal workflows, moderation, approvals)
Public endpoints to power front-ends or integrations

New: Plugin Generators (Demo)

Boaz showed a generator that creates a full content type inside a plugin, complete with:

Schema
Controller
Service
Router
Permission hooks in Users & Permissions

You can also generate single parts (like “just a controller”), and future templates may include homepage widgets or content-manager sidebar widgets. The goal: remove boilerplate so you can focus on logic.

Big picture: the docs for plugin APIs are being expanded so more “hidden” capabilities become discoverable and supported.

Community Starters You Can Use Today

TanStack Start + Strapi (community project): A starter with a dynamic landing page (via Strapi’s dynamic zones), blog with pagination and search, and auth (email + providers like GitHub). It’s meant to be extended and welcomes contributions.

Your browser does not support the video tag.

Project Repo

NOTM Next.js + Strapi: A well-structured monorepo starter with a video walkthrough (Docker, DB, front-end, back-end). Great if you want a production-minded baseline without reinventing the wheel.

Project Repo

Video setup guilde.

Both are helpful when you don’t want to start from zero and need working patterns for routing, data fetching, auth, and content modeling.

If you want to experiment this week, try:

Generating an OpenAPI spec and loading it into a client.
Turning on Media Library AI and uploading a few images.
Scaffolding a plugin with the generator and adding one homepage widget.
Cloning a starter and wiring it to your Strapi instance.

Got a cool plugin or starter? Reach out. We love showcasing community work in future calls. Thanks for being part of the Strapi journey!

Security Disclosure of Vulnerabilities: CVE-2025-3930, CVE-2025-53092, CVE-2025-25298, CVE-2024-56143, and CVE-2024-52588

Strapi — Thu, 13 Nov 2025 13:00:49 +0000

Disclosure Summary

Thanks to an X community member and some of our internal team, we have been notified and patched five security vulnerabilities:

CVE-2025-3930: No GHSA for this, CNA release (note it's in Polish): https://cert.pl/posts/2025/10/CVE-2025-3930/ and the CVE record: https://www.cve.org/CVERecord?id=CVE-2025-3930
CVE-2025-53092: GHSA-9329-mxxw-qwf8
CVE-2025-25298: GHSA-2cjv-6wg9-f4f3
CVE-2024-56143: GHSA-495j-h493-42q2
CVE-2024-52588: GHSA-v8wj-f5c7-pvxf

Per our security policy, we are performing our due diligence by publicly disclosing these vulnerabilities after careful testing, validation, communication, and our mandatory waiting period. For further details of the patched vulnerabilities, please refer to the information below or consult the linked GitHub Advisories.

We would like to thank the following community members for their participation in our security program:

CVE-2025-3930: Cert.pl and their reporting party
CVE-2025-53092: ghostvirus
CVE-2025-25298: Sinan
CVE-2024-56143: Boegie19
CVE-2024-52588: Võ Thành Minh Khôi

Immediate resolution steps for all vulnerabilities disclosed here

To immediately resolve all vulnerabilities detailed in this post, please update all of your Strapi packages to version v5.24.2 OR v4.25.24 (excluding CVE-2025-3930).

CVE-2025-3930: Lack of JWT Expiration after Log Out in Strapi

Summary of CVE-2025-3930 Vulnerability Details

CVE: CVE-2025-3930
CVSS v3.1 Vector: CVSS:4.0/AV:N/AC:H/AT:N/PR:N/UI:N/VC:L/VI:L/VA:N/SC:N/SI:N/SA:N
Affected Versions: <5.24.2
How to Patch: Immediately update your Strapi to version >=5.24.2

Description of CVE-2025-3930

Strapi uses JSON Web Tokens (JWT) for authentication. After logout or account deactivation, the JWT is not invalidated, which allows an attacker who has stolen or intercepted the token to freely reuse it until its expiration date (which is set to 30 days by default, but can be changed).
The existence of the /admin/renew-token endpoint allows anyone to renew near-expiration tokens indefinitely, further increasing the impact of this attack.

It should be noted that this vulnerability really only impacts the admin panel since it was the only part of the application that utilized token renewals. Normally, it would require an admin's token to be leaked either intentionally (malicious authorized actor) or via some kind of MITM attack.
The threat probability of this is quite low in real-world use cases.

You can see the fix PR here (there were a few other hotfixes as well). In addition to resolving the vulnerability, we did heavily refactor the authentication system (for both the Admin Panel and Users & Permissions).
For the Admin Panel, applications will default to the new system; for Users & Permissions, the legacy system will remain the default until Strapi 6.
We recommend reviewing the implementation for Users & Permissions and refactoring frontend usage to switch to this new system. You can find the documentation here.

This new system for both the Admin Panel and Users & Permissions is a complete session management system, including refresh tokens and logout endpoints. Sessions are tracked per user, per device, and per session.

IoC's for CVE-2025-3930

If you have persistent logs (either through your cloud service or process managers such as PM2), review your log file and look for large volumes of calls to the /admin/renew-token endpoint.
This is a normal endpoint, but if there are multiple calls (especially from the same IP Address) in addition to pure admin-api calls (without the admin panel frontend calls); this could be an indication that the endpoint was abused.

An example for log filtering using grep: grep '/admin/renew-token' /path/to/strapi/logs/*

CVE-2025-53092: CORS Misconfiguration Leads to Sensitive Data Exposure

Summary of CVE-2025-53092 Vulnerability Details

CVE: CVE-2025-53092
CVSS v3.1 Vector: CVSS:3.1/AV:N/AC:L/PR:N/UI:R/S:U/C:H/I:N/A:N
Affected Versions: < 5.20.0
How to Patch: Immediately update your Strapi to version >= 5.20.0

Description of CVE-2025-53092

Strapi was misconfigured by default to set the Access-Control-Allow-Origin header to any request based on the domain the request was sent from.
While-list validation was not always correct based on the Origin header.

IoC's for CVE-2025-53092

Due to the nature of this vulnerability, there are no direct methods to determine if you are impacted other than reviewing network logs.

CVE-2025-25298: Weak Password Length Validation

Summary of CVE-2025-25298 Vulnerability Details

CVE: CVE-2025-25298
CVSS v3.1 Vector: CVSS:3.1/AV:L/AC:H/PR:L/UI:R/S:U/C:N/I:N/A:N
Affected Versions: < 5.10.3
How to Patch: Immediately update your Strapi to version >= 5.10.3

Description of CVE-2025-25298

Strapi utilizes bcrypt.js for password hashing. This package has a limit of 72 bytes, wherein if a password exceeds this byte limit, any additional bytes will resolve to the same hash as the 72-byte limit.

IoC's for CVE-2025-25298

Due to the way the hashing system functions (one-way), it's not possible to determine the byte size of previous passwords. Would advise forcing a password update after upgrading, as the patch limited password length to <73 bytes

CVE-2024-56143: Unauthorized Access to Private Fields via parms.lookup

Summary of CVE-2024-56143 Vulnerability Details

CVE: CVE-2024-56143
CVSS v3.1 Vector: CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:L/A:N
Affected Versions: > 5.0.0, < 5.5.2
How to Patch: Immediately update your Strapi to version >= 5.5.2

Description of CVE-2024-56143

It's possible to access any private fields by filtering them through the lookup query string parameter ?lookup[updatedBy][field]=somestring

Given that this specific parameter is not documented and not widely used by most users (in general, it's only used within the Admin Panel), the probability of an attack before the disclosure is extremely low.

However, any user who has not updated once disclosure occurs is at a VERY HIGH probability risk. It should also be noted that this vulnerability does not impact Strapi 4.

IoC's for CVE-2024-56143

If you have persistent logs (either through your cloud service or process managers such as PM2), review your log file and look for calls using this parameter in addition to typically sensitive fields such as password, registrationToken, or resetPasswordToken.
Strapi will not, by default, ever use lookup on these fields. Standard usage is only done on non-sensitive fields.

An example for log filtering using grep: grep -E 'lookup\[(createdBy|updatedBy)\]\[(password|resetPasswordToken|registrationToken)\]' /path/to/strapi/logs/*
It should be noted that this could also apply to usage of the content-api (users & permissions plugin), in which case you should review the logs for your content-type structure.
Advising all users to change their passwords is also recommended, and reviewing the database tables to remove any users who haven't completed registration (registrationToken is not null) and deleting/nulling any users with resetPasswordToken that haven't been used.

CVE-2024-52588: Server-Side Request Forgery in Webhook function

Summary of CVE-2024-52588 Vulnerability Details

CVE: CVE-2024-52588
CVSS v3.1 Vector: CVSS:3.1/AV:N/AC:L/PR:H/UI:N/S:U/C:H/I:N/A:N
Affected Versions: <4.25.2
How to Patch: Immediately update your Strapi to version >=4.25.2

Description of CVE-2024-52588

In the latest version of Strapi, in the function Settings -> Webhooks, the application allows us to input a URL in order to create a Webhook connection.
However, we can input into this field the local domains such as localhost, 127.0.0.1, 0.0.0.0,.... in order to make the Application fetch into the internal itself, which causes the vulnerability Server-Side Request Forgery (SSRF).

IoC's for CVE-2024-52588

Review your webhooks to look for any that point to internal resources unrelated to your Strapi application.
Given the nature of this vulnerability, only an authorized user with the correct permissions could utilize this to effectively execute port scans of internal resources.

Commitment to Responsible Disclosure

We at Strapi do believe in responsible disclosure. In the case of these vulnerabilities, we have worked with the security researcher to ensure that the vulnerabilities were patched before the full disclosure of the vulnerabilities. Once a vulnerability is patched, we add a notice to our release notes to inform users that there was a security vulnerability, but initially wanted to delay detailed disclosure for a few weeks to give time for users to upgrade before the release of the full disclosure. As an additional step, we immediately notified our customers via several emails beforehand to ensure they were aware of the vulnerabilities and to upgrade their Strapi servers.

In this case, we believe that delaying the detailed disclosure was important to ensure that users had the time required to upgrade their Strapi servers before making the details of each vulnerability public, thus placing that information in the hands of bad actors. We also believe that the security researcher was very professional and responsible in handling the vulnerabilities, and we are very thankful for their work in helping us improve the security of Strapi.

We urge anyone who believes they have discovered a security vulnerability to assist us in responsibly disclosing the vulnerability to us by submitting a GitHub Advisory on our main repo or by contacting our security team via security@strapi.io.

Thanks,

The Strapi Security Team

A Guide to Role-Based Access Control (RBAC) in Strapi

Strapi — Tue, 04 Mar 2025 12:23:01 +0000

Introduction

Before modern web apps, software ran as standalone programs on personal computers or Local Area Networks (LANs).

These software programs were built for tasks like accounting or inventory management. These programs served small, controlled groups, such as IT staff or specific employees. Because they were isolated from the internet, security was straightforward: shared passwords or basic permissions sufficed. Physical access mattered more than digital threats.

Today, web applications reach millions, demanding robust security measures. Role-based access control (RBAC) meets this need, assigning permissions based on user roles to protect resources like content and features. In a connected world, RBAC is a must-have.

Prerequisites

To follow along in this article, one should have a basic understanding of the following:

Familiarity with Strapi CMS(Content Management System).
Basic understanding of Software Development and web applications.

What you will Learn in this Article

This article is written to provide basic to deep insights into role-based access control. By the end of this article, you would have understood the following;

The meaning of RBAC (Role Based Access Control) generally and in context to software applications.
How RBAC works in a CMS like Strapi.
How to manage custom conditions for roles in the Strapi Admin Panel.
How to manage end user accounts in client applications.
The importance of RBAC in applications, Strapi in particular.

What is Role Based Access Control (RBAC)

Role-based access control (RBAC) is an access control method that assigns permissions to users in a system based on their roles rather than specifying benefits individually.

Understanding RBAC in Web Applications

In RBAC, permissions to access resources are based on job responsibilities, and users are assigned to these roles. With this assignment, permissions are thereby attached to the roles.

RBAC can be applied not just in software but even in organizations(e.g., banks) where only authorized staff can access the bank vault at certain intervals.

These real-world applications mirror how RBAC works in software, where roles like “Admin,” “Editor,” and “Viewer” define access levels. In software applications, RBAC provides security and efficiency by enabling centralized permission management.

Instead of assigning permissions to individual users, changes are made at the role level, instantly affecting all users assigned to that role. This makes software systems easier when scaling or performing security audits in organizations.

For this article, we will focus on how role-based access control can be implemented in software applications to enhance security and simplify user management.

Benefits of Strapi Role-Based Access Control

Role-based Access Control presents multiple benefits for all users(admins, end-users) of an application, due to its specific nature.
Strapi RBAC presents more benefits, especially due to the granular control it grants administrators; below are some of these benefits explained.

Ease of Administrative Workloads: Strapi RBAC simplifies administrative workload, admins can easily create, add and switch roles across the application without any downtime or delays.
Compliance: RBAC improves privacy and confidentiality in applications by managing access to data and its usage.
Team Efficiency: Clearly defining permissions for roles improves efficiency by enabling specialists to handle particular tasks.
Granular Control: Strapi enables admins specify permissions for CRUD(create, read, update, delete) actions content types or API endpoints.
Security: By ensuring users only have access to the resources required for their role, Strapi RBAC reduces the risk of security data breaches in organizations and public user data.
Customization: Admins can create custom conditions for roles in an application, allowing for flexibility without the need for technical knowledge.
Collaboration: Teams with different member responsibilities (e.g., developers and content creators) can work in harmony without interfering with each other's tasks.
Scalability: Appropriately defined permissions for roles simplify scalability as organizations grow with responsibilities.
Ease of Development: Access control management from the admin panel reduces the need for custom control logic from the backend.

How Users Interact with Systems Based on Roles.

Users interact with software systems by performing 4 main actions, create, read, update, delete. To explain this properly, we would take an individual who signed up on a task management application for example.

Create: This refers to any operation that creates an entry on the software. For this user, it includes creating an account or creating a task for the day. It adds a record/store to the database, which can then be read, updated or deleted later.
Read: A read operation means retrieving data from where it is stored. For this user, it would mean viewing the daily tasks that are already set. The data read could be created by that same user or another.
Update: This enables an application user modify an entry already created in a software or system. In the task management application, it could mean changing the task name, or time which it is due etc.
Delete: This is a very powerful operation that should always be treated with caution as most times it cannot be reversed. On the task management application it would mean deleting a completed task or deleting the users account from the platform.

RBAC Example

To effectively implement RBAC in software, it is important to analyze the actions to be performed by your users. This way you can assign roles accurately based on organizational hierarchy.

A good example can be seen in the illustration below, and the following points need to be understood.

The Administrator is the principal and has all privileges.
There are three other user roles; Author, Editor, and Reader with their privileges listed just below.
Users are then assigned to roles with privileges required by their job.
Each role can have multiple users assigned to it.

The above illustration seeks to demonstrate RBAC in the context of a blog platform, The Author has the permissions to write blog posts and edit only his blog posts. The Editor approves, publishes and can also edit blogs too. A reader has permission to view and like posts only.

In a real-life example of a blogging platform like Hashnode or Dev.to, for example, they have very robust RBAC systems.

On blogs written by others, you have the role of a reader who can only like posts and comment meanwhile on your blog posts you have permissions to create, read, update and delete posts.

Only the site administrators have the ability to modify site settings which affect the entire platform. We have thoroughly explained RBAC in concept, let us now focus how it works in Strapi.

How RBAC Works and Default Roles in Strapi CMS

Strapi is a headless CMS used for building modern web applications which can be accessed by millions of individuals, as a result it offers in-built tools and techniques for implementing role based access control as this ensures application security, consistency and end user satisfaction.

In Strapi, there are 3 roles by default in a new application.

Super Admin: Users assigned to this role can access and manage all features/settings of the application.
Editor: An editor is allowed to proofread and publish content, including those of other users.
Author: Can manage the content they have created only.

You can manage roles in Strapi CMS from your admin dashboard in the Administration Panel under the Roles sub-section as seen below.

In your admin panel, navigate using the address below.

Setings > Administration panel > Roles

Managing Content Types for User Roles in Strapi

A Content Type in Strapi is like a template for the information to be managed on a software application powered by a CMS (content management system) like Strapi. Content types define the structure of your application's data.

Strapi offers two main types of collection types:

Single Types: This content type can manage only one entry and is used to model unique content that exists only once in a platform such as 'Homepage', 'About Us' etc.
Collection Types: A collection type is ideal for repeatable data, it supports multiple entries such as 'Blog Posts', 'Users', 'Equipment' etc.

Each type can be customized with fields like text, media, and numbers with the ability to add relations to each other. They are managed in the Content-type builder of the Strapi administration panel. The content type builder is the core plugin of Strapi and offers features for robust content management. You can read more about the Content-type builder here.

Enabling Collection Types Permissions for Default Roles

To truly gain an understanding, it often helps to use relatable examples of a real-life application of the software. For this section of the article, we will be using the context of an inventory application in use by an equipment rental company using an inventory application.

To enable content type permissions, navigate to the roles sub-section of the admin panel.

On the page above, we can observe the following Super Admin has control over all site settings and Collection Types.

Let us take a look. In your roles sub-section, click the Super Admin role.

The image above shows that the Create, Read, Update, and Delete actions for all collection types are allowed for the Super Admin and cannot be changed by default.

In Strapi, other roles except the Super Admin can be reassigned to new users in the users sub-section of your administration panel. This can be to enable a user perform certain actions that are not allowed on the current role. Take a look at the demonstration below.

In the above image, we edited a user's role from Author to Editor. Now we can assign the permission for the Editor to perform Update, Delete and Pubsdlish actions on all Collection Types.

Now, the user only has the permissions specified for the Editor role in the roles sub-section of the admin panel.

As you can see below, only the edit function is available for the Equipment, Rental and User content types.

These default roles can be modified and made to fit any permission specification according to the Collection Types of your application needs.

Creating Custom Roles in Strapi Admin Panel

You can create custom roles to be assigned to admin users of the Strapi admin panel. This is most advisable in scenarios where total uniqueness is needed, thus requiring designated names and custom permissions other than the default.

All roles, both default and custom, can be managed in the roles sub-section of the Administration panel.

The example below would explain through the example of an inventory application as mentioned before. We will continue to the relate the concepts to the inventory application as we have been doing earlier on in this article.

Example

Let us assume a custom role "Rental Manager" is needed, apart from the admin this role alone would have permissions to the rentals collection type to manage the delivery of newly rented equipment and already active rentals.

This will enable specialization thus improving efficiency in the organization. The following steps can be taken to achieve this goal.

Head over to the roles sub-section of the administration panel and click "Add new role".

Input the role name "Rental Manager" and enable CRUD operations for the Rental Collection type only.
Click the save button at the top-right corner of the page.

The flexibility of Strapi RBAC is what makes it one of the best, ensuring that only a user of the admin panel assigned to the "Rental Manager" role has access to the rental collection type on the admin panel and is responsible for its management alone.

Creating Custom Conditions for Roles

When building applications from scratch, most developers make use of custom middleware and policies to ensure custom conditions are met before certain permissions are assigned to user roles.

With Strapi, you can create these same custom conditions with ease in the admin panel or through code. Assume that in the inventory software both company staff and customers can login.

To create custom conditions in Strapi, you would have to observe certain procedures accurately.

Declare New Condition: A new condition is declared as an object, it can have five possible properties such as: displayName, name, category, plugin, handler. A code sample illustrates the explained below.

{
  displayName: 'rental page access',
  name: 'rental-page-access',
  async handler(user) {
    return user.email.endsWith('@inventory.com');
  },

Use a condition handler: A handler is used to verify the condition; it is a function that returns a query object or a boolean value (true/false). It is very useful when performing checks in custom conditions.

//handler to return a query object
async handler(user) {
    return { price: { $gt: 50 } };
  },


 //handler to return a boolean value
 handler: () => {
 new Date().getHours() === 17;
 }

The examples below will shed more light and detail on these concepts as they might seem abstract at once.

Register the Condition: To enable availability in the administration panel, conditions should be declared and registered in the index.ts/js file in the src folder of your Strapi project. Both single and multiple conditions can be registered.

export default async () => {
  await strapi.admin.services.permission.conditionProvider.register(condition);
};

The code block above shows the register method being exported. "Read in detail" the example below for understanding.

Example:

Imagine you want to write a custom condition that enables only company staff with emails that end in "@inventory.com" to access the rentals and statistics page of the application, and then end-users with other emails are restricted to the equipment availability page.

This would enable the company keep its data private while enabling end users still hire equipment all on the same application.

A sample statistics page restricted to "Staff Only"

You would achieve this custom condition in the index.js(or index.ts) file of your Strapi application.

const condition = {
  displayName: 'rental page access',
  name: 'rental-page-access',
  async handler(user) {
  // the company email domain is specified here'inventory.com'
    return user.email.endsWith('@inventory.com');
  },
};

//this code below registers the condition in Strapi
export default async () => {
  await strapi.admin.services.permission.conditionProvider.register(condition);
};

You can see that the above code block contains all steps mentioned above, a new condition object with a handler plus the conditionProviderregister() used in the export function last.

If you want to explicitly associate this custom condition with a plugin in the admin panel, you could also add the plugin property in the condition object.

plugin: "admin"

You can also go further to say restrict access to a particular equipment on the application once the available quantity is less than "10". In a company setting, this would be to reduce the risk of processing orders on equipment not currently available.

For a scenario like this, a condition handler that returns a can be used; this returns a boolean value (true or false)
The code block below can be applied.

export default async () => {
  await strapi.admin.services.permission.conditionProvider.register({
    displayName: 'Equipment Quantity under 10',
    name: 'equipment-quantity-under-10',
    plugin: 'admin',
    handler: { amount: { $lt: 10 } },
  });
};

You will notice that the plugin property was included in the code block above to associate the custom condition with the admin plugin in the Strapi panel.

Let's say for instance that you have multiple custom conditions, you can pass them as an array of objects and then register the condition using the conditionProvider.registerMany() method instead of the conditionProvider.register() method used for single conditions.

const conditions = [
  {
    displayName: "rental page access",
    name: "rental-page-access",
    async handler(user) {
      // the company email domain is specified here'inventory.com'
      return user.email.endsWith("@inventory.com");
    },
  },
  {
    displayName: "Equipment Quantity under 10",
    name: "equipment-quantity-under-10",
    plugin: "admin",
    handler: { amount: { $lt: 10 } },
  },
];

export default async () => {
  await strapi.admin.services.permission.conditionProvider.registerMany(
    conditions,
  );
};

NOTE: Custom conditions for collection types can be set in the admin panel user interface too.

For example, in the illustration below, enable the Author role for some custom conditions.

To enable these custom conditions, click on the settings button to the right of that particular content type. A modal will pop-up enabling you to update, delete and publish content since this is for the editor role.

From the above illustration, you can see that the Author can update, delete and publish when he has the same role as the creator. A custom role like this one has benefits in an organization ensuring that the user can update, delete and publish as long his/her role is the same with the original creator while maintaining clear distinct permissions.

Managing End-User Accounts in Strapi RBAC

One of the features that grants Strapi admins granular control over users is the Users & Permissions Plugin. It grants full access to tools and functionlaity to manage users on the client applications built on Strapi.

The Users & Permissions Plugin enables admins manage users as a Collection type in the Strapi admin panel.

The image below shows how end-users are managed as a collection type.

Already registered end-users are displayed under the User collection type, which is powered by the "Users and permissions" plugin. The image above is an accurate example.

Creating an End-user in Strapi

These can be done through two different methods:

Through the Admin Panel.
By making a POST request through the Strapi content API.

Through The Admin Panel

In the user section of the Collection Types, click the "create new entry" button at the top right of the page.

You will be required to fill in the appropriate information and then save the information for the User Collection type.

Taking a look at the User Collection type, we can see that a new user has been added below.

Managing end-user roles is an integral part of role-based access control in Strapi, the Users & Permissions plugin enables admins easily manage them the right way.

Creating End-Users through the API Endpoint

Creating new end-users can also be done programmatically by making post requests to the appropriate endpoint. This is more convinient when enabling users register through a frontend application built on-top of Strapi.

In your Strapi admin panel, open the roles sub-section under the Users & Permissions Plugin, you would see the page below display.

Select the Authenticated option as seen below, scroll to the Users-permissions option and enable the "select all" option under the user section.

With this step done, you can make POST requests in your application to create new users through your frontend application.

An example from a Next.js application is shown below.

const sendDetails = async () => {
  try {
    const response = await fetch(
      "http://localhost:1337/api/auth/local/register",
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
        },
        body: JSON.stringify(user),
      },
    );
    const data = await response.json();
    if (response.ok) {
      setNotification({
        message: "User registered successfully, redirecting to dashboard",
        type: "success",
      });
      // to delay the re-routing by 3 seconds
      setTimeout(() => {
        router.push("/overview");
      }, 3000);
    } else {
      //display notifications if registration is not successful
      setNotification({
        message: "An error occured, please try again!",
        type: "error",
      });
    }
    console.log(data);
  } catch (error) {
    console.error("Error registering user:", error);
    console.log(error);
  }
};

sendDetails();

Conclusion

RBAC is unarguably one of the most important concepts in this era of modern applications with complexity and high user interaction.
With Strapi, Role-based access control is efficiently executed as it offers just the same benefits with flexibility with an "ease of execution" design.

When building applications, it is important to carefully map the responsibilities and activities that would to be performed on a routine basis for the application. You can then create roles and assign these responsibilities in your application while observing hierarchy and, lastly, assign users to the roles according to job responsibilities.
This ensures application stability, privacy, and security, thus increasing the ability to scale if need be.

Want to learn more about Aministrator roles RBAC in Strapi? Click here!

Build modern websites with the most customizable Headless CMS. Get started with Strapi 5!

Forem: Strapi

Strapi release roundup: everything that changed between January and February 2026

Admin UI & mobile experience

Content Manager

Media Library

Developer experience

What's next

Demystifying Strapi's Populate & Filtering

Introduction

Why is This Discussion Necessary?

Setting Up the Example Project

Clone the Repository

Install Dependencies

Seed the Database

Start the Application

Getting Started with Population and Field Selection

Permissions Matter

Key Takeaways

Exploring Population and Field Selection with Examples

Populate Everything First Level Deep with the Wildcard Operator

Populate Specific Relations

Populate Nested Relations

Populate and Field Select

Complex Population and Field Selection

Step 1: Basic Wildcard Populate

Step 2: Populate All Nested Data with on

Step 3: Selective Population with on

Filtering Data

Top-level Filtering Example

Filtering by Relation Example

Complex Filtering

Migrating from Strapi 4 to Strapi 5

Response Format Changes

Temporary Compatibility

New Features to Leverage

Quick Reference: Response Format Comparison

Conclusion

Additional Resources

Fixing ISR Revalidation Across Kubernetes Replicas on strapi.io

Context

The Cache That Nobody Else Knew About

Three Approaches That Didn't Work

What Actually Worked: Redis Pub/Sub

Walking Through the Implementation

What We Learned

References

Let's Build A Strapi Plugin To Integrate Vercel’s AI SDK In Our Next.js 16 Project

What We're Building

Key Features

Architecture Overview

System Architecture

Request Flow Patterns

Project Structure

Technology Stack

Backend (Strapi Server)

Frontend (Next.js Client)

AI Services

Important: UIMessage vs ModelMessage (AI SDK v6)

Part 1: Setting Up Strapi

Step 1.1: Create a New Strapi Project

Step 1.2: Project Structure After Creation

Step 1.3: Configure Environment Variables

Step 1.4: Verify Strapi Installation

Part 2: Building the AI SDK Plugin (Our first Strapi Plugin)

Plugin Architecture

Step 2.1: Using Strapi Plugin SDK to Scaffold Our Plugin

Step 2.2 Install the AI SDK dependencies

Step 2.3: Plugin Structure Overview

Phase 1: Plugin Configuration & Initialization

Step 2.4: Configure the Plugin in Strapi

Step 2.5: Create Basic Types

Step 2.6: Create the AI SDK Manager (Basic Version)

Step 2.7: Create the Register Hook

Step 2.8: Verify Plugin Initialization

Phase 2: Basic Text Generation (Non-Streaming)

Step 2.9: Add generateText to AISDKManager

Step 2.10: Create the Service

Step 2.11: Create the Controller

Step 2.12: Create the Route

Step 2.13: Test with curl

Step 2: Populate All Nested Data with `on`

Step 3: Selective Population with `on`

Add the `askStreamAI` function to `lib/api.ts`:

Create `hooks/useAskStream.ts`:

Update `hooks/index.ts`:

Create `components/AskStreamExample.tsx`:

Update `components/index.ts`:

Update `app/page.tsx` to include both examples:

Create `components/ChatExample.tsx`:

Update `components/index.ts`:

Update `app/page.tsx` to include all three examples: