Installation

The package name is @gnosticai/ui. The shadcn namespace is @gnosticai. Registry commands copy Astro source into your project.

Generate a new site

From the gnostic-ui workspace, run:

pnpm generate --theme studio --out ../client-site
cd ../client-site
pnpm install
pnpm dev

The destination must be empty. Edit src/content/globals/site.json for shared copy. Add Markdown or JSON pages in src/content/pages. Set the production URL in astro.config.ts before deployment.

Add the registry to an existing site

Use Astro 6, Tailwind 4, and Node 22.12 or later. Add this components.json at the project root. If one already exists, merge the registry entry and keep your existing settings.

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "base-vega",
  "rsc": false,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "src/styles/global.css",
    "baseColor": "neutral",
    "cssVariables": true
  },
  "iconLibrary": "lucide",
  "aliases": {
    "components": "@/components",
    "ui": "@/components/ui",
    "utils": "@/lib/utils",
    "lib": "@/lib"
  },
  "registries": {
    "@gnosticai": "https://ui.gnosticai.com/r/{name}.json"
  }
}

Add the import alias to tsconfig.json:

{
  "extends": "astro/tsconfigs/strict",
  "compilerOptions": {
    "paths": { "@/*": ["./src/*"] }
  }
}

Items use explicit src targets. UI components install into src/components/ui/<name>/. Blocks install into src/components/blocks/<category>/. Relative imports preserve the source layout.

Set up Tailwind

pnpm dlx shadcn@latest add @gnosticai/astro-tailwind

This adds the base stylesheet and a small Astro integration. Review an existing stylesheet before accepting a replacement. Add the integration to your Astro config:

import { defineConfig } from "astro/config"
import gnosticTailwind from "./src/integrations/tailwind"

export default defineConfig({
  integrations: [gnosticTailwind()],
})

If your site already has the Tailwind Vite plugin, keep it and install @gnosticai/init instead. Do not enable Tailwind twice. Import src/styles/global.css once in your site layout.

Install components and blocks

pnpm dlx shadcn@latest add @gnosticai/button @gnosticai/card
pnpm dlx shadcn@latest add @gnosticai/hero-13

---
import { Button } from "@/components/ui/button"
import Hero from "@/components/blocks/hero/hero-13.astro"
---

Each item includes its required registry and npm dependencies. Install @gnosticai/ui for the base styles and all UI components. Use individual block names to keep the copied source small.

Themes and integrations

pnpm dlx shadcn@latest add @gnosticai/theme-earth
pnpm dlx shadcn@latest add @gnosticai/astro-seo
pnpm dlx shadcn@latest add @gnosticai/astro-cloudflare
pnpm dlx shadcn@latest add @gnosticai/theme-schema

A theme item adds CSS variables. It does not replace your page layout. The site generator uses theme block selections when it creates a new site. See the theme preview to compare colors.

The SEO and Cloudflare items install packages and print setup instructions. They do not replace an existing config. Static sites can use Cloudflare Worker assets without the server adapter.

For local registry tests, change the registry URL to http://127.0.0.1:4321/r/{name}.json. The production URL becomes usable after the registry is deployed.

Sidebar