@hyperfrontend/features

SDK, CLI, and dev server for building, embedding, and orchestrating hyperfrontend micro-frontend features.

What is @hyperfrontend/features?

@hyperfrontend/features is the batteries-included layer on top of @hyperfrontend/nexus (cross-window messaging). Nexus handles the communication protocol; this package formalizes the frontend glue — iframe management, display modes, and lifecycle orchestration — needed to embed micro-frontend features in any host application.

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

Key Features

• Host SDK (/host) - Embed features with a shell factory, display modes (embedded, dialog, popup, standalone), and open/close lifecycle.
• Hostee SDK (/hostee) - Initialize a feature app, declare its contract, and manage its lifecycle.
• CLI (/cli) - init, build, and dev commands driven by feature.config.*.
• Dev server (/server) - Static file server plus a debug UI for inspecting host/hostee message traffic.
• Zero-config bundling - Direct dependencies are bundled by @hyperfrontend/builder, so generated shells stay self-contained.

Architecture Highlights

The package separates the host and hostee surfaces behind independent subpath exports and builds them on top of the Nexus messaging layer. For a full architectural overview — with diagrams of the host/hostee handshake, display modes, and shell generation — see ARCHITECTURE.md.

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 { createShell, DisplayMode } from '@hyperfrontend/features/host'

const shell = createShell({
  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' })

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

npx @hyperfrontend/features init   # scaffold the hostee glue into an app
npx @hyperfrontend/features build  # generate + bundle a publishable shell package
npx @hyperfrontend/features dev     # serve apps with the debug UI

API Overview

Entry point	Purpose
@hyperfrontend/features	Shared types, contract validation, defineConfig
@hyperfrontend/features/host	Host-side SDK (shell, display modes, lifecycle)
@hyperfrontend/features/hostee	Hostee-side SDK (feature init, lifecycle)
@hyperfrontend/features/cli	CLI (init, build, dev) and hf bin
@hyperfrontend/features/server	Dev server and debug UI

Using Nx? The package also ships a feature generator and build/serve executors at @hyperfrontend/features/nx/* to streamline integration in an Nx workspace.

Compatibility

Environment	Supported
Node.js >= 18	✅
Modern Browsers	✅
Tree Shakeable	✅

License

MIT