Get started

Pick the workflow that matches how you build.

Swirski UI can act like a regular component library, a source-copy CLI, or a shadcn-compatible registry. The components are the same design language; the install workflow changes how much ownership you want.

Short version

Package for speed. Swirski CLI for full source ownership. shadcn registry when your app already uses shadcn.

Platforms

Web and native live in the same package.

Most of the docs show the web components from @swirski/ui. React Native apps use @swirski/ui/native and the native setup helper for bundled fonts.

Native setup

Web

React and Next.js apps

Import CSS once, then use the full web component library from @swirski/ui.

import "@swirski/ui/styles.css";
import { Button, Card, Title } from "@swirski/ui";

Native

React Native apps

Use the native entrypoint and run the setup helper once so bundled fonts match the web package.

pnpm exec swirski-native setup

import { Button, Card, Title } from "@swirski/ui/native";

Workflow 01

Install as a component library.

This is the easiest path for most users. You get typed React components, package updates, and the least setup.

01
Install the package
This gives you the complete component library from the @swirski/ui package.
```
pnpm add @swirski/ui
```
02
Import the styles once
Add the stylesheet in your app entry, root layout, or global CSS setup.
```
import "@swirski/ui/styles.css";
```

Use components

Import the pieces you need and compose them like any other React component library.

import { Button, Card, CardContent, Title } from "@swirski/ui";

export default function Page() {
  return (
    <Card>
      <CardContent>
        <Title order={2} size="h3">Build loud.</Title>
        <Button>Start</Button>
      </CardContent>
    </Card>
  );
}

Workflow 02

Copy source with the Swirski CLI.

This is for teams that like the shadcn idea but want Swirski's own registry and simple copy command. The source lands in your project and becomes yours.

01
Install the Swirski CLI
The CLI copies component source into your app instead of importing it from node_modules.
```
pnpm add -D @swirski/cli
```
02
Create a config
The config tells the CLI where copied component folders should go.
```
pnpm exec swirski init
```

Copy one or many

Add a single item, a small set, or the entire local registry.

pnpm exec swirski add button
pnpm exec swirski add button card dialog
pnpm exec swirski add --all

Workflow 03

Install from the shadcn-compatible registry.

This is for projects that already use shadcn. Swirski publishes registry item JSON at ui.swirski.dev so the shadcn CLI can view and add individual items.

01
Preview a registry item
Use view when you want to inspect what the shadcn CLI will install.
```
pnpm dlx shadcn@latest view https://ui.swirski.dev/r/button.json
```
02
Install one item
Pass the hosted Swirski registry item URL to shadcn add.
```
pnpm dlx shadcn@latest add https://ui.swirski.dev/r/button.json
```

Install several items

shadcn can add multiple registry items in one command. For a full source copy, Swirski CLI also supports add --all.

pnpm dlx shadcn@latest add \
  https://ui.swirski.dev/r/button.json \
  https://ui.swirski.dev/r/card.json \
  https://ui.swirski.dev/r/dialog.json

Need a rule of thumb?

Start with the package. Switch to copy workflows when you need ownership.

Less technical users can treat Swirski like a normal UI package. More technical users can copy components through Swirski CLI or shadcn and edit the source directly.

Browse components CLI and registry