Cubix
GitHub

Upgrade

Cubix components live in your repo. Updating means pulling a newer registry item with the CLI, reviewing the diff, and keeping the edits that belong to your product.

How updates work

Cubix is copy-paste ownership, not a runtime package of components. After cubix-ui add, the source under components/cubix is yours. When Cubix ships a fix or API improvement, you opt in by re-adding the same name from the registry.

  • CLI version - cubix-ui@latest (or a pinned version) fetches items and writes files.
  • Registry - default catalog is the public Cubix registry; override with CUBIX_REGISTRY_URL when you need a mirror or local public/r.
  • Base - updates follow cubix.json (base, aria, or radix). Pass --base to target another variant.

Update a component

Re-run add for the component. If the file already exists, the CLI asks before overwriting unless you pass --overwrite.

pnpm dlx cubix-ui@latest add button
pnpm dlx cubix-ui@latest add button --overwrite

Update several names in one pass when a changelog entry touches a set of related primitives:

pnpm dlx cubix-ui@latest add button dialog select --overwrite

Bases

Ready components ship for Base UI, React Aria, and Radix with the same visual API. Keep the base in cubix.json stable for day-to-day work. When you intentionally migrate a screen, re-add with --base and fix imports in that feature only.

pnpm dlx cubix-ui@latest add button --base aria

Do not mix bases inside one feature tree. Shared helpers under @/lib that the registry ships (except utils) update with the component that depends on them.

Pin the CLI when you need a known snapshot

For reproducible upgrades in CI or a release branch, pin the CLI version that matches the changelog entry you are applying:

pnpm dlx cubix-ui@0.1.4 add button --overwrite

Pair that with the Changelog so you know which components and packaging fixes landed in that release.

Safe merge checklist

Checklist
1. Commit or stash local edits under components/cubix before updating.
2. Re-add only the components you intend to refresh.
3. Diff the overwritten files - keep your product-specific changes.
4. Run your app build and smoke the touched screens (light, dark, RTL if you ship them).
5. Commit the registry refresh separately from unrelated app work.

Prefer small diffs. If you heavily customized a file, copy your variant aside, overwrite from the registry, then re-apply only the product-specific pieces (copy, layout, analytics hooks).

What not to expect

  • There is no automatic semver bump inside your app for component source - ownership means you choose when to pull.
  • Coming soon components are not in the installable registry yet. Wait for a ready release before adding them.
  • Switching bases is a migration, not a silent upgrade. Treat it like changing a dependency with a different compose API.

Next steps