/fedify

name: fedify
description: >-
  Use this skill whenever writing JavaScript or TypeScript code that uses
  Fedify to build an ActivityPub server, handle federation activities,
  implement fediverse features, or integrate Fedify with a web framework
  such as Hono, Express, Next.js, Nuxt, Fastify, Koa, NestJS, Astro,
  SvelteKit, Fresh, h3, Elysia, or Cloudflare Workers. Covers the
  `Federation` builder pattern, actor/inbox/outbox/collection dispatchers,
  inbox listeners, vocabulary objects from `@fedify/vocab`, key pair
  management, HTTP Signatures, Object Integrity Proofs, the `KvStore` and
  `MessageQueue` interfaces, database adapter packages, structured logging
  with LogTape, OpenTelemetry tracing, the `fedify` CLI toolchain, and
  common mistakes. Also apply when the user mentions ActivityPub,
  federation, fediverse, WebFinger, NodeInfo, FEPs, or Mastodon
  interoperability, even if they do not name Fedify explicitly.

Fedify skill ============

Fedify is a TypeScript library for ActivityPub server applications. It works across Deno, Node.js, and Bun. The library takes care of the fiddly parts of the fediverse (HTTP Signatures, Object Integrity Proofs, WebFinger, NodeInfo, JSON-LD, delivery queues) so application code can stay focused on dispatchers and activity handlers.

Always link into the full documentation at <https://fedify.dev/> instead of guessing. Every docs page is also served as raw Markdown by appending `.md` to its path, so <https://fedify.dev/manual/federation.md> returns `text/markdown`. This skill uses the `.md` form in every fedify.dev link below so you can read the source directly without HTML rendering; when you present a link *to the user*, strip the `.md` suffix so browsers render the HTML page (so `https://fedify.dev/manual/federation.md` becomes `https://fedify.dev/manual/federation`). The index at <https://fedify.dev/llms.txt> and the full bundle at <https://fedify.dev/llms-full.txt> are authoritative; this skill only points the way. Do not invent APIs; verify names against those docs or against the installed `@fedify/fedify` types.

Builder pattern ---------------

Two entry points reach a `Federation<TContextData>` object:

• `createFederationBuilder<TContextData>()` returns a

`FederationBuilder<TContextData>`. Register dispatchers and listeners on it, then `await builder.build(options)` to obtain the `Federation<TContextData>`. Prefer this in larger apps, especially when you need to split configuration across files or avoid circular imports. In serverless runtimes such as Cloudflare Workers, bindings are only available per-request, so the `Federation` must be constructed inside the request handler; the builder pattern is the documented approach there because dispatcher registration can happen at module load time and only the asynchronous `.build(options)` call runs per request.

• `createFederation<TContextData>(options)` returns a

`Federation<TContextData>` directly. Appropriate when everything fits in one module.

`.build()` is asynchronous; always `await` it. See <https://fedify.dev/manual/federation.md>.

~~~~ typescript import { createFederationBuilder, MemoryKvStore } from "@fedify/fedify";

const builder = createFederationBuilder<AppState>(); // ...register dispatchers on builder... export const federation = await builder.build({ kv: new MemoryKvStore(), // development only }); ~~~~

> [!IMPORTANT] > Production deployments *must* provide a real `queue` implementation. > Without one, outgoing activities are sent synchronously and delivery > becomes unreliable under load. See > <https://fedify.dev/manual/federation.md>.

> [!WARNING] > Never set `allowPrivateAddress: true` outside tests. It disables the > SSRF guard that blocks Fedify from fetching private or loopback > addresses. See <https://fedify.dev/manual/federation.md> and > <https://fedify.dev/manual/deploy.md>.

Dispatchers -----------

Every route Fedify serves is driven by a dispatcher callback registered on the builder (or `Federation` object). Do not hand-roll these routes in the web framework; the dispatcher signatures encode the library's URI template guarantees.

• `setActorDispatcher(path, dispatcher)`: returns an

`ActorCallbackSetters` chain that also carries `setKeyPairsDispatcher()`.

• `setObjectDispatcher(type, path, dispatcher)`: for individual

`Object` types such as `Note` or `Article`.

• `setInboxDispatcher(path, dispatcher)`: the inbox *collection*

endpoint. The inbox *listener* is a different API (see below).

• `setOutboxDispatcher(path, dispatcher)`.
• `setFollowingDispatcher(path, dispatcher)` /

`setFollowersDispatcher(path, dispatcher)` / `setLikedDispatcher(path, dispatcher)` / `setFeaturedDispatcher(path, dispatcher)` / `setFeaturedTagsDispatcher(path, dispatcher)`.

• `setCollectionDispatcher()` and `setOrderedCollectionDispatcher()`

for custom collections.

• `setNodeInfoDispatcher(path, dispatcher)` and

`setWebFingerLinksDispatcher(dispatcher)` for protocol endpoints.

Paths use URI templates. If an identifier can contain URI characters, switch the template variable from `{identifier}` to `{+identifier}` to avoid double-encoding. See <https://fedify.dev/manual/uri-template.md>.

> [!WARNING] > Simple expansion (`{identifier}`) percent-encodes reserved characters a > second time. If actors or objects are keyed by URIs, use reserved > expansion (`{+identifier}`).

See <https://fedify.dev/manual/actor.md>, <https://fedify.dev/manual/object.md>, and <https://fedify.dev/manual/collections.md>.

Inbox listeners ---------------

`setInboxListeners(inboxPath, sharedInboxPath?)` returns an `InboxListenerSetters` object with:

• `.on(ActivityType, handler)`: chainable, keyed by the *class*

(`Follow`, `Create`, `Undo`, etc.).

• `.onError(handler)`.
• `.onUnverifiedActivity(handler)`.
• `.setSharedKeyDispatcher(dispatcher)`.
• `.