docs: clarify that `ssr = true` is required for prerendering in adapter-static

[th0rgall]

Describe the bug

I’ll start with a quote from another related issue #11639 (comment) :

People enable SPA without prerendering and their sites are much slower as a result because it results in an extra round trip to the server before anything can be rendered. I found tons of examples of this in the wild.

I have unfortunately maintained such a site for years, up until today.

Some months ago I tried to figure out how to achieve multi-page SSG with pre-rendered page content, but I didn't succeed at first. I thought it was not possible. Another SvelteKit project recently made me realize my misconception, because it used adapter-static without export const srr = false

The problem

The problem was that I never realized that:

1. adapter-static still works when you have set ssr = true. In fact, this is recommended setup, otherwise you only effectively generate empty shell pages as static pages (see next point).
2. ssr needs to be set to true in order for prerender = true to actually pre-render page content. Or, said differently, since ssr = true is the default, I had to remove ssr = false to start rendering my static pages content at build time.

I'm not the only one confused by this. There is the link in the opening quote above, but here are two more examples:

• Prerendering broken with ssr=false, prerender=true (and cloudflare) #12598

  ”Most people will probably think the prerender option will already give them a fully prerendered page.”

• Adapter-static: How to setup the head content of the fallback page #11910 (comment)

  "[...] so changing the ssr to true did indeed change the output to include the headers as expected. [...] But if ssr needs to be true, then I'm not sure what prerender actually does, presumably nothing with the static adapter? But this is not made clear in the svelte docs. [..]"

I think our 5-year-old project had ssr = false as an legacy setting from the Sapper/alpha SvelteKit days, and I never intuitively saw a reason to remove it. But I can also imagine that people looking for SSG will automatically assume that they should disable SSR, since the two concepts can/should not be combined in other frameworks.

How to improve the docs?

Here are some suggestions. I'm willing to try submitting a PR if a potential reviewer agrees with the direction:

• Most importantly, the adapter-static ("Static site generation docs") do not mention this caveat. These docs were my entry point to learn how to use adapter-static to achieve SSG. I would add something like a second warning after the instruction to set prerender to true:

  💡 make sure to also remove export const ssr = false from layouts or pages where you want your page content to be pre-rendered. adapter-static is compatible with SSR. It relies on the server-render pass at build time to pre-render static content. Without ssr = true, prerender = true has no effect. ssr = true is the default rendering mode if you have not disabled it. For more context, see Prerendering individual pages

• Maybe https://svelte.dev/docs/kit/page-options#ssr could have a line like:

  "If you use adapter-static, ssr should be set to true to pre-render static page content, since this content is server-rendered at build time"

• It could also be explicitly mentioned in the "prerender" docs https://svelte.dev/docs/kit/page-options#prerender, but those docs already link to the adapter-static docs. Improving the latter would be sufficiently clear, I think.

Reproduction

N.A.

Logs

System Info

System:
    OS: macOS 15.6.1
    CPU: (10) arm64 Apple M1 Pro
    Memory: 127.06 MB / 32.00 GB
    Shell: 5.9 - /bin/zsh
  Binaries:
    Node: 20.11.0 - ~/.nvm/versions/node/v20.11.0/bin/node
    Yarn: 4.9.0 - ~/.nvm/versions/node/v20.11.0/bin/yarn
    npm: 10.2.4 - ~/.nvm/versions/node/v20.11.0/bin/npm
    bun: 1.1.17 - ~/.bun/bin/bun
  Browsers:
    Chrome: 140.0.7339.133
    Edge: 126.0.2592.68
    Safari: 18.6
    Safari Technology Preview: 26.0
  npmPackages:
    @sveltejs/adapter-static: ^3.0.8 => 3.0.8 
    @sveltejs/kit: 2.21.2 => 2.21.2 
    @sveltejs/vite-plugin-svelte: ^3.1.2 => 3.1.2 
    svelte: ^4.2.19 => 4.2.19 
    vite: ^5.4.18 => 5.4.18

Severity

annoyance

Additional Information

No response

[benmccann]

Yes, PR welcome!! Might have some feedback about some of the wording, but if you can open one up to get the ball rolling that would be great! Thanks for bringing this to our attention!