Skip to content

Add middleware customization guide for Strapi Cloud production environment #3148

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
raulbalestra wants to merge 5 commits into
base: main
Choose a base branch
from
+259 −5
Open

Add middleware customization guide for Strapi Cloud production environment #3148

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
729b8f4
Add middleware customization guide for Strapi Cloud production enviro…
raulbalestra May 11, 2026
bb53c66
Address review feedback on middleware guide
raulbalestra May 11, 2026
646c7fb
Apply inline review feedback from derrickmehaffy
raulbalestra May 11, 2026
806aa5d
Fix code block titles in upload.md Security Middleware section
raulbalestra May 11, 2026
5344a28
Apply structural simplification per reviewer feedback
raulbalestra May 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
242 changes: 242 additions & 0 deletions docusaurus/docs/cloud/advanced/middlewares.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,242 @@
---
title: Middleware Configuration for Strapi Cloud
displayed_sidebar: cloudSidebar
description: Configure custom middlewares for your Strapi Cloud production environment.
canonicalUrl: https://docs.strapi.io/cloud/advanced/middlewares.html
tags:
- configuration
- middlewares
- CORS
- Content Security Policy
- CSP
- production
- Strapi Cloud
- Strapi Cloud configuration
- Strapi Cloud project
---

# Middleware Configuration for Strapi Cloud

<Tldr>
On Strapi Cloud, middleware customizations must go in `config/env/production/middlewares`. Changes to the global config file are overwritten on deploy.
</Tldr>

:::prerequisites

- A local Strapi project.
- A Strapi Cloud project (see [Getting Started](/cloud/getting-started/deployment)).

:::

On Strapi Cloud, `NODE_ENV` is always set to `production`. The platform applies its own production-level middleware configuration on deploy. Any changes to the global `config/middlewares` file are overwritten and will not take effect. For available middleware options, see [Middlewares configuration](/cms/configurations/middlewares).

To apply custom middleware configuration on Strapi Cloud, place your changes in:

<Tabs groupId="js-ts">
<TabItem value="js" label="JavaScript" default>

```
config/env/production/middlewares.js
```

</TabItem>
<TabItem value="ts" label="TypeScript">

```
config/env/production/middlewares.ts
Comment thread
pwizla marked this conversation as resolved.
```

</TabItem>
</Tabs>

:::caution
The `config/env/production/middlewares` file **fully replaces** the global middleware array. Your file must include the complete list:

- `strapi::errors`
- `strapi::security`
- `strapi::cors`
- `strapi::poweredBy`
- `strapi::logger`
- `strapi::query`
- `strapi::body`
- `strapi::session`
- `strapi::favicon`
- `strapi::public`

Both CSP and CORS customizations can be combined in the same file.
:::

:::note
- You can keep your existing `config/middlewares` file as-is as it will not cause conflicts. The production-specific file takes precedence on Strapi Cloud.
- Upload size limits on Strapi Cloud are enforced at the infrastructure level (Cloudflare gateway) and cannot be overridden via the `strapi::body` config. For external storage options, see [Upload Provider Configuration](/cloud/advanced/upload).
:::

## Custom Content Security Policy (CSP)

If you use an external upload provider, allow its domain in the CSP directives. Without this, the Strapi Admin panel will block images and media from those sources.

Create or update `config/env/production/middlewares`:

<Tabs groupId="js-ts">
<TabItem value="js" label="JavaScript" default>

```js title="config/env/production/middlewares.js"
module.exports = [
'strapi::errors',
{
name: 'strapi::security',
config: {
contentSecurityPolicy: {
useDefaults: true,
directives: {
'connect-src': ["'self'", 'https:'],
'img-src': [
"'self'",
'data:',
'blob:',
'market-assets.strapi.io',
'your-custom-domain.com', // replace with your provider domain
],
'media-src': [
"'self'",
'data:',
'blob:',
'market-assets.strapi.io',
'your-custom-domain.com', // replace with your provider domain
],
upgradeInsecureRequests: null,
},
Comment thread
pwizla marked this conversation as resolved.
},
},
},
'strapi::cors',
'strapi::poweredBy',
'strapi::logger',
'strapi::query',
'strapi::body',
'strapi::session',
'strapi::favicon',
'strapi::public',
];
```

</TabItem>
<TabItem value="ts" label="TypeScript">

```ts title="config/env/production/middlewares.ts"
export default [
'strapi::errors',
{
name: 'strapi::security',
config: {
contentSecurityPolicy: {
useDefaults: true,
directives: {
'connect-src': ["'self'", 'https:'],
'img-src': [
"'self'",
'data:',
'blob:',
'market-assets.strapi.io',
'your-custom-domain.com', // replace with your provider domain
],
'media-src': [
"'self'",
'data:',
'blob:',
'market-assets.strapi.io',
'your-custom-domain.com', // replace with your provider domain
],
upgradeInsecureRequests: null,
},
Comment thread
pwizla marked this conversation as resolved.
},
},
},
'strapi::cors',
'strapi::poweredBy',
'strapi::logger',
'strapi::query',
'strapi::body',
'strapi::session',
'strapi::favicon',
'strapi::public',
];
```

</TabItem>
</Tabs>

:::tip
For a full list of upload providers and their required domains, see the <ExternalLink to="https://market.strapi.io/providers" text="Strapi Market"/>.
:::

## Custom CORS headers

If your frontend sends custom request headers (e.g. for authorization flows), you need to explicitly allow them in the CORS configuration. Placing this in the global `config/middlewares` file will not work on Strapi Cloud. Place it in `config/env/production/middlewares` instead.

<Tabs groupId="js-ts">
<TabItem value="js" label="JavaScript" default>

```js title="config/env/production/middlewares.js"
module.exports = ({ env }) => [
'strapi::errors',
'strapi::security',
{
name: 'strapi::cors',
config: {
enabled: true,
origin: [env('CLIENT_URL')],
headers: [
'Content-Type',
'Authorization',
'Origin',
'Accept',
'X-Requested-With',
'your-custom-header', // add any custom headers your frontend sends
],
},
},
'strapi::poweredBy',
'strapi::logger',
'strapi::query',
'strapi::body',
'strapi::session',
'strapi::favicon',
'strapi::public',
];
```

</TabItem>
<TabItem value="ts" label="TypeScript">

```ts title="config/env/production/middlewares.ts"
export default ({ env }) => [
'strapi::errors',
'strapi::security',
{
name: 'strapi::cors',
config: {
enabled: true,
origin: [env('CLIENT_URL')],
headers: [
'Content-Type',
'Authorization',
'Origin',
'Accept',
'X-Requested-With',
'your-custom-header', // add any custom headers your frontend sends
],
},
},
'strapi::poweredBy',
'strapi::logger',
'strapi::query',
'strapi::body',
'strapi::session',
'strapi::favicon',
'strapi::public',
];
```

</TabItem>
</Tabs>
14 changes: 9 additions & 5 deletions docusaurus/docs/cloud/advanced/upload.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -237,9 +237,13 @@ export default ({ env }) => ({

Due to the default settings in the Strapi Security Middleware you will need to modify the `contentSecurityPolicy` settings to properly see thumbnail previews in the Media Library.

:::caution
On Strapi Cloud, `NODE_ENV` is always set to `production`. Changes to the global `config/middlewares.ts` file are overwritten on each deploy and will not take effect. Place your Security Middleware customizations in `config/env/production/middlewares.ts` instead. See [Middleware Configuration for Strapi Cloud](/cloud/advanced/middlewares) for details.
:::

To do this in your Strapi project:

1. Navigate to `./config/middlewares.js` or `./config/middlewares.ts` in your Strapi project.
1. Navigate to `./config/env/production/middlewares.js` or `./config/env/production/middlewares.ts` in your Strapi project.
2. Replace the default `strapi::security` string with the object provided by the upload provider.

**Example:**
Expand All @@ -248,7 +252,7 @@ To do this in your Strapi project:
<Tabs groupId="upload-examples" >
<TabItem value="cloudinary" label="Cloudinary">

```js title=./config/middleware.js
```js title=./config/env/production/middlewares.js
module.exports = [
// ...
{
Expand Down Expand Up @@ -284,7 +288,7 @@ module.exports = [
</TabItem>
<TabItem value="amazon-s3" label="Amazon S3">

```js title=./config/middleware.js
```js title=./config/env/production/middlewares.js
module.exports = [
// ...
{
Expand Down Expand Up @@ -324,7 +328,7 @@ module.exports = [
<Tabs groupId="upload-examples" >
<TabItem value="cloudinary" label="Cloudinary">

```ts title=./config/middleware.ts
```ts title=./config/env/production/middlewares.ts
export default [
// ...
{
Expand Down Expand Up @@ -360,7 +364,7 @@ export default [
</TabItem>
<TabItem value="amazon-s3" label="Amazon S3">

```ts title=./config/middleware.ts
```ts title=./config/env/production/middlewares.ts
export default [
// ...
{
Expand Down
8 changes: 8 additions & 0 deletions docusaurus/sidebars.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -745,6 +745,14 @@ const sidebars = {
new: false,
},
},
{
type: 'doc',
id: 'cloud/advanced/middlewares',
label: 'Middleware configuration for Cloud',
customProps: {
new: false,
},
},
],
},
],
Expand Down
Loading