@nexpress/plugin-forum

Multi-board forum plugin for NexPress. It combines native board/post collections, member writes, moderation, rich text, public/member/private audiences, daily-unique views, recommendations, bounded popular feeds, comments, validated member attachments, optional signed contextual Q&A with official answers, and theme-neutral build-time skins.

Install

pnpm add @nexpress/plugin-forum

Generated projects receive Forum through the framework defaults. The standalone forumCollections and forumPlugin exports remain available, while framework defaults use one paired factory result and additionally wire optional Shop product inquiries. For a custom path, collection names, skin catalog, or contextual source, use one paired factory result:

import { defineConfig } from "@nexpress/core";
import { createForum } from "@nexpress/plugin-forum";

const forum = createForum({
  basePath: "/boards",
  defaultSkinId: "community-full",
});

export default defineConfig({
  collections: [...forum.collections],
  plugins: [forum.plugin],
});

Generate and apply the two collection tables, then create and publish a board from Admin → Community → Forum boards:

pnpm schema:gen && pnpm db:generate && pnpm db:migrate

The default routes are /boards, /boards/:boardKey, member create/edit routes, and UUID-based post detail URLs. A selected skin renders the board index, post list, detail, and route-owned create/edit content without taking over authentication or write policy. Boards and posts support public, signed-in-member, and private audiences; a post cannot be broader than its board, and narrowing a board waits until its existing posts are equally restrictive. Members can write only board, title, body, category, audience, and attachment fields; pin, lock, status, board policy, and moderation stay operator-owned. Board lists include bounded title/body search, category and member filters, canonical filter-preserving pagination, and notices that stay out of filtered results. List and detail surfaces share batched view, visible comment, and reaction totals; the detail recommendation button uses the same Core reaction contract as comments.

Published posts readable by the current member expose a report action. Reports use the configured post collection slug, reject duplicate unresolved filings, surface target context in Admin, and resolve through closed dismiss/unpublish actions.

Each board can enable attachments and set an exact file-count and per-file size cap. Uploads reuse Core media storage, verify extension/MIME/signature, remain uploader-only while unreferenced, and inherit the audience of every referencing document. They are served only as forced sandboxed downloads. Both bundled skins render the same attachment count, detail list, and route-owned composer controls.

Forum can also reuse an ordinary member-write board for contextual questions. Its one-hour NP_SECRET proof binds the site, board, source type/id, label, and local path; the proof is removed before persistence. Forum keeps ownership of audience, moderation, attachments, answers, and author notifications. The default Shop bridge expects a published product-questions board and otherwise renders nothing. See the live guide for the independent Forum/Shop factory wiring and custom-path source options.

Two bundled skins are always available: classic for the familiar compact table and community-full for policy summaries, author identity, status-rich rows, numbered pagination, detailed post metadata, comments, and composers. Both work with any theme. Forum structure ships in @layer np-blocks and reads core theme tokens with documented --np-forum-* override properties, so a theme can enhance the plugin without importing it and the plugin remains fully usable without that theme.

Post detail routes localize the shared framework comment surface rather than owning a parallel comment implementation. Each page receives batched public author profiles and viewer reaction summaries and supports nested replies, member-owned edit/delete, reporting, muting, sorting, and bounded pagination. Skins and themes can enhance the stable .np-comment-* and data-np-comment-* hooks independently.

Forum post collections also opt into the shared public member-profile activity contract. Only published, public-audience posts and their visible comments appear under /u/:handle; pending, member-only, and private targets are absent from both counts and pages. The route and Core own that projection, so skins and themes consume prepared activity rather than importing or querying forum collections.

The plugin also registers forum.board-directory and forum.post-feed blocks plus a forum.community-home pattern. They use the forum factory's configured paths and collection slugs internally, expose only published public-audience rows from active public boards, and give themes stable data/style hooks without making either package depend on the other. The post feed supports latest, notices, and a 1–90 day popular mode over at most 200 recent candidates.

See the full forum guide for board settings, skin authoring, policy behavior, and current scope.

License

MIT