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}" />

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 fix the error I'm getting trying to include a package? permalink

Old beta versions of the SvelteKit template included the configuration value noExternal: Object.keys(pkg.dependencies || {}) in svelte.config.js. First, please check if this line is present in your project and remove it if so. Removing this line fixes most issues and has since been removed from the template.

Note that you can no longer directly require JSON files, since SvelteKit expects svelte.config.js to be an ES module. You can load JSON like so:

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

The second most commonly-encountered issue is having a Svelte component that imports a CommonJS library. In this case, you should try to work with the library authors to distribute an ESM version of the dependency. However, in the meantime, you can workaround this issue by adding the dependency to vite.optimizeDeps.include in svelte.config.js.

Also, some older Svelte libraries don't work nicely with Vite's pre-bundling process, check out @sveltejs/vite-plugin-svelte's docs for current limitations and workarounds.

If you are still encountering issues we recommend 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 sveltejs/integrations for examples of using many popular libraries like Tailwind, PostCSS, Firebase, GraphQL, mdsvex, and more.

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.

Also see sveltejs/integrations for examples of setting up these and similar libraries.

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.

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. In this case, you may still find a benefit of including a browser check as shown below because Vite may otherwise attempt to optimize the dependency and fail on it. We hope to make this unnecessary in the future.

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

	let lib;

	if (browser) {
onMount(async () => {
	lib = (await import('some-browser-only-library')).default;

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.

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.

Internal server error: The request url [...] is outside of Vite serving allow list permalink

For security reasons, Vite has been configured to only allow filesystem access when the request file fulfils one of these requirements:

  • Within workspace root
  • Within the listed server.fs.allow exceptions
  • Part of the dependency graph of your application code

Refer to Vite documentation for server.fs.allow for configuration and more details.

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