Instruction file imported from rafoxme/uix (.cursor/rules/project.mdc). Copyright stays with the author.

rafox/ui project rules

Stack

• Turborepo + Bun workspaces monorepo.
• packages/ui (@rafox/ui): the shadcn-style SolidJS component registry. Source of truth for components, examples, charts, blocks, and styles.
• apps/v1 (@rafox/v1): Astro 7 docs site. SSR output server with the Cloudflare Workers adapter, SolidJS islands for demos.

Commands (run from the repo root)

• bun install — install all workspaces (Bun, Node 22+ engines enforced via bunfig.toml).
• bunx turbo dev — run the docs dev server.
• bunx turbo build — build the registry (shadcn build), then the docs site.
• bunx turbo lint — oxlint across all packages (Ultracite presets).
• bunx turbo test — vitest across all packages.
• bunx turbo format — oxfmt write in place; bun run format:check --filter <pkg> to verify.
• bunx turbo typecheck — tsc --noEmit for the ui package, astro check for v1.
• bunx turbo deploy — rebuild and deploy the docs Worker via Wrangler.

Conventions

• Imports: components use @/ → packages/ui/src (shadcn convention, do not change). Docs app code uses @docs/ → apps/v1/src. Never import @/ inside apps/v1.
• Styling: Tailwind CSS v4. Components use class= (Solid), never className. Use the cn() helper from @/lib/utils for conditional classes.
• Solid primitives: use createSignal, createMemo, createEffect, Show, For, Switch/Match, createContext, onCleanup. Keep imports to the fewest possible.
• Registry: every new component needs an entry in packages/ui/src/registry/kobalte/registry.json plus a demo in packages/ui/src/registry/kobalte/examples/ui/. Register with registry:ui, source type only. Regenerate with bun run r-build --filter @rafox/ui.
• Registry URLs: registry dependency links use https://rafox-ui.pages.dev/r/kobalte/<name>.json. Never point at the old zaidan domain.
• Site URL: the site base URL comes from PUBLIC_SITE in apps/v1/.env — never hardcode it in pages or astro.config.ts.
• Naming: kebab-case for file names of non-component modules and registry item names; PascalCase for component files is allowed (ultracite's filename-case is disabled for that reason).
• Lint: never silence individual lines with // biome-ignore/// eslint-disable. If a rule is wrong for the whole repo, disable it in oxlint.config.ts with a comment.
• Formatting: oxfmt, printWidth 100, double quotes, trailing commas. Never reformat files unrelated to your change.
• No comments in code unless they explain a non-obvious decision.
• Tests: co-locate *.test.ts next to the module (vitest). Test utilities, cn, theme helpers, and registry helpers.

Astro specifics

• Pages live in apps/v1/src/pages. Framework components must be imported in the frontmatter (---) to be usable as islands. client:only="solid" is required for Solid demos.
• apps/v1/src/lib/registry.ts imports registry.json as a module (bundled) — do not switch back to fs reads, they break on Cloudflare Workers.
• After changing the registry, run bun run apps/v1/scripts/sync-registry.ts (or the docs build) to refresh apps/v1/public/r.