NodeBB — Complete Reference

Overview

NodeBB is a modern, open-source forum software built on Node.js with native WebSocket real-time updates. Founded in 2014 by Julian Lam, Andrew Rodrigues, and Barış Soner Üşaklı in Toronto, Canada. Licensed GPL-3.0.

Starting with v4.0.0 (released January 20, 2025), NodeBB includes ActivityPub federation as a core feature — not a plugin. This makes NodeBB the first major traditional forum software to ship ActivityPub in its core. The implementation was funded by the NLNet Foundation (NGI Zero Core fund, approved August 2023).

NodeBB organizes content as forum topics (not ephemeral posts). Content is presented chronologically with active topics "bumped" to the top when receiving replies. This is fundamentally different from microblogging platforms — NodeBB brings the structured discussion forum paradigm into the Fediverse.

1. Technology Stack

Database Architecture

NodeBB provides a unified database abstraction layer (hashes, sets, sorted sets, lists) that works identically across all three backends. Data is stored as key-value objects (e.g.,

user:<uid>

Multi-database support: Sessions can be separated into a different database instance (e.g., Redis for sessions, MongoDB for data). Redis pub-sub is used for inter-process communication regardless of primary database, enabling horizontal scaling across multiple Node.js processes.

Plugin System

Hooks-based architecture with four hook types:

Plugins can mount API routes at

/api/v3/plugins

2. ActivityPub Implementation

Why Core, Not Plugin

ActivityPub required extensive architectural changes that couldn't be accomplished via a plugin. It was built directly into the NodeBB core.

Configuration

• Global toggle:

  ACP > Settings > Federation (ActivityPub)

• New v4 installs: federation enabled by default, all categories federate
• Upgrades from v3: federation disabled by default (opt-in)
• Per-category control: the "fediverse" pseudo-user is granted viewing/posting privileges on a per-category basis
• Domain filtering: allow-list or deny-list modes

Development Timeline

3. Actor Types

Person

/u/username

Group

/category/<cid>

Application

Category as Group Actor (FEP-1b12)

Each category identifies itself as a

Group

• Maintain follow relationships with other actors and remote users
• Can follow other

  Group

  actors from different forums
• Federate content via the Announce relay pattern
• Have a unique handle — a "slugified" version of the category name (e.g., "Category About Cats" →

  category-about-cats

  )

When a user posts content (new topic or reply), the category wraps it in an

Announce

User creates post → Create{Note} sent to Category
Category wraps → Announce{Create{Note}} sent to all followers
Remote instances receive → display post in corresponding category

This is the same pattern used by Lemmy communities and Kbin/Mbin magazines. Remote users can follow a NodeBB category the same way they follow a Lemmy community.

The Uncategorized Pseudo-Category

Serves as a catch-all for manually discovered remote content (via URL paste into search). Content lands here automatically before admins move it to appropriate local categories. The Uncategorized category does NOT use the Announce pattern and has automated pruning.

4. Content Model and Conversational Context

Two-Level Hierarchy

NodeBB maps forum structure to ActivityPub using a two-level hierarchy:

Category (audience) → Topic (context) → Post
     Group actor        OrderedCollection    Note/Article

Every post carries both properties:

• audience

  → points to the category (

  Group

  actor)

• context

  → points to the topic (resolvable URL returning an

  OrderedCollection

  per FEP-7888)

Object Types

context

Note

Article

inReplyTo

Group

audience

NodeBB builds topics from incoming ActivityPub activities (

Create

Question

Listen

Note

Article

Context Resolution (FEP-7888)

When NodeBB encounters an object with a

context

1. Primary: Resolvable context — resolves the URL to retrieve a

   Collection

   , parses all objects, organizes them into a single topic. Supports synchronization headers for freshness verification.

2. Fallback: Reply chain traversal — traverses

   inReplyTo

   chain upward to the root node, organizes chain objects into a topic.

Reply chain traversal has limitations:

• If any object in the chain becomes unresolvable, the chain breaks
• Only follows the direct reply path, missing sibling branches

Outboxes

User and category outboxes (v4.10.0+) return paginated

OrderedCollection

Create

Like

first

last

prev

next

5. FEP Support

NodeBB evaluates FEPs using four positions (mirroring Mozilla's Specification Positions): positive, neutral, defer, negative.

Implemented

Partially Implemented

FEP-7458 (Using the replies collection)

Positive (Not Yet Implemented)

FEP-044f, FEP-8b32, FEP-9967, FEP-c0e0

NodeBB is an active participant in the SWICG Forum and Threaded Discussions Task Force, promoting threaded discussion formats in the Fediverse.

6. Content Discovery and Pruning

Discovery Methods

1. Follow users/categories — search for handles (e.g.,

   user@domain.social

   )
2. URL paste — paste a remote content URL into NodeBB's search bar to pull it in; content lands in Uncategorized
3. Cross-posting (v4.8.0+) — topics from remote categories can be added to local categories

No Relay Support

NodeBB explicitly does NOT support relays. This is intentional — relays "do not guarantee the quality of incoming content." The design prioritizes relationship-based content distribution over algorithmic or broadcast discovery.

Content Pruning

NodeBB automatically manages remote content to prevent database bloat:

Both settings are configurable via the admin panel.

7. NodeBB vs Discourse (Federation)

Both bring threaded forum discussions to the Fediverse, using categories as Group actors. NodeBB's core integration means tighter coupling with the ActivityPub protocol and more extensive FEP adoption. Discourse's plugin approach allows easier opt-in/opt-out but has less deep integration.

8. Interoperability Notes for Implementers

1. Categories are

   Group

   actors — follow a NodeBB category by sending

   Follow

   to the Group actor at

   /category/<cid>

   . The category relays all content via

   Announce

   , identical to Lemmy communities. Category handles are slugified names (e.g.,

   general-discussion

   ).

2. Posts carry both

   context

   and

   audience

   —

   context

   points to the topic (resolvable

   OrderedCollection

   ),

   audience

   points to the category (

   Group

   actor). This two-level hierarchy is NodeBB-specific and differs from Lemmy's single-level approach.

3. Topics are resolvable collections — if your software encounters a NodeBB

   context

   URL, resolve it to get the full topic as an

   OrderedCollection

   . This is the recommended way to backfill conversations (per FEP-7888 and FEP-f228).

4. Note

   and

   Article

   objects accepted — NodeBB processes both

   Note

   and

   Article

   types when building topics. Send whichever is appropriate for your content.

5. No relay federation — NodeBB will not participate in relay subscriptions. Content exchange requires explicit follow relationships.

6. Remote content is pruned — NodeBB deletes remote content after 30 days (configurable) if it has no local engagement. If your software references old NodeBB content, it may have been pruned from remote instances that imported it. Similarly, content your software sends to NodeBB will be pruned if no local user engages with it.

7. Cross-posting — since v4.8.0, a single topic can appear in multiple local categories. This means the same remote content may be accessible via different category Group actors on the same instance.

8. Soft deletion (FEP-4f05) — NodeBB supports soft deletion. When content is deleted, a

   Delete

   activity with a

   Tombstone

   object is sent rather than simply disappearing.

9. Custom emojis (FEP-9098) — NodeBB supports federated custom emoji. Remote emoji in posts and chats are rendered (since v4.7.0).

10. Content in Uncategorized has no

    audience

    — manually discovered content landing in the Uncategorized pseudo-category may not have a proper

    audience

    property pointing to a Group actor. This content is not Announced to followers.