Crap CMS

Crap CMS is a headless content management system built in Rust. It combines a compiled core with Lua hooks (neovim-style) and an overridable HTMX admin UI.

Motivation

I built several Rust/WebAssembly frontend projects and couldn’t find a CMS that fit the stack. So I built one.

The idea: a simple CMS written in Rust, extensible via a lightweight scripting language, with no complicated build steps or infrastructure requirements.

Inspiration came from what I consider the best solutions out there:

• Lua scripting API — modeled after Neovim and Awesome WM, where Lua gives users deep control without touching core code
• Configuration & hook system — inspired by Payload CMS, an excellent and highly recommended CMS for anyone needing a production-ready solution
• CLI tooling — influenced by Laravel’s comprehensive Artisan CLI
• SQLite + WAL + FTS — sufficient for most of my use cases, and it bundles cleanly into a single binary with zero external dependencies. The database layer is abstracted behind a trait, so alternative relational backends could be added in the future if the need arises
• Pure JavaScript with JSDoc types — no TypeScript, no bundler, no build step. Type safety through JSDoc annotations, checkable with tsc --checkJs without compiling anything
• HTMX + Web Components — easy to theme (similar to WordPress child themes), no frontend build step. Web Components are a native browser standard — no framework updates, no outdated dependencies, no breaking changes
• gRPC API — binary protocol with streaming support, ideal for service-to-service communication. And because I wanted it. A separate REST proxy is available for those who prefer plain JSON over HTTP

The project is functional but not yet production-ready — it still needs to prove itself.

Warning: While in alpha (0.x), breaking changes may appear without prior notice.

Design Philosophy

• Lua is the single source of truth for schemas. Collections and fields are defined in Lua files, not in the database. The database stores content, not structure.
• Single binary. The admin UI (Axum) and gRPC API (Tonic) run in one process on two ports.
• Config directory pattern. All customization lives in one directory, auto-detected from CWD (or set explicitly with --config/-C).
• No JS build step. The admin UI uses Handlebars templates + HTMX with plain CSS.
• Hooks are the extension system. Lua hooks at three levels (field, collection, global) provide full lifecycle control with transaction-safe CRUD access.

Feature Set

• Collections with 20 field types (text, number, textarea, richtext, select, radio, checkbox, date, email, json, code, relationship, array, group, upload, blocks, row, collapsible, tabs, join)
• Globals — single-document collections for site-wide settings
• Hooks — field-level, collection-level, and globally registered lifecycle hooks
• Access Control — collection-level and field-level, with filter constraint support
• Authentication — JWT sessions, password login, custom auth strategies, email verification, password reset
• Uploads — file uploads with automatic image resizing and format conversion (WebP, AVIF)
• Relationships — has-one and has-many with configurable population depth
• Localization — per-field opt-in localization with locale-suffixed columns
• Versions & Drafts — document version history with draft/publish workflow
• Live Updates — real-time mutation events via SSE and gRPC streaming
• Admin UI — template overlay system, theme switching, Web Components
• gRPC API — full CRUD with filtering, pagination, and server reflection
• CLI Tooling — interactive scaffolding wizard, blueprints, data export/import, backups

Tech Stack

Installation

Static Binary

Pre-built static binaries are attached to each GitHub Release. No runtime dependencies required.

curl -L -o crap-cms \
  https://github.com/dkluhzeb/crap-cms/releases/latest/download/crap-cms-linux-x86_64
chmod +x crap-cms
sudo mv crap-cms /usr/local/bin/

Available binaries:

Docker

docker run -p 3000:3000 -p 50051:50051 \
  ghcr.io/dkluhzeb/crap-cms:latest serve -C /example

Images are Alpine-based (~30 MB) and published to ghcr.io/dkluhzeb/crap-cms. See the README for production usage and available tags.

Building from Source

Requires a Rust toolchain (edition 2024) via rustup and a C compiler:

git clone https://github.com/dkluhzeb/crap-cms.git
cd crap-cms
cargo build --release

The binary is at target/release/crap-cms. SQLite and Lua are bundled — no system libraries needed.

Optional Tools

• grpcurl — for testing the gRPC API from the command line. See grpcurl installation.
• lua-language-server (LuaLS) — for IDE autocompletion in Lua config files. The project provides type definitions in types/crap.lua.

Quick Start

1. Scaffold a new project

The fastest way to get started is the interactive init wizard:

crap-cms init ./my-project

The wizard walks you through:

1. Admin port (default: 3000)
2. gRPC port (default: 50051)
3. Localization — enable and choose locales (e.g., en, de, fr)
4. Auth collection — creates a users collection with email/password login
5. First admin user — prompts for email and password right away
6. Upload collection — creates a media collection for file/image uploads
7. Additional collections — keep adding as many as you need

A JWT auth secret is auto-generated and written to crap.toml so tokens survive restarts.

When it finishes you’ll have a ready-to-run config directory:

my-project/
├── crap.toml
├── init.lua
├── .luarc.json
├── .gitignore
├── collections/
│   ├── users.lua
│   └── media.lua
├── globals/
├── hooks/
├── migrations/
├── templates/
├── static/
├── types/
│   └── crap.lua
├── data/
└── uploads/

2. Start the server

cd my-project
crap-cms serve

This starts:

• Admin UI at http://localhost:3000/admin
• gRPC API at localhost:50051

3. Log in to the admin UI

Visit http://localhost:3000/admin/login and sign in with the credentials you created during init.

If you skipped user creation during init, bootstrap one now:

# Interactive (prompts for password)
crap-cms user create -e admin@example.com

# Non-interactive
crap-cms user create \
    -e admin@example.com \
    -p secret123 \
    -f role=admin \
    -f name="Admin User"

4. Create content via gRPC

Use grpcurl to interact with the API. The server supports reflection, so no proto import is needed:

# List all posts
grpcurl -plaintext localhost:50051 crap.ContentAPI/Find \
    -d '{"collection": "posts"}'

# Create a post
grpcurl -plaintext localhost:50051 crap.ContentAPI/Create \
    -d '{
      "collection": "posts",
      "data": {
        "title": "Hello World",
        "slug": "hello-world",
        "status": "draft",
        "content": "My first post."
      }
    }'

Alternative: Run with the example config

The repository includes an example/ config directory with sample collections, useful if you’re building from source:

git clone https://github.com/dkluhzeb/crap-cms.git
cd crap-cms
cargo build --release
./target/release/crap-cms serve -C ./example

Then bootstrap an admin user:

crap-cms user create -C ./example -e admin@example.com

Config Directory

All customization lives in a single config directory. When you run CLI commands from inside this directory (or a subdirectory), the config is auto-detected by walking up and looking for crap.toml. You can also set it explicitly with --config/-C or the CRAP_CONFIG_DIR environment variable.

Directory Structure

my-project/
├── crap.toml              # Server/database/auth configuration
├── init.lua               # Runs at startup (register global hooks, etc.)
├── .luarc.json            # LuaLS config for IDE support
├── .gitignore             # Ignores data/, uploads/, types/ by default
├── collections/           # One .lua file per collection
│   ├── posts.lua
│   ├── users.lua
│   └── media.lua
├── globals/               # One .lua file per global
│   └── site_settings.lua
├── hooks/                 # Lua modules referenced by hook strings
│   ├── posts.lua
│   └── access.lua
├── migrations/            # Custom SQL migrations (see `migrate` command)
├── templates/             # Handlebars overrides for admin UI
│   └── fields/
│       └── custom.hbs
├── translations/          # Admin UI translation overrides (JSON per locale)
│   └── de.json
├── static/                # Static file overrides (CSS, JS, fonts)
├── data/                  # Runtime data (auto-created)
│   ├── crap.db            # SQLite database
│   ├── crap.pid           # Process ID file (when running with --detach)
│   └── logs/              # Rotating log files (when [logging] file = true)
├── uploads/               # Uploaded files (auto-created per collection)
│   └── media/
└── types/                 # Auto-generated type definitions (see `typegen`)
    ├── crap.lua           # API surface types (crap.* functions)
    └── generated.lua      # Per-collection types (data, doc, hook, filters)

File Loading Order

1. crap.toml is loaded first (or defaults are used if absent)
2. collections/*.lua files are loaded alphabetically
3. globals/*.lua files are loaded alphabetically
4. init.lua is executed last

Lua Package Path

The config directory is prepended to Lua’s package.path:

<config_dir>/?.lua;<config_dir>/?/init.lua;...

This means require("hooks.posts") resolves to <config_dir>/hooks/posts.lua.

LuaLS Support

Create a .luarc.json in your config directory for IDE autocompletion:

{
    "runtime": { "version": "Lua 5.4" },
    "workspace": { "library": ["./types"] }
}

Generate type definitions with:

crap-cms typegen

This writes two files: types/crap.lua (API surface types for the crap.* functions) and types/generated.lua (per-collection types derived from your field definitions). Use -l all to generate types for all supported languages.

crap.toml

The crap.toml file configures the server, database, authentication, and other global settings. All sections and fields are optional — sensible defaults are used when omitted.

If no crap.toml file exists in the config directory, all defaults are used. An empty file is also valid — all defaults apply.

Top-Level Fields

Environment Variable Substitution

String values in crap.toml can reference environment variables using ${VAR} syntax:

[auth]
secret = "${JWT_SECRET}"

[database]
path = "${DB_PATH:-data/crap.db}"

[email]
smtp_pass = "${SMTP_PASSWORD}"

• ${VAR} — replaced with the value of VAR. Startup fails if VAR is not set.
• ${VAR:-default} — replaced with VAR if set and non-empty, otherwise uses default.

Substitution only applies to string values — ${VAR} patterns in comments are safely ignored.

This allows keeping secrets out of config files and varying configuration across environments.

Duration Values

Most time-related fields accept an integer (seconds), a human-readable string with a suffix, or a bare number string:

# These are all equivalent:
token_expiry = 7200
token_expiry = "7200"
token_expiry = "2h"

# Supported suffixes: s (seconds), m (minutes), h (hours), d (days)
poll_interval = "5s"
login_lockout_seconds = "5m"
auto_purge = "7d"

Fields that support this: token_expiry, login_lockout_seconds, reset_token_expiry, forgot_password_window_seconds, max_age, poll_interval, cron_interval, heartbeat_interval, auto_purge, grpc_rate_limit_window, connection_timeout, smtp_timeout, busy_timeout, request_timeout, grpc_timeout.

File Size Values

File size fields accept both an integer (bytes) and a human-readable string:

# These are equivalent:
max_file_size = 52428800
max_file_size = "50MB"

# Supported suffixes (case-insensitive, 1024-based):
# B (bytes), KB (kilobytes), MB (megabytes), GB (gigabytes)
max_file_size = "500B"
max_file_size = "100KB"
max_file_size = "1GB"

Fields that support this: max_file_size (global and per-collection), max_memory, http_max_response_bytes, grpc_max_message_size.

Configuration Validation

crap.toml is validated at startup. Fatal validation errors prevent the server from starting with a descriptive error message. Non-fatal issues log warnings.

Fatal errors:

• database.pool_max_size = 0
• database.connection_timeout = 0
• hooks.vm_pool_size = 0
• server.admin_port or server.grpc_port is 0
• server.admin_port == server.grpc_port (ports must be distinct)
• auth.password_policy.min_length > auth.password_policy.max_length

Warnings (server starts but logs a warning):

• jobs.max_concurrent = 0 — no jobs will execute
• auth.secret is set but shorter than 32 characters
• depth.max_depth = 0 — all population requests capped to 0

Full Reference

# Optional: warn if the running binary doesn't match this version
# crap_version = "0.1.0"

[server]
admin_port = 3000       # Admin UI port
grpc_port = 50051       # gRPC API port
host = "0.0.0.0"        # Bind address
# public_url = "https://cms.example.com"  # Public-facing base URL for generated links
# h2c = false           # Enable HTTP/2 cleartext (for reverse proxies)
# trust_proxy = false   # Trust X-Forwarded-For (enable behind reverse proxy)
# compression = "off"   # "off" (default), "gzip", "br", "all"
# grpc_reflection = false        # Enable gRPC server reflection (default: false)
# grpc_rate_limit_requests = 0   # Per-IP request limit (0 = disabled, recommended: 100)
# grpc_rate_limit_window = 60    # Sliding window in seconds (or "1m")
# grpc_max_message_size = "16MB" # Max gRPC message size (default 16MB)
# request_timeout = "30s"        # Admin HTTP request timeout (none by default)
# grpc_timeout = "30s"           # gRPC request timeout (none by default)

[database]
path = "data/crap.db"   # Relative to config dir, or absolute
pool_max_size = 32       # Max connections in the pool
busy_timeout = "30s"     # SQLite busy timeout (integer ms or "30s", "1m")
connection_timeout = 5   # Pool checkout timeout (seconds or "5s")

[admin]
dev_mode = false         # Reload templates per-request (enable in development)
require_auth = true      # Block admin when no auth collection exists (default: true)
# access = "access.admin_panel"  # Lua function: which users can access the admin UI

# [admin.csp]                    # Content-Security-Policy (enabled by default)
# enabled = true
# script_src = ["'self'", "'unsafe-inline'", "https://unpkg.com"]
# style_src = ["'self'", "'unsafe-inline'", "https://fonts.googleapis.com"]
# font_src = ["'self'", "https://fonts.gstatic.com"]
# img_src = ["'self'", "data:"]
# connect_src = ["'self'"]
# frame_ancestors = ["'none'"]
# form_action = ["'self'"]
# base_uri = ["'self'"]

[auth]
secret = ""              # JWT signing key. Empty = auto-generated and persisted to data/.jwt_secret
token_expiry = "2h"      # Default token expiry (accepts integer seconds or "2h", "30m", etc.)
max_login_attempts = 5   # Failed attempts per email before temporary lockout
max_ip_login_attempts = 20  # Failed attempts per IP before lockout (higher for shared IPs)
login_lockout_seconds = "5m"  # Lockout duration after max attempts
reset_token_expiry = "1h"    # Password reset token expiry
max_forgot_password_attempts = 3   # Forgot-password requests per email before rate limiting
forgot_password_window_seconds = "15m"  # Rate limit window for forgot-password

[auth.password_policy]
min_length = 8              # Minimum password length
max_length = 128            # Maximum password length (DoS protection)
# require_uppercase = false # Require at least one uppercase letter
# require_lowercase = false # Require at least one lowercase letter
# require_digit = false     # Require at least one digit
# require_special = false   # Require at least one special character

[depth]
default_depth = 1        # Default population depth for FindByID (Find always defaults to 0)
max_depth = 10           # Hard cap on population depth (prevents abuse)
# populate_cache = false           # Cross-request populate cache (opt-in)
# populate_cache_max_age_secs = 0  # Periodic cache clear for external DB mutations

[pagination]
default_limit = 20      # Default limit for Find queries (when none is specified)
max_limit = 1000         # Hard cap on limit — requests above this are clamped
# mode = "page"          # "page" (offset) or "cursor" (keyset)

[upload]
max_file_size = "50MB"   # Global max file size (accepts bytes or "50MB", "1GB", etc.)

[email]
smtp_host = ""           # SMTP server hostname. Empty = email disabled (no-op)
smtp_port = 587          # SMTP port (587 for STARTTLS, 465 for TLS, 25/1025 for plain)
smtp_user = ""           # SMTP username
smtp_pass = ""           # SMTP password
smtp_tls = "starttls"    # "starttls" (default), "tls" (implicit TLS), "none" (plain/test)
from_address = "noreply@example.com"  # Sender email address
from_name = "Crap CMS"  # Sender display name
# smtp_timeout = 30     # SMTP connection/send timeout in seconds (or "30s")

[hooks]
on_init = []             # Lua function refs to run at startup (with CRUD access)
# max_depth = 3          # Max hook recursion depth (0 = no hooks from Lua CRUD)
vm_pool_size = 8         # Number of Lua VMs for concurrent hook execution
                         # Default: max(available_parallelism, 4), capped at 32
max_instructions = 10000000  # Max Lua instructions per hook (0 = unlimited)
max_memory = "50MB"          # Max Lua memory per VM (0 = unlimited)
allow_private_networks = false  # Block HTTP requests to private/loopback IPs
http_max_response_bytes = "10MB"  # Max HTTP response body size

[live]
enabled = true           # Enable SSE + gRPC Subscribe for live mutation events
channel_capacity = 1024  # Broadcast channel buffer size
# max_sse_connections = 1000        # Max concurrent SSE connections (0 = unlimited)
# max_subscribe_connections = 1000  # Max concurrent gRPC Subscribe streams (0 = unlimited)

[locale]
default_locale = "en"    # Default locale code
locales = ["en", "de"]   # Supported locales (empty = disabled)
fallback = true          # Fall back to default locale if field is NULL

[jobs]
max_concurrent = 10          # Max concurrent job executions across all queues
poll_interval = "1s"         # How often to poll for pending jobs
cron_interval = "1m"         # How often to check cron schedules
heartbeat_interval = "10s"   # How often running jobs update their heartbeat
auto_purge = "7d"            # Auto-purge completed/failed runs older than this
image_queue_batch_size = 10  # Pending image conversions to process per poll

[access]
default_deny = false     # When true, deny all operations without explicit access functions

[cors]
allowed_origins = []     # Origins allowed for CORS. Empty = CORS disabled (default)
                         # Use ["*"] to allow any origin
allowed_methods = ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"]
allowed_headers = ["Content-Type", "Authorization"]
exposed_headers = []     # Response headers exposed to the browser
max_age = "1h"   # How long browsers cache preflight results
allow_credentials = false # Allow cookies/Authorization. Cannot use with ["*"] origins

[mcp]
# enabled = false         # Enable MCP server
# http = false            # Mount POST /mcp on admin server
# config_tools = false    # Enable config read/write tools
# api_key = ""            # API key for HTTP transport
# include_collections = [] # Only expose these collections
# exclude_collections = [] # Hide these collections

Section Details

[server]

[database]

[admin]

[admin.csp]

Content-Security-Policy header configuration for the admin UI. Each field is a list of CSP sources for the corresponding directive. Theme developers can extend these lists to allow external resources (CDNs, custom fonts, analytics, etc.).

Example: allowing a custom CDN and analytics:

[admin.csp]
script_src = ["'self'", "'unsafe-inline'", "https://unpkg.com", "https://cdn.example.com", "https://analytics.example.com"]
style_src = ["'self'", "'unsafe-inline'", "https://fonts.googleapis.com", "https://cdn.example.com"]
font_src = ["'self'", "https://fonts.gstatic.com", "https://cdn.example.com"]
img_src = ["'self'", "data:", "https://cdn.example.com"]
connect_src = ["'self'", "https://analytics.example.com"]

[auth]

[auth.password_policy]

Password strength requirements applied to all password-setting paths (create, update, reset, CLI).

[depth]

[pagination]

[upload]

[email]

When configured, email enables password reset (“Forgot password?” link on login), email verification (optional per-collection), and the crap.email.send() Lua API.

[hooks]

[live]

See Live Updates for full documentation.

[locale]

[jobs]

[access]

Enable this to enforce a “secure by default” posture — every collection must explicitly declare its access rules. Without it, collections without access functions are open to any authenticated (or anonymous) user.

[cors]

When CORS is enabled, the layer is added to both the admin UI (Axum) and gRPC API (Tonic) servers. CORS runs before CSRF middleware, so preflight OPTIONS requests get CORS headers without triggering CSRF validation.

[mcp]

See MCP Overview for usage details.

[logging]

File logging writes to rotating files in the configured directory. Each project has its own log directory, so multiple instances on the same machine are naturally isolated.

Use crap-cms logs to view log output, crap-cms logs -f to follow in real time, and crap-cms logs clear to remove old rotated files. See the CLI Reference for details.

When locales are configured, any field with localized = true in its Lua definition gets one column per locale (title__en, title__de) instead of a single title column. The API accepts a locale parameter on Find, FindByID, Create, Update, GetGlobal, and UpdateGlobal to control which locale to read/write. The admin UI shows a locale selector in the edit sidebar.

Special locale values:

• "all" — returns all locales as nested objects: { title: { en: "Hello", de: "Hallo" } }
• Any locale code (e.g., "en", "de") — returns flat field names with that locale’s values
• Omitted — uses the default locale

Example

[server]
admin_port = 8080
grpc_port = 9090
host = "127.0.0.1"

[database]
path = "/var/lib/crap/production.db"

[admin]
dev_mode = false
# require_auth = true
# access = "access.admin_panel"

[auth]
secret = "a-very-long-random-string-for-jwt-signing"
token_expiry = "24h"
max_login_attempts = 10
login_lockout_seconds = "10m"

[depth]
default_depth = 1
max_depth = 5

[upload]
max_file_size = "100MB"

[email]
smtp_host = "smtp.example.com"
smtp_port = 587
smtp_user = "noreply@example.com"
smtp_pass = "your-smtp-password"
from_address = "noreply@example.com"
from_name = "My App"

[logging]
file = true
# path = "data/logs"
# rotation = "daily"
# max_files = 30

[hooks]
on_init = ["hooks.seed.run"]
vm_pool_size = 8
max_instructions = 10000000
max_memory = "50MB"
allow_private_networks = false
http_max_response_bytes = "10MB"

Localization

Crap CMS supports per-field localization, allowing content to be managed in multiple languages. Any field type can be marked localized, and the API returns data differently based on a locale parameter.

Configuration

Enable localization by adding a [locale] section to crap.toml:

[locale]
default_locale = "en"
locales = ["en", "de", "fr"]
fallback = true

When locales is empty (the default), localization is completely disabled and all behavior is unchanged.

Per-Field Opt-In

Mark individual fields as localized in your Lua definitions:

crap.collections.define("pages", {
    fields = {
        crap.fields.text({
            name = "title",
            required = true,
            localized = true,  -- this field has per-locale values
        }),
        crap.fields.text({
            name = "slug",
            required = true,
            -- not localized — single value shared across all locales
        }),
    },
})

Only fields with localized = true are affected. Non-localized fields behave exactly as before.

Storage

Localized fields use suffixed columns in SQLite:

• A field title with locales ["en", "de"] becomes columns title__en and title__de
• Non-localized fields keep their single column
• required is only enforced on the default locale column (title__en)
• unique checks the locale-specific column being written to (e.g., writing locale "de" checks title__de)
• Junction tables (arrays, blocks, has-many) get a _locale column

Unique + Localized

When a field has both unique = true and localized = true, uniqueness is enforced per locale. Two documents can have the same value in different locales, but not in the same locale:

crap.fields.text({
    name = "slug",
    unique = true,
    localized = true,
})

This also applies to fields inside a localized Group — uniqueness is checked against the fully suffixed column (e.g., seo__slug__en).

API Behavior

All read and write RPCs accept an optional locale parameter:

Reading

Flat response (single locale):

{ "title": "Hello World" }

Nested response (locale = "all"):

{ "title": { "en": "Hello World", "de": "Hallo Welt" } }

When fallback = true and a field is NULL for the requested locale, the default locale value is returned instead.

Writing

Writes target a single locale. The locale parameter determines which locale column to write to:

# Write German title
grpcurl -plaintext -d '{
  "collection": "pages",
  "id": "abc123",
  "locale": "de",
  "data": { "title": "Hallo Welt" }
}' localhost:50051 crap.ContentAPI/Update

Non-localized fields are always written to their single column regardless of the locale parameter.

Admin UI

When locales are configured, the admin edit page shows a locale selector in the sidebar. Clicking a locale tab reloads the form with that locale’s data. The save action writes to the selected locale.

When editing in a non-default locale, non-localized fields are shown as readonly with a “Shared Field” badge. This prevents accidentally overwriting values that are shared across all locales.

Lua API

Locale in CRUD Operations

All Lua CRUD functions accept an optional locale parameter:

-- Find with locale
local result = crap.collections.find("pages", { locale = "de" })

-- Find by ID with locale
local doc = crap.collections.find_by_id("pages", id, { locale = "de" })

-- Create in a specific locale
crap.collections.create("pages", data, { locale = "de" })

-- Update in a specific locale
crap.collections.update("pages", id, data, { locale = "de" })

-- Globals
local settings = crap.globals.get("site_settings", { locale = "de" })
crap.globals.update("site_settings", data, { locale = "de" })

Locale Configuration Access

-- Check if localization is enabled
if crap.locale.is_enabled() then
    local default = crap.locale.get_default()  -- "en"
    local all = crap.locale.get_all()           -- {"en", "de", "fr"}
end

Hook Context

The locale is available in hook context:

function M.before_change(ctx)
    if ctx.locale then
        print("Writing to locale: " .. ctx.locale)
    end
    return ctx
end

Admin Label Localization

Field labels, descriptions, placeholders, select option labels, block labels, and collection/global display names can all be localized. Instead of a plain string, provide a table keyed by locale:

crap.collections.define("pages", {
    labels = {
        singular = { en = "Page", de = "Seite" },
        plural = { en = "Pages", de = "Seiten" },
    },
    fields = {
        crap.fields.text({
            name = "title",
            required = true,
            localized = true,
            admin = {
                label = { en = "Title", de = "Titel" },
                placeholder = { en = "Enter page title", de = "Seitentitel eingeben" },
                description = { en = "The main heading", de = "Die Hauptüberschrift" },
            },
        }),
        crap.fields.select({
            name = "status",
            options = {
                { label = { en = "Draft", de = "Entwurf" }, value = "draft" },
                { label = { en = "Published", de = "Veröffentlicht" }, value = "published" },
            },
        }),
    },
})

Plain strings still work — they’re used as-is regardless of locale:

admin = { label = "Title", placeholder = "Enter title" }

The admin UI resolves labels based on default_locale from crap.toml.

Admin UI Translations

All built-in admin UI text (buttons, labels, headings, error messages) can be translated. The system uses a {{t "key"}} Handlebars helper that looks up translation strings.

Built-in English

English translations are compiled into the binary. No configuration needed for English.

Custom Translations

Place a JSON file at <config_dir>/translations/<locale>.json to override or add strings:

{
  "save": "Speichern",
  "delete": "Löschen",
  "create": "Neu erstellen",
  "cancel": "Abbrechen",
  "search_placeholder": "Suchen...",
  "collections": "Sammlungen",
  "globals": "Globale",
  "dashboard": "Übersicht"
}

The file must match your default_locale in crap.toml. Keys not present in the override file fall back to English.

Interpolation

Translation strings support {{variable}} placeholders:

{
  "page_of": "Seite {{page}} von {{total}}",
  "no_items_yet": "Keine {{name}} vorhanden"
}

Templates pass values as hash parameters: {{t "page_of" page=pagination.page total=pagination.total_pages}}.

Available Keys

See translations/en.json in the source tree for all available translation keys.

Backward Compatibility

• No [locale] config or empty locales = feature completely disabled
• No localized = true on fields = no locale columns created
• All existing behavior is preserved when localization is not configured
• Plain string labels/descriptions/placeholders work exactly as before

Command-Line Reference

crap-cms <COMMAND> [OPTIONS]

Use crap-cms --help to list all commands, or crap-cms <command> --help for details on a specific command.

Global Flags

Config Directory Resolution

Most commands need a config directory (the folder containing crap.toml). The CLI resolves it in this order:

1. --config / -C flag — explicit path, highest priority
2. CRAP_CONFIG_DIR environment variable — useful for CI/Docker
3. Auto-detection — walks up from the current working directory looking for crap.toml

If you cd into your project directory (or any subdirectory), commands just work without any flags:

cd my-project
crap-cms serve
crap-cms status
crap-cms user list

From elsewhere, use -C:

crap-cms -C ./my-project serve
crap-cms -C ./my-project status

Or set the environment variable:

export CRAP_CONFIG_DIR=./my-project
crap-cms serve

Commands

serve — Start the server

crap-cms serve [-d] [--stop] [--restart] [--status] [--json] [--only <admin|api>] [--no-scheduler]

--detach, --stop, --restart, and --status are mutually exclusive.

crap-cms serve                    # foreground
crap-cms serve -d                 # detached (background)
crap-cms serve --status           # is it running?
crap-cms serve --stop             # stop detached instance
crap-cms serve --restart          # stop + start detached
crap-cms serve --json
crap-cms serve --only admin       # admin UI only
crap-cms serve --only api         # gRPC API only
crap-cms serve --no-scheduler     # both servers, no scheduler
crap-cms serve --only admin --no-scheduler
crap-cms serve -d --only api      # detached, API only

status — Show project status

crap-cms status

Prints collections (with row counts), globals, DB size, and migration status.

user — User management

user create

crap-cms user create [-c <COLLECTION>] [-e <EMAIL>] [-p <PASSWORD>] [-f <KEY=VALUE>]...

# Interactive (prompts for password)
crap-cms user create -e admin@example.com

# Non-interactive
crap-cms user create \
    -e admin@example.com \
    -p secret123 \
    -f role=admin \
    -f name="Admin User"

user list

crap-cms user list [-c <COLLECTION>]

Lists all users with ID, email, locked status, and verified status (if email verification is enabled).

crap-cms user list
crap-cms user list -c admins

user info

crap-cms user info [-c <COLLECTION>] [-e <EMAIL>] [--id <ID>]

Shows detailed info for a single user: ID, email, locked/verified status, password status, timestamps, and all field values.

crap-cms user info -e admin@example.com
crap-cms user info --id abc123

user delete

crap-cms user delete [-c <COLLECTION>] [-e <EMAIL>] [--id <ID>] [-y]

user lock / user unlock

crap-cms user lock [-c <COLLECTION>] [-e <EMAIL>] [--id <ID>]
crap-cms user unlock [-c <COLLECTION>] [-e <EMAIL>] [--id <ID>]

user verify / user unverify

crap-cms user verify [-c <COLLECTION>] [-e <EMAIL>] [--id <ID>]
crap-cms user unverify [-c <COLLECTION>] [-e <EMAIL>] [--id <ID>]

Manually mark a user’s email as verified or unverified. Only works on collections with verify_email = true. Useful when email is not configured.

user change-password

Change a user’s password. Prompts for the new password if -p is omitted.

crap-cms user change-password [-c <COLLECTION>] [-e <EMAIL>] [--id <ID>] [-p <PASSWORD>]

init — Scaffold a new config directory

crap-cms init [DIR] [--no-input]

Runs an interactive wizard that scaffolds a complete config directory. Defaults to ./crap-cms if no directory is given.

The wizard prompts for:

A 64-character auth secret is auto-generated and written to crap.toml.

crap-cms init ./my-project

After scaffolding:

cd my-project
crap-cms serve

make — Generate scaffolding files

make collection

crap-cms make collection [SLUG] [-F <FIELDS>] [-T] [--auth] [--upload] [--versions] [--no-input] [-f]

Without --no-input, missing arguments (slug, fields) are collected via interactive prompts. The field survey asks for name, type, required, and localized (if localization is enabled).

Field shorthand syntax:

name:type[:modifier][:modifier]...

Modifiers are order-independent:

# Basic
crap-cms make collection posts

# With fields
crap-cms make collection articles \
    -F "title:text:required,body:richtext"

# With localized fields
crap-cms make collection pages \
    -F "title:text:required:localized,body:textarea:localized,slug:text:required"

# Auth collection
crap-cms make collection users --auth

# Upload collection
crap-cms make collection media --upload

# Non-interactive with versions
crap-cms make collection posts \
    -F "title:text:required,body:richtext" --versions --no-input

make global

crap-cms make global [SLUG] [-F <FIELDS>] [-f]

crap-cms make global site_settings
crap-cms make global nav -F "links:array(label:text:required,url:text)"

make hook

crap-cms make hook [NAME] [-t <TYPE>] [-c <COLLECTION>] [-l <POSITION>] [-F <FIELD>] [--force]

Missing flags are resolved via interactive prompts. The wizard lists collections and globals from the registry (globals are tagged). For non-interactive mode, the slug is auto-detected as a global if it exists in the globals registry.

Valid positions by type:

Generated hooks use per-collection typed annotations for IDE support:

• Collection hooks: crap.hook.Posts, crap.hook.global_site_settings
• Field hooks: crap.field_hook.Posts, crap.field_hook.global_site_settings
• Condition hooks: crap.data.Posts, crap.global_data.SiteSettings
• Delete hooks: generic crap.HookContext (data only contains the document ID)
• Access hooks: generic crap.AccessContext

# Interactive (prompts for everything)
crap-cms make hook

# Fully specified
crap-cms make hook auto_slug \
    -t collection -c posts -l before_change

# Field hook
crap-cms make hook normalize_email \
    -t field -c users -l before_validate -F email

# Access hook
crap-cms make hook owner_only \
    -t access -c posts -l read

# Condition hook (client-side table)
crap-cms make hook show_external_url \
    -t condition -c posts -l table -F post_type

make job

crap-cms make job [SLUG] [-s <SCHEDULE>] [-q <QUEUE>] [-r <RETRIES>] [-t <TIMEOUT>] [-f]

# Interactive (prompts for slug)
crap-cms make job

# With schedule
crap-cms make job cleanup_expired -s "0 3 * * *" -r 3 -t 300

# Simple job (triggered from hooks)
crap-cms make job send_welcome_email

blueprint — Manage saved blueprints

blueprint save

crap-cms blueprint save <NAME> [-f]

Saves the current config directory as a reusable blueprint (excluding data/, uploads/, types/). A .crap-blueprint.toml manifest is written with the CMS version and timestamp.

blueprint use

crap-cms blueprint use <NAME> [DIR]

Creates a new project from a saved blueprint. If the blueprint was saved with a different CMS version, a warning is printed (but the operation proceeds).

blueprint list

crap-cms blueprint list

Lists saved blueprints with collection/global counts and the CMS version they were saved with.

blueprint remove

crap-cms blueprint remove <NAME>

db — Database tools

db console

crap-cms db console

Opens an interactive sqlite3 session on the project database.

db cleanup

crap-cms db cleanup [--confirm]

Detects columns in collection tables that don’t correspond to any field in the current Lua definitions. System columns (_-prefixed like _password_hash, _locked) are always kept. Plugin columns are safe because plugins run during schema loading — their fields are part of the live definitions.

# Dry run — show orphans without removing them
crap-cms db cleanup

# Actually drop orphan columns
crap-cms db cleanup --confirm

export — Export collection data

crap-cms export [-c <COLLECTION>] [-o <FILE>]

Export includes crap_version and exported_at metadata in the JSON envelope. On import, a version mismatch produces a warning (but does not abort).

crap-cms export
crap-cms export -c posts -o posts.json

import — Import collection data

crap-cms import <FILE> [-c <COLLECTION>]

crap-cms import backup.json
crap-cms import backup.json -c posts

typegen — Generate typed definitions

crap-cms typegen [-l <LANG>] [-o <DIR>]

crap-cms typegen
crap-cms typegen -l all
crap-cms typegen -l ts -o ./client/src/types

proto — Export proto file

crap-cms proto [-o <PATH>]

Writes content.proto to stdout or the given path. No config directory needed.

crap-cms proto
crap-cms proto -o ./proto/

migrate — Run database migrations

crap-cms migrate <create|up|down|list|fresh>

crap-cms migrate create backfill_slugs
crap-cms migrate up
crap-cms migrate list
crap-cms migrate down -s 2
crap-cms migrate fresh -y

backup — Backup database

crap-cms backup [-o <DIR>] [-i]

crap-cms backup
crap-cms backup -o /tmp/backups -i

restore — Restore from backup

crap-cms restore <BACKUP> [-i] [-y]

Replaces the current database with a backup snapshot. Cleans up stale WAL/SHM files.

crap-cms restore ./backups/backup-2026-03-07T10-00-00 -y
crap-cms restore /tmp/backups/backup-2026-03-07T10-00-00 -i -y

templates — List and extract default admin templates

Extract the compiled-in admin templates and static files into your config directory for customization.

templates list

crap-cms templates list [-t <TYPE>] [-v]

crap-cms templates list
crap-cms templates list -t templates
crap-cms templates list -v

templates extract

crap-cms templates extract [PATHS...] [-a] [-t <TYPE>] [-f]

# Extract specific files
crap-cms templates extract layout/base.hbs styles.css

# Extract all templates
crap-cms templates extract --all --type templates

# Extract everything, overwriting existing
crap-cms templates extract --all --force

jobs — Manage background jobs

jobs list

crap-cms jobs list

Lists all defined jobs with their configuration (handler, schedule, queue, retries, timeout, concurrency).

jobs trigger

crap-cms jobs trigger <SLUG> [-d <DATA>]

Manually queue a job for execution. Works even while the server is running (SQLite WAL allows concurrent access). Prints the queued job run ID.

jobs status

crap-cms jobs status [--id <ID>] [-s <SLUG>] [-l <LIMIT>]

Show recent job runs. If --id is given, shows details for that specific run. Otherwise lists recent runs across all jobs.

jobs cancel

crap-cms jobs cancel [--slug <SLUG>]

Deletes pending jobs from the queue. Useful for clearing stuck or unwanted jobs that keep retrying.

jobs purge

crap-cms jobs purge [--older-than <DURATION>]

jobs healthcheck

crap-cms jobs healthcheck

Checks job system health and prints a summary: defined jobs, stale jobs (running but heartbeat expired), failed jobs in the last 24 hours, pending jobs waiting longer than 5 minutes, and scheduled jobs that have never completed a run.

Exit status: healthy (no issues), warning (failed or long-pending jobs), unhealthy (stale jobs detected).

crap-cms jobs list
crap-cms jobs trigger cleanup_expired
crap-cms jobs status
crap-cms jobs status --id abc123
crap-cms jobs cancel
crap-cms jobs cancel -s process_inquiry
crap-cms jobs purge --older-than 30d
crap-cms jobs healthcheck

images — Manage image processing queue

Inspect and manage the background image format conversion queue. See Image Processing for how to enable queued conversion.

images list

crap-cms images list [-s <STATUS>] [-l <LIMIT>]

images stats

crap-cms images stats

Shows counts by status (pending, processing, completed, failed) and total.

images retry

crap-cms images retry [--id <ID>] [--all] [-y]

images purge

crap-cms images purge [--older-than <DURATION>]

crap-cms images list
crap-cms images list -s failed
crap-cms images stats
crap-cms images retry --id abc123
crap-cms images retry --all -y
crap-cms images purge --older-than 30d

mcp — Start the MCP server (stdio)

Start an MCP (Model Context Protocol) server over stdio for AI assistant integration.

crap-cms mcp

Reads JSON-RPC 2.0 from stdin, writes responses to stdout. Use with Claude Desktop, Cursor, VS Code, or any MCP-compatible client. See MCP Overview for configuration and usage.

logs — View and manage log files

crap-cms logs [-f] [-n <lines>]
crap-cms logs clear

View log output from file-based logging. Requires [logging] file = true in crap.toml (auto-enabled when running with --detach).

Subcommands:

crap-cms logs                # show last 100 lines
crap-cms logs -f             # follow in real time
crap-cms logs -n 50          # show last 50 lines
crap-cms logs clear          # remove old rotated files

Log files are stored in data/logs/ (or the path configured in [logging] path). Old files are automatically pruned on startup based on max_files. See Configuration Reference for all logging options.

Environment Variables

Collections

Collections are the core data model in Crap CMS. Each collection maps to a SQLite table and is defined in a Lua file.

Basics

• One Lua file per collection in the collections/ directory
• Files are loaded alphabetically at startup
• Each file calls crap.collections.define(slug, config)
• The slug becomes the table name and URL segment
• Fields, hooks, access control, auth, and uploads are all configured in the definition

Example

-- collections/posts.lua
crap.collections.define("posts", {
    labels = {
        singular = "Post",
        plural = "Posts",
    },
    timestamps = true,
    admin = {
        use_as_title = "title",
        default_sort = "-created_at",
        list_searchable_fields = { "title", "slug" },
    },
    fields = {
        crap.fields.text({ name = "title", required = true }),
        crap.fields.text({ name = "slug", required = true, unique = true }),
        crap.fields.select({
            name = "status",
            default_value = "draft",
            options = {
                { label = "Draft", value = "draft" },
                { label = "Published", value = "published" },
            },
        }),
        crap.fields.richtext({ name = "content" }),
    },
    hooks = {
        before_change = { "hooks.posts.auto_slug" },
    },
    access = {
        read   = "hooks.access.public_read",
        create = "hooks.access.authenticated",
        delete = "hooks.access.admin_only",
    },
})

System Fields

Every collection automatically has these columns (not in your field definitions):

Auth collections also get a hidden _password_hash TEXT column.

Versioned collections with drafts = true also get:

Versioned collections also get a companion _versions_{slug} table that stores JSON snapshots of every save. See Versions & Drafts.

Schema Sync

On startup, Crap CMS compares each Lua definition against the existing SQLite table:

• Missing table — creates it with all defined columns
• Missing columns — adds them via ALTER TABLE
• Removed columns — logged as a warning (SQLite doesn’t easily drop columns)
• Type changes — not automatically migrated (manual intervention needed)

Collection Definition Schema

Full reference for every property accepted by crap.collections.define(slug, config).

Top-Level Properties

admin

hooks

All hook values are arrays of string references in module.function format.

See Hooks for full details.

auth

Set to true for defaults, or provide a config table:

-- Simple
auth = true

-- With options
auth = {
    token_expiry = 3600,
    disable_local = false,
    strategies = {
        { name = "api-key", authenticate = "hooks.auth.api_key_check" },
    },
}

See Auth Collections for the full schema.

upload

Set to true for defaults, or provide a config table:

-- Simple
upload = true

-- With options
upload = {
    mime_types = { "image/*" },
    max_file_size = 10485760,
    image_sizes = {
        { name = "thumbnail", width = 300, height = 300, fit = "cover" },
    },
    format_options = {
        webp = { quality = 80 },
    },
}

See Uploads for the full schema.

access

If a property is omitted, that operation is allowed for everyone.

See Access Control for full details.

versions

Set to true for defaults (drafts enabled, unlimited versions), or provide a config table:

-- Simple: versions with drafts
versions = true

-- With options
versions = {
    drafts = true,
    max_versions = 20,
}

-- Versions without drafts (pure audit trail)
versions = {
    drafts = false,
    max_versions = 50,
}

See Versions & Drafts for the full workflow.

Indexes

Field-Level Indexes

Set index = true on a field to create a B-tree index on its column. This speeds up queries that filter or sort on that field. Unique fields are already indexed by SQLite, so index = true is skipped when unique = true.

crap.fields.text({ name = "status", index = true }),
crap.fields.date({ name = "published_at", index = true }),

For localized fields, one index is created per locale column (e.g., idx_posts_title__en, idx_posts_title__de).

Compound Indexes

Use the top-level indexes array for multi-column indexes:

indexes = {
    { fields = { "status", "created_at" } },
    { fields = { "category", "slug" }, unique = true },
}

Indexes are synced idempotently on startup: missing indexes are created with CREATE INDEX IF NOT EXISTS, and stale indexes (from removed fields or changed definitions) are dropped. Only indexes with the idx_{collection}_ naming prefix are managed — external indexes are left untouched.

Complete Example

crap.collections.define("posts", {
    labels = {
        singular = "Post",
        plural = "Posts",
    },
    timestamps = true,
    admin = {
        use_as_title = "title",
        default_sort = "-created_at",
        hidden = false,
        list_searchable_fields = { "title", "slug", "content" },
    },
    fields = {
        crap.fields.text({
            name = "title",
            required = true,
            hooks = {
                before_validate = { "hooks.posts.trim_title" },
            },
        }),
        crap.fields.text({
            name = "slug",
            required = true,
            unique = true,
        }),
        crap.fields.select({
            name = "status",
            required = true,
            default_value = "draft",
            options = {
                { label = "Draft", value = "draft" },
                { label = "Published", value = "published" },
                { label = "Archived", value = "archived" },
            },
        }),
        crap.fields.richtext({ name = "content" }),
        crap.fields.relationship({
            name = "tags",
            relationship = { collection = "tags", has_many = true },
        }),
    },
    hooks = {
        before_change = { "hooks.posts.auto_slug" },
    },
    access = {
        read   = "hooks.access.public_read",
        create = "hooks.access.authenticated",
        update = "hooks.access.authenticated",
        delete = "hooks.access.admin_only",
    },
})

Versions & Drafts

Crap CMS supports document versioning with an optional draft/publish workflow.

Enabling Versions

Add versions to your collection definition:

-- Simple: enables versions with drafts
crap.collections.define("articles", {
    versions = true,
    fields = { ... },
})

-- With options
crap.collections.define("articles", {
    versions = {
        drafts = true,
        max_versions = 20,
    },
    fields = { ... },
})

Config Properties

Setting versions = true is equivalent to { drafts = true, max_versions = 0 }.

Setting versions = false or omitting it disables versioning entirely.

How It Works

When versioning is enabled, every create and update operation saves a JSON snapshot of the document to a _versions_{slug} table. This provides a full audit trail with the ability to restore any previous version.

Database Changes

Versioned collections get an additional table:

_versions_articles (
    id TEXT PRIMARY KEY,
    _parent TEXT NOT NULL REFERENCES articles(id) ON DELETE CASCADE,
    _version INTEGER NOT NULL,
    _status TEXT NOT NULL,        -- "published" or "draft"
    _latest INTEGER NOT NULL DEFAULT 0,  -- 1 for the most recent version
    snapshot TEXT NOT NULL,               -- full JSON snapshot
    created_at TEXT DEFAULT (datetime('now')),
    updated_at TEXT DEFAULT (datetime('now'))
)

When drafts = true, the main table also gets a _status column (TEXT NOT NULL DEFAULT 'published').

Draft/Publish Workflow

When drafts = true, documents have a _status field that is either "published" or "draft".

Creating Documents

Updating Documents

The version-only draft save is key: it lets authors iterate on changes without affecting the published version. The main table always reflects the last published state.

Reading Documents

Validation

Required field validation is skipped for draft saves. This lets authors save incomplete work. Validation is enforced when publishing (draft = false).

gRPC API

Draft Parameter

The draft parameter is available on these RPCs:

// Create a draft
CreateRequest { collection, data, draft: true }

// Draft update (version-only, main table unchanged)
UpdateRequest { collection, id, data, draft: true }

// Find all documents including drafts
FindRequest { collection, draft: true }

// Get the latest version (may be a newer draft)
FindByIDRequest { collection, id, draft: true }

ListVersions

List version history for a document:

grpcurl -plaintext -d '{
    "collection": "articles",
    "id": "abc123",
    "limit": "10"
}' localhost:50051 crap.ContentAPI/ListVersions

Response:

{
    "versions": [
        { "id": "v1", "version": 3, "status": "draft", "latest": true, "created_at": "..." },
        { "id": "v2", "version": 2, "status": "published", "latest": false, "created_at": "..." },
        { "id": "v3", "version": 1, "status": "published", "latest": false, "created_at": "..." }
    ]
}

RestoreVersion

Restore a previous version, writing its snapshot data back to the main table:

grpcurl -plaintext -d '{
    "collection": "articles",
    "document_id": "abc123",
    "version_id": "v3"
}' localhost:50051 crap.ContentAPI/RestoreVersion

This overwrites the main table with the snapshot data, sets _status to "published", and creates a new version entry for the restore.

Lua API

The draft option is available on create and update:

-- Create as draft
local doc = crap.collections.create("articles", {
    title = "Work in progress",
}, { draft = true })

-- Draft update (version-only save)
crap.collections.update("articles", doc.id, {
    title = "Still editing...",
}, { draft = true })

-- Publish
crap.collections.update("articles", doc.id, {
    title = "Final Title",
})  -- draft defaults to false

Admin UI

Buttons

When drafts are enabled, the edit form shows context-aware buttons:

Status Badge

A status badge (published or draft) appears in the document meta panel and in the collection list view.

Version History

The edit sidebar shows a “Version History” panel listing recent versions with:

• Version number
• Status badge (published/draft)
• Timestamp
• Restore button (for non-latest versions)

Clicking Restore writes the snapshot data back to the main table and redirects to the edit form.

Access Control

Draft operations use the existing update access rule. There is no separate access rule for drafts. If you need finer-grained control (e.g., only admins can publish, but editors can save drafts), inspect the incoming data._status field in your access hooks:

function hooks.access.publish_control(ctx)
    if ctx.data and ctx.data._status == "draft" then
        -- Any authenticated user can save drafts
        return ctx.user ~= nil
    end
    -- Only admins can publish
    return ctx.user and ctx.user.role == "admin"
end

Versions Without Drafts

You can enable version history without the draft/publish workflow:

versions = {
    drafts = false,
    max_versions = 50,
}

This creates version snapshots on every save but does not add a _status column, does not filter by publish state, and does not show draft/publish buttons in the admin UI. Useful for pure audit trails.

Example

crap.collections.define("articles", {
    labels = { singular = "Article", plural = "Articles" },
    timestamps = true,
    versions = {
        drafts = true,
        max_versions = 20,
    },
    admin = {
        use_as_title = "title",
        default_sort = "-created_at",
    },
    fields = {
        crap.fields.text({ name = "title", required = true }),
        crap.fields.text({ name = "slug", required = true, unique = true }),
        crap.fields.textarea({ name = "summary" }),
        crap.fields.richtext({ name = "body" }),
    },
    access = {
        read   = "hooks.access.public_read",
        create = "hooks.access.authenticated",
        update = "hooks.access.authenticated",
        delete = "hooks.access.admin_only",
    },
})

Soft Deletes

Collections can opt into soft deletes so that deleted documents are moved to trash instead of being permanently removed. Trashed documents can be restored or permanently purged after a configurable retention period.

Enabling

crap.collections.define("posts", {
  soft_delete = true,
  soft_delete_retention = "30d",  -- optional: auto-purge after 30 days
  -- ...
})

When soft_delete = true:

• Deleting a document sets a _deleted_at timestamp instead of removing the row
• Soft-deleted documents are excluded from all reads, counts, and search
• Upload files are preserved until the document is permanently purged
• Version history is preserved

Permissions

Soft deletes introduce a split between trashing (reversible) and permanent deletion (destructive):

Example configuration:

access = {
  read = "access.anyone",
  create = "access.editor_or_above",
  update = "access.editor_or_above",
  trash = "access.editor_or_above",       -- editors can trash and restore
  delete = "access.admin_or_director",    -- only admins can permanently delete
}

If access.trash is not set, it falls back to access.update — any user who can edit a document can also trash it. If access.delete is not set, permanent deletion is only possible via the auto-purge scheduler.

Admin UI

Trash view

The collection list shows a Trash button when soft_delete is enabled. Clicking it shows the trash view (?trash=1) with:

• Restore button — moves the document back to the active list
• Delete permanently button — permanently removes the document (only shown when access.delete is configured)
• Empty trash button — permanently removes all trashed documents (only shown when access.delete is configured)

Delete dialog

The delete button on list rows and the edit sidebar opens a modal dialog:

• Soft-delete collections: Shows “Move to trash” (primary) and “Delete permanently” (danger) buttons
• Hard-delete collections: Shows only “Delete permanently” button
• “Delete permanently” is hidden when the user lacks access.delete permission

Retention & Auto-Purge

Set soft_delete_retention to automatically purge expired documents:

soft_delete_retention = "30d"   -- purge after 30 days
soft_delete_retention = "7d"    -- purge after 7 days
soft_delete_retention = "90d"   -- purge after 90 days

The scheduler runs the purge job periodically. Documents with _deleted_at older than the retention period are permanently deleted, including upload file cleanup.

If soft_delete_retention is not set, trashed documents persist indefinitely until manually purged via the admin UI or CLI.

Supported formats: "30d" (days), "24h" (hours), or raw seconds.

API

gRPC

// Soft-delete (default for soft_delete collections)
rpc Delete (DeleteRequest) returns (DeleteResponse);

// Force permanent deletion
DeleteRequest { collection: "posts", id: "abc", force_hard_delete: true }

// Restore from trash
rpc Restore (RestoreRequest) returns (RestoreResponse);

The DeleteResponse includes a soft_deleted boolean indicating whether the deletion was soft or hard.

Lua

-- Soft delete (moves to trash)
crap.collections.delete("posts", id)

-- Force permanent delete
crap.collections.delete("posts", id, { forceHardDelete = true })

-- Restore from trash
crap.collections.restore("posts", id)

MCP

MCP delete tools automatically use soft delete when the collection has it enabled.

CLI

# List all trashed documents
crap trash list

# List trashed documents in a specific collection
crap trash list --collection posts

# Restore a document from trash
crap trash restore posts abc123

# Purge all expired documents (respects soft_delete_retention)
crap trash purge

# Purge documents older than 7 days
crap trash purge --older-than 7d

# Dry run — show what would be purged without deleting
crap trash purge --dry-run

# Empty all trash in a collection (requires --confirm)
crap trash empty posts --confirm

Database Schema

When soft_delete = true, a _deleted_at TEXT column is added to the collection table. The value is NULL for active documents and an ISO 8601 timestamp for soft-deleted documents.

All read queries automatically append AND _deleted_at IS NULL to exclude trashed documents. The include_deleted flag on FindQuery overrides this for the trash view.

Notes

• Soft-deleted documents retain all join table data (arrays, blocks, relationships) — nothing is cascaded
• FTS index entries are removed on soft-delete and re-synced on restore
• Upload files are kept on disk until the document is permanently purged
• Version history is preserved through soft-delete and restore
• Back-reference warnings still appear on the delete confirmation for upload/media collections

Fields

Fields define the schema of a collection or global. Each field maps to a SQLite column (except arrays and has-many relationships, which use join tables).

Defining Fields

There are two ways to define fields: factory functions (recommended) and plain tables.

Factory Functions (Recommended)

crap.fields.* functions set the type automatically and return a plain table. Your editor shows only the properties relevant to each field type — no blocks on a text field, no options on a checkbox.

fields = {
    crap.fields.text({ name = "title", required = true }),
    crap.fields.select({ name = "status", options = {
        { label = "Draft", value = "draft" },
        { label = "Published", value = "published" },
    }}),
    crap.fields.relationship({ name = "author", relationship = { collection = "users" } }),
}

Plain Tables

You can also define fields as plain tables with an explicit type key. This is fully supported and equivalent — factories just set type for you.

fields = {
    { name = "title", type = "text", required = true },
    { name = "status", type = "select", options = { ... } },
}

Both syntaxes can be freely mixed in the same fields array.

Why factories? The types/crap.lua file ships per-type LuaLS classes (e.g., crap.SelectField, crap.ArrayField). When you use crap.fields.select({...}), your editor autocompletes only the properties that apply to select fields. With plain tables, the single crap.FieldDefinition class shows every possible property.

Common Properties

Every field type accepts these properties:

Supported Types

admin Properties

Layout Wrappers

Row, Collapsible, and Tabs are layout wrappers — they exist only for admin UI grouping. They are transparent at the data layer: sub-fields are promoted as top-level columns with no prefix (unlike Group, which creates prefixed columns).

Nesting

Layout wrappers can be nested inside each other and inside Array/Blocks sub-fields at arbitrary depth:

crap.fields.array({
    name = "team_members",
    fields = {
        crap.fields.tabs({
            name = "member_tabs",
            tabs = {
                {
                    label = "Personal",
                    fields = {
                        crap.fields.row({
                            name = "name_row",
                            fields = {
                                crap.fields.text({ name = "first_name", required = true }),
                                crap.fields.text({ name = "last_name", required = true }),
                            },
                        }),
                        crap.fields.email({ name = "email" }),
                    },
                },
                {
                    label = "Professional",
                    fields = {
                        crap.fields.text({ name = "job_title" }),
                    },
                },
            },
        }),
    },
})

In this example, first_name, last_name, email, and job_title all become flat columns in the {collection}_team_members join table — the Tabs and Row wrappers are invisible at the data and API layer.

All combinations work: Row inside Tabs, Tabs inside Collapsible, Collapsible inside Row, etc.

Depth limit

The admin UI rendering caps layout nesting at 5 levels deep. Beyond this, fields are silently omitted from the form. This limit is a safety guard against infinite recursion — realistic schemas never hit it (5 levels means something like Array → Tabs → Collapsible → Row → Tabs → field).

The data layer (DDL, read, write, versions) has no depth limit.

Custom Validation

The validate property references a Lua function in module.function format. The function receives (value, context) and returns:

• nil or true — valid
• false — invalid with a generic message
• string — invalid with a custom error message

-- hooks/validators.lua
local M = {}

function M.min_length_3(value, ctx)
    if type(value) == "string" and #value < 3 then
        return ctx.field_name .. " must be at least 3 characters"
    end
end

return M

-- In field definition:
crap.fields.text({ name = "title", validate = "hooks.validators.min_length_3" })

The context table contains:

Text

Single-line string field. The most common field type.

SQLite Storage

TEXT column.

Definition

crap.fields.text({
    name = "title",
    required = true,
    unique = true,
    default_value = "Untitled",
    admin = {
        placeholder = "Enter title",
        description = "The display title",
    },
})

Multi-Value (has_many)

Store multiple text values as a JSON array in a TEXT column. Renders as a tag-style input in the admin UI.

crap.fields.text({
    name = "tags",
    has_many = true,
    min_length = 2,   -- each tag must be at least 2 chars
    max_rows = 10,    -- at most 10 tags
})

• Values are stored as ["tag1","tag2","tag3"] in the TEXT column
• min_length / max_length validate each individual value
• min_rows / max_rows validate the count of values
• Duplicate values are prevented in the admin UI
• Type generation maps to string[] / Vec<String> / list[str] etc.

Admin Rendering

Renders as an <input type="text"> element. When has_many = true, renders as a tag input where users type and press Enter to add chips.

Notes

• Empty strings are stored as NULL in SQLite
• Unknown field types default to text

Number

Numeric field for integers or floating-point values.

SQLite Storage

REAL column. Empty values are stored as NULL.

Definition

crap.fields.number({
    name = "price",
    required = true,
    default_value = 0,
    admin = {
        placeholder = "0.00",
    },
})

Multi-Value (has_many)

Store multiple numbers as a JSON array in a TEXT column. Renders as a tag-style input in the admin UI.

crap.fields.number({
    name = "scores",
    has_many = true,
    min = 0,
    max = 100,
    max_rows = 5,
})

• Values are stored as ["10","20","30"] in the TEXT column
• min / max validate each individual value
• min_rows / max_rows validate the count of values
• Type generation maps to number[] / Vec<f64> / list[float] etc.

Step

Set admin.step to control the number input step attribute:

crap.fields.number({
    name = "price",
    admin = { step = "0.01" },
})

Valid values: "1" (integers only), "0.01" (cents), "any" (no step constraint). Defaults to browser default ("1").

Admin Rendering

Renders as an <input type="number"> element. When has_many = true, renders as a tag input where users type and press Enter to add number chips.

Value Coercion

String values from form submissions are parsed as f64. If parsing fails, NULL is stored.

Textarea

Multi-line text field for longer content.

SQLite Storage

TEXT column.

Definition

crap.fields.textarea({
    name = "description",
    admin = {
        placeholder = "Enter a description...",
        rows = 12,
        resizable = false,
    },
})

Admin Options

Admin Rendering

Renders as a <textarea> element. By default, the textarea is vertically resizable. Set admin.resizable = false to disable the resize handle.

Rich Text

Rich text field with a ProseMirror-based WYSIWYG editor. Stored as HTML (default) or ProseMirror JSON.

SQLite Storage

TEXT column containing HTML content (default) or ProseMirror JSON document.

Definition

crap.fields.richtext({
    name = "content",
    admin = {
        placeholder = "Write your content...",
    },
})

Storage Format

By default, richtext fields store raw HTML. Set admin.format = "json" to store the ProseMirror document structure as JSON instead:

crap.fields.richtext({
    name = "content",
    admin = {
        format = "json",
    },
})

HTML vs JSON

Important notes

• Changing format does NOT migrate existing data. If you switch from "html" to "json" (or vice versa), existing documents retain their original format. The editor will attempt to parse the stored content according to the current format setting.
• The API returns the stored format as-is (HTML string or JSON string).
• Full-text search automatically extracts plain text from JSON-format richtext fields.

Toolbar Configuration

By default, all toolbar features are enabled. Use admin.features to limit which features are available:

crap.fields.richtext({
    name = "content",
    admin = {
        features = { "bold", "italic", "heading", "link", "bulletList" },
    },
})

Available Features

When features is omitted or empty, all features are enabled (backward compatible). Undo/redo buttons are always available regardless of feature configuration.

Custom Nodes

Custom ProseMirror nodes let you embed structured components (CTAs, embeds, alerts, mentions, etc.) inside richtext content. Register nodes in init.lua, then enable them on specific fields via admin.nodes.

Registration

Node attributes use the same crap.fields.* factory functions as collection fields. Only scalar types are allowed: text, number, textarea, select, radio, checkbox, date, email, json, code.

-- init.lua
crap.richtext.register_node("cta", {
    label = "Call to Action",
    inline = false, -- block-level node
    attrs = {
        crap.fields.text({ name = "text", required = true, admin = { label = "Button Text" } }),
        crap.fields.text({ name = "url", required = true, admin = { label = "URL", placeholder = "https://..." } }),
        crap.fields.select({ name = "style", admin = { label = "Style" }, options = {
            { label = "Primary", value = "primary" },
            { label = "Secondary", value = "secondary" },
        }}),
    },
    searchable_attrs = { "text" },
    render = function(attrs)
        return string.format(
            '<a href="%s" class="btn btn--%s">%s</a>',
            attrs.url, attrs.style or "primary", attrs.text
        )
    end,
})

Field configuration

crap.fields.richtext({
    name = "content",
    admin = {
        format = "json",
        nodes = { "cta" },
        features = { "bold", "italic", "heading", "link", "bulletList" },
    },
})

Node spec options

Allowed attribute types

Node attrs support all scalar field types. Complex types (array, group, blocks, relationship, upload, richtext, row, collapsible, tabs, join) are rejected at registration time.

Supported attribute features

Node attrs support most field features that make sense in the richtext context.

Admin display hints

These control how attributes appear in the node edit modal:

Server-side validation

Node attribute values inside richtext content are validated server-side on create/update. The following checks run automatically:

Validation errors reference the node location: "content[cta#0].url" (first CTA node’s url attribute in the content field).

before_validate hooks

Node attrs support hooks.before_validate for normalizing values before validation:

crap.richtext.register_node("cta", {
    label = "CTA",
    attrs = {
        crap.fields.text({
            name = "url",
            required = true,
            hooks = {
                before_validate = { "hooks.trim_whitespace" },
            },
        }),
    },
})

The hook receives (value, context) and returns the transformed value. Runs before validation checks.

Unsupported features

These features have no effect on node attributes and will produce a warning at registration time:

Server-side rendering

Use crap.richtext.render(content) in hooks to replace custom nodes with rendered HTML. The function auto-detects format (JSON or HTML). Custom nodes with a render function produce the function’s output; nodes without one pass through as <crap-node> custom elements.

-- In an after_read hook
function hooks.render_content(context)
    local doc = context.doc
    if doc.content then
        doc.content = crap.richtext.render(doc.content)
    end
    return context
end

FTS search

Custom node attributes listed in searchable_attrs are automatically extracted for full-text search when the field uses JSON format.

Resize Behavior

By default, the richtext editor is vertically resizable (no max-height constraint). Set admin.resizable = false to lock it to a fixed height range (200–600px):

crap.fields.richtext({
    name = "content",
    admin = {
        resizable = false,
    },
})

Admin Rendering

Renders as a ProseMirror-based rich text editor with a configurable toolbar. When custom nodes are configured, an insert button group appears in the toolbar for each node type. Nodes display as styled cards (block) or pills (inline) in the editor; double-click to edit attributes.

Notes

• No server-side sanitization is applied — sanitize in hooks if needed
• The toolbar configuration only affects the admin UI; it does not validate or strip content server-side
• Custom node names must be alphanumeric with underscores only

Select

Single-value selection from predefined options.

SQLite Storage

TEXT column storing the selected value.

Definition

crap.fields.select({
    name = "status",
    required = true,
    default_value = "draft",
    options = {
        { label = "Draft", value = "draft" },
        { label = "Published", value = "published" },
        { label = "Archived", value = "archived" },
    },
})

Options Format

Each option is a table with:

Multi-Value (has_many)

Allow selecting multiple options. Values are stored as a JSON array in a TEXT column.

crap.fields.select({
    name = "categories",
    has_many = true,
    options = {
        { label = "News", value = "news" },
        { label = "Tech", value = "tech" },
        { label = "Sports", value = "sports" },
    },
})

Admin Rendering

Renders as a <select> dropdown. When has_many = true, renders as a multi-select.

Radio

Single-value selection from predefined options, rendered as radio buttons.

SQLite Storage

TEXT column storing the selected value.

Definition

crap.fields.radio({
    name = "priority",
    required = true,
    options = {
        { label = "Low", value = "low" },
        { label = "Medium", value = "medium" },
        { label = "High", value = "high" },
    },
})

Options Format

Each option is a table with:

Admin Rendering

Renders as a group of radio buttons (one selectable at a time). Functionally identical to Select but with a different UI presentation — use radio when there are few options and you want them all visible at once.

Checkbox

Boolean field stored as an integer (0 or 1).

SQLite Storage

INTEGER column with DEFAULT 0.

Definition

crap.fields.checkbox({
    name = "published",
    default_value = false,
})

Admin Rendering

Renders as an <input type="checkbox"> element.

Value Coercion

The following string values are treated as true: "on", "true", "1", "yes". Everything else (including absence) is false.

Special Behavior

• Absent checkboxes are always treated as false (not as a missing/required field)
• The required property is effectively ignored for checkboxes — an unchecked checkbox is always valid
• Default value is 0 at the database level

Date

Date, datetime, time, or month field with configurable picker appearance and automatic normalization.

SQLite Storage

TEXT column. Values are normalized on write (see Storage Format below).

Definition

-- Date only (default) — stored as UTC noon to prevent timezone drift
crap.fields.date({ name = "birthday" })
crap.fields.date({ name = "birthday", picker_appearance = "dayOnly" })

-- Date and time — stored as full ISO 8601 UTC
crap.fields.date({ name = "published_at", picker_appearance = "dayAndTime" })

-- Time only — stored as HH:MM
crap.fields.date({ name = "reminder", picker_appearance = "timeOnly" })

-- Month only — stored as YYYY-MM
crap.fields.date({ name = "birth_month", picker_appearance = "monthOnly" })

Picker Appearance

The picker_appearance option controls the HTML input type in the admin UI and how values are stored:

Date Normalization

All date values are normalized in coerce_value before writing to the database, regardless of how they arrive (admin form or gRPC API):

• Date only (2026-01-15) → 2026-01-15T12:00:00.000Z (UTC noon prevents timezone drift)
• Full ISO 8601 (2026-01-15T09:00:00Z, 2026-01-15T09:00:00+05:00) → converted to UTC, formatted as YYYY-MM-DDTHH:MM:SS.000Z
• datetime-local (2026-01-15T09:00) → treated as UTC, formatted as YYYY-MM-DDTHH:MM:SS.000Z
• Time only (14:30) → stored as-is
• Month only (2026-01) → stored as-is

This normalization ensures consistent storage and correct behavior when filtering and sorting.

Admin Rendering

Renders as the appropriate HTML5 input type based on picker_appearance. For dayOnly and dayAndTime, the stored ISO string is automatically converted to the format the HTML input expects (YYYY-MM-DD and YYYY-MM-DDTHH:MM respectively).

Date Constraints

Use min_date and max_date to restrict the allowed range. Values are validated server-side and set as HTML min/max attributes on the input.

crap.fields.date({
    name = "event_date",
    min_date = "2026-01-01",
    max_date = "2026-12-31",
})

Both values use ISO 8601 format. Dates outside the range produce a validation error.

Validation

Non-empty date values are validated against recognized date/datetime/time/month formats. Invalid formats produce a validation error. If min_date or max_date are set, the value is also checked against those bounds.

Timezone Support

Date fields can opt into timezone awareness with timezone = true. This stores the user’s selected IANA timezone in a companion column and converts between local time and UTC automatically.

Enabling

crap.fields.date({
    name = "start_date",
    picker_appearance = "dayAndTime",
    timezone = true,
    default_timezone = "America/New_York",  -- optional pre-selected timezone
})

Only dayAndTime supports timezones — timezone only makes sense when there’s a time component. Using timezone = true with dayOnly, timeOnly, or monthOnly emits a warning and is ignored.

How It Works

1. Admin UI: A timezone dropdown appears next to the date input. The user selects a timezone and enters a local time.
2. On save: The local time is converted to UTC using the selected timezone (via chrono-tz). Both the UTC date and the IANA timezone string are stored.
3. On reload: The UTC value is converted back to local time for display. The user always sees the time they entered — re-saving without changes produces the same UTC value (no drift).

Storage

Two columns are created:

The naming follows the pattern {field_name}_tz. Inside Groups, it becomes {group}__{field}_tz.

API Responses

Both fields appear in gRPC and MCP responses:

{
  "start_date": "2026-05-02T12:00:00.000Z",
  "start_date_tz": "America/Sao_Paulo"
}

The date is always UTC. Frontends convert to local display:

const local = new Date(doc.start_date)
    .toLocaleString("en-US", { timeZone: doc.start_date_tz });

Global Default Timezone

Set a default timezone for all date fields in crap.toml:

[admin]
default_timezone = "America/New_York"

This pre-selects the timezone in the admin dropdown for any date field with timezone = true that doesn’t specify its own default_timezone. The field-level setting takes precedence.

Compatibility

• Localized fields: Each locale gets its own _tz column (e.g., start_date_tz__en)
• Groups / Rows / Tabs / Collapsible / Arrays: Companion columns follow the parent field’s naming rules
• Versioning: Timezone data is included in version snapshots and restored correctly
• Migration: Adding timezone = true to an existing field creates the _tz column via ALTER TABLE ADD COLUMN with NULL default. No data migration needed.
• Lua plugins: The timezone and default_timezone properties survive roundtrips through crap.collections.config.list() and crap.collections.define()

Notes

• Pure dates are stored with UTC noon (T12:00:00.000Z) so timezone offsets up to ±12h never flip the calendar date
• When timezone = true with dayOnly, noon is calculated in the selected timezone then converted to UTC
• Comparison operators (greater_than, less_than) work correctly on the normalized ISO string representation
• The picker_appearance option controls whether the picker shows date-only or date+time

Email

Email address field.

SQLite Storage

TEXT column.

Definition

crap.fields.email({
    name = "contact_email",
    required = true,
    unique = true,
    admin = {
        placeholder = "user@example.com",
    },
})

Admin Rendering

Renders as an <input type="email"> element with browser-native validation.

Auto-Injection

When a collection has auth = true and no email field is defined, one is automatically injected with required = true and unique = true. See Auth Collections.

JSON

Arbitrary JSON data stored as a text blob.

SQLite Storage

TEXT column containing a JSON string.

Definition

crap.fields.json({
    name = "metadata",
    admin = {
        description = "Arbitrary JSON metadata",
    },
})

Admin Rendering

Renders as a <textarea> with monospace font for JSON editing.

Notes

• Values are stored as raw JSON strings
• No schema validation is performed on the JSON content
• Use hooks or custom validate functions to enforce structure if needed

Relationship

Reference to documents in another collection. Supports has-one (single reference) and has-many (multiple references via junction table).

Has-One

Stores a single document ID as a TEXT column on the parent table.

crap.fields.relationship({
    name = "author",
    relationship = {
        collection = "users",
        has_many = false,  -- default
    },
})

At depth=0, the field value is a string ID. At depth=1+, it’s replaced with the full document object.

Has-Many

Uses a junction table ({collection}_{field}) with parent_id, related_id, and _order columns.

crap.fields.relationship({
    name = "tags",
    relationship = {
        collection = "tags",
        has_many = true,
    },
})

At depth=0, the field value is an array of string IDs. At depth=1+, each ID is replaced with the full document object.

Polymorphic Relationships

A relationship field can reference documents from multiple collections by setting collection to a Lua array of slugs instead of a single string.

crap.fields.relationship({
    name = "related_content",
    relationship = {
        collection = { "posts", "pages" },
        has_many = false,
    },
})

Has-one storage — the column stores a composite string in "collection/id" format (e.g., "posts/abc123"). At depth=0 the raw composite string is returned. At depth=1+ it is replaced with the full document object.

Has-many storage — uses a junction table (same as a regular has-many) with an additional related_collection TEXT column that records which collection each referenced document belongs to.

crap.fields.relationship({
    name = "featured_items",
    relationship = {
        collection = { "posts", "pages", "events" },
        has_many = true,
    },
})

Admin UI — the relationship picker fetches and displays search results grouped by collection, so editors can find and select documents from any of the target collections in one widget.

Relationship Config

Legacy Flat Syntax (Deprecated)

A flat syntax is still supported but deprecated — a warning is logged at startup when it’s used:

-- Deprecated: triggers a warning
crap.fields.relationship({
    name = "author",
    relation_to = "users",
    has_many = false,
})

-- Preferred: use the relationship table
crap.fields.relationship({
    name = "author",
    relationship = { collection = "users" },
})

The flat syntax does not support max_depth or polymorphic collections. Migrate to the relationship = { ... } table form.

Junction Table Schema

For a has-many field tags on collection posts, the junction table is:

CREATE TABLE posts_tags (
    parent_id TEXT NOT NULL REFERENCES posts(id) ON DELETE CASCADE,
    related_id TEXT NOT NULL,
    _order INTEGER NOT NULL DEFAULT 0,
    PRIMARY KEY (parent_id, related_id)
);

Admin Rendering

Has-one renders as a searchable input. Has-many renders as a multi-select with chips for selected items.

Drawer Picker

Add admin.picker = "drawer" to enable a browse button next to the search input. Clicking it opens a slide-in drawer panel with a searchable list for browsing documents.

crap.fields.relationship({
    name = "author",
    relationship = { collection = "users" },
    admin = { picker = "drawer" },
})

• Without picker: inline search autocomplete only (default behavior)
• With picker = "drawer": inline search + browse button that opens a drawer with a scrollable list

Population Depth

See Population Depth for details on controlling how deeply relationships are resolved.

Array

Repeatable group of sub-fields. Each array item is a row in a join table.

Storage

Array fields use a dedicated join table: {collection}_{field}.

The join table has columns:

Definition

crap.fields.array({
    name = "slides",
    fields = {
        crap.fields.text({ name = "title", required = true }),
        crap.fields.text({ name = "image_url" }),
        crap.fields.textarea({ name = "caption" }),
    },
    admin = {
        description = "Image slides for the gallery",
    },
})

Sub-Fields

Sub-fields support the same properties as regular fields (name, type, required, default_value, admin, etc.). Has-one relationships are supported (stored as a TEXT column in the join table). Nested arrays (array inside array) are not supported.

Layout Wrappers in Sub-Fields

Array sub-fields can be organized with Row, Collapsible, and Tabs layout wrappers. These are transparent — their children become flat columns in the join table, exactly as if they were listed directly in fields.

crap.fields.array({
    name = "items",
    fields = {
        crap.fields.tabs({
            name = "item_tabs",
            tabs = {
                {
                    label = "Content",
                    fields = {
                        crap.fields.text({ name = "title", required = true }),
                        crap.fields.textarea({ name = "description" }),
                    },
                },
                {
                    label = "Appearance",
                    fields = {
                        crap.fields.select({ name = "color", options = { ... } }),
                    },
                },
            },
        }),
    },
})

The join table gets columns title, description, and color — the Tabs wrapper is invisible at the data layer. Nesting is supported at arbitrary depth (e.g., Row inside Tabs inside Array). See Layout Wrappers for details.

API Representation

In API responses, array fields appear as a JSON array of objects:

{
  "slides": [
    { "id": "abc123", "title": "Slide 1", "image_url": "/img/1.jpg", "caption": "First" },
    { "id": "def456", "title": "Slide 2", "image_url": "/img/2.jpg", "caption": "Second" }
  ]
}

Writing Array Data

Via gRPC, pass an array of objects:

{
  "slides": [
    { "title": "Slide 1", "image_url": "/img/1.jpg" },
    { "title": "Slide 2", "image_url": "/img/2.jpg" }
  ]
}

On write, all existing rows for the parent are deleted and replaced with the new data. This is a full replacement, not a merge.

Row Labels

By default, array rows in the admin UI are labeled with the field label and row index (e.g., “Slides 0”, “Slides 1”). You can customize this with label_field and row_label.

label_field

Set admin.label_field to the name of a sub-field. Its value is used as the row title, and updates live as you type.

crap.fields.array({
    name = "slides",
    admin = {
        label_field = "title",
    },
    fields = {
        crap.fields.text({ name = "title", required = true }),
        crap.fields.text({ name = "image_url" }),
        crap.fields.textarea({ name = "caption" }),
    },
})

With this configuration, each row shows the title value instead of “Slides 0”.

row_label (Lua function)

For computed labels, set admin.row_label to a Lua function reference. The function receives the row data as a table and returns a display string (or nil to fall back to label_field or the default).

-- collections/products.lua
crap.fields.array({
    name = "variants",
    admin = {
        row_label = "labels.variant_row",
        label_field = "name", -- fallback if row_label returns nil
    },
    fields = {
        crap.fields.text({ name = "name", required = true }),
        crap.fields.text({ name = "sku" }),
        crap.fields.number({ name = "price" }),
    },
})

-- hooks/labels.lua
local M = {}

function M.variant_row(row)
    local name = row.name or "Untitled"
    if row.sku and row.sku ~= "" then
        return name .. " (" .. row.sku .. ")"
    end
    return name
end

return M

Priority

1. row_label Lua function (if set and returns a non-empty string)
2. label_field sub-field value (if set and the field has a value)
3. Default: field label + row index (e.g., “Slides 0”)

Note: row_label is only evaluated server-side. Rows added via JavaScript in the browser fall back to label_field (live-updated) or the default until the form is saved and reloaded.

Row Limits (min_rows / max_rows)

Enforce minimum and maximum row counts. These are validation constraints (like required), not just UI hints.

crap.fields.array({
    name = "slides",
    min_rows = 1,
    max_rows = 10,
    fields = { ... },
})

• min_rows: Minimum number of items. Validated on create/update (skipped for draft saves).
• max_rows: Maximum number of items. Validated on create/update. The admin UI disables the “Add” button when the limit is reached.

Validation runs in validate_fields(), shared by admin handlers, gRPC, and Lua crap.collections.create()/update().

Default Collapsed State (collapsed)

Existing rows render collapsed by default on page load (admin.collapsed = true). Set admin.collapsed = false to start rows expanded. New rows added via the “Add” button are always expanded.

crap.fields.array({
    name = "slides",
    admin = {
        collapsed = false, -- start rows expanded (default is true)
    },
    fields = { ... },
})

Custom Labels (labels)

Customize the “Add Row” button text and field header with singular/plural labels.

crap.fields.array({
    name = "slides",
    admin = {
        labels = { singular = "Slide", plural = "Slides" },
    },
    fields = { ... },
})

With this config, the add button reads “Add Slide” instead of “Add Row”.

Admin Rendering

Renders as a repeatable fieldset with:

• Drag handle for drag-and-drop reordering
• Row count badge showing the number of items
• Toggle collapse/expand all button
• Each row has expand/collapse toggle, move up/down, duplicate, and remove buttons
• “No items yet” empty state when no rows exist
• “Add Row” button (or custom label) to append new rows
• Add button disabled when max_rows is reached

Group

Visual grouping of sub-fields. Sub-fields become prefixed columns on the parent table (no join table).

Storage

Group fields do not create their own column. Instead, each sub-field becomes a column with a double-underscore prefix: {group}__{sub}.

For example, a group named seo with sub-fields title and description creates columns:

• seo__title TEXT
• seo__description TEXT

Definition

crap.fields.group({
    name = "seo",
    fields = {
        crap.fields.text({ name = "title", required = true }),
        crap.fields.textarea({ name = "description" }),
        crap.fields.checkbox({ name = "no_index" }),
    },
    admin = {
        description = "Search engine optimization settings",
    },
})

Sub-Fields

Sub-fields support the same properties as regular fields (name, type, required, default_value, admin, etc.), including nested groups, arrays, blocks, and relationships.

• Nested groups use stacked prefixes: outer__inner__field.
• Arrays/Blocks inside groups create prefixed join tables: {collection}_{group}__{field}.
• Relationships inside groups create prefixed junction tables (for has-many) or prefixed columns (for has-one).

API Representation

In API responses (after hydration), group fields appear as a nested object:

{
  "seo": {
    "title": "My Page Title",
    "description": "A page about...",
    "no_index": 0
  }
}

Writing Group Data

Via gRPC, pass the flat prefixed keys:

{
  "seo__title": "My Page Title",
  "seo__description": "A page about..."
}

The double-underscore separator is used in all write operations (forms, gRPC). On read, the prefixed columns are reconstructed into a nested object.

Filtering on Group Sub-Fields

Use dot notation to filter on group sub-fields. The dot syntax is converted to the double-underscore column name internally.

crap.collections.find("pages", {
    where = {
        ["seo.title"] = { contains = "SEO" },
        ["seo.no_index"] = "0",
    },
})

The equivalent double-underscore syntax also works: seo__title.

See Query & Filters for filtering on other nested field types (arrays, blocks, relationships).

Admin Rendering

Renders as a <fieldset> with a legend. Each sub-field is rendered using its own field type template (text, checkbox, select, etc.).

Row

Layout-only grouping of sub-fields. Unlike Group, sub-fields are promoted as top-level columns with no prefix.

Storage

Row fields do not create their own column. Each sub-field becomes a top-level column using its plain name — no prefix is added.

For example, a row with sub-fields firstname and lastname creates columns:

• firstname TEXT
• lastname TEXT

This is different from Group, which prefixes sub-field columns (seo__title).

Definition

crap.fields.row({
    name = "name_row",
    fields = {
        crap.fields.text({ name = "firstname", required = true }),
        crap.fields.text({ name = "lastname", required = true }),
    },
})

API Representation

In API responses, row sub-fields appear as flat top-level fields (not nested):

{
  "firstname": "Jane",
  "lastname": "Doe"
}

Writing Row Data

Use the plain sub-field names directly — no prefix needed:

{
  "firstname": "Jane",
  "lastname": "Doe"
}

Nesting

Row can be nested inside other layout wrappers (Tabs, Collapsible) and inside Array/Blocks sub-fields at arbitrary depth. All nesting combinations work — see the Layout Wrappers section for details and examples.

Depth limit: The admin UI caps layout nesting at 5 levels. The data layer has no limit.

Admin Rendering

Sub-fields are rendered in a horizontal row layout. The row itself has no fieldset, legend, or collapsible wrapper — it is purely a layout mechanism for placing related fields side by side.

Collapsible

Layout-only collapsible container for sub-fields. Like Row, sub-fields are promoted as top-level columns with no prefix. Unlike Group, which creates prefixed columns (group__subfield), Collapsible is purely a UI container.

Storage

Collapsible fields do not create their own column. Each sub-field becomes a top-level column using its plain name — no prefix is added. This is identical to Row storage.

For example, a collapsible with sub-fields meta_title and meta_description creates columns:

• meta_title TEXT
• meta_description TEXT

Definition

crap.fields.collapsible({
    name = "seo_section",
    admin = {
        label = "SEO Settings",
        -- collapsed defaults to true; set false to start expanded
        -- collapsed = false,
    },
    fields = {
        crap.fields.text({ name = "meta_title" }),
        crap.fields.textarea({ name = "meta_description" }),
    },
})

API Representation

In API responses, collapsible sub-fields appear as flat top-level fields (not nested):

{
  "meta_title": "My Page Title",
  "meta_description": "A description for search engines"
}

Writing Data

Use the plain sub-field names directly — no prefix needed:

{
  "meta_title": "My Page Title",
  "meta_description": "A description for search engines"
}

Nesting

Collapsible can be nested inside other layout wrappers (Tabs, Row) and inside Array/Blocks sub-fields at arbitrary depth. All nesting combinations work — see the Layout Wrappers section for details and examples.

Depth limit: The admin UI caps layout nesting at 5 levels. The data layer has no limit.

Admin Rendering

Sub-fields are rendered inside a collapsible section with a toggle header. The section starts collapsed by default (admin.collapsed = true). Set admin.collapsed = false to start expanded. Clicking the header toggles visibility. This is useful for grouping related fields that don’t need to be visible at all times (e.g., SEO settings, advanced options).

Comparison with Group and Row

Tabs

Layout-only tabbed container for sub-fields. Like Row and Collapsible, sub-fields across all tabs are promoted as top-level columns with no prefix.

Storage

Tabs fields do not create their own column. Each sub-field across all tabs becomes a top-level column using its plain name — no prefix is added. This is identical to Row storage.

For example, tabs with sub-fields title, body, meta_title, and meta_description creates columns:

• title TEXT
• body TEXT
• meta_title TEXT
• meta_description TEXT

Definition

crap.fields.tabs({
    name = "content_tabs",
    tabs = {
        {
            label = "Content",
            fields = {
                crap.fields.text({ name = "title", required = true }),
                crap.fields.richtext({ name = "body" }),
            },
        },
        {
            label = "SEO",
            description = "Search engine optimization settings",
            fields = {
                crap.fields.text({ name = "meta_title" }),
                crap.fields.textarea({ name = "meta_description" }),
            },
        },
    },
})

Each tab has:

• label (required) — the tab button text
• description (optional) — help text shown inside the tab panel
• fields — array of field definitions (same syntax as any other field list)

API Representation

In API responses, all tab sub-fields appear as flat top-level fields (not nested by tab):

{
  "title": "My Post",
  "body": "<p>Content here</p>",
  "meta_title": "My Post | Blog",
  "meta_description": "Read about my post"
}

Writing Data

Use the plain sub-field names directly — tabs are invisible at the data layer:

{
  "title": "My Post",
  "body": "<p>Content here</p>",
  "meta_title": "My Post | Blog",
  "meta_description": "Read about my post"
}

Nesting

Tabs can be nested inside other layout wrappers (Row, Collapsible) and inside Array/Blocks sub-fields at arbitrary depth. Tab fields can themselves contain Row, Collapsible, or nested Tabs. All nesting combinations work — see the Layout Wrappers section for details and examples.

Depth limit: The admin UI caps layout nesting at 5 levels. The data layer has no limit.

Admin Rendering

Sub-fields are organized into tabs with a tab bar at the top. The first tab is active by default. Clicking a tab button switches the visible panel. Each tab can have its own description text.

Comparison with Other Layout Types

Code

Code editor field stored as a plain text string. Renders a CodeMirror 6 editor in the admin UI with syntax highlighting and language-aware features.

SQLite Storage

TEXT column containing the raw code string.

Definition

crap.fields.code({
    name = "metadata",
    admin = {
        language = "json", -- "json", "javascript", "html", "css", "python", or "plain"
    },
})

Admin Options

Supported Languages

Admin Rendering

Renders as a CodeMirror 6 editor with line numbers, bracket matching, code folding, auto-completion, and search. Falls back to a plain <textarea> if the CodeMirror bundle is not loaded.

Notes

• Content is stored as a raw string (not parsed or validated for syntax)
• Supports min_length and max_length validation (applied to the raw string)
• The CodeMirror bundle (static/codemirror.js) is loaded via <script defer> in the admin layout
• To rebuild the bundle: bash scripts/bundle-codemirror.sh

Join

A virtual, read-only field that displays documents from another collection that reference the current document. No data is stored — results are computed at read time by querying the target collection.

Lua Definition

crap.fields.join({ name = "posts", collection = "posts", on = "author" })

This reads as: “Show me all documents in the posts collection where posts.author equals this document’s ID.”

Properties

Behavior

• No database column — join fields are virtual. No migration, no storage.
• Read-only — displayed in the admin UI but not editable. No form input is rendered.
• No validation — since no data is submitted, validation is skipped entirely.
• Admin UI — shows a list of linked documents with clickable links to edit each one. Displays “No related items” when empty.
• API responses — at depth >= 1, join fields return an array of document objects from the target collection. At depth = 0, join fields are omitted (no stored value).

Example

Given an authors collection and a posts collection where each post has a relationship field called author:

-- collections/authors.lua
return {
    slug = "authors",
    fields = {
        crap.fields.text({ name = "name", required = true }),
        crap.fields.join({ name = "posts", collection = "posts", on = "author" }),
    },
}

When editing an author, the “posts” join field displays all posts where posts.author equals the current author’s ID.

Upload

File reference field. Stores a relationship to an upload collection. Supports both single-file (has-one) and multi-file (has-many) modes.

Storage

• Has-one (default): stores the referenced media document’s ID in a TEXT column on the parent table.
• Has-many (has_many = true): stores references in a junction table {collection}_{field}, same as has-many relationships.

Definition

Single file (has-one):

crap.fields.upload({
    name = "featured_image",
    relationship = {
        collection = "media",
        max_depth = 1,
    },
})

Multi-file (has-many):

crap.fields.upload({
    name = "gallery",
    relationship = {
        collection = "media",
        has_many = true,
    },
})

Note: The flat relation_to syntax is deprecated for upload fields too. Use relationship = { collection = "..." } instead.

The target collection should be an upload collection (defined with upload = true).

API Representation

Has-one

At depth=0, returns the media document ID as a string:

{
  "featured_image": "abc123"
}

At depth=1+, the ID is populated with the full media document (same as relationship population):

{
  "featured_image": {
    "id": "abc123",
    "collection": "media",
    "filename": "hero.jpg",
    "mime_type": "image/jpeg",
    "url": "/uploads/media/hero.jpg",
    "sizes": { ... }
  }
}

Has-many

At depth=0, returns an array of media document IDs:

{
  "gallery": ["abc123", "def456"]
}

At depth=1+, each ID is populated with the full media document:

{
  "gallery": [
    { "id": "abc123", "collection": "media", "filename": "hero.jpg", ... },
    { "id": "def456", "collection": "media", "filename": "banner.png", ... }
  ]
}

Admin Rendering

• Has-one: renders as a searchable input with filename as the display label and image preview above.
• Has-many: renders as a searchable multi-select widget (same as has-many relationships) with chips for selected files.

Drawer Picker

Upload fields default to picker = "drawer", which shows a browse button next to the search input. Clicking it opens a slide-in drawer panel with a thumbnail grid for visually browsing upload documents.

-- drawer is the default for upload fields — no need to set it explicitly
crap.fields.upload({
    name = "featured_image",
    relation_to = "media",
})

• Default (picker = "drawer"): inline search + browse button that opens a drawer with thumbnail grid
• picker = "none": inline search autocomplete only (no browse button)

Blocks

Flexible content field with multiple block types. Each block type has its own schema. Stored in a join table with JSON data.

Storage

Blocks fields use a dedicated join table: {collection}_{field}.

The join table has columns:

Unlike arrays (which have typed columns per sub-field), blocks use a single JSON data column because each block type can have a different schema.

Definition

crap.fields.blocks({
    name = "content",
    blocks = {
        {
            type = "hero",
            label = "Hero Section",
            fields = {
                crap.fields.text({ name = "heading", required = true }),
                crap.fields.text({ name = "subheading" }),
                crap.fields.text({ name = "image_url" }),
            },
        },
        {
            type = "richtext",
            label = "Rich Text",
            fields = {
                crap.fields.richtext({ name = "body" }),
            },
        },
        {
            type = "cta",
            label = "Call to Action",
            fields = {
                crap.fields.text({ name = "text", required = true }),
                crap.fields.text({ name = "url", required = true }),
                crap.fields.select({ name = "style", options = {
                    { label = "Primary", value = "primary" },
                    { label = "Secondary", value = "secondary" },
                }}),
            },
        },
    },
})

Layout Wrappers in Block Fields

Block sub-fields can be organized with Row, Collapsible, and Tabs layout wrappers. Since blocks store data as JSON, wrappers are transparent at the data layer — their children appear as flat keys in the JSON object.

blocks = {
    {
        type = "feature_card",
        label = "Feature Card",
        fields = {
            crap.fields.tabs({
                name = "card_tabs",
                tabs = {
                    {
                        label = "Content",
                        fields = {
                            crap.fields.text({ name = "heading", required = true }),
                            crap.fields.textarea({ name = "body" }),
                        },
                    },
                    {
                        label = "Style",
                        fields = {
                            crap.fields.select({ name = "variant", options = { ... } }),
                        },
                    },
                },
            }),
        },
    },
}

The JSON data contains heading, body, and variant as flat keys — the Tabs wrapper is invisible. Nesting is supported at arbitrary depth. See Layout Wrappers for details.

Block Definitions

Each block definition has:

API Representation

In API responses, blocks fields appear as a JSON array of objects, each with _block_type and the block’s field values:

{
  "content": [
    {
      "id": "abc123",
      "_block_type": "hero",
      "heading": "Welcome",
      "subheading": "To our site"
    },
    {
      "id": "def456",
      "_block_type": "richtext",
      "body": "<p>Some content...</p>"
    }
  ]
}

Writing Blocks Data

Via gRPC, pass an array of objects with _block_type:

{
  "content": [
    { "_block_type": "hero", "heading": "Welcome", "subheading": "To our site" },
    { "_block_type": "richtext", "body": "<p>Content here</p>" }
  ]
}

On write, all existing block rows for the parent are deleted and replaced. This is a full replacement, not a merge.

Row Labels

By default, block rows display the block type label and row index (e.g., “Hero Section 0”). You can customize this per block type with label_field, or across all block types with row_label.

Per-Block label_field

Set label_field on each block definition to a sub-field name. The value of that field is used as the row title, and updates live as you type.

crap.fields.blocks({
    name = "content",
    blocks = {
        {
            type = "hero",
            label = "Hero Section",
            label_field = "heading",
            fields = {
                crap.fields.text({ name = "heading", required = true }),
                crap.fields.text({ name = "subheading" }),
            },
        },
        {
            type = "image",
            label = "Image",
            label_field = "caption",
            fields = {
                crap.fields.upload({ name = "image", relationship = { collection = "media" } }),
                crap.fields.text({ name = "caption" }),
            },
        },
    },
})

Each block type can have a different label_field — hero blocks show the heading, image blocks show the caption.

row_label (Lua function)

For computed labels across all block types, set admin.row_label on the blocks field. The function receives the full row data (including _block_type) and returns a display string.

-- collections/posts.lua
crap.fields.blocks({
    name = "content",
    admin = {
        row_label = "labels.content_block_row",
    },
    blocks = { ... },
})

-- hooks/labels.lua
local M = {}

function M.content_block_row(row)
    if row._block_type == "hero" then
        return "Hero: " .. (row.heading or "Untitled")
    elseif row._block_type == "code" then
        local lang = row.language or ""
        if lang ~= "" then return "Code (" .. lang .. ")" end
        return "Code"
    end
    return nil -- fall back to per-block label_field or default
end

return M

Priority

1. row_label Lua function (if set and returns a non-empty string)
2. Per-block label_field on the BlockDefinition
3. Field-level admin.label_field (shared across all block types)
4. Default: block type label + row index (e.g., “Hero Section 0”)

Note: row_label is only evaluated server-side. Rows added via JavaScript in the browser fall back to label_field (live-updated) or the default until the form is saved and reloaded.

Row Limits (min_rows / max_rows)

Enforce minimum and maximum block counts. These are validation constraints, not just UI hints.

crap.fields.blocks({
    name = "content",
    min_rows = 1,
    max_rows = 20,
    blocks = { ... },
})

• min_rows: Minimum number of blocks. Validated on create/update (skipped for draft saves).
• max_rows: Maximum number of blocks. Validated on create/update. The admin UI disables the “Add Block” button when the limit is reached.

Default Collapsed State (collapsed)

Existing block rows render collapsed by default on page load (admin.collapsed = true). Set admin.collapsed = false to start rows expanded. New blocks added via the UI are always expanded.

crap.fields.blocks({
    name = "content",
    admin = {
        collapsed = false, -- start rows expanded (default is true)
    },
    blocks = { ... },
})

Custom Labels (labels)

Customize the “Add Block” button text with singular/plural labels.

crap.fields.blocks({
    name = "content",
    admin = {
        labels = { singular = "Section", plural = "Sections" },
    },
    blocks = { ... },
})

With this config, the add button reads “Add Section” instead of “Add Block”.

Block Groups

Organize blocks into groups in the picker dropdown using <optgroup> elements. Ungrouped blocks appear at the top.

crap.fields.blocks({
    name = "content",
    blocks = {
        {
            type = "hero",
            label = "Hero Section",
            group = "Layout",
            fields = { ... },
        },
        {
            type = "columns",
            label = "Columns",
            group = "Layout",
            fields = { ... },
        },
        {
            type = "richtext",
            label = "Rich Text",
            group = "Content",
            fields = { ... },
        },
        {
            type = "divider",
            label = "Divider",
            -- No group: appears at the top of the dropdown
            fields = {},
        },
    },
})

Card Picker

By default, blocks use a dropdown select to choose the block type. Set admin.picker = "card" to use a visual card grid instead. This is useful when you have several block types and want a more visual picker.

crap.fields.blocks({
    name = "content",
    admin = {
        picker = "card",
    },
    blocks = {
        {
            type = "hero",
            label = "Hero Section",
            fields = { ... },
        },
        {
            type = "richtext",
            label = "Rich Text",
            fields = { ... },
        },
    },
})

Each card shows the block type label and a generic icon. To display custom icons or thumbnails, set image_url on individual block definitions:

blocks = {
    {
        type = "hero",
        label = "Hero Section",
        image_url = "/static/blocks/hero.svg",
        fields = { ... },
    },
    {
        type = "richtext",
        label = "Rich Text",
        image_url = "/static/blocks/text.svg",
        fields = { ... },
    },
}

Blocks without an image_url show a generic widget icon. Both group and image_url can be combined with the card picker.

Admin Rendering

Renders as a repeatable fieldset with:

• Drag handle for drag-and-drop reordering
• Row count badge showing the number of blocks
• Toggle collapse/expand all button
• Block type selector dropdown with “Add Block” button (or custom label)
• Each row shows the block type label (or custom label), move up/down, duplicate, and remove buttons
• “No items yet” empty state when no blocks exist
• Block-specific fields rendered within each row
• Add button disabled when max_rows is reached

Globals

Globals are single-document collections for site-wide settings. Each global stores exactly one row.

Definition

Define globals in globals/*.lua using crap.globals.define():

-- globals/site_settings.lua
crap.globals.define("site_settings", {
    labels = {
        singular = "Site Settings",
    },
    fields = {
        crap.fields.text({ name = "site_name", required = true, default_value = "My Site" }),
        crap.fields.text({ name = "tagline" }),
    },
})

Config Properties

Database Table

Each global gets a table named _global_{slug} with a single row where id = 'default'. The row is auto-created on startup.

Globals always have created_at and updated_at timestamp columns.

Differences from Collections

Lua API

-- Get current value
local settings = crap.globals.get("site_settings")
print(settings.site_name)

-- Update
crap.globals.update("site_settings", {
    site_name = "New Name",
    tagline = "A fresh start",
})

gRPC API

# Get
grpcurl -plaintext -d '{"slug": "site_settings"}' \
    localhost:50051 crap.ContentAPI/GetGlobal

# Update
grpcurl -plaintext -d '{
    "slug": "site_settings",
    "data": {"site_name": "Updated Site"}
}' localhost:50051 crap.ContentAPI/UpdateGlobal

Relationships

Relationship fields reference documents in other collections. Crap CMS supports two relationship types:

Has-One

A single reference stored as a TEXT column containing the related document’s ID.

crap.fields.relationship({
    name = "author",
    relationship = {
        collection = "users",
    },
})

At depth=0 (default for Find):

{ "author": "user_abc123" }

At depth=1:

{
    "author": {
        "id": "user_abc123",
        "collection": "users",
        "name": "Admin User",
        "email": "admin@example.com",
        "created_at": "2024-01-01 00:00:00"
    }
}

Has-Many

Multiple references stored in a junction table ({collection}_{field}).

crap.fields.relationship({
    name = "tags",
    relationship = {
        collection = "tags",
        has_many = true,
    },
})

At depth=0:

{ "tags": ["tag_1", "tag_2", "tag_3"] }

At depth=1:

{
    "tags": [
        { "id": "tag_1", "collection": "tags", "name": "Rust" },
        { "id": "tag_2", "collection": "tags", "name": "CMS" },
        { "id": "tag_3", "collection": "tags", "name": "Lua" }
    ]
}

Writing Relationships

Has-One

Set the field to the related document’s ID:

{ "author": "user_abc123" }

Has-Many

Pass an array of IDs:

{ "tags": ["tag_1", "tag_2", "tag_3"] }

Order is preserved via the _order column in the junction table.

On write, all existing junction table rows for the parent are deleted and replaced. This is a full replacement.

Partial Updates

For has-many fields, if the field is absent from the update data, the junction table is not modified. This supports partial updates — only explicitly included fields are changed.

Delete Protection

Every collection table has a _ref_count column that tracks how many documents reference it. When _ref_count > 0, the document cannot be deleted — this prevents orphaned references across collections.

How It Works

When document A has a relationship field pointing to document B, B’s _ref_count is incremented. When A is updated to point elsewhere or hard-deleted, B’s _ref_count is decremented. This makes delete protection an O(1) check — no scanning required.

Reference counting covers all relationship types:

Scope

Delete protection applies to all collections, not just uploads. Any document referenced by another document is protected.

Soft Delete Interaction

Soft-deleting a document does not adjust ref counts. The outgoing references remain counted because:

• Soft-deleted documents can be restored, so their references should remain tracked
• Trashed documents still “own” their references in the database

Only hard deletion (permanent) decrements ref counts on the targets.

Soft-deleted documents that are referenced by other documents can still be trashed — the ref count check only blocks deletion of the target document.

Admin UI

The delete confirmation page shows a warning when a document has _ref_count > 0:

This document is referenced by other content. Referenced by 3 document(s). [Show details]

Clicking Show details lazy-loads the full list of referencing documents, fields, and counts via the back-references API endpoint.

API Behavior

Admin & gRPC

Attempting to delete a document with _ref_count > 0 returns an error:

Cannot delete '<id>' from '<collection>': referenced by N document(s)

Lua API

-- Single delete: fails with error if referenced
local ok, err = pcall(crap.collections.delete, "media", "m1")

-- Bulk delete: skips referenced documents and reports the count
local result = crap.collections.delete_many("media", {
    where = { status = { equals = "unused" } }
})
-- result.deleted = documents actually deleted
-- result.skipped = documents skipped due to outstanding references

Force Hard Delete

The forceHardDelete option bypasses the ref count check. This is used internally for Empty Trash operations and can be used in Lua hooks:

crap.collections.delete("media", "m1", {
    forceHardDelete = true  -- skips ref count check
})

Back-References API

To see which documents reference a target, use the back-references endpoint:

GET /admin/collections/{slug}/{id}/back-references

Returns a JSON array:

[
    {
        "owner_slug": "posts",
        "owner_label": "Posts",
        "field_name": "image",
        "field_label": "Image",
        "document_ids": ["p1", "p2"],
        "count": 2,
        "is_global": false
    }
]

This endpoint performs the full back-reference scan, so it’s heavier than the ref count check. It’s designed for on-demand use (e.g., the “Show details” button).

Migration

When upgrading to a version with reference counting, the _ref_count column is automatically added to all collection and global tables. A one-time backfill migration computes the initial counts from existing relationship data. This runs automatically on first startup and is gated by a _crap_meta flag so it only runs once.

Population Depth

The depth parameter controls how deeply relationship fields are populated with full document objects.

Depth Values

Defaults

Configuration

Global Config

[depth]
default_depth = 1   # Default for FindByID (default: 1)
max_depth = 10       # Hard cap for all requests (default: 10)

Per-Field Max Depth

Cap the depth for a specific relationship field, regardless of the request-level depth:

crap.fields.relationship({
    name = "author",
    relationship = {
        collection = "users",
        max_depth = 1,  -- never populate deeper than 1, even if depth=5
    },
})

Usage

gRPC

# Find with depth=1
grpcurl -plaintext -d '{
    "collection": "posts",
    "depth": 1
}' localhost:50051 crap.ContentAPI/Find

# FindByID with depth=2
grpcurl -plaintext -d '{
    "collection": "posts",
    "id": "abc123",
    "depth": 2
}' localhost:50051 crap.ContentAPI/FindByID

Lua API

-- Find with depth
local result = crap.collections.find("posts", { depth = 1 })

-- FindByID with depth
local post = crap.collections.find_by_id("posts", id, { depth = 2 })

Circular Reference Protection

The population algorithm tracks visited (collection, id) pairs. If a document has already been visited in the current recursion path, it’s kept as a plain ID string instead of being populated again.

This prevents infinite loops when collections reference each other (e.g., posts → users → posts).

Performance

Population adds queries beyond the main find/find_by_id. How many depends on the depth and number of relationship fields.

How It Works

• Batch fetching: Find with depth >= 1 collects all referenced IDs across all returned documents per relationship field and fetches them in a single IN (...) query. This means one extra query per relationship field, regardless of how many documents reference it.
• Recursive batching: At depth >= 2, the same batch strategy applies recursively — populated documents’ relationships are batch-fetched at each depth level.
• Per-document fetching: FindByID populates a single document. Join fields (reverse lookups) also use per-document queries since they require a WHERE clause per parent.

Query Cost

Join fields add one query per document per join field at each depth level.

Populate Cache

For high-traffic deployments, an opt-in cross-request cache avoids redundant population queries. When enabled, populated documents are cached in memory and reused across requests. The cache is automatically cleared on any write operation (create, update, delete).

[depth]
populate_cache = true              # Enable cross-request populate cache (default: false)
populate_cache_max_age_secs = 60   # Optional: periodic full cache clear (default: 0 = off)

When to enable: High read traffic with repeated deep population of the same related documents (e.g., many posts referencing the same set of authors/categories).

Trade-off: If the database is modified outside the API (e.g., direct SQL, external tools), cached data can become stale. Set populate_cache_max_age_secs to limit staleness, or leave the cache disabled (default).

Recommendations

• Use depth=0 for list endpoints. Find defaults to depth=0 for this reason. Fetch related data when displaying a single document instead.
• Use select to limit populated fields. Non-selected relationship fields are skipped entirely during population.
• Set per-field max_depth on relationship fields that don’t need deep population.
• If you need related data in a list, use depth=1 with select to populate only the specific relationship fields you need.

Query & Filters

Unified reference for querying documents across both the Lua API and gRPC API.

Filter Operators

Note: For exists/not_exists, the value is ignored — only the key matters. Use not_exists for IS NULL (not { exists = false }).

gRPC shorthand limitation: In Lua, bare values like { count = 42 } or { active = true } are coerced to string equals. The gRPC where JSON only accepts string or operator object values — numeric/boolean shorthand is not supported.

Sorting

Prefix a field name with - for descending order. When order_by is omitted, results are sorted by created_at DESC (newest first) for collections with timestamps, or id ASC otherwise. When sorting by a non-id field, an id tiebreaker is always appended for stable ordering.

Lua:

crap.collections.find("posts", { order_by = "-created_at" })

gRPC:

grpcurl -plaintext -d '{
    "collection": "posts",
    "order_by": "-created_at"
}' localhost:50051 crap.ContentAPI/Find

Pagination

Use limit and page for pagination. The response includes a nested pagination object with total count and page info.

Lua:

local result = crap.collections.find("posts", {
    limit = 10,
    page = 3,
})
-- result.pagination.totalDocs   = 150 (total matching documents)
-- result.pagination.limit       = 10
-- result.pagination.totalPages  = 15
-- result.pagination.page        = 3   (1-based)
-- result.pagination.pageStart   = 21  (1-based index of first doc on this page)
-- result.pagination.hasNextPage = true
-- result.pagination.hasPrevPage = true
-- result.pagination.prevPage    = 2
-- result.pagination.nextPage    = 4
-- #result.documents             = 10  (this page)

gRPC:

grpcurl -plaintext -d '{
    "collection": "posts",
    "limit": "10",
    "page": "3"
}' localhost:50051 crap.ContentAPI/Find

Cursor-Based Pagination

Cursor-based pagination is opt-in via [pagination] mode = "cursor" in crap.toml. When enabled, the pagination object includes opaque startCursor and endCursor tokens instead of page/totalPages. These represent the cursors of the first and last documents in the result set. Pass after_cursor (forward) or before_cursor (backward) on the next request to navigate from any cursor position.

after_cursor/before_cursor and page are mutually exclusive. after_cursor and before_cursor are also mutually exclusive with each other.

Lua:

-- First page
local result = crap.collections.find("posts", {
    order_by = "-created_at",
    limit = 10,
})
-- result.pagination.hasNextPage  = true
-- result.pagination.hasPrevPage  = false
-- result.pagination.startCursor  = "eyJpZCI6ImFiYzEyMyJ9"  (cursor of first doc)
-- result.pagination.endCursor    = "eyJpZCI6Inh5ejc4OSJ9"  (cursor of last doc)

-- Next page (forward)
local page2 = crap.collections.find("posts", {
    order_by = "-created_at",
    limit = 10,
    after_cursor = result.pagination.endCursor,
})

-- Previous page (backward)
local page1_again = crap.collections.find("posts", {
    order_by = "-created_at",
    limit = 10,
    before_cursor = page2.pagination.startCursor,
})

gRPC:

# First page
grpcurl -plaintext -d '{
    "collection": "posts",
    "order_by": "-created_at",
    "limit": "10"
}' localhost:50051 crap.ContentAPI/Find
# Response pagination includes start_cursor / end_cursor when cursor mode is active

# Next page (forward)
grpcurl -plaintext -d '{
    "collection": "posts",
    "order_by": "-created_at",
    "limit": "10",
    "after_cursor": "eyJpZCI6Inh5ejc4OSJ9"
}' localhost:50051 crap.ContentAPI/Find

# Previous page (backward)
grpcurl -plaintext -d '{
    "collection": "posts",
    "order_by": "-created_at",
    "limit": "10",
    "before_cursor": "eyJpZCI6ImFiYzEyMyJ9"
}' localhost:50051 crap.ContentAPI/Find

Cursors encode the position of a document in the sorted result set. They are opaque — do not parse or construct them manually. startCursor and endCursor are always present when the result set is non-empty.

Combining Filters

Multiple filters are combined with AND:

Lua:

crap.collections.find("posts", {
    where = {
        status = "published",
        created_at = { greater_than = "2024-01-01" },
        title = { contains = "update" },
    },
    order_by = "-created_at",
    limit = 10,
})

gRPC:

grpcurl -plaintext -d '{
    "collection": "posts",
    "where": "{\"status\":\"published\",\"created_at\":{\"greater_than\":\"2024-01-01\"},\"title\":{\"contains\":\"update\"}}",
    "order_by": "-created_at",
    "limit": "10"
}' localhost:50051 crap.ContentAPI/Find

OR Filters

Use the or key to combine groups of conditions with OR logic. Each element in the or array is an object whose fields are AND-ed together. Multiple or groups are joined with OR.

Lua:

-- title contains "hello" OR category = "news"
crap.collections.find("posts", {
    where = {
        ["or"] = {
            { title = { contains = "hello" } },
            { category = "news" },
        },
    },
})

-- status = "published" AND (title contains "hello" OR title contains "world")
crap.collections.find("posts", {
    where = {
        status = "published",
        ["or"] = {
            { title = { contains = "hello" } },
            { title = { contains = "world" } },
        },
    },
})

-- Multi-condition groups: (status = "published" AND title contains "hello") OR (status = "draft")
crap.collections.find("posts", {
    where = {
        ["or"] = {
            { status = "published", title = { contains = "hello" } },
            { status = "draft" },
        },
    },
})

gRPC:

# title contains "hello" OR category = "news"
grpcurl -plaintext -d '{
    "collection": "posts",
    "where": "{\"or\":[{\"title\":{\"contains\":\"hello\"}},{\"category\":\"news\"}]}"
}' localhost:50051 crap.ContentAPI/Find

# status = "published" AND (title contains "hello" OR title contains "world")
grpcurl -plaintext -d '{
    "collection": "posts",
    "where": "{\"status\":\"published\",\"or\":[{\"title\":{\"contains\":\"hello\"}},{\"title\":{\"contains\":\"world\"}}]}"
}' localhost:50051 crap.ContentAPI/Find

Top-level filters and or groups are combined with AND. Each object inside the or array can have multiple fields which are AND-ed together within that group.

Field Selection (select)

Use select to specify which fields to return. Reduces data transfer and skips relationship hydration/population for non-selected fields. The id, created_at, and updated_at fields are always included.

Lua:

-- Return only title and status
crap.collections.find("posts", {
    select = { "title", "status" },
})

-- Works with find_by_id too
crap.collections.find_by_id("posts", id, {
    select = { "title", "status" },
})

gRPC:

# Return only title and status fields
grpcurl -plaintext -d '{
    "collection": "posts",
    "select": ["title", "status"]
}' localhost:50051 crap.ContentAPI/Find

# FindByID with select
grpcurl -plaintext -d '{
    "collection": "posts",
    "id": "abc123",
    "select": ["title", "status"]
}' localhost:50051 crap.ContentAPI/FindByID

Behavior:

• select is optional. When omitted or empty, all fields are returned (backward compatible).
• System fields (id, created_at, updated_at) are always included.
• Selecting a group field name (e.g., "seo") includes all its sub-fields.
• Relationship fields not in select are skipped during population (saves N+1 queries).

Field Validation

All filter field names and order_by fields are validated against the collection’s field definitions. Invalid field names return an error. This prevents SQL injection via field names.

Draft Parameter (Versioned Collections)

Collections with versions = { drafts = true } automatically filter by _status = 'published' on Find queries. Use the draft parameter to change this behavior.

Lua:

-- Default: only published documents
local published = crap.collections.find("articles", {})

-- Include drafts
local all = crap.collections.find("articles", { draft = true })

-- FindByID: get the latest version (may be a draft)
local latest = crap.collections.find_by_id("articles", id, { draft = true })

gRPC:

# Default: only published
grpcurl -plaintext -d '{"collection": "articles"}' \
    localhost:50051 crap.ContentAPI/Find

# Include drafts
grpcurl -plaintext -d '{"collection": "articles", "draft": true}' \
    localhost:50051 crap.ContentAPI/Find

# FindByID: get latest version snapshot
grpcurl -plaintext -d '{"collection": "articles", "id": "abc123", "draft": true}' \
    localhost:50051 crap.ContentAPI/FindByID

You can also filter directly on _status:

crap.collections.find("articles", {
    where = { _status = "draft" },
})

See Versions & Drafts for the full workflow.

Nested Field Filters (Dot Notation)

You can filter on sub-fields of group, array, blocks, and has-many relationship fields using dot notation.

Group Fields

Group sub-fields can be filtered using dot notation. Internally, seo.meta_title is converted to seo__meta_title (the flat column name). The double-underscore syntax also continues to work.

Lua:

crap.collections.find("pages", {
    where = {
        ["seo.meta_title"] = { contains = "SEO" },
    },
})

gRPC:

grpcurl -plaintext -d '{
    "collection": "pages",
    "where": "{\"seo.meta_title\":{\"contains\":\"SEO\"}}"
}' localhost:50051 crap.ContentAPI/Find

Array Sub-Fields

Filter by sub-field values in array rows. Uses an EXISTS subquery against the array join table. Returns parent documents that have at least one array row matching the condition.

Lua:

-- Find products where any variant has color "red"
crap.collections.find("products", {
    where = {
        ["variants.color"] = "red",
    },
})

-- Group-in-array: filter by a group sub-field within array rows
-- (uses json_extract on the JSON column in the join table)
crap.collections.find("products", {
    where = {
        ["variants.dimensions.width"] = "10",
    },
})

Block Sub-Fields

Filter by field values inside block rows. Uses json_extract on the block data column. Returns parent documents that have at least one block row matching.

Lua:

-- Find posts where any content block has body containing "hello"
crap.collections.find("posts", {
    where = {
        ["content.body"] = { contains = "hello" },
    },
})

-- Filter by block type
crap.collections.find("posts", {
    where = {
        ["content._block_type"] = "image",
    },
})

-- Group-in-block: filter by a group sub-field within block data
crap.collections.find("posts", {
    where = {
        ["content.meta.author"] = "Alice",
    },
})

Has-Many Relationships

Filter by related document IDs. Uses an EXISTS subquery against the relationship join table.

Lua:

-- Find posts that have tag "tag-123"
crap.collections.find("posts", {
    where = {
        ["tags.id"] = "tag-123",
    },
})

Combining Nested and Regular Filters

Nested field filters can be freely combined with regular column filters and OR groups:

Lua:

crap.collections.find("products", {
    where = {
        status = "published",
        ["variants.color"] = "red",
        ["or"] = {
            { ["content._block_type"] = "image" },
            { ["tags.id"] = "tag-featured" },
        },
    },
})

All filter operators (equals, contains, like, in, greater_than, etc.) work with nested field filters.

Full-Text Search

Use the search parameter for fast full-text search powered by SQLite FTS5. This searches across all text-like fields (text, textarea, richtext, email, code) or the fields specified in list_searchable_fields in the collection’s admin config.

Lua:

local result = crap.collections.find("posts", {
    search = "hello world",
    limit = 10,
})

gRPC:

grpcurl -plaintext -d '{
    "collection": "posts",
    "search": "hello world",
    "limit": "10"
}' localhost:50051 crap.ContentAPI/Find

Behavior:

• Each whitespace-separated word is treated as a literal search term (implicit AND).
• Results are ranked by relevance (FTS5 rank).
• search can be combined with where filters, pagination, sorting, and all other query parameters.
• Collections without text fields silently ignore the search parameter.
• The search parameter also works with Count to get the total number of matching documents.

Indexed fields are determined by:

1. admin.list_searchable_fields if configured on the collection.
2. Otherwise, all parent-level fields with types: text, textarea, richtext, email, code.

The FTS index is automatically created and rebuilt on server startup for every collection with text fields.

Valid Filter Fields

You can filter on any column in the collection table:

• User-defined fields (that have parent columns)
• id
• created_at (if timestamps enabled)
• updated_at (if timestamps enabled)
• _status (if versions.drafts enabled)

Additionally, you can filter on sub-fields using dot notation:

• Group sub-fields: group_name.sub_field (syntactic sugar for group_name__sub_field)
• Array sub-fields: array_name.sub_field or array_name.group.sub_field (group-in-array)
• Block sub-fields: blocks_name.field, blocks_name._block_type, or blocks_name.group.sub_field
• Has-many relationships: relationship_name.id

Hooks

Hooks let you intercept and modify data at every stage of a document’s lifecycle. They’re the primary extension mechanism in Crap CMS.

Three Levels of Hooks

1. Field-level hooks — per-field value transformers. Defined on individual FieldDefinition entries.
2. Collection-level hooks — per-collection lifecycle hooks. Defined on CollectionDefinition or GlobalDefinition.
3. Globally registered hooks — fire for all collections. Registered via crap.hooks.register() in init.lua.

All hooks at all levels run in this order for each lifecycle event:

field-level → collection-level → globally registered

Hook References

Collection-level and field-level hooks are string references in module.function format:

hooks = {
    before_change = { "hooks.posts.auto_slug" },
}

This resolves to require("hooks.posts").auto_slug via Lua’s module system. The config directory is on the package path, so hooks/posts.lua should return a module table:

-- hooks/posts.lua
local M = {}

function M.auto_slug(ctx)
    if ctx.data.slug == nil or ctx.data.slug == "" then
        ctx.data.slug = crap.util.slugify(ctx.data.title or "")
    end
    return ctx
end

return M

No Closures

Hook references are always strings, never Lua functions. This keeps collection definitions serializable (important for the future visual builder).

The one exception is crap.hooks.register(), which takes a function directly — but it’s called in init.lua, not in collection definitions.

CRUD Access in Hooks

Before-event hooks (before_validate, before_change, before_delete) have full CRUD access via the crap.collections.* and crap.globals.* APIs. They share the parent operation’s database transaction.

After-write hooks (after_change, after_delete) also have CRUD access and run inside the same transaction. Errors roll back the entire operation.

After-read hooks (after_read) do NOT have CRUD access.

See Transaction Access for details.

Concurrency

Hooks execute in a pool of Lua VMs, allowing concurrent hook execution across requests. The pool size is configurable:

[hooks]
vm_pool_size = 8  # default: max(available_parallelism, 4), capped at 32

Each VM is fully initialized at startup with the same configuration (package paths, API registration, CRUD functions, init.lua execution). When a request needs to execute a hook, it acquires a VM from the pool and returns it when done. This prevents hook execution from serializing under concurrent load.

Resource Limits

Lua VMs have configurable instruction, memory, and recursion limits to prevent runaway hooks:

[hooks]
max_depth = 3                      # max hook recursion depth (hook → CRUD → hook; 0 = no hooks from Lua CRUD)
max_instructions = 10000000        # per hook invocation (0 = unlimited)
max_memory = 52428800              # per VM in bytes, 50 MB (0 = unlimited)
allow_private_networks = false     # block HTTP to internal IPs
http_max_response_bytes = 10485760 # 10 MB (increase for large file downloads)

• Instruction limit — a hook that exceeds the instruction count is terminated with an error. The default (10M) is generous for complex hooks.
• Memory limit — caps total Lua memory per VM. Exceeding it raises a memory error.
• Private network blocking — crap.http.request resolves hostnames and rejects private/loopback/link-local IPs unless allow_private_networks = true.
• crap.crypto.random_bytes — capped at 1 MB per call.

State & Module Caching

Lua’s require function caches modules in package.loaded. This means module-level variables persist across requests on the same VM:

-- hooks/posts.lua
local M = {}
local counter = 0  -- persists across requests!

function M.before_change(ctx)
    counter = counter + 1  -- increments forever on this VM
    return ctx
end

return M

To avoid cross-request state leaks, keep hook functions stateless — use the ctx table for input/output, and crap.collections.* for persistent storage. If you need request-scoped state, store it in ctx.context (the request-scoped shared table — see Hook Context), not module-level locals.

Module-level constants and utility functions are fine — only mutable state is the concern.

Important: VM pool behavior. Since HookRunner uses a pool of Lua VMs, global state in Lua modules persists across requests within the same VM but is not shared across VMs. Each VM in the pool has its own independent copy of module-level variables. This means:

• Module-level variables can act as in-memory caches, but different requests may hit different VMs and see different cached values.
• Cached state is not consistent across the pool — one VM’s counter may be at 5 while another is at 12.
• All cached state is lost on server restart (VMs are re-initialized from scratch).

If you need shared, consistent state, use crap.collections.* or crap.globals.* to persist to the database.

Lifecycle Events

Nine lifecycle events fire during CRUD operations and admin page rendering.

Event Reference

* before_read hooks have no CRUD access when called from the gRPC API or admin UI. However, when triggered from a Lua CRUD call inside a hook (e.g., crap.collections.find() inside before_change), before_read hooks inherit the parent’s transaction context and DO have CRUD access.

Document ID in Hook Context

In after_change and after_delete hooks, context.data.id contains the document ID. This is useful for queuing jobs or looking up the document after it’s been written. In before_delete hooks, context.data.id is also available.

Write Lifecycle (create/update)

1. field before_validate hooks (CRUD access)
2. collection before_validate hooks (CRUD access)
3. global registered before_validate hooks (CRUD access)
4. field validation (required, unique, custom validate)
5. field before_change hooks (CRUD access)
6. collection before_change hooks (CRUD access)
7. global registered before_change hooks (CRUD access)
8. database write (INSERT or UPDATE)
9. join table write (has-many relationships, arrays)
10. field after_change hooks (CRUD access, same transaction)
11. collection after_change hooks (CRUD access, same transaction)
12. global registered after_change hooks (CRUD access, same transaction)
13. transaction commit
14. live setting check (background)
15. before_broadcast hooks (background, no CRUD)
16. EventBus publish (if not suppressed)

Bulk Operations (update_many/delete_many)

update_many and delete_many run the same per-document lifecycle as their single-document counterparts. Each matched document goes through the full hook pipeline individually, all within a single transaction (all-or-nothing).

update_many runs steps 1–12 above for each document. Key differences from single-document update:

• Only provided fields are written (partial update). Absent fields — including checkboxes — are left unchanged.
• Password updates are rejected. Use single-document Update instead.
• Hook-modified data is captured and written (hooks can transform the data).
• Set hooks = false to skip all hooks and validation for performance.

delete_many runs the delete lifecycle (steps 1–5 below) for each document.

Read Lifecycle (find/find_by_id)

1. collection before_read hooks
2. global registered before_read hooks
3. database query
4. field after_read hooks
5. collection after_read hooks
6. global registered after_read hooks

Delete Lifecycle

1. collection before_delete hooks (CRUD access)
2. global registered before_delete hooks (CRUD access)
3. database delete
4. collection after_delete hooks (CRUD access, same transaction)
5. global registered after_delete hooks (CRUD access, same transaction)
6. transaction commit
7. live setting check (background)
8. before_broadcast hooks (background, no CRUD)
9. EventBus publish (if not suppressed)

Execution Order

At each lifecycle stage, hooks run in this order:

1. Field-level hooks (per-field, in field definition order)
2. Collection-level hooks (string refs from collection definition, in array order)
3. Globally registered hooks (from crap.hooks.register(), in registration order)

Example: before_change on create

Given this setup:

-- collections/posts.lua
crap.collections.define("posts", {
    fields = {
        crap.fields.text({
            name = "title",
            hooks = { before_change = { "hooks.fields.uppercase" } },
        }),
        crap.fields.text({
            name = "slug",
            hooks = { before_change = { "hooks.fields.normalize_slug" } },
        }),
    },
    hooks = {
        before_change = { "hooks.posts.set_defaults", "hooks.posts.validate_business_rules" },
    },
})

-- init.lua
crap.hooks.register("before_change", function(ctx)
    crap.log.info("audit: " .. ctx.operation .. " on " .. ctx.collection)
    return ctx
end)

Execution order for a create operation:

1. hooks.fields.uppercase (field: title)
2. hooks.fields.normalize_slug (field: slug)
3. hooks.posts.set_defaults (collection)
4. hooks.posts.validate_business_rules (collection)
5. Registered audit function (global)

Multiple Hooks per Event

Both field-level and collection-level hooks accept arrays. Hooks in the same array run sequentially, each receiving the output of the previous one.

hooks = {
    before_change = { "hooks.posts.first", "hooks.posts.second" },
}

first runs, its returned context is passed to second.

Field Hooks

Field-level hooks operate on individual field values rather than the full document context.

Signature

function hook(value, context)
    -- transform value
    return new_value
end

Return value: The new field value. This replaces the existing value in the data.

Context Table

Typed Contexts

The type generator (crap-cms typegen) emits per-collection field hook contexts with typed data fields:

• Collections: crap.field_hook.{PascalCase} — e.g., crap.field_hook.Posts has data: crap.data.Posts
• Globals: crap.field_hook.global_{slug} — e.g., crap.field_hook.global_site_settings has data: crap.global_data.SiteSettings

Use the typed context when a hook is specific to one collection:

---@param value number|nil
---@param context crap.field_hook.Inquiries
---@return number|nil
return function(value, context)
    -- context.data is typed as crap.data.Inquiries
    -- IDE autocompletes context.data.name, context.data.email, etc.
    return value
end

For shared hooks that work across multiple collections, use the generic crap.FieldHookContext (where data is table<string, any>).

Events

Definition

crap.fields.text({
    name = "title",
    hooks = {
        before_validate = { "hooks.fields.trim" },
        before_change = { "hooks.fields.sanitize_html" },
        after_read = { "hooks.fields.add_word_count" },
    },
})

Example

-- hooks/fields.lua
local M = {}

function M.trim(value, ctx)
    if type(value) == "string" then
        return value:match("^%s*(.-)%s*$")
    end
    return value
end

function M.slugify(value, ctx)
    -- Auto-generate slug from title if empty
    if (value == nil or value == "") and ctx.data.title then
        return crap.util.slugify(ctx.data.title)
    end
    return value
end

return M

Registered Hooks

Registered hooks fire for all collections at a given lifecycle event. Register them in init.lua using crap.hooks.register().

Registration

-- init.lua
crap.hooks.register("before_change", function(ctx)
    crap.log.info("[audit] " .. ctx.operation .. " on " .. ctx.collection)
    return ctx
end)

Unlike collection-level hooks (which are string references), registered hooks are Lua functions passed directly.

API

crap.hooks.register(event, fn)

Register a hook function for a lifecycle event.

crap.hooks.remove(event, fn)

Remove a previously registered hook. Uses rawequal for identity-based matching — you must pass the exact same function reference.

local my_hook = function(ctx)
    -- ...
    return ctx
end

crap.hooks.register("before_change", my_hook)
-- Later:
crap.hooks.remove("before_change", my_hook)

CRUD Access

Registered hooks follow the same rules as collection-level hooks:

• Before-event hooks (before_validate, before_change, before_delete) have CRUD access via the shared transaction
• Write after-event hooks (after_change, after_delete) have CRUD access — they run inside the same transaction via run_hooks_with_conn
• Read after-event hooks (after_read) do NOT have CRUD access — they run without a transaction

Execution Order

Registered hooks run after field-level and collection-level hooks at each lifecycle stage.

Example: Audit Log

-- init.lua
crap.hooks.register("before_change", function(ctx)
    crap.log.info(string.format(
        "[audit] %s %s: %s",
        ctx.operation,
        ctx.collection,
        ctx.data.id or "(new)"
    ))
    return ctx
end)

Example: Auto-Set Created By

-- init.lua (requires auth + access context in hooks)
crap.hooks.register("before_change", function(ctx)
    if ctx.operation == "create" then
        -- Set created_by to current user ID if field exists
        -- (requires the collection to have a created_by field)
    end
    return ctx
end)

Hook Context

Collection-level hooks receive a context table and must return a (potentially modified) context table.

Context Shape

{
    collection = "posts",       -- Collection slug
    operation = "create",       -- "create", "update", "delete", "find", "find_by_id", or "init"
    data = {                    -- Document data (mutable in before-write hooks)
        title = "Hello World",
        slug = "hello-world",
        status = "draft",
        id = "abc123",          -- Present on update/delete, absent on create
        created_at = "...",     -- Present on read/update
        updated_at = "...",
    },
    locale = "en",              -- Locale for this operation (nil if not locale-specific)
    draft = true,               -- Whether this is a draft save (versioned collections only)
    hook_depth = 0,             -- Current recursion depth (0 = top-level, 1+ = from Lua CRUD in hooks)
    context = {                 -- Request-scoped shared table (persists across all hooks in the same request)
        -- Hooks can read and write arbitrary keys here to share data
    },
    user = {                    -- Authenticated user document (nil if unauthenticated)
        id = "user_123",
        email = "admin@example.com",
        role = "admin",
        -- ... all fields from the auth collection
    },
    ui_locale = "en",           -- Admin UI locale (nil if not set)
}

Typed Contexts

The type generator (crap-cms typegen) emits per-collection context types with typed data fields for IDE autocomplete:

• Collections: crap.hook.{PascalCase} — e.g., crap.hook.Posts has data: crap.data.Posts and collection: "posts" (literal)
• Globals: crap.hook.global_{slug} — e.g., crap.hook.global_site_settings has data: crap.global_data.SiteSettings

Use the typed context for hooks that target a specific collection:

---@param context crap.hook.Posts
---@return crap.hook.Posts
return function(context)
    -- context.data.title, context.data.slug, etc. autocomplete
    return context
end

Delete hooks receive only { id = "..." } in data (not full document fields), so they use the generic crap.HookContext:

---@param context crap.HookContext
---@return crap.HookContext
return function(context)
    local id = context.data.id
    return context
end

For shared hooks that fire across multiple collections (e.g., via crap.hooks.register()), use the generic crap.HookContext.

Data Mutation

In before-write hooks (before_validate, before_change), you can modify ctx.data and return the modified context. The changes flow through to the database write.

function M.auto_slug(ctx)
    if not ctx.data.slug or ctx.data.slug == "" then
        ctx.data.slug = crap.util.slugify(ctx.data.title or "")
    end
    return ctx
end

In after-read hooks, you can also modify ctx.data to transform the response before it reaches the client.

Return Value

Hooks must return the context table (or a new table with data). If a hook returns:

• A table with a data key — the data is replaced
• A table without a data key — the original data is kept
• A non-table value — the original context is kept

System Fields in Data

On create, id is not yet assigned (it’s generated by the database write).

Draft Field

For versioned collections with drafts = true, the context includes a draft field:

You can use this in hooks to customize behavior based on publish state:

function M.before_change(ctx)
    if ctx.draft then
        -- Draft save: skip expensive operations
        return ctx
    end
    -- Publishing: run full processing
    ctx.data.published_at = os.date("!%Y-%m-%d %H:%M:%S")
    return ctx
end

User

The user field contains the full authenticated user document from the auth collection, or nil if the request is unauthenticated (or no auth collection exists). This is the same user document used by access control functions.

function M.before_change(ctx)
    if ctx.user then
        ctx.data.last_edited_by = ctx.user.email
    end
    return ctx
end

UI Locale

The ui_locale field contains the admin UI locale code (e.g., "en", "de"), or nil if not set. This is useful for returning user-facing messages (e.g., validation errors) in the correct language.

function M.validate_title(value, ctx)
    if not value or value == "" then
        if ctx.ui_locale == "de" then
            return "Titel ist erforderlich"
        end
        return "Title is required"
    end
    return true
end

Hook Depth

The hook_depth field tracks how deep in the hook→CRUD→hook chain the current execution is:

When hook_depth reaches hooks.max_depth (default: 3, configurable in crap.toml), hooks are automatically skipped but the DB operation still executes. This prevents infinite recursion when hooks create/update documents in the same collection.

function M.audit_hook(ctx)
    -- Only audit at the top level, not from recursive hook calls
    if ctx.hook_depth >= 1 then
        return ctx
    end
    crap.collections.create("audit_log", {
        action = ctx.operation,
        collection = ctx.collection,
    })
    return ctx
end

Context (Request-Scoped Shared Table)

The context field is a request-scoped table that persists across all hooks in the same request. It allows hooks to share data with each other without relying on module-level state.

Each hook in the chain receives the same context table, and any modifications made by one hook are visible to all subsequent hooks in the same request. The table starts empty at the beginning of each request.

This is useful for:

• Passing computed values from before_validate to before_change without recomputing
• Sharing request metadata between hooks
• Accumulating data across multiple hooks for use in after_change

-- In before_validate hook: compute and share a value
function M.before_validate(ctx)
    ctx.context.original_title = ctx.data.title
    return ctx
end

-- In after_change hook: use the shared value
function M.after_change(ctx)
    if ctx.context.original_title ~= ctx.data.title then
        crap.log.info("Title changed from: " .. (ctx.context.original_title or "nil"))
    end
    return ctx
end

Note: The context table is not the same as module-level variables. Module-level variables persist across requests on the same VM (see Hooks Overview), while context is scoped to a single request and automatically cleaned up.

Transaction Access

Hooks can call back into the Crap CMS CRUD API. Whether a hook has CRUD access depends on the lifecycle event.

Which Hooks Get CRUD Access?

This applies to all three hook levels (field, collection, registered).

Available Functions

Inside hooks with CRUD access:

-- Collections
crap.collections.find("posts", { where = { status = "published" } })
crap.collections.find_by_id("posts", "abc123")
crap.collections.create("audit_log", { action = "update", target = ctx.data.id })
crap.collections.update("posts", id, { view_count = views + 1 })
crap.collections.delete("drafts", old_id)

-- Globals
crap.globals.get("site_settings")
crap.globals.update("counters", { total_posts = count + 1 })

Transaction Sharing

CRUD calls inside hooks share the same database transaction as the parent operation. This means:

• If the hook creates a document and the parent operation later fails, the created document is rolled back
• If the hook fails, the entire parent operation rolls back
• All changes are atomic — either everything commits or nothing does

This applies to all write hooks: before_validate, before_change, after_change, before_delete, and after_delete.

Error Handling

If any hook (before or after) returns an error or throws a Lua error, the entire transaction is rolled back and the operation fails with an error message. This includes after-hooks — an after_change error will roll back the main DB operation too.

Calling CRUD Outside Hooks

Calling crap.collections.find() etc. outside a hook context (no active transaction) results in an error:

crap.collections CRUD functions are only available inside hooks
with transaction context (before_change, before_delete, etc.)

on_init Hooks

The [hooks] on_init list in crap.toml runs at startup with CRUD access. All on_init hooks share a single database transaction — if any hook fails, all changes are rolled back. This makes seeding and startup migrations atomic:

[hooks]
on_init = ["hooks.seed.run"]

-- hooks/seed.lua
local M = {}

function M.run(ctx)
    local result = crap.collections.find("posts")
    if result.pagination.totalDocs == 0 then
        crap.collections.create("posts", {
            title = "Welcome",
            slug = "welcome",
            status = "published",
            content = "Welcome to your new site!",
        })
        crap.log.info("Seeded initial post")
    end
    return ctx
end

return M

If an on_init hook fails, the server aborts startup.

Access Control Functions

Access control functions (access.read, access.create, access.update, access.delete on collections/globals and access.read, access.create, access.update on fields) run with CRUD access inside their own transaction. Each access check gets a dedicated transaction that commits on success or rolls back on error.

Auth Strategies

Custom auth strategy authenticate functions run with CRUD access inside a transaction. All strategies for a given request share a single transaction — if a strategy authenticates successfully, the transaction commits. If all strategies fail, the transaction rolls back.

Jobs

Background job system for scheduled and queued tasks.

Overview

Crap CMS includes a built-in job scheduler for running background tasks. Jobs are defined in Lua, can be triggered manually or on a cron schedule, and execute with full CRUD access to all collections.

Use cases:

• Scheduled cleanup (e.g., delete expired posts nightly)
• Async processing triggered from hooks (e.g., send welcome email after user creation)
• Periodic data sync or aggregation

Defining Jobs

Jobs are defined via crap.jobs.define() in init.lua or files under jobs/:

-- jobs/cleanup_expired.lua
crap.jobs.define("cleanup_expired", {
    handler = "jobs.cleanup_expired.run",
    schedule = "0 3 * * *",        -- daily at 3am
    queue = "maintenance",
    retries = 3,
    timeout = 300,
    concurrency = 1,
    skip_if_running = true,
    labels = { singular = "Cleanup Expired Posts" },
    access = "hooks.check_admin",  -- optional access control
})

local M = {}
function M.run(ctx)
    -- ctx.data = input data from queue() or {} for cron
    -- ctx.job = { slug, attempt, max_attempts }
    -- Full CRUD access available
    local expired = crap.collections.find("posts", {
        where = { expires_at = { less_than = os.date("!%Y-%m-%dT%H:%M:%SZ") } }
    })
    for _, doc in ipairs(expired.documents) do
        crap.collections.delete("posts", doc.id)
    end
    return { deleted = #expired.documents }
end
return M

Configuration Options

Queuing from Hooks

Jobs can be queued programmatically from hooks:

-- In a hook
crap.jobs.queue("send_welcome_email", { user_id = ctx.data.id, email = ctx.data.email })

queue() inserts a pending job and returns immediately. The scheduler picks it up on its next poll cycle.

Handler Context

The handler function receives a context table:

function M.run(ctx)
    ctx.data          -- table: input data from queue() or {} for cron
    ctx.job.slug      -- string: job definition slug
    ctx.job.attempt   -- integer: current attempt (1-based)
    ctx.job.max_attempts -- integer: total attempts allowed
end

The handler has full CRUD access (crap.collections.find(), .create(), etc.) running inside its own database transaction. If the handler returns a table, it’s stored as the job result (JSON). If it errors, the job is marked failed (and retried if attempts remain).

Back Pressure

• Global concurrency: [jobs] max_concurrent in crap.toml (default: 10)
• Per-job concurrency: concurrency field on the definition
• Timeout: Jobs running longer than timeout are marked failed
• Skip-if-running: Cron-triggered jobs skip if a previous run is still active

Error Handling

Job execution is fully isolated. If a job handler panics, the panic is caught and logged — it does not crash the server or affect other jobs. The job is marked as failed and retried if attempts remain.

Crash Recovery

On startup, the scheduler marks any previously-running jobs as stale (the server was restarted while they were executing). Jobs with remaining retry attempts are re-queued.

Running jobs update a heartbeat timestamp periodically so stale detection works even during normal operation.

Configuration (crap.toml)

[jobs]
max_concurrent = 10       # global concurrency limit
poll_interval = 1         # seconds between pending job polls
cron_interval = 60        # seconds between cron schedule checks
heartbeat_interval = 10   # seconds between heartbeat updates
auto_purge = "7d"         # auto-delete completed jobs older than this

CLI Commands

crap-cms -C <config_dir> jobs list                   # list defined jobs
crap-cms -C <config_dir> jobs trigger <slug>         # manually queue a job
crap-cms -C <config_dir> jobs status [--id <id>]     # show recent job runs
crap-cms -C <config_dir> jobs purge [--older-than 7d] # clean up old runs

gRPC API

Four RPCs for job management:

• ListJobs — list all defined jobs
• TriggerJob(slug, data_json?) — queue a job, returns the run ID
• GetJobRun(id) — get details of a specific run
• ListJobRuns(slug?, status?, limit?, offset?) — list job runs with filters

All require authentication. TriggerJob also checks the job’s access function if defined.

Plugins

Crap CMS doesn’t have a formal plugin system. It doesn’t need one — Lua’s open module system provides everything required. A plugin is just a Lua module that modifies collections, globals, registers hooks, or any combination.

How It Works

1. Collection and global definition files (collections/*.lua, globals/*.lua) are auto-loaded first.
2. init.lua runs after all definitions are registered.
3. Plugins are require()-d from init.lua and can read, modify, or extend any registered collection or global.

This works because crap.collections.define() and crap.globals.define() overwrite — calling either twice for the same slug replaces the first definition with the second.

Writing a Plugin

A plugin is a Lua module that returns a table with an install() function:

-- plugins/audit_log.lua
local M = {}

function M.install()
    -- Register a global hook that runs for all collections
    crap.hooks.register("before_change", function(ctx)
        if ctx.operation == "create" then
            ctx.data.created_by = ctx.user and ctx.user.email or "system"
        end
    end)
end

return M

Modifying Collections

Use crap.collections.config.get() to retrieve a single collection, or crap.collections.config.list() to iterate all collections:

-- plugins/alt_text.lua
-- Adds an alt_text field to every upload collection.
local M = {}

function M.install()
    for slug, def in pairs(crap.collections.config.list()) do
        if def.upload then
            def.fields[#def.fields + 1] = crap.fields.text({
                name = "alt_text",
                admin = { description = "Describe this image for accessibility" },
            })
            crap.collections.define(slug, def)
        end
    end
end

return M

Patching a Single Collection

-- plugins/post_reading_time.lua
local M = {}

function M.install()
    local def = crap.collections.config.get("posts")
    if not def then return end

    def.fields[#def.fields + 1] = crap.fields.number({
        name = "reading_time",
        admin = { readonly = true, description = "Estimated reading time (minutes)" },
    })

    -- Add a hook to calculate it
    def.hooks.before_change = def.hooks.before_change or {}
    def.hooks.before_change[#def.hooks.before_change + 1] = "plugins.post_reading_time.calculate"

    crap.collections.define("posts", def)
end

function M.calculate(ctx)
    local body = ctx.data.body or ""
    local words = select(2, body:gsub("%S+", ""))
    ctx.data.reading_time = math.ceil(words / 200)
    return ctx
end

return M

Modifying Globals

The same pattern works for globals:

-- plugins/global_meta.lua
-- Adds a "last_updated_by" field to every global.
local M = {}

function M.install()
    for slug, def in pairs(crap.globals.config.list()) do
        def.fields[#def.fields + 1] = crap.fields.text({
            name = "last_updated_by",
            admin = { readonly = true },
        })
        crap.globals.define(slug, def)
    end
end

return M

Patching a Single Global

local def = crap.globals.config.get("site_settings")
if def then
    def.fields[#def.fields + 1] = crap.fields.richtext({ name = "footer_html" })
    crap.globals.define("site_settings", def)
end

Installing a Plugin

-- init.lua
require("plugins.alt_text").install()
require("plugins.post_reading_time").install()

A plugin is a file in your config directory (typically plugins/). Install it by copying or cloning into that directory and adding a require line.

Collection-Level Override

When a plugin adds fields to all collections but you want a custom version for one collection, just define the field directly in that collection’s Lua file. The plugin should check for existing fields before adding:

-- Plugin checks before adding
for _, field in ipairs(def.fields) do
    if field.name == "seo" then
        has_seo = true
        break
    end
end

if not has_seo then
    def.fields[#def.fields + 1] = seo_fields
    crap.collections.define(slug, def)
end

This way, posts.lua can define its own custom SEO group (e.g., with an extra og_image field) and the plugin will skip it.

API Reference

Plugin Execution Order

Since init.lua runs sequentially, plugins install in the order you require them. If plugin B depends on fields added by plugin A, require A first:

require("plugins.seo").install()         -- adds seo fields
require("plugins.seo_defaults").install() -- sets default values on seo fields

Authentication

Crap CMS provides built-in authentication via auth-enabled collections. Any collection can serve as an auth collection by setting auth = true.

Key Concepts

• Auth collection — a collection with auth = true. Users are regular documents in this collection.
• Two auth surfaces — Admin UI uses an HttpOnly cookie (crap_session). gRPC API uses Bearer tokens.
• JWT — all tokens are JWT signed with the configured secret (or an auto-generated one persisted to data/.jwt_secret).
• Argon2id — passwords are hashed with Argon2id before storage.
• Rate limiting — login endpoints enforce per-email rate limiting (configurable max attempts and lockout window).
• Timing-safe — login always performs a password hash comparison, even when the user doesn’t exist, to prevent timing-based email enumeration.
• CSRF protection — admin UI forms and HTMX requests are protected with double-submit cookie tokens.
• Secure cookies — the crap_session cookie includes the Secure flag in production (when dev_mode = false).
• _password_hash — a hidden column added to auth collection tables. Never exposed in API responses, hooks, or admin forms.
• _locked — when set to a truthy value, the user is denied access on every request (JWT validation, Me, admin session). Takes effect immediately, even for valid unexpired tokens. See Auth Collections.
• Custom strategies — pluggable auth via Lua functions (API keys, LDAP, SSO).
• Password reset — token-based forgot/reset password flow via admin UI and gRPC. Requires email configuration.
• Email verification — optional per-collection. When enabled, users must verify their email before logging in.

Activation

Auth middleware activates when at least one auth collection exists or when admin.require_auth is true (the default). This means:

• require_auth = true (default): If no auth collections are defined, the admin shows a “Setup Required” page. Create an auth collection and bootstrap a user to proceed.
• require_auth = false: If no auth collections are defined, the admin is fully open (dev/prototyping mode).
• Auth collection exists: Standard authentication applies. Optionally, admin.access can further restrict which authenticated users can access the admin panel.

Quick Setup

1. Define an auth collection:

-- collections/users.lua
crap.collections.define("users", {
    auth = true,
    fields = {
        crap.fields.text({ name = "name", required = true }),
        crap.fields.select({ name = "role", options = {
            { label = "Admin", value = "admin" },
            { label = "Editor", value = "editor" },
        }}),
    },
})

2. Bootstrap the first user:

crap-cms -C ./my-project user create -e admin@example.com

3. (Optional) Set a JWT secret explicitly, or let it auto-generate and persist to data/.jwt_secret: