A WebJs app imports its own files through package imports, the imports field of package.json, and the components you add are imported the same way.
Package imports let you use private #... import aliases from your package.json instead of deep ../../../ relative paths. Node 24 and later and Bun resolve them natively, so there is no build step and no compilerOptions.paths to keep in sync.
Example
A WebJs app has one catch-all entry in its package.json:
{
"imports": {
"#*": "./*"
}
}
Then import the installed components using #... specifiers:
import { buttonClass } from '#components/ui/button.ts';
import { cn } from '#lib/utils/cn.ts';
Package import specifiers must start with #, and there is no slash after it: write #lib/..., not #/lib/..., because Bun does not resolve a #/ key. Keep the file extension, since the browser loads these modules as they are, with nothing in between to guess it.
App
For a WebJs app that installs components into its own directory.
Configure package.json
webjs create writes the imports entry for you. In an app that lacks it, add the catch-all, which covers every top-level directory at once:
{
"imports": {
"#*": "./*"
}
}
Because the key is one wildcard, a new top-level folder is aliased with no change here. The WebJs server reads the same map, so a # import resolves in the browser too, and a # import of a .server.ts file still counts as a server-only import.
Configure TypeScript
The scaffold's tsconfig.json already resolves package imports. It uses Node's own resolution, which reads the imports field, and allows the .ts extension in a specifier.
{
"compilerOptions": {
"module": "NodeNext",
"moduleResolution": "NodeNext",
"allowImportingTsExtensions": true
}
}
You do not need compilerOptions.paths for these aliases.
Configure components.json
Leave the aliases in components.json as directory paths. They tell the CLI where to write each file, and the CLI writes a relative import inside every file it installs, so the installed files never depend on the alias map.
{
"aliases": {
"components": "components",
"ui": "components/ui",
"lib": "lib",
"utils": "lib/utils/cn"
}
}
The ui directory, components/ui, is reached as #components/ui/... through the same catch-all.
The utils path, lib/utils/cn, is the file lib/utils/cn.ts, reached as #lib/utils/cn.ts.
What the CLI writes
When add copies a file, it rewrites each import to a path relative to where the file lands. The dialog, for example, lands in components/ui/ and imports the helpers and the button beside it:
import { cn, ensureId } from '../../lib/utils/cn.ts';
import { onBeforeCache } from '../../lib/utils/dom.ts';
import { buttonClass } from './button.ts';
A block's page and its own components are rewritten the same way, wherever their targets put them. Your own code is free to use # imports for all of them.
Monorepo
In a monorepo, each WebJs app has its own package.json with its own imports field and its own components.json, and its # specifiers resolve inside that app. See the monorepo docs.
File extensions
The catch-all maps #x to ./x unchanged, so a specifier carries its extension, as every import in a WebJs app does:
import { buttonClass } from '#components/ui/button.ts';
Do not change the target to add an extension ("./*.ts"). The browser and Node both load the path you write, and a pattern that appends .ts would stop every other file type, such as a .js module or a stylesheet, from resolving through it.
Troubleshooting
If a #... import does not resolve, check that:
- the specifier starts with
#, with no slash after it - the
importsentry is in the app's ownpackage.json - the specifier names a top-level directory, not a file at the app root (import a root file such as
./env.tsrelatively) - the specifier keeps the file extension
- the matching file exists after components are added
If a component landed in an unexpected directory, check the aliases in components.json: they are directory paths, so a value such as #components is read as a folder named #components.