includio-cms

A headless CMS built for SvelteKit. Type-safe, extensible, with a modern admin interface and pluggable adapters for database, files, email, and AI.

Contents

• Features
• System requirements
• Quick start (5 minutes)
• Configuration
• Adapters
  • Writing your own adapter
  • Optional peer dependencies
• CLI
• Links
• For AI assistants
• License

Features

• 20 field types — text, structured content, media, relations, blocks, SEO, URL, custom plugins, and more
• Structured content — ProseMirror-based rich text with inline blocks, tables, media embeds
• Media management — image styles (Sharp), video transcoding (ffmpeg), focal points, blur placeholders
• Per-language versioning — independent draft / published / scheduled per language
• Layout DSL — organize admin editor with sections, columns, cards, accordions
• Frontend components — <Image>, <Video>, <StructuredContent>, <Media> for SvelteKit
• REST API — API key auth, CRUD endpoints, schema introspection
• Entity API — server-side programmatic CRUD for scripts, migrations, webhooks
• Code generation — TypeScript types and Zod schemas from your content schema
• Pluggable adapters — swap database, file storage, email, AI provider
• Plugin system — lifecycle hooks and custom field types
• Strict config validation — invalid configs throw a ConfigValidationError listing every issue with a path and a fix hint

System requirements

• Node.js 18+ (20 LTS recommended)
• PostgreSQL 14+ — required by the bundled db-postgres adapter; or write your own DatabaseAdapter
• ffmpeg + ffprobe — optional, only required for video transcoding (set FFMPEG_PATH / FFPROBE_PATH if not on PATH)
• A SvelteKit project (Kit ≥ 2.48, Svelte ≥ 5.43, Vite ≥ 7)

Quick start (5 minutes)

The five steps below take you from pnpm add to a running admin at /admin.

1. Install:

pnpm add includio-cms
pnpm dlx includio install-peers

2. Configure environment:

cp node_modules/includio-cms/.env.example .env
# edit .env — set DATABASE_URL and BETTER_AUTH_SECRET

Generate a secret:

openssl rand -hex 32

3. Create src/lib/cms/cms.config.ts:

import { defineConfig } from 'includio-cms/sveltekit';
import { pg } from 'includio-cms/db-postgres';
import { local } from 'includio-cms/files-local';

export default defineConfig({
  languages: ['en'],
  db: pg({ databaseUrl: process.env.DATABASE_URL! }),
  files: local(),
  auth: { secret: process.env.BETTER_AUTH_SECRET! },
  collections: []
});

4. Scaffold admin routes + create a user:

pnpm dlx includio scaffold admin
pnpm dlx includio create-user

5. Run the dev server:

pnpm dev

Open http://localhost:5173/admin and sign in with the user you just created.

Need more? Full reference in DOCS.md. API surface in API.md.

Configuration

defineConfig({ ... }) is your single source of truth. The shape (abridged):

defineConfig({
  languages: ['en', 'pl'],   // first entry is the default locale
  db, files,                 // required adapters
  email, ai,                 // optional adapters
  auth: { secret },          // required for /admin
  collections: [postsCollection],
  singles:     [siteSettings],
  forms:       [contactForm],
  apiKeys:     [{ key: '...', role: 'admin' }],
  media:       { /* sharp / video / maintenance options */ },
  typography:  { fixOrphans: true },
  shop, cmp                  // optional modules
});

Invalid configs throw immediately at startup with every issue listed:

ConfigValidationError: CMSConfig validation failed (2 issues):
  - languages[0]: must be a 2-letter ISO code (e.g. 'en' or 'pl-PL')
  - collections[1].slug: duplicate collection slug 'posts'
    — Hint: each collection/single/form must have a unique `slug`

See DOCS.md for every field type and option.

Adapters

includio-cms ships four pluggable contracts. Each has a default implementation; bring your own when you need to.

| Contract | Default | Lazy peer dep | |--------------------|------------------------|------------------------------| | DatabaseAdapter | includio-cms/db-postgres | postgres, drizzle-orm | | FilesAdapter | includio-cms/files-local | — | | EmailAdapter | includio-cms/email-nodemailer | nodemailer | | AIAdapter | includio-cms/ai-openai, includio-cms/ai-claude | openai, @anthropic-ai/sdk |

Source of truth: src/lib/types/adapters/.

Writing your own adapter

Each contract is a TypeScript interface — implement every required method (optionals are marked ?). TypeScript will enforce the surface.

import type { DatabaseAdapter } from 'includio-cms/types';

export function myDbAdapter(config: { connection: string }): DatabaseAdapter {
  // ...connect, prepare your client...
  return {
    createEntry: async (data) => { /* ... */ },
    getEntries: async (opts) => { /* ... */ },
    countEntries: async (opts) => { /* ... */ },
    updateEntry: async (data) => { /* ... */ },
    archiveEntry: async (data) => { /* ... */ },
    deleteEntry: async (data) => { /* ... */ },
    createEntryVersion: async (data) => { /* ... */ },
    updateEntryVersion: async (data) => { /* ... */ },
    getEntryVersions: async (data) => { /* ... */ },
    deleteEntryVersion: async (data) => { /* ... */ }
    // ...form submissions, media files, image/video styles, tags, consent logs...
  };
}

Wire it in cms.config.ts:

import { defineConfig } from 'includio-cms/sveltekit';
import { myDbAdapter } from './my-adapter.js';

export default defineConfig({
  db: myDbAdapter({ connection: process.env.MY_DB_URL! }),
  // ...
});

Reference implementation: src/lib/db-postgres/index.ts (drizzle + postgres).

Optional peer dependencies

The default email + AI adapters depend on third-party SDKs that are not installed by default. Install the peer once you use the adapter:

| Adapter | Required peer | Install | |--------------------|---------------------|-------------------------------| | email-nodemailer | nodemailer | pnpm add nodemailer | | ai-openai | openai | pnpm add openai | | ai-claude | @anthropic-ai/sdk | pnpm add @anthropic-ai/sdk |

Each SDK is loaded lazily on first call. A missing peer throws a clear error at runtime — install it and the adapter wakes up. pnpm dlx includio install-peers automates this for the parts of the CMS you have configured.

CLI

The includio binary ships with three subcommands. Run any of them with --help for details.

| Command | What it does | |--------------------------|-----------------------------------------------------------| | includio scaffold admin| Generates /admin and /api/admin route files | | includio install-peers | Installs missing optional peer SDKs based on your config | | includio create-user | Creates an admin/user account interactively |

Global flags: --help, -h and --version, -v.

Links

• Full documentation
• Public API surface
• Changelog
• Roadmap
• Known risks
• Storybook — visual reference for all 86 UI components (designer source-of-truth)

For AI assistants

Full documentation is in DOCS.md (shipped with the npm package). When working on a project using includio-cms, read node_modules/includio-cms/DOCS.md for the complete API reference, available components, and migration guides.

License

MIT