Installation

Configure an app's components.json, install the foundations, and turn on the drift check.

Requirements

Next.js 16 with the App Router and React 19;
Tailwind CSS 4 through @tailwindcss/postcss;
TypeScript with an @/* path alias;
Bun, which runs the drift check script.

1. Add components.json

nalarx-frontend has no components.json yet. Add one next to each app's package.json (apps/web, apps/admin):

components.json

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "src/app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true,
    "prefix": ""
  },
  "aliases": {
    "components": "@/components",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks",
    "utils": "@/lib/cn"
  },
  "registries": {
    "@nalarx": "https://<registry-host>/r/{name}.json"
  }
}

Items install into src/components/ui/nx/ and import each other relatively, so they do not depend on these aliases. Keep them anyway: the shadcn CLI needs them, and the app's own @/lib/cn stays where it is.

The registry host is not decided yet. Until it is, use one of these:

Source	`@nalarx` value
This repo running locally (`bun run dev`)	`http://localhost:3000/r/{name}.json`
A pinned release on GitHub (private repo)	`{ "url": "https://raw.githubusercontent.com/<org>/nalarx-ui/<tag>/public/r/{name}.json", "headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" } }`

Items name each other as @nalarx/<item>, so changing this one line moves every install to another host or release. See Versioning for pinning.

2. Install the foundations

bunx shadcn@latest add @nalarx/theme @nalarx/base @nalarx/drift-check

This writes:

File	From
`src/styles/nalarx-ui/tokens.css`	`theme`
`src/styles/nalarx-ui/nx.css`	`base`
`src/components/ui/nx/lib/cn.ts`	`base`
`scripts/nalarx-ui-drift.ts`	`drift-check`

It also adds clsx and tailwind-merge if the app does not have them.

3. Import the styles

Import both files right after Tailwind in the app's global stylesheet, theme first:

src/app/globals.css

@import "tailwindcss";
@import "../styles/nalarx-ui/tokens.css";
@import "../styles/nalarx-ui/nx.css";

In nalarx-frontend these two files replace the token blocks, the @theme inline bridge and the shared nx-* rules in globals.css. Deprecated aliases (--danger, --success, --warning, --bg-2, --bg-alt, --bg-elevated, --ink-1), chart tokens and screen-specific rules stay in the app.

4. Load the fonts

The theme names the fonts but does not load them. Load them the way apps/web does, with next/font writing the same variables:

src/app/layout.tsx

import { Manrope } from "next/font/google";

const manrope = Manrope({
  subsets: ["latin"],
  weight: ["300", "400", "500", "600", "700"],
  variable: "--font-sans",
  display: "swap",
});

// <html className={manrope.variable}>

--font-mono is Manrope on purpose; use .tnum or tabular-nums for numbers. The display role reads --font-plex-serif (IBM Plex Serif 300), and --font-serif is Instrument Serif.

5. Record and check

bun scripts/nalarx-ui-drift.ts record theme base drift-check
bun scripts/nalarx-ui-drift.ts check

Run the formatter before record, so the recorded fingerprints match the files you commit. Commit nalarx-ui.lock.json and add the check to CI:

- run: bun scripts/nalarx-ui-drift.ts check

Agent skill

Coding agents install and integrate items with the nalarx-ui skill in skills/nalarx-ui/ of this repo.

RequirementsCopy Anchor Link

1. Add components.jsonCopy Anchor Link

2. Install the foundationsCopy Anchor Link

3. Import the stylesCopy Anchor Link

4. Load the fontsCopy Anchor Link

5. Record and checkCopy Anchor Link

Agent skillCopy Anchor Link