Components

Components are self-contained packages that add functionality to a WarmHub repo. A component declares the shapes, subscriptions, credentials, and seed data it needs, and installation applies the manifest-provisioned resources in one operation. Registered components can also delegate selected resources to a setup callback.

Other uses of “component”

The word component names a few related things. This page covers the installable package — the unit of distribution, defined by component.json and manifest.json. The rest build on it:

• componentRef attribution — tags SDK writes and subscriptions to an installed component by its Org/Name ref.
• Components tab — the web UI view listing a repo’s installed components.
• client.component.* — the SDK methods that install, list, and manage these packages.

What a component does

When you install a component, WarmHub:

1. Reads the component’s manifest (warmhub/manifest.json) to learn what resources it needs
2. Creates manifest-provisioned shapes for the data types the component works with
3. Sets up manifest-provisioned subscriptions that deliver to your webhook endpoints when data changes
4. Seeds initial data the component needs to operate
5. Creates manifest-provisioned credential sets for any external API keys the component requires
6. Calls the setup endpoint for registered components that declare setup-provisioned resources

All resources are tracked under a ComponentInstall record so the CLI can manage, diagnose, and tear down the component later.

Key concepts

Manifest-driven: Components use a declarative JSON manifest rather than imperative scripts. The manifest describes what resources the component needs, and the CLI handles creation, reconciliation, and teardown.

Ownership: Resources created by a component are tagged with the component’s ID. This prevents accidental modification and enables clean teardown. Users can still create things under component-owned shapes — ownership protects schema, not data.

State tracking: Each installed component has a state that reflects its health:

State	Meaning
installing	Install in progress
ready	All declared resources exist and are active
degraded	One or more declared resources are missing or inactive
paused	The component has subscriptions and all of them are paused
uninstalled	Torn down (terminal) — subscriptions paused and tokens revoked, but shapes and seeded data are preserved; the install record is retained so a reinstall can revive it
error	Install failed

Registered components

Registered components are org-owned component identities installed with wh component install <org/name>. Registering publishes the component’s manifest to WarmHub, so installs resolve the stored manifest snapshot directly through the registry. They are useful for sharing a component across repos in an org and for installs that need a setup callback to create external service state.

Authors enable this model by registering the component identity with wh component register <name> --org <org> --manifest <path>, and optionally adding a setupUrl. --source-url is optional documentation metadata. Manifest resources marked provisioning: "setup" are skipped by the local installer and must be created by that setup service.

See Manifest Reference for provisioning and runtimeAccess, CLI Commands for registration commands, and the client.component API reference for the registry methods.

First-party components

WarmHub publishes its own registered components, such as warmhub/identity and warmhub/veritas. You install them by <org>/<name> exactly like any other registered component:

wh component install warmhub/identity --repo myorg/myrepo

There is no separate “install by id” path. A manifest’s reverse-DNS component.id (e.g. com.warmhub.MyComponent) is manifest metadata, not a CLI argument — install and every lifecycle command take the <org>/<name> ref.

CLI commands

# Install WarmHub's first-party Identity component
wh component install warmhub/identity --repo myorg/myrepo

# Validate your package offline, then register it from its manifest and install by <org>/<name>
wh component validate ./my-component
wh component register my-component --org myorg --manifest ./warmhub/manifest.json
wh component install myorg/my-component --repo myorg/myrepo

# List installed components
wh component list --repo myorg/myrepo

# View component details (lifecycle commands take the <org>/<name> ref)
wh component view myorg/my-component --repo myorg/myrepo

# Run health checks
wh component doctor myorg/my-component --repo myorg/myrepo

# Tear down the component (terminal — pauses subscriptions and marks it uninstalled; shapes and data are preserved)
wh component teardown myorg/my-component --repo myorg/myrepo

Example

A component that watches for new Paper things and summarizes them:

my-summarizer/
  warmhub/
    component.json          # Identity: id, name, version
    manifest.json           # Resources: shapes, subscriptions, credentials, seeds

Registering and installing it:

# Register the identity from its manifest, then install by <org>/<name>
wh component register my-summarizer --org myorg --manifest ./warmhub/manifest.json
wh component install myorg/my-summarizer --repo myorg/research
# Installed my-summarizer v1.0.0

# Set the required API key
wh credential set summarizer-creds api_key --value sk-...

# Verify health
wh component doctor myorg/my-summarizer --repo myorg/research

Next steps

Need	Page
The full manifest format (provisioning, runtimeAccess)	Manifest Reference
Install, update, doctor, or teardown an installed component	Component Lifecycle
Build your own component	Authoring Components
The offline validation workflow before publishing	Testing Components
Registration and install commands	CLI: component management