SvelteKit 1.0 migration guide (from SvelteKit alpha)

[Rich-Harris]

General advice

We highly recommend to not directly update to 1.0 and instead go through the breaking changes one-by-one. This way, the migration instructions will be easier to follow and also be more correct - some of them might be slightly outdated since they are shadowed by subsequent changes.

If you're prior to version 1.0.0-next-406

New versions of SvelteKit include a design overhaul that will require some changes to your app. (You can read about the overall reasoning behind these changes in #5748.)

To begin migrating your app, run the following command:

npx svelte-migrate routes

You will need to do this before installing the new version! We recommend updating to the most recent version before these changes — @sveltejs/[email protected] — and ensuring that your app works with that version before running the migration.

This will rename files inside your routes folder (see this comment to learn more about the changes), migrate some of the changes automatically and annotate your code with errors that link back to this page and tell you what needs to be manually updated. You can find these errors by searching your codebase for @migration.

If you're after version 1.0.0-next-406

If you update to versions past that, there are some more breaking changes, which are described in more details with info on how to migrate in their respective PRs. Again, we advise you to do these step by step, always updating to the relevant next-X version, then migrate, then go to the next next-X version, until you've reached 1.0:

• layout rework (1.0.0-next.432): Implement new layouts system #6174
• sveltekit attribute changes (1.0.0-next.454): feature: Replace sveltekit:* with valid HTML attributes like data-sveltekit-* #6170
• prerendering and configuration changes (1.0.0-next.455): Prerendering overhaul #6392, [breaking] ssr/hydrate/router/prerender.default are now configurable in +page(.server).js and +layout(.server).js #6197
• form actions (1.0.0-next.472): Form actions #6469
• prerendering/config changes (1.0.0-next.560): rename prerendering to building, remove config.kit.prerender.enabled #7762
• preload/prefetch changes (1.0.0-next.565): Replace data-sveltekit-prefetch/prefetch(...)/prefetchRoutes(...) #7776
• Rename invalid to fail (1.0.0-next.578): [breaking] rename invalid(...) and ValidationError #8012
• Vite peer dependency update (1.0.0-next.579): Upgrade to Vite 4 #7543

There may be small breaking changes inbetween those listed above. All have a meaningful error thrown with either direct migration instructions or a link to the PR which explains how to migrate.

For a list of all breaking changes: https://github.com/sveltejs/kit/pulls?q=is%3Apr+label%3A%22breaking+change%22+is%3Aclosed or https://github.com/sveltejs/kit/blob/master/packages/kit/CHANGELOG.md (breaking changes are marked with [breaking])

Upgrading to 1.0

Make sure to first upgrade to the last version before the 1.0 release that still has all the errors and warnings that help you with upgrading. That version is 1.0.0-next.588. They are removed from 1.0 onwards.

[Rich-Harris]

Update load function

Previously, your layout/page components could export a load function from <script context="module">. This function has been moved into a separate file — +page.js for pages, +layout.js for layouts — and the API has changed.

Input parameter

The following were removed/renamed from/in the input parameter:

• stuff (see below)
• props (renamed to data, see below)

Types

SvelteKit will generate a $types module for each route which you can use to gain type safety when dealing with parameters and data.

For a page file:

// TypeScript
-import type { Load } from './__types';
+import type { PageLoad } from './$types';

export const load: PageLoad = () => {
  // ...
}

// JavaScript with TypeScript in JSDoc comments
-/** @type {import('./__types').Load} */
+/** @type {import('./$types').PageLoad} */
export function load() {
  // ...
}

For a layout file:

// TypeScript
-import type { Load } from './__types';
+import type { LayoutLoad } from './$types';

export const load: LayoutLoad = () => {
  // ...
}

// JavaScript with TypeScript in JSDoc comments
-/** @type {import('./__types').Load} */
+/** @type {import('./$types').LayoutLoad} */
export function load() {
  // ...
}

Return value

Instead of returning an object with some combination of status, error, redirect, cache, stuff, dependencies and props, your load function should just return the data that the component needs.

export function load() {
  return {
-    props: {
-      answer: 42
-    }
+    answer: 42
  };
}

Errors

Instead of returning { status, error }, throw an error constructed with the error helper from @sveltejs/kit:

+import { error } from '@sveltejs/kit';
+
export function load() {
-  return {
-    status: 400,
-    error: new Error('not found')
-  };
+  throw error(400, 'not found');
}

Redirects

Similarly, redirects should be thrown using the redirect helper:

+import { redirect } from '@sveltejs/kit';
+
export function load() {
-  return {
-    status: 307,
-    redirect: '/login'
-  };
+  throw redirect(307, '/login');
}

There is a known bug with redirect: it will currently fail during client-side navigation, due to #5952

Cache

When running on the server, load can now set arbitrary headers with the provided setHeaders function, which you can use to control caching behaviour:

export function load({ setHeaders }) {
-  return {
-    cache: {
-      maxage: 300,
-      private: false
-    }
-  };
+  setHeaders({
+    'cache-control': 'public, max-age=300'
+  });
}

Data from the server

If you have a +page.server.js or +layout.server.js file that exports a GET handler, this handler will run before load. The data returned from the handler is available to the load function as the provided data object:

-export function load({ props }) {
-  console.log(props.data_from_the_server);
+export function load({ data }) {
+  console.log(data.data_from_the_server);
}

If you have a +page.server.js or +layout.server.js and you don't have a load function, it's equivalent to this:

export function load({ props }) {
  return props;
}

Stuff

If you have a load function in your layout(s) as well as in your page, the functions will now run concurrently. To receive data from a parent load function, use the provided parent function:

-export function load({ stuff }) {
  console.log(stuff.a);
+export async function load({ parent }) {
+  const data = await parent();
+  console.log(data.a);

  return {
-    stuff: {
-      b: stuff.a * 2
-    }
+   b: data.a * 2
  };
}

The data from all your load functions (or +layout.server.js/+page.server.js files) is merged into a single object that can be used anywhere in your app via $page.data, which replaces $page.stuff.

Dependencies

The provided depends function takes over from dependencies:

-export function load() {
+export function load({ depends }) {
-  return {
-    dependencies: ['/foo', '/bar']
-  };
+  depends('/foo', '/bar');
}

[Rich-Harris]

Update +page.server.js

This file, previously referred to as a page endpoint, exists to provide your page with data from the server. The data retrieval function was renamed from GET to load. The other handlers still correspond to HTTP methods — POST, PUT, PATCH and DELETE. NOTE: These other handlers are removed in favor of form actions in a later breaking change, see this PR for migration instructions on that.

Types

The types of your handlers can be imported from ./$types, which is generated by SvelteKit per-route. Previously, handlers were typed with the RequestHandler type, but should now use the type specific to the method:

// TypeScript
-import type { RequestHandler } from './__types';
+import type { PageServerLoad } from './$types';

-export const GET: RequestHandler = () => {
+export const load: PageServerLoad = () => {
  // ...
}

// JavaScript with TypeScript in JSDoc comments
-/** @type {import('./__types').RequestHandler} */
-export function GET() {
+/** @type {import('./$types').PageServerLoad} */
+export function load() {
  // ...
}

Return value

Instead of returning { status, headers, body }, load (formerly GET) should just return data:

export function load() {
  return {
-    body: {
-      answer: 42
-    }
+    answer: 42
  }
}

POST, PUT and PATCH handlers should not return data. They can return an errors object of validation errors that can be used for UI (provided to the component as an errors prop), plus an optional status that defaults to 400 when error is provided and is otherwise ignored:

export async function POST() {
  return {
    status: 418,
-    body: {
+    errors: {
      foo: 'bar'
    }
  };
}

POST handlers can, on success, return an optional location property pointing to the newly created resource:

export function POST() {
  return {
    location: '/items/123'
  };
}

DELETE handlers should have no return value.

Errors

As with load functions in +page.js, errors should be thrown using the error helper from @sveltejs/kit:

+import { error } from '@sveltejs/kit';
+
export function load() {
-  return {
-    status: 400,
-    body: new Error('not found')
-  };
+  throw error(400, 'not found');
}

Redirects

Redirects should also be thrown, using the redirect helper from @sveltejs/kit:

+import { redirect } from '@sveltejs/kit';
+
export function load() {
-  return {
-    status: 307,
-    headers: {
-      location: '/login'
-    }
-  };
+  throw redirect(307, '/login');
}

Setting headers

Previously, headers other than set-cookie were ignored when returned from a page endpoint. Headers can now be set using the provided setHeader function:

export function load({ setHeaders }) {
  setHeaders({
    'x-foo': 'bar'
  });
}

+layout.server.js

It's also possible to create a +layout.server.js with similar semantics to +page.server.js, except that it can only export load rather than POST, PUT, PATCH or DELETE, and the data type is LayoutServerLoad instead of PageServerLoad.

[Rich-Harris]

Update +server.js

This file, previously referred to as a standalone endpoint, gives you low-level control over how SvelteKit responds to requests.

Types

As with +page.server.js, types can be imported from ./$types:

// TypeScript
-import type { RequestHandler } from './__types';
+import type { RequestHandler } from './$types';

export const GET: RequestHandler = () => {
  // ...
}

// JavaScript with TypeScript in JSDoc comments
-/** @type {import('./__types').RequestHandler} */
+/** @type {import('./$types').RequestHandler} */
export function GET() {
  // ...
}

Return value

Instead of returning a { status, headers, body } object, +server.js handlers should return a Response object:

export function GET() {
-  return {
-    status: 200,
-    headers: {
-      'x-foo': 'bar'
-    },
-    body: {
-      answer: 42
-    }
-  }
+  return new Response(JSON.stringify({ answer: 42 }), {
+    headers: {
+      'content-type': 'application/json; charset=utf-8'
+      'x-foo': 'bar'
+    }
+  });
}

If you use the set-cookie header with multiple values, you need to transform it using the Headers object:

-  return new Response('blah', {
-    headers: {
-      'set-cookie': [a, b]
-    }
-  });
+  const headers = new Headers();
+  headers.append('set-cookie', a);
+  headers.append('set-cookie', b);
+  return new Response('blah', { headers });

[Rich-Harris]

Add data prop

Instead of having multiple props corresponding to the props returned from a load function, page components now have a single data prop which is automatically typed:

<script>
-  /** @type {string} */
-  export let foo;
-
-  /** @type {boolean} */
-  export let bar;
-
-  $: console.log({ foo, bar });
+  /** @type {import('./$types').PageData} */
+  export let data;
+
+  $: console.log(data);
</script>

If you want to have quick-and-dirty migration, you can destructure the data prop using a reactive assignment - that way, you don't need to touch the rest of the file:

<script>
-  /** @type {string} */
-  export let foo;
-
-  /** @type {boolean} */
-  export let bar;
-
-  $: console.log({ foo, bar });
+  /** @type {import('./$types').PageData */
+  export let data;
+  let { foo, bar } = data;
+  $: ({ foo, bar } = data); // so it stays in sync when `data` changes
+
+  $: console.log({ foo, bar });
</script>

A page that has a +page.server.js file with a POST/PUT/PATCH handler can also receive an errors prop containing validation errors:

<!-- TypeScript -->
<script>
  import type { PageData, Errors } from './$types';

  export let data: PageData;
  export let errors: Errors;
</script>

<!-- JavaScript with TypeScript in JSDoc comments -->
<script>
  /** @type {import('./$types').PageData */
  export let data;

  /** @type {import('./$types').Errors */
  export let errors;
</script>

Layouts

The same applies to layouts, only that you need to use LayoutData (for +layout.svelte) or LayoutData.named (for +layout-named.svelte) instead of PageData when you want to type your data prop.

[Rich-Harris]

Check for missing imports

If a layout/page component had a <script context="module">, it will have been moved into a +layout.js or +page.js file. In most cases this is what you want, but occasionally the script block may have included imports (or declared variables) that are used in the main body of your component and therefore need to be moved back.

[Rich-Harris]

Replace error load function

__error.svelte files have been renamed to +error.svelte.

Previously, an error file could export load from <script context="module">, consequently the <script> was able to receive props from it. This is no longer the case — error pages should render immediately without the opportunity for further things to go wrong.

You can access status and error from the page store:

<script>
  import { page } from '$app/stores';
</script>

<h1>{$page.status} : {$page.error.message}</h1>

[dummdidumm]

File name changes

The router is now folder-based, not file-based. This means there's now only one way to describe a route.

Here's how you define that there's a route /about:

Old	New
routes/about/index.svelte	routes/about/+page.svelte
routes/about.svelte	routes/about/+page.svelte
routes/posts.json.js (a standalone endpoint)	routes/posts.json/+server.js

The same principle applies to parameterized routes:

Old	New
routes/[slug]/index.svelte	routes/[slug]/+page.svelte
routes/[slug].svelte	routes/[slug]/+page.svelte

The naming of the routing files has changed. They correspond as follows (assuming the first variant of the table above):

Old Description	Old	New
page UI	index.svelte	+page.svelte
load function etc	<script context="module"> in index.svelte	+page.js
page endpoint	index.js with index.svelte next to it	+page.server.js
standalone endpoint	index.js without index.svelte next to it	+server.js
layout UI	__layout.svelte	+layout.svelte
load function etc	<script context="module"> in __layout.svelte	+layout.js
		+layout.server.js (server GET for layout, didn't exist previously)
error UI	__error.svelte	+error.svelte
load function etc	<script context="module"> in __error.svelte	No longer exists

To summarize: All route files have a + sign in front now to distinguish them at a glance and group them, the contents of <script context="module"> is moved into a separate file, which means that there's now at most three files per page (or layout).