Hybrid rendering

[matthewp]

• Implementation PR: feat: hybrid output astro#6991
• Stage 3 Proposal: Hybrid rendering stage 3 proposal roadmap#565

Needs

Note that this feature will likely be released as experimental at first.

The config reference page will include details on about how to turn on this feature.

Currently prerendering is explained on the server-side rendering page. Since this new feature is for SSG it wouldn't work well there.

How it works

See the RFC for full details. In short:

defineConfig({
  output: 'hybrid'
})

Then you can opt-out of prerendering on a per-page basis, for ex:

index.astro

---
export const prerender = false;
---

[sarah11918]

Thanks @matthewp ! Just to confirm, this will release as experimental next Wednesday, right? in 2.5? We'll get started on some docs in prep for that!

[matthewp]

The plan is experimental in 2.5, yes.

Where's the right place to document this, do you think? Currently prerendering is explain on the SSR page, but this new feature is for SSG.

[sarah11918]

I'm going to have to think about this one. We've talked as a longer-term goal of SSR eventually not having its own page, but more SSR and SSG interwoven as appropriate throughout Docs as just two different options when discussing other topics. This is another reason why that would make sense.

I'll come up with some thoughts!

[sarah11918]

OK, so to figure out where to place this (maybe something about rendering added to our routing page?):

• when you configure server: hybrid, I'm checking that this does not require the user to also install an adapter integration in order to make use of some pre-rendering? Because I don't see mention of needing to do that. (i.e. Is hybrid actually a sneaky way of setting server but with default rendering set to false?) If it requires an adapter, and is "stealth server" mode, then we could add it to SSR for now to augment the existing pre-rendering content, and I make a note (maybe on the routing page?) that pre-rendering for some pages is available for your routes using server: hybrid and link to SSR page for more details.
• We could consider a new "rendering" page that will include everything about SSR vs SSG, pre-rendering etc. to replace the existing SSR page. This is a little more ambitious and not necessary for this 2.5 release (but, I could accomplish it on my end if we felt it was high enough priority). BUT, that would also lead me to want to include this information on the existing SSR page, because then it will be right there for when I redesign the page.

So, I think the answer I seem to be converging on is, it's least disruptive to what we have now and probably most convenient for you to add your docs to the SSR page.

And it'll be on me to first, make a logical link from elsewhere in the docs (again, I'm thinking routing or endpoints or something... I'll discuss with @delucis, too). And then, maybe in time for 2.5 release, maybe not, I'll repurpose the SSR page into a "rendering" page where we can also have better SSG vs SSR content, all the options etc. We knew that the SSR page was outgrowing its use, and now's as good a time as any to tackle that!

[matthewp]

@sarah11918 Good point, hybrid does also require an adapter. I'll update the RFC to convey that. Given that, I like option A here, for now anyways, it becomes a secondary way to do SSR and can be documented there.