feat: refactor edgemiddleware into middlewareMode adapter feature

[leekeh]

Changes

Refactor edgeMiddleware option into a more generic middlewareMode, creating space for future options.

• Deprecate edgeMiddleware in core and all adapters
• Create new Adapter Feature called middlewareMode
• Implement and expose the option in the included adapters.
• Automatically map edgeMiddleware to middlewareMode: edge for backwards compatibility
• Add middlewareMode to the SSR manifest

Context

Currently, middleware runs on static pages during build, and on dynamic pages after build. There is the need to customize this behavior, specifically to run middleware on static pages, for example to add an authentication check.

Some adapters have a way to implement this using edgeMiddleware, but this is not possible for all adapters, since not all environments support edge middleware. It would be better to have a generic way to define when middleware should run. We call this new option middlewareMode.

In this first PR, I'm focusing on preparing the configuration for these new features, without adding them yet. In a subsequent PR, implementations for on-request and always options for middlewareMode will be added.

Mode	Build-time (prerendered pages)	Request-time (SSR pages)	Request-time (prerendered pages)	Use case
"classic" (default)	✅	✅	❌	Today's default. Middleware affects static pages only at build time.
"always"	✅	✅	✅	Middleware runs everywhere. Good for auth, A/B testing, personalization on all pages.
"on-request"	❌	✅	✅	Middleware only runs at request time. For runtime-only concerns (auth headers, sessions).
"edge"	❌	❌ (separate bundle)	❌ (separate bundle)	Middleware deployed as a separate edge function (Vercel, Netlify). Formerly known as edgeMiddleware config option.

Related discussions:

• Allow running middleware on-request for prerendered pages roadmap#869
• feat: add support for running full middleware on static pages #14617 (comment)

Testing

Since this is a refactor that should not change any existing functionality, no new tests were added. Existing tests should pass.

Docs

withastro/docs#13277

/cc @withastro/maintainers-docs for feedback!

[changeset-bot]

🦋 Changeset detected

Latest commit: 804801e

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[codspeed-hq]

Merging this PR will not alter performance

✅ 18 untouched benchmarks

---

_{Comparing leekeh:feat/step-1 (804801e) with main (98ea30c)}

[ematipico]

I love where this is heading! As for the docs, developers are responsible to update/add the docs themselves, so you'll have to send a PR to the docs repository.

As for the requested changes, let's remove the options that were added to the cloudflare and node adapter.

As for the changeset, astro must be a minor because we're adding a new "feature", meaning a new option

[sarah11918]

Hi @leekeh ! Thanks for being so receptive to Ema's feedback! Just giving some more advice on the changeset from Astro Docs here!

We have guidance and models to get you started in our Docs contributing docs: https://contribute.docs.astro.build/docs-for-code-changes/changesets/

Please take a look at this guide and see if you can match our format/style a little more closely. Then, I'm happy to come in and help you polish them up! The main idea is, you're giving people a new feature and we want to make sure that the changeset shows it off and hypes it up! That means making it clear who this is for, and why/how they might want to use it.. and why it's cool or what it unlocks! When it replaces something existing, we also want to be extra explicit about how to update their own project code, and what to look for to make sure they got it right.

There are examples on that page that will give you an idea! I'll be checking back in later, but don't hesitate to ask questions in the mean time!

[leekeh]

Hi @leekeh ! Thanks for being so receptive to Ema's feedback! Just giving some more advice on the changeset from Astro Docs here!

We have guidance and models to get you started in our Docs contributing docs: https://contribute.docs.astro.build/docs-for-code-changes/changesets/

Please take a look at this guide and see if you can match our format/style a little more closely. Then, I'm happy to come in and help you polish them up! The main idea is, you're giving people a new feature and we want to make sure that the changeset shows it off and hypes it up! That means making it clear who this is for, and why/how they might want to use it.. and why it's cool or what it unlocks! When it replaces something existing, we also want to be extra explicit about how to update their own project code, and what to look for to make sure they got it right.

There are examples on that page that will give you an idea! I'll be checking back in later, but don't hesitate to ask questions in the mean time!

Hi @sarah11918 :)
Thanks for the info, I wasn't aware about these specific guidelines. I updated the changeset files to use the present tense verb format, but I'm not sure what else needs to be tweaked. I tried to be explicit on the changes with the diff example and the needed changes for the users. Let me know if anything else seems incorrect.
There is not much of a new feature here either, because that will be mainly in the next step, so this one is just a preparation of that and a refactor. So the next changesets will be more hype, I promise ^^

[sarah11918]

Thanks, @leekeh , these changesets look great! I left some tiny comments for your consideration. They are very minor, but I always like to let people know what our typical style is because the more consistent we are, the easier it is for people to get used to our changelogs.

[sarah11918]

@ematipico Should the @astrojs/netlify and @astrojs/vercel changesets also be minor vs patch, because the user will have to update to a new config option? (vs the Node.js adapter which is all internal and only a refactor?)

That's the only thing I spot still!

[sarah11918]

Also commenting that the accompanying docs PR is approved, so docs is happy whenever this PR is ready!

[ematipico]

@ematipico Should the @astrojs/netlify and @astrojs/vercel changesets also be minor vs patch, because the user will have to update to a new config option? (vs the Node.js adapter which is all internal and only a refactor?)

That's the only thing I spot still!

Ah yes, they should be minor too!