kit.files.* deprecation

[Rich-Harris]

We deprecated the kit.files.* configuration options in #14152. This was prompted by the addition of remote functions, which SvelteKit was looking for inside kit.files.lib and kit.files.routes (aka src/lib and src/routes, for 99% of people) — some people wanted to be able to put remote functions elsewhere in src, and the existing setup made that hard. We could have added a kit.files.remotes option or similar, but... ugh.

Another example: observability. If you can configure other stuff in src, shouldn't you be able to configure src/instrumentation.server.ts? If not, why the discrepancy?

And so on. Faced with a choice of adding a new config option for every new feature, or just removing a feature that none of us could remember the original reason for, we decided it made sense to remove it. This makes things much simpler — not so much implementation-wise, but in terms of the framework's learnability and so on. Right now, every time we mention specific files or directories in the docs we either have to gloss over the configurability or add throat-clearing like this:

And every time someone moves between SvelteKit codebases, there's a chance they'll have to temporarily rewire their brain to get their bearings. This is particularly troublesome if you're an LLM: for coding assistants, it's hugely beneficial if project structure is predictable and documented.

But.

Some of you have since left comments on closed PRs and issues arguing against this decision. Continuing discussions on closed threads is never a good idea, so if there's a conversation to be had it's better to have it here.

We won't be moved by complaints like 'I want to use source instead of src or pages instead of routes for aesthetic reasons'. The whole point of a framework is to have a consistent vernacular, and if there are naming choices that truly don't make sense then they should change for everyone.

But we do want to make sure that people have enough flexibility to solve esoteric cases. So far, at least, it seems like the only thing that's missing is the ability to configure routes, and if the outcome of this discussion is that we keep everything deprecated except routes, that seems like a useful discovery and an overall win. Perhaps we'll even revisit #6031 in light of this.

Having said that, it's not yet totally clear to me what the limitations of a conventional monorepo setup would be. There is some weirdness involved — if you have multiple SvelteKit apps in a monorepo, you'll likely need to do this sort of thing which feels a bit grubby...

// project/apps/app-one/svelte.config.js
export { default } from '../../svelte.config.js';

...but if there are limitations and sticking points here then perhaps we can address those too.

Appreciate those of you who have weighed in on this already — I realise adding deprecation notices is a heavy-handed way to gather feedback, but you are proof that it works!

[nosovk]

I've made a small demo, of how we use routes in wild life:
https://github.com/nosovk/svelte-kit-multiple-routes-example

check .env file in a repo and svelte-config.js to get an idea.

In real life projects different providers used (mostly static adapter with something, like Cloudflare, Vercel and probably soon will shift to Fastly), and base path hardly used (because lands embedded to sites managed by different partners).

The land itself placed in $lib, if we can support api in exact adapter we also import api handlers from $lib (can extend repo if needed)

[aksnjaxh]

Thanks for the reproduction repo. We have a similar setup, but probably even more complicated

[nodeartio]

We use the same kind setup for lots of projects.

[maxcoredev]

Me fight for Svelte in every company I work.
All of them have projects on different frameworks and documented practices on how we look on our project's structure, etc. And it's always framework-agnostic. We have libs that are agnostic. (All that projects are often huge and related to business processes automation in most cases). So, it's not about "personally me want sources instead of src in my pet project", it's in common enterprise protocol.

And this is what I came up with in latest project:

assets/ (`files.assest = 'assets/'` instead of `static/`, sounds logical since `%sveltekit.assets%`)
lab/ (Light Agnostic Bundle, agnostic to framework, `git pull`ed)
les/ (Library Extending Svelte — agnostic to project, also `git pull`)
lib/ (current project specific lib we all now)
src/ (pages and components grouped by domain)
    users/
        user.svelte
        users.svelte
    groups/
        group.svelte
        group.svelte
routes/ (code based router, more on it below)
    [...path]/
        +error.svelte
        +page.svelte
        +page.server.ts
        +page.ts

Ye, we want to be global lib (which is git pulled) in root to be on the same level with project specific lib...
And tech logic live in lib/, but business logic in src/ without any extra nestings

Also, our teem refuse to make our project structure depend on browser urls since marketing-managers can change it any time and as often as they want it to.
So we use our own code-based-router.
routes/ are just universal proxy for everything and we define routes in urls.ts like that:

import type { Pattern, Error } from '/router/types.ts';

const error: Error = () => import('/src/error.svelte');
const base: Layout = {page: () => import('/src/base.svelte'), error: error};
const layouts = [base];

const patterns: Pattern[] = [
    {re: '',                   page: () => import('/src/home.svelte'), layouts},
    {re: 'users',              page: () => import('/src/users/user.svelte'), layouts},
    {re: 'users/(<id>[0-9]+)', page: () => import('/src/users/users.svelte'), layouts},
]

export { patterns, error}

And we are happy with that.
(Sure it also needs config.kit.files.routes).

Honestly, when I first saw "The config.kit.files.routes option is deprecated, and will be removed in a future version" I felt panic.
It'll become much harder to fight for Svelte.
I'm not an expert to say what framework should do or should not, but as a developer, I'll be glad if frameworks were aimed to provide possibilities and freedom, so different users find/develop their own best practices suiting their needs, enterprise users can develop their best practices, indy-dev theirs and so on.
Big thx for raising that topic

P.S. I do understand the value of simplicity (but not unification among all kinds of projects), and I'll be ok with any other mechanism of reorganising paths that'll be easier to maintain from Svelte's side

[blaketradedev]

I've built my whole app in a way relying on "config.kit.files.routes"

Please don't deprecate this, I see others complaining as well, which gives me hope you won't, and thanks for listening to us.

files: {
routes: 'src/routes/project_name'
},

$project: 'src/lib/project/project_name/*'

[dummdidumm]

@blaketradedev could you clarify? This sounds like you have multiple projects in one project and decide which one to build based on some environment variable. If yes, what aren't you using a monorepo to achieve the same thing?

[prince-jagani]

I've been a Svelte user for a while now, and the flexibility of the kit.files configuration was actually one of the key reasons I chose SvelteKit over other frameworks. The ability to customize the file structure isn't just an "aesthetic" preference for me; it's a critical part of how I manage complex projects.

For example, in a current project, I have a monorepo setup where I share components and utility functions from a single $lib directory across multiple SvelteKit applications. Each application, however, has its own distinct set of routes and layouts. I'm able to manage this seamlessly by using the kit.files configuration to point to separate routes directories for each app, like this:

/** @type {import('@sveltejs/kit').Config} */
const config = {
	kit: {
		adapter: adapter(),
		files: {
			routes: 'src/routes/project-1',
			src: 'src/src-1',
			// ... other custom paths
		}
	}
};

This setup allows me to build a single application with shared $lib components while maintaining entirely distinct layouts and pages for different "sub-projects" or modules. For example, I can have src/src-1 containing specific source code and src/routes/project-1 defining the routes for a particular part of my application, all within the same SvelteKit instance, reusing common components defined in $lib.

I understand the goal of making SvelteKit more consistent and predictable, especially for new users and tools like LLMs. However, for those of us working on more unconventional, large-scale projects, this feature is a lifeline. I believe removing it entirely would be a step backward in terms of flexibility and would force developers to use "grubby" workarounds that are arguably less readable and harder to maintain than the current configuration options.

[dummdidumm]

Why are you not using a "regular" monorepo, i.e. one package with your lib functionality and then one package per application that references that lib?

lib/...
project-1/...
project-2/...

where each project's package.json does "devDependencies": { "lib": "workspace:* } (using pnpm)

https://pnpm.io/workspaces

[blaketradedev]

I've built my whole app in a way relying on "config.kit.files.routes"

Please don't deprecate this, I see others complaining as well, which gives me hope you won't, and thanks for listening to us.

files: {
routes: 'src/routes/project_name'
},

$project: 'src/lib/project/project_name/*'

[MegaDiablo]

In my project, I keep both frontend and backend in the same repository, and it is crucial for me to at least specify my own root directory for the entire frontend structure.

Example stucture:

project/
    .git/
    server/ ( code of backend [use python] )
    webui/  ( code of frontend [use as Backend-for-Frontend] )
        lib/
        routes/
        app.html
        ...
    vite.config.js
    svelte.config.js
    package.json
    ...

[PatrickG]

But that would be solvable with the new kit.files.src option, no?
I must have misunderstood something.
I thought kit.files.src would remain available as a configuration option.

[dummdidumm]

Shouldn't you be able to keep doing that, just move your frontend-specific configs into the webui folder?

[blaketradedev]

@Rich-Harris Please reconsider deprecating this. It’s such an essential part of my workflow that its removal would make updating nearly impossible for me. I know I’m speaking for more than just myself, as many users rely on it without actively commenting here.

kit: { adapter: adapter({ out: 'build' }), files: { routes: `src/routes/${project}` }, alias: { '@/*': './src/lib/*', $assets: 'src/assets/*', $layout: 'src/layout/*', $components: 'src/components/*', $auth: 'src/auth/*', $server: 'src/server/*', $i18n: 'src/i18n/*', $ctx: 'src/lib/context/*', $socket: 'src/socket/*', $table: 'src/lib/layout/global/table/*', $default: 'src/routes/_default/*', $project: `src/routes/${project}/assets/*` } }

[paulovieira]

For those affected by this change: wouldn't a simple symlink to a custom directory accomplish the same result?

I apologize if this sounds naive but I didn't see any mention of this solution.

[MegaDiablo]

I'm sorry, but this is an attempt to solve some of the problems when there is already a flexible and normal solution in the config.

This is where we collect cases on why it is worth leaving these settings in the configuration.

[aksnjaxh]

Unfortunately not. Changing env variable is a bit more easy then recreation of symlink (especially in a team where linux\widows\osx used by different developers). Also CI/CD tools have building env support, while symlink is a more complicated and requires some hacks on platforms like cloudlfare pages\workers

[paulovieira]

I agree: symlinks could work in some cases but would be a hack compared to the current solution. Sorry if my suggestion added noise to this discussion.

Another 2 cents to the discussion: even if the kit.files.* options are kept, the rest of the docs could omit them (except in the "Reference -> Configuration" page) . That is, the options could be available for advanced use cases, but don't encourage people to use them. This might help AI agents to consider only the standard structure.

[PatrickG]

Just want to leave a +1 for revisiting #6031

[aksnjaxh]

Supporting of configuration options for folder structure is crucial for monorepos. Workarounds like symlinks are problematic. Keeping customization options is vital for SvelteKit's adaptability to complex, real-world development scenarios, where SvelteKit often integrated within large existing codebases.

[dummdidumm]

Workarounds like symlinks are problematic

Why exactly? What is a workaround about this?

[peterpeterparker]

Similarly to @MegaDiablo, my personal and professional projects use SvelteKit in a repo where both the frontend and backends (Rust) live together. As a result, the src folder is subdivided, for example:

src
   backend1
   backend2
   backend3
   frontend

While one could argue that if config.kit.files were to be deprecated, all npm, Vite, and Svelte configuration could be moved inside the src/frontend subfolder, I personally think it’s cleaner and more maintainable to keep the configuration at the root of the repo rather than “hiding” it within a source subfolder.

In addition, our repo contains other tools - such as Node.js scripts - that share dependencies with the application. From that perspective, it also makes sense to keep the package.json and node_modules solely at the root of the repo.

Currently, my svelte.config are set up like this:

const filesPath = (/** @type {string} */ path) => `src/frontend/${path}`;

/** @type {import('@sveltejs/kit').Config} */
const config = {
	preprocess: vitePreprocess(),

	kit: {
		adapter: adapter({
			fallback: 'index.html',
			precompress: false
		}),
		files: {
			assets: filesPath('static'),
			lib: filesPath('src/lib'),
			routes: filesPath('src/routes'),
			appTemplate: filesPath('src/app.html')
		},
       ...

Examples:

• https://github.com/junobuild/juno
• https://github.com/dfinity/oisy-wallet

[peterpeterparker]

Are you sure this is a new option? Where is it documented?

According types, is deprecated as well.

files?: {
			/**
			 * the location of your source code
			 * @deprecated
			 * @default "src"
			 * @since 2.28
			 */
			src?: string;

Its description also only mention source code which excludes other files such as the static folder.

Morover the deprecation warning - e.g. "The config.kit.files.lib option is deprecated, and will be removed in a future version" - does not mention it.

[PatrickG]

Oh, then I must have misunderstood something.
I thought kit.files.src would remain available as a configuration option.

[peterpeterparker]

I agree with you, though. In my use cases, I do not need multiple options. Being able to specify where src and static are located would be enough and wouldn’t introduce breaking changes or pipeline issues like deprecating all the options would.

[nosovk]

Actually need to control "routes" location... src itself is a corner case, when all folders moved to new location. Like baseUrl for whole project. But unfortunately it's not enough, if you want to support multiple sites, with shared $lib

[peterpeterparker]

if you want to support multiple sites, with shared $lib

That may be another use case than the one I shared. In the following project, I have two distinct SvelteKit apps - in src folder. - that share a common library ('core'). I use aliases to point to its source. Each app has its own svelte.config.

https://github.com/dfinity/oisy-wallet-signer/tree/main/demo

Side note: I guess this is one of the option to resolve the breaking change if kit.files ever really gets removed. Move package.json, svelte.config, tsconfig, and vite.config into the 'root' folder where the SvelteKit app’s src and static directories live.

[maxcoredev]

I’ll make my point in separate comment:
Me do not want Svelte team to maintain and support features which are 'unjustified?'. Since then more important features will get more attention they need.

And probably there could to be a universal and less complex mechanism like kit.alias remapping object like

{
    '/src/routes/': '/routes/',
    …
}

for any dir without predefining possible keys in that object and without that magical $src paths, etc.

Will not say for others, but it’ll totally suit needs of projects I work on

[aurelienrichard]

I understand the rationale, but this deprecation is defended as if SvelteKit were opinionated about folder structure, which it isn't.
"Here's a src/lib and a src/routes folder, do what you want with it" isn't sufficient to guarantee that a project won't turn into a giant mess as it grows. Therefore, we need to bring our own opinions about folder structure to the table. Which is fine, but without this feature, it seems like it will be much harder to do so.

Having a plan to structure a project at scale isn't just an aesthetic preference; it's a requirement. I wouldn't mind this change if it meant that SvelteKit would be more opinionated about folder structure as a result of it, but it doesn't look like it will be. So, in my view, this is a mistake.

[Rich-Harris]

Your solution to SvelteKit being insufficiently opinionated about folder structure is for it to be less opinionated about folder structure?

[blaketradedev]

I asked my cousin, did you understand what Rich Harris said here showing your reply, and he said I got brain damage, we're humans, we don't possess to comprehend your high intellectual response, will you keep the feature please? <3

[aurelienrichard]

Your solution to SvelteKit being insufficiently opinionated about folder structure is for it to be less opinionated about folder structure?

Not quite.
It's either opinionated or unopinionated but with the tools to apply our own opinions. Either scenario is fine. However, if this change were to take effect, we'd end up in an awkward middle ground. That's what I'm getting at.

[oneezy]

I have a complex monorepo (turborepo + pnpm workspaces) that would significantly benefit from retaining config.kit.files options that I don't think kit.files.src can handle alone. It's not about aesthetic preferences for me, but more about eliminating complex workarounds.

Current Architecture

template/
├── apps/
│   ├── app/            # Sveltekit 
│   ├── docs/           # Sveltekit
│   ├── site/           # Sveltekit
│   └── storybook/      # Sveltekit 
└── packages/
    ├── config/         # shared configs for all apps
    │── tools/          # custom tooling for symlink creation
    └── ui/             # shared components lib for all apps
        ├── src/          # (workspace)
        └── static/       # (symlink)

Current Workarounds (that kit.files would eliminate)

1. Static Asset Sharing

Current solution: Custom symlink management via packages/tools

pnpm symlinks

With kit.files: Simple config per app

// apps/site/svelte.config.js
export default {
  kit: {
    files: {
      assets: '../../packages/ui/static'
    }
  }
}

2. Remote Functions Issue

Current problem: Remote functions only work within individual apps, not shared packages
With kit.files: Could potentially reference shared remote function directories

3. Shared Configuration

Current: Complex config inheritance via @packages/config-svelte

// packages/config/svelte/svelte.config.js - Master config
export default {
  kit: {
    adapter: adapter(),
    alias: {
      "@packages/ui": resolve("../../packages/ui/src/lib"),
      "@packages/tools": resolve("../../packages/tools/src"),
      $root: resolve("../../../"),
      $app: resolve("../../apps/app/src"),
      $docs: resolve("../../apps/docs/src"),
      $site: resolve("../../apps/site/src"),
      $storybook: resolve("../../apps/storybook/src"),
      $lib: "./src/lib",
    },
    experimental: { remoteFunctions: true }
  }
}

// apps/**
import config from "@packages/config-svelte";
export default config;

With kit.files: Simplified shared config, each app gets shared assets automatically

// packages/config/svelte/svelte.config.js - Much simpler master config
export default {
  kit: {
    adapter: adapter(),
    files: {
      assets: '../../packages/ui/static'  // All apps inherit shared assets
    },
    alias: {
      "@packages/ui": resolve("../../packages/ui/src/lib"),
      "@packages/tools": resolve("../../packages/tools/src"),
      $lib: "./src/lib",
    },
    experimental: { remoteFunctions: true }
  }
}

// apps/** (stays exactly the same - no symlink tooling needed)
import config from "@packages/config-svelte";
export default config;

Why This Matters for Monorepos

1. Eliminates custom tooling - No need for symlink management scripts
2. Simplifies scaling - Adding new apps becomes trivial configuration
3. Standard approach - Uses SvelteKit's native path system vs. custom workarounds
4. Cross-platform reliability - No symlink compatibility issues

[dummdidumm]

I don't understand point 3 - there's the assets argument but you already handled that in 1, everything else is just additional aliases. Could you clarify?

[oneezy]

Sorry, I was being redundant there. I really have two main arguments:

1. Static asset sharing - kit.files.assets would eliminate custom symlink tooling
2. Remote functions - could potentially work from shared packages with kit.files configuration

[maxcoredev]

One more thing why we have to remap files.assest from static/ to assets/
Because API service also have its' own https://example.org/static/, and it is proxied through Svelte, so:
https://example.org/assets/ <— Svelte's static
https://example.org/static/ <— API's static
https://example.org:8000/static/ <— also API's static

[ebolyen]

We have a probably pretty esoteric situation:

We have two versions of this site: https://view.qiime2.org/

One version is deployed with a service worker (and thus needs a different config) and the other is vendored into a CLI application, with a different initialization involving a local ephemeral file-server.

It seemed at the time that the files.routes was a simple way to set up the different entry-points for the application. I mention this because we have a situation where the config is necessarily different, so we don't feel the pain of using an ENV var to swap things out, it just looks a bit like using webpack of old.

I imagine we could probably do the mono-repo approach and punt most of the application code out of sveltekit, but as largely Python developers, I don't think that would have occurred to us without this discussion.

[ebolyen]

Actually, a question about the mono-repo approach, would we still get HMR from vite if the code lives in a svelte library a directory above the various deployment-oriented sveltekit repos?

[ebolyen]

Just to offer a thought: what about something like a build-time group in routes? It would be set via some mechanism during build/preview/dev and the entry-points are still in a consistent place:

routes/
├── (+default)
│   ├── bar/...
│   ├── +layout.svelte
│   └── +page.svelte
└── (+vendor)
    ├── foo/...
    ├── +layout.svelte
    └── +page.svelte

This would be a bit weird looking, but I think someone unfamiliar with it would google it and find the relevant docs. LLMs I suspect wouldn't care, worst case they miss the build prefix, but it's still in routes and then sveltekit could even error on the "orphaned" routes, making fixing it straight-forward.

[ryanatkn]

Offering one POV, I've resisted monorepos, surely somewhat irrationally, but also because I have a lot of interconnected projects with different needs and drawing boundaries at the monorepo doesn't make sense for most of them. So I put more time into workflows that work on sets of repos instead of a bundled one.

Is it optimal? Probably not, I see advantages that fit well with JS's module system, but I wasn't seeking to adopt monorepos. But Svelte has had me eat my vegetables before and I liked it, it could be one of those.

In an experimental project I have src/roots as my frontends directory, so each of its subdirs like src/roots/foo is the equivalent of a SvelteKit src/routes. This seems to scale nicely but it's an opinionated choice about the shape of things and it's not designed for the web.

[laztheripper]

Please don't deprecate this...

I use this in every new project because I use a different asset folder depending on dev/prod.
This lets the prod version use different files that only exist there and not on my dev pc and it lets me have tools that generate a folder structure that the project can directly use that cannot be made to just be /static/.

I can't use sveltekit if you remove this.

I feel like any non-trivial project with self hosted load balancers and all the rest will require the assets path to be configurable and this so-called "fix" only helps for people making markdown blogs and vercel hosted apps with 5 total users (no offense).

[sm-harun]

I hope the svelte team reconsiders this decision. A lot of people have already been using this feature, and is a good selling point to use for svelte-kit. Svelte should be for EVERYONE, it shouldn't lock you in to a specific file structure it decides, And the config.kit.files is a really huge help to that.