@nectary/react

CLI that copies React wrappers for Nectary web components into your project, the same way shadcn/ui does: you own the code and can edit it.

Quickstart

npx @nectary/react init          # nectary.json, src/ui/, theme, AGENTS.md
npx @nectary/react add button    # copies src/ui/Button/

import '@nectary/theme-base'                 // once, at the app root
import { Button } from '@ui/Button'          // needs the @ui/* → src/ui/* alias

<div className="nectary-theme-base">
  <Button text="Save" aria-label="Save" type="primary" />
</div>

To set up the @ui alias for TypeScript and Vite, see the Getting started guide.

Requires Node ^18.19.0 or >=20.5.0. init installs react, @nectary/components and the chosen theme if they're missing.

Commands

| Command | What it does | | --- | --- | | init [-y] [--no-agents] | Creates nectary.json, the components folder and .nectary/lock.json, installs dependencies, and writes AI agent instructions | | add <names...> | Copies components (--atoms, --compositions, --all, --path, --overwrite) | | list | Lists the registry (--atoms, --compositions, --installed, --outdated) | | view <name> [--md] | Shows the description, import, props and files. --md prints the full Markdown reference | | diff [name] | Shows your local edits against the installed registry version | | update [name] [-f] | Pulls newer registry versions | | agents | Re-writes the AI agent instructions and components catalog |

Files go to src/ui/ by default. Set componentsPath in nectary.json to change it.

Using with AI coding agents

The CLI gives agents layered context, so they reuse these components instead of generating new ones:

1. AGENTS.md: init (and agents) adds a short managed block between <!-- nectary:start --> and <!-- nectary:end -->. It tells agents to check the catalog, import from @ui/*, and run npx nectary add rather than hand-rolling UI. Content outside the markers is never touched. Claude Code users can add @AGENTS.md to their CLAUDE.md.
2. src/ui/README.md: an auto-generated catalog of installed components (with their import lines) and the components available to add. It is regenerated on add and update.
3. Per-component reference: npx nectary view <name> --md, or node_modules/@nectary/react/dist/llms/<name>.md offline. Each covers props, an import line and an example.
4. Web: the docs site serves /llms.txt (an index) and /llms-full.txt (everything).

More

• Getting started guide: alias setup, themes, workflow
• Component docs: npm run docs (http://localhost:6006)
• CONTRIBUTING.md: development, sync-check, publishing, adding a composition