Simpler custom layouts

[Rich-Harris]

Update: The decision has been made, thank you for participating in the discussion!

The sense I've had from recent discussions is that people don't really like how named layouts work. And I kind of agree — a file with a name like [email protected] is doing a lot of work, and the inheritance rules (layouts can inherit from sibling layouts indefinitely, but if they don't specify a parent (wait — is it a parent or a sibling?) then they will go one directory higher to continue the search, unless you want them to inherit from the default layout at the current level in which case you can specify @default, which is a reserved name) are a lot to try and understand.

It's a powerful and flexible system, but it's not intuitive, and common tasks (grouping some-but-not-all siblings with a custom layout, or breaking out of the layout hierarchy to the root) are unnecessarily cumbersome.

Beyond that, the fact that it's possible for a directory to contain multiple different layouts adds some unavoidable complexity. For example, because there's no canonical root layout that everything is guaranteed to inherit from, we don't have a place to put code that gets run for every single page, or apply universal CSS. (We often talk about creating a dedicated client entry point — the equivalent of src/hooks.js but in the browser — that is responsible for hydrating the app and importing global CSS and e.g. firing analytics events on navigation, but there'd be no need to introduce a new concept like that if we had a root layout.) Implementation-wise, the extra complexity in the codebase is also a source of sadness for me personally.

Can we do better?

The two jobs of custom layouts

Fundamentally, there are two reasons to use custom layouts:

1. you want some portions of your app to use one layout, and other portions to use another (for example, /about and /testimonials might be 'marketing' pages, while /dashboard and /item are 'app' pages and /admin is neither)
2. you want a particular page or subtree to 'break out' of the current layout hierarchy — most likely to the root layout (which could be an empty <slot /> file), but possibly to something lower down. For example /item/[id]/edit might need to break out of the app layout or the item layout within it.

A lot of this can be achieved within a layout itself, by doing this sort of thing...

{#if $page.data.blank}
  <slot />
{:else}
  <div class="layout">
    <slot />
  </div>
{/if}

...but it's less scalable, and only applies to the UI (rather than the load functions that apply to different layouts).

Here's how we'd achieve the structure above in our current system:

src/routes/
├ about/[email protected]
├ admin/+page.svelte
├ dashboard/[email protected]
├ item/
│ ├ [id]/+page.svelte
│ │ └ edit/[email protected]
│ └ [email protected]
├ testimonials/[email protected]
├ +layout.svelte
├ [email protected]
├ [email protected]
└ [email protected]

There's a lot going on here: four layouts in src/routes, three of which inherit from the base +layout.svelte (and one of those three, root, is just a <slot /> since it only exists to give a way to reference the root layout from /item/[id]/edit).

The nice thing about this approach is that the directory structure maps perfectly to the routing structure, but everything else is bad: 'app' and 'marketing' are expressed three different ways (once per route that uses them, plus once in the name of the layout); lexical ordering means that app/marketing pages are interleaved, which in all likelihood doesn't correspond to the placement of shared modules, or the human factor of code organisation (i.e. that the 'marketing' pages are likely owned by a separate team to the 'app' pages); the weird @root thing. Making sense of the hierarchy is just really hard.

Job 1: groups

An obvious way to solve the grouping problem is with a directory that doesn't add a route segment:

src/routes/
+ (app)/
│ ├ dashboard/+page.svelte
│ ├ item/
│ │ ├ [id]/+page.svelte
│ │ │ └ edit/[email protected]  # ignore this for now — we'll solve it in a minute
│ │ └ +layout.svelte
│ └ +layout.svelte
+ (marketing)/
│ ├ about/+page.svelte
│ ├ testimonials/+page.svelte
│ └ +layout.svelte
├ admin/+page.svelte
└ +layout.svelte

It's subjective, but I find this much more obvious. All the (app) and (marketing) code is co-located (and that would extend to any shared modules or components, which would currently have to go in src/lib otherwise they'd clutter up the root directory), and it's easier to trace the 'flow' of layouts from tip to root.

Since all this applies to data loading as well as UI, it's also very easy to add an (authenticated) guard or similar — just add an (authenticated)/+layout.server.js file with a load function that throws an error or redirect if the user isn't logged in.

Job 2: breaking out

Technically, it's possible to achieve everything with just groups, by having sibling hierarchies:

src/routes/
├ (app)/
│ ├ dashboard/+page.svelte
│ ├ item/
│ │ ├ [id]/+page.svelte
│ │ └ +layout.svelte
│ └ +layout.svelte
├ (marketing)/
│ ├ about/+page.svelte
│ ├ testimonials/+page.svelte
│ └ +layout.svelte
+ item/
+ ├ [id]/
+ │ └ edit/+page.svelte
├ admin/+page.svelte
└ +layout.svelte

...but this is monstrous. Given how often this is necessary, it's worth having a more idiomatic solution. As long as we're using the filesystem to define custom layout hierarchies (on which, see the 'what about' section below), then this necessarily involves adding some syntax to filenames, but it doesn't need to be as much syntax as we currently have.

Currently, you have to declare a layout in some parent directory to act as an 'anchor', which means we need the -foo construct. But this is unnecessary, because we already have a perfectly good way of identifying the parent level to which we want to 'ascend' — the segment names themselves.

For example if we wanted to use the c layout in /a/b/c/d/[e]/+page.svelte, we don't need to declare a +layout-c inside the c directory — we can just... use c:

src/routes/a/b/c/d/[e]/[email protected]

To ascend straight to the root layout, we can just omit the name altogether — [email protected]. So our more realistic example becomes this:

src/routes/
├ (app)/
│ ├ dashboard/+page.svelte
│ ├ item/
│ │ ├ [id]/+page.svelte
+ │ │ └ edit/[email protected]
│ │ └ +layout.svelte
│ └ +layout.svelte
├ (marketing)/
│ ├ about/+page.svelte
│ ├ testimonials/+page.svelte
│ └ +layout.svelte
├ admin/+page.svelte
└ +layout.svelte

[email protected] would reset to the whatever layout for everything in its subtree.

Downsides

The main drawback of this proposal is the way the directory tree no longer maps 1:1 with the routing tree. Finding the code for a specific route becomes very slightly harder. Reasonable people can disagree about how major that is.

A corollary is that it becomes more possible to introduce conflicts (between (foo)/whatever and (bar)/whatever), though the framework can easily throw a helpful error in that case.

What about export const layout = ...?

A common question: why does it need to be expressed in directory and filenames? why can't we having something like this?

export const layout = 'foo';

One answer is that SvelteKit really needs to be able to resolve the layout hierarchy statically, and with layouts expressed in JavaScript it's impossible to guarantee that. If it can't be determined statically, then SvelteKit needs to load the leaf node (+page), then find out which layout it references and load that, and repeat, all the way back to the root one at a time.

By constrast, when we know the layout hierarchy statically we can load all the pieces concurrently, resulting in faster apps.

There are other options — we could add a +config.json or something. But it's honestly hard to see how that's an improvement.

What about existing named layouts?

+layout-name.svelte etc would no longer exist under this proposal, so it's not additional API, rather it replaces the existing API.

---

Thanks for reading this far! Feedback welcome 🙏

[dummdidumm]

I like the grouping mechanism because loading and or layout ui often go hand in hand with feature areas. I don't like that it potentially creates more folder depth, but I can live with that - but curious to hear other people's opinions. An alternative would be to keep the current system but without the possibility to inherit from siblings - you would always go up the tree, and all named layouts inherit from the default layout automatically. This should achieve the same without the grouping mechanism.

One question about segments: if I want to rewind to the layout within [...rest], do I reference that by doing +layout@[...rest]?

One edge case I'm not sure how it's handled: what if there are multiple segments in the tree with the same name. What to do if you want to jump past the first one?

One note about +config.json: it could be valuable if we place the other things like ssr, prerender etc in there. It's theoretically possible right now to have these be dynamic values, but I have yet to see a case where that's actually needed, and we could meet the "is dev mode" cases through string enums.

[Rich-Harris]

Does this mean referencing a (group) layout (non-root) looks something like +page@(app).svelte or +page@(marketing).svelte, etc.?

Correct

@CaptainCodeman What does 'references across groups' mean?

[CaptainCodeman]

Exactly that example - it wasn't clear if the groups were independent or not.

Once you are referencing groups though you're kind of back to just using named layouts (I guess apart from within the group?)

[Rich-Harris]

Yes, and?

[CaptainCodeman]

I don't think you get much in return for splitting up your route hierarchy into these group folders, not just into different folders but potentially also to multiple inconsistent depths.

Not enough to make it a worthwhile tradeoff.

Now to locate a route, you have to know & remember which layout(s) it uses, to know which folder(s) to look in.

[Rich-Harris]

Or type Cmd-P followed by /thing-im-looking-for/. Realistically all but the most complex apps will have a couple of root-level (group) directories at most.

[lukaszpolowczyk]

This is slightly off topic (slightly sorry), but slightly related:
Modal navigation - #4560
In one video Rich himself said that this needs to be done before SvelteKit 1.0

This proposal creates a solution that uses slots to put a modal page in a simple page.
This is quite universal.
You may want to take this into consideration, when thinking broadly about layout, etc.
Because then the normal page is sort of one of a pyramid of layouts.

[TheHadiAhmadi]

Also it would be great if sveltekit team consider #627 now

[CaptainCodeman]

Since all this applies to data loading as well as UI, it's also very easy to add an (authenticated) guard or similar — just add an (authenticated)/+layout.server.js file with a load function that throws an error or redirect if the user isn't logged in.

I can't picture how this would be usable, wouldn't pages only belong to one "group" or another? What if they need to take part in two groups at the same time? i.e. one for auth, one for some other context

I'm picturing a site like firebase console, where you have auth and you might have a selected project. Currently, I'd use a layout for loading the selected project data that becomes the context, and that layout uses another that ensures auth ... but other things also need to use the auth layout as well (e.g. user preferences, billing, profile) without any project context. I don't see how I could have an (auth) group and a (project) group and pages use both.

[Rich-Harris]

Like this?

src/routes/
├ (authed)
│ ├ (project)
│ │ └ project-that-is-also-authed
│ └ thing-that-is-authed-but-not-a-project

Obviously you couldn't have an unauthed project under this design, but at that point layouts are the wrong tool for the job.

[CaptainCodeman]

So groups can also be nested ... at any level? (i.e. any point in the route tree can introduce a new group?)

[Rich-Harris]

Yes

[dummdidumm]

It sounds like you want to mix and match load functions, which I believe is easier if you create reusable load functions which you call from your respective layouts. It's possible you would even not need the advanced layout mechanisms at all then

[CaptainCodeman]

No, each load would be doing its own thing, although they depend on the higher levels they don't repeat what they do.

There's actually a (console) layout, which would load the list of accessible projects based on the users auth, and the selected (project) level would be the context to show all pages related to that project, also checking for access permissions to it.

[coryvirok]

I understand the rationale for this proposal but I think the solution is digging the hole even deeper. The problem stated was that named layouts were confusing. The solution proposes a new abstraction that adds more "api" to file and directory names, which IMO will increase the confusion and learning curve.

Using a hierarchy to determine routing is reasonable because it maps 1:1 with a URL structure, which is indeed a hierarchical tree structure with no loops - read: "not a graph". But as soon as we want to break out of the layout determined by the hierarchy that determines routes, we are attempting to create a graph. (Please let me know if that's not clear and I'll provide more details.)

I liked how RH (or someone... can't remember) described the render tree as different than the data tree. In reality, we have at least 2 trees and 1 undirected graph. Trees: route, data. Graph: render, (where layout is part of render.) I recommend only using directories and filenames for the "api" of the route concern. Which means URLs are determined by directories and filenames. Ideally rendering is determined by code in the templates, (which would mean we have to solve the static determinism problem RH mentioned in the discussion HEAD.) And data... well, that's more difficult but using +X.server.js seems ... fine ... for now?

Tl;DR - I'd suggest moving away from treating the file and directory names as an API and move toward separating routing vs render "APIs".

p.s. One of the great things (and strongly intended design decisions) of SvelteKit is the drive toward type safety. IDE + types = happy_devs. But the more we encode into file and directory names, the less benefit we get from IDEs.

Thanks as always for reading

[arxpoetica]

This proposal absolutely does not increase the API for named layouts from how it currently works. It just reworks the API into something more elegant and intuitive. I would argue that it's even less surface API area, though that's up for debate.

Rich said,

The main drawback of this proposal is the way the directory tree no longer maps 1:1 with the routing tree. Finding the code for a specific route becomes very slightly harder. Reasonable people can disagree about how major that is.

I contrived some outlandish examples (for the sake of argument) elsewhere with Rich, and came away thinking of this proposal as bullet proof. I would also argue the grouping explicitly makes it easier to find and make sense of routes and associated layouts.

[coryvirok]

Maybe I'm missing something. But doesn't this proposal include adding 2 new file/directory naming conventions? (dir) and [email protected] (<~ note the missing layout name?)

If so, then that's 2 new concepts that are being added the the "API" we have for filesystem names.

[iceghost]

Maybe I'm missing something. But doesn't this proposal include adding 2 new file/directory naming conventions? (dir) and [email protected] (<~ note the missing layout name?)

If so, then that's 2 new concepts that are being added the the "API" we have for filesystem names.

@coryvirok Things got replaced, not added.

• The @ replaces @default
• The (group) replaces multiple layouts in a single directory.

If you ask me, the API doesn't change much, but the directory tree gets simplified a lot. Named layouts become less powerful and focus more on the jobs they're supposed to do.

[Rich-Harris]

Strictly speaking, the @ doesn't replace @default — that's just a deeply confusing mechanism to enable a layout to inherit from a default sibling layout instead of the default parent layout. To achieve the equivalent of @, you need to create an empty (i.e. <slot />) layout in src/routes that uses @default to reference the actual root layout, and give it an arbitrary name like root, give you this:

src/routes/
├ foo/
│ ├ bar/
│ │ └ [email protected]
├ +layout.svelte
└ [email protected]

You have to have these superfluous 'anchor' layouts everywhere you want to reset to a parent layout that's also the default layout for its subtree. It's very unwieldy.

In addition to getting rid of that, this proposal removes +layout-foo.

Sure, if you count the additions and removals, it comes out more or less as a wash, depending how you slice and dice it (I'd argue this breakdown is generous to the status quo)...

➖ +layout-foo
➖ @default
➕ (group)
➕ @

...but an accurate appraisal requires us to compare how intuitive those various aspects are. +layout-foo@bar isn't intuitive, because you have to remember which punctuation is for declaring a named layout and which is for using a named layout, and @default definitely isn't.

By contrast, in this proposal we have an unambiguous hierarchy with a single piece of layout-related syntax in component filenames. I think it's pretty hard to argue that this increases confusion.

[stausmar]

I also think the existing design could be easier because it really complicates the file naming. Especially if you are just starting out it could be quite difficult to understand how layouts work.

What I don't like about this approach

• What I don't like about this approach is that we add "another" thing to the folder structure. Currently, the folder structure has one responsibility which is defining the routes. From my point of view, this is very simple and logical. But due to that, you already have a lot of folders and depending on the application, the folder structure could be even more complex. Navigating through the different folder layers can be time consuming already. Finding your files quickly should be a no-brainer. So adding another folder layer (or even multiple layers for nested layouts) will further increase the complexity and depth of the folder structure.

• In addition, you will bloat your root directory with all the layout files. I know, this is the same already today, but I never really liked that.

Here's my suggestion:

Why not having a separate folder src/layouts where you can find all your layouts? That would definitely keep the root directory clean.

src/layouts/default.svelte
src/layouts/admin.svelte
src/layouts/login.svelte
src/layouts/product.svelte

The layouts could be applied by this:

+page.svelte

<Layout name="admin">
    <h1>Admin Dashboard</h1>
    <div>....</div>
</Layout>

Nested layouts could be done by this:

+page.svelte

<Layout name="admin">
    <h1>Admin Dashboard</h1>
    <Layout name="product">
        <div>...</div>
    </Layout>
</Layout>

Advantages of this approach

• The root directory is kept clean
• Folder structure is still responsible for routing only
• Folder structure depth won't increase
• Opening layouts in your editor is fast because they have a separate directory
• Looking at a page easily indicates what layouts are used

I'm still a beginner, so I can't really tell if that would be a good approach or not. But from the perspective of a beginner, this looks very easy and logical.

[dummdidumm]

I wouldn't want to repeat the wrapped layout in every of my page components. The common case is that you don't need many different layouts, if at all, so for the common case it's more boilerplate.
From an Implantation perspective I also fail to imagine how to make this work. The reference would need to be trough the page filename or export const layout = .. in the .js file .

[Rich-Harris]

In addition, you will bloat your root directory with all the layout files. I know, this is the same already today, but I never really liked that.

I'm having a hard time understanding this response. Currently, if you need to break out of a layout hierarchy to the root then at minimum you need +layout.svelte and [email protected]. If you have any custom layouts that apply to top-level subroutes, then you need an additional +layout-whatever.svelte for them. In the original example, there are four layouts in the root directory!

Under this proposal, your root directory will have at most a single layout.

Why not having a separate folder src/layouts where you can find all your layouts? That would definitely keep the root directory clean.

Keeping the directory clean is not the goal. The goal is to make things understandable. That's where the current system falls down, and where this new proposal has significant advantages.

Putting layouts (which are inherently hierarchical) in a separate (flat) directory would make it much harder to understand the relationships between different parts of the app.

[CaptainCodeman]

They may be loosely hierarchical but don't always have a 1:1 match to the route hierarchy which gives rise to the named reference complexities.

I think it comes down to whether there are ever that many layouts that having them in the route hierarchy, esp. given that you then often want to undo that hierarchy by skipping inheritance etc..., is really that clear or valuable.

[weepy]

I'm sure you'll all hate this, but expressed in a special comment block at the top would solve everything ...

<!-- use-layout=whatever -->
<script>
... 
</script>

[dummdidumm]

This sounds like a different version of export const layout = .. in +page.js

[weepy]

yeah but it's guaranteed to be easy to statically analyse

[jthegedus]

One answer is that SvelteKit really needs to be able to resolve the layout hierarchy statically, and with layouts expressed in JavaScript it's impossible to guarantee that.

I believe the package resolution of Golang uses this proposed comment-style type of optimisation. First line of each file is required to be a package definition, package <package_name>, the package resolution algorithm doesn't parse all files as Go and read the AST, but rather knows about the rule package definition rule so it only needs to read in and parse the first line of each file to assign files into packages. This is my naïve understanding.

I certainly don't understand this problem nearly as much as anyone else here, but I doesn't seem there's a specific requirement to parse the code through JS first to determine the layout or any other Kit config value per route.

If the first 15 chars aren't <!-- use-layout the use the default layout, else read the rest of the comment and bail. Alternately, export const layout = can be checked by the same mechanism, though at a perf cost since you would need to check the entire <script> tag before knowing it didn't exist to revert to default. While not a pretty solution to implement, the internals of a compiler aren't always pretty.

Again, I am not clear on the inner working of Kit and when this part is evaluated and if it indeed does need to be done after parsing files into JS. Just wanted to share that I believe other tools use mechanisms/optimisations like this.

[weepy]

The problem with export const layout = is that it would need to somehow guarantee not to be dynamic.
The problem with magic comments is that some consider them to be hacky.
The problem with the other solutions is that they add noise to the filesystem.
Can't have it all.....

[jthegedus]

somehow guarantee not to be dynamic

The framework can define the rules for this. Assume it's static, don't allow dynamic. Grep the file for Single or Double quote strings after the layout = . If people make it dynamic, then it will likely fail. Tell them not to do it, the rules of the feature say "don't do that". Dev tooling can still lint this value to warn not to make it dynamic, but the compiler consume it as I suggested. The filename solution cannot be dynamic, so it's not restricting the solution space for layout names.

Inelegant or hacky, sure. Simple to use and explain, I think so.

[kevmodrome]

Another option might be something like this:

src/
├ routes/
│ ├ dashboard@user/+page.svelte
│ │ ├ billing/+page.svelte
│ ├ about@marketing/+page.svelte
│ ├ testimonials@marketing/+page.svelte
├ layouts/
│ ├ user.svelte
│ ├ marketing.svelte

Specify all the layouts in a layouts folder. Each file is one layout. To specify a layout on a route add a @layoutName at the end. Add multiple like so: routeName@authed-user/ (would use the authed layout and then the user layout in that order) or if on multiple levels you would do dashboard@user/billing@something.

Not sure how you would go about adding a layout to the absolute top-level though. Maybe a default layout would apply to the top? Or maybe routes@default/? 🤔

Unsure how you would "eject" from layouts. Maybe something like @-layout?

[n-pn]

this will be annoying pretty fast if you have a dozen of pages.
also sometime you also need to rename your layouts, then it will be super annoying.

[kevmodrome]

I suppose - but that doesn't seem like something you'd do that often. This is way clearer to the consumer than the other proposals in here IMO.

[Rich-Harris]

It's way clearer in the simplest cases, but putting layouts in a separate src/layouts directory simply doesn't scale. There are fundamentally two options:

1. a flat directory, where every layout has a unique name, and if one layout inherits from another it's expressed in the filename
2. somehow recreate the route hierarchy in the layouts directory

The first option forces you to come up with a bunch of unique names, for basically no reason. (Even in the current system, where you're also forced to come up with names, at least they only need to be unique within a subtree.) Understanding the layout hierarchy is very confusing, because you have to mentally convert an unordered subset of the list of names into a linked list that applies to a given page.

The second is a maintenance nightmare, especially for larger apps.

Even if that weren't the case, you'd still be forced to add @marketing etc to every route that used it, as you are today. (Also, it needs to apply to the filename, not the directory name, otherwise you can't have a page opt out of the layout hierarchy while its children stay within it.)

[CaptainCodeman]

you'd still be forced to add @marketing etc to every route that used it, as you are today

If I find myself doing that it usually means I need to flip the default and named layouts round, so only the odd exception needs to be given a name.

[j4w8n]

My hesitation with the groups is that it really messes with my head on the routing. Especially if those (directories) are collapsed.

Quick side note: how in the world do y'all create those fancy-looking folder/file structures??

We've already gone to a directory centric approach to defining routes. What if we did the same for layouts?

• All layouts would go in src/layouts.
• If you want an app layout, create a directory for it.
• In each directory, the layout file is simply +layout.svelte.
• In src/routes, reference the layout with [email protected].
• Layouts inherit from the layouts above. So in the case of authed/project/+layout.svelte, it inherits from authed/+layout.svelte. And this is automatic when referencing it with [email protected].
• If a +page.svelte file doesn't reference a named layout, it would automagically inherit from the root layout - no matter where it is in your routes structure.

This keeps the layout structure separated from the route structure, while (I think?) simplifying things.

What I don't like about my idea:

• it pulls +layout.svelte away from the other layout files. I suppose you could place all layout files in their respective src/layouts folder, but would it make the framework's router job more difficult??

• It de-colocates files. In these various proposals, I've seen the desire to co-locate files as much as possible.

src/
|- layouts/
|  |- app/
|  |  +layout.svelte
|  |- authed/
|  |  |- project/
|  |  |  +layout.svelte
|  |  +layout.svelte
|  |- item/
|  |  +layout.svelte
|  |- marketing
|  |  +layout.svelte
|  +layout.svelte

src/
|- routes/
|  |- about/
|  |  [email protected]
|  |- admin/
|  |  |- project/
|  |  |  [email protected]
|  |  [email protected]
|  |- dashboard/
|  | [email protected]
|  |- item/
|  | [email protected]
|  |  |- [id]/
|  |  | +page.svelte
|  |- pricing
|  |  +page.svelte
|  |- testimonials/
|  |  [email protected]
|  +page.svelte

[CaptainCodeman]

I'm trying to glean what the exact rules are based on the descriptions given and and previous comments

Sorry, I thought "references across groups" was clear. Across as in, referencing other folders than the group the route is in. Otherwise I would describe that as references within groups.

So it sounds like references across groups (from one tree to another) is not allowed, all you can do is reference the current or parent group (?) you are in?

[Rich-Harris]

The proposal explicitly says 'identifying the parent level' — parents, not cousins or nieces or nephews. It would be absurd if it worked any other way!

[CaptainCodeman]

That was in the context of referring to route segments. The other comments were talking about references to (group) names which appeared to be something different. I was seeking clarification as to what the proposal was.

I've stopped trying to decide if something is absurd or not.

[Rich-Harris]

I really wish you'd take this reflexive snark somewhere else.

[CaptainCodeman]

I feels like you're determined to imply every question is stupid or the answer already obvious.

I'm asking them because to me they weren't, and I've explained the reasons for my confusion.

[harrylaulau]

I don't think grouping is a good idea as it would as well make perfect sense to just split the two groups into 2 parent routes given how different they are (and redirect if they accessing the parent route)
e.g. using the example above, we could just write the following with throw redirect in app/+layout.svelte and marketing/+layout.svelte:

src/routes/
+ ├ app/
│ ├ dashboard/+page.svelte
│ ├ item/
│ │ ├ [id]/+page.svelte
| │ │ └ edit/+page.svelte
│ │ └ +layout.svelte
│ └ +layout.svelte
+ ├ marketing/
│ ├ about/+page.svelte
│ ├ testimonials/+page.svelte
│ └ +layout.svelte
├ admin/+page.svelte
└ +layout.svelte

still there would be a problem where app and marketing pages would use the root layout. For this I suggest we can write a single @ which indicates it does not inherit any layout, such that the child pages of that route would also do the same:

src/routes/
+ ├ app@/
│ ├ dashboard/+page.svelte
│ ├ item/
│ │ ├ [id]/+page.svelte
| │ │ └ edit/+page.svelte
│ │ └ +layout.svelte
│ └ +layout.svelte
+ ├ marketing@/
│ ├ about/+page.svelte
│ ├ testimonials/+page.svelte
│ └ +layout.svelte
├ admin/+page.svelte
└ +layout.svelte

Then for child pages that would like to escape we can write like, which fall backs to /app/+layout.svelte:

src/routes/
├ app@/
│ ├ dashboard/+page.svelte
│ ├ item/
│ │ ├ [id]/+page.svelte
+ │ │ └ edit/[email protected]
│ │ └ +layout.svelte
│ └ +layout.svelte
├ marketing@/
│ ├ about/+page.svelte
│ ├ testimonials/+page.svelte
│ └ +layout.svelte
├ admin/+page.svelte
└ +layout.svelte

such that if we want to fallback to routes/+layout.svelte

src/routes/
├ app@/
│ ├ dashboard/+page.svelte
│ ├ item/
│ │ ├ [id]/+page.svelte
+ | │ │ └ edit/[email protected]
│ │ └ +layout.svelte
│ └ +layout.svelte
├ marketing@/
│ ├ about/+page.svelte
│ ├ testimonials/+page.svelte
│ └ +layout.svelte
├ admin/+page.svelte
└ +layout.svelte

for me this way seems to be more straight-forward and still maintain the route hierarchy.

[Rich-Harris]

So you're saying that the routes should just be /app/dashboard instead of /dashboard, and /marketing/about instead of /about?

[harrylaulau]

Yes! Since they don’t share any layout then maybe it’s more reasonable to split in two completely different route trees and get rid of the layout with single @.

[Rich-Harris]

I mean that's fine, if it's in your power to do that, in which case you don't need to bother with any of this stuff.

But when your boss/client/whatever comes along and says /dashboard and /item need to share a different layout to /about and /testimonials, 'just change them to /app/dashboard etc' is not an answer that will get you promoted.

[harrylaulau]

thats true though XD

[theetrain]

TL;DR

• Defining layouts as a declarative file tree is certainly challenging under the constraint of static resolution, and to unlock the functionality of the parent() function. We require several pieces of functionality from layouts, and having that all be accessible exclusively from file names is an interesting problem. (see bottom)
• "groups" are not rendered as routes, which is not confusing but is mentally toiling when deciphering files as routes and having to mentally ignore groups as becoming rendered routes
• I propose keeping named layouts and introducing a "root layout" defined as [email protected] so that child pages can slot into layouts and stop at either defined root layouts ([email protected]) or at the absolute root layout (/src/routes/+layout.svelte)

I like the part of the proposal where a page can reference the root layout using [email protected], but I'm not a fan of the "groups" idea for these reasons:

Group problem 1. It could potentially make some refactors difficult

If a team decides to change a group name then that could block some other teammates' changes upstream and would require careful planning. Bigger teams may have potentially bigger conflicts.

Group problem 2. What if we need more groups?

Original example for reference

src/routes/
├ (app)/
│ ├ dashboard/+page.svelte
│ ├ item/
│ │ ├ [id]/+page.svelte
│ │ │ └ edit/[email protected]
│ │ └ +layout.svelte
│ └ +layout.svelte
├ (marketing)/
│ ├ about/+page.svelte
│ ├ testimonials/+page.svelte
│ └ +layout.svelte
├ admin/+page.svelte
└ +layout.svelte

An app may require more groups in order to have new "root layouts"; such as item reviews, store locator, user profiles, or (marketing) sponsorships; and the new app routes require a different root layout because they don't utilize a common navigator or footer because they're meant to be embeddable (iframe) app pages. Altogether, that would look something like this:

src/routes/
├── (app)/
│   ├── dashboard/+page.svelte
│   ├── item/
│   │   ├── [id]/
│   │   │   ├── edit/[email protected]
│   │   │   └── +page.svelte
│   │   └── +layout.svelte
│   └── +layout.svelte
+── (app-embeddable)/
+   ├── item/[id]/reviews/+page.svelte
+   ├── stores/
+   │   ├── [id]/+page.svelte
+   │   ├── +page.svelte
+   │   └── +layout.svelte
+   ├── users/
+   │   ├── [id]/+page.svelte
+   │   └── +page.svelte
+   └── +layout.svelte
├── (marketing)/
│   ├── about/+page.svelte
│   ├── testimonials/+page.svelte
│   └── +layout.svelte
+── (marketing-sponsors)/
+   └── sponsors/
+       ├── +page.svelte
+       └── +layout.svelte
├── admin/+page.svelte
└── +layout.svelte

And what if a page needs to render both as an app and as an embeddable page? We could add a src/routes/embed/ directory, but its +layout.svelte would have to break out from the root layout as well.

I hope this example doesn't come across as contrived since I had worked on such an app with embeddable requirements. A fair argument would be having the (app)/+layout.svelte change when it's wrapped in an iframe (which is detected as window.self === window.top), but it's unknown how much of the layout's design and back-end needs would change under this scenario, which could bloat the layout.

Potential solution: root layouts

I propose keeping named layouts and introducing a "layout root assignment" by appending @ to a layout, which would be [email protected]. That way any page written as [email protected] will utilize the nearest root layout.

Given the following:

src/routes/
-── (app)/
├── admin/+page.svelte
│── dashboard/+page.svelte
+── embed/
+   ├── item/[id]/reviews/+page.svelte
+   ├── stores/
+   │   ├── [id]/[email protected]
+   │   ├── +page.svelte
+   │   └── +layout.svelte
+   ├── users/
+   │   ├── [id]/+page.svelte
+   │   └── +page.svelte
+   └── [email protected]
│── item/
│   ├── [id]/
│   │   ├── reviews/
│   │   │   ├── +page.svelte
│   │   │   └── [email protected]
│   │   ├── edit/[email protected]
│   │   └── +page.svelte
│   └── +layout.svelte
│   └── +layout.svelte
-── (marketing)/
+── about/+page+marketing.svelte
+── sponsors/
+   ├── +page.svelte
+   └── [email protected]
+── testimonials/[email protected]
├── +layout.svelte
+── +layout-marketing.svelte

The behaviour would be:

• Pages inherit layouts from the current directory and up the file tree, slotting into each other until a root layout is found.
  Example: routes/embed/stores/+page.svelte
  slots into routes/embed/stores/+layout.svelte
  slots into routes/embed/[email protected] and stops there since the page found a "root layout".
• Pages declared as [email protected] will only slot into the nearest root layout without any slot cascade, which is the expected behaviour of calling a named layout.
  Example: routes/embed/stores/[id]/[email protected]
  slots into: routes/embed/[email protected] and stops there since the page found its "nearest root layout"

I understand the big question is "is this intuitive?" and not "is this clean?". At a glance, it's not intuitive how @ behaves unless we explicitly add a name like +layout-root.svelte, which leans even more towards named layouts.

Revisiting layout functionality

Compared to the imperative approach in Astro, Nuxt, and Jekyll, I think we would lose functionality if we don't have the flexibility of named layouts. With the groups proposal, we wouldn't have selective layout inheritance (i.e. [email protected]) unless we duplicate some layouts and add more groups in order to consume those special permutations.

From my understanding, layouts require the following functionality:

1. layouts can have optional loaders and server functions
2. a page can consume a layout

Static site generators like Jekyll require every page to explicitly define their layout in the page's code. A layout can also slot into other layouts, but it's inflexible: once a layout consumes another layout, that's defined permanently. Breaking out of that requires duplicate layouts.

SvelteKit today solves problems 1 and 2 and adds bonus functionality thanks to the file-based router:

• pages slot into sibling and parent layouts as defined in the file-based router
• layouts can have back-end logic defined in files like +layout.server.js and slotted-in pages can consume that data via the parent() function

That's great, athough some applications may run into inflexibility concerns when a page should not consume a certain sibling or parent layout, and for that I can see how this discussion can yield several potential solutions. I hope my proposal introduces enough flexibility without introducing too much new complexity, compared with groups.

Thanks for your effort.

[danawoodman]

@theetrain how does colocating make it easier to loop in an each block?

[CaptainCodeman]

I think he means splitting out the inner content into a separate component. Just to avoid having too much in the page view component.

One thing often forgotten in all this is unit tests - if you have a test file that also references a component, as well as the view, is it then "shared"?

[n-pn]

@theetrain sorry for the late response, what I meant by "reusable components" were components that can be imported by multi pages in different places. Like the one that needs ../../../.. in your example.

[danawoodman]

@np-nam just put it in $lib/components if you want to share it

[theetrain]

Thanks everyone for the lively discussion. I see the new changes have been implemented, so let's try it.

@np-nam I see your point about making reusable components (needed by multiple pages) be shared in $lib or similar. I must have been distracted and forgotten this basic technique in the moment!

Also, it looks like [email protected] made it into the new "Advanced Routing" set of documented features. It would be cool if I helped in some way.

[bhvngt]

What I like about this proposal is that it keeps layouts under structural context.

In the current structure, layout gets referenced through names which always takes a minute to wrap your head around as it leads to finding that name in the structure before being able to relate it to its parent. This one step can make things less understandable.

In the proposed structure, the fact that I can scan my directory structure and make sense of parent-child relationships for layouts just like I do for normal routing relationships helps a lot.

These is more like a trade-off between tags and groups. While the former appear to give more flexibility (for example referring same name at different depth) at the cost of additional complexity, I believe for the context of routing such flexibility is better achieved through shared libraries instead of embedding it inside a filename.

[guifesquet]

Even if +page* and +layout* have the same design (routes/**/*, *.svelte, *.js); they have different purpose (routing/content vs routing/structure), but they are also highly correlated (data inheritance, page rendering).

Introducing (group) job might become a nightmare in understanding routes.

The proposal to create an src/layouts/layout-name/+layout* structure and using it with src/routes/**/layout-name@*, address the group and the break out jobs. We still need to add +layout* at the root, branch and leaf levels.
This way the implementation may become a nightmare…

[Rich-Harris]

I've commented elsewhere about why src/layouts is a non-starter:

• Simpler custom layouts #6124 (reply in thread)
• Simpler custom layouts #6124 (reply in thread)

[iceghost]

I'm not against the proposal. But here goes another idea... Instead of letting layout inherits layout, can we switch to something like directory uses layout or segment uses layout?

The default example becomes:

src/routes/
├── dashboard@app/+page.svelte
├── item@/[id]@/edit/+page.svelte
├── item@app/
│   ├── [id]/+page.svelte
│   └── +layout.svelte
├── about@marketing/+page.svelte
├── testimonials@marketing/+page.svelte
├── admin/+page.svelte
├── +layout.svelte
├── +layout-app.svelte
└── +layout-marketing.svelte

• dashboard@app/ will use the +layout-app.svelte layout
• about@marketing/ will use the +layout-marketing.svelte layout
• item@/ will skip current segment layout
• item@app/ will use the +layout-app.svelte layout
• admin/ will use the +layout.svelte layout

So there are three choices:

• directory/ uses the default layout
• directory@name/ uses the named layout
• directory@/ skips or opts out of using layouts

and you can use multiple of them (items@/ and items@app in the example). Those three all map to /directory/ segment.

The layout is scoped within a segment. This means two things:

1. Directories can only skip using layouts on that segment. The ancestor or other segments won't be affected.

2. You can only use the layouts inside the same directory, not on the ancestor directories like how the current named layout works. For example, you can't use @app anywhere else, only inside /.

src/routes/
└── a/
    ├── b/
    │   └── c@foo/+page.svelte // ❌ nope
    └── +layout-foo.svelte

3. Multiple layouts inside multiple directories apply to the same segment. For example, take a look at item@/[id]@/edit/+page.svelte. You may think that [id]@ is unnecessary, but on the other item* directories, there is a default +layout.svelte that will apply to that, which is unwanted so you'll need @. This may trip people up, unfortunately, when the layout lies in a different directory. This is the best I can do to simulate a DAG with a directory tree.

src/routes/
├── item@/[id]/edit/+page.svelte // remove the @ on [id]
└── item@app/
    ├── [id]/+page.svelte
    └── +layout.svelte           // this will apply to above [id] 👆

Compared to the default proposal:

• Less nested, but had to splatter @marketing on directories.
• This only provides a way to break out of a single layout, not all the way to the top like the original proposal. I don't know which is more preferable, but I would like some flexibility.

One more thing I forgot to mention is where do you put the layout files if there are multiple directories for the segment?

For example, what happens if I put the +layout.svelte inside item@/ instead of inside item@app/? The answer is nothing happens, so one will have to choose between the two. We may invent a convention to help with that though:

Prioritize putting the layout on the first folder, sorted alphabetically

For the original example, I should've put the +layout.svelte inside item@/ according to this convention:

src/routes/
├── dashboard@app/+page.svelte
├── item@/
│   ├── [id]@/edit/+page.svelte
│   └── +layout.svelte
├── item@app/[id]/+page.svelte
├── about@marketing/+page.svelte
├── testimonials@marketing/+page.svelte
├── admin/+page.svelte
├── +layout.svelte
├── +layout-app.svelte
└── +layout-marketing.svelte

But yes, the tree grows and you can't decide this ahead of time. Use whatever directory you deem appropriate.

EDIT: well, what about +layout.svelte and +page.svelte in the same directory? I think it should follow the same semantic:

• +page.svelte use the default layout
• [email protected] skip the layout
• [email protected] use the named layout

[iceghost]

Now, you can work out the layout stack without following the inheritance chain:

item@/[id]@/edit/+page.svelte will only use the +layout.svelte of /edit/ segment. The stack:

edit/  : +layout.svelte of /edit/
[id]@/ : nope
item@/ : nope

item@app/[id]/+page.svelte will use the +layout-app.svelte of /item/ segment and the +layout.svelte of /[id]/ segment. The stack:

[id]/     : +layout.svelte     of /[id]/
item@app/ : +layout-app.svelte of /item/

[iceghost]

If I need to give this a name, scoped named layout sounds good to me.

[iceghost]

On second thought, maybe we can apply it to layouts, too, so that the canonical root problem in the OP can be solved. So... while with the original named layouts, +layout-app.svelte will not inherit the sibling +layout.svelte. With my proposal applies to layouts:

• +layout-app.svelte will inherit the sibling +layout.svelte
• [email protected] will skip the default sibling
• [email protected] will inherit the sibling +layout-name.svelte

So... to sum up, my proposal is to limit the scope of named layouts to only inside a directory and between siblings. I think that's all?

[stalkerg]

Because we currently have a specific role for each file in the folder, I don't see any sense apply extra syntax to the file instead of the folder.
The folder now is a route endpoint - not a file anymore.

[iceghost]

Because we currently have a specific role for each file in the folder, I don't see any sense apply extra syntax to the file instead of the folder. The folder now is a route endpoint - not a file anymore.

Umm... you're talking about my proposal, right?

If we only had @ syntax on folders, not the files, how would you apply layouts to the root route (/)?

src/routes/
├── +layout-a.svelte
├── +layout-b.svelte
└── +page.svelte

So we still need @ on the file. Perhaps only on +page.svelte, but might as well on +layout.svelte for composing layouts.

But yeah, the original proposal is already coming to town 😅 I guess discussing this is now futile.

[malgor]

It looks like you are trying to use one concept to solve two separate problems. Let directories specify routes, period. Now find another means of associating layouts.

To my way of thinking the problem is really how to bi-directionally link components and layouts. Layouts already link to components with a slot. So now use a compatible means of linking components to layouts. In these terms, layouts are really just components by another name. The real thing that distinguishes a layout is that it is not a route, it is implicitly used by routes. That suggests layouts don't belong under /routes at all.

You mentioned a possible, but rejected, solution in JavaScript. I'd think about an HTML solution that is the counterpart to <slot />. That is, something like a <svelte:wrapper "my_wrapper" /> tag that means "I belong in the slot of layout "my_wrapper".

[CaptainCodeman]

There are only 3 ways to do it that I can think of:

1. A layout lists all the components it applies to (some component routers effectively do this, it works for small apps but doesn't scale)
2. A view indicates which layout it inherits from (the approach Astro uses, and I think what you're suggesting?)
3. The location in the hierarchy acts as a container for the layout

3 was good for ease-of-use because the association came from the route structure, but it breaks down when you don't actually want the layout containment to match that route structure, which is what the resets and named layouts addressed.

I'd prefer to keep the current system to splitting up the route tree even more, I think it just fragments and obfuscates the structure too much. Next option for me would be 2. It's been dismissed because it "doesn't scale" which I don't understand - exactly how many different layouts do people typically need? And if all those layouts are folders ... that seems like it would also be equally problematic.

[dummdidumm]

It's not about the number of typical layouts, it's that you would have a <MyLayout>page html here</MyLayout/> in every +page.svelte. It's also close to impossible from an implementation perspective to see which of your components in your +page.svelte are layouts and run their load functions prior to displaying the page.
If you want to use this approach, you can do this today btw:

1. Create your reusable layout component within $lib: MyLayout.svelte
2. Create your reusable layout load function within $lib: my-layout-load.js
3. Use load in your +page.js: export function load(params) = { await myLayoutLoad(params); ... return .. }
4. Use the component in your +page.svelte: <MyLayout>...</MyLayout>

[bdougherty]

Can anyone explain in more detail why export const layout = 'foo'; isn't an option? Couldn't the compiler throw an error if it is set to anything but a string literal? Wouldn't that make it so it can be determined statically?

[Rich-Harris]

As long as you require that everything is vanilla JS/TS — no using other compile-to-JS languages, or using Vite's define etc — then sure, you could use TypeScript to generate an AST for every route file and determine the layout statically. It would slow down your builds, but it would be possible.

But then it's not JavaScript — it's a subset of JavaScript, or rather a confusing mixture of JavaScript and not-quite-JavaScript in the same file. People would try to do things like export const layout = EMBEDDED ? 'embed' : 'normal', and we'd have to add documentation explaining why that's not possible. Then we'd get feature requests from people saying 'well what if we made it so that it is possible — determined statically if we can, but otherwise we bail out of the optimisation and figure it out at runtime?' and before you know it the whole thing is a stinking, convoluted mess.

[kdheepak]

With a folder based routing, (imho), having a +layout.svelte for EVERY +page.svelte makes intuitive sense to me. With missing +layout.svelte fallbacks "falling" to the +layout.svelte file one folder up. i.e. Explicit +layout.svelte files override parent layouts.

For example this:

src/routes/
├ about/[email protected]
├ admin/+page.svelte
├ dashboard/[email protected]
├ item/
│ ├ [id]/+page.svelte
│ │ └ edit/[email protected]
│ └ [email protected]
├ testimonials/[email protected]
├ +layout.svelte
├ [email protected]
├ [email protected]
└ [email protected]

would be this:

src/routes/
├ about/
│ ├ +layout.svelte
│ └ +page.svelte
├ about/+page.svelte
├ dashboard/+page.svelte
├ item/
│ └ [id]/+page.svelte
│   └ edit/
│     ├ +layout.svelte
│     └ +page.svelte
├ testimonials/
│ ├ +layout.svelte
│ └ +page.svelte
└ +layout.svelte

If about/+layout.svelte and testimonals/+layout.svelte are similar / idential, I would just implement the common code in a $lib/components/marketing_layout.svelte component and import it from there. Or I would even recommend having a $lib/layouts/marketing.svelte component and import that.

(imho) this is

1. the easiest to understand for a beginner.
2. jives nicely into a mental model of "create a folder for a route and everything that affects that route is in that folder".
3. has all the same advantages as +page.svelte, i.e. easy to fuzzy search for etc.

What do people think about this?

[Rich-Harris]

This would require huge amounts of boilerplate for any non-trivial app. It's not just UI that you'd need to reimplement all over the place...

<!-- src/routes/settings/+layout.svelte -->
<script>
  import RootLayout from '$lib/layouts/root.svelte';
  import AppLayout from '$lib/layouts/root.svelte';

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

<RootLayout {data}>
  <AppLayout {data}>
    <div class="settings">
      <!-- layout markup goes here -->
      <slot />
    </div>
  </AppLayout>
</RootLayout>

...it's all the data loading (and auth guards, etc). And you wouldn't get free type safety inside RootLayout and AppLayout — you'd have to do a bunch more work that the framework currently does for you.

[theetrain]

This is an interesting take. Under the modal you're describing, would pages only slot in once to the nearest layout, and layouts never slot into their nearest parent layout?

If so, that is indeed simple, but we lose out on features such as layout inheritance, and multiple layout loaders via parent(). In my experience, I've often used layouts that cascade from up to 1 parent layout, but never 2 or more. Under this model of only having 1 layout a page can slot into, I wonder if I would run into concerns where I wish I had 2 layouts, but I cannot think of any 🤔

If about/+layout.svelte and testimonals/+layout.svelte are similar / idential, I would just implement the common code in a $lib/components/marketing_layout.svelte component and import it from there.

I agree this is simple, but a bit repetitive since you would need to import marketing_layout.svelte onto every page that needs it, which is similar to other static site generators that declare their layouts in code, and those layouts can declare other layouts.

[kdheepak]

Maybe instead, the layout could inherit the layout from the folder above by default? and maybe there's a filename based way to opt out of that behavior to "break out" (e.g. [email protected])?

Possibly controversial but we could also use the < and > symbols in the filename to define whether it inherits or not. e.g. +layout<parent.svelte is a layout that inherits from /src/routes/parent/+layout.svelte. and +layout>all.svelte would make all subroutes inherit from it.

< and > are reserved characters on Windows apparently. Maybe +layout^.svelte doesn't inherit but +layout.svelte inherits by default.

FWIW I really like using folders for routes and I really like the specific implementation that was landed on (I just upgraded most of my projects to the latest version of sveltekit this weekend and in one of my larger projects everything became a lot simpler to understand. I even caught some bugs that I didn't know I had).

Without any actual data on this, I'm venturing a guess that a large number of projects have a root layout that implements basic structure such has header html / footer html / javascript based analytics / maybe global css etc. I'm also assuming that most projects will probably want a unique layout for a small number of all the routes they have, and they probably the same layout for any sub-routes (i.e. sub folders) for those routes.

For example, if we were implementing github: github.com/sveltejs/kit/discussions, github.com/sveltejs/kit/issues, github.com/sveltejs/kit/pulls etc all probably would use the layout defined in /src/routes/[username]/[repo]/[email protected] but /src/routes/[username]/+layout.svelte would be a completely different layout.

[malgor]

@theetrain makes a good point. Is there really a requirement for inheritance from layout to layout? I know in my app there isn't and I can't think of a use case where there would be. How many people really want multiple nested layouts? If it is for rare esoteric use cases then consider having the simple, easy to understand layout design that @theetrain describes, and make the few people who want more employ the JavaScript imports that @Rich-Harris described.

[CaptainCodeman]

I've definitely used that feature already.

Ironically, I have thought about changing it to use it's own "internal layout" system so it can be packaged up for re-use to make adding to other projects easier.

[stalkerg]

It's pretty common to have up to 3 levels in admin pages.

[danawoodman]

Throwing an idea on the wall that I haven't fully baked, so bare with me.

JSON route configuration file

To address the needs for complex route inheritance, "breaking out" of route inheritance and the fact that export const layout = "foo" isn't statically analyzable, what if instead we create a JSON file for a page?

src/routes/blog/[slug]/+page.json

{
  "layout": "@post",
  "prerender": true
}

Which could map to src/routes/+layout-post.svelte.

Handle any route configuration

Any route specific configuration could live here (layout, prerender, hydrate, router, etc).

{
  "layout": "foo@bar",
  "prerender": true,
  "hydrate": false,
  "router": false
}

Static analysis

Since it's JSON, it's statically analizable. Resolves point 1.

Works for layout inheritance/error pages too

Could be applied to a layout or error via the same mechanism perhaps (+layout.json, +error.json).

This could help allow for "grouped layouts" by allowing you to indicate one layout is nested within another.

For example, in src/routes/admin/+layout.svelte, you could "extend" the src/routes/+layout-admin.svelte layout:

{
  "layout": "@admin"
}

Inherit any layout anywhere

You could reference a layout by path:

{
  "layout": "foo/bar/baz"
}

Would map to src/routes/foo/bar/baz/+layout.svelte.

This means you could map to any arbitrary layout in your app irrespective of its hierarchy and would negate the need for all the fancy file name gymnastics.

Kit could notice if that path was invalid and throw an error.

Partially resolves point 2.

Resetting layout to default

Setting layout to "@" defaults to the root layout (or maybe "" or "@default"?):

{
  "layout": "@"
}

Partially resolves point 2.

Custom named layouts

For custom named layouts (eg "marketing", could do:

{
  "layout": "@marketing"
}

Which could map to src/routes/+layout-marketing.svelte.

{
  "layout": "foo/bar/baz@biz"
}

Would map to src/routes/foo/bar/baz/+layout-biz.svelte.

Simple default case

For the default case of a route just using the default layout, no config option needs to be set, only set it when you want to override the default hierarchical inheritance.

JSON is standard and simple

And finally, we're all used to JSON for configuration, so I don't think it would be too confusing.

FIN

Thanks for coming to my TED talk ✌️

[coryvirok]

Another possibly divisive suggestion:

Can we get rid of layouts? Do we even need them? ... Hear me out...

Why not do what other routing libs do and just allow for a <slot/> element in your page? The page would act as the layout, which would be an even stronger coupling than using a filename like [email protected]. If we need to pass data from the child to the parent page, we could easily do this in a Sveltish way by following my suggestion here.

Now that we have per route "middleware" or whatever we want to call it, we can build the data server-side and push down through data to the browser which will render a simple render tree for https://example.com/foo that starts with src/routes/+page.svelte which has a <slot/> that renders src/routes/foo/+page.svelte, etc...

And if you needed a child URL to break out of the parent component, you would put that logic into the parent component itself while having the data returned from the server stuff something into data to trigger the parent component to handle it in a special way... Everything is a Component. Easy to grok. No need for complicated parallel loading or file naming conventions or anything.

This is how it works with VueRouter and it's pretty nice.

[guifesquet]

*.js | *.ts, *.svelte, or *.json are error prone.
In the case of *.svelte, this means adding data inheritance in Svelte, not a SvelteKit stuff.
Ok, there is the compiler, but why use the old way (see Apache Tiles)

I personally don’t find a better way for the group job.
For the break out one, you spoke about @something to reset/replace the layout, right?

• at the leaf level +page@ and +page@segment,
• at the subtree level +layout@whatever.

Honestly, to introduce this third level of abstraction, we need something to materialize it, I’m fine with you proposal.

I’m curious to see what you’ll imagine for the next one.

[danawoodman]

Why is JSON problematic exactly?

[guifesquet]

You need to open a new file to know something is happening, I don’t speak about hydrate/prerender properties; and unless there is a plugin that analyze and notify (just in case of error), you have to open the file.

I come from the Java world, years ago xml was used to configure, today it’s decorators with annotations through the compiler.

[danawoodman]

I find a JSON config file both very standard and way more intuitive than the current proposal of using folders with parens in them and all the other route gymnastics.

[jchanes04]

While I might be late to the party (hopefully more than 3 days of discussion is being given to important changes like these though), I find that the current system of named layouts is, in a word, gross, and this new proposed system does little to improve. I think this is where the filename magic in kit started to get out of hand, and moving away from using filenames as an API is better for readability, tooling, and offers more flexibility in the future.

Current and older systems

Going back to a time before named layouts, you were restricted to two options:

• Nest all of the layouts going down the filetree
• Use a __layout.reset.svelte to completely ignore all other layouts, then put all of your layout code inside that file

This system was quite simple, and for many apps was perfectly sufficient. The issues came with keeping code DRY, since layout resets required you to put all of your layout code in one file, unable to take advantage of the fact that you've already written that code before. Resets were also an all-or-nothing solution which lacked control and could end up being very clunky with larger, more intricate apps.

With the introduction of named layouts, all of this was flipped on its head, since they offered so much control over how your layouts were inherited. With so much flexibility, however, came a loss of simplicity. Many experienced devs, as well as myself, are left head scratching trying to remember what the rules are for where layouts can inherit from, and "where the heck is this layout defined," and shoving layout inheritance into filenames made it frustratingly opaque to debug. I wouldn't call it a nightmarishly complicated task, but constantly running into issues like that could definitely put a damper on one's workflow.

Design considerations

The fundamental question when designing systems like these is where to place the balance between simplicity, consistency, and flexibility. Layout resets excelled in the first, named layouts excelled in the last, and I think that a new system should strike a balance between these. An important realization is that (applying the classic 80/20 rule) ~80% of your code is going to use only ~20% of the available features. It's going to be much more common in most, if not all apps, that pages will not need to break out of the classic layout nesting system.

Knowing this, a new system should preserve the trait that the majority of cases will be the simplest to deal with. The point in contention is how to handle the abnormal, more complex, and special cases in need of fine control, while also striking that balance between simplicity and flexibility.

I think many people here make a good point by acknowledging that layouts run double-duty in a kit app, being integral to both the render tree and the load tree. These two systems are often, but not always, correlated, so I don't see a need to completely separate them. The current +layout.js/+layout.server.js and +layout.svelte files are sufficient for keeping these concerns linked, but distinct.

My proposal

With a lot of fluff out of the way (mostly to get my own brain warmed up), here's how I think layouts should be designed and used.

For the simple cases where layouts are neatly nested inside one another and load functions are called in nice succession (assuming await parent()), I see no reason to change this. This is how most layouts are used in an app, and they should be as simple as possible. To be perfectly clear on what keeping the current implementation entails:

• +layout.svelte and +layout.js or +layout.server.js files can be placed in any level of the routing file tree
• All routes inside a directory will use that folder's layout as one of their layouts
• In the case where there are multiple layout files in the directory tree of a route, they will be applied top to bottom. For +layout.svelte files, this means that if layout B is in a child directory of layout A's directory, the markup of layout B will be put inside the <slot></slot> of layout A. For +layout.js and +layout.server.js files, this means that if layout B calls await parent(), layout A's load function will execute first, and then layout B's

Now for the real meat of the proposal: how to break this system. If you stop to think about it, layouts are really just components with a slot and some extra magic behind the scenes. Why not take inspiration from the way we use components? This has the advantage of being easy to understand for those who have learned svelte before kit, and provides a consistent syntax.

I propose that in order to break out of the classic layout nesting, one would import a layout just as they would import a regular component, and then use it like they would use a regular component. Since there are already methods available to generate an import tree without actually running the code, this seems like it falls within the constraints of "statically analyzable". Here's an example, where src/routes/blog/posts/featured/+layout.svelte wants to use a special "featured layout" for the list of featured posts, which happens to be used by other routes within blog:

<script>
    import FeaturedLayout from 'src/routes/blog/+layout-featured.svelte'
</script>

<FeaturedLayout>
    <h1>Here is where your specific code for this layout</h1>
    <slot></slot>
</FeaturedLayout>

Note that the named layout syntax is used, but only to disambiguate this from any other layouts you happen to have made. The contents of the layout filename are completely arbitrary and don't affect how it's used, as long as it starts with +layout- so sveltekit knows that it's a layout.

The classic layout nesting could also pick up from wherever the layout is imported from, in this case checking for layouts in src/routes/blog and src/routes. Note that src/routes/blog/posts is skipped. I can see arguments either for or against this feature, so this is still up in the air.

In order to keep the import tree from being a complete free-for-all, there should be restrictions about where layouts can be imported from. One potential idea: layouts can only be imported from directories that are direct parents of the current directory, which includes the src/routes directory. This solves two issues. First, if a layout imports from a layout that is a child of it, and the above paragraph is implemented, it can cause circular dependencies. In general, it just doesn't make sense to ever do something like that, so I think this is a valid restriction. Second, keeping layout imports restricted to direct parent directories makes it less likely that changing a layout in src/routes/blog doesn't accidentally break something in src/routes/projects.

Note that having an actual import statement in the file makes many things much easier. First, it completely removes the ambiguity of "where is this layout coming from". Second, and more importantly, it makes it much easier to use existing tooling to its full extent. While I can't speak specifically to the design of kit tooling, I predict that analyzing filenames to look for the layout name, then digging through the filetree to find the layout is a hassle. How the heck should you display something like a "this layout does not exist" error anyways if the error is in the filename? This is probably why (afaik) there is exactly zero tooling out there that understands these kinds of "imports" inside the filename. For how much emphasis was put on enabling nice tooling during the routing rework, it's being conveniently ignored here.

One issue that I also see with this new proposal is that the one-to-one correspondence between the directory tree and the route tree that was emphasized so much during the routing rework is ditched. This is a regression. Plain and simple.

To deal with the last remaining piece of the puzzle, I propose that a utility import be added to @sveltejs/kit that easily allows one to import and use a blank layout, therefore acting as a layout reset:

<script>
    import { BlankLayout } from '@sveltejs/kit'
</script>

<BlankLayout>
    <slot></slot>
</BlankLayout>

BlankLayout would just consist of a <slot></slot> and nothing else.

Possible drawbacks

I acknowledge that there may be a few drawbacks with this proposal. First, the importing of a .svelte file may cause .js files to be indirectly imported and run as well, which can cause confusion. To this, I say that having some sort of real import is better than having no real imports and just a string of text inside a filename to guide you on what's being imported/run/used.

Next, and closely related to the previous, could using layouts as if they were components cause confusion about what can and can't be done with them? For example, things like putting layouts inside {#if} or {#each} blocks may be impossible to implement, or not make sense to implement in the first place. I believe that with good error messages and good documentation, this can be a very small issue. Consider for example, how onMount is a function, but with special rules surrounding when and how it can be used. This doesn't cause too much confusion, and it's easy to get an idea of what you can and can't do.

There's still a lot of open questions about the fine details of implementing a big change like this and whether parts of it are feasible. I hope that Rich and the rest of the team can at least give this some thought, as I think I've been clear about what the advantages of such a system could be, and what the disadvantages are of showing even more of the API into filenames.

[dummdidumm]

Using layouts through imports is unfortunately not statically analyzable in a good fashion that handles more complex use cases. What if you have it nested inside an #if (as you already stated)? What if you have a component an only inside that component is the layout import? It would give a false sense of composition if it's only applicable in the simplest of use cases.

By the way, there is nothing stopping you from using the layout composition that way. You can create a reusable UI component for layouts X and Y and do the same for a load function:

export function load(event) {
  return reusableLoad(event);
}

<script>
  import ReusableLayout from '$lib/ReusableLayout.svelte';
  export data;
</script>

<ReusableLayout {data}>
  <slot />
</ReusableLayout>

[stalkerg]

This proposal is ok for me, maybe I can comment on a few things, but folks here have already done it.
After all, I have many more critical questions: how does such a proposal affect +layout.server.js, +layout.js, and +page.js relationships?
I now have two issues that are very important and related to this proposal.

#6183

here, I need a place where I can init i18n, and it should be called globally, after any +layout.server.js but before +layout.js AND +page.js (now it's possible with await parent() boilerplate only)

#6196

if I want to have a separate +layout.svelte without a sidebar for my chat page, I also should duplicate +layout.server.js and +layout.js what sounds wrong for me because my second root layout should use totally same data. I believe this proposal should solve this issue as well somehow.
Basically, if you add to your example .js files, it will be much messy.

During the discussion for this proposal, don't forget that for each layout.svelte file, we can have two more javascript files.
For me would be great if I could choose load function that I should inherit.

[stalkerg]

@danawoodman But for #6196 still I need to create almost empty files? (with reimport my shared load function)

[dummdidumm]

That's true, but it requires no additional API. Regardless what API we choose, there will always be cases where you have to resort to things like composition, which may feel boilerplaty but is simple to understand. Under the proposal, it may also be possible that you can create your two root layouts by having two groups at the root like this:

src/routes
  |- layout.svelte // do things that are true for all layouts in here
  |- (group1)
     |- layout.svelte
     |- layout.server.js
     |- route-a
         |- ...
  |- (group2)
     |- layout.svelte
     |- layout.server.js
     |- route-b
         |- ...

[stalkerg]

Thanks, I will try, maybe it's not so bad.

[danawoodman]

@stalkerg what are you replying to? You mean my suggestion of using a config file?

[stalkerg]

@danawoodman it's was to @dummdidumm
@dummdidumm thanks! A new layout groups is really cool and simplifies things!

[dummdidumm]

Thank you everyone for participating in the discussion! After careful consideration, reading all the alternative proposals and much discussion internally we decided to go with the original proposal, as it - in our opinion - strikes the best balance between simplicity and handling more complex use cases.

What became clear from the discussion is that the use cases vary drastically and that it's close to impossible to design an API that satisfies them all in a consistent way that is easy to learn. It also became clear that whatever API we land on, people feel somewhat compelled to use it because "that's what the framework gives you" - even if other means such as composition or a simple if-statement somewhere in your layout would solve the problem more easily. We hope to make it more clear in the docs that you are encouraged to find your own ways if you don't want to use the (group) mechanism (because for example your use case would result in many nested groups, or you don't want to introduce one for that single outlier).

[danawoodman]

I'm curious, why add this at all at this point if there is so much resistance to it?

Is the rationale that we need to make all these big changes before we get to v1.0?

To me it would be better to not make a change and let things play out a bit before rushing the gun on something so divisive. Couldn't a solution be added post v1.0?

[dummdidumm]

We could only add it if it was non-breaking, this was a breaking change. Furthermore, we didn't feel there was big resistance to the change - the proposal had many thumbs up and alternate proposals like JSON or named layouts v2 didn't feel like they were completely contrary to what the original proposal had (and some just didn't work with the restrictions we have). I fully understand that it's tough to go through all these breaking changes in such quick succession right now, but the end is in sight.

[madeleineostoja]

I'm astonished at how fast such a huge change was proposed, discussed, and then implemented. I mean I happen to quite like it — even with a fairly simple use-case (2x authenticated layouts & an unauthenticated layout, all sharing data) named layouts were a pig — but I do feel like these large design changes should somehow be surfaced and dogfooded better.

Idk I guess that's difficult when sveltekit is barrelling so fast towards a finalised 1.0 API, but as a user I feel like I JUST did a major refactor I didn't have a chance to think about and I'm gonna have to turn around straight away and go do another one now. I know it's all pre release so I did this to myself, but damn the ride is getting rocky. Bundling some of these huge changes up and communicating them in a more cohesive way to developers would be v helpful

---

EDIT — Just refactored for layout groups, and it made my route structures so much clearer, and auth guards simpler, so I'm a big fan. But regardless the feedback about the rapid succession of poorly communicated breaking changes causing friction in the community stands

Still this basic app structure is a thing of beauty 👌🏼

routes
  (app)
  (public)
  +layout.svelte

[dummdidumm]

I understand that one could feel that way, but we don't just do this to check a box, we are genouinly eager for feedback. Note that most people who read it will either go "yeah that works" and close the discussion, or go "that's great!" and put a thumbs up in there, then close - most of the time only those who are opposed to it or have an alternate proposal will make a discussion post, which makes it seem like the reception is negative. We've read all alternate proposals carefully, some wouldn't work due to technical reasons, some would not satisfy other constraints like predictability or more ability to code yourself into a corner. We discussed these and looked if the alternate proposals could be worked into the original proposal, but that wasn't working without making things ambiguous or less learnable - which is why we stuck with the initial proposal.

[CaptainCodeman]

I think the point is it doesn't really give people sufficient time to read, consider and respond in anything but a hurried fashion. Many people aren't even aware of the changes at all until they have suddenly appeared.

If you happen to be free to be looking at the Svelte repo that day, you might see it and have chance to respond ... if

[Rich-Harris]

After opening the routing RFC and the forms RFC, I personally have been bombarded with 'when will it be ready?' messages via tweets, DMs and so on. They say you can please some of the people all of the time and all of the people some of them, but not all of the people all of the time, and that is never truer than in open source! On a macro level, we're under pressure from the community to reach a stable release, and that necessitates breaking changes.

I just don't know what alternative approach to gathering feedback from the people motivated to give it could be better than an announcement on sveltejs/kit/discussions. We're told the changes are poorly communicated but this right here is the avenue for communication.

Keeping discussions open has diminishing returns: there's a decay function in effect, and — empirically — the discussion tends to get less useful after the initial wave of responses. Meanwhile, there's a real cost to delaying, apart from the mini-Osborne effect that happens when people know changes are coming. Often, resolution of one design question unlocks the resolution of others; there are many chunks of work that simply can't happen when you know that changes are coming to the affected part of the codebase. Implementing this change in particular removed a significant amount of technical debt that has allowed us to make progress on a swath of issues, which would otherwise have remained open needlessly.

it can feel like these are just announced to check a box

I take issue with that — the routing proposal evolved significantly as a result of the discussion, and forms are still up in the air because the discussion is ongoing. But in this case it was clear that there no real workable alternatives; by adopting groups we are adopting a solution that has been proven to work with Remix, and will be part of a future Next version, which validates the design choice. (Neither Remix nor Next has the 'breakout' mechanism, however.)

I understand that there's a lot of turbulence right now, and if there was a way of making progress towards 1.0 without that being the case I would take it. Unfortunately there just isn't a way to make everyone happy. I wish there was a kinder way to say this, but this is the price of using pre-release software; we're all paying that cost now to reach a better 1.0 sooner. We do our best to make the changes as manageable as possible (with migration guides and informative error messages), which honestly I feel like a lot of open source projects at this stage wouldn't bother with, but if there are concrete suggestions for how we can make them more so then we would definitely like to hear them.

[mskocik]

My take on this - if someone is really interested in what's going on, he/she can turn on notifications for discussions. I am deleting more than hundred mails related to discussion notifications on a daily basis. And I can't say there isn't/wasn't enough room or time for discussion.

[danawoodman]

All we're asking for is letting these things "soak" longer so more people have a chance to be aware of them and voice their feedback.

A few days just isn't reasonable, no matter the medium or how many people thumbs up the original post.

We all appreciate the strong push to 1.0. I, for one, can't wait for the API to stabilize so I can help "spread the SvelteKit gospel". I'm just asking that some more time is given between announcement and merge.

(And it's worth reiterating that I genuinely appreciate all the core teams contributions and I know you all have to deal with a hell of a lot of comments, criticism and more. The reason we're so vocal is because we really care about (nay, love) this project.)

[rakataprime]

When there is a change like this there should be a greater effort to gather input and slowdown to find a more palatable solution for the community over a longer time period . I actually really liked the layout system when their wasn't named layouts and wish there was still an option to use that system for less complicated uses. I generally don't like pushing logic into the filenames and feel like that is the wrong way to go. I would prefer having a another configuration file that specifies the routing grouping as an alternative solution. Can there be a poll on discord / here for this or other controversial proposals in the future?

[dummdidumm]

You don't need to use groups to create layouts, you can still put them into your folder like before. You can also rewind to earlier layouts by referencing their folder name, all without groups. This change replaced the named layouts in favor of groups, but the simple layout solutions stayed the same.

[acoyfellow]

Looking at the updated docs, i see this:

The URL's to access these pages are this:

/dashboard
/item
/about
/testimonials
/admin

so we have routes that are actually in the same subdirectory to access, but don't live in the same folder

am i understanding that correctly?

[harrylaulau]

its for complex layout management. So I think the correct way is to stick with the old way and only opt in to this new way when you find that you are trying to hack the layout system to achieve something.

[acoyfellow]

@harrylaulau I was using +layout-admin.server.js for checking auth on /admin subdirectory. I can't do that anymore, it throws:
> Files prefixed with + are reserved (saw src/routes/+layout-admin.server.js)

// +layout-admin.server.js
import { redirect } from "@sveltejs/kit";
export async function load({ locals, url }) {
  if (url.pathname !== "/admin/login" && !locals.user) {
    throw redirect(307, "/admin/login");
  }
  return {
    user: locals.user
  };
}

I've re-organized my routes to use the new (admin) folders, and it works as I'd expect. I'll be trying to get used to it.

[harrylaulau]

I think It should be more straightforward for your use case 😂👍🏻

[dummdidumm]

@acoyfellow if you use that layout only inside that admin subdirectory, you don't need the group, you can just place the layout in there: src/routes/admin/+layout.server.js

[acoyfellow]

@dummdidumm thats good news, thank you. Not sure how I missed that.

[Parables]

I am okay with the new changes in the routing system, makes my routes easier to reason about because I can group routes to now use the same layout. Excellent work done.

FWIW, it would be very helpful if we can version the docs to sync with new updates.

I keep the docs opened in multiple tabs only to scroll down to the named-layout section and its gone,
replaced by this (group) thing, and I have been struggling to wrap my head around it over the weekend on how to use these latest changes.

I tried updating the package.json with ncu but that didn't help.
Out of frustration, I run rm -rf node_modules .sveltekit and reinstalled using a different package manager.
Then magically, SvelteKit opened only to tell me that $app/env has been renamed to `$app/environment.

Not everyone follows CHANGELOG.md files for updates, so by versioning the docs, with a What's New section, early adopters and veterans won't be left scratching their heads on how this new feature works and how to migrate their apps to the latest version.

I really love the work you guys are doing here with a strong emphasis on Keeping It: SvelteKit Simple.

Thank you so much for Svelte and SvelteKit are heaven-sent blessings, so invaluable