Setup

Get a token

The registry is private, so shadcn needs credentials.

Create a GitHub token

Create a personal access token with read access to ilovehugetits/9am-ui.

Export it

Add it to your shell profile so it survives a reboot.

export NINEAM_UI_TOKEN=github_pat_xxxxxxxx

Never commit the token. components.json references it as ${NINEAM_UI_TOKEN} and shadcn expands it at install time, so the file itself stays safe to check in.

Point a script at the registry

Add a registries block to your script’s web/components.json:

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": false,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "src/index.css",
    "baseColor": "neutral",
    "cssVariables": true,
    "prefix": ""
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "registries": {
    "@9am": {
      "url": "https://raw.githubusercontent.com/ilovehugetits/9am-ui/main/r/{name}.json",
      "headers": {
        "Authorization": "Bearer ${NINEAM_UI_TOKEN}"
      }
    }
  },
  "iconLibrary": "lucide"
}

Items are served straight off raw.githubusercontent.com, so there is nothing to host and no npm registry to authenticate against.

Start a new script

Create the web project

mkdir -p my-script/web && cd my-script/web
bun init -y

Then add the components.json shown above.

Install the scaffold

bunx shadcn@latest add @9am/scaffold

This writes vite.config.ts, tsconfig.json, eslint.config.js, postcss.config.js, index.html, src/main.tsx, and a starter src/components/App.tsx — and pulls in the theme, fonts, NUI bridge, i18n, viewport, and the icons the starter uses.

Add the Lua half

cd .. && bun <path-to-9am-ui>/cli/index.ts lua

Writes fxmanifest.lua, client/nui.lua, shared/locale.lua, and locales/en.json into the resource root. Existing files are skipped unless you pass --force.

This step is not a registry item because shadcn rejects any install target containing .., and the Lua files belong one level above the web project.

Configure the script

Edit web/src/nui.config.ts — this is the one kit file you are meant to change.

export const nuiConfig = {
  resourceName: "my-script",
  themeStorageKey: "my-script:theme",
  defaultTheme: "dark",
} as const;

Keep the localStorage key in index.html in sync with themeStorageKey. It runs before first paint to stop the wrong theme flashing.

Build and verify

bun install
bun run build
bun src/scripts/9am-ui.mjs doctor

Add the kit to an existing script

Add the registries block, then take only what you want:

bunx shadcn@latest add @9am/theme @9am/fonts
bunx shadcn@latest add @9am/viewport @9am/data-table

Dependencies resolve transitively. Asking for @9am/data-table also installs button, input, table, i18n, and its three icons — and nothing else, so a script that only wants a button does not pull in charts. After adding the theme, import it from your entry stylesheet. Order matters:

@import "tailwindcss";
@import "tw-animate-css";

@import "./styles/9am-fonts.css";
@import "./styles/9am-theme.css";

/* your script's own styles go below */

Where files land

Item type	Destination
Primitives and icons	`src/components/ui/`
`@9am/utils`, `@9am/smooth-scroll`	`src/lib/`
`useNuiEvent`, `useTheme`	`src/hooks/`
`fetchNui`, `misc`, `debugData`	`src/utils/`
`VisibilityProvider`	`src/providers/`
`@9am/i18n`	`src/i18n/`
`@9am/theme`, `@9am/fonts`	`src/styles/`
`@9am/nui` config	`src/nui.config.ts`
`@9am/tools`	`src/scripts/9am-ui.mjs`

Recommended package scripts

{
  "scripts": {
    "start": "vite",
    "start:game": "vite build --watch",
    "build": "tsc && vite build",
    "production-build": "tsc && vite build --mode prod",
    "lint": "eslint src",
    "ui:check": "bun src/scripts/9am-ui.mjs check",
    "ui:doctor": "bun src/scripts/9am-ui.mjs doctor"
  }
}

Command	Use it for
`bun run start`	Browser-only development with mock data. Fastest loop for UI work.
`bun run start:game`	Rebuilds `dist` on save. Restart the resource to reload the NUI.
`bun run build`	Required before testing in-game — `web/dist` is gitignored.
`bun run production-build`	Customer-ready build with dev seeds and console noise stripped.

Get Started

Scripts

UI Kit

Get a token

Point a script at the registry

Start a new script

Add the kit to an existing script

Where files land

Recommended package scripts

​Get a token

​Point a script at the registry

​Start a new script

​Add the kit to an existing script

​Where files land

​Recommended package scripts

Get a token

Point a script at the registry

Start a new script

Add the kit to an existing script

Where files land

Recommended package scripts