opacacms 0.1.3 → 0.1.4

package/README.md

@@ -0,0 +1,1063 @@
+# OpacaCMS
+
+> An experimental, runtime-agnostic headless CMS built with TypeScript. Define your schema, access control, and business logic directly in code — no visual builders, no lock-in.
+
+OpacaCMS runs natively on **Node.js, Bun, Cloudflare Workers, and Next.js** using [Hono](https://hono.dev) for routing. The schema you define becomes both your database tables and your REST API, automatically.
+
+---
+
+## Table of Contents
+
+- [Getting Started](#getting-started)
+- [Project Structure](#project-structure)
+- [Configuration](#configuration)
+- [Collections](#collections)
+- [Field Types](#field-types)
+- [Globals](#globals)
+- [Access Control](#access-control)
+- [Hooks](#hooks)
+- [Authentication](#authentication)
+- [Database Adapters](#database-adapters)
+- [Migrations](#migrations)
+- [Storage (File Uploads)](#storage-file-uploads)
+- [Internationalization (i18n)](#internationalization-i18n)
+- [Custom Admin Components](#custom-admin-components)
+- [The Client SDK](#the-client-sdk)
+- [Runtime Integrations](#runtime-integrations)
+- [CLI Reference](#cli-reference)
+- [Production Build](#production-build)
+
+---
+
+## Getting Started
+
+**Requirements:** [Bun](https://bun.sh) (recommended) or Node.js 18+.
+
+```bash
+# Scaffold a new project
+bunx opacacms init my-cms
+
+cd my-cms
+bun install
+bun dev
+```
+
+To add OpacaCMS to an **existing** project:
+
+```bash
+bun add opacacms
+```
+
+---
+
+## Project Structure
+
+```
+my-cms/
+├── opacacms.config.ts   ← schema + database + auth configuration
+├── migrations/          ← generated migration files
+├── opaca-types.d.ts     ← generated TypeScript types (optional)
+├── collections/         ← your collection definitions
+│   ├── posts.ts
+│   └── products.ts
+├── globals/             ← your global definitions
+│   └── site-settings.ts
+└── src/
+    └── index.ts         ← runtime entry point
+```
+
+---
+
+## Configuration
+
+Everything is defined in `opacacms.config.ts` and exported as the **default export**.
+
+```typescript
+// opacacms.config.ts
+import { defineConfig } from 'opacacms';
+import { createSQLiteAdapter } from 'opacacms/db/sqlite';
+import { posts } from './collections/posts';
+import { siteSettings } from './globals/site-settings';
+
+export default defineConfig({
+  appName: 'My Blog',
+  serverURL: 'http://localhost:3000',
+  secret: process.env.OPACA_SECRET,
+  db: createSQLiteAdapter('local.db'),
+  collections: [posts.build()],
+  globals: [siteSettings.build()],
+});
+```
+
+> `defineConfig` validates your configuration at startup and throws a descriptive error if anything is misconfigured.
+
+### Full config options
+
+| Option           | Type                             | Description                                   |
+| ---------------- | -------------------------------- | --------------------------------------------- |
+| `appName`        | `string`                         | Displayed in the admin UI                     |
+| `serverURL`      | `string`                         | The public URL of your application            |
+| `secret`         | `string`                         | Signs auth tokens — use an env variable       |
+| `db`             | `DatabaseAdapter`                | Required. Your database adapter               |
+| `collections`    | `Collection[]`                   | Your data schemas (call `.build()` on each)   |
+| `globals`        | `Global[]`                       | Singleton documents (call `.build()` on each) |
+| `storages`       | `Record<string, StorageAdapter>` | Named file storage buckets                    |
+| `auth`           | `OpacaAuthConfig`                | Auth strategies & features                    |
+| `api`            | `ApiConfig`                      | Rate limiting, max pagination limit           |
+| `i18n`           | `{ locales, defaultLocale }`     | Localization                                  |
+| `trustedOrigins` | `string[]`                       | For CORS and cookie security                  |
+
+---
+
+## Collections
+
+A **Collection** maps directly to a database table and generates a full REST API automatically. Collections are defined using the **Collection Builder** from `opacacms/schema`.
+
+```typescript
+// collections/posts.ts
+import { Collection, Field } from 'opacacms/schema';
+
+export const posts = Collection.create('posts') // slug → /api/posts
+  .label('Blog Posts')
+  .icon('FileText')
+  .useAsTitle('title')
+  .versions({ drafts: true, maxRevisions: 10 })
+  .admin({
+    defaultColumns: ['title', 'slug', '_status', 'createdAt'],
+    views: [
+      { name: 'Published', filter: { _status: { equals: 'published' } } },
+      { name: 'Drafts', filter: { _status: { equals: 'draft' } } },
+    ],
+  })
+  .fields([
+    Field.text('title').localized().required(),
+    Field.slug('slug').from('title').unique(),
+    Field.richText('content').localized(),
+    Field.relationship('author').to('_users').single().displayField('name'),
+    Field.select('category')
+      .choices(['News', 'Tutorial', 'Review'])
+      .defaultValue('News'),
+    Field.date('publishedAt').label('Published At'),
+  ]);
+```
+
+Register in your config:
+
+```typescript
+// opacacms.config.ts
+import { posts } from './collections/posts';
+
+export default defineConfig({
+  collections: [posts.build()],
+});
+```
+
+### Collection Builder — all methods
+
+| Method                    | Description                                     |
+| ------------------------- | ----------------------------------------------- |
+| `Collection.create(slug)` | Start a new collection                          |
+| `.label(string)`          | Display name in the admin UI                    |
+| `.icon(IconName)`         | Lucide icon for the sidebar                     |
+| `.useAsTitle(fieldName)`  | Which field acts as the document title          |
+| `.timestamps(bool)`       | Add `createdAt` / `updatedAt` (default: `true`) |
+| `.fields([...])`          | Define fields — see [Field Types](#field-types) |
+| `.access(rules)`          | Collection-level access control                 |
+| `.versions(opts)`         | Enable drafts & revisions                       |
+| `.webhooks([...])`        | Outbound HTTP callbacks on lifecycle events     |
+| `.admin(opts)`            | Admin UI settings (columns, views, etc.)        |
+| `.virtual(name, opts)`    | Add a computed field (not stored in DB)         |
+| `.computed(name, opts)`   | Alias for `.virtual()`                          |
+| `.build()`                | Compile to the raw config object                |
+
+### Auto-generated API
+
+For a collection with slug `posts`:
+
+| Method   | Endpoint         | Description                |
+| -------- | ---------------- | -------------------------- |
+| `GET`    | `/api/posts`     | List documents (paginated) |
+| `GET`    | `/api/posts/:id` | Get single document        |
+| `POST`   | `/api/posts`     | Create document            |
+| `PATCH`  | `/api/posts/:id` | Update document            |
+| `DELETE` | `/api/posts/:id` | Delete document            |
+
+**Query parameters:** `?page=1&limit=10&sort=createdAt:desc&populate=author&locale=pt-BR`
+
+**Filtering:** `GET /api/posts?title[like]=%TypeScript%&_status[equals]=published`
+
+---
+
+## Field Types
+
+All fields are constructed with `Field` from `opacacms/schema`. Every field starts with `Field.<type>(name)` and supports a fluent modifier chain.
+
+### Common modifiers — available on all fields
+
+```typescript
+Field.text('title')
+  .label('Article Title')
+  .required() // NOT NULL
+  .unique() // UNIQUE constraint
+  .localized() // stored per-locale
+  .defaultValue('Untitled')
+  .readOnly() // non-editable in admin
+  .hidden() // hidden from admin UI
+  .placeholder('Enter title…')
+  .admin({ description: 'The article title', width: '50%' })
+  .validate((val) => val.length > 3 || 'Too short');
+```
+
+### Primitives
+
+```typescript
+Field.text('title').required();
+Field.textarea('bio').placeholder('Tell us about yourself…');
+Field.number('price').min(0).max(99999).defaultValue(0);
+Field.boolean('active').defaultValue(true).label('Is Active?');
+Field.date('publishedAt');
+Field.json('metadata');
+```
+
+### Slug
+
+```typescript
+Field.slug('slug').from('title').unique();
+// 'My Article' → 'my-article'
+```
+
+### Select & Radio
+
+```typescript
+Field.select('status').choices(['draft', 'published', 'archived']);
+
+Field.select('role').choices([
+  { label: 'Admin', value: 'admin' },
+  { label: 'Editor', value: 'editor' },
+  { label: 'Viewer', value: 'viewer' },
+]);
+
+Field.radio('tier').choices([
+  { label: 'Free', value: 'free' },
+  { label: 'Pro', value: 'pro' },
+  { label: 'Enterprise', value: 'enterprise' },
+]);
+```
+
+### Rich Text
+
+```typescript
+Field.richText('body').localized();
+// defaultMode: 'notion' (block-based) | 'simple' (toolbar)
+```
+
+### File Upload
+
+```typescript
+Field.file('avatar')
+  .bucket('default') // key in config.storages
+  .allowedmime_types(['image/jpeg', 'image/png', 'image/webp'])
+  .maxSize(5 * 1024 * 1024); // 5 MB
+```
+
+The uploaded file URL is stored inline in the document:
+
+```json
+{
+  "avatar": {
+    "url": "https://cdn.example.com/photo.jpg",
+    "filename": "photo.jpg",
+    "mime_type": "image/jpeg",
+    "filesize": 204800
+  }
+}
+```
+
+### Relationship
+
+```typescript
+// Single reference
+Field.relationship('author').to('_users').single().displayField('name');
+
+// hasMany — creates a join table automatically
+Field.relationship('tags').to('tags').many();
+
+// Type-safe reference to another Collection builder
+import { products } from './products';
+Field.relationship('related').to(products).many();
+```
+
+### Join (virtual inverse relationship)
+
+```typescript
+// Lists documents from another collection that reference this one
+Field.join('comments').collection('comments').on('post_id');
+```
+
+### Group (nested object)
+
+Flattened as `preferences__theme` in the database, returned as `{ preferences: { theme } }` in the API.
+
+```typescript
+Field.group('preferences').fields(
+  Field.select('theme').choices(['light', 'dark', 'system']),
+  Field.boolean('notifications').defaultValue(true),
+);
+```
+
+### Blocks (dynamic content sections)
+
+Each block type gets its own table. The API returns them as a single ordered array.
+
+```typescript
+Field.blocks('content').blocks(
+  Field.block('hero')
+    .label('Hero Section')
+    .fields(
+      Field.text('headline').required(),
+      Field.text('subheadline'),
+      Field.text('ctaLabel'),
+      Field.text('ctaLink'),
+    ),
+  Field.block('featureGrid')
+    .label('Feature Grid')
+    .fields(
+      Field.text('sectionTitle'),
+      Field.number('columns').defaultValue(3),
+    ),
+);
+```
+
+### Layout fields (admin only — no database column)
+
+```typescript
+// Side-by-side columns
+Field.row().fields(
+  Field.text('firstName').required(),
+  Field.text('lastName').required(),
+);
+
+// Tabbed sections
+Field.tabs()
+  .tab('Content', Field.text('title').required(), Field.textarea('description'))
+  .tab('SEO', Field.text('metaTitle'), Field.textarea('metaDescription'));
+
+// Collapsible section
+Field.collapsible()
+  .label('SEO Metadata')
+  .initiallyCollapsed()
+  .fields(
+    Field.text('metaTitle'),
+    Field.textarea('metaDescription'),
+    Field.text('canonicalUrl'),
+  );
+```
+
+### Virtual / Computed
+
+Computed at request time — never written to the database:
+
+```typescript
+export const users = Collection.create('users')
+  .fields([
+    Field.text('firstName').required(),
+    Field.text('lastName').required(),
+  ])
+  .virtual('fullName', {
+    label: 'Full Name',
+    returnType: 'string',
+    resolve: ({ data }) => `${data.firstName} ${data.lastName}`,
+  });
+```
+
+---
+
+## Globals
+
+A **Global** is a singleton document (one row in the database). Perfect for site settings, navigation, or any app-wide configuration.
+
+```typescript
+// globals/site-settings.ts
+import { Global, Field } from 'opacacms/schema';
+
+export const siteSettings = Global.create('site-settings')
+  .label('Site Settings')
+  .icon('Settings')
+  .fields([
+    Field.text('siteName').required().defaultValue('My Site'),
+    Field.text('email').required(),
+    Field.text('phone'),
+  ]);
+
+// globals/header.ts
+export const headerSettings = Global.create('header')
+  .label('Header')
+  .icon('Layout')
+  .fields([
+    Field.text('siteTitle').required(),
+    Field.json('navItems').label('Navigation Items'),
+  ]);
+```
+
+Register in your config:
+
+```typescript
+export default defineConfig({
+  globals: [siteSettings.build(), headerSettings.build()],
+});
+```
+
+### Global Builder — all methods
+
+| Method                   | Description                                           |
+| ------------------------ | ----------------------------------------------------- |
+| `Global.create(slug)`    | Start a new global                                    |
+| `.label(string)`         | Admin display name                                    |
+| `.icon(IconName)`        | Lucide icon                                           |
+| `.timestamps(bool/opts)` | Enable/disable or rename timestamps (default: `true`) |
+| `.fields([...])`         | Field definitions                                     |
+| `.access(rules)`         | Who can read / update this global                     |
+| `.virtual(name, opts)`   | Add a computed field                                  |
+| `.build()`               | Compile to the raw config object                      |
+
+**API endpoints:**
+
+| Method  | Endpoint                     | Description         |
+| ------- | ---------------------------- | ------------------- |
+| `GET`   | `/api/globals/site-settings` | Read the document   |
+| `PATCH` | `/api/globals/site-settings` | Update the document |
+
+---
+
+## Access Control
+
+Access can be defined at the **collection level** and at the **field level**.
+
+### Collection-level access
+
+```typescript
+export const orders = Collection.create('orders')
+  .fields([...])
+  .access({
+    read:   ({ user }) => !!user,
+    create: ({ user }) => user?.role === 'admin',
+    update: ({ user, data }) => user?.id === data?.userId,
+    delete: false,
+  });
+```
+
+The `access` function receives: `{ req, user, session, apiKey, data, operation }`.
+
+### Field-level access
+
+```typescript
+Field.number('creditScore').access({
+  readOnly: ({ user }) => user?.role !== 'admin',
+});
+
+Field.textarea('internalNotes').access({
+  hidden: ({ user }) => user?.role !== 'admin', // stripped from API responses
+});
+```
+
+### Requiring API keys
+
+```typescript
+export const webhooks = Collection.create('webhooks')
+  .access({ requireApiKey: true })
+  .fields([...]);
+```
+
+---
+
+## Hooks
+
+Run async logic during a document's lifecycle. Hooks can transform data before it is written or trigger side effects after.
+
+```typescript
+export const posts = Collection.create('posts')
+  .fields([
+    Field.text('title').required(),
+    Field.slug('slug').from('title').unique(),
+    Field.number('views'),
+  ])
+  .hooks({
+    beforeCreate: async (data) => {
+      data.views = 0;
+      return data;
+    },
+    afterCreate: async (doc) => {
+      await notifySlack(`New post: ${doc.title}`);
+    },
+    beforeUpdate: async (data) => data,
+    afterUpdate: async (doc) => {
+      /* ... */
+    },
+    beforeDelete: async (id) => {
+      /* ... */
+    },
+    afterDelete: async (id) => {
+      /* ... */
+    },
+  });
+```
+
+### Webhooks
+
+```typescript
+export const products = Collection.create('products')
+  .webhooks([
+    {
+      events: ['afterCreate', 'afterUpdate', 'afterDelete'],
+      url: 'https://api.example.com/webhooks/cms',
+      headers: { 'X-Secret': process.env.WEBHOOK_SECRET! },
+    },
+  ])
+  .fields([...]);
+```
+
+---
+
+## Authentication
+
+OpacaCMS uses [better-auth](https://better-auth.com) under the hood. Auth tables (`_users`, `_sessions`, etc.) are created automatically by migrations.
+
+```typescript
+export default defineConfig({
+  auth: {
+    strategies: {
+      emailPassword: true,
+      magicLink: {
+        enabled: true,
+        sendEmail: async ({ email, url }) => {
+          await sendTransactionalEmail({ to: email, loginUrl: url });
+        },
+      },
+    },
+    socialProviders: {
+      github: {
+        clientId: process.env.GITHUB_CLIENT_ID!,
+        clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+      },
+    },
+    features: {
+      apiKeys: { enabled: true },
+    },
+  },
+});
+```
+
+Auth endpoints are at `/api/auth/*`. The Admin UI provides a built-in login page.
+
+### API Keys
+
+When `apiKeys` is enabled, clients can authenticate using `Authorization: Bearer <key>` instead of cookies — useful for server-to-server calls and webhooks.
+
+---
+
+## Database Adapters
+
+Install only the adapter you need:
+
+```typescript
+// SQLite (zero config, great for development)
+import { createSQLiteAdapter } from 'opacacms/db/sqlite';
+db: createSQLiteAdapter('local.db');
+
+// SQLite via better-sqlite3 (synchronous, faster reads)
+import { createBetterSQLiteAdapter } from 'opacacms/db/better-sqlite';
+db: createBetterSQLiteAdapter('local.db');
+
+// Bun's built-in SQLite
+import { createBunSQLiteAdapter } from 'opacacms/db/bun-sqlite';
+db: createBunSQLiteAdapter('local.db');
+
+// PostgreSQL
+import { createPostgresAdapter } from 'opacacms/db/postgres';
+db: createPostgresAdapter(process.env.DATABASE_URL);
+
+// Cloudflare D1
+import { createD1Adapter } from 'opacacms/db/d1';
+db: createD1Adapter(env.DB);
+```
+
+### Push mode (development only)
+
+```typescript
+db: createPostgresAdapter(process.env.DATABASE_URL, {
+  push: process.env.NODE_ENV !== 'production',
+  pushDestructive: false, // if true, drops stale columns/tables
+});
+```
+
+---
+
+## Migrations
+
+For production, use file-based migrations instead of push mode.
+
+### 1. Generate migration files
+
+```bash
+bunx opacacms migrate:create initial-schema
+# → migrations/20260319120000_initial-schema.ts  (Postgres/SQLite)
+# → migrations/20260319120000_initial-schema.sql  (Cloudflare D1)
+```
+
+The generated file has zero external dependencies — no need to install `kysely`:
+
+```typescript
+// migrations/20260319120000_initial-schema.ts
+import type { OpacaMigrationDb } from 'opacacms/db';
+
+export async function up(db: OpacaMigrationDb): Promise<void> {
+  await db.schema
+    .createTable('posts')
+    .addColumn('id', 'text', (col) => col.primaryKey())
+    .addColumn('title', 'text', (col) => col.notNull())
+    .addColumn('slug', 'text', (col) => col.unique())
+    .addColumn('created_at', 'text', (col) =>
+      col.defaultTo('CURRENT_TIMESTAMP'),
+    )
+    .addColumn('updated_at', 'text', (col) =>
+      col.defaultTo('CURRENT_TIMESTAMP'),
+    )
+    .execute();
+}
+
+export async function down(db: OpacaMigrationDb): Promise<void> {
+  await db.schema.dropTable('posts').execute();
+}
+```
+
+### 2. Apply migrations
+
+```bash
+bunx opacacms migrate
+```
+
+### 3. Check status
+
+```bash
+bunx opacacms migrate:status
+```
+
+### Cloudflare D1
+
+```bash
+# Apply locally (dev)
+bunx opacacms migrate:d1 --local --binding DB
+
+# Apply to production
+bunx opacacms migrate:d1 --remote --binding DB
+```
+
+---
+
+## Storage (File Uploads)
+
+Define storage buckets in your config. Reference them by name in `Field.file()`.
+
+### S3 / AWS
+
+```typescript
+import { createS3Adapter } from 'opacacms/storage/s3';
+
+storages: {
+  default: createS3Adapter({
+    region: process.env.AWS_REGION!,
+    bucket: process.env.S3_BUCKET!,
+    credentials: {
+      accessKeyId:     process.env.AWS_ACCESS_KEY_ID!,
+      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+    },
+    publicUrl: 'https://cdn.example.com',
+  }),
+}
+```
+
+### Cloudflare R2
+
+```typescript
+import { createR2Adapter } from 'opacacms/storage/r2';
+
+storages: {
+  default: createR2Adapter({
+    bucketBinding: env.BUCKET,
+    publicUrl: 'https://assets.example.com',
+  }),
+  secure: createR2Adapter({
+    bucketBinding: env.SECURE_BUCKET,
+    publicUrl: 'https://assets.example.com',
+  }),
+}
+```
+
+### Local filesystem (development)
+
+```typescript
+import { createLocalAdapter } from 'opacacms/storage/local';
+
+storages: {
+  default: createLocalAdapter({
+    directory: './public/uploads',
+    publicUrl: 'http://localhost:3000/uploads',
+  }),
+}
+```
+
+---
+
+## Internationalization (i18n)
+
+```typescript
+export default defineConfig({
+  i18n: {
+    locales: ['en', 'pt-BR', 'es'],
+    defaultLocale: 'pt-BR',
+  },
+});
+```
+
+Mark individual fields as localized with `.localized()`:
+
+```typescript
+Field.text('title').localized().required();
+Field.richText('body').localized();
+Field.text('slug'); // not localized — same value across all locales
+```
+
+The API resolves the locale from the `x-opaca-locale` header or `?locale=` query param, falling back to `defaultLocale`. Pass `?locale=all` to get all locales at once.
+
+---
+
+## Custom Admin Components
+
+You can replace any field's input or table cell with your own component. This works with **any framework** — React, Vue, Vanilla JS — by implementing the `defineCustomField` adapter.
+
+### 1. Register a custom field tag
+
+```typescript
+// src/admin/my-components.ts
+import { defineCustomField } from 'opacacms/admin';
+import { createRoot } from 'react-dom/client';
+import MyColorPicker from './MyColorPicker';
+
+defineCustomField('my-color-picker', {
+  mount(container, props) {
+    (container as any)._root = createRoot(container);
+    (container as any)._root.render(<MyColorPicker {...props} />);
+  },
+  update(container, props) {
+    (container as any)._root.render(<MyColorPicker {...props} />);
+  },
+  unmount(container) {
+    (container as any)._root.unmount();
+  },
+});
+```
+
+The `props` object your component receives:
+
+| Prop          | Type            | Description                                 |
+| ------------- | --------------- | ------------------------------------------- |
+| `value`       | `any`           | Current field value                         |
+| `onChange`    | `(val) => void` | Call to update the value                    |
+| `fieldConfig` | `object`        | The field's schema definition               |
+| `disabled`    | `boolean`       | True if access control disabled the field   |
+| `readOnly`    | `boolean`       | True if access control made it read-only    |
+| `error`       | `string?`       | Validation error message                    |
+| `parentData`  | `object?`       | All other field values in the same document |
+
+### 2. Reference in the schema
+
+```typescript
+Field.text('primaryColor').admin({
+  components: {
+    Field: 'my-color-picker', // used in the edit form
+    Cell: 'my-color-cell', // used in the collection list table
+  },
+});
+```
+
+### 3. Load your script
+
+Your custom component script must be loaded in the browser before the admin UI mounts. For Cloudflare Workers, serve the file as a static asset and include it as a `<script>` tag in the admin HTML page. For Next.js, import it in your admin layout.
+
+---
+
+## The Client SDK
+
+Use the typed client to query your CMS from any frontend:
+
+```typescript
+import { createClient } from 'opacacms/client';
+
+const cms = createClient({ baseURL: 'https://my-cms.example.com' });
+
+// List with filtering and pagination
+const result = await cms.collections.posts.find({
+  '_status[equals]': 'published',
+  limit: 10,
+  page: 1,
+});
+console.log(result.docs); // array of documents
+console.log(result.totalPages);
+
+// Single document
+const post = await cms.collections.posts.findOne('abc-123');
+
+// Create / Update / Delete
+const newPost = await cms.collections.posts.create({ title: 'Hello' });
+await cms.collections.posts.update('abc-123', { title: 'Updated' });
+await cms.collections.posts.delete('abc-123');
+
+// Globals
+const settings = await cms.globals['site-settings'].get();
+await cms.globals['site-settings'].update({ siteName: 'New Name' });
+```
+
+### Typed client with generated types
+
+```bash
+bunx opacacms generate:types --url http://localhost:3000 --out opaca-types.d.ts
+```
+
+```typescript
+import { createClient } from 'opacacms/client';
+import type { GeneratedTypes } from './opaca-types';
+
+const cms = createClient<GeneratedTypes>({ baseURL: '...' });
+
+// IDE autocomplete now knows the exact shape of every collection
+const post = await cms.collections.posts.findOne('123');
+// post.title → string ✓
+```
+
+---
+
+## Runtime Integrations
+
+### Next.js
+
+Create a catch-all API route:
+
+```
+src/app/api/[[...route]]/route.ts
+```
+
+```typescript
+// src/app/api/[[...route]]/route.ts
+import { createNextHandler } from 'opacacms/runtimes/next';
+import config from '../../../opacacms.config';
+
+export const { GET, POST, PUT, PATCH, DELETE, OPTIONS } =
+  createNextHandler(config);
+```
+
+```typescript
+// opacacms.config.ts
+import { defineConfig } from 'opacacms';
+import { createPostgresAdapter } from 'opacacms/db/postgres';
+
+export default defineConfig({
+  appName: 'My Next.js CMS',
+  serverURL: process.env.NEXT_PUBLIC_API_URL!,
+  secret: process.env.OPACA_SECRET!,
+  db: createPostgresAdapter(process.env.DATABASE_URL!),
+  collections: [
+    /* posts.build(), ... */
+  ],
+});
+```
+
+Serve the Admin UI from a Next.js page:
+
+```tsx
+// src/app/admin/[[...all]]/page.tsx
+export default function AdminPage() {
+  return (
+    <html>
+      <body>
+        <opaca-admin server-url={process.env.NEXT_PUBLIC_API_URL} />
+        <script type="module" src="/opacacms/webcomponent.js" />
+      </body>
+    </html>
+  );
+}
+```
+
+---
+
+### Cloudflare Workers
+
+```typescript
+// src/index.ts
+import { createCloudflareWorkersHandler } from 'opacacms/runtimes/cloudflare-workers';
+import getConfig from './opacacms.config';
+
+const app = createCloudflareWorkersHandler(getConfig);
+
+// Serve the Admin UI for /admin/* routes
+app.get('/admin*', (c) => {
+  return c.html(`
+    <!DOCTYPE html>
+    <html>
+      <head>
+        <title>Admin</title>
+        <link rel="stylesheet" href="/admin.css">
+      </head>
+      <body>
+        <opaca-admin server-url="${new URL(c.req.url).origin}"></opaca-admin>
+        <script type="module" src="/webcomponent.js"></script>
+      </body>
+    </html>
+  `);
+});
+
+export default app;
+```
+
+```typescript
+// opacacms.config.ts
+import { defineConfig } from 'opacacms';
+import { createD1Adapter } from 'opacacms/db/d1';
+import { createR2Adapter } from 'opacacms/storage/r2';
+
+// Export as a function to access per-request Cloudflare bindings
+const getConfig = (env: Env, request: Request) =>
+  defineConfig({
+    appName: 'My Workers CMS',
+    serverURL: new URL(request.url).origin,
+    secret: env.OPACA_SECRET,
+    trustedOrigins: ['https://my-frontend.com'],
+    db: createD1Adapter(env.DB),
+    storages: {
+      default: createR2Adapter({
+        bucketBinding: env.BUCKET,
+        publicUrl: new URL(request.url).origin,
+      }),
+    },
+    auth: {
+      features: { apiKeys: { enabled: true } },
+    },
+    i18n: {
+      locales: ['en', 'pt-BR'],
+      defaultLocale: 'pt-BR',
+    },
+    collections: [
+      /* posts.build(), ... */
+    ],
+    globals: [
+      /* siteSettings.build(), ... */
+    ],
+  });
+
+export default getConfig;
+```
+
+```jsonc
+// wrangler.jsonc
+{
+  "name": "my-cms",
+  "compatibility_date": "2024-09-23",
+  "d1_databases": [
+    { "binding": "DB", "database_name": "my-cms-db", "database_id": "..." },
+  ],
+  "r2_buckets": [{ "binding": "BUCKET", "bucket_name": "my-cms-assets" }],
+}
+```
+
+---
+
+### Bun (standalone)
+
+```typescript
+// src/index.ts
+import { createBunHandler } from 'opacacms/runtimes/bun';
+import config from './opacacms.config';
+
+const { init } = createBunHandler(config, { port: 3000 });
+await init();
+```
+
+---
+
+### Node.js
+
+```typescript
+// src/index.ts
+import { createNodeHandler } from 'opacacms/runtimes/node';
+import config from './opacacms.config';
+
+const { init } = createNodeHandler(config, { port: 3000 });
+await init();
+```
+
+---
+
+## CLI Reference
+
+The CLI auto-detects your config at `opacacms.config.ts`, `src/opacacms.config.ts`, or `index.ts`.
+
+```bash
+# Scaffold a new project
+bunx opacacms init my-project
+
+# Generate migrations from your current schema
+bunx opacacms migrate:create <name>
+
+# Apply pending migrations (Postgres / SQLite)
+bunx opacacms migrate
+
+# Check which migrations have been applied
+bunx opacacms migrate:status
+
+# Apply SQL migrations to Cloudflare D1
+bunx opacacms migrate:d1 --local   # local dev
+bunx opacacms migrate:d1 --remote  # production
+
+# Seed the database with fake data
+bunx opacacms seed --count 50
+bunx opacacms seed:assets --count 20
+
+# Generate TypeScript types from a running instance
+bunx opacacms generate:types --url http://localhost:3000 --out opaca-types.d.ts
+
+# Use a custom config file path
+bunx opacacms migrate:create --config ./path/to/config.ts
+```
+
+---
+
+## Production Build
+
+### Disable push mode
+
+```typescript
+db: createPostgresAdapter(process.env.DATABASE_URL, {
+  push: false, // never auto-alter schema in production
+});
+```
+
+### Required environment variables
+
+```bash
+OPACA_SECRET=<random-32-char-string>    # required
+DATABASE_URL=postgres://...             # for Postgres
+```
+
+### Deploy flow
+
+```bash
+# Generate + apply migrations
+bunx opacacms migrate:create latest
+bunx opacacms migrate            # Postgres / SQLite
+# or
+bunx opacacms migrate:d1 --remote  # Cloudflare D1
+
+# Start the server
+node dist/index.js
+# or
+wrangler deploy
+```

package/dist/{chunk-ry15hke8.js → chunk-yr32cp7h.js}

@@ -1249,7 +1249,6 @@ function createDatabaseInitMiddleware(config, state) {
 }
 
 // src/server/middlewares/rate-limit.ts
-import { WorkersKVStore } from "@hono-rate-limiter/cloudflare";
 import { rateLimiter } from "hono-rate-limiter";
 function createRateLimitMiddleware(config) {
   const rateLimitConfig = config.api?.rateLimit;
@@ -1277,7 +1276,10 @@ function createRateLimitMiddleware(config) {
     if (!resolvedStore && c.env) {
       const kvBindingKey = Object.keys(c.env).find((key) => key.startsWith("OPACA_") && c.env[key]?.put && c.env[key]?.get);
       if (kvBindingKey) {
-        resolvedStore = new WorkersKVStore({ namespace: c.env[kvBindingKey] });
+        try {
+          const { WorkersKVStore } = await import("@hono-rate-limiter/cloudflare");
+          resolvedStore = new WorkersKVStore({ namespace: c.env[kvBindingKey] });
+        } catch (_) {}
       }
     }
     const limiter = rateLimiter({

package/dist/runtimes/bun.js

@@ -1,6 +1,6 @@
 import {
   createAPIRouter
-} from "../chunk-ry15hke8.js";
+} from "../chunk-yr32cp7h.js";
 import"../chunk-62ev8gnc.js";
 import"../chunk-cvdd4eqh.js";
 import"../chunk-ybbbqj63.js";

package/dist/runtimes/cloudflare-workers.js

@@ -1,6 +1,6 @@
 import {
   createAPIRouter
-} from "../chunk-ry15hke8.js";
+} from "../chunk-yr32cp7h.js";
 import"../chunk-62ev8gnc.js";
 import"../chunk-cvdd4eqh.js";
 import"../chunk-ybbbqj63.js";

package/dist/runtimes/next.js

@@ -1,6 +1,6 @@
 import {
   createAPIRouter
-} from "../chunk-ry15hke8.js";
+} from "../chunk-yr32cp7h.js";
 import"../chunk-62ev8gnc.js";
 import"../chunk-cvdd4eqh.js";
 import"../chunk-ybbbqj63.js";

package/dist/runtimes/node.js

@@ -1,6 +1,6 @@
 import {
   createAPIRouter
-} from "../chunk-ry15hke8.js";
+} from "../chunk-yr32cp7h.js";
 import"../chunk-62ev8gnc.js";
 import"../chunk-cvdd4eqh.js";
 import"../chunk-ybbbqj63.js";

package/dist/server.js

@@ -4,7 +4,7 @@ import {
   createGlobalHandlers,
   createHandlers,
   hydrateDoc
-} from "./chunk-ry15hke8.js";
+} from "./chunk-yr32cp7h.js";
 import {
   defineConfig
 } from "./chunk-zvwb67nd.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opacacms",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "sideEffects": false,
   "scripts": {
     "build": "bun run ../../scripts/build.ts && tsc --emitDeclarationOnly",
@@ -145,11 +145,13 @@
     }
   },
   "devDependencies": {
+    "@better-auth/core": "^1.5.5",
     "@cloudflare/workers-types": "^4.20260313.1",
     "@faker-js/faker": "^10.3.0",
     "@happy-dom/global-registrator": "^20.8.4",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
+    "@types/better-sqlite3": "^7.6.13",
     "@types/bun": "latest",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
@@ -262,8 +264,6 @@
   },
   "dependencies": {
     "@better-auth/api-key": "^1.5.5",
-    "@better-auth/core": "^1.5.5",
-    "@types/better-sqlite3": "^7.6.13",
     "better-auth": "^1.5.5",
     "hono": "^4.12.7",
     "ky": "^1.14.3",