Getting Started

Prerequisites

Kosmesis expects a create-praxisjs-scaffolded project (the minimal, full, or router template all work) using Vite. If you don't have one yet:

npm create praxisjs@latest my-projectcd my-project

pnpm create praxisjs my-projectcd my-project

yarn create praxisjs my-projectcd my-project

bun create praxisjs my-projectcd my-project

Setup

Run `init`

From the root of your PraxisJS project:

npx kosmesis init

pnpm dlx kosmesis init

yarn dlx kosmesis init

bunx kosmesis init

This will:

Write a components.json config file.
Add @import "tailwindcss"; plus Kosmesis's theme tokens (--background, --foreground, --primary, ...) to your global stylesheet.
Wire the @tailwindcss/vite plugin into your vite.config.ts.
Create src/lib/utils.ts exporting a cn() helper (clsx + tailwind-merge).

Add a component

npx kosmesis add button

pnpm dlx kosmesis add button

yarn dlx kosmesis add button

bunx kosmesis add button

This copies button.tsx into src/components/ui/button.tsx. If the component wraps a Morphos primitive, its package (e.g. @morphos/inputs) is installed automatically.

Use it

import { Button } from "@/components/ui/button";

@Component()
class MyPage extends StatefulComponent {
  render() {
    return <Button variant="outline">Click me</Button>;
  }
}

@/components/ui/... assumes a @/* → ./src/* path alias in tsconfig.json. Add one if your create-praxisjs template doesn't already have it, or adjust the aliases in components.json to use relative imports instead.

Fetching from another registry

Every component so far came from components.json's default registry field (https://kosmesis.praxisjs.org/r). There are two ways to pull from somewhere else:

One-off, for a single add:

kosmesis add button --registry ./packages/registry/dist/r

Persistent, addressed by name: register a namespace once, then reference it directly whenever you add a component — no flag needed, and it works alongside the default registry in the same add call.

kosmesis registry add acme https://ui.acme.internal/r
kosmesis add @acme/button
kosmesis add @acme/button badge   # mixes a namespaced and a default-registry component

Command	What it does
`kosmesis registry add <namespace> <url>`	Saves `<url>` under `@<namespace>` in `components.json`, so `@<namespace>/<component>` resolves there from now on.
`kosmesis registry list`	Prints the default registry and every configured namespace.
`kosmesis registry remove <namespace>`	Forgets a namespace.

<url> (for both --registry and kosmesis registry add) can be a local directory (handy while developing components) or an http(s):// base serving the same <styleSystem>/<name>.json shape.

Whichever registry resolves a component is trusted at install time: its files are written to disk as-is and its dependencies are installed automatically. Only add a namespace, or pass --registry, for a registry you trust — the same way you'd only add an npm registry mirror you trust.

Want to serve your own components this way? See Custom Registry.

Updating a component

There's no update command — because there's no dependency to update. If a newer version of a component ships better defaults, re-run kosmesis add <component> and diff the result before overwriting your local copy (or just apply the change by hand).