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:

• componentId attribution — tags SDK writes and subscriptions to an installed component.
• 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
ready	All resources exist, all credentials populated
credentials-required	Resources created, but one or more credential keys need values
degraded	One or more declared resources are missing or inactive
paused	All subscriptions paused (via teardown)
installing	Install in progress
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.

Bundled system components

WarmHub also ships reserved system components that install by id from the backend. The current installable bundled component is:

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

This path does not require wh component register, does not create a registry entry, and does not use a local or GitHub component package. The backend resolves the bundled manifest and installs the component into the target repo. Lowercase system ids are reserved for WarmHub; third-party component id validation is unchanged.

CLI commands

# Install WarmHub's bundled Identity system component
wh component install com.warmhub.identity --repo myorg/myrepo

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

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

# View component details
wh component view my-component --repo myorg/myrepo

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

# Pause all component subscriptions
wh component teardown 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 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