Introduction

timbl is a schema-defined, headless CMS framework for TypeScript. It owns content modeling, validation, persistence, and the generated API. It does not own your frontend, your routing, or your presentation layer.

What timbl does

• Content modeling: Define collections and globals with typed fields in content.config.ts. The schema is the source of truth.
• Validation: Every write runs through schema validation before it reaches the database.
• Persistence: A swappable database adapter handles storage. SQLite with Drizzle is the default.
• HTTP API: A JSON REST API is generated from your schema, with OpenAPI docs at /docs.
• Authentication: A swappable auth adapter handles sessions and principals. Better Auth is the default.
• Storage: A swappable storage adapter handles uploads. Local storage is the default.
• Plugins: Extend schema, add routes, register hooks, and contribute query extensions.
• Type safety: The client SDK infers types from your config, so frontend code is typed without bundling the runtime.

Why timbl

Most CMS options force a tradeoff. You get an admin UI and lose control of your data shape, or you get code-first schema and lose the editing experience. timbl takes the second path deliberately: schema is code, the API is generated from it, and the admin UI is a future concern, not a tax you pay now.

The other tradeoff is lock-in. Pick a CMS and you usually pick its database, its auth, its storage, and its frontend framework. timbl makes each of those replaceable through a contract, so you can swap SQLite for Postgres or Better Auth for Clerk without rewriting your schema or your frontend.

What timbl does not do

• It does not render your frontend. Your Astro site, Next.js app, or mobile client consumes the API.
• It does not ship an admin UI in v1. Writes go through the API or the client SDK.
• It does not own your deployment. Run it anywhere that runs Bun.

Packages

Package	Purpose
timbl	Primary runtime and schema authoring package
@timbl/core	Lower-level schema, plugin, query, and adapter contracts
@timbl/client	Typed framework-agnostic REST client
@timbl/adapter-better-auth	Official Better Auth integration
@timbl/plugin-rss	Official RSS feed plugin
@timbl/plugin-seo	Official SEO field extension plugin

Start here

If you are new, go through Quick Start to get a CMS running in five minutes. Then read Content Model to understand collections, globals, fields, and relations.

If you are integrating with a frontend, jump to Client SDK or the Astro and Next.js kitchen sink examples.

If you are extending the runtime, read Extension Model and the Plugins guide.

Defaults

timbl ships with opinionated defaults so you can start without configuring infrastructure. Each default is replaceable through a documented adapter contract.

• Runtime: Bun
• HTTP delivery: Hono
• Database: SQLite with Drizzle
• Storage: local filesystem
• Auth: Better Auth
• Logging: Pino

See Architecture for the package boundaries and API Tiers for which surfaces are stable.