Add middleware customization guide for Strapi Cloud production environment by raulbalestra · Pull Request #3148 · strapi/documentation

raulbalestra · 2026-05-09T00:31:52Z

Description

Adds a new page cloud/advanced/middlewares documenting how to correctly configure custom middlewares on Strapi Cloud.

Why it's needed: On Strapi Cloud, NODE_ENV is always production and the platform injects its own middleware configuration at the production env level. This means changes made to the global config/middlewares.ts are silently overwritten on each deploy. Users must place their customizations in config/env/production/middlewares.ts instead, but this behavior is not currently documented anywhere.

What the page covers:

Explanation of why config/middlewares.ts changes don't apply on Cloud
How to use config/env/production/middlewares.ts as the correct override path
Common use case: custom CSP directives for external upload providers (Cloudflare R2, S3, etc.)
Common use case: custom CORS headers for frontend authorization flows
JavaScript and TypeScript examples for both cases
Notes on combining CSP + CORS in a single file, upload size limits, and Strapi v4/v5 compatibility

Also adds the new page to the Cloud sidebar under "Advanced configuration".

Related issue(s)/PR(s)

Closes #8943
Closes #8944

strapi-cla · 2026-05-09T00:31:57Z

All committers have signed the CLA.

vercel · 2026-05-09T00:31:58Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
documentation	Ready	Preview, Comment	May 18, 2026 2:01pm

…nment Closes #8943 and #8944: document that config/middlewares.ts is overwritten on Cloud deploys and that customizations must go in config/env/production/middlewares.ts. Covers CSP and CORS use cases with JS/TS examples following the docs style guide.

derrickmehaffy

Page is solid and the core explanation (NODE_ENV=production + injected prod config) is exactly right. A few changes before merge:

Not tied to a specific line:

cloud/advanced/upload.md still instructs users to edit the global ./config/middlewares.js for the strapi::security block (see its "Configure the Security Middleware" section, lines ~236–399). Per this new page, that won't take effect on Cloud. Either update upload.md to use config/env/production/middlewares.ts, or at minimum add a cross-link from upload.md → this page. Without it the two docs contradict each other.
No link to the standard middlewares reference (/cms/configurations/middlewares). Users will need the full options table for security, cors, etc. — add a pointer in the intro or a See also section.
Sibling pages (upload.md, email.md) open with a :::prerequisites block. Consider adding one (e.g. Cloud project, local Strapi v4.8.2+) for consistency.

derrickmehaffy · 2026-05-11T20:56:04Z

+Upload size limits on Strapi Cloud are enforced at the infrastructure level (Cloudflare gateway) and cannot be overridden via the `strapi::body` config. See [Upload Provider Configuration](/cloud/advanced/upload) for guidance on using external providers to handle larger file sizes.
+:::
+
+This behavior applies to all Strapi Cloud plans and to both Strapi v4 and v5.


v4 is EOL — referencing it here is unnecessary and may mislead users into thinking v4-specific guidance lives on this page. Drop the v4 mention.

- Add :::prerequisites block to middlewares.md for consistency with sibling pages - Add See also section linking to /cms/configurations/middlewares reference - Update upload.md Security Middleware section with :::caution pointing to config/env/production/middlewares.ts and cross-linking the new guide

- Tldr and path block now show both .ts and .js extensions - Add upgradeInsecureRequests: null to CSP directives (JS and TS) - CORS examples use factory function with env() helper instead of process.env - Rewrite caution block to explicitly state the production array fully replaces the global one and list all required middlewares - Remove v4 EOL mention

Update file path titles from ./config/middleware.js to ./config/env/production/middlewares.js (and .ts) to match the correct Cloud override path documented in the new middlewares guide.

raulbalestra · 2026-05-11T21:50:53Z

Hi @derrickmehaffy, all your feedback has been addressed:

Review comments:

Updated upload.md, added a :::caution block with a cross-link to this page, updated step 1, and fixed all 4 code block titles to point to config/env/production/middlewares.js|ts.
Added a ## See also section linking to /cms/configurations/middlewares.
Added a :::prerequisites block consistent with the sibling pages.
Inline comments:

Tldr and path block now show both .ts and .js.
Added upgradeInsecureRequests: null to the CSP directives in both JS and TS examples.
CORS examples now use a factory function with env('CLIENT_URL') instead of process.env.
Rewrote the caution block to state explicitly that the production file fully replaces the global array and listed all 10 required middlewares.
Removed the v4 mention.

pwizla · 2026-05-13T16:44:03Z

I've just done a complete review, technical writing wise, @raulbalestra
Thank you very much, the page will be super valuable to users 🙏

What needs to be changed before I can merge it: Drastically simplify the page structure. As it is, it doesn't quite fit with the rest of the docs pages. Here are my recommendations:

Completely get rid of the See also section: We don't have such sections in any other docs pages. Upload provider configuration link is already mentioned in the note above. Middlewares configuration link can be given in the intro. paragraph, after the prerequisites block
"Important notes" shouldn't be a section. Just remove the h2, keep the caution and note content exactly as they are, but move them:
- caution should be after the "To apply custom middleware configuration… " sentence in the intro
- merge the note about upload size limits with the note in the intro: You'll get a unique :::note Notes admonition block, with 2 bullet points
Delete the "Common use cases" h2 and upgrade the 2 h3s it contains to h2s. That will reduce the page structure/"on this page" navigation to the following simple structure: ## Custom Content Security Policy (CSP), ## Custom CORS headers

Hope everything is clear. I can make the changes for you if it's easier.

pwizla

Please apply all the structural changes I mentioned and your PR will be ready to merge 🚀 Thank you, Raul!

- Remove ## Common use cases: upgrade CSP and CORS sections to H2 - Remove ## Important notes H2: move caution after file path block - Merge two :::note blocks into one with 2 bullet points - Remove ## Related resources: add Middlewares config link to intro paragraph - Fix Tabs: add default to all JS TabItems, quote code block titles - Remove v4 version requirement from prerequisites

pwizla

LGTM now, thank you, Raul! 🚀

…nment (#3148) (#3193) * Add middleware customization guide for Strapi Cloud production environment Closes #8943 and #8944: document that config/middlewares.ts is overwritten on Cloud deploys and that customizations must go in config/env/production/middlewares.ts. Covers CSP and CORS use cases with JS/TS examples following the docs style guide. * Address review feedback on middleware guide - Add :::prerequisites block to middlewares.md for consistency with sibling pages - Add See also section linking to /cms/configurations/middlewares reference - Update upload.md Security Middleware section with :::caution pointing to config/env/production/middlewares.ts and cross-linking the new guide * Apply inline review feedback from derrickmehaffy - Tldr and path block now show both .ts and .js extensions - Add upgradeInsecureRequests: null to CSP directives (JS and TS) - CORS examples use factory function with env() helper instead of process.env - Rewrite caution block to explicitly state the production array fully replaces the global one and list all required middlewares - Remove v4 EOL mention * Fix code block titles in upload.md Security Middleware section Update file path titles from ./config/middleware.js to ./config/env/production/middlewares.js (and .ts) to match the correct Cloud override path documented in the new middlewares guide. * Apply structural simplification per reviewer feedback - Remove ## Common use cases: upgrade CSP and CORS sections to H2 - Remove ## Important notes H2: move caution after file path block - Merge two :::note blocks into one with 2 bullet points - Remove ## Related resources: add Middlewares config link to intro paragraph - Fix Tabs: add default to all JS TabItems, quote code block titles - Remove v4 version requirement from prerequisites Co-authored-by: raulbalestra <63110244+raulbalestra@users.noreply.github.com>

vercel Bot deployed to Preview May 9, 2026 00:33 View deployment

raulbalestra requested a review from derrickmehaffy May 9, 2026 00:36

raulbalestra force-pushed the cloud/add-middleware-customization-guide branch from 6b42f5c to 729b8f4 Compare May 11, 2026 20:36

vercel Bot deployed to Preview May 11, 2026 20:38 View deployment

derrickmehaffy requested changes May 11, 2026

View reviewed changes

vercel Bot deployed to Preview May 11, 2026 21:21 View deployment

vercel Bot deployed to Preview May 11, 2026 21:43 View deployment

Fix code block titles in upload.md Security Middleware section

806aa5d

Update file path titles from ./config/middleware.js to ./config/env/production/middlewares.js (and .ts) to match the correct Cloud override path documented in the new middlewares guide.

vercel Bot deployed to Preview May 11, 2026 21:47 View deployment

pwizla reviewed May 13, 2026

View reviewed changes

Comment thread docusaurus/docs/cloud/advanced/middlewares.md Outdated

pwizla requested changes May 13, 2026

View reviewed changes

pwizla self-assigned this May 13, 2026

pwizla self-requested a review May 18, 2026 12:42

pwizla marked this pull request as ready for review May 18, 2026 12:43

vercel Bot deployed to Preview May 18, 2026 13:54 View deployment

raulbalestra force-pushed the cloud/add-middleware-customization-guide branch from dccd817 to 5344a28 Compare May 18, 2026 13:59

vercel Bot deployed to Preview May 18, 2026 14:01 View deployment

pwizla requested a review from derrickmehaffy May 18, 2026 14:51

pwizla approved these changes May 18, 2026

View reviewed changes

pwizla removed the v5 Documentation PR that targets Strapi v5 label May 18, 2026

pwizla added this to the 6.26.0 milestone May 18, 2026

derrickmehaffy approved these changes May 19, 2026

View reviewed changes

pwizla merged commit 16d3441 into strapi:main May 20, 2026
5 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add middleware customization guide for Strapi Cloud production environment#3148

Add middleware customization guide for Strapi Cloud production environment#3148
pwizla merged 5 commits into
strapi:mainfrom
raulbalestra:cloud/add-middleware-customization-guide

raulbalestra commented May 9, 2026 •

edited

Loading

Uh oh!

strapi-cla commented May 9, 2026 •

edited

Loading

Uh oh!

vercel Bot commented May 9, 2026 •

edited

Loading

Uh oh!

derrickmehaffy left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

derrickmehaffy May 11, 2026

Uh oh!

raulbalestra commented May 11, 2026

Uh oh!

Uh oh!

pwizla commented May 13, 2026

Uh oh!

pwizla left a comment •

edited

Loading

Uh oh!

pwizla left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

raulbalestra commented May 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Related issue(s)/PR(s)

Uh oh!

strapi-cla commented May 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel Bot commented May 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

derrickmehaffy left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

derrickmehaffy May 11, 2026

Choose a reason for hiding this comment

Uh oh!

raulbalestra commented May 11, 2026

Uh oh!

Uh oh!

pwizla commented May 13, 2026

Uh oh!

pwizla left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pwizla left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

raulbalestra commented May 9, 2026 •

edited

Loading

strapi-cla commented May 9, 2026 •

edited

Loading

vercel Bot commented May 9, 2026 •

edited

Loading

pwizla left a comment •

edited

Loading