kit: Add a straightforward way to export error pages with `adapter-static`

What I’m doing now is src/routes/404.svelte – which builds to /build/404/index.html (currently using static adapter).

So then I add a postbuild npm script to move that file to the correct location:

{
  // ...
  "scripts": {
    "build": "svelte-kit build",
    "postbuild": "mv build/404/index.html build/404.html"
  }
}

Summary for future readers

You can have your cake and eat it too. 🍰 i.e. :

• Use sveltekit adapter-static
• Pre-render all your pages by default, hence better performance and SEO (Search Engine Optimization)
• Fallback to an error page when navigating to a non-existent page or resource
• The fallback works locally and even if the site is hosted via a static provider (e.g. Cloudflare, Azure Static Web Apps, etc.)

Step 1: create error page

Step 2: update sveltekit.config.js

import adapter from '@sveltejs/adapter-static';
import preprocess from 'svelte-preprocess';

/** @type {import('@sveltejs/kit').Config} */
const config = {
	preprocess: preprocess(),
	
	kit: {
		adapter: adapter({
			pages: 'build',
			assets: 'build',
			fallback: '404.html', <------- HERE
			precompress: false
		}),
		prerender: {
			default: true <------- HERE
		}
		
		// other configs...
	}

	// other configs...
};

export default config;

Step 3: let your static host service know how to handle not found resources. As an example, I’m using the Azure Static Websites config

// staticwebapp.config.json
{
    "responseOverrides": {
        "404": {
            "rewrite": "/404.html",
            "statusCode": 404
        }
    }
}

Oh, right, thanks, I missed this one. An option would be nice indeed.

However, the resulting fallback doesn’t render a 404 using $error.svelte, it simply renders a blank page with spa: true, which ultimately solves a different problem.

What am I still missing?

@vwkd Right now, the best way is to build a routes/404.svelte file and the include a postbuild script that moves the built 404/index.html into the the build directory’s root as 404.html

Before the recent output dir changes, this would look like:

{
  "scripts": {
    // ...
    "postbuild": "mv build/404/index.html build/404.html"
  }
}

I’ve run into the same issue. A static error page is missing. I’d like to see an option to export __error.svelte into mypath/myname.html. Maybe something like

// svelte.config.js
import adapter from '@sveltejs/adapter-static';

export default {
	kit: {
		adapter: adapter({
			error: 'mypath/myname.html'
		})
	}
};

This is needed for Cloudflare Pages to show an error page. By default, Cloudflare Pages redirects all invalid URLs back to the root, because it assumes SPA mode if there is no 404.html present (see ​Not Found behavior).

Currently, it’s even impossible to export such 404.html manually, because a 404.svelte generates a 404/index.html instead of a 404.html.

The fallback option is designed for this

I agree with @Raicuparta, this results in a blank page if JS is disabled in the browser. It seems like the fallback page is not prerendered along with the other routes, and instead relies on CSR.

I ended up reaching the exact same conclusion as @jeroenheijmans, but it not working with javascript off is a bit of a bummer. It’s the one thing missing here. Hoping there’s a solution for this

The fallback option appears to disable SSR altogether, exporting a single HTML document that I assume is an SPA entry point. What I’m trying to do is export all routes as usual, plus a /404. Where am I wrong?

fallback and the new prerender.default: true option make it straightforward to render a fallback 404.html (or 200.html, in the SPA case) page, so I’ll close this issue