Conflict Between SSR Deployment Guides Using Adapters (output: 'server') and the On-Demand Rendering Guide (output: 'static')

[romarioputra]

📚 Subject area/topic

SSR, Adapters, Astro Output Configuration

📋 Page(s) affected (or suggested, for new content)

https://docs.astro.build/en/guides/on-demand-rendering
https://docs.astro.build/en/guides/integrations-guide/cloudflare/
https://docs.astro.build/en/guides/integrations-guide/netlify/
https://docs.astro.build/en/guides/integrations-guide/node/
https://docs.astro.build/en/guides/integrations-guide/vercel/

📋 Description of content that is out-of-date or incorrect

Problem:

The current deployment guides for official Astro adapters (Cloudflare, Netlify, Node, and Vercel) recommend setting output: 'server' by default. However, this conflicts with the tip (and Astro's main philosophy of delivering the smallest amount of JavaScript possible) in the on-demand rendering guide, which suggests starting with output: 'static' unless most pages require SSR.

Start with the default 'static' mode until you are sure that most or all of your pages will be rendered on demand! This ensures that your site is as performant as possible, not relying on a server function to render static content.

The 'server' output mode does not bring any additional functionality. It only switches the default rendering behavior.

For example, the Cloudflare manual installation guide instructs users to configure astro.config.mjs as follows:

import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  output: 'server',
  adapter: cloudflare(),
});

Why this is confusing:

1. Astro’s docs recommend output: 'static' by default:

   • The [on-demand rendering guide](https://docs.astro.build/en/guides/on-demand-rendering/#server-mode) explicitly states:

     "Start with the default 'static' mode until you are sure that most or all of your pages will be rendered on demand! This ensures that your site is as performant as possible, not relying on a server function to render static content."

   • This suggests that output: 'static' should remain the starting point for most projects, yet all official adapter guides default to output: 'server'.

2. Cloudflare Pages does not require output: 'server':

   • I confirmed with an Astro core team member in Discord that Cloudflare Pages still supports SSR even when output: 'static' is used.

3. Granular control with prerender = false already exists:

   • The correct way to enable SSR for specific pages is via export const prerender = false, making output: 'server' unnecessary for projects that are mostly static.

4. All official adapter guides follow this pattern:

   • Cloudflare, Netlify, Node, and Vercel all default to output: 'server', despite output: 'static' being the suggested starting point in Astro’s other documentation.

Suggestion:

1. Clarify in adapter documentation that output: 'static' works too – Keep output: 'server' as the default in deployment guides but explicitly mention that output: 'static' is also viable with a reminder on using prerender: false for SSR pages.
2. (Possible idea) Use output: static as the default when installing adapter, and then clarify that you need to add prerender: false for SSR pages.

🖥️ Reproduction in StackBlitz (if reporting incorrect content or code samples)

No response

[sarah11918]

Thank you for filing this issue! We still do have some legacy docs (especially deploy guides are typically quite old) that are from a time before we even had (the now deprecated!) hybrid mode! So, static was REALLY, ONLY static, and you HAD to use server with an adapter.

One thought I had was that linking to the adapters guide when we want to show manual installation (vs duplicating the same instructions on a deploy guide) allows us to get this right, get it right ONCE, and then use this as our main reference.

I will also point out that we also can't just make blanket changes across the board: there may also be some situations/recipes that do describe a server app, and if that's the example in use, then we have to make sure that either we keep output: 'server' or the entire example is updated to reflect having a static orientation.

I do think maybe starting with unifying the adapter page intros to include:

• "This adapter allows Astro to deploy your on-demand rendered routes to Vercel/Netlify/Cloudflare/a Node environment"
• If you’re using Astro as a static site builder, you only need this adapter if you are using additional Vercel/Netlify/Cloudflare/ services (e.g. Vercel Web Analytics, Netlify Image CDN service). Otherwise, you do not need an adapter to deploy your static site.
• Learn how to deploy your site in our Netlify/Vercel/Cloudflare deployment guide

Then, from the config code samples, just remove output: entirely. Let's let the on demand rendering guide handle needing to update output

Lastly, all the deploy guides should probably have much less about installing an adapter (at all: CLI or manual). That should just be a link to where we make our canonical docs.

That's my first thought here!

[romarioputra]

I do think maybe starting with unifying the adapter page intros to include:

• "This adapter allows Astro to deploy your on-demand rendered routes to Vercel/Netlify/Cloudflare/a Node environment"
• If you’re using Astro as a static site builder, you only need this adapter if you are using additional Vercel/Netlify/Cloudflare/ services (e.g. Vercel Web Analytics, Netlify Image CDN service). Otherwise, you do not need an adapter to deploy your static site.
• Learn how to deploy your site in our Netlify/Vercel/Cloudflare deployment guide

I agree, no comment here! Thank you!

Then, from the config code samples, just remove output: entirely. Let's let the on demand rendering guide handle needing to update output

I just tried adding adapters through the Astro CLI and they don’t change the Astro config output: so I agree on removing output: from the Adapter's manual installation sample code.

[sarah11918]

Just a heads up that I have this on my plate to tackle next week, after some PRs that will affect our adapter / deploy pages will be updated!

I'm thinking of making this our adapter intro (Netlify example):

This adapter allows Astro to deploy your on-demand rendered routes and features to Netlify, including server islands, actions, and sessions.

If you're using Astro as a static site builder, you don't need an adapter.

Learn how to deploy your Astro site in our Netlify deployment guide.

Then, as discussed, will remove server from the code examples unless we're talking about on-demand rendering by default and also remove instructions for installing/configuring the adapters from the corresponding deploy pages.

I hope this will also clarify which Astro features do require an adapter! Noting that people are welcome to add to this discussion, but because I know which docs are currently undergoing changes, I don't want any PRs until next week! 😄