Skip to content

Consumption Modes

Choose copy-first source you own or versioned runtime package imports.

@diffgazer/ui has two intended consumption modes.

Info:

npm packages: @diffgazer/add, @diffgazer/ui, and @diffgazer/keys are on npm. Copy-first mode runs through dgadd (pnpm add -D @diffgazer/add) or, with no package at all, through the hosted registry (npx shadcn add https://r.b4r7.dev/r/ui/<item>.json); runtime package mode is npm install @diffgazer/ui @diffgazer/keys — see the canonical Consumption Paths section.

Copy-first mode

Use copy-first mode when the consuming app should own and customize component source. Installing @diffgazer/add as a dev dependency is what puts dgadd on pnpm exec (Copy-first mode).

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

This mode copies component files, shared utilities, theme CSS, and optional standalone keyboard hooks into the app. The app owns future edits and reviews updates with:

bash
pnpm exec dgadd diff ui/button
pnpm exec dgadd add ui/button --overwrite

Prerequisites:

  • React >=19.2.0.
  • Tailwind CSS v4.
  • TypeScript and bundler/framework source alias such as @/* or ~/* configured before dgadd init.
  • Copied src/styles/styles.css imported from the app CSS entrypoint.

src/styles/styles.css is generated from the shared style seed plus registry component CSS. It is the copied-source equivalent of package-mode @diffgazer/ui/styles.css.

Runtime package mode

Use runtime package mode when you want versioned imports and do not need source customization.

Install both packages when using this path:

bash
npm install @diffgazer/ui @diffgazer/keys

Prerequisites:

  • React >=19.2.0.
  • Tailwind CSS v4.
  • @diffgazer/keys installed as a required peer.
  • Tailwind loads package source hints from the CSS file that imports Tailwind:
css
@import "tailwindcss";
@import "@diffgazer/ui/sources.css";
@import "@diffgazer/ui/styles.css";

Visible vs. hidden registry items

registry.json is the visible catalog of directly installable items. Items marked "hidden": true in their meta are internal dependencies (e.g. portal, shared primitives). They are not listed in the public registry index but install transitively when a visible item declares them in registryDependencies. The public registry.json served to consumers contains only visible items; hidden items keep per-item JSON files on disk so transitive resolution works, but they do not appear in dgadd list or npx shadcn add catalogs. The one exception is the hidden use-* keys shims (use-navigation, use-focus-restore, use-focus-trap, use-scroll-lock): the public-registry build inlines them into the consumers that need them and removes their per-item JSON, so they are not transitively resolvable and no item may declare them as a registryDependency.

Keyboard integration

Copy-first mode has two keyboard integration options:

  • --integration copy copies standalone hooks into the app.
  • --integration keys rewrites imports to the @diffgazer/keys package.

Runtime package mode always requires @diffgazer/keys because package entries can import keyboard hooks.

Support contract

During 0.x, public APIs can still change. Breaking changes require a changeset and migration notes. Runtime package consumers update with their package manager. Copy-first consumers compare and re-apply source updates manually.