@webjsdev/cli 0.10.18 → 0.10.19

package/lib/create.js

@@ -85,11 +85,10 @@ const UI_REGISTRY_ROOT = resolveUiRegistryRoot();
 
 /**
  * Read a single @webjsdev/ui registry component, rewrite its relative import
- * of `../lib/utils.ts` so it resolves correctly when written to
- * `components/ui/<name>.ts` in the scaffolded app. The scaffold puts cn()
- * at `lib/utils/cn.ts` (folder-grouped with other browser-safe helpers).
- * From `components/ui/<x>.ts`, the equivalent path is two-up plus into the
- * utils/ folder: `../../lib/utils/cn.ts`.
+ * of `../lib/utils.ts` to the scaffolded app's aliased path so it resolves
+ * when written to `components/ui/<name>.ts`. The scaffold puts cn() at
+ * `lib/utils/cn.ts` (folder-grouped with other browser-safe helpers), so the
+ * alias form is `#lib/utils/cn.ts` (#555/#556).
  *
  * @param {string} name  component name without `.ts` (e.g. 'button')
  * @returns {Promise<string>} source with import rewritten
@@ -97,9 +96,11 @@ const UI_REGISTRY_ROOT = resolveUiRegistryRoot();
 async function readUiComponent(name) {
   const src = join(UI_REGISTRY_ROOT, 'components', `${name}.ts`);
   const raw = await readFile(src, 'utf8');
+  // The registry component imports cn() via a relative `../lib/utils.ts`; rewrite
+  // it to the scaffolded app's aliased path (cn lives at lib/utils/cn.ts).
   return raw
-    .replaceAll("'../lib/utils.ts'", "'../../lib/utils/cn.ts'")
-    .replaceAll('"../lib/utils.ts"', '"../../lib/utils/cn.ts"');
+    .replaceAll("'../lib/utils.ts'", "'#lib/utils/cn.ts'")
+    .replaceAll('"../lib/utils.ts"', '"#lib/utils/cn.ts"');
 }
 
 /**
@@ -286,6 +287,17 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     version: '0.1.0',
     type: 'module',
     private: true,
+    // Native package.json subpath aliases (#555): write app-internal imports as
+    // `#lib/...`, `#components/...`, `#db/...`, `#<any-dir>/...` instead of deep
+    // `../../../` relatives. ONE catch-all key, so a new top-level folder is
+    // aliased with no config change. Node 24+ and Bun both resolve `#*` natively
+    // (a `#/`-prefixed key is rejected by Bun, so this slash-free form is the
+    // cross-runtime-safe shape; no build step, no tsconfig paths). The webjs
+    // server expands the same map for the import graph + browser importmap. Opt
+    // out by using a plain relative import.
+    imports: {
+      '#*': './*',
+    },
     scripts: {
       // No `predev` / `prestart` hooks (#550): the `webjs` block below holds
       // the start orchestration (`webjs db migrate`), run INSIDE `webjs start`,
@@ -724,8 +736,8 @@ export async function createUser(input: { name: string; email: string }) {
  * /api/users: thin route wrapper over typed server actions.
  * Business logic lives in modules/users/, not here.
  */
-import { listUsers } from '../../../modules/users/queries/list-users.server.ts';
-import { createUser } from '../../../modules/users/actions/create-user.server.ts';
+import { listUsers } from '#modules/users/queries/list-users.server.ts';
+import { createUser } from '#modules/users/actions/create-user.server.ts';
 
 export async function GET() {
   return Response.json(await listUsers());
@@ -742,8 +754,8 @@ export async function POST(req: Request) {
     await writeFile(join(appDir, 'test', 'unit', 'users.test.ts'), `import { test } from 'node:test';
 import assert from 'node:assert/strict';
 
-import { listUsers } from '../../modules/users/queries/list-users.server.ts';
-import { createUser } from '../../modules/users/actions/create-user.server.ts';
+import { listUsers } from '#modules/users/queries/list-users.server.ts';
+import { createUser } from '#modules/users/actions/create-user.server.ts';
 
 test('listUsers returns an array', async () => {
   const users = await listUsers();
@@ -833,16 +845,16 @@ export type ActionResult<T> =
   await writeFile(join(appDir, 'app', 'layout.ts'), `// webjs-scaffold-placeholder. This is the example app chrome (brand, nav, content-width container). Adapt it to your app, then delete this line. webjs check fails while the marker remains.
 import { html, cspNonce } from '@webjsdev/core';
 import '@webjsdev/core/client-router';
-import '../components/theme-toggle.ts';
+import '#components/theme-toggle.ts';
 // Webjs UI components are tiered:
 //   - Tier 1 (button, card, input, label, alert, badge, separator, etc.) are
 //     class-helper FUNCTIONS, with no custom element to register. Each page
 //     imports the specific helpers it needs (e.g.
-//     \`import { buttonClass } from '../components/ui/button.ts'\`).
+//     \`import { buttonClass } from '#components/ui/button.ts'\`).
 //   - Tier 2 (dialog, popover, tooltip, tabs, accordion, etc.) ARE custom
 //     elements. Register them by side-effect-importing here once so they
 //     work transitively across every page:
-//       import '../components/ui/dialog.ts';
+//       import '#components/ui/dialog.ts';
 // The example app/page.ts below uses only Tier-1 helpers, so nothing
 // extra needs to be registered. Add Tier-2 imports as you 'webjs ui add'.
 
@@ -1014,18 +1026,18 @@ ${SHADCN_THEME}
 
   await writeFile(join(appDir, 'app', 'page.ts'), `// webjs-scaffold-placeholder. This is the example homepage. Replace it with your app's real page, then delete this line. webjs check fails while the marker remains.
 import { html } from '@webjsdev/core';
-import { rubric, displayH1, accentLink } from '../lib/utils/ui.ts';
-import { buttonClass } from '../components/ui/button.ts';
-import { badgeClass } from '../components/ui/badge.ts';
+import { rubric, displayH1, accentLink } from '#lib/utils/ui.ts';
+import { buttonClass } from '#components/ui/button.ts';
+import { badgeClass } from '#components/ui/badge.ts';
 import {
   cardClass,
   cardHeaderClass,
   cardTitleClass,
   cardDescriptionClass,
   cardContentClass,
-} from '../components/ui/card.ts';
-import { alertClass, alertTitleClass, alertDescriptionClass } from '../components/ui/alert.ts';
-import { separatorClass } from '../components/ui/separator.ts';
+} from '#components/ui/card.ts';
+import { alertClass, alertTitleClass, alertDescriptionClass } from '#components/ui/alert.ts';
+import { separatorClass } from '#components/ui/separator.ts';
 
 export const metadata = {
   title: '${name}: built with webjs',

package/lib/saas-template.js

@@ -14,17 +14,19 @@ const UI_REGISTRY_ROOT = resolve(
 );
 
 /**
- * Read a registry component and rewrite its `'../lib/utils.ts'` import for
- * the scaffolded app's `components/ui/<name>.ts` layout (two-up to lib/).
- * Mirrors the helper in `create.js`, kept private here to avoid coupling.
+ * Read a registry component and rewrite its `'#lib/utils.ts'` import for
+ * the scaffolded app's `components/ui/<name>.ts` layout (the `#lib/utils/cn.ts`
+ * alias). Mirrors the helper in `create.js`, kept private here to avoid coupling.
  */
 async function readUiComponent(name) {
   const src = join(UI_REGISTRY_ROOT, 'components', `${name}.ts`);
   if (!existsSync(src)) return null;
   const raw = await readFile(src, 'utf8');
+  // The registry component imports cn() via a relative `../lib/utils.ts`; rewrite
+  // it to the scaffolded app's aliased path (cn lives at lib/utils/cn.ts).
   return raw
-    .replaceAll("'../lib/utils.ts'", "'../../lib/utils.ts'")
-    .replaceAll('"../lib/utils.ts"', '"../../lib/utils.ts"');
+    .replaceAll("'../lib/utils.ts'", "'#lib/utils/cn.ts'")
+    .replaceAll('"../lib/utils.ts"', '"#lib/utils/cn.ts"');
 }
 
 /** Copy named registry components into `<appDir>/components/ui/`. */
@@ -79,7 +81,7 @@ export async function writeSaasFiles(appDir) {
   // lib/auth.server.ts
   await writeFile(join(appDir, 'lib', 'auth.server.ts'), [
     "import { createAuth, Credentials } from '@webjsdev/server';",
-    "import { db } from '../db/connection.server.ts';",
+    "import { db } from '#db/connection.server.ts';",
     "import { compare } from './password.server.ts';",
     "",
     "export const { auth, signIn, signOut, handlers } = createAuth({",
@@ -124,9 +126,9 @@ export async function writeSaasFiles(appDir) {
   await writeFile(join(appDir, 'modules', 'auth', 'actions', 'signup.server.ts'), [
     "'use server';",
     "",
-    "import { db } from '../../../db/connection.server.ts';",
-    "import { users } from '../../../db/schema.server.ts';",
-    "import { hash } from '../../../lib/password.server.ts';",
+    "import { db } from '#db/connection.server.ts';",
+    "import { users } from '#db/schema.server.ts';",
+    "import { hash } from '#lib/password.server.ts';",
     "",
     "export async function signup(input: { name: string; email: string; password: string }) {",
     "  const exists = await db.query.users.findFirst({ where: { email: input.email }, columns: { id: true } });",
@@ -141,7 +143,7 @@ export async function writeSaasFiles(appDir) {
   await writeFile(join(appDir, 'modules', 'auth', 'queries', 'current-user.server.ts'), [
     "'use server';",
     "",
-    "import { auth } from '../../../lib/auth.server.ts';",
+    "import { auth } from '#lib/auth.server.ts';",
     "",
     "export async function currentUser() {",
     "  const session = await auth();",
@@ -263,7 +265,7 @@ export async function writeSaasFiles(appDir) {
   // app/api/auth/[...path]/route.ts
   await mkdir(join(appDir, 'app', 'api', 'auth', '[...path]'), { recursive: true });
   await writeFile(join(appDir, 'app', 'api', 'auth', '[...path]', 'route.ts'), [
-    "import { handlers } from '../../../../lib/auth.server.ts';",
+    "import { handlers } from '#lib/auth.server.ts';",
     "export const GET = handlers.GET;",
     "export const POST = handlers.POST;",
     "",
@@ -273,10 +275,10 @@ export async function writeSaasFiles(appDir) {
   await mkdir(join(appDir, 'app', 'login'), { recursive: true });
   await writeFile(join(appDir, 'app', 'login', 'page.ts'), [
     "import { html } from '@webjsdev/core';",
-    "import { cardClass, cardHeaderClass, cardTitleClass, cardDescriptionClass, cardContentClass, cardFooterClass } from '../../components/ui/card.ts';",
-    "import { buttonClass } from '../../components/ui/button.ts';",
-    "import { inputClass } from '../../components/ui/input.ts';",
-    "import { labelClass } from '../../components/ui/label.ts';",
+    "import { cardClass, cardHeaderClass, cardTitleClass, cardDescriptionClass, cardContentClass, cardFooterClass } from '#components/ui/card.ts';",
+    "import { buttonClass } from '#components/ui/button.ts';",
+    "import { inputClass } from '#components/ui/input.ts';",
+    "import { labelClass } from '#components/ui/label.ts';",
     "",
     "export const metadata = { title: 'Login' };",
     "",
@@ -315,11 +317,11 @@ export async function writeSaasFiles(appDir) {
   await mkdir(join(appDir, 'app', 'signup'), { recursive: true });
   await writeFile(join(appDir, 'app', 'signup', 'page.ts'), [
     "import { html } from '@webjsdev/core';",
-    "import { signup } from '../../modules/auth/actions/signup.server.ts';",
-    "import { cardClass, cardHeaderClass, cardTitleClass, cardDescriptionClass, cardContentClass, cardFooterClass } from '../../components/ui/card.ts';",
-    "import { buttonClass } from '../../components/ui/button.ts';",
-    "import { inputClass } from '../../components/ui/input.ts';",
-    "import { labelClass } from '../../components/ui/label.ts';",
+    "import { signup } from '#modules/auth/actions/signup.server.ts';",
+    "import { cardClass, cardHeaderClass, cardTitleClass, cardDescriptionClass, cardContentClass, cardFooterClass } from '#components/ui/card.ts';",
+    "import { buttonClass } from '#components/ui/button.ts';",
+    "import { inputClass } from '#components/ui/input.ts';",
+    "import { labelClass } from '#components/ui/label.ts';",
     "",
     "export const metadata = { title: 'Sign up' };",
     "",
@@ -387,7 +389,7 @@ export async function writeSaasFiles(appDir) {
   // app/dashboard/middleware.ts
   await mkdir(join(appDir, 'app', 'dashboard', 'settings'), { recursive: true });
   await writeFile(join(appDir, 'app', 'dashboard', 'middleware.ts'), [
-    "import { auth } from '../../lib/auth.server.ts';",
+    "import { auth } from '#lib/auth.server.ts';",
     "",
     "export default async function requireAuth(req: Request, next: () => Promise<Response>) {",
     "  const session = await auth();",
@@ -402,10 +404,10 @@ export async function writeSaasFiles(appDir) {
   // app/dashboard/page.ts
   await writeFile(join(appDir, 'app', 'dashboard', 'page.ts'), [
     "import { html } from '@webjsdev/core';",
-    "import { currentUser } from '../../modules/auth/queries/current-user.server.ts';",
-    "import { cardClass, cardHeaderClass, cardTitleClass, cardDescriptionClass, cardContentClass } from '../../components/ui/card.ts';",
-    "import { buttonClass } from '../../components/ui/button.ts';",
-    "import { badgeClass } from '../../components/ui/badge.ts';",
+    "import { currentUser } from '#modules/auth/queries/current-user.server.ts';",
+    "import { cardClass, cardHeaderClass, cardTitleClass, cardDescriptionClass, cardContentClass } from '#components/ui/card.ts';",
+    "import { buttonClass } from '#components/ui/button.ts';",
+    "import { badgeClass } from '#components/ui/badge.ts';",
     "",
     "export const metadata = { title: 'Dashboard' };",
     "",
@@ -433,8 +435,8 @@ export async function writeSaasFiles(appDir) {
   // app/dashboard/settings/page.ts
   await writeFile(join(appDir, 'app', 'dashboard', 'settings', 'page.ts'), [
     "import { html } from '@webjsdev/core';",
-    "import { currentUser } from '../../../modules/auth/queries/current-user.server.ts';",
-    "import { cardClass, cardHeaderClass, cardTitleClass, cardDescriptionClass, cardContentClass } from '../../../components/ui/card.ts';",
+    "import { currentUser } from '#modules/auth/queries/current-user.server.ts';",
+    "import { cardClass, cardHeaderClass, cardTitleClass, cardDescriptionClass, cardContentClass } from '#components/ui/card.ts';",
     "",
     "export const metadata = { title: 'Settings' };",
     "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.18",
+  "version": "0.10.19",
   "type": "module",
   "description": "webjs CLI - dev, start, create, db",
   "bin": {

package/templates/AGENTS.md

@@ -202,10 +202,10 @@ Pure functions that return Tailwind class strings. You apply them to
 import {
   cardClass, cardHeaderClass, cardTitleClass,
   cardContentClass, cardFooterClass,
-} from '../../components/ui/card.ts';
-import { inputClass } from '../../components/ui/input.ts';
-import { labelClass } from '../../components/ui/label.ts';
-import { buttonClass } from '../../components/ui/button.ts';
+} from '#components/ui/card.ts';
+import { inputClass } from '#components/ui/input.ts';
+import { labelClass } from '#components/ui/label.ts';
+import { buttonClass } from '#components/ui/button.ts';
 
 return html`
   <div class=${cardClass()}>
@@ -237,13 +237,13 @@ elements. Import them once (typically in `app/layout.ts`) and use
 
 ```ts
 // app/layout.ts (registers the custom elements for every page)
-import '../components/ui/dialog.ts';
-import '../components/ui/tabs.ts';
+import '#components/ui/dialog.ts';
+import '#components/ui/tabs.ts';
 ```
 
 ```ts
 // app/some-page/page.ts (uses the registered elements)
-import { buttonClass } from '../../components/ui/button.ts';
+import { buttonClass } from '#components/ui/button.ts';
 
 return html`
   <ui-dialog>
@@ -463,7 +463,7 @@ singleton avoids opening a new connection on every dev-server reload), and
 the tables from `db/schema.server.ts`:
 
 ```ts
-import { db } from '../../../db/connection.server.ts';
+import { db } from '#db/connection.server.ts';
 const users = await db.query.users.findMany();
 ```
 
@@ -754,8 +754,8 @@ legitimately use `static styles = css\`\`` for scoped CSS.
 ```ts
 // modules/posts/actions/create-post.server.ts
 'use server';
-import { db } from '../../../db/connection.server.ts';
-import { posts } from '../../../db/schema.server.ts';
+import { db } from '#db/connection.server.ts';
+import { posts } from '#db/schema.server.ts';
 
 export async function createPost(input: { title: string; body: string }) {
   if (!input.title) return { success: false, error: 'title required', status: 400 };
@@ -806,7 +806,7 @@ with a `route.ts` POST handler:
 ```ts
 // app/posts/route.ts
 import { redirect, html } from '@webjsdev/core';
-import { createPost } from '../../modules/posts/actions/create-post.server.ts';
+import { createPost } from '#modules/posts/actions/create-post.server.ts';
 
 export async function POST(req: Request) {
   const form = await req.formData();

package/templates/CONVENTIONS.md

@@ -281,7 +281,7 @@ codegen, so there is no dev `before` step.
    preferences (theme, sidebar collapsed, etc.).
 5. To add a model: edit `db/schema.server.ts`, then `npm run db:generate`
    and `npm run db:migrate`. Access via `import { db } from
-   '../../../db/connection.server.ts'` (and the tables from
+   '#db/connection.server.ts'` (and the tables from
    `db/schema.server.ts`) **only inside `.server.{js,ts}` files,
    `route.ts` handlers, or `middleware.ts`**. Components, pages, and
    layouts call into the wrapped server query instead; the framework
@@ -388,6 +388,7 @@ modules/
 ```
 
 **Rules:**
+- **Prefer the `#` root alias over deep relatives.** Write `import { db } from '#db/connection.server.ts'`, `import { Button } from '#components/ui/button.ts'`, `#lib/...`, `#modules/...` instead of `../../../`. It is native `package.json "imports"` (the single `"#*": "./*"` key covers every top-level folder, so a new folder needs no config), resolved by Node and Bun with no build step. There is no slash after the `#` (`#lib/...`, not `#/lib/...`). A same-directory import stays relative (`./sibling.ts`).
 - One exported function per server action/query file
 - Server actions need BOTH the `.server.{js,ts}` extension AND a `'use server'` directive at the top. Extension alone marks a server-only utility (source-protected, not RPC-callable). Directive alone is a lint violation (`use-server-needs-extension`).
 - Components must call `Class.register('tag')`
@@ -588,8 +589,8 @@ the module once (typically in `app/layout.ts`) and use the tag.
 ```ts
 // Tier 1: class helpers on native elements (use this for forms,
 // dashboards, cards, layouts, anywhere the value is purely visual)
-import { buttonClass } from '../components/ui/button.ts';
-import { inputClass } from '../components/ui/input.ts';
+import { buttonClass } from '#components/ui/button.ts';
+import { inputClass } from '#components/ui/input.ts';
 return html`
   <button class=${buttonClass({ size: 'lg' })}>Save</button>
   <input class=${inputClass()} placeholder="Email">
@@ -773,7 +774,7 @@ Consume:
 
 ```ts
 // app/page.ts
-import { rubric } from '../lib/utils/ui.ts';
+import { rubric } from '#lib/utils/ui.ts';
 
 export default function Home() {
   return html`
@@ -925,8 +926,8 @@ route imports and calls it.
 ```ts
 // modules/posts/actions/create-post.server.ts
 'use server';
-import { db } from '../../../db/connection.server.ts';
-import { posts } from '../../../db/schema.server.ts';
+import { db } from '#db/connection.server.ts';
+import { posts } from '#db/schema.server.ts';
 export async function createPost({ title, body }) {
   const [post] = await db.insert(posts).values({ title, body }).returning();
   return post;
@@ -936,7 +937,7 @@ export async function createPost({ title, body }) {
 ```ts
 // app/api/posts/route.ts
 import { route } from '@webjsdev/server';
-import { createPost } from '../../../modules/posts/actions/create-post.server.ts';
+import { createPost } from '#modules/posts/actions/create-post.server.ts';
 // The route() adapter merges query + route params + JSON body into one input
 // object and JSON-responds the result. Pass { validate } to guard the input.
 export const POST = route(createPost);
@@ -1039,8 +1040,8 @@ Where the data lives, where to read it:
 ```ts
 // modules/posts/actions/create-post.server.ts
 'use server';
-import { db } from '../../../db/connection.server.ts';
-import { posts } from '../../../db/schema.server.ts';
+import { db } from '#db/connection.server.ts';
+import { posts } from '#db/schema.server.ts';
 import type { ActionResult } from '../types.ts';
 
 export async function createPost(input: {
@@ -1167,8 +1168,8 @@ Routes are thin wrappers over typed server actions. Business logic lives in
 
 ```ts
 // app/api/users/route.ts: thin wrapper
-import { listUsers } from '../../../modules/users/queries/list-users.server.ts';
-import { createUser } from '../../../modules/users/actions/create-user.server.ts';
+import { listUsers } from '#modules/users/queries/list-users.server.ts';
+import { createUser } from '#modules/users/actions/create-user.server.ts';
 
 export async function GET() { return Response.json(await listUsers()); }
 export async function POST(req: Request) {

package/templates/test/hello/hello.test.ts

@@ -16,7 +16,7 @@ test('html template renders correctly', async () => {
 
 test('example: your first server action test', async () => {
   // Import your server action:
-  // import { createPost } from '../../modules/posts/actions/create-post.server.ts';
+  // import { createPost } from '#modules/posts/actions/create-post.server.ts';
   //
   // const result = await createPost({ title: 'Test', body: 'Content' });
   // assert.equal(result.success, true);