# Package Imports

Import WebJs UI components with package.json imports.

Source: https://webjs.dev/ui/docs/package-imports

A WebJs app imports its own files through [package imports](https://nodejs.org/api/packages.html#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`:

```json title="package.json"
{
  "imports": {
    "#*": "./*"
  }
}
```

Then import the installed components using `#...` specifiers:

```ts
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:

```json title="package.json"
{
  "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.

```json title="tsconfig.json"
{
  "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.

```json title="components.json"
{
  "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:

```ts title="components/ui/dialog.ts"
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](https://webjs.dev/ui/docs/monorepo).

## File extensions

The catch-all maps `#x` to `./x` unchanged, so a specifier carries its extension, as every import in a WebJs app does:

```ts
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 `imports` entry is in the app's own `package.json`
- the specifier names a top-level directory, not a file at the app root (import a root file such as `./env.ts` relatively)
- 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`.
