Update & Versioning

This page explains how to modify a component after it is published, how to release a new version, and when the version number must change.

Two update paths

Path	Best for	What you can change
Update page (Web)	Routine iteration after the first publish	Code, preview configuration, description, tags
comphub upload	Code-only changes, skipping the page	Only publishes code, leaves metadata untouched

The first publish can only go through the upload page, because __id__ is written during that step.

Using the update page

1. Download the current version: find the component in "My Components", click "Update" and download the online version as your baseline first.
2. Edit locally: change the code and top up the docs in your project.
3. Verify locally: preview through the local service and confirm nothing regressed.
4. Submit the update: go back to the update page, select the modified folder, bump the version number, adjust the preview and description as needed and click "Update".

When you only change the description, tags or preview configuration, no version bump is needed.

Updating with the CLI

comphub login                                  # Once per machine
cd src/components/MyComponent
comphub upload -m "Fix tooltip positioning"

You can also point at the directory explicitly:

comphub upload src/components/MyComponent -m "Fix tooltip positioning"

Differences from the update page:

• A version bump is mandatory: if version in the local comp.json is not greater than the online one, the CLI refuses outright.
• It does not touch description, tags or preview configuration: those are only available on the update page.

You can do a dry run first:

comphub upload -m "Fix tooltip positioning" --dry-run

--dry-run prints the project path, component ID, online version and the version about to be published, then stops without submitting.

Semantic versioning

major.minor.patch

Type	Change	Example
Patch	Bug fix, backwards compatible	1.0.0 → 1.0.1
Minor	New feature, backwards compatible	1.0.0 → 1.1.0
Major	Breaking change	1.0.0 → 2.0.0

A bump is required when you change component code, the props interface or behaviour.

A bump is optional when you only change the description, tags or preview configuration.

Two ways to change the version number

Update page: edit the version input directly in the configuration area and the platform writes it into comp.json.

Locally by hand:

{
  "name": "MyComponent",
  "version": "1.1.0"
}

Remember to save — this is the file the CLI reads.

Multiple versions coexist

The platform keeps historical versions. Consumers can:

• Switch versions on the preview page to compare differences.
• Download any historical version.
• Pin the version they use in their own project.

An already-downloaded old version does not change when a new version is published.

Changelog

Maintaining one in README.md is recommended:

## Changelog

### 1.1.0 (2026-10-26)

- Added: support for custom theme colours
- Improved: rendering performance with large datasets

### 1.0.1 (2026-10-20)

- Fixed: the tooltip did not show up in some cases

Consumers get a better answer from the README than from the version number when deciding whether to upgrade.

When the submit result is uncertain

If the CLI reports Submit result cannot be confirmed or times out, the server may already have written the update. Do not retry blindly — confirm the latest version on the component detail page first:

• Version already updated: no retry needed.
• Version unchanged: run the upload again.

Next steps

• Full command reference: Using the CLI
• Errors while updating: FAQ & Glossary