Upgrade guide

Proper UI is at v0.1.0 and has not had a public release yet, so there is no migration history to document. This page explains how versioning works today and how you'll update once releases start shipping.

Versioning

@properui/ui and the properui CLI are versioned and released independently, each following semantic versioning. Releases are managed with Changesets: a change lands with a changeset describing its impact (patch, minor, or major), and publishing the release regenerates the changelog from those changesets.

While the project is on 0.x, any release may include a breaking change — semver doesn't promise stability below 1.0.0. Once @properui/ui reaches 1.0.0, breaking changes will only ship in a major-version bump, and this page will gain a ## vX.Y.Z section for each one, documenting exactly what changed and how to adapt.

Updating the npm package

If your project depends on @properui/ui as an npm package, update it the normal way:

npm install @properui/ui@latest

Or your package manager's equivalent (pnpm up @properui/ui, yarn up @properui/ui). Check the package's published release notes before upgrading across a major version.

Updating components you've copied in

The CLI copies component source directly into your project, so there's no dependency version to bump for those files — you update them by pulling in the current registry version. Start with diff to see what changed:

npx @properui/cli@latest diff              # every installed component
npx @properui/cli@latest diff button       # just one

diff compares your local files against the current registry version and shows exactly what's different, so you can decide whether to merge the change by hand or take the upstream file as-is. To take it as-is, re-run add with --overwrite:

npx @properui/cli@latest add button --overwrite

--overwrite replaces the local file entirely — it doesn't merge. Review the diff output first if you've customized the component, or you'll lose those edits.

What to expect from a future breaking change

There's no upgrade or migrate command today, and this page won't describe one until it ships. diff and add --overwrite are the tools available now for pulling changes into components you've already copied in. When the first breaking change lands:

• It will be documented here under a new ## vX.Y.Z heading, naming the specific class, prop, or structural change and how to update your code.
• diff will show you exactly which of your files are affected, since it always compares against the current registry content.
• For any file you haven't customized, add --overwrite will bring it fully up to date in one step.

FAQs