replace `$lib` with `#lib`

[Rich-Harris]

More for discussion than anything: now that the imports field of a package.json is widely supported, including by TypeScript, maybe it would be more coherent to use it for src/lib than having a special alias. Essentially:

• $app/* — our stuff
• #lib/* — your stuff

[hyunbinseo]

Related issue #15234

I've been using this convention in multiple projects based on https://github.com/hyunbinseo/svelte-kit-template

I love the distinction of $ and #. That's how I am using it with SvelteKit@2 - $ imports are SvelteKit proprietary.

---

If SvelteKit@3 targets Node.js 24.14+, maybe #lib can be handled by subpath imports entirely?

Though it seems to require Node.js module resolution (e.g. nodenext)

Reference https://nodejs.org/api/packages.html#subpath-imports

{
  "imports": {
    "#lib/*": "./src/lib/*"
  }
}

[manuel3108]

Potential toods:

• Remove addition of the path to the .svelte-kit/tsconfig.json
• Adjust sv create
• Add documentation
• potentially add something to sv migrate
• Deprecate alias in svelte-kit config

[theetrain]

I tried using #lib and #customAlias a few months ago in VSCode, but I ran into issues with syntax highlighting and auto imports. Unfortunately, I don't have screenshots handy and I've since moved to Zed.

I'm still in favour of this change since it's supported by package.json, Node.js, and apparently TypeScript. Let's just ensure editors play nicely with them.

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

Unfortunately we can't limit support to Node 24.14+ for v3 -- 22 still has a lot of life left in it. That'll have to be a v4 thing (if 24 isn't EOL by then 😆)

[Rich-Harris]

There's no issue with support. All that changed in 24.14 is support for #/, which doesn't concern us

[cofl]

One key difference that will need documenting is that subpath imports don't work at all with implicit directory modules or file imports without extensions, whereas the current path mechanism has no issue with those. On pages like Loading data the documentation will likely need to be updated:

import * as db from '#lib/server/database.js' // or
import * as db from '#lib/server/database/index.js'

I know my opinion doesn't matter much here, but changing TypeScript's module/moduleResolution to nodenext may be desirable to lead users like myself toward consistency between subpath imports and relative imports:

import type { PageProps } from "./$types.js"

Subpath imports do seem to work without any changes to the .tsconfig.

[hyunbinseo]

@cofl That's why I've mentioned nodenext above. I am fine with nodenext - all my projects use this - but it will be cumbersome for existing users to upgrade.

Also, is the SvelteKit v3's Node.js engine target decided? It's a major release and requiring current LTS in the dev environment seems reasonable. (or runtime in the case of adapter-node users)

[Rich-Harris]

Yep:

kit/packages/kit/package.json

Lines 137 to 139 in dfbe012

	"engines": {
	"node": ">=22"
	}

I would love for everyone to use nodenext — I've been banging the 'extensionless imports are stupid' drum for a long time (e.g. nodejs/node#46074 (comment)) — but unfortunately I think users might revolt. Even forcing $lib/server/database to #lib/server/database/index.js (which I honestly didn't realise was a consequence of this change) is likely to annoy some people.

(I still think this is the right call though — those people can always create their own alias if they're that opposed to having better and more explicit code.)

[paoloricciuti]

I've tried without much success to at least allow for index.js resolution but it might be possible with multiple import maps to allow for the resolution of #lib/db

[Rich-Harris]

Actually I think it's possible to do it like this, which is working for me locally:

"imports": {
  "#lib": [
    "./src/lib/*",
    "./src/lib/*.js",
    "./src/lib/*/index.js"
  ]
}

nodenext enjoyers can remove the last two entries.

[lishaduck]

Does that work in Node, or just TypeScript? IIRC for exports, that'd be attw's FallbackCondition, which I believe is the same for imports as well, though I don't have something on hand to test it with at the moment.

[Rich-Harris]

It appears not — it only respects the first entry in the array, oddly enough. But given that the code is always run via Vite, that's... probably fine? And if people want to prevent themselves from writing code that will fail if run without Vite, they can always just get rid of the second two options. They'll still be in a better position than if they were using $lib.

[lishaduck]

Oh, does Vite "support" fallbacks as well? I didn't realize that, I thought they matched the Node.js behavior (at least in dev). If it does handle it, my bad, sorry!