@sveltejs/adapter-static

@sveltejs/adapter-static

Adapter for SvelteKit apps that prerenders your entire site as a collection of static files. If you'd like to prerender only some pages, you will need to use a different adapter together with the prerender option.

Usage

Install with npm i -D @sveltejs/adapter-static, then add the adapter to your svelte.config.js...

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

export default {
  kit: {
    adapter: adapter({
      // default options are shown. On some platforms
      // these options are set automatically — see below
      pages: 'build',
      assets: 'build',
      fallback: null,
      precompress: false,
      strict: true
    })
  }
};

...and add the prerender option to your root layout:

// src/routes/+layout.js

// This can be false if you're using a fallback (i.e. SPA mode)
export const prerender = true;

⚠️ You must ensure SvelteKit's trailingSlash option is set appropriately for your environment. If your host does not render /a.html upon receiving a request for /a then you will need to set trailingSlash: 'always' to create /a/index.html instead.

Zero-config support

Some platforms have zero-config support (more to come in future):

• Vercel

On these platforms, you should omit the adapter options so that adapter-static can provide the optimal configuration:

export default {
  kit: {
-    adapter: adapter({...}),
+    adapter: adapter(),
    }
  }
};

Options

pages

The directory to write prerendered pages to. It defaults to build.

assets

The directory to write static assets (the contents of static, plus client-side JS and CSS generated by SvelteKit) to. Ordinarily this should be the same as pages, and it will default to whatever the value of pages is, but in rare circumstances you might need to output pages and assets to separate locations.

fallback

Specify a fallback page for SPA mode, e.g. index.html or 200.html or 404.html.

precompress

If true, precompresses files with brotli and gzip. This will generate .br and .gz files.

strict

By default, adapter-static checks that either all pages and endpoints (if any) of your app were prerendered, or you have the fallback option set. This check exists to prevent you from accidentally publishing an app where some parts of it are not accessible, because they are not contained in the final output. If you know this is ok (for example when a certain page only exists conditionally), you can set strict to false to turn off this check.

SPA mode

You can use adapter-static to create a single-page app or SPA by specifying a fallback page.

In most situations this is not recommended: it harms SEO, tends to slow down perceived performance, and makes your app inaccessible to users if JavaScript fails or is disabled (which happens more often than you probably think).

If you want to create a simple SPA with no prerendered routes, the necessary config looks like this:

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

export default {
  kit: {
    adapter: adapter({
      fallback: '200.html'
    }),
    prerender: { entries: [] }
  }
};

// src/routes/+layout.js
export const ssr = false;

You can also turn only part of your app into an SPA.

Let's go through these options one by one:

Add fallback page

The fallback page is an HTML page created by SvelteKit that loads your app and navigates to the correct route. For example Surge, a static web host, lets you add a 200.html file that will handle any requests that don't correspond to static assets or prerendered pages. We can create that file like so:

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

export default {
  kit: {
    adapter: adapter({
      fallback: '200.html'
    })
  }
};

How to configure this behaviour does however depend on your hosting solution and is not part of SvelteKit. It is recommended to search the host's documentation on how to redirect requests.

Turn off prerendering

When operating in SPA mode, you can omit the prerender option from your root layout (or set it to false, its default value), and only pages that have the prerender option set will be prerendered at build time.

SvelteKit will still crawl your app's entry points looking for prerenderable pages. If svelte-kit build fails because of pages that can't be loaded outside the browser, you can set config.kit.prerender.entries to [] to prevent this from happening. (Setting config.kit.prerender.enabled to false also has this effect, but would prevent the fallback page from being generated.)

You can also add turn off prerendering only to parts of your app, if you want other parts to be prerendered.

Turn off ssr

During development, SvelteKit will still attempt to server-side render your routes. This means accessing things that are only available in the browser (such as the window object) will result in errors, even though this would be valid in the output app. To align the behavior of SvelteKit's dev mode with your SPA, you can add export const ssr = false to your root +layout. You can also add this option only to parts of your app, if you want other parts to be prerendered.

Apache

To run an SPA on Apache, you should add a static/.htaccess file to route requests to the fallback page:

<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /
  RewriteRule ^200\.html$ - [L]
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule . /200.html [L]
</IfModule>

GitHub Pages

When building for GitHub Pages, make sure to update paths.base to match your repo name, since the site will be served from https://your-username.github.io/your-repo-name rather than from the root.

You will have to prevent GitHub's provided Jekyll from managing your site by putting an empty .nojekyll file in your static folder. If you do not want to disable Jekyll, change the kit's appDir configuration option to 'app_' or anything not starting with an underscore. For more information, see GitHub's Jekyll documentation.

A config for GitHub Pages might look like the following:

const dev = process.argv.includes('dev');

/** @type {import('@sveltejs/kit').Config} */
const config = {
	...
	kit: {
		...
		paths: {
			base: dev ? '' : '/your-repo-name',
		},
		// If you are not using a .nojekyll file, change your appDir to something not starting with an underscore.
		// For example, instead of '_app', use 'app_', 'internal', etc.
		appDir: 'internal',
	}
};

Changelog

The Changelog for this package is available on GitHub.

License

MIT