Skip to main content

monorepo usage

Run the CLI inside a monorepo: workspace targeting, config inheritance, validation rules.

Workspace-aware CLI

When duck-ui.config.json has "monorepo": true, the CLI resolves the install target in this priority order:

  1. The --workspace flag, if passed - wins outright.
  2. Otherwise, the nearest parent directory (from your cwd, bounded by the config's workspace.root) containing a package.json - auto-detected.
  3. Otherwise, the workspace.project value stored in duck-ui.config.json - the default picked (or prompted for) during init.

The CLI validates that the target workspace has package.json (and, for init, tsconfig.json) before installing.

Examples

# Init monorepo (passing --workspace implies monorepo mode)
npx @gentleduck/cli init --workspace apps/web

# Add component to specific workspace
npx @gentleduck/cli add button --workspace apps/dashboard

# Update all in workspace
npx @gentleduck/cli update --all --workspace packages/ui

# Remove from a workspace
npx @gentleduck/cli remove sidebar --workspace apps/dashboard

Layout patterns

Single shared UI workspace

apps/
  web/
  dashboard/
  marketing/
packages/
  ui/        ← duck-ui.config.json here
    components/
    hooks/
duck-ui.config.json   { "monorepo": true, "workspace": "packages/ui" }

Run all CLI commands from the repo root. The CLI writes into packages/ui/components/... regardless of where you invoked it.

Per-app components

apps/
  web/
    components/        ← gets its own components
    duck-ui.config.json
  dashboard/
    components/        ← gets its own components
    duck-ui.config.json

CD into the app, run from there. Each duck-ui.config.json lives next to the components it controls.

Validation

Before installing, the CLI checks:

  • Target workspace exists
  • package.json is readable
  • tsconfig.json is present (the CLI doesn't try to write one)

Failing any check aborts with a clear error pointing at the missing file.

CI / scripted setups

# In a workspace bootstrap script
npx @gentleduck/cli init \
  --workspace packages/ui \
  --project-type VITE \
  --yes \
  --all

--yes skips every prompt. --all installs the full component catalog.