SvelteKitBuild and deploy

Static site generation

To 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.

Usage

Run npx sv add sveltekit-adapter="adapter:static", or install with npm i -D @sveltejs/adapter-static and add the adapter to your vite.config.js:

vite.config

import adapterimport adapter from '@sveltejs/adapter-static';
import { sveltekit(alias) function sveltekit(config?: Config): Promise<Plugin[]>
import sveltekitThe SvelteKit Vite plugin, which must be added to your vite.config.js file along with your project's configuration:
/// file: vite.config.js
import adapter from '@sveltejs/adapter-auto';
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [
		sveltekit({
			adapter: adapter(),
			compilerOptions: {
				experimental: {
					async: true
				}
			},
			experimental: {
				remoteFunctions: true
			}
		})
	]
});
As well as SvelteKit, the plugin options are used by other tooling that integrates with Svelte such as editor extensions.
Any options that don't belong to SvelteKit are passed through to vite-plugin-svelte, so you can set options like inspector here too. The experimental namespace is shared — SvelteKit reads its own flags and forwards the rest.

[!LEGACY]
Prior to SvelteKit 3, config lived in a svelte.config.js file, which is no longer supported. The ability to configure SvelteKit via vite.config.js was added in version 2.62.

reference } from '@sveltejs/kit/vite';
import { defineConfig(alias) function defineConfig(config: UserConfig): UserConfig (+5 overloads)
import defineConfigType helper to make it easier to use vite.config.ts
accepts a direct 
{@link 
UserConfig
}
 object, or a function that returns it.
The function receives a 
{@link 
ConfigEnv
}
 object.
 } from 'vite';

export default defineConfig(alias) defineConfig(config: UserConfig): UserConfig (+5 overloads)
import defineConfigType helper to make it easier to use vite.config.ts
accepts a direct 
{@link 
UserConfig
}
 object, or a function that returns it.
The function receives a 
{@link 
ConfigEnv
}
 object.
({
	plugins(property) UserConfig.plugins?: PluginOption[] | undefinedArray of vite plugins to use.
: [
		sveltekit(alias) sveltekit(config?: Config): Promise<Plugin[]>
import sveltekitThe SvelteKit Vite plugin, which must be added to your vite.config.js file along with your project's configuration:
/// file: vite.config.js
import adapter from '@sveltejs/adapter-auto';
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [
		sveltekit({
			adapter: adapter(),
			compilerOptions: {
				experimental: {
					async: true
				}
			},
			experimental: {
				remoteFunctions: true
			}
		})
	]
});
As well as SvelteKit, the plugin options are used by other tooling that integrates with Svelte such as editor extensions.
Any options that don't belong to SvelteKit are passed through to vite-plugin-svelte, so you can set options like inspector here too. The experimental namespace is shared — SvelteKit reads its own flags and forwards the rest.

[!LEGACY]
Prior to SvelteKit 3, config lived in a svelte.config.js file, which is no longer supported. The ability to configure SvelteKit via vite.config.js was added in version 2.62.

reference({
			adapter(property) Config.adapter?: Adapter | undefinedYour adapter is run when executing vite build. It determines how the output is converted for different platforms.
undefined
: adapterimport adapter({
				// default options are shown. On some platforms				// these options are set automatically — see below				pages(property) pages: string: 'build',
				assets(property) assets: string: 'build',
				fallback(property) fallback: undefined: undefinedvar undefined,
				precompress(property) precompress: boolean: false,
				strict(property) strict: boolean: true
			})
		})
	]
});

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

src/routes/+layout

// 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 large performance and SEO impacts
export const prerenderconst prerender: true = 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' in your root layout to create /a/index.html instead.

You must ensure SvelteKit’s ssr option isn’t set to false. Otherwise, prerendering will save an empty ‘shell’ page instead of the fully rendered content.

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:

vite.config

import adapterimport adapter from '@sveltejs/adapter-static';
import { sveltekit(alias) function sveltekit(config?: Config): Promise<Plugin[]>
import sveltekitThe SvelteKit Vite plugin, which must be added to your vite.config.js file along with your project's configuration:
/// file: vite.config.js
import adapter from '@sveltejs/adapter-auto';
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [
		sveltekit({
			adapter: adapter(),
			compilerOptions: {
				experimental: {
					async: true
				}
			},
			experimental: {
				remoteFunctions: true
			}
		})
	]
});
As well as SvelteKit, the plugin options are used by other tooling that integrates with Svelte such as editor extensions.
Any options that don't belong to SvelteKit are passed through to vite-plugin-svelte, so you can set options like inspector here too. The experimental namespace is shared — SvelteKit reads its own flags and forwards the rest.

[!LEGACY]
Prior to SvelteKit 3, config lived in a svelte.config.js file, which is no longer supported. The ability to configure SvelteKit via vite.config.js was added in version 2.62.

reference } from '@sveltejs/kit/vite';
import { defineConfig(alias) function defineConfig(config: UserConfig): UserConfig (+5 overloads)
import defineConfigType helper to make it easier to use vite.config.ts
accepts a direct 
{@link 
UserConfig
}
 object, or a function that returns it.
The function receives a 
{@link 
ConfigEnv
}
 object.
 } from 'vite';

export default defineConfig(alias) defineConfig(config: UserConfig): UserConfig (+5 overloads)
import defineConfigType helper to make it easier to use vite.config.ts
accepts a direct 
{@link 
UserConfig
}
 object, or a function that returns it.
The function receives a 
{@link 
ConfigEnv
}
 object.
({
	plugins(property) UserConfig.plugins?: PluginOption[] | undefinedArray of vite plugins to use.
: [
		sveltekit(alias) sveltekit(config?: Config): Promise<Plugin[]>
import sveltekitThe SvelteKit Vite plugin, which must be added to your vite.config.js file along with your project's configuration:
/// file: vite.config.js
import adapter from '@sveltejs/adapter-auto';
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [
		sveltekit({
			adapter: adapter(),
			compilerOptions: {
				experimental: {
					async: true
				}
			},
			experimental: {
				remoteFunctions: true
			}
		})
	]
});
As well as SvelteKit, the plugin options are used by other tooling that integrates with Svelte such as editor extensions.
Any options that don't belong to SvelteKit are passed through to vite-plugin-svelte, so you can set options like inspector here too. The experimental namespace is shared — SvelteKit reads its own flags and forwards the rest.

[!LEGACY]
Prior to SvelteKit 3, config lived in a svelte.config.js file, which is no longer supported. The ability to configure SvelteKit via vite.config.js was added in version 2.62.

reference({
			adapter(property) Config.adapter?: Adapter | undefinedYour adapter is run when executing vite build. It determines how the output is converted for different platforms.
undefined
: adapterimport 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

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 200.html, but can vary depending on your deployment platform. You should avoid index.html where possible to avoid conflicting with a prerendered homepage.

This option has large negative performance and SEO impacts. It is only recommended in certain circumstances such as wrapping the site in a mobile app. See the single page apps documentation for more details and alternatives.

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.

GitHub Pages

When building for GitHub Pages, if your repo name is not equivalent to your-username.github.io, make sure to update config.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:

vite.config

import process(alias) var process: NodeJS.Process
import process from 'node:process';
import adapterimport adapter from '@sveltejs/adapter-static';
import { sveltekit(alias) function sveltekit(config?: Config): Promise<Plugin[]>
import sveltekitThe SvelteKit Vite plugin, which must be added to your vite.config.js file along with your project's configuration:
/// file: vite.config.js
import adapter from '@sveltejs/adapter-auto';
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [
		sveltekit({
			adapter: adapter(),
			compilerOptions: {
				experimental: {
					async: true
				}
			},
			experimental: {
				remoteFunctions: true
			}
		})
	]
});
As well as SvelteKit, the plugin options are used by other tooling that integrates with Svelte such as editor extensions.
Any options that don't belong to SvelteKit are passed through to vite-plugin-svelte, so you can set options like inspector here too. The experimental namespace is shared — SvelteKit reads its own flags and forwards the rest.

[!LEGACY]
Prior to SvelteKit 3, config lived in a svelte.config.js file, which is no longer supported. The ability to configure SvelteKit via vite.config.js was added in version 2.62.

reference } from '@sveltejs/kit/vite';
import { defineConfig(alias) function defineConfig(config: UserConfig): UserConfig (+5 overloads)
import defineConfigType helper to make it easier to use vite.config.ts
accepts a direct 
{@link 
UserConfig
}
 object, or a function that returns it.
The function receives a 
{@link 
ConfigEnv
}
 object.
 } from 'vite';

export default defineConfig(alias) defineConfig(config: UserConfig): UserConfig (+5 overloads)
import defineConfigType helper to make it easier to use vite.config.ts
accepts a direct 
{@link 
UserConfig
}
 object, or a function that returns it.
The function receives a 
{@link 
ConfigEnv
}
 object.
({
	plugins(property) UserConfig.plugins?: PluginOption[] | undefinedArray of vite plugins to use.
: [
		sveltekit(alias) sveltekit(config?: Config): Promise<Plugin[]>
import sveltekitThe SvelteKit Vite plugin, which must be added to your vite.config.js file along with your project's configuration:
/// file: vite.config.js
import adapter from '@sveltejs/adapter-auto';
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [
		sveltekit({
			adapter: adapter(),
			compilerOptions: {
				experimental: {
					async: true
				}
			},
			experimental: {
				remoteFunctions: true
			}
		})
	]
});
As well as SvelteKit, the plugin options are used by other tooling that integrates with Svelte such as editor extensions.
Any options that don't belong to SvelteKit are passed through to vite-plugin-svelte, so you can set options like inspector here too. The experimental namespace is shared — SvelteKit reads its own flags and forwards the rest.

[!LEGACY]
Prior to SvelteKit 3, config lived in a svelte.config.js file, which is no longer supported. The ability to configure SvelteKit via vite.config.js was added in version 2.62.

reference({
			adapter(property) Config.adapter?: Adapter | undefinedYour adapter is run when executing vite build. It determines how the output is converted for different platforms.
undefined
: adapterimport adapter({
				fallback(property) fallback: string: '404.html'
			}),
			paths(property) Config.paths?: {
    assets?: "" | `http://${string}` | `https://${string}`;
    base?: "" | `/${string}`;
    origin?: string;
    relative?: boolean;
} | undefined: {
				base(property) base?: "" | `/${string}` | undefinedA root-relative path that must start, but not end with / (e.g. /base-path), unless it is the empty string. This specifies where your app is served from and allows the app to live on a non-root path. Note that you need to prepend all your root-relative links with the base value or they will point to the root of your domain, not your base (this is how the browser works). You can use resolve(...) from $app/paths for that: <a href="{resolve('/your-page')}">Link</a>. If you find yourself writing this often, it may make sense to extract this into a reusable component.
""
: process(alias) var process: NodeJS.Process
import process.argv(property) NodeJS.Process.argv: string[]The process.argv property returns an array containing the command-line
arguments passed when the Node.js process was launched. The first element will
be 
{@link 
execPath
}
. See process.argv0 if access to the original value
of argv[0] is needed. The second element will be the path to the JavaScript
file being executed. The remaining elements will be any additional command-line
arguments.
For example, assuming the following script for process-args.js:
import { argv } from 'node:process';

// print process.argv
argv.forEach((val, index) => {
  console.log(`${index}: ${val}`);
});
Launching the Node.js process as:
node process-args.js one two=three four
Would generate the output:
0: /usr/local/bin/node
1: /Users/mjr/work/node/process-args.js
2: one
3: two=three
4: fourv0.1.27
.includes(method) Array<string>.includes(searchElement: string, fromIndex?: number): booleanDetermines whether an array includes a certain element, returning true or false as appropriate.
searchElement The element to search for.
fromIndex The position in this array at which to begin searching for searchElement.
('dev') ? '' : process(alias) var process: NodeJS.Process
import process.env(property) NodeJS.Process.env: NodeJS.ProcessEnvThe process.env property returns an object containing the user environment.
See environ(7).
An example of this object looks like:
{
  TERM: 'xterm-256color',
  SHELL: '/usr/local/bin/bash',
  USER: 'maciej',
  PATH: '~/.bin/:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin',
  PWD: '/Users/maciej',
  EDITOR: 'vim',
  SHLVL: '1',
  HOME: '/Users/maciej',
  LOGNAME: 'maciej',
  _: '/usr/local/bin/node'
}
It is possible to modify this object, but such modifications will not be
reflected outside the Node.js process, or (unless explicitly requested)
to other Worker threads.
In other words, the following example would not work:
node -e 'process.env.foo = "bar"' &#x26;&#x26; echo $foo
While the following will:
import { env } from 'node:process';

env.foo = 'bar';
console.log(env.foo);
Assigning a property on process.env will implicitly convert the value
to a string. This behavior is deprecated. Future versions of Node.js may
throw an error when the value is not a string, number, or boolean.
import { env } from 'node:process';

env.test = null;
console.log(env.test);
// => 'null'
env.test = undefined;
console.log(env.test);
// => 'undefined'
Use delete to delete a property from process.env.
import { env } from 'node:process';

env.TEST = 1;
delete env.TEST;
console.log(env.TEST);
// => undefined
On Windows operating systems, environment variables are case-insensitive.
import { env } from 'node:process';

env.TEST = 1;
console.log(env.test);
// => 1
Unless explicitly specified when creating a Worker instance,
each Worker thread has its own copy of process.env, based on its
parent thread's process.env, or whatever was specified as the env option
to the Worker constructor. Changes to process.env will not be visible
across Worker threads, and only the main thread can make changes that
are visible to the operating system or to native add-ons. On Windows, a copy of process.env on a Worker instance operates in a case-sensitive manner
unlike the main thread.
v0.1.27
.BASE_PATHstring | undefined
			},
		})
	]
});

You can use GitHub actions to automatically deploy your site to GitHub Pages when you make a change. Here’s an example workflow:

.github/workflows/deploy

name: Deploy to GitHub Pages

on:
  push:
    branches: 'main'

jobs:
  build_site:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v7

      # 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@v6
      #   with:
      #     version: 8

      - name: Install Node.js
        uses: actions/setup-node@v6
        with:
          node-version: 20
          cache: npm

      - name: Install dependencies
        run: npm i

      - name: build
        env:
          BASE_PATH: '/${{ github.event.repository.name }}'
        run: |
          npm run build

      - name: Upload Artifacts
        uses: actions/upload-pages-artifact@v5
        with:
          # this should match the `pages` option in your adapter-static options
          path: 'build/'

  deploy:
    needs: build_site
    runs-on: ubuntu-latest

    permissions:
      pages: write
      id-token: write

    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
      - name: Deploy
        id: deployment
        uses: actions/deploy-pages@v5

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.

Edit this page on GitHub llms.txt

previous next

Bun servers Single-page apps