@hyperfrontend/features/hostHost
Host-side SDK for embedding hyperfrontend features — shell factory, display modes, iframe utilities, and lifecycle.
import { createShell, DisplayMode } from '@hyperfrontend/features/host'
const shell = createShell({
url: 'https://features.example.com/clock',
container: '#clock-slot',
displayMode: DisplayMode.Embedded,
})
shell.on('open', () => console.log('feature connected'))
shell.on('tick', (time) => console.log('feature said', time))
shell.open()
shell.send('set-timezone', { tz: 'UTC' })API
| Export | Purpose |
|---|---|
createShell | Build a shell handle for a feature; returns open/close/send/on/isOpen. |
DisplayMode | The four built-in modes: Embedded, Dialog, Popup, Standalone. |
ShellHandle | Type of the handle returned by createShell. |
ShellOptions | Options accepted by createShell and per-open overrides. |
ExperiencePlugin | Opt-in extension point for layering transitions/animations onto display modes. |
The shell wraps a @hyperfrontend/nexus broker: send emits a contract action to the feature, and on subscribes to feature messages and the open/close/error lifecycle events. close disconnects the channel; destroy also releases the DOM.
API Reference
ƒ Functions
Creates a host-side shell for embedding a feature.
Provisions a nexus broker and returns a handle whose
Provisions a nexus broker and returns a handle whose
open mounts the feature in the requested display mode. The contract option takes the feature's contract exactly as the feature authored it; the shell derives the host-side orientation itself, so the handle sends what the feature accepts and receives what the feature emits.Parameters
| Name | Type | Description |
|---|---|---|
§options | ShellOptions | Create-time shell options, overridable per open call. |
Returns
ShellHandleA handle exposing
open, close, destroy, send, on, and isOpen.Example
Embedding a clock feature
const clock = createShell({ container: '#clock', url: 'https://clock.example.com' })
clock.open({ displayMode: DisplayMode.Dialog, dialogWidth: 530 })
clock.on('timeUpdated', (data) => console.log(data))◈ Interfaces
Public handle returned by createShell.
Properties
Description of a single action a feature can emit or accept.
Structurally compatible with nexus's channel contract action shape so the same contract can drive both messaging and the shell type generator.
Structurally compatible with nexus's channel contract action shape so the same contract can drive both messaging and the shell type generator.
Properties
§
respondsWith?:string— When this action is used as a request, the type of the action in the other direction that answers it.
Opt-in extension that decorates a feature's mount lifecycle (e.g. transitions, animations).
Register plugins through ShellOptions.plugins. After each successful mount the shell calls
Register plugins through ShellOptions.plugins. After each successful mount the shell calls
onMount on every plugin in registration order; before each unmount it calls onUnmount one plugin at a time in reverse registration order, awaiting any returned promise, then runs the teardowns returned by onMount (also in reverse registration order) and finally removes the feature. The SDK ships no built-in plugins.Properties
Context handed to an ExperiencePlugin around a feature's mount lifecycle.
Properties
The set of actions a feature emits to, and accepts from, its counterpart.
This is the same shape the on-disk
This is the same shape the on-disk
*.contract.json files and the shell generator consume.Per-request settings accepted by
request.Properties
Options accepted by the host-side FeatureContract consumer when creating or opening a shell.
Properties
§
contract?:FeatureContract— The feature's contract exactly as the feature authored it (
emitted = what the feature sends, accepted = what the feature handles). The shell derives the host-side orientation itself — hand it the feature's contract, never a pre-swapped copy. Replaces the generic default when provided.§
embedSizing?:EmbedSizing— How an embedded feature is sized; defaults to
fill (the iframe fills its container).§
onUnresponsive?:UnresponsivePolicy— How the host reacts when the feature stops responding; defaults to
emit.§
plugins?:unknown— Experience plugins wrapped around each mount/unmount;
onMount runs in registration order, onUnmount in reverse.Context passed to an UnresponsivePolicy callback when a feature stops beating.
◆ Types
How the feature is laid out when the host surfaces it.
type EmbedSizing = "fill" | "content"Answers one request type; may return the response value directly or a promise of it.
type RequestHandler = (data: unknown) => unknownUnion of the supported security envelope selectors.
none is the local default (opt-in security); production builds must pick v1 or v2.type SecurityProtocol = "none" | "v1" | "v2"What the host does when a feature misses too many heartbeats.
emit (the default) emits an error; unmount also tears the feature down; a callback takes over handling entirely with the UnresponsiveInfo.type UnresponsivePolicy = "emit" | "unmount" | (info: UnresponsiveInfo) => void● Variables
Supported ways a host can surface an embedded feature.
All four modes are built into the SDK.
All four modes are built into the SDK.