feat: middleware and virtual routes #7254
Conversation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
1 Ignored Deployment
|
| :::note | ||
| On all prerendered pages, the middleware runs only during the **build process** to create static pages and does not run in the deployed website. This applies to all pages in a `static` (SSG) project. This also includes prerendered pages in `hybrid` mode (default) and any pages in `server` mode with `export const prerender = true`. | ||
| ### Timing of middleware execution | ||
| By default, astro builds your project into a static site. In this [mode](https://docs.astro.build/en/basics/rendering-modes/), the middleware runs during the build as well. This allows the pages access to [`locals` object](#storing-data-in-contextlocals). Additionally, the static files can be served immediately since no server-side code is run on-request, ensuring fast response times. |
There was a problem hiding this comment.
Users ask "why not run middleware only on-request for static pages". So I tried to give the 2 reasons here:
- you'll need
Astro.locals, and - you probably don't want server-side code to run on-request if it can run ahead of time for performance.
There was a problem hiding this comment.
OK, so I see this less about timing and more about "why would I run middleware on static pages?"
In that framing, I can see adding something here. Let me try something!
|
|
||
| For on-demand rendered pages in `server` (default) or `hybrid` (with `export const prerender = false`) mode, the middleware runs in the deployed website when the route is requested. | ||
| In server deployments, if a request does not match a page in your project, astro will serve a 404 page. The middleware will be run during the rendering if the 404 page is on-demand rendered. If the middleware throws an error, a 500 error page will be served without running the middleware. |
There was a problem hiding this comment.
As far as prerendering and middleware execution is concerned, the 404 page behaves the same as any other page. However, it's worth reiterating because the 500 page does not.
When on-demand rendered, the 500 page will be rendered without the middleware if the middleware is the reason that the 500 error page has to be served (it errror'd).
sarah11918
added
add new content
There was a problem hiding this comment.
Hey @lilnasy ! It felt like there was more here than needed to be, and with the deleted lines and everything, it was awkward to use GitHub here to suggest changes.
So sorry, I just edited the file so I could do something different here. So, we're going to start small, and build back up with info that is truly needed. How is this for a start?
|
It is great for a start! Some bullet points we should get across:
It's fine to leave some out if they feel too specific of details. I'll add suggestions for these points. |
|
|
||
| ### Handling 404 pages | ||
|
|
||
| Middleware will run for an on-demand rendered route while Astro attempts to render a 404 page. However, it is up to the [adapter](/en/guides/server-side-rendering/) to decide whether that code runs. Some adapters may serve a platform-specific error page instead. |
There was a problem hiding this comment.
| Middleware will run for an on-demand rendered route while Astro attempts to render a 404 page. However, it is up to the [adapter](/en/guides/server-side-rendering/) to decide whether that code runs. Some adapters may serve a platform-specific error page instead. | |
| Middleware will run for an on-demand rendered route while Astro attempts to render a 404 page. However, it is up to the [adapter](/en/guides/server-side-rendering/) to decide whether that code runs. Some adapters may serve a platform-specific error page instead. | |
| If a page fails to render due to an error, astro will attempt to render your custom 500 page. If the error page is set to render on-demand, the middleware will run a second time for that request. | |
| If there is an error caused by middleware code, the on-demand rendered custom 500 page will be rendered without the middleware. `Astro.locals`, therefore, may be missing. |
There was a problem hiding this comment.
I'm trying to figure out how important it is to add these two paragraphs. 500 is generic error, right? Does it matter that middleware runs if the page 500s? What practical value is this to the author, and would they change anything about how they write their code knowing this? In which situations would it make a difference?
Similarly, if a 500 page is being served, how much does it matter that they don't have Astro.locals? How common is it to create a custom 500 page (at all) and then in particular, one that would make use of locals?
I'm going by the "not everything is true belongs in docs" principle, and want to include things that will affect people's decisions, and that they need to know to build properly. I'm going to need your help to figure out if these fit that criteria.
There was a problem hiding this comment.
Not that important.
The most important point would be that 500 page could miss locals sometimes. However, even that I don't feel too strongly about - it came up only once.
Co-authored-by: Arsh <69170106+lilnasy@users.noreply.github.com>
|
OK @lilnasy - I made one adjustment and then a couple of suggestions that I think might address your outstanding points? See what you think of this, whether you feel those both a) are correct 😅 and b) provide helpful information to be worth including! Then, we'll be finished here! |
|
@arsh For the sake of having something ready for minor release tomorrow, I'm committing my suggestions, but I'm totally open to your feedback! Still at least 12 hours before I'm merging. 😂 If you don't have a chance to look at this before it merges with the minor release and you want to change something, then happy to PR an update to it! |
|
Thanks for getting this all the info in a much better shape! Just one suggestion. Even without it, looks ready to publish. |
Co-authored-by: Arsh <69170106+lilnasy@users.noreply.github.com>
Description (required)
404.astro, there is no difference.Related issues & labels (optional)