svelte-adapter-github
Adapter for SvelteKit apps that prerenders your site as a collection of static files for GitHub Pages.
Usage
Install with npm i -D svelte-adapter-github
, then add the adapter to your svelte.config.js
:
// svelte.config.js
import adapter from 'svelte-adapter-github';
export default {
kit: {
adapter: adapter({
// default options are shown
pages: 'docs',
assets: 'docs',
domain: null,
jekyll: false,
fallback: null,
precompress: false
})
}
};
Unless you're in SPA mode, the adapter will attempt to prerender every page of your app, regardless of whether the prerender
option is set.
Options
pages
The directory to write prerendered pages to. It defaults to docs
.
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.
domain
If you're using a custom domain on GitHub pages, include it here as type string. This will create a CNAME file in your build directory, with the domain as its contents.
jekyll
GitHub Pages defaults to using jekyll to build your site's files. However, this isn't generally needed when deploying a static svelte site. So, by default, we create an empy .nojekyll
file in your build directory. If you need the jekyll build step, set this option to true
and read the GitHub Pages section.
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.
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).
The fallback page is a blank HTML page that loads your SvelteKit 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 otherwise match. We can create that file like so:
// svelte.config.js
import adapter from '@sveltejs/adapter-static';
export default {
kit: {
adapter: adapter({
fallback: '200.html'
})
}
};
When operating in SPA mode, only pages that have the prerender
option set will be prerendered.
GitHub Pages
When building for GitHub Pages - and if you're not using a custom domain - 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.
By default, we provide a .nojekyll
file, to prevent GitHub Pages from using Jekyll to manage your site. If you do not want to disable Jekyll, pass in the jekyll: true
adapter option and 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 - not using a custom domain - might look like the following:
const dev = process.env.NODE_ENV === 'development';
/** @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',
}
};