@hyperfrontend/features§

What is @hyperfrontend/features?

Embedding another team's app inside your page usually means an iframe, a pile of postMessage conventions nobody wrote down, and a frame that never quite fits the space you gave it. @hyperfrontend/features turns that into a contract: the feature app declares what it sends, what it accepts, and which display modes it supports; the host picks a mode and gets a typed handle back. The messaging protocol underneath is @hyperfrontend/nexus, and this package adds everything around it: iframe management, display modes and sizing, the open/close lifecycle, and a CLI that packages a feature app into an installable shell.

// In the feature app, from '@hyperfrontend/features/hostee'
const feature = createFeature({ name: 'checkout', contract })
await feature.ready()
feature.send('order-placed', { id: 'A-1094' })

// In the host app, from '@hyperfrontend/features/host'
const checkout = createShell({ modes: { dialog: mountDialog }, url: 'https://checkout.example.com' })
checkout.on('order-placed', (order) => showReceipt(order))
checkout.open({ displayMode: DisplayMode.Dialog })

It is organized into independent subpath entry points so consumers import only the surface they need.

Key Features

Why Use @hyperfrontend/features?

You get typed host and hostee SDKs, a CLI, and a dev server for composing micro-frontend features, and it works with any framework (React, Vue, Angular, vanilla JS) and build tool. Features build into self-contained shell packages with their dependencies bundled in, so a host installs one package and inherits no transitive install burden.

Installation

npm install @hyperfrontend/features

Quick Start

In a feature app (the hostee), declare a contract and connect to whatever host embeds it:

import { createFeature } from '@hyperfrontend/features/hostee'

const feature = createFeature({
  name: 'clock',
  contract: { emitted: [{ type: 'tick' }], accepted: [{ type: 'set-timezone' }] },
})

await feature.ready()
feature.on('set-timezone', ({ tz }) => render(tz))
setInterval(() => feature.send('tick', Date.now()), 1000)

In a host app, build a shell and surface the feature in any display mode:

import { builtInDisplayModes, createShell, DisplayMode } from '@hyperfrontend/features/host'

const shell = createShell({
  modes: builtInDisplayModes,
  url: 'https://features.example.com/clock',
  container: '#clock-slot',
  displayMode: DisplayMode.Embedded,
})

shell.on('tick', (time) => console.log('feature said', time))
shell.open()
shell.send('set-timezone', { tz: 'UTC' })

Presentation is host-controlled and contract-preconfigured: a feature declares the display modes it supports (display.modes in feature.config.*, plus per-mode defaults like fixed embedded dimensions or the dialog box footprint and position), the generated shell builds in exactly those modes, and the host picks one per open.

At runtime the SDK measures the host-side space and reports it to the feature as exact pixels (the initial size travels with the mode announcement itself), and frames stay hidden until the session opens. In dialog mode the feature draws its own dialog box inside a transparent full-viewport pane and backdrop/Escape dismissal is coordinated for you. The host SDK docs cover the modes one by one.

Contract actions may carry a required: true flag on accepted entries, which denies the connection unless the counterpart emits that type. Unflagged actions never gate the connection, so adding actions to a contract stays backward compatible.

The SDK's own traffic (the heartbeat, the presentation announcements, dismiss signals, dirty state, and the request/response envelopes) rides the same channel under a reserved __hf: prefix and is filtered out before your handlers run. Your contract must not declare action types beginning with __hf:; everything the plane carries is listed in the architecture guide.

Both sides can opt into a sealed envelope: pass protocol (and, for v4, a sharedKey) to createShell and createFeature, and the two sides negotiate it during the connection handshake.

Handshake frames stay plaintext while product messages (including sends queued before the handshake) leave sealed, and a plaintext product message arriving on a secured channel is dropped. Key agreement is paid once per session; each message then costs one AES-GCM operation, so many secured channels can run at once on one page.

Security is fail-closed: a counterpart that cannot run the selected protocol is denied, and a session the counterpart never confirms (a mismatched v4 key, for instance) closes with reason: 'security-unconfirmed' after the connect timeout. A packet the envelope cannot protect or unwrap is discarded and surfaced on that side as an error event shaped { reason: 'security-error', message, code }, so a message one side sent and the other never received is never silent.

A contract may carry a semver version, or createFeature can receive a version option that takes precedence over contract.version. Each side presents its version during the handshake, and incompatible cuts (a different major, or a different minor below 1.0.0) are denied before the channel opens, surfacing as an error on both handles. A side without a version always passes the check, so unversioned peers keep connecting.

A refused handshake ends at once. Whichever gate refuses (contract, policy, version, or fail-closed security), the host destroys the mount and the feature's pending ready() rejects: a deny surfaces as an error carrying the gate's reason, and a cancel the counterpart sent after aborting at its own gates surfaces on the host as error with reason: 'handshake-cancelled'.

Contract entries with a schema are enforced on both ends: send validates the payload against the sender's own emitted schema and throws in the sender's frame before anything crosses the wire, while incoming messages are validated against the receiver's own accepted schema. An invalid payload is dropped and surfaced as an error event shaped { reason: 'invalid-payload', type, errors }. Schema-less actions pass through unchanged.

What each of these controls is actually worth, and which parts of an integration's security remain the operator's job rather than the SDK's, is stated once, in the Security Model.

From the command line, scaffold, build, and serve features with the bundled hf CLI:

# scaffold the hostee glue into an app
npx @hyperfrontend/features init
# generate and bundle a publishable shell package
npx @hyperfrontend/features build --protocol v4
# serve apps with the debug UI
npx @hyperfrontend/features dev
# serve a built site for production
npx @hyperfrontend/features serve --root dist

build requires --protocol v3 or --protocol v4; an explicit --protocol none produces an open, unauthenticated shell and builds only together with --allow-open.

API Overview

Two of the entry points are runtimes, one per side of the frame, and an app imports exactly one. /host gives a host page createShell: hand it a feature URL and a map of display modes, get back a ShellHandle to open, send to, listen on and close. /hostee gives a feature app createFeature: hand it the contract that app will speak, get back a FeatureHandle of the same shape. Both return synchronously; the feature awaits ready(), and the host watches its shell's open, close and error events.

The root entry is the DOM-free one: the contract, config and payload types both runtimes share, the defineConfig helper a feature.config.* file exports, and validateContract for checking one before it ever reaches a wire. Import it from build scripts, config files and Node tests, where reaching for /host or /hostee would drag a browser runtime along.

The last two entry points are Node tooling, importable as modules because the hf bin is only a thin argv wrapper over them. /cli is init, build, dev and serve as functions, for when a shell invocation will not do. /server is the machinery under two of those: startDevServer for the multi-app dev server and its traffic-inspecting debug UI, and startStaticServer for production hosting.

What build emits is the part worth knowing: a feature becomes a self-contained shell package with its direct dependencies bundled in, so a host installs that one package and inherits no transitive install burden. Nx workspaces reach the same tooling as plugin targets, through init and feature generators and build and serve executors under the nx/generators and nx/executors subpaths; nx add @hyperfrontend/features installs the package and runs the init one for you.

Every option, handle, contract and payload type is in the API reference.

Compatibility