@we8/cms

@we8/cms is the core headless CMS of the we8 package: a Hono application carrying the content, forms, analytics, media, and SEO modules behind the /api/v1 public API that every frontend consumes. It is single-site by construction (one site, one worker, one database, one bucket), it validates public pk and sk API keys itself, and it owns the AEO backend that is its headline feature: llms.txt publishing, answer-oriented content fields, AEO check endpoints, and crawler attribution.

Auth is not built in. The CMS knows what an owner may do and what a member may do; who somebody is comes from a provider your worker registers in one line. @we8/auth is the embedded one (Better Auth over your own D1, email and password), and it is what npm create we8 composes. Register nothing and every /api/v1/admin/* request is refused: an unconfigured deploy is a locked site, never an open one.

import cms, { registerAdminAuth } from '@we8/cms';
import { embeddedAdminAuth } from '@we8/auth';

registerAdminAuth(embeddedAdminAuth);

export default cms;

Requirements

• Runs on Cloudflare Workers. Deploy it with @we8/cloudflare and wrangler (what npm create we8 sets up), or with your own Worker config.
• Bindings: a D1 database as DB, an R2 bucket as MEDIA, and optionally static assets as ASSETS for the admin portal.
• An admin auth provider, registered by your worker. @we8/auth is the embedded one and requires the secret BETTER_AUTH_SECRET.
• Secrets: TURNSTILE_SECRET is optional, and only enforced for forms that enable Turnstile.
• Runtime dependencies, bundled at deploy: hono and zod. Node 20 or newer for the tooling around it.

Local development

cp .dev.vars.example .dev.vars   # then set a real BETTER_AUTH_SECRET
npm run db:migrate               # apply the migrations to the local D1
npm run db:seed                  # a working site: settings, a post, a form, dev keys
npm run dev                      # http://localhost:8787

The seed publishes two development API keys in plain text, which is what makes local curl calls possible. Never run it against a real deployment.

curl http://localhost:8787/api/v1/health
curl http://localhost:8787/llms.txt
curl -H "X-We8-Key: pk_live_000000000000000000000000000000000000000000000000" \
  http://localhost:8787/api/v1/posts

npm run dev runs the composed worker in dev/index.ts, which registers the embedded provider, so local development behaves like a scaffolded project. npm run db:migrate applies both migration directories: this package's, and the one @we8/auth ships.

GET /api/v1/auth/mode says which mode a worker is in (embedded, external, or none) and whether the first account can still be created.

Create the owner account by signing up once; the endpoint closes as soon as an account exists.

curl -X POST http://localhost:8787/api/auth/sign-up/email \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"a-long-enough-password","name":"You"}'

Serving the admin portal

This worker can serve the admin portal from its own origin, so the SPA, the API, and the session cookie all share one host and nothing is cross-origin.

npm run build --workspace @we8/admin-app   # build the portal
npm run admin:bundle                       # copy it into ./public
npm run dev                                # the portal is now at /

./public is the worker's static-asset root and ships empty. A deployment that skips those two steps serves no assets and runs API-only, which is the headless install; the SPA fallback in src/spa.ts stands down on its own when there is no bundle behind the binding.

Bindings

DB (D1) and MEDIA (R2), plus the vars SITE_URL and CMS_VERSION. TURNSTILE_SECRET, EMAIL_MODE, EMAIL_FROM, and API_PREFIX are optional, and ASSETS is the optional static-asset binding that carries the admin portal. API_PREFIX moves the whole API off its default /api/v1 mount and renames nothing; set it only when something else already owns /api on this origin. An auth provider adds its own: @we8/auth requires BETTER_AUTH_SECRET and takes an optional AUTH_URL.

Upgrading from 0.1

0.2 makes auth optional, and that is the whole breaking change. The core no longer embeds Better Auth; a provider is composed in src/index.ts instead.

1. Update every @we8/* dependency to ^0.2.0. To keep exactly the 0.1 behavior, add @we8/auth and register it in your worker entry:

   import cms, { registerAdminAuth, registerEmailSender } from '@we8/cms';
   import { embeddedAdminAuth } from '@we8/auth';
   import { cloudflareEmailSender } from '@we8/cloudflare';
   
   registerAdminAuth(embeddedAdminAuth);
   registerEmailSender(cloudflareEmailSender);
   
   export default cms;

2. Run npm run db:migrate (locally, then db:migrate:remote). The auth tables now belong to @we8/auth, whose migrations are written to be safe on a database that already carries them: existing users, sessions, and content are untouched.

3. Run npx we8-cloudflare doctor. It knows the auth modes and names anything still missing.

4. Optionally, refresh the project's agent skill: npx we8-cloudflare skill.

A worker that registers no provider refuses every /api/v1/admin/* request with a 403 explaining the two ways forward. To run without @we8/auth, compose cloudflareAccessAdminAuth() or perimeterAdminAuth({ acknowledged: true }) from @we8/cloudflare instead; their README documents both.

More

• @we8/auth: the embedded admin sign-in, as its own package.
• create-we8: the fastest path from nothing to a working site; the README it writes into your project carries every step.
• GET /api/v1/openapi.json on any install: the full /v1 contract, live, keyless, and always in sync with the code serving it.
• @we8/client and @we8/astro: the typed ways to consume it.