roast logo

_ssr.json file

What is the _ssr.json file?

Roast.io is unique among static web hosting providers because of its server-side rendering (SSR) feature. It allows us to auto generate open graph images and simplifies server-side rendering for single-page apps. It's powered by Prerender.cloud


The default configuration is designed to "just work" for both plain-old HTML sites and singe-page apps.


_ssr.json is a JSON file in the root of your deploy with the file name _ssr.json. It configures the SSR process that can run on deploy, on first page load, or via API call.

There are 6 valid fields: paths, lazyLoad, botsOnly, whitelistQueryParams, autoOg, and metaOnly. If you don't include the _ssr.json file, then the defaults will be used.

{"paths": []} (default) means ssr nothing on deploy
{"paths": null} means ssr everything, on deploy, found via crawling and/or sitemaps
{"paths": ["/", "/docs"]} means ssr only / and /docs on deploy (and if lazyLoad is disabled, then this acts like a whitelist)


{"lazyLoad": true} (default) means initial visits to pages not yet ssr'd will trigger ssr (and brief delay while page is compiled)
{"lazyLoad": false} means visits to pages not yet ssr'd will return non-ssr version of page
{"lazyLoad": ["/", "/docs"]} like true, but with whitelist
{"botsOnly": false} (default) all user-agents will receive SSR content
{"botsOnly": true} means that only visitors with known bot user-agents (googlebot, twitterbot, etc.) will receive the SSR content
{"whitelistQueryParams": null} (default) means allow all query params
{"whitelistQueryParams": []} means drop all query params
{"whitelistQueryParams": ["page"]} means only allow the page query param
{"autoOg": true} (default) auto generate and host and inject og:images (link previews) (only if they don't exist)
{"autoOg": false} do not auto generate og:images (link previews)
{"metaOnly": true} (default) SSR is limited to title+meta tags only
{"metaOnly": false} full page SSR

Why use the _ssr.json file?

To explicitly control SSR behavior instead of being subjected to default behavior.

Example use cases

(default) SSR only title+meta tags, auto generate open graph image, on first page load

you don't need a _ssr.json file if you want this behavior
{ "lazyLoad": true, "paths": [], "botsOnly": false, "autoOg": true, "metaOnly": true }

SSR everything on every deploy

(this can get expensive but guarantees all of your pages found via sitemaps/crawling are served quickly)

{ "lazyLoad": false, "paths": null, "botsOnly": false, "autoOg": true, "metaOnly": false }

SSR everything on every deploy plus lazy load anything else

(same as above, but lazyLoad pages that weren't found via sitemaps or crawling)

{ "lazyLoad": true, "paths": null }

SSR on first page visit, no SSR on deploy

(cost effective for sites with tens of thousands of pages (long tail) that are rarely visited, and can tolerate an initial slow page load while the SSR happens)

{ "lazyLoad": true, "paths": [] }

SSR on first page visit, some SSR on deploy

(same as above, but when you want certain pages SSR'ed immediately)

{ "lazyLoad": true, "paths": ["/","/docs","/pricing"] }

never SSR anything

(which defeats the purpose of using roast.io - although you could still trigger the SSR via the API)

{ "lazyLoad": false, "paths": [] }