Migration guides from other JavaScript ActivityPub libraries

[dahlia]

Developers already running federated services on other JavaScript ActivityPub libraries are a natural audience for Fedify, but moving an existing service is non-trivial: actor keys, followed/followers collections, and queued outbound deliveries all need to survive the swap, and the mental model of each source library differs from Fedify's builder-and-dispatcher pattern.

We should publish a set of migration guides that walk through the transition from the most likely source libraries, each covering both code-level rewrites and data/key continuity.

Proposed placement

The top-level nav is space-constrained, so the migration guides do not get a top-nav entry. Instead, expose them through the sidebar only.

• Sidebar: Add a new group Migrating to Fedify immediately below the existing Manual group, with the four guides listed as items. This puts migration content adjacent to the existing getting-started path, which is where readers coming from another library are most likely to browse.
• Top nav: Unchanged.

The file tree lives at docs/migrate/, kept parallel to docs/tutorial/ rather than nested inside it, since migration guides are a distinct genre.

• docs/migrate.md: Landing page. Brief summary of each guide and a short decision tree.
• docs/migrate/apex.md: From activitypub-express.
• docs/migrate/activity-kit.md: From @activity-kit/*.
• docs/migrate/express-handrolled.md: From hand-rolled Express code, including forks/descendants of express-activitypub.
• docs/migrate/activity-streams.md: From activitystrea.ms (vocabulary-only migration).

Guide scope

Each guide follows the same template so readers can skim across them:

1. When to migrate: concrete signals that Fedify is a better fit (unmaintained upstream, missing features, interop issues, runtime limits).
2. Mental model mapping: a concise table mapping source-library concepts to Fedify concepts (e.g. apex routes and onIncoming callbacks to FederationBuilder dispatchers and inbox listeners).
3. Code migration: before/after snippets for the most common constructs: actor definition, inbox handling, outbox generation, follower collections, HTTP Signatures.
4. Data migration: how to preserve actor key pairs, followers/following collections, and any in-flight queue state. This is the part that silently breaks federation if done wrong.
5. Common pitfalls: behaviors that differ subtly (e.g. context resolution, signing algorithm defaults, actor URI schemes).
6. Worked example: a small before/after project illustrating the migration end-to-end.

From activitypub-express (apex)

Express middleware with MongoDB store; the most common non-Fedify stack in the Node.js fediverse today. The guide covers Express-to-integration-package replacement (e.g. @fedify/express), MongoDB-backed actor and collection data export, and key-pair carryover so existing followers are not lost.

From @activity-kit/* (ActivityKit)

TypeScript-first, spec-oriented, but effectively dormant. The guide emphasizes Fedify's equivalents for the @activity-kit/endpoints handlers and storage adapters, and addresses readers who are stuck on an unmaintained stack.

From hand-rolled Express/ActivityPub code

Covers the large set of small bots, blogs, and single-actor services derived from Darius Kazemi's express-activitypub reference implementation and similar hand-rolled codebases. These typically implement just enough ActivityPub to federate with Mastodon. The guide shows how to replace the custom handlers with Fedify's actor dispatcher, inbox listener, and outbox, while preserving the actor's existing URI scheme so external servers keep following correctly.

From activitystrea.ms (vocabulary-only)

Short guide covering a pure vocabulary swap to @fedify/vocab. No data migration section; this one is code-only.

Deliverables

1. In docs/.vitepress/config.mts, add a Migrating to Fedify sidebar group immediately below the Tutorials group. Do not touch the top-level nav.
2. Write docs/migrate.md landing page with the decision tree.
3. Write the four guides: docs/migrate/apex.md, docs/migrate/activity-kit.md, docs/migrate/express-handrolled.md, docs/migrate/activity-streams.md.
4. Each guide includes at least one end-to-end before/after example. Where code is substantial, link to a companion repository or examples/ entry rather than inlining.
5. Cross-link the landing page from the Installation page and from README.md.
6. Add an entry to CHANGES.md.

Out of scope

• Automated migration tooling (codemods, CLI migrators). May be a follow-up if readers ask for it.
• Guides for libraries outside the four listed above (e.g. @semapps/activitypub, @evanp/activitypub-bot). These audiences are small or have natural non-Fedify paths, and can be follow-ups if requested.
• Cross-language migration (Ruby, Python, Elixir, etc.). Fedify is JavaScript/TypeScript only.