Frequently Asked Questions

SvelteKit is not 1.0 yet. Should I use it? What about Sapper? permalink

SvelteKit is currently in beta while we finalize the APIs. No new features will be added to Sapper and all development will be focused on SvelteKit.

How do I use HMR with SvelteKit? permalink

SvelteKit has HMR enabled by default powered by svelte-hmr. If you saw Rich's presentation at the 2020 Svelte Summit, you may have seen a more powerful-looking version of HMR presented. This demo had svelte-hmr's preserveLocalState flag on. This flag is now off by default because it may lead to unexpected behaviour and edge cases. But don't worry, you are still getting HMR with SvelteKit! If you'd like to preserve local state you can use the @hmr:keep or @hmr:keep-all directives as documented on the svelte-hmr page.

Why am I getting a 404? permalink

Please make sure you're returning something from your page's load function. See the section about fallthrough routes for more details.

I'm having trouble using an adapter. permalink

Please make sure the version of the adapter specified in your package.json is "next".

How do I hash asset file names for caching? permalink

You can have Vite process your assets by importing them as shown below:

	import imageSrc from '$lib/assets/image.png';

<img src="{imageSrc}" />

If you prefer to directly import in the markup, try svelte-preprocess-import-assets and you can write this instead:

<img src="$lib/assets/image.png" />

How do I setup a path alias? permalink

First, you need to add it to the Vite configuration. In svelte.config.js add vite.resolve.alias:

// svelte.config.js
import path from 'path';

export default {
	kit: {
		vite: {
			resolve: {
				alias: {
					$utils: path.resolve('./src/utils')

Then, to make TypeScript aware of the alias, add it to tsconfig.json (for TypeScript users) or jsconfig.json:

  "compilerOptions": {
    "paths": {
      "$utils/*": ["src/utils/*"]

How do I use environment variables? permalink

Vite uses dotenv to load environment variables from a file named .env or similar. Only environment variables prefixed with VITE_ are exposed. You would need to instantiate dotenv yourself if you want all environment variables exposed in process.env['YOUR_ENV_VAR']. We hope to see all environment variables exposed on the server-side in the future.

Environment variables cannot be used directly in Svelte templates due an issue in the way Vite's define plugin works.

For example, you can create a .env file in your project root folder with a VITE_* variable:


Then you can access this variable in a .js or .ts module:

export const MESSAGE = import.meta.env.VITE_MESSAGE;

Then you can pull in the variable in your components from the module:

	import { MESSAGE } from `$lib/Env.js`
<h1>Hello, {MESSAGE}</h1>

You can also use Vite's define option:

define: { 'process.env.FOO': 'process.env.FOO' }

Please see the Vite documentation for more info about environment variables.

How do I include details from `package.json` in my application? permalink

You cannot directly require JSON files, since SvelteKit expects svelte.config.js to be an ES module. If you'd like to include your application's version number or other information from package.json in your application, you can load JSON like so:

const pkg = JSON.parse(fs.readFileSync(new URL('package.json', import.meta.url), 'utf8'));

How do I fix the error I'm getting trying to include a package? permalink

SSR in Vite is not yet stable. Libraries work best with Vite when they distribute both CJS and ESM in their package and you may wish to work with library authors to make this happen.

Svelte components must be written entirely in ESM. It is encouraged to make sure the dependencies of Svelte components provide an ESM version. However,in order to handle CJS dependencies vite-plugin-svelte will look for any CJS dependencies and ask Vite to pre-bundle them by automatically adding them to Vite's optimizeDeps.include which will use esbuild to convert them to ESM.

If you are still encountering issues we recommend checking the list of known Vite issues most commonly affecting SvelteKit users and searching both the Vite issue tracker and the issue tracker of the library in question. Sometimes issues can be worked around by fiddling with the optimizeDeps or ssr config values.

How do I use X with SvelteKit? permalink

How do I setup library X?

Please see the community site for examples of using many popular libraries like Tailwind, PostCSS, Firebase, GraphQL, mdsvex, and more. We recommend using Svelte adders which allow you to run a script to automatically add popular technologies to a newly created SvelteKit project.

How do I use svelte-preprocess?

svelte-preprocess provides support for Babel, CoffeeScript, Less, PostCSS / SugarSS, Pug, scss/sass, Stylus, TypeScript, global styles, and replace. Adding svelte-preprocess to your svelte.config.js is the first step. It is provided by the template if you're using TypeScript. JavaScript users will need to add it. For many of the tools listed above, you will then only need to install the corresponding library such as npm install -D sassor npm install -D less. See the svelte-preprocess docs for full details.

How do I use Firebase?

Please use SDK v9 which provides a modular SDK approach that's currently in beta. The old versions are very difficult to get working especially with SSR and also resulted in a much larger client download size. Even with v9, most users need to set kit.ssr: false until vite#4425 and firebase-js-sdk#4846 are solved.

How do I use a client-side only library that depends on document or window?

Vite will attempt to process all imported libraries and may fail when encountering a library that is not compatible with SSR. This currently occurs even when SSR is disabled.

If you need access to the document or window variables or otherwise need it to run only on the client-side you can wrap it in a browser check:

import { browser } from '$app/env';

if (browser) {
	// client-only code here

You can also run code in onMount if you'd like to run it after the component has been first rendered to the DOM:

import { onMount } from 'svelte';

onMount(async () => {
	const { method } = await import('some-browser-only-library');
	method('hello world');

If the library you'd like to use is side-effect free you can also statically import it and it will be tree-shaken out in the server-side build where onMount will be automatically replaced with a no-op:

import { onMount } from 'svelte';
import { method } from 'some-browser-only-library';

onMount(() => {
	method('hello world');

Otherwise, if the library has side effects and you'd still prefer to use static imports, check out vite-plugin-iso-import to support the ?client import suffix. The import will be stripped out in SSR builds. However, note that you will lose the ability to use VS Code Intellisense if you use this method.

import { onMount } from 'svelte';
import { method } from 'some-browser-only-library?client';

onMount(() => {
	method('hello world');

How do I setup a database?

Put the code to query your database in endpoints - don't query the database in .svelte files. You can create a db.js or similar that sets up a connection immediately and makes the client accessible throughout the app as a singleton. You can execute any one-time setup code in hooks.js and import your database helpers into any endpoint that needs them.

How do I use middleware?

adapter-node builds a middleware that you can use with your own server for production mode. In dev, you can add middleware to Vite by using a Vite plugin. For example:

const myPlugin = {
  name: 'log-request-middleware',
  configureServer(server) {
    server.middlewares.use((req, res, next) => {
      console.log(`Got request ${req.url}`);

/** @type {import('@sveltejs/kit').Config} */
const config = {
	kit: {
		target: '#svelte',
		vite: {
			plugins: [ myPlugin ]

export default config;

See Vite's configureServer docs for more details including how to control ordering.

Does it work with Yarn 2?

Sort of. The Plug'n'Play feature, aka 'pnp', is broken (it deviates from the Node module resolution algorithm, and doesn't yet work with native JavaScript modules which SvelteKit — along with an increasing number of packages — uses). You can use nodeLinker: 'node-modules' in your .yarnrc.yml file to disable pnp, but it's probably easier to just use npm or pnpm, which is similarly fast and efficient but without the compatibility headaches.

See also the Svelte FAQ for questions relating to Svelte directly.