TabletopDOCS
Getting started

Node

Define a site with @tbtop/cms and serve it on Node, Bun or Cloudflare Workers.

Alpha

The Node package is in alpha: its API may change between minor versions. Pin an exact version and read the changelog before you upgrade.

@tbtop/cms is the CMS core for Node, Bun and Cloudflare Workers: pages, blocks and SEO over your Kysely database, edited in the Node build of @tbtop/admin. It is meant for new projects: it owns its tbtop_* tables and does not share a database with the Laravel package.

The frontend is headless. Your framework (TanStack Start, Hono with React, Astro…) asks the CMS for a page's props and renders them; @tbtop/cms/react has the React half.

Install

npm install @tbtop/cms @tbtop/admin kysely

Node 22+ or Bun. React, better-auth, @tbtop/inertia-admin and @json-render/* are optional peers, needed only for the parts that use them.

Define the site

A site is a set of records made of fields. One description gives the admin form, the zod schema and the TypeScript type, so the three cannot drift.

site.ts
// Client-safe: the browser imports `site.catalog` from this file.
import { block, defineSite, f, hero, pageType } from "@tbtop/cms/site";

export const site = defineSite({
	blocks: {
		Hero: hero,
		Quote: block({ text: f.textarea().translatable(), by: f.text() }, { label: "Quote" }),
	},
	pages: {
		page: { tagline: f.text() }, // extends the built-in `page` type
		post: pageType({ author: f.text(), readingTime: f.number() }, { label: "Post", jsonLd: "BlogPosting" }),
	},
	settings: { Company: { phone: f.text() } }, // tabs of the Site settings page
});

Fields are f.text, textarea, richtext, number, boolean, date, select, tags, image, link, pages, collection and repeater. Each takes .label(), .helperText(), .translatable() and .required().

Serve it

server.ts
import { serve } from "@tbtop/cms/serve";
import { site } from "./site";

export default serve(site, { db, render, renderError });

serve wires sign-in (Better Auth over your db), the admin panel, robots, sitemaps and form posts, then hands every page to your render. On the first request it migrates the database, creates the error pages and the first admin.

The first admin

Set these before the first start (on Workers, as wrangler secret put secrets):

VariablePurpose
BETTER_AUTH_SECRETRequired; the app refuses to start without it
TBTOP_ADMIN_EMAIL, TBTOP_ADMIN_PASSWORDThe first admin, created only while the site has no admin

The admin opens at /admin. Once it exists, rotate the password on the Users page; changing the variables no longer changes anything.

Deploy on a VPS

Run tbtop-cms migrate on each release and tbtop-cms scheduled from cron every minute. Both read the default export of cms.config.ts (or --config). Without the scheduled task, form submissions stay pending and nobody is notified.

Next

The package README covers page types, collections, link fields, the React renderer, forms, caching and what the alpha does not have yet: packages/node. Guides on this site follow.

On this page