@nectary/react

CLI to add Nectary compositions (higher-order React components built on @nectary/components) directly into your project. Same “copy source into your repo” approach as Shadcn UI — you own the code and can edit it.

Prerequisites

• Node ^18.19.0 or >=20.5.0
• A project with @nectary/components installed

Usage

List compositions

npx @nectary/react list

View a composition

npx @nectary/react view <name>

Add a composition

npx @nectary/react add <name>

Examples:

npx @nectary/react add button
npx @nectary/react add select
npx @nectary/react add phone-input
npx @nectary/react add table

Files are written under src/components/nectary/ by default. The CLI also installs any npm dependencies required by the composition.

Options

• --path <path> – Override the output directory (default: src/components/nectary).
• --overwrite – Replace existing files. Without this, existing files are skipped.

Configuration

Optional nectary.json at your project root:

{
  "componentsPath": "src/components/nectary"
}

Development

npm install
npm run build
npm test
npm run docs

Docs live under docs/latest/src/pages/react/ using the same MDX + examples/*.tsx?example conventions as the Nectary components docs site. Local preview is a lightweight Vite app (npm run docs, port 6006).

Keeping wrappers in sync with @nectary/components

Sync is drift detection, not codegen. Manual wrapper fixes must not be overwritten.

NECTARY_COMPONENTS_DIR=../components/components npm run sync:check
# optional machine-readable output:
NECTARY_COMPONENTS_DIR=../components/components npm run sync:check -- --json

The check compares each mapped registry item’s *Props to the matching WC types.ts (TSinch*Props / TSinch*Events). It reports:

• New upstream components with no wrapper yet
• Prop/event add, remove, or type change
• Orphan wrappers with no upstream WC

Exit 0 if clean, 1 on actionable drift, 2 on tool errors (missing checkout — npm @nectary/components does not ship types.ts). Parts (e.g. accordion-item) and registry items with category: "composition" (plus select / phone-input / …) are listed as info; prop/event diffs run for atoms only.

When the report flags something: update the registry wrapper (and docs) by hand, or add a new registry/<name>/ entry. Do not run build:wrappers to “sync” — that scaffold script can overwrite existing files.

Optional scaffolding only (destructive for generated: true items):

NECTARY_COMPONENTS_DIR=../components/components npm run build:wrappers

CI runs sync-check on schedules and as a manual web-pipeline job (clones the components repo).

Merging docs into the components repository

1. Copy docs/latest/src/pages/react/** into components/docs/latest/src/pages/react/.
2. In docs/latest/src/entries.ts, add a reactReq scanner (same pattern as componentReq) with routes /react/{name}/{tab}.
3. Export getReactRoutes from the docs bootstrap and add a single React components sidebar group in the shell ComponentsList (do not split atoms/compositions).
4. Add a webpack/tsconfig alias @ui/* → your components path (default src/ui/*), matching consumer projects after nectary init / nectary add.

Page folders use 01-Examples.mdx and examples/{Basename}.tsx exporting {Basename}Example, so they drop into the existing discovery model without a routes table.

Publishing

Releases use semantic-release with Conventional Commits, same model as the Nectary components monorepo.

| Prefix | Release | Example | | --- | --- | --- | | feat: ... | minor | feat: add sheet composition | | fix: ... | patch | fix: skip overwrite without flag | | BREAKING CHANGE: in body/footer | major | — | | chore, docs, refactor, test, ci | none | — |

On main, the GitLab pipeline runs npm run release, which publishes @nectary/react to npm when the commit history warrants a new version. MRs run npm run dry-run only.

Required CI variables: NPM_TOKEN, CI_GIT_PUSH_TOKEN (or GITLAB_TOKEN for @semantic-release/gitlab).

Adding a composition

1. Add source under registry/<name>/.
2. Register it in registry.json (name, description, dependencies, files).
3. Run npm run build (writes dist/registry/<name>.json).
4. Add or update docs/latest/src/pages/react/{PascalName}/ examples.
5. Merge a conventional commit to main so semantic-release publishes.