Skip to content

Consumption Modes

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

@diffgazer/ui has two intended consumption modes.

Info:

Before publication: Diffgazer packages are not yet published to npm, so neither mode installs from the public registry yet. Pack the workspace packages from a checkout and install those tarballs in the target app — see the canonical Consumption Paths section.

Copy-first mode

Use copy-first mode when the consuming app should own and customize component source. Before publication, the packed @diffgazer/add tarball installed in the target app is what puts dgadd on pnpm exec (Copy-first mode procedure).

bash
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. Before publication, pack them from a checkout of the repository and install the tarballs:

bash
pnpm --filter @diffgazer/keys pack --pack-destination /tmp/diffgazer-packs
pnpm --filter @diffgazer/ui pack --pack-destination /tmp/diffgazer-packs
bash
npm install /tmp/diffgazer-packs/diffgazer-ui-*.tgz /tmp/diffgazer-packs/diffgazer-keys-*.tgz

After publication, this becomes:

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.