@qentrah/cms

Documentation · Install guide

Provider-neutral Qentrah headless CMS framework for Node.js, Vercel, and Cloudflare

These guides describe the published 3.0.0-beta.29 package. The examples use the APIs and files in that release; beta packages should be kept on matching versions.

Documentation

• Install and verify
• Define collections
• Configure providers and plugins
• API and exports
• Troubleshooting

Install and verify

Before you start

• node: >=18.0.0.

Use a project with a package.json. Check the runtime and package manager:

node --version
npm --version

Install the documented version

npm install @qentrah/[email protected]

Confirm the installation

npm ls @qentrah/cms

The output should show @qentrah/[email protected]. Commit the lockfile so another developer installs the same dependency tree.

Peer dependencies

Install compatible peers in the consuming application. These ranges come from the published manifest.

| Package | Required range | | --- | --- | | zod | ^3.0.0 || ^4.0.0 | | hono | ^4.0.0 | | drizzle-orm | ^0.44.0 | | @cloudflare/workers-types | ^4.0.0 || ^5.0.0 |

Create an application

npx create-qentrah@beta my-qentrah
cd my-qentrah
npm run dev

Install the runtime directly

npm install @qentrah/cms@beta hono drizzle-orm zod

import { createQentrahApp, registerCollections } from '@qentrah/cms'
import type { QentrahConfig } from '@qentrah/cms'

const config: QentrahConfig = {
  name: 'My CMS',
}

registerCollections([
  {
    name: 'article',
    displayName: 'Article',
    slug: 'articles',
    kind: 'collection',
    schema: {
      type: 'object',
      properties: {
        title: { type: 'string', title: 'Title', required: true },
        body: { type: 'lexical', title: 'Body' },
      },
      required: ['title'],
    },
    managed: true,
    isActive: true,
  },
])

export default createQentrahApp(config)

Expected result

The factory exports a Hono application. Hosting, database bindings, migrations, storage, and authentication still need to be configured by the consuming application. Creating the object alone does not provision a database.

Define collections

npm install @qentrah/cms@beta hono drizzle-orm zod

import { createQentrahApp, registerCollections } from '@qentrah/cms'
import type { QentrahConfig } from '@qentrah/cms'

const config: QentrahConfig = {
  name: 'My CMS',
}

registerCollections([
  {
    name: 'article',
    displayName: 'Article',
    slug: 'articles',
    kind: 'collection',
    schema: {
      type: 'object',
      properties: {
        title: { type: 'string', title: 'Title', required: true },
        body: { type: 'lexical', title: 'Body' },
      },
      required: ['title'],
    },
    managed: true,
    isActive: true,
  },
])

export default createQentrahApp(config)

Schema responsibilities

registerCollections registers collection metadata. Give each collection a stable name and slug, define its schema and required properties, and decide whether it is managed and active. The example uses a string title and Lexical body. A schema registration does not by itself establish access permissions or complete a deployment migration.

Read content from an app

Use the separate @qentrah/sdk package for a typed client. Relations and media are not populated by default in the CMS. Make population explicit in the server query contract instead of assuming related records are always embedded.

Configure providers and plugins

Configure the app factory

import { createQentrahApp, type QentrahConfig } from "@qentrah/cms";

const config: QentrahConfig = {
  name: "My CMS",
  plugins: { register: [] },
};
export default createQentrahApp(config);

Configuration map

| Field | Purpose | | --- | --- | | providers | Runtime-specific persistence, storage and related adapters | | collections | Collection directory and synchronization settings | | plugins.register | Explicit plugin list | | plugins.disableAll | Disable both core and user plugins and plugin bootstrapping | | email | Custom provider or built-in resend, sendgrid, or console | | routes | Path and Hono handler pairs | | middleware.beforeAuth / afterAuth | Middleware around authentication | | auth.extendBetterAuth | Extend authentication configuration | | version / name | Application identity |

Provider selection

Choose adapters for the actual target runtime. The package includes database support for SQLite, D1, PostgreSQL and Neon, and storage support for local files, S3-compatible storage and R2. Required bindings, credentials and migrations are supplied by the consuming deployment.

Email fallback

An explicitly supplied email provider takes precedence. A named built-in can use its environment settings; otherwise the implementation checks provider environment variables and falls back to the console provider. Console delivery logs messages rather than sending email. Configure a real provider before relying on password-reset or magic-link delivery.

Explicit plugin registration

plugins.directory and plugins.autoLoad are deprecated no-ops. Put plugin instances in plugins.register; plugin routes are mounted before the admin catch-all.

API and exports

Package identity

| Field | Value | | --- | --- | | Package | @qentrah/cms | | Version inspected | 3.0.0-beta.29 | | License | MIT | | Module type | module |

Public import paths

| Import path | Published target | | --- | --- | | @qentrah/cms | ./dist/index.d.ts | | @qentrah/cms/types | ./dist/types.d.ts | | @qentrah/cms/utils | ./dist/utils.d.ts | | @qentrah/cms/routes | ./dist/routes.d.ts | | @qentrah/cms/plugins | ./dist/plugins.d.ts | | @qentrah/cms/adapters | ./dist/adapters.d.ts | | @qentrah/cms/services | ./dist/services.d.ts | | @qentrah/cms/templates | ./dist/templates.d.ts | | @qentrah/cms/middleware | ./dist/middleware.d.ts | | @qentrah/cms/package.json | ./package.json |

CLI entry points

• qentrah-db-reset → bin/db-reset.js.

Inspect the original release

Open the versioned npm page or download its published archive. The archive includes the actual executable files and declarations used to write these guides.

Troubleshooting

Check the installed version

npm ls @qentrah/cms

Compare the installed version with the version noted in this guide. Inspect your lockfile before changing dependencies; prerelease behavior may differ between versions.

Import or module errors

Use only public import paths listed in API and exports. Avoid importing guessed paths inside dist. ESM-only packages require an ESM-aware application. Install declared peer dependencies in the consuming application.

Application starts but persistence fails

Check the configured runtime provider and database bindings before making content requests. The app factory does not provision credentials or schema. Use the consuming application’s documented migrations. Do not use the qentrah-db-reset command as a generic recovery step: it resets data.

Plugin routes are missing

Register plugins explicitly with plugins.register. The directory and autoLoad fields are deprecated no-ops; a Worker does not have a filesystem to scan.

Release documentation

Documentation checked against the previously published package artifact. This documentation-only release preserves executable files and dependencies.