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.