Recipes

A recipe takes you from nothing to one working thing: a goal, the calls in order, and an end state you can observe. A guide covers one surface of @fkn/lib completely, where a recipe crosses several to finish one job and links to the guide that owns each concept. This page defines the step badges and lists the ten recipes, one line each.

How to read a recipe

Every recipe opens with a sentence naming its end state and a cost block: Uses, the entry points it calls, Needs, what has to be in place first, and Proven by, how many integrations the shape is drawn from.

Each step is an H2 that opens with a badge, ## [Page] Step name, naming the realm its code runs in. A realm is one JavaScript execution context: a window, a worker, or the sandbox origin of a package, an npm module FKN loads on an origin of its own. The four badges:

• [Build] for bundler and package configuration
• [Page] for code in the app’s window realm, its app.ts
• [Worker] for code in a worker realm, the engine.ts the page relays
• [Package] for code inside a package the app connects to, its package.ts

Steps are grouped by badge, so one file is finished before the next opens. A recipe breaks the grouping only where the work itself demands it: shipping a package ends with a build step, after the package code it publishes. The axis is the realm because that is the split integrations confuse: a page and its worker as a two-file split in five of the integrations behind these recipes, and an app and its package in three.

Networking

The relay is the server that holds the real socket at the far end of net and dgram, and these four get an engine’s socket calls there:

• run sockets in a worker puts an engine on a worker thread, relays it from the page, stops it in order, and turns a missing relay into an error rather than a call that never settles.
• bundle an app that uses sockets gets a Vite build whose worker chunk runs against the one copy of the library the page relayed.
• give a WebAssembly engine sockets runs an engine written for Node’s net and dgram unchanged, with every buffer copied and addresses read once the relay has answered.
• hold an inbound port reserves a port peers can reach, reclaims it after the relay session drops, and reports a state rather than an exception.

The user’s browser

The extension is the FKN browser extension, and these two use it when it is on the page:

• use the extension or the cloud per request sends each request through the user’s own session when the extension is there and through the cloud when it is not.
• drive a real site and play its video puts another site inside your layout, drives it with locators after one consent prompt, and plays its video.

Packages

The host app is the app that installs a package, and one recipe covers each side of that contract:

• install a package and show its UI installs before persisting anything, handles both ways a connection fails, and draws the package inside your layout.
• ship a package bundles into one file, answers connections with onConnect, draws only while a host shows it, and publishes so a host can find it.

Rooms

A room is a realtime channel several browsers join from an invite the app shares, sealed in the browser, and one recipe builds a chat on it:

• run a chat room opens or joins from the page address, renders every event with invented labels, sends what the form holds, and says why the room ended.

Storage and account

The account is the FKN identity a person carries between sites, and one recipe keeps app state in it:

• back state up to the account writes app state to the account and reads it back on the next device, with a first run treated as empty and one writer per browser.