Reference
JavaScript API
The package entry points of handoff-app 2.1.0, and the Handoff class for driving it from Node.
Entry points
| Import | Exports |
|---|---|
handoff-app | defineConfig, fromEnv, the Handoff class (default export), CoreTransformers, CoreTransformerUtils, CoreTypes, the provider define helpers, and the Config types |
handoff-app/react | defineCatalogItem, fromCSF, and the types Preview, CatalogPreview, CatalogItem, CatalogItemMeta, CompositionRef, Meta, StoryObj |
handoff-app/handlebars | defineCatalogItem, and the types Preview, CatalogPreview, CatalogItem, CatalogItemMeta, CompositionRef |
handoff-app/pattern | defineCatalogItem for compositions, and the types CatalogItem, CatalogItemMeta, CompositionRef |
handoff-app/providers | defineStorageProvider, defineEmailProvider, defineAiProvider, and their types. The only import a server module may use. |
The Handoff class
Every CLI command is a method on the Handoff class, so a Node script or CI tool can drive Handoff
without the CLI.
import Handoff from 'handoff-app'
const handoff = new Handoff({ profile: 'staging' })
await handoff.fetch()
await handoff.publishAll()Constructor options
| Option | Effect |
|---|---|
debug | Debug logs, like -d |
force | Like -f |
dryRun | Publish uploads nothing and checkout writes nothing |
skipBuild | Publish the existing build output, like --no-build |
config | A partial config merged over the loaded config file, as the last layer |
configPath | An explicit config file, like -c |
profile | Config profile, like --profile. Wins over HANDOFF_PROFILE. |
profileWithoutConfig | 'saved-login' accepts a profile that only has a saved registry login; 'any' accepts any valid name |
Methods
Each method returns a promise of the instance, so calls chain.
| Method | CLI equivalent |
|---|---|
fetch() | fetch |
component(name) | build:components [name] |
build(target?, skipComponents?, buildPackage?) | build |
start(), dev() | start, dev |
dbMigrate() | db:migrate |
publishCatalog(id?), checkoutCatalog(id?) | publish catalog, checkout catalog |
publishKind(kind, id?), checkoutKind(kind, id?) | One kind: components, patterns, pages, tokens, or assets |
publishTokens(setId?), publishAssets(collection?) | publish tokens, publish assets (and the matching checkout* methods) |
publishAll(targets?), checkoutAll(targets?) | publish all, checkout all |
validateComponents(skipBuild?) | validate:components |
makeComponent(name), makePage(name, parent) | make:component, make:page |
ejectConfig(), ejectPages(), ejectTheme() | eject:config, eject:pages, eject:theme |
publishAll and checkoutAll run tokens and assets first, then components, patterns, and pages.
They take an optional list of targets; a target is a kind, or { kind, ids } to narrow it to some
ids. A failed kind is reported, the rest continue, and the call throws at the end.
Path helpers include getOutputPath(), getTokensFilePath(), getConfigFilePaths(), and
getProfile().