Build and deploy
Static site generation
Edit this page on GitHubTo use SvelteKit as a static site generator (SSG), use adapter-static
.
This will prerender your entire site as a collection of static files. If you'd like to prerender only some pages and dynamically server-render others, you will need to use a different adapter together with the prerender
option.
Usagepermalink
Install with npm i -D @sveltejs/adapter-static
, then add the adapter to your svelte.config.js
:
ts
importCannot find module '@sveltejs/adapter-static' or its corresponding type declarations.2307Cannot find module '@sveltejs/adapter-static' or its corresponding type declarations.adapter from'@sveltejs/adapter-static' ;export default {kit : {adapter :adapter ({// default options are shown. On some platforms// these options are set automatically — see belowpages : 'build',assets : 'build',fallback :undefined ,precompress : false,strict : true})}};
...and add the prerender
option to your root layout:
ts
// If you're using a fallback (i.e. SPA mode) you don't need to prerender all// pages by setting this here, but should prerender as many as possible to// avoid disastrous performance and SEO impactsexport constprerender = true;
ts
// If you're using a fallback (i.e. SPA mode) you don't need to prerender all// pages by setting this here, but should prerender as many as possible to// avoid disastrous performance and SEO impactsexport constprerender = 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 settrailingSlash: 'always'
in your root layout to create/a/index.html
instead.
Zero-config supportpermalink
Some platforms have zero-config support (more to come in future):
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()
}
};
Optionspermalink
pagespermalink
The directory to write prerendered pages to. It defaults to build
.
assetspermalink
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.
fallbackpermalink
To create a single page app (SPA) you must specify the name of the fallback page to be generated by SvelteKit, which is used as the entry point for URLs that have not been prerendered. This is commonly index.html
or 200.html
, but can vary depending on your deployment platform. Note that reliance on this option is highly discouraged and you should prerender as many pages as possible to avoid the drawbacks of single page apps. See the single page apps documentation for more details.
precompresspermalink
If true
, precompresses files with brotli and gzip. This will generate .br
and .gz
files.
strictpermalink
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.
GitHub Pagespermalink
When building for GitHub Pages, if your repo name is not equivalent to your-username.github.io
, make sure to update config.kit.paths.base
to match your repo name. This is because the site will be served from https://your-username.github.io/your-repo-name
rather than from the root.
You'll also want to generate a fallback 404.html
page to replace the default 404 page shown by GitHub Pages.
A config for GitHub Pages might look like the following:
ts
importCannot find module '@sveltejs/adapter-static' or its corresponding type declarations.2307Cannot find module '@sveltejs/adapter-static' or its corresponding type declarations.adapter from'@sveltejs/adapter-static' ;/** @type {import('@sveltejs/kit').Config} */constconfig = {kit : {adapter :adapter ({fallback : '404.html'}),paths : {Type 'string | undefined' is not assignable to type '"" | `/${string}` | undefined'. Type 'string' is not assignable to type '"" | `/${string}` | undefined'.2322Type 'string | undefined' is not assignable to type '"" | `/${string}` | undefined'. Type 'string' is not assignable to type '"" | `/${string}` | undefined'.: base process .argv .includes ('dev') ? '' :process .env .BASE_PATH }}};export defaultconfig ;
You can use GitHub actions to automatically deploy your site to GitHub Pages when you make a change. Here's an example workflow:
yaml
name: Deploy to GitHub Pageson:push:branches: 'main'jobs:build_site:runs-on: ubuntu-lateststeps:- name: Checkoutuses: actions/checkout@v3# If you're using pnpm, add this step then change the commands and cache key below to use `pnpm`# - name: Install pnpm# uses: pnpm/action-setup@v2# with:# version: 8- name: Install Node.jsuses: actions/setup-node@v3with:node-version: 18cache: npm- name: Install dependenciesrun: npm install- name: buildenv:BASE_PATH: '/${{ github.event.repository.name }}'run: |npm run build- name: Upload Artifactsuses: actions/upload-pages-artifact@v2with:# this should match the `pages` option in your adapter-static optionspath: 'build/'deploy:needs: build_siteruns-on: ubuntu-latestpermissions:pages: writeid-token: writeenvironment:name: github-pagesurl: ${{ steps.deployment.outputs.page_url }}steps:- name: Deployid: deploymentuses: actions/deploy-pages@v2
If you're not using GitHub actions to deploy your site (for example, you're pushing the built site to its own repo), add an empty .nojekyll
file in your static
directory to prevent Jekyll from interfering.