Install in an app outside the repository

This page shows how to use @werft-ai/ui in a React app outside this repository. You build the package in the repository, pack it into a tarball, and npm install that file in the app. The app does not need Tailwind.

Make the tarballCopy Anchor Link

Run these at the repository root. You need the Bun the repository pins, 1.3.14 (packageManager in the root package.json), and npm.

bun install
bun run --cwd packages/ui build:package
npm pack ./packages/ui/dist

build:package writes the built JavaScript and type declarations, the CSS, a package.json for distribution, and LICENSE into packages/ui/dist. npm pack packs that directory into werft-ai-ui-<version>.tgz in the current directory. The version is the version in packages/ui/package.json.

Install it in an appCopy Anchor Link

The example is a Vite + React + TypeScript app. If you do not have one, create it with npm create vite@latest my-app -- --template react-ts.

@werft-ai/ui takes react and react-dom ^19.3.0 as peer dependencies. If the app's React is older, upgrade it first, then install the tarball you made.

npm install react@^19.3.0 react-dom@^19.3.0
npm install <path to the repository>/werft-ai-ui-0.0.0.tgz

Radix, class-variance-authority, clsx, tailwind-merge, and lucide-react are dependencies of the package and are installed with it.

Import the CSSCopy Anchor Link

Import the prebuilt styles.css once. It holds the tokens, the rules for the kit's elements, and the utility classes the kit uses, so the components render without Tailwind.

import "@werft-ai/ui/styles.css";
import { Button, Card } from "@werft-ai/ui";

styles.css does not include Tailwind's preflight (its global reset). It sets one global rule: every element's default border-color is --werft-color-border, so an element the app gives a border-width and border-style but no colour draws in that colour (the border shorthand sets a colour too, so it is not affected). The resets the kit expects (borders, margins, button backgrounds, link underlines, and so on) apply only to the kit's elements and what is inside them, at zero specificity. App markup you put inside a kit component also loses the browser's default margins and underlines. The kit's rules sit in a cascade layer, so the app's CSS outside any layer always wins.

Tailwind v4 appsCopy Anchor Link

To use the kit's utility names (bg-primary, text-control, rounded-control, and others) in the app's own markup, import theme.css after styles.css in the app's CSS. theme.css connects the tokens to Tailwind utilities.

@import "tailwindcss";
@import "@werft-ai/ui/styles.css";
@import "@werft-ai/ui/theme.css";

The classes the kit's components use are already in styles.css, so you do not need to scan node_modules with @source.

FontsCopy Anchor Link

The package ships no fonts. The font lists live in --werft-font-sans (Geist, then Pretendard Variable) and --werft-font-mono (Geist Mono first), but styles.css applies them only to the kit's werft-* elements. Controls such as buttons and segmented controls inherit the app's font, so if the app sets no font on body (or :root), they render in the browser's default font, usually a serif such as Times. Put one line in the app's CSS:

body { font-family: var(--werft-font-sans); }

With it, text falls back to the system fonts at the end of the list even when the app loads neither Geist nor Pretendard. To show Hangul in Pretendard, the app loads it itself. This repository's web console uses the dynamic subset from the pretendard package.

npm install pretendard

import "pretendard/dist/web/variable/pretendardvariable-dynamic-subset.css";

ThemeCopy Anchor Link

Light is the default. Turning on the dark theme works the same as in Apply the theme.

Import pathsCopy Anchor Link

Next stepsCopy Anchor Link

• Apply the theme: the dark theme and the override rules