Skip to Content
Documentation

Run a Community Forum

Enable the @vitnode/forum plugin, create forums in AdminCP, choose who publishes straight away, and let members post topics and nested comments.

@vitnode/forum adds a community forum to a VitNode app: a tree of forums, topics inside them and Reddit-style nested comments. It is built only from Content Engine pieces - a container for the forums, two content types and a thread - so everything you learn here works the same way in your own plugins.

Lives in the monorepo

The plugin is private: true and ships with the VitNode repository, like the newsroom plugin. It is not published to npm yet.

Enable the API plugin

Add the API factory to vitnode.api.config.ts - in apps/web for a single app, and in apps/api too for a split deployment.

apps/web/src/vitnode.api.config.ts
import { forumApiPlugin } from "@vitnode/forum/config.api"; 

export const vitNodeApiConfig = buildApiConfig({
  plugins: [
    forumApiPlugin(), 
  ],
});

Enable the web plugin

The web factory brings the pages, the AdminCP Forums screen and the translations.

apps/web/src/vitnode.config.ts
import { forumPlugin } from "@vitnode/forum/config"; 

export const vitNodeConfig = buildConfig({
  plugins: [
    forumPlugin(), 
  ],
});

Migrate and start

The plugin owns two tables, forum_topics and forum_comments. Run the migrations, then start the app.

Migrate and start the forum
bun run db:migrate
bun dev

Create your forums

In AdminCP, open Forums and create a few. Forums nest up to four levels deep, and you can drag them to reorder. A forum's Icon accepts the same icon:name or emoji value as role prefixes.

Pages members get

PageWhat it does
/forumEvery forum with its topic and comment counts and its newest topic
/forum/:slugSubforums and the topics of one forum, newest first
/forum/create/topicStart a topic (signed-in members)
/forum/topics/:slugThe topic, its nested comments, and a comment box
/forum/topics/:id/editEdit your own topic
/forum/comments/:slugPermalink of one comment - redirects to its place in the topic
/forum/me/pendingYour posts a moderator approved, declined, or has not looked at yet

Comments nest up to six levels - hit Reply under any comment to answer it. On small screens deep comments stop indenting, so the text keeps its width, and every branch can be collapsed. A comment removed by a moderator stays as "This comment was removed." when it has public replies, so the conversation keeps its shape.

The forum index, forum and topic pages are cached for a minute and refreshed in the background. Edit buttons and the comment box load in the browser, so every visitor gets the same cached page. The comment editor itself waits for a click on Write a comment…, so readers who only read never download it.

Topic and comment counts are cached too when Redis is configured (REDIS_URL). Any new, published, hidden, moved or deleted topic or comment expires them on the spot, and a five-minute limit catches anything that changed behind the forum's back, such as a row edited by hand. Topic lists leave out the topic body, so GET /api/@vitnode/forum/content/topics returns titles, slugs and dates only - read one topic for its body. Topic pages set a canonical URL and DiscussionForumPosting structured data with the comment count.

Topics also have delivery: a renamed topic redirects its old address to the new one, and /api/@vitnode/forum/content/topics/delivery/sitemap lists every public topic for your sitemap.xml. Topics waiting for approval never appear there, in search or in any list - until a moderator says yes, they don't exist for anyone but their author.

Topics and comments show up in search, on /discover and on their authors' profile timelines. A comment is headed by its topic's title and stays out of public results while its topic is not public - see Borrow the title from a related record. Upgrading a forum that already has posts? Rebuild the index once in Debug Panel → Search (/admin/core/debug/search).

Choose who publishes straight away

By default every member's topic and comment goes live immediately and authors can edit their posts for as long as they like. Change that per forum in the forum's Publishing settings - for example, require approval for new topics in Announcements, or let authors edit comments for one hour only. A forum inherits from its parent until you override a value. See Container policies for every option.

When a post needs approval, the author sees "Waiting for a moderator", and the post appears on /forum/me/pending. Moderators with the Approve permission for that forum review it in ModCP. See Approvals.

Grant moderators a forum

AdminCP only manages the forums themselves. Topics and comments live on the public forum: authors edit their own, and moderators step in right there or in ModCP.

Moderator permissions for topics and comments are scoped by forum. Give a moderator role Edit and Approve on Topics and Comments, and pick the forums it covers - a single forum, or a forum and everything below it. See Scoped permissions.