Upgrading

Overview

Copied source is a trade. You get to change any line, you are never broken by an update you did not ask for, and no dependency can alter your interface between two deploys. In exchange, improvements do not arrive on their own, and taking one means merging into code you may have edited.

That trade is a good one for a health interface, where an unreviewed change to how a clinical status renders is a genuine hazard. But it only holds if upgrading is survivable, and this page is how opsinjs intends to make it so.

See what changed before you change anything

npx shadcn@latest diff @opsinjs/result-card

npx shadcn@latest add @opsinjs/result-card --dry-run

Merge deliberately

Three approaches, in the order you should prefer them.

You have not edited the file. Overwrite it. Check the diff, take the new version, run your tests. This is the common case and it takes a minute.

You have edited it lightly. Take the new version and re-apply your edits on top, rather than hand-picking hunks out of the update. Re-applying a small, known change to new code is more reliable than reasoning about a merge. It also makes you re-justify the edit, which is often useful on its own.

You have edited it heavily. Treat it as a three-way merge between the version you started from, your current file, and the new one. Nothing in the file tells you the first of those three, so that base comes from your own version control: commit the files shadcn add writes, in their own commit, so a later --diff has something to compare against.

If you find yourself doing a heavy merge repeatedly on the same component, the divergence is telling you something. Either your change belongs upstream, or your component has become a different component. In the first case, propose it. In the second, the component should stop pretending to be an opsinjs one.

Treat generated files as generated

Two things in your project are not yours to edit, and editing them is the main avoidable source of upgrade pain:

• The token layer (opsinjs.css). Replace it wholesale on every upgrade. Your extensions belong in your own @theme block after it. See Adding your own tokens.
• Anything carrying a generated-file header. If a file says it is generated, an upgrade will overwrite it, and the polite warning in the header is the only notice you get.

Verify it worked

1. Your tests pass, especially any that assert on rendered clinical status.
2. Nothing in your own code was silently rewritten. Read the diff of the whole commit, not just the component file.
3. The token layer still resolves. An upgraded component may read a token that an older token layer does not define. Upgrade both together.
4. The greyscale check still passes. A visual change that quietly makes status colour-only is exactly the kind of regression an upgrade can introduce and a test suite will not catch.
5. You have recorded which version you took, in the commit message or the pull request. Nothing in the file records it for you.

Troubleshooting

A component references a token that does not exist. The component and the token layer are from different versions. Upgrade the token layer.

The diff is enormous and you did not edit the file. This is formatting drift. A different Prettier configuration reformatted it on the way in. Normalise before comparing, or the real change will be invisible inside the noise.

Your edits are gone. The upgrade overwrote them. This is why the dry run and the diff come first; recover from version control, then re-apply on top.

You cannot tell which version you have. There is no stamp in the file to look at. Emitting one is specified and not built. Fall back to version control: find the commit that added or last updated the file and read the date, then diff against the registry to see how far apart you are. If that is hopeless, take the current version cleanly and record it this time.

Next

• Versioning policy says what semver covers here, which is more than you expect.
• Upgrades and diffs covers the registry-side mechanics.