Docs

Versions & upgrading

Every version of every component is kept forever and stays installable. The subscription's job is making that easy to use: grab a component now, and later hot-swap it for whatever version you actually want — a newer one, an older one, it doesn't matter — without re-doing the install by hand.

Every version is archived, not just "latest"

Publishing a new version of a component never deletes the old one. Pin an exact version with <slug>@<version>:

bash

velocityx add aspect-ratio-box@1.0.0

See what's actually available for a slug — every version, and its access level — with info:

bash

velocityx info aspect-ratio-box

bash

Aspect-Ratio Media Box  (aspect-ratio-box)
Reserves a stable aspect ratio for media to prevent layout shift, using the native CSS aspect-ratio property.
Category: Bento & Layout    Framework: astro
Demo: https://aidxn.com/components/aspect-ratio-box

Versions
  2.0.0  paid   (current)
  1.0.0  free

Install:            velocityx add aspect-ratio-box
Install a version:  velocityx add aspect-ratio-box@<version>

On a component's own page, the same data shows up as a version picker whenever a slug has more than one version — today that's just aspect-ratio-box, switching between its entry regenerates the install command for whichever version is selected.

Free and paid are set per version, not per component

This is the part most likely to catch you out: a single component can have a free version and a paid version at the same time. aspect-ratio-box is the real example — v1.0.0 is free and MIT licensed, v2.0.0 is on the subscription. A free version installs with no account and no licence key:

bash

velocityx add aspect-ratio-box@1.0.0

and the paid version asks for one, same as any other subscription component:

bash

velocityx add aspect-ratio-box@2.0.0

MIT cannot be revoked. A version published free stays free forever — publishing a paid v2 later doesn't reach back and lock v1. If you installed aspect-ratio-box v1.0.0 before ever subscribing, that file is yours permanently, subscription or not.

Upgrading

upgrade hot-swaps an already-installed component for a different version. Omit the slug to check every component the lockfile knows about; name one to check just that one; pin an exact target the same way add does.

bash

velocityx upgrade
velocityx upgrade aspect-ratio-box
velocityx upgrade aspect-ratio-box@1.0.0

That third one is a genuine downgrade — v2.0.0 back to v1.0.0 — and it works. Keeping every version archived is half the point: if a newer version doesn't fit, pin back to a known-good one instead of being stuck.

Always safe to run first — --dry-run previews the whole thing and writes nothing:

bash

velocityx upgrade --dry-run

Your edits are safe by default

If a file has changed on disk since it was installed — the lockfile hash no longer matches — upgrade refuses rather than overwriting it, because you own the installed source the moment it lands:

bash

Refusing to overwrite — your edits would be lost.
Re-run with --force to overwrite anyway (your local edits WILL be lost), or merge by hand.

--force overrides it, and says exactly that before it does — edits will be lost, not "may" be.

The migration note

Every upgrade prints a note before writing anything: the version jump, what props were added, removed or changed, and what to change in your code. For a direction, access and prop diff it might look like:

bash

Upgrade: aspect-ratio-box  1.0.0 → 2.0.0  (subscription)
  + new props: fit, position
  ⚠  Palette: v1.x reads primary-* as the action colour; v2.x treats it as the neutral ramp and uses accent-* for actions. If you only ever set --vx-primary-*, define --vx-accent-* too or the action button renders unstyled with no error.
  --dry-run: nothing written.

Be honest with yourself about what that line means: not every upgrade is a pure win. A newer version can drop a feature the old one had, and when it does, the note says so under a dropped-feature warning — read it before assuming "newer" means "strictly better" for your case.

The palette gotcha — this one bites silently

Older components read primary-* as the brand action colour. Newer components read primary-* as the neutral ramp instead, and use accent-* for actions. Upgrade a component across that line in a project that only ever defined --vx-primary-* and the action button renders with no colour at all — and nothing errors. No console warning, no build failure, just an unstyled button.

Define --vx-accent-* alongside --vx-primary-* up front and this never comes up — see the theme contract in Usage for the full variable list and the RGB-channel format they need.

Flags

Flag	Commands	Does
--dry-run	upgrade	Prints the full migration note — version jump, prop diff, palette and dropped-feature warnings — and writes nothing.
--force	upgrade	Overwrite local edits detected since install. Warns first; edits are lost once it runs.
--dest <dir>	upgrade	Project source root the files are written under. Default `src`, same as `add`.