Skip to content

Installation

Initialize a project with dgadd and add @diffgazer/ui components as source.

@diffgazer/ui components install as source files. dgadd copies components and optional @diffgazer/keys hooks into your app and tracks them for later updates.

Info:

Installing via dgadd: Components are namespaced (ui/button, ui/dialog). For the full command and flag reference — init, add, list, diff, remove — see the dgadd CLI reference.

Info:

npm packages: @diffgazer/add is on npm. pnpm add -D @diffgazer/add puts dgadd on pnpm exec, and npx @diffgazer/add <command> runs it without the install. Components also install without dgadd from the hosted registry: npx shadcn add https://r.b4r7.dev/r/ui/<item>.json.

Install

Add @diffgazer/add as a dev dependency, then run the installer and add a component:

bash
pnpm add -D @diffgazer/add
pnpm exec dgadd init
pnpm exec dgadd add ui/button

The one-shot pnpm dlx/npx @diffgazer/add commands do the same without the dev dependency — see Package managers.

Setup

01.

Install Tailwind CSS

@diffgazer/ui source expects Tailwind CSS 4. Install and configure Tailwind before running dgadd init, then import the copied style entry after init writes it.

css
@import "tailwindcss";

See Tailwind Setup for framework-specific details.

02.

Configure a source alias

dgadd init requires a TypeScript or Vite source alias such as @/* or ~/*. It rejects projects without one unless --allow-missing-alias is passed for an app whose tooling already resolves source aliases.

Add the alias to TypeScript:

json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

For Vite, mirror the same alias in vite.config.ts:

ts
import { resolve } from "node:path"
import { defineConfig } from "vite"

export default defineConfig({
  resolve: {
    alias: {
      "@": resolve(__dirname, "./src"),
    },
  },
})

See TypeScript for framework-specific details.

03.

Initialize

With dgadd available and the source alias in place, run init once and add a component:

bash
pnpm exec dgadd init
pnpm exec dgadd add ui/button

This creates diffgazer.json, records the aliases dgadd uses, creates install directories, writes src/lib/utils.ts, and copies src/styles/theme.css plus src/styles/styles.css. It does not edit your TypeScript config, bundler config, or app CSS entrypoint.

04.

Import the component CSS

Import the copied Tailwind/theme entry from your app CSS:

css
@import "tailwindcss";
@import "./styles/styles.css";
05.

Add components

Add components by namespaced item name. Bare names are rejected:

bash
pnpm exec dgadd add ui/dialog ui/tabs ui/menu

Keyboard hooks

Standalone hooks can be copied directly:

bash
pnpm exec dgadd add keys/navigation keys/focus-trap keys/focus-restore keys/scroll-lock

Components with keyboard behavior choose copy mode or package mode:

bash
pnpm exec dgadd add ui/menu --integration copy
pnpm exec dgadd add ui/menu --integration keys

copy installs local hook source. keys imports hooks from @diffgazer/keys.

Package managers

@diffgazer/add is on npm, so the one-shot form works with every package manager:

bash
pnpm dlx @diffgazer/add init
npx @diffgazer/add init
yarn dlx @diffgazer/add init
bunx @diffgazer/add init

Result

After adding ui/menu --integration copy, a typical project looks like this:

text
src/
  components/
    ui/
      menu/
        menu.tsx
        menu-item.tsx
        index.ts
  hooks/
    use-navigation.ts
    utils/
      navigation-dispatch.ts
  lib/
    utils.ts
  styles/
    styles.css
    theme.css
diffgazer.json

See Tailwind Setup for theme configuration.