Fixing load, and tightening up SvelteKit's design before 1.0

[Rich-Harris]

migration guide now available at #5774!

update: thank you! #5748 (comment)

updated! #5748 (comment)

I've edited this post with the amendments described in that comment.

---

Alright friends, strap in — this will be a long read, but hopefully one that leaves you as excited about SvelteKit's future as we are. What follows is a proposal for a set of changes that address the wartiest bits of SvelteKit's design, particularly the more confusing aspects of load — it should enable us to close #3021, #3751, #4274, #4656, #4801, #4815, #4911, #5218, #5467, #5537, #5633, #5669, #5732, #5750 and #5532, and it will reframe discussions taking place in a couple of dozen other issues.

It will involve some migration work proportional to the size of your app. For that, we're sorry. (We're particularly sorry to people who have created educational content around the current design.) Because of the scale of the changes, we're taking the unusual step of building a migration script that will do as much as can be automated and annotate your codebase for the remainder with errors like this:

throw new Error(
  '@migration task: Update handler return values (https://github.com/sveltejs/kit/issues/xxxx#yyyy)'
);

tl;dr

Please don't comment on the discussion after only reading this section! It's here to prime the pump and to give you something to refer back to once you've digested the entire thing, including the rationale for the various design decisions.

With that caveat, this proposal:

• replaces the current file-and-directory based routing with something more explicit: directories dictate which routes are created, and route files such as +page.svelte dictate how those routes behave
• moves load into a separate +page.js file along with export const prerender etc
• adds page-level export const ssr = false control
• radically simplifies the load API
• improves SSR and navigation performance by allowing load functions to run concurrently
• simplifies endpoints
• replaces page props with a single data prop, plus an errors prop for validation errors from POST/PUT/PATCH handlers, and...
• ...insodoing, vastly improves the TypeScript experience

Let's dive in.

Why are we doing this?

The current filesystem-based routing design has some weak spots:

• There are multiple ways to express a route. src/routes/foo.svelte and src/routes/foo/index.svelte are equivalent, and having two ways to do things is always a source of confusion. Each has downsides — too many index.svelte files open in your editor gets confusing, but foo.svelte makes it awkward to colocate related files. I frequently find myself moving foo.svelte to foo/index.svelte as the route becomes more complex (e.g. it needs a dedicated error page, or it gains a child route, or I need to break something out into a separate component, or it needs a page endpoint, and so on). These changes are costly and annoying, and I always kick myself for not just always using folders.
• It often makes sense for components and modules to be colocated with the route that uses them. Many people will create a src/routes/foo/Widget.svelte, unaware that this creates an unwanted and broken /foo/Widget route. It's possible to mark files as 'private' with config.kit.routes (the default is to treat _Widget.svelte, the aesthetics of which make me shudder, as private) but this is a little convoluted.
• Speaking of aesthetics, __layout.svelte and __error.svelte are just... ugly.
• A file like src/routes/foo/index.json.js creates a /foo.json route. Everything about this is wantonly confusing.
• Generated types are great, but they're hideous to use. A file like src/routes/foo/[id=integer]@somelayout.svelte must import its generated types from ./__types/[id=integer]@somelayout, and keep it in sync if [id=integer] is renamed to [id=uuid] (though after said rename, VSCode will have tried to 'fix' the import, usually to something batshit insane).

Meanwhile, load has a number of confusing aspects:

• It's in the same file as the layout/page component, in a <script context="module">. This leads many people to ask 'why can't arbitrary components have a load function?', to which the unsatisfying answer is 'you just can't, it doesn't work that way'. The data tree and the render tree are separate-but-related concepts, and our current design conflates them.
• Components (other than those layout/page components) can't access the data tree without 'prop drilling'.
• It's rather boilerplatey.
• In its current incarnation, it prevents (or at least discourages) parallel loading, which is bad for performance. We want to make it hard for you to build a slow site.
• One of its arguments is literally called stuff because we couldn't figure out what else to do with it. We think stuff is unnecessary, for reasons we'll explore below.
• The return value is extremely convoluted — all the possible properties (error, status, redirect, cache, dependencies, stuff, props) are optional, but some require other properties to make sense (e.g. redirect needs a 3xx status, status needs an error if it's larger than 400, but an error doesn't need a status) and others don't make sense in combination (e.g. error and props). Good luck teaching TypeScript about all these quirks, much less humans.
• The status and error arguments are bizarre. status is usually null, but will have a value if it's an __error.svelte file of if there's a page endpoint, but also you can return a status code that will override the status code that was passed in, except sometimes it won't, because reasons. This behaviour is confusing enough that I don't think we even have tests for a lot of it, much less documentation.
• There's no linkage between the returned props and the type of the props in the component itself — you have to redeclare the types, uselessly. (The same goes for page endpoints.)

We don't want to throw the baby out with the bathwater. load has some great qualities — SvelteKit makes it very easy to use external APIs for your data without going back to your server (which costs money for you and time for your users), or to delay navigation until some work has happened without attempting to render, or populating the data tree with things that can't be serialized (like components!) — and these are worth preserving.

But we can definitely do better. The rest of this document will explain how.

Routing

This will seem familiar if you've read #5037, though it has a few small changes.

Instead of defining routes via files and folders, routes are only defined by folders. Layout and page components are defined with +layout.svelte and +page.svelte files — so src/routes/about.svelte would become src/routes/about/+page.svelte.

The + prefix marks the file as being a route file. This scheme has a number of benefits:

• Files without the prefix (like Widget.svelte) are simply ignored by the router, making colocation easy without workarounds
• Route files are grouped alphabetically — in your editor, a route directory will contain child directories, route files, and ordinary files, in that order
• If we need to add more route files in future (e.g. +loading.svelte), we can do so without it being a breaking change, because + is a reserved prefix

If a page uses a named layout, it can be expressed as [email protected].

Why +?

We considered a variety of characters (~, @, #, $, %, -, +, =, _ and so on).

Some of these don't work well in some contexts ($ needs to be escaped in the terminal, for example). Others have an existing meaning (_ in particular has a well-established connotation that it makes the thing private, whereas +page.svelte is defining the public interface of your app) that rules them out. @ and # feel very 'heavy', as in they occupy a lot of black pixels.

We ultimately landed on + because you're adding a route to your app (or some behaviour to your route). It's a lightweight, symmetrical character that doesn't have baggage, and doesn't need to be escaped (though vim users will need to do vim ./+page.svelte instead of vim +page.svelte).

As to 'why do we need to prefix route files at all?', see the Prefixes section of this comment.

Endpoints

If a page has an endpoint, it lives in the route as +page.server.js. We will also introduce layout endpoints — +layout.server.js. (We're not using +page.js and +layout.js for this, as they have another purpose described below.)

This bears repeating as it might be unexpected at first: if today you have src/routes/foo/index.svelte and src/routes/foo/index.js, these don't both become +page.{js,svelte}. index.svelte becomes +page.svelte but index.js becomes +page.server.js, because +page.js has a different meaning, covered below.

Standalone endpoints are expressed as +server.js. A +server.js file cannot coexist with +page.svelte.

In future we might retire the use of terminology like 'endpoint' in documentation and elsewhere, in favour of talking about +page.server.js and +server.js files

At present, src/routes/foo/index.json.js creates a /foo.json route. Under this proposal, it will be necessary to create a separate route:

src/routes/foo.json/+server.js

The API for endpoints will change, as detailed below.

New load API

As mentioned, <script context="module"> is a problematic home for load. As such, it — along with other module exports like prerender — will move to new files, +page.js and +layout.js, making them siblings of +page.svelte and +layout.svelte. (Error components — +error.svelte — will no longer be able to use load, as this is a source of bugginess and confusion for the sake of an arguably undesirable feature.)

In case you're wondering why we have both +page.js and +page.server.js: like +page.svelte, +page.js runs on the server during SSR and in the client during hydration and navigation. +page.server.js, by contrast, only runs on the server, so it can access your database or filesystem (and private environment variables etc) directly. You can use one or the other (or both together) depending on your needs. The same goes for +layout.js and +layout.server.js.

Separating everything out into a separate file gives us three big wins:

• It clearly communicates that load belongs to the route and not the component, eliminating the 'why can't my Widget.svelte have a load?' confusion.
• We can reinstate export const ssr = false. This used to live inside the component, and would tell SvelteKit not to SSR a given page, but in order to read ssr SvelteKit had to import the component. Since the most common reason for not wanting to SSR a page was that it used components that couldn't be imported server-side, this blew everything up, and we replaced it with an option in handle that is much less ergonomic than a granular, declarative boolean.
• It means TypeScript can easily understand your load function. I'm very excited about this — it's going to be absolutely huge for ergonomics and productivity — but an explanation is out of scope for this section, so for now just trust me.

The function signature will also change.

Inputs

Today, load takes a single LoadEvent argument — an object with url, params, props, fetch, session, stuff, status and error. We're removing stuff, status and error, renaming props to data, and adding three new functions — parent, depends and setHeaders:

• stuff prevents layout load functions from running in parallel with the page load function.
• error and status are redundant (and confusing, as described above) — $page.status and $page.error should be used instead.
• data is a more agnostic and universal term that can be used more consistently throughout the design. In this case it refers to data served from +page.server.js, allowing you to intercept/munge/augment/disregard data from the server.
• parent (open to bikeshedding) allows a load function to opt back in to the waterfall in cases where that's necessary for the purposes stuff is used for today.
• depends (again, bikesheddable) allows a load function to declare a dependency on a specific resource (replacing dependencies, which is only necessary in niche circumstances)
• setHeaders will give pages the ability to set headers during SSR, including cache-control. (Unnecessary-for-now but potentially interesting detail: in the future, we plan to introduce a streaming rendering mode that will flush headers and the first bytes of HTML before the page has loaded and rendered. In that mode, setHeaders would throw an error, since you can't set headers once the response is already on its way to the user.)

If you have both +page.js with a load and a +page.server.js with a GET, SvelteKit will call the GET first and pass the data to load. If you only have +page.js, SvelteKit can run the load immediately, with data = {}.

Outputs

Instead of returning a complicated object as described above, load simply returns data:

// src/app/foo/+page.js

/** @type {import('./$types').Load} */
export function load(event) {
  return {
    // ok, you probably don't need a `load` function for this
    answer: 42,
    food: 'potato'
  };
}

This means we can no longer return redirect, status, error, cache, stuff or dependencies. Let's address these in reverse order.

• dependencies: ['/foo', '/bar'] can be replaced with a call to depends('/foo', '/bar')

• stuff is used for two purposes — to cascade things from the top to the bottom, and to pass things like <title> or breadcrumbs from the bottom of the data tree to the top of the render tree, so it can be used in <svelte:head> or <nav> etc. We'll ignore the latter for now and focus on cascading. Using the parent function, we can capture all the data that has been loaded by parent load functions (and +page.server.js files, as appropriate):

  // src/routes/+layout.js
  export function load({ fetch }) {
    const res = await fetch(
      'https://www.randomnumberapi.com/api/v1.0/random?min=1&max=100&count=1'
    );
    const [number] = await res.json();
  
    return {
      number
    };
  }
  
  // src/routes/foo/+page.js
  export async function load({ parent }) {
    const { number } = await parent();
    return {
      doubled: number * 2
    };
  }

  This prevents the second load function from running until we've got data from randomnumberapi.com.

• Instead of magic cache values, we simply make it possible to set headers directly from load. Most of the time setting cache-control headers on HTML is a mistake, I think, but if you know what you're doing then we will no longer stand in your way.

• There's only one reason to set status, and that's if something went wrong. Otherwise it should just be 200. Accordingly, under the new rules the way you set an error status is just by throwing an error. We'll expose a helper function from @sveltejs/kit/data (bikesheddable) to allow you to throw errors that have a status code attached:

  // src/app/admin/+layout.js
  import { error } from '@sveltejs/kit/data';
  
  /** @type {import('./$types').Load} */
  export function load({ session }) {
    if (!session.user) {
      // second argument is an optional error message
      throw error(401, 'show yourself, coward');
    }
  
    if (!session.user.is_admin) {
      throw error(403, 'insufficient mojo');
    }
  
    // ...
  }

  A thrown error that didn't come from the error helper would result in a 500 status code and trigger the handleError hook.

  With the code above, any /admin/* route will error if the user isn't signed in or isn't an admin. We don't need to repeat that logic in child load functions, because await parent() will also throw if the right conditions are not met:

  // src/app/admin/settings/+page.js
  
  /** @type {import('./$types').Load} */
  export function load({ parent, fetch }) {
    // this throws if user is not an admin...
    await parent();
  
    // ...meaning we don't bother fetching this data that would
    // have been discarded anyway
    const res = await fetch('...');
  
    // ....
  }

• This next one might feel weird but bear with me — redirects are also thrown. That's partly because a redirect result is semantically closer to an error result than to success, but partly because it's useful if await parent() throws in the redirect case as well as the error case:

  // src/app/admin/+layout.js
  -import { error } from '@sveltejs/kit/data';
  +import { error, redirect } from '@sveltejs/kit/data';
  
  /** @type {import('./$types').Load} */
  export function load({ session }) {
    if (!session.user) {
      // second argument is an optional error message
  -    throw error(401, 'show yourself, coward');
  +    throw redirect(307, '/login');
    }
  
    if (!session.user.is_admin) {
      throw error(403, 'insufficient mojo');
    }
  
    // ...
  }

Exposing data from load

Assuming we have some data from our load function in +page.js or +layout.js (or from +page.server.js/+layout.server.js if we're getting data direct from the server instead of via load), the next step is to use it in our components.

Today, the component exposes individual props. If you're building an ecommerce site you might have something like this:

<script>
  /** @type {Array<{ product: import('$lib/types').Product, qty: number }>} */
  export let cart;

  /** @type {import('$lib/types').Promotion[]} */
  export let promotions;
</script>

But there's a problem here — there's nothing forcing that laboriously-typed cart prop to actually correspond to the type of data the component receives. It could be renamed items, or qty could become quantity. If you're lucky, that'll result in a runtime error you can try and debug, but you're equally likely to ship NaN and undefined to production.

In the new world we have a single data prop, which is automatically typed:

<script>
  /** @type {import('./$types').Data} */
  export let data;
</script>

The ./$types module is automatically generated by SvelteKit from your source code — a slightly more sophisticated version of our existing generated types.

Page-level data

The data prop contains only what was returned from load (or +page.server.js, if there's no load). In some cases it's useful for a layout to be able to use data from the page load, for example populating <title> from a single <svelte:head> rather than requiring each page to add <svelte:head> separately.

We can do that with $page.data, which contains everything.

<!-- src/app/+layout.js -->
<script>
  import { page } from '$app/stores';
</script>

<!-- it doesn't matter where in the app this component is! -->
<svelte:head>
  <title>{$page.data.title}</title>
</svelte:head>

Conceptually, $page.data looks like this:

$page.data = {
  ...(await load1()),
  ...(await load2()),
  ...(await load3()),
  ...(await loadn())
};

+page.server.js and +layout.server.js API

The Artist Formerly Known As Endpoints also gets an API facelift. One of the rough edges of the current design is that 'page endpoints' and 'standalone endpoints' are very similar-looking but are in fact entirely different beasts — standalone endpoints can return a Response or at least a Response-like object with streaming binary data and custom headers etc, while page endpoints can only return a POJO (Plain Old JavaScript Object) so it can be passed directly to the page for SSR then serialized as JSON to travel over the wire. Also, headers returned from page endpoints are silently ignored, which is weird.

This redesign fixes all that. +page.server.js and +layout.server.js have a different API to +server.js. We'll cover +server.js in the next section.

As with today's page endpoints, +page.server.js exports handlers named for the HTTP methods they handle — GET, POST, PUT, PATCH and DELETE. (We might add OPTIONS in time.) +layout.server.js is not involved in mutations, so it only exports GET.

GET

Like load, a GET handler just returns data, rather than { status?, headers?, body } as now:

// src/routes/foo/+page.server.js

/** @type {import('./$types').GET} */
export function GET() {
  return {
    answer: 42
  };
}

There's only one useful status for a GET request — a 200. Anything else indicates something went wrong, so — as with load — we throw in those cases, using the same helpers as before:

// src/routes/foo/+page.server.js
import { error } from '@sveltejs/kit/data';

/** @type {import('./$types').GET} */
export function GET({ session }) {
  if (session.user?.name !== 'Dan') {
    throw error(403, `If your name's not Dan, you're not coming in`);
  }

  return {
    answer: 42
  };
}

Headers (including cache-control and set-cookie) can be set with the same setHeaders function passed into load.

POST

While +server.js gives you complete control over the Response (see below), in +page.server.js we can streamline things in a way that satisfies the common case and makes it easy to implement progressive enhancement (I hope to resurrect the <Form> discussion soon).

In the case of POST, there are basically three possible outcomes — success, failure due to input validation errors, and failure due to something unexpected that requires showing an error page.

Unexpected failures are easy to deal with, as it's the same as load and GET — throw error(status).

Validation errors cause the page to be re-rendered with the errors, so they can be used for UI that guides the user towards valid inputs:

// src/routes/todos/+page.server.js

/** @type {import('./$types').POST} */
export function POST({ request }) {
  const data = await request.formData();

  if (!data.get('description').includes('potato')) {
    return {
      errors: {
        description: 'Must include the word "potato"'
      }
    };
  }

  await create_todo(data);
}

<script>
  /** @type {import('./$types').Data} */
  export let data;

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

<form method="post">
  {#if errors?.description}
    <p class="error">{errors.description}</p>
  {/if}
  <input name="description">
  <button type="submit">Create new TODO</button>
</form>

As with today's page endpoints, the GET function will also be called in the case of validation errors, so that both data and errors are populated when the page reloads.

By default this page will render with a 400 status code, though an optional status property returned alongside errors can override it if necessary.

Redirects

A common pattern with POST requests is to redirect to the newly created resource. We can achieve this in SvelteKit by returning a location property that indicates where the created resource lives:

// src/routes/todos/+page.server.js

/** @type {import('./$types').POST} */
export function POST({ request }) {
  const data = await request.formData();

  if (!data.get('description').includes('potato')) {
    return {
      errors: {
        description: 'Must include the word "potato"'
      }
    };
  }

-  await create_todo(data);
+  const id = await create_todo(data);
+
+  return {
+    location: `/todos/${id}`
+  };
}

A native form submission would cause the browser to redirect to /items/${id} with a 303; if no location is provided the page would simply reload (perhaps using the PRG pattern?).

In a progressive enhancement context where you're submitting data via fetch (either manually, or via a framework-provided <Form> abstraction), you might prefer to get a hold of the created resource rather than reloading the page or redirecting to /items/${id}. In those cases, SvelteKit could match the location to a +page.server.js file (or call GET in the current +page.server.js file) and return the data in the response. We don't need to figure out all the details for this aspect right now, but I'm confident that we're on the path towards an even better progressive enhancement story than we have today.

PUT and PATCH

These methods are basically the same as POST, except that since no new resource is being created, there's no need to return a location property.

DELETE

DELETE is simpler still; no data is being submitted, so there's no room for errors. If the function succeeds, SvelteKit responds with a 204.

+server.js API

As mentioned, +server.js differs from +page.server.js — rather than providing an unserialized POJO to the page for SSR, +server.js is responsible for constructing the entire response. In this new design, we make this responsibility clear — rather than the { status, headers, body } return value, handlers must simply return a Response.

As conveniences (and to keep things consistent), the error and redirect imports and the setHeaders helper can be used, though strictly speaking they're not necessary since you could construct your own error/redirect Response objects with whatever headers you like.

+server.js is useful when you need to expose a public API, or you need to do things that aren't possible with +page.server.js like streaming binary data.

Next steps

We plan to implement this new design (and the migration script) as soon as we're able to, incorporating feedback from this discussion along the way.

I know this all seems like a lot, and you're probably exhausted from reading it. (Imagine how I feel after writing it.) As a result, you might feel like this is a lot of new complexity, just because of the sheer amount of information you've just ingested. In reality, this is a significant simplification, and — when presented in the form of documentation and educational content — will be much easier to learn. I promise.

[mvllow]

I appreciate all the work/thought put into this as well as the willingness to make such significant changes for the benefit of all users.

First impression is that the plethora of naming conventions related to routing are a step backwards. Svelte usually encourages "using the platform", whether it be the simplistic style tag over something like css-in-js or the lack of unnecessary boilerplate when dealing with reactivity. These design decisions make Svelte easy to pick up, especially by those without experience in other frameworks. The addition requirement of using /about/+page.svelte not only raises the learning curve for newcomers but also distances itself from the platform, where we are used to seeing about.html or /about/index.html.

I won't pretend to understand the inner-workings of these changes. If the new naming conventions are necessary on any level to get the technical benefits such as the simpler load function, then so be it. This is less a complaint and more expressing a slight discomfort with the direction compared to what I personally feel Svelte did so well – reducing cognitive load and staying close to the "vanilla" way of doing things.

[Rich-Harris]

Something I've often observed as an open source maintainer is that when changes are proposed, parts of the existing userbase will use the learning experience of hypothetical future users as a reason to resist the change:

it's difficult to understand at first glance

undeniably adding to the learning curve, when accessibility to newer developers is one of the best things about Svelte

In reality, often the main thing that impedes learning is ambiguity. The current approach has ambiguity in spades, whereas the proposal offers a single canonical way to declare routes. And on the subject of 'simplicity'...

simple is better no?

...it's important to distinguish 'simple' from 'familiar': #5748 (reply in thread)

What I don’t like is page-data and layout-data

Agree. I want to change these to +page.server.js and +layout.server.js (and +server.js, for 'standalone endpoints').

[shmert]

Putting server in the name makes it instantly clearer. Except those seem like they could be construed as "comment" sections of the name?

[rsweeneydev]

As I was reading the proposal, I thought to myself: "It's a shame they picked +page.data.js rather than +page.server.js"

I don't see the rational for using "page" as the special keyword to identify the handler for "foo/". HTTP already has a convention: "index".

• +page.svelt => index.svelte
• +page.js => index.loader.js
• +page-data.js =>index.server.js

Adding a "+" prefix to the name is ugly.

[Envl]

Is it a good idea to differentiate components from pages in folder routes using "comment" e.g. Avatar.component.svelte? So that we can name a route as it is.

[WhyAsh5114]

In reality, often the main thing that impedes learning is ambiguity. The current approach has ambiguity in spades, whereas the proposal offers a single canonical way to declare routes.

Ok, I agree with you, but TBH +page.svelte seems weird, maybe index.svelte could be the default reserved name? Or even page.svelte?

Anything is fine really. I was a bit upset about the routing changes before, but now I get why you would want to do this.

EDIT: Also I apologize for confusing simple with the familiar. I get the +page.svelte, it's more explicit, but maybe we could have something that is both familiar and simple, like index.svelte.

[TheOnlyTails]

While at first this seemed weird, it grew on me while I was reading it.
Would making simple static routes (like src/routes/+index.svelte) still be possible?
creating a whole new directory for a single file seems excessive.

[TheOnlyTails]

yeah, MDSveX might have an issue here

[Rich-Harris]

All routes will be defined by a directory.

In the case of /, the directory is src/routes itself, so that would be src/routes/+page.svelte. While it might seem excessive in the case of e.g. src/routes/about/+page.svelte, it will soon pay for itself in a variety of ways: it's future-proof (if you suddenly realise you need a component that's only used on /about, no problem figuring out where to put it), you can copy-paste your type declaration...

/** @type {import('./$types').Data} */

...from any other export let data wherever without needing to adjust the import path, and your file tree is more sanely organised — rather than this (actual screenshot from the demo app)...

...you'd have this, which makes it much clearer that /todos and /about are siblings than in the current case, where things are strewn about higgledy-piggledy:

src/routes/
├ about/
├ todos/
├ +layout.svelte
└ +page.svelte

Creating an intermediate directory is a moment's pain, but pays ongoing dividends.

[TheOnlyTails]

Hm, I see what you mean. i think some confusion can come from /index/+page.svelte not being equivalent to /+page.svelte.

[TravisSpomer]

I think you are really underestimating the pain of adding the extra directory, especially for content-focused sites that don't require much or any back-end code. But you're a super smart dude and have thought this through 500x as long as I have, so I will defer to your wisdom here.

Worst-case, someone who finds this really obnoxious for whatever reason could use SvelteKit for sites that are "apps" and something like Astro+Svelte for sites that are just static content (which SvelteKit is currently awesome for!).

[fabiogiolito]

I don't understand some of the issues that this change fixes (or they don't affect me --yet, they might be too advanced to me). But I can say this makes things more complicated for me me (a basic user) to understand how to build with sveltekit.

Allowing components to be mixed with routes is a step backwards in clarity and organization. Some components are with specific routes, others are elsewhere because they're more global… we're losing the simple "lib stuff is here, routes are here" changing to "things can be anywhere because for a route to count it must have this specific structure and name".

If I understood correctly, a basic app structure will change like this:

before

src/routes/
├ user/
    ├ __layout.svelte
    ├ index.svelte
    ├ following.svelte
    └ followers.svelte
├ __layout.svelte
└ index.svelte

after

src/routes/
├ user/
    ├ +layout.svelte
    ├ +layout-data.js
    ├ +page.svelte
    ├ +page-data.js
    ├ following/
        ├ +page.svelte
        └ +page-data.js
    └ followers/
        ├ +page.svelte
        └ +page-data.js
├ +layout.svelte
├ +layout-data.js
├ +page.svelte
└ +page-data.js

[PizzaConsole]

Seems like a pretty solid design update to me (from probably the little I understood 😁) Thanks for the in depth update!

[prvaghasiya]

Thank you for your work on SvelteKit

Currently I could not find a way to communicate from page to layout.
for example, when I need to update navbar (present in layout) after some state changes in page.

Can we also think of this communication (from page to layout with reactivity) in this new design?

[Theo-Steiner]

You can do this to some extent with stores already.
Although the dream for me would be if we could just dispatch events in a route and listen to it from layouts.

[Bandit]

Sounds like you could use $page.data for this now?

[antony]

This is because the flow of data from page -> layout would be the wrong direction.

For predictability, data should primarily flow downwards (two way bindings are a necessary exception).

What this means is that you should tell your page to update something in the hierarchy above the navigation (a store, perhaps) and your navbar should be reactive to this change.

[Rich-Harris]

$page.data can contain anything, including stores, so you could in theory share a store that is written to in the leaf and read from in the layout

[Theo-Steiner]

I think the proposed changes really could add a lot of value to SvelteKit as while they do increase (file-system) verbosity, they also could help adding quite a bit of clarity.

I personally am most excited about the new abilities for passing around loaded data:

const { number } = await parent();

to access data from upwards the tree and an app wide $page.data store as an escape hatch, when data needs to travel upwards. This used to be quite difficult due to stores being so finicky during SSR.

Does const { number } = await parent(); mean that props have to be named uniquely along page trees? If so, it would be great if typescript could help with that.

Regarding naming: I think +data.js, +page.svelte and +page-data.js are very descriptive and will really help beginners with the mental model of what runs on the server and what on the client: everything with 'data' in it runs on the server, page runs on the client. This is not true for +page.js in my opinion though, as it will run both on the client and the server and thus behave very differently from the very similarly named +page.svelte. Would perhaps +load.js not be a better name to indicate this difference?
The optional labels are a really great feature for orienting yourself!

My last question is regarding the auth guard example.
For no load function down the page tree to run concurrently with the auth guard, do they all have to await parent()?
Assuming that the protected routes could become quite nested, this seems like a lot of boilerplate. If one node of the tree were to skip awaiting the parent, it and all its children would run concurrently with the authentification guarding load function, correct?

Very excited about the future of kit. You maintainers all rock!

PS: I feel for early svelte kit content creators...

[elliott-with-the-longest-name-on-github]

This is not true for +page.js in my opinion though, as it will run both on the client and the server and thus behave very differently from the very similarly named +page.svelte

This isn't true though, right? Both +page.js and +page.svelte will run on the client OR the server depending on the context. In this regard, they are the same.

[Duenke]

Isn’t it true that EVERYTHING runs on the server if not a static app, and then endpoint functions ONLY run on the server after initial load?

I feel it’s nice in theory to try distinguish server safe code from client unsafe code (secrets and what have you), but I think it would be much cleaner to drop +page-data.js and lump endpoints in with load() in the +page.js file. This would strengthen the idea that +data.js is special and also make the idea that load() is actually optional if you just want unprocessed data from the GET endpoint.

[Rich-Harris]

Data properties don't have to be uniquely named - they'll be merged, with { foo } from the page load overwriting { foo } from the layout load. They'll be typed correctly either way (at least, I'm 90% sure this is possible!).

It's not possible to combine +page.js and +page-data.js into a single file, because +page.js needs to run in the browser, and combining them would make it impossible to import there.

[i-am-gizm0]

I'm not the biggest fan of the properties getting merged/overwritten (although with this pattern, I can't think of any better ideas)... I know I've used similar names in multiple layers? before and I can see this becoming a trap for beginners and causing weird bugs unless that's really well/obviously documented

[Rich-Harris]

I would argue that if you're using the same name to refer to different things, that's the problem, not the fact that they're getting merged. If anything, this will encourage people not to overload common words, and that's a good thing.

That said, everything will be correctly typed. If you have something like this...

// src/routes/+layout.js
export function load() {
  return {
    thing: 1
  };
}

// src/routes/foo/+layout.js
export function load() {
  return {
    thing: 'x'
  };
}

// src/routes/foo/+page.js
export async function load({ parent }) {
  // TypeScript will understand that `thing` is a string and not a number
  const { thing } = await parent();

  return {
    THING: thing.toUpperCase()
  };
}

[rchrdnsh]

hmmmm…the new routing changes don’t feel so great to me…have not thought them through, however…just curious if anybody floated the idea of having different special characters for different types of routes, so as to avoid excessively long files names?

maybe:

+ for routes
- for layouts
= for data

or something along those lines, so as to avoid writing +page or +layout, etc…

will read through the thing again as well…

[Theo-Steiner]

At least with the above proposal, +page.svelte,+page.js, +data.js and +page-data.js are all fixed names, so they won't become excessively long. Shortening the syntax to just a symbol is very easily overlooked IMO.

[jchanes04]

This goes in the wrong direction IMO, there's a fine line between having special symbols to indicate something special about the file and having so many symbols that it becomes difficult to keep track of everything. The ability to name files is enough to differentiate them without trying to codegolf the names with a potentially easily overlooked character.

[rchrdnsh]

I agree in general, but these naming conventions will already sometimes require a + and a - and a @ in the same file name if I’m reading it correctly? Which I might not be (late, tired, brain broke). If page files all used one symbol and data files all used one symbol and layout files all used one symbol, then that is three symbols, and no more, like traffic lights. Anymore than that would be too much, but maybe any less than that invites other complexities that might be subjectively worse, like comically long filenames?

Sidenote…are emojis valid in file names? (Kinda only partially joking, tbh ;-P

[Rich-Harris]

You missed error pages. And then if we later decide to add loading UI and a route-level config.json we're up to six special characters. Non-starter I'm afraid.

[rchrdnsh]

ahhhh...so there would be more than three file categories...understood :-)

[pilcrowonpaper]

That was a lot to take in (especially with so much page and data) but to summarize the new routes directory:

• +page.svelte: The client-side page (client)
• +page.ts: The current `context="module" (client+server)
• +page-data.ts: A simplified endpoints (server)
• +data.ts: Do everything by yourself (everything), can't co-exist with the rest
• +layout.svelte: Layout
• +layout-data.ts: Layout context="module"
• +layout.ts : Layout endpoints ← Q. What are these?

I understand it, and now I'm starting to prefer "directory-based" routing, but there's got to be better names for the files. I don't know if it was just me, or its way too confusing.

First, not a big fan of +. It already has a meaning of "to add," and it feels weird to have it (like, what are we adding?). I feel it's better to stick with the current convention of using _ or __, which doesn't have any assumed meaning.

Anyway, we shouldn't be using page, data, or a combination of them. On top of being confusing by itself, it creates even more confusion since you get returned value from the load function (which is in page.ts) with $page.data (but page-data.ts also exists). I also find data to be too much of a catch-all term (it can represent anything). Something like this would make it much more easier to understand and memorize (I suck at naming stuff but the point is we should name them and stick with it):

• _page.svelte (+page.svelte)
• _page-module.ts (+page.ts)
• _page-endpoints.ts (+page-data.ts)
• _requests.ts (+data.ts)
• (same for the layouts)

Also, I'm not sure about labeled files. I think it's wrong to add "comments" to file names in the first place, but that could just be me. Using named layouts, it'll look like [email protected], which not only looks wrong and but also looks like .label is connected to @layout. If we can get rid of labels or change how its implemented, my previous name-change could look like this:

• _page.svelte
• _page.module.ts
• _page.endpoints.ts

which I much prefer, and it also takes the [filename].[data_type].[file_extension] form that the data.json.ts take.

Other things:

• I'm not too sure about "auto-cascading" in load functions. It wish there was a better way to control which parent you're getting from, though it might not be too big of a deal.

[AnatoleLucet]

Why even bothering prefixing a _/+? Couldn't page.svelte, page-module.js, etc. be reserved names?

[elliott-with-the-longest-name-on-github]

Why even bothering prefixing a _/+? Couldn't page.svelte, page-module.js, etc. be reserved names?

Because then if SvelteKit ever needs a new reserved file, it's a breaking change. If in the future we needed to reserve "potato.svelte", we'd have to bump a major version because someone somewhere could have used that name in their project. With a prefix, we can reserve that prefix, allowing us to add +literallyanything.anything and it won't be a breaking change.

[jacob-8]

How about reserving page.svelte, page.js, etc, without prefixes and also reserving + so that there is room to use +potato.svelte in the future? This would be the proper use of the + character as it would indicated to users "Hey, there's a new type of reserved filename added after the release of SvelteKit 1.0 - make sure you're using a recent enough version to be able to use this type of file." Then in SvelteKit 2.0, the plussed filenames, +potato.svelte, could be trimmed down to just potato.svelte as they are no longer new additions.

[amr3k]

I really got confused by all the pages in this proposal!

[BiscuiTech]

While I disagree with your use of the _ keyword, your naming convention strongly resonates with me. It's extremely confusing with all the pages and datas. I can't quickly tell you what page.js and data.js does and it's a problem.
I can understand why Rich went for it originally (extending the use of the reserved work data onto the filenames kinda makes sense), but I feel we lost meaning along the way.

[prvaghasiya]

Is parent data (await parent()) going to be accessible outside load like $page.stuff?

[Theo-Steiner]

yup, search for $page.data in Rich's post!

[qriosdev]

A lot of exciting stuff! Appreciate your work.

Feel a bit unsettled about file naming but I guess it's a matter of getting used to. With good documentation and examples, especially about differences and main use cases for +page.js and +page-data.js, people should be able to figure out what they need.

[MattStopa]

Lots of great points in the post. This is just my personal opinion but it feels at this point that routing will be extremely complicated. There are going to be a lot of rules to learn and a lot of "ahhh why isn't this working?!?!" IMO.

This to me at least is pretty confusing
src/routes/foo.json/+data.js

It almost feels like a non directory based router would be easier rather than having to infer things.

[Duenke]

I think he included this route as foo.json to describe the transition more easily. In practice, I think it would be silly to name a route as “.json”, and instead you might create an endpoint like src/routes/produce/+data.js. The whole “.json” convention is legacy from when the files had to have those extensions.

[saturnonearth]

After reading through a couple times, I think I am beginning to understand it. I won't comment too much on some of decisions made as they are out of the scope of my expertise, but I will say one thing...seeing filenames begin with + hurts me on the inside. it just feels...wrong

[Theo-Steiner]

I see where you're coming from, but the alternative to using special characters in file based routing would be to limit what you can name your files and have reserved names... not exactly better either

[saturnonearth]

Yea that is true, but using a character that is universally seen as an "action" is the wrong approach, imo. There are other character or character combinations that could be considered. Let's have a vote! 😂

[elliott-with-the-longest-name-on-github]

I believe in the maintainers' chat the reason we decided on + was because it is an action: You are adding functionality to your route.

[jycouet]

Nice to read about the reasoning behind the +

[saturnonearth]

I believe in the maintainers' chat the reason we decided on + was because it is an action: You are adding functionality to your route.

I still think that sometimes it's better to stick with more commonly used symbols than something that makes logical sense because as programmers we are creatures of habit and it is OK to hold onto things that give us a sense of familiarity. You don't see a lot of files start with + for a reason.

[chanced]

Is file-based routing worth it once your conventions reach routes/about/[email protected]?

Simple file names to page routes are easy enough to grasp. "Create aroutes/about.svelte and you get an /about page. Need a layout? create a __layout.svelte file." Obviously that simplicity comes at a cost of flexibility.

Some of these changes are trying to introduce flexibility but are spiking the complexity without the advantage of being discoverable. There is no way to know that +data and +page has special meaning if you aren't educated beforehand. You can't ask your IDE via code-completion what the API is. You must obtain the knowledge of conventions and maintain it to function.

Obviously a lot of thought has been put into this and I hope it works out for the project.

[TravisSpomer]

For the filename /src/routes/about/[email protected] and the route /about, the filename is 86% magic, and the important part is in the middle. Obviously that's a near-worst-case scenario, but it's also not a terribly contrived or unrealistic one.

[Theo-Steiner]

I agree in that [email protected] looks comical, but I think you are grossing over the fact that the label is entirely optional and [email protected] looks a lot less complicated.
Edit: and @layoutname is also a very rare case.

[rchrdnsh]

I don’t KNOW if this will be true, but I can imagine I will ALWAYS label everything, so then every file name will 67 characters long with dots and dashes and plusses and minuses and ooooomlawts, and…

[Rich-Harris]

There is no way to know that +data and +page has special meaning if you aren't educated beforehand

The beauty of having an unusual prefix is that it immediately clues you into the fact that there's something special about this file. The minute you Cmd-K and search for +page it will immediately become clear because there's zero ambiguity or terminology (you don't need to know to search for words like 'endpoint'). Unless, of course, people make a conscious choice not to RTFM in which case shrug.

I agree about the labels, I hate them. They're only included as a sop to people who have dozens of page files open simultaneously and think the naming conventions are the problem, rather than the fact that they have dozens of page files open simultaneously. I might propose getting rid of them when I refine this RFC.

[chanced]

@Rich-Harris

The beauty of having an unusual prefix is that it immediately clues you into the fact that there's something special about this file.

That is certainly true. I do think the prefix may need to be something different though as someone mentioned in the comments that vim +page.svelte doesn't work.

I agree about the labels, I hate them.
Same, but I see why they were proposed and why you included them.

I guess I'm just old and still favor explicit routing with a declarative struct utilizing something like the proposed URLPattern over file-based routing. However, I concede that almost all of the popular front-end frameworks have opted for file-based routing so there must be merit which I'm too antiquated to appreciate.

The changes to load are great by the way.

As always, thanks for the effort you and everyone else working on svelte / kit has put in.

[josh-collinsworth]

At present, src/routes/foo/index.json.js creates a /foo.json route. Under this proposal, it will be necessary to create a separate route:

src/routes/foo.json/+data.js

IMO, this is not less confusing than foo.json.js. I'd even go so far as to say it's more confusing adding a faux file extension to the name of a directory than it is to a file.

Could it be possible to do foo/json/+data.js instead, and make the return type part of the path? That could be a bit more intuitive in some ways.

I can easily imagine downsides to that suggestion. It's just that adding a file extension to the name of a folder seems like a very awkward convention, and not a step in the right direction if the goal is to make endpoint naming more intuitive.

[lukaszpolowczyk]

foo.json      .js
vs
foo.json/+data.js

And the latter is simpler and less confusing. ;D

When you add /+data in the middle, it all becomes simple and unambiguous. ;D

[Theo-Steiner]

I think while this is ugly it simply is the price to pay for moving from a file-based routing system to a directory based routing system.
every directory directly maps to one segment of the url

[lukaszpolowczyk]

@Theo-Steiner Apparently so, but I feel that SvelteKit is no longer svelte. It's no longer "the best DX in the world," but "some DX."

[saturnonearth]

@Theo-Steiner Apparently so, but I feel that SvelteKit is no longer svelte. It's no longer "the best DX in the world," but "some DX."

It's funny you mentioned this, because as I was reading the changes, I thought the exact same thing. But I thought that was just my lack of experience in things like routers. To me, a big selling point of Svelte and SvelteKit were the ease of entry and intuitively. Things felt more like native JS and just worked - this feels like it's extrapolating too much in the name of "future proofing" - but I definitely could be wrong. I love Svelte and it really re-sparked my love for web dev. I definitely don't want it to become "some DX".

[Duenke]

I think he included this route as foo.json to describe the transition more easily. In practice, I think it would be silly to name a route as “.json”, and instead you might create an endpoint like src/routes/produce/+data.js. The whole “.json” convention is legacy from when the files had to have those extensions.

But if you really wanted to, it looks like foo/json/+data.js is a valid endpoint path.

[kenmcewan]

Lots to like, lots I don't fully understand but sounds sensible.

The one change that seems a bit contrived is the labels on filenames. Can see the use for identifying files but without the knowledge that it is just for labelling it would be expected to be something different. Would some way of identifying it as a non-standard part of a file be viable, so

src/routes/about/+page.about.svelte
src/routes/contact/+page.contact.svelte

would become:

src/routes/about/+page.[about].svelte
src/routes/contact/+page.[contact].svelte

Yes a bit more work in naming the file when using labels but as it's optional it doesn't add overall and hopefully makes it clearer it's a "special" part of the filename.

[Mlocik97]

doesn't it make bigger sense to put [about] to folder name? What if I want to prepend it in 2nd level of 3 level pathname route? Like /someting/[slug]-something/something/?

[lukaszpolowczyk]

I don't understand the problem of turning a route file into a route folder at all:

folder3.mp4

In my opinion, TOTALLY route files without folders should be allowed.

Changing one into the other is a natural step, and fabulously easy.
Am I not understanding something?

I mean something like I wrote earlier that _name.svelte should be the route file.

[Duenke]

100% agree that it should be an option. /data.svelte should equal /data/+page.svelte.

[amr3k]

Thanks, this is really helpful tip, it would be great to have some kind of a bash script to automate the conversion

[enyo]

It's not that it's difficult to do, it's that it's not uniform. This becomes a point of discussion in teams... some will prefer to always create the folder so it's uniform, and some will prefer the shorter syntax. It's also harder to easily see which routes are available in one glance since some will be folders, some won't.

[lukaszpolowczyk]

@enyo I understand it, but the argument with difficulty was also written by Rich.
It is simply inconsistent with the truth. :P

Route files can be optional, just as hidden files are now.
But I repeat - I understand the need to simplify in general.

[Hecatron]

One thought would be a plugable routing system.
Currently it is possible to use Routify within sveltekit via the use of a catchall route. (which is what I'll probably be doing especially if these changes go through)
There was some discussion on it here #2731

But something that can more easily be switched out depending on how someone wants to do the routing
such as programatically via an api instead of file based, or a combination of both would be an idea.

One thing I tend to be against from a personal preference is crowding the filenames with metadata or symbols.
I tend to prefer that sort of thing being inside a file instead of part of the file name, but that's just personal preference.

I think file based routing only works in the context of when it's simple.
I suspect creating a directory for every file may become a bit messy personally.
If you're trying to do something more complicated than simple routing then I would tend to opt for something code based over file based naming conventions, since you end up trying to fit too much information into a directory or filename.

[jesperordrup]

Routing is such a huge thing and I think it should stay in sveltekit. If there wasn't an official router we would always deal with examples and docs using some new/other/differentl router

[Hecatron]

You can still have an official router, just also provide options for alternatives at the same time.
I don't see having examples using a different router being a bad thing personally, since you'd likely want to use something different based on the particular use case, such as a small simple project vs a large complex one.

Some of it is also based on coding style and how the end project is going to be designed. For example I might have a case where I want to use api based routing for pages but I also want to use file based routing for api endpoints.

Ultimately if you try and force things so that only one direction is possible it's likley this could be a turn off for a lot of folk.
At the moment we still have the catchall approach which I'm grateful for at least, it just doesn't feel that elegant.

[xpertekShaun]

Use another framework, there are tons to choose from. forcing your will on a framework probably results in a worse framework.
You could always contribute via code commits, pushing routing into config files is a bad idea.

[Hecatron]

Personally I wouldn't push routing into config files, instead I'd opt for code based routing in a single "optional" file at the top of a directory. Basically an API hook into the router that could be customised to alter the behaviour of the router in whatever way you wanted to, or just leave alone and parse the directory using the defaults with no file present, that way you get the best of both worlds.

As for forcing my will onto a framework, I disagree I'm doing that by suggesting there should be multiple options available, or api hooks that 3rd partys could hook into, I would say quite the opposite.

[k-amryn]

While we're on the idea of simplifying project structure, one suggestion I would add is the ability to have static files in the folders with our source code, instead of a separate static folder. If each route now gets its own directory it would feel natural to include images and other page assets in the folder for the page they're used on, such that typing "./mypicture.jpg" actually refers to "the .jpg in this current folder" instead of "the .jpg in the current folder of the .html file after being compiled"

[CaptainCodeman]

The potential drawback of this is if the route has any parameters - it would be less than optimal to be serving the same image from multiple URLs, it would be a potential foot-gun.

For purely static routes though, it kind of makes sense although mixing together code + static content may end up a little messy.

[Mlocik97]

it would be pain to implement... having ./static/ folder is really simple, Vite just copy it to build. Nothing else... But if it would be in folder all over ./src/routes/, there would need to be crawler... also how will Vite decide if it's static and shouldn't be processed or if it's something that needs to be processed? This is really something I think is bad idea.

[Rich-Harris]

https://kit.svelte.dev/docs/assets

[swyxio]

a mild suggestion for the prefix - + also bothers me but i could live with - but i am wondering if kit. as a prefix wouldnt work?

kit.page.js, kit.layout.js. more searchable, still easy to type and say, and makes obvious it is a sveltekit api

whatever you guys decide i will live with :) its awkward and appreicate the effort spent here.

[CaptainCodeman]

Is that fewer pixels? ;)

Contrived reason: prefix with the power symbol as it "powers" the route. Or 'it looks like an insert character, as the page is "inserted" at this point of the routes'

Ship it.

[Mlocik97]

and it even looks like small arrow that points to directory name

love this idea from vultix

[Mlocik97]

another idea is kit_ prefix, that is longer to write and messy.

[Mlocik97]

also is it really problem that _ is for private modules and __ is for Kit specific files?

[nulladdict]

That’s actually a pretty cool prefix. It’s short enough, readable, consist entirely out of safe characters and gets right to the point (saying that this files are special to sveltekit)

[swyxio]

from a teaching and DX POV, the number of files does concern me. a big draw of Svelte was single file components, and with this proposal we no longer have single file routes (arguably we never had them... anyway).

• when teaching: the more files people have to jump back and forth, the slower you go, compared to "open up one file and paste this in, we can step thru the code later".
• when coding: having to jump between files, keep the docs up, etc slows down the flow

that is of course a thing we can let go if we must, but if @pilcrowonpaper's summary is accurate (i couldnt remember the number of new files to know while reading the proposal) then we have at least 8 new files to keep in mind. (and he didnt even include the .server variants).

traditional estimates for people's working memory of cardinality is 3-5. we're looking at 8 or more here and asking the sveltekit developer to get comfortable with a lot of filename syntax. just want to make sure we make this choice consciously - file "api"s are more costly to change than code "api"s

i dont have the knowledge/havent spent the time to make a constructive suggestion but

1. how much can we consolidate the .server or .data files?
2. or centralize the layout logic and only use the [email protected] named layout convention (doubles down on the "one way to do things" concept)

[Rich-Harris]

You don't have eight new files, you have one new file per page (+page.js) and one new file per layout (+layout.js). The others already exist, just with different (and confusingly inconsistent) names

[vipero07]

While this is all seems like sound architecture the thing that is most interesting to me is "in the future, we plan to introduce a streaming rendering mode that will flush headers and the first bytes of HTML before the page has loaded and rendered".

Please tell me that means rendering similar to Marko.

On a more related note; You mentioned index.svelte being problematic for having multiple open... It really isn't if you just use ctrl+p even if you have tons of files open. Regardless, +page.svelte and the other + routes doesn't address that concern. But you already knew that.

[Hecatron]

Personally I would tend to disagree, but it's largely a question of personal preference.
Ctrl P doesn't replace tabs it's just a different way of selecting files. In the same way using Explorer is a different way of selecting files. Or you could open up windows files explorer and double click the file to open the file.
Having a different way to do a thing, doesn't make the original way redundant but it can be more inconvenient.

That being said I would say it's a minor issue compared to some of the others listed such as compatibility with vim with the + sign.

[Explosion-Scratch]

This whole discussion has been a bit confusing to me, is this a good summary of what's going on:

• route/index.svelte → route/+page.svelte
• route.svelte → route.svelte
• route/__layout.svelte → route/+layout.svelte
• route/index.js → route/+page.server.js

[Mlocik97]

except second one, yes.

[CaptainCodeman]

2nd one would be:

route.svelte → route/+page.svelte

There's also route/+page.js, right? Which I think should be the endpoint*, but I believe it's the load (?)

*Most of my routes would then be:

route/+page.svelte
route/+page.ts

i.e. the things that are typically the most common are the shortest. I think the loader would benefit from a clearer name, and if SK is working well you likely don't need it anyway.

[Explosion-Scratch]

@CaptainCodeman that's a really big change,so every single route would need an entire folder?

[CaptainCodeman]

That is the change in the OP

[cdcarson]

Thanks for your work, and the opportunity to give feedback. Huge upvote for the way you are throwing errors and redirects. How to do that consistently has been a recurring pain in the neck.

I don't have much skin in the game about file naming, just as long as (1) the convention is settled and (2) the debate about naming does not obscure what I'd call -- just my opinion -- More Important Things. For example, my biggest takeaway from this proposal is that SvelteKit is moving full-on toward route middleware. That is, the ability to do data-fetching and business logic in +layout.server.js files as well as in the endpoint and in hooks.js.

One of the reasons I like Kit now is that it does away with middleware in the classic, inchoate, terrible, Express sense. Kit forces you to answer questions like "is the user logged in?" and "may the user see this kitten's dashboard?" at the route level rather than in some abstraction, most likely premature, residing elsewhere. The details of answering such questions can still be abstracted out, but you still have to ask them (a good thing) in each endpoint. Application-wide things like reading/writing cookies and logging can be handled in the hooks, where you can see at a glance, in one file, what's going on.

I realize that I will probably still be able to do this -- I won't be tied to a chair & forced to use +layout.server.js. I also realize that there's no accounting for taste and some people may really like middleware. But I think there are a couple of reasons to rethink the +layout.server.js middleware pattern as something the platform encourages or allows.

• It takes developer focus away from the route at hand. Rather than explicitly asking a question in the route endpoint, you're left wondering whether you have asked it elsewhere. Elsewhere may be several folders up the tree.
• You need to write an integration test to see whether an endpoint works. Unit testing an endpoint no longer guarantees its correctness to the same extent it would if it were directly responsible for all the logic and data. It may rely on things from middleware that might have gone away or changed shape. To be fair, such breaking changes may also happen in hooks.js. But that's just one file, not two or six.
• The name +layout.server.js (regardless of what the eventual convention is) does not and cannot convey what is going on inside. Contrast this with a file named gate-kitten-dashboard.js.

Whole platforms have sprung up to try to make middleware less dicey, more testable, etc. They've had limited success. (Try to do simple email/password authentication in Nest.js/Passport, for example.) The basic problem with middleware -- the implicit, tight coupling it introduces and the intendant confusion -- remains.

I'd really like to see SvelteKit go all in the other way, stick a fork in middleware for good, and encourage folks to concentrate on the logic of individual pages.

[Rich-Harris]

I feel like we didn't do a good job of explaining +layout.server.js, so let me try here: if you have a project like this...

src/
├ routes/
│ ├ my-api-route/
│ │ └ +server.js
│ ├ my-page-route/
│ │ ├ +page.js
│ │ ├ +page.server.js
│ │ └ +page.svelte
│ ├ +layout.js
│ ├ +layout.server.js
│ └ +layout.svelte
└ hooks.js

...then when you hit /my-page-route the following will happen:

1. handle in hooks.js runs, which calls resolve, which identifies the route and
2. calls +layout.server.js and my-page-route/+page.server.js concurrently. as each returns, +layout.js and my-page-route/+page.js are called with the resulting data
3. the return values of load are then used to render +layout.svelte and my-page-endpoint/+page.svelte

The +layout.server.js isn't middleware in the sense that it intercepts the request and does something with it before my-page-route/+page.js sees it; those happen in parallel. But in the same way that +page.server.js gives us a nice easy way to get data from the server into +page.svelte, +layout.server.js gives us a nice way to get data from the server into +layout.svelte.

(A typical route wouldn't need all these files, of course — in the vast majority of cases you'd just use the .server.js files if you have any data requirements, or want to implement auth guards and what-have-you.)

If you hit /my-api-route, the process is simpler:

1. handle in hooks.js runs, which calls resolve, which identifies the route and
2. returns the Response from the GET handler in my-api-route/+server.js

The +layout.js file isn't involved in this exchange at all, since we're not rendering a page.

[CaptainCodeman]

Can /my-page-route/+page.server.js wait for the parent data from /+layout.server.js in any way (if it depends on it), or is it only the UI load functions?

Having some middlewarish ability is lacking right now.

[rumack]

Must say, I'm really enthusiastic about these changes. I had only started to programme when Svelte and Sapper arrived on the scene -- it's all I've ever used for designing and creating web applications so I'm not inclined to compare it to other frameworks. This new design makes total sense to me and clears up quite a lot of lingering confusion I had. Can't wait to start implementing it. I've a few apps going into production over the next few weeks so the sooner it's ready the better from my perspective. Good luck with the implementation!

[hubert-ix]

My first reaction after reading this is a lot of mixed feelings. I love Svelte and SvelteKit and have started a number of professional projects with both of them. The main reason was because of the beautiful simplicity of Svelte and SvelteKit.

Of course we often always resist change, and I've tried to really understand the benefits of these changes for my specific projects. But unfortunately I don't really get it - probably my own fault.

I don't quite see for example what will be the benefit of having multiple +page.svelte over multiple index.svelte. That seems to be the same thing, except that:

1. we lose the huge benefit of having files named after the URL (/about.svelte matching /about)
2. we lose the beauty of index.svelte being like index.html

Also putting the load function (or its equivalent) in another file will pretty much double the number of files in my project. So, I don't quite see the benefit there.

So, all in all, not particularly excited thus far.

[speiffer829]

I do not find the routing changes very cash-money at all.

[leddy231]

Overall sounds like a step in the right direction, especially the simplified load.

But I do agree with the rest of the thread that having a bunch of files named the same thing becomes confusing, it is already confusing enough with 5 different __layout.svelte tabs open.

Reading something like +page.svelte makes me think the filename is empty, which is confusing. it feels the same as .page.svelte

Could we simply allow for arbitrary prefixes to the files? ex:

routes/
├ item/
│ └ item+page.svelte
└ user/
 ├ user+page.svelte
 ├ user+layout.server.js
 └ user+layout.svelte

The prefixes can be whatever and does not have to match the folder name (but makes sense if they do)

[fabiogiolito]

Sharing my perspective of someone who has been empowered by Svelte and Sveltekit to build things despite having a somewhat medium knowledge of JS.

TLDR: The routes change has a big negative impact to beginner devs, are meant to solve very advanced usecases to the detriment of basic experience, and most justifications are debatable.

Going over each reasoning:

There are multiple ways to express a route. src/routes/foo.svelte and src/routes/foo/index.svelte are equivalent, and having two ways to do things is always a source of confusion.

Not that confusing. You can start with a file and move to a folder as needed, or just go with folders. Besides, “index” is pretty standard and is being dropped in this change.

Each has downsides — too many index.svelte files open in your editor gets confusing.

Editors have solutions for this. Renaming all to +page doesn’t solve the problem.

but foo.svelte makes it awkward to colocate related files.

Do not colocate files. Bad practice. It muddies the route structure. File based routing makes it straightforward to understand the entire route structure by looking at it, specially when you’re coming fresh to an existing codebase. With folder based and collocated files you have to pause and know which files create routes, which are extra things.

I frequently find myself moving foo.svelte to foo/index.svelte as the route becomes more complex.

That’s very natural, start simple and move to complex slowly. It’s just renaming a file. A this differentiation adds semantics to what’s a basic route and what’s more special. Or just use folders always, make it show a warning if you forget to do it.

It often makes sense for components and modules to be colocated with the route that uses them.

I disagree, it’s bad practice. There’s more value in separating components from helpers from routes…

Many people will create a src/routes/foo/Widget.svelte, unaware that this creates an unwanted and broken /foo/Widget route.

I don’t know if it’s a broad issue, but the folder is called routes. Maybe a better solution is having a default “components” folder to make it clear and unambiguous where components go instead of changing how everything else works.

Speaking of aesthetics, __layout.svelte and __error.svelte are just... ugly.

That might be a personal preference. Having every file start with a + is just as ugly. At least the “__” differentiates and indicates it’s a special case, while +layout and +page feel more like both are routes or on the same level.

A file like src/routes/foo/index.json.js creates a /foo.json route. Everything about this is wantonly confusing.

That’s actually what I’d expect if I saw a index.json.js not sure what the confusion would be here. I’d expect foo.json.js to create that same route as well.

Generated types are great, but they're hideous to use. A file like src/routes/foo/[id=integer]@somelayout.svelte must import its generated types from ./__types/[id=integer]@somelayout, and keep it in sync if [id=integer] is renamed to [id=uuid] (though after said rename, VSCode will have tried to 'fix' the import, usually to something batshit insane).

I have to admit I did not get into typescript yet so have not come across this issue and don’t know what it means for beginners.

Meanwhile, load has a number of confusing aspects:
It's in the same file as the layout/page component, in a <script context="module">. This leads many people to ask 'why can't arbitrary components have a load function?', to which the unsatisfying answer is 'you just can't, it doesn't work that way'. The data tree and the render tree are separate-but-related concepts, and our current design conflates them.

Isn’t the answer “because components are not routes”? It’s ok to say “because that’s not how it works”, changing the entire structure of how things work just to say “it still doesn’t work but now people wont ask as much” is not satisfactory.

Components (other than those layout/page components) can't access the data tree without 'prop drilling'.

Not seeing how this changes with the new structure. (Might be above my level of knowledge)

It's rather boilerplatey.

Moving to different file doesn’t make it less boilerplatey in itself, it’s just elsewhere now.

—
Other changes related to load are too specific and advanced that wouldn’t affect beginners in a negative way.

[elliott-with-the-longest-name-on-github]

Do not colocate files. Bad practice. It muddies the route structure. File based routing makes it straightforward to understand the entire route structure by looking at it, specially when you’re coming fresh to an existing codebase. With folder based and collocated files you have to pause and know which files create routes, which are extra things.

That's the whole thing -- with directory-based routing, it doesn't muddy the route structure. I run several production projects built on SK. Colocation is invaluable. Many times, I would have a thousand-line route file if I couldn't break it up into multiple components, but those components are often very specific to the route they're on. Without colocation, I would end up with a disgusting amount of $lib/routes/component-for-this-specific-route files.

That might be a personal preference. Having every file start with a + is just as ugly. At least the “__” differentiates and indicates it’s a special case, while +layout and +page feel more like both are routes or on the same level.

There's not really a solution to this other than to just RTFM. Directories are routes. Files are not.

Isn’t the answer “because components are not routes”?

Yes. Because components are not routes. Hence the change.

changing the entire structure of how things work just to say “it still doesn’t work but now people wont ask as much” is not satisfactory.

The point of the change is not this -- this is just a tertiary benefit. Two great reasons for this: 1. loads can run in parallel and 2. route-level settings don't reside in a Svelte file, meaning we can use route-level settings like export const ssr which didn't work inside a Svelte file.

Not seeing how this changes with the new structure. (Might be above my level of knowledge)

$page.data

[aloker]

Personally, I think the changes look promising. We're already creating folders per route most of the time. Having just one way of doing things will make onboarding much easier. The data/errors props API with auto generated types solves problems I'm experiencing all the time. I don't mind the + prefix. It clearly differentiates files with special meaning. The only situation that feels a tad weird is routes/my-api.json.ts vs routes/my-api.json/server.ts, but given all the advantages and consistency of the new structure I'm sure I'll get used to it.

Obviously a lot of thought went into this, so I wanted to balance the (fair) criticism a bit. I'm sure many silent users are looking forward to a more consistent, actual simpler approach to routing/endpoints/load.

[Rich-Harris]

I'm going to save future commenters the time and effort by locking this thread now. The discussion has been had, and the decisions have been made. Thank you to everyone who joined in!

I realise a few of you are still sceptical about some of these changes. At this point, there's nothing anyone can say that will convince you except experiencing it, and for that to happen we need to stop yakking and get cracking. I promise you'll come around. In the meantime, I'll leave this here:

[benmccann]

I wanted to take a minute to share an update and say thanks to the entire community here. It was truly amazing to see the passion around Svelte and SvelteKit. We saw people come forth with alternate proposals, graphs/flowcharts, example projects, testing against various tools, and so much more. There was real effort invested into sharing feedback here and while we can't give each individual post the response it deserves, I do want to make it clear that we read and gave real consideration to all of the suggestions here.

Design is inherently subjective and varies by usecase. People use SvelteKit to build small static sites and large interactive sites. They use different editors, tooling, libraries, infrastructure, and platforms. They work as individuals, on small teams, and on large teams. They are beginners, intermediate, or advanced users. They are consumers of the technology and/or teachers of it. Some build only their UI in SvelteKit while others build their whole site or applications. And so on... It was very helpful to have all of the input here to ensure we're considering all of the cases and making the best trade-offs for the user base as a whole including those who may adopt Svelte in the future.

The Svelte maintainers met for ~3.5 hours over the weekend to discuss the proposal and ensure we had landed on the most preferred design before beginning to implement any changes. The feedback here was taken into account a few days ago in updating the proposal to make changes such as removing labels and introducing a .server.js file extension and this is the version of the proposal that we considered. There were 11 maintainers in attendance and we discussed and then voted on each aspect of the proposal. While it's hard to see publicly the impact that the posts here had on the discussion, I want to make sure that everyone here knows that many of the individual posts were brought up and discussed and influenced the way that we each cast our votes. Some votes were closer than others. Ultimately we affirmed all aspects of the proposal except for one. There had been a suggestion to rename src/routes to src/app (#3021), which we decided not to move forward with.

We believe these changes will result in the best overall version of SvelteKit and we look forward to everyone being able to use it when it's available and continue to build it together. SvelteKit is the work not just of the growing group of maintainers, but also the whole community here. We'll be offering a migration guide and tooling to assist with some of the more automatable parts. In the meantime, we'll be largely pausing other development efforts including PR review for the next short while to allow us to focus on and land this large change.

Thanks again to everyone who participated in the discussion!