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

[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/*'

[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.

[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?

[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.

[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

[PatrickG]

But that would be solvable with the new kit.files.src option in those projects, no?

[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.