welshman/docs/app/index.md

@welshman/app

An instance-based, composable client for building nostr applications. It powers production clients like Coracle and Flotilla, and ties together the rest of the welshman packages (util, net, store, router, signer, feeds) into a single, cohesive app layer.

The core idea: an app is an App instance

Everything in @welshman/app hangs off a single App instance. An App owns the per-identity primitives — an event Repository, a connection Pool, a Tracker, and a WrapManager — plus a config and (optionally) a signed-in User. Because all state lives on the instance, two apps never share data: you can run multiple identities side-by-side, and tearing one down with cleanup() releases everything it allocated.

import {createApp} from "@welshman/app"

// A batteries-included app (event ingestion, relay stats, gift-wrap
// unwrapping, and NIP-42 auth are all wired up by default policies)
const app = createApp()

Features are exposed as plugins — lazily-constructed singletons resolved through app.use(...):

import {createApp, Profiles, RelayLists, Thunks} from "@welshman/app"

const app = createApp()

// Each plugin is constructed once per app and memoized
const profiles = app.use(Profiles)
const relayLists = app.use(RelayLists)

This replaces the previous global-singleton design (pubkey, deriveProfile, publishThunk, Router.get()). There are no module-level globals anymore — you create an app and reach everything through it.

Architecture at a glance

Layer	What it is	Where
App	The app instance; owns repository/pool/tracker/wrapManager and the use() registry	App
User & sessions	The signed-in identity and serializable login descriptors	User & Sessions
Policies	Side effects installed at construction (ingest, auth, stats, wraps)	App
Plugins	Lazily-resolved feature modules built on a small set of base classes	Plugin architecture
Data plugins	Reactive collections of profiles, lists, relays, handles, zappers…	Data
Publishing	Optimistic publishing via thunks	Publishing
Requests	Loading & negentropy sync	Requests
Routing	Outbox-model relay selection and tag builders	Routing
Web of Trust	Follow/mute graph scoring	Web of Trust
Feeds & Search	Feed controllers and fuzzy search	Feeds & Search

Quick example

import {createApp, User, toSession, nip07, Profiles, Thunks, Router} from "@welshman/app"
import {getNip07} from "@welshman/signer"
import {makeEvent, NOTE} from "@welshman/util"
import {addMinimalFallbacks} from "@welshman/router"

// 1. Log in. A session is a serializable {method, data} descriptor; User
//    turns it back into a live, signing identity.
const pubkey = await getNip07().getPubkey()
const session = toSession(nip07, {})
const user = await User.fromSession(session)

// 2. Create the app around that user.
const app = createApp({user})

// 3. Read data reactively. Stores lazily fetch over the network using the
//    outbox model and update as events arrive.
const profile = app.use(Profiles).one(pubkey)   // Readable<Maybe<Profile>>
profile.subscribe($profile => console.log($profile?.name))

// 4. Publish optimistically. The event is written to the local repository
//    immediately, signed lazily, and progress is reported per-relay.
const thunk = app.use(Thunks).publishToOutbox({
  event: makeEvent(NOTE, {content: "hi"}),
  delay: 3000,                                   // soft-undo window
})

// Abort before `delay` elapses to undo
// thunk.abort()
await thunk.waitForCompletion()

// 5. Tear it all down
app.cleanup()

Installation

npm install @welshman/app
# or
pnpm add @welshman/app
yarn add @welshman/app

@welshman/app has peer dependencies on svelte (4 or 5) and the other welshman workspace packages (@welshman/feeds, @welshman/lib, @welshman/net, @welshman/router, @welshman/signer, @welshman/store, @welshman/util), plus @pomade/core for the optional Pomade signer.