kilo-ui

shadcn-style Vue 3 registry for team CRUD apps.

This package does not work like a normal UI runtime dependency. It works like shadcn: the CLI copies component source code into the project that needs it. After that, the project owns the code and can edit it.

What lives where

| Location | Contents | |----------|----------| | node_modules/@lyda/kilo-ui/ | CLI, registry, theme CSS under registry/styles/…, cn() at utils (from registry/lib/utils.ts in the tarball), defineConfig. There is no src/lib or src/styles in your app for Kilo — that’s all inside this package folder after npm install. | | Your app root | kilo.config.ts, env.d.ts | | Your Tailwind root CSS (e.g. src/assets/base.css) | init merges a small marked block: @import theme from the package + @source for your components / composables. One @import "tailwindcss" for the whole app — no extra src/styles/kilo-ui.css file. | | src/components/ui/... (or your prefix) | Appears only after kilo-ui add — copied components. init does not create an empty ui folder. |

Not added to new projects: src/lib/utils.ts, a separate src/styles/kilo-ui.css, or an empty components/ui tree — use @lyda/kilo-ui/utils, merged CSS in your Tailwind root, and run add when you want components.

One Tailwind in the app

Your Vue + Vite app already has Tailwind (tailwindcss + @tailwindcss/vite). Installing @lyda/kilo-ui does not install Tailwind again. The library repo uses Tailwind in devDependencies for docs and development only; the published package does not ship Tailwind as a dependency.

There is one @import "tailwindcss" — in your existing root stylesheet (e.g. src/assets/base.css). kilo-ui init merges into that file (between /* kilo-ui:start */ and /* kilo-ui:end */):

1. @import "@lyda/kilo-ui/styles/twui-theme.css" (tokens live in node_modules)
2. @source globs so Tailwind scans src/components and src/composables (paths are computed relative to that CSS file).

Import only that Tailwind root from main.ts (e.g. import './assets/base.css').

You should not have src/lib/ for Kilo — cn comes from @lyda/kilo-ui/utils. Remove leftover src/lib/utils.ts from older scaffolds if you still have it.

npm ERESOLVE / peer warnings

This package does not install Tailwind. The published tarball only ships the CLI, registry files, and jiti (used to load kilo.config). tailwindcss and @tailwindcss/vite live in this repo’s devDependencies for docs and library development — npm does not put devDependencies of a package into apps that install it, and tailwindcss is not listed under dependencies or peerDependencies. Your app keeps one Tailwind install (the one you already added for Vue).

So when you see npm warn ERESOLVE overriding peer dependency while installing @lyda/kilo-ui, it is almost always from another part of the tree (commonly Vite vs @vitejs/plugin-vue vs @tailwindcss/vite peer ranges), not because kilo-ui pulled a second Tailwind.

To hide warnings: npm install -D @lyda/kilo-ui --legacy-peer-deps
Or align Vite / plugin versions to what those plugins expect.

This package declares vue as the only peer dependency (Tailwind remains your app’s responsibility; see Prerequisites in docs). If styles or init fail, follow docs/docs/troubleshooting.md (also on the docs site under Configuration → Troubleshooting).

Use In A Project

From any Vue project:

After you publish this project to npm, install the exact name from its package.json (for example @lyda/kilo-ui).
Do not run npm install -D kilo-ui expecting this Vue CLI — the public npm name kilo-ui is already used by a different project.

npm install -D @lyda/kilo-ui@latest
npx kilo-ui add data-table

First install in a new project: the package postinstall runs kilo-ui init once (unless kilo.config.ts already exists). That creates kilo.config.ts in your app root (next to package.json) — not inside node_modules. Edit ui.componentsDir (or componentsPrefix) for the install folder (e.g. ki → src/components/ki/...). If the folder is not ui, kilo-ui add injects defineOptions({ name: "KiCardBox" }) so you can use <KiCardBox /> (prefix + file name). Use ui.componentTagPrefix: false to skip that. An annotated example ships at node_modules/@lyda/kilo-ui/config/kilo.config.example.ts. If install used --ignore-scripts, run npx kilo-ui init once yourself.

You can still run npx kilo-ui init anytime to add missing scaffold files; use init --force to reset kilo.config.ts to defaults (back up first if you customized it).

Note: The public npm name kilo-ui may point to a different project (not this Vue CLI). If npm install -D kilo-ui pulls SvelteKit or other wrong peers, use a scoped name or install from file: / Git. See Installation in the docs site.

What init Creates

npx kilo-ui init creates:

• kilo.config.ts — TypeScript project config (defineConfig from @lyda/kilo-ui/config), aliases, ui.componentsDir, and tailwind.css (path to your Tailwind root CSS file, default src/assets/base.css)
• Merged block in that CSS file — theme import from node_modules + @source for components/composables (no second stylesheet, no src/styles/kilo-ui.css)
• @lyda/kilo-ui/utils — shared cn() (no src/lib; default aliases.lib points at the package)
• env.d.ts (project root) — Vue + Vite types for *.vue (skipped if present); updates tsconfig paths for @/* when possible

init does not create src/components/ui until you run add.

In main.ts, import your Tailwind root once:

import './assets/base.css'

Your app should also have the normal Vue @ alias pointing to src. Most Vite Vue projects already do. If not, add this to vite.config.ts:

import { fileURLToPath, URL } from 'node:url'

resolve: {
  alias: {
    '@': fileURLToPath(new URL('./src', import.meta.url)),
  },
}

What add Creates

npx kilo-ui add data-table copies source into your app:

src/components/ui/data-table/DataTable.vue
src/composables/useSortedFilteredList.ts
src/types/teamwork-ui.ts

Then use it from your own source files:

<script setup lang="ts">
import DataTable from '@/components/ui/data-table/DataTable.vue'
import type { DataTableColumn } from '@/types/teamwork-ui'

type User = { id: string; name: string; email: string }

const columns: DataTableColumn<User>[] = [
  { key: 'name', label: 'Name', sortable: true },
  { key: 'email', label: 'Email', sortable: true },
]

const users: User[] = [
  { id: '1', name: 'Ashiba', email: '[email protected]' },
]
</script>

<template>
  <DataTable :columns="columns" :rows="users" />
</template>

Available Components

npx kilo-ui list

Current registry items:

• data-table - searchable, sortable CRUD table
• app-navbar - responsive web/mobile navbar
• activity-log - user/activity log

Customize

Because components are copied into the app, your team can edit them directly:

src/components/ui/data-table/DataTable.vue

Theme tokens ship in @lyda/kilo-ui/styles/twui-theme.css (merged into your Tailwind root by init). Override @theme in your own CSS after that @import.

Documentation Site

A shadcn-style docs site lives in docs/ and is built with VitePress.

npm install
npm run docs:dev      # http://localhost:5174
npm run docs:build    # static build in docs/.vitepress/dist
npm run docs:preview  # preview the production build

It includes:

• A landing page
• Get Started (Introduction, Installation, CLI, Theming)
• Components index + per-component pages with live preview, source tab, and props tables
• Live previews import directly from registry/ so docs and what the CLI ships never drift

Repository Layout

bin/             # The kilo-ui CLI (Node, zero-dep)
registry/        # Source-of-truth for components copied by the CLI
docs/            # VitePress docs site (mirrors ui.shadcn.com style)

Editing a component? Update the file in registry/. The CLI and docs both pick it up automatically.

Maintain this repo (publish)

Scripts (similar idea to larger libraries like PrimeVue: clear names):

| Script | What it does | |--------|----------------| | npm run dev | Docs site dev server | | npm run build | Docs production build | | npm run quality | typecheck + CLI smoke test | | npm publish | Runs prepublishOnly → quality before publish |

1. Create an npm account and log in: npm login

2. Use a scoped package name you control (recommended). The unscoped npm name kilo-ui is already taken by a different project.

3. Bump version when you ship changes: npm version patch (or minor / major)

4. From this repo root:

   npm publish --access public

   For a scoped public package: npm publish --access public
   For private paid npm org: npm publish --access restricted

5. Consumers install with:

   npm install -D @lyda/kilo-ui
   npx kilo-ui init
   npx kilo-ui add data-table

Note: This package only ships bin/, registry/, and README.md (files in package.json). Docs and devDependencies are not published. Host the docs site separately (npm run docs:build → upload docs/.vitepress/dist).