Modern, composable CMS for developers
Trokky is a TypeScript-native content management system designed as a developer-friendly alternative to Sanity. It provides full type safety from schemas to frontend and a composable architecture with a React-based admin UI. Storage is a choice, not a premise: your content lives in JSON files, in Postgres, or in Cloudflare D1 — on infrastructure you own either way.
Trokky is a monorepo with 3 packages:
| Package | Published as | Description |
|---|---|---|
packages/trokky/ |
@trokky/trokky |
CMS server: engine, routes, adapters, mail, i18n, Express integration |
packages/studio/ |
@trokky/studio |
React admin UI and field system (25+ field types) |
packages/client/ |
@trokky/client |
Frontend SDK: HTTP client, query builder, type generation |
packages/mcp/ |
@trokky/mcp |
MCP server: lets AI agents work on a site's content through an API token |
The CLI is a separate Go project at github.com/Trokky/cli.
import express from 'express'
import { TrokkyExpress } from '@trokky/trokky/express'
import '@trokky/trokky/adapters/filesystem-data'
import '@trokky/trokky/adapters/filesystem-media'
const app = express()
const trokky = await TrokkyExpress.create({
schemas: [
{
name: 'article',
title: 'Article',
type: 'document',
fields: {
title: { type: 'string', required: true },
content: { type: 'richtext' },
publishedAt: { type: 'date' }
}
}
],
storage: {
data: { adapter: 'filesystem-data', options: { contentDir: './content' } },
media: { adapter: 'filesystem-media', options: { mediaDir: './media' } }
},
security: {
adminUser: {
username: process.env.TROKKY_ADMIN_EMAIL,
password: process.env.TROKKY_ADMIN_PASSWORD
}
},
studio: {
url: process.env.STUDIO_URL, // public Studio URL: device-flow approval page + email links
branding: { title: 'My CMS' }
}
})
trokky.mount(app)
// Studio is a router you mount yourself, before any catch-all
import { studioRouter } from '@trokky/studio/express'
app.use('/studio', studioRouter({ apiPath: '/api' }))
app.listen(3000)The server package uses subpath exports for clean, targeted imports:
// Server setup
import { TrokkyExpress } from '@trokky/trokky/express'
import '@trokky/trokky/adapters/filesystem-data'
import '@trokky/trokky/adapters/filesystem-media'
// Types
import type { BaseDocument, User } from '@trokky/trokky/types'
import type { MediaAsset } from '@trokky/trokky/types/media'
// Mail
import { MailService } from '@trokky/trokky'
import { SMTPMailAdapter } from '@trokky/trokky/mail/smtp'
// Structure
import { StructureBuilder } from '@trokky/trokky/structure'
// Client SDK (separate package)
import { TrokkyClient } from '@trokky/client'Storage is split into data (structured) and media (files), each using the adapter pattern:
| Adapter | Import | Description |
|---|---|---|
| Filesystem Data | @trokky/trokky/adapters/filesystem-data |
File-based JSON storage, Git-friendly |
| Filesystem Media | @trokky/trokky/adapters/filesystem-media |
Local file storage for media |
| PostgreSQL Data | @trokky/trokky/adapters/postgres-data |
PostgreSQL for structured data |
| Cloudflare D1 | @trokky/trokky/adapters/cloudflare-d1 |
D1 for structured data, on Workers |
| Cloudflare R2 | @trokky/trokky/adapters/cloudflare-r2 |
R2 object storage for media, on Workers |
Adapters self-register on import via registerAdapter().
The filesystem adapters are the Git-friendly ones: content is JSON on disk, so it can be
committed alongside the code. The database adapters are not — with Postgres or D1 the code and
schemas live in Git and the content lives in the database, which is what running on a server or
at the edge means. Use the CLI's backup/restore to take a content snapshot in either case.
- Schema-driven content modeling with TypeScript definitions and Zod validation
- 25+ field types including rich text, media, references, arrays, and objects
- Split storage architecture enabling optimal backends per concern (e.g. PostgreSQL for data, S3 for media)
- JWT authentication with role-based access control (admin, editor, author, viewer)
- Multi-factor authentication with TOTP and email OTP
- OAuth2 authorization server with device code flow
- Passkey/WebAuthn support for passwordless authentication
- Event system with webhooks, retry policies, and persistent storage
- Media management with automatic image variant generation
- Internationalization via i18next
- Audit logging for compliance and security monitoring
- Mail service with console, SMTP, and Resend adapters
Projects use trokky.config.ts for centralized configuration:
// trokky.config.ts
export default {
schemas: './schemas',
storage: {
data: { adapter: 'filesystem-data', options: { contentDir: './content' } },
media: { adapter: 'filesystem-media', options: { mediaDir: './media' } }
},
studio: {
url: process.env.STUDIO_URL, // public Studio URL: device-flow approval page + email links
branding: { title: 'My CMS' }
},
security: {
adminUser: {
username: process.env.TROKKY_ADMIN_EMAIL,
password: process.env.TROKKY_ADMIN_PASSWORD
}
}
}Password hashing is tuned via security.cryptoOptions (adapterType, saltRounds, pbkdf2Iterations); see API.md for the versioned hash format and rehash-on-login behavior.
- Node.js >= 18.0.0
- npm >= 8.0.0
npm run dev # Start full demo (API + Studio)
npm run build # Build all packages
npm run test # Run all tests
npm run test:coverage # Tests with coverage report
npm run lint # Lint all packages
npm run type-check # TypeScript type checking
npm run clean # Clean build outputs
npm run format # Format with PrettierThere is no example app in this repository. To start a project, scaffold one with the CLI:
trokky create my-site --template blog --data filesystem
cd my-site && npm install && npm run devtrokky.dev walks through that build end to end, from an empty folder to a typed page rendering content you edited in the Studio.
Trokky uses Vitest for all packages, React Testing Library for Studio components, and Supertest for Express integration tests. Coverage target is 80%+ across the board.
cd packages/trokky && npm test # Server tests
cd packages/studio && npm test # Studio tests
cd packages/client && npm test # Client tests
cd packages/mcp && npm test # MCP server testsAll API endpoints are mounted at /api by default. Studio is served wherever the site mounts studioRouter() from @trokky/studio/express, by convention /studio. The server exposes 90+ endpoints covering content CRUD, media management, authentication (JWT, OAuth, passkeys, MFA), webhooks, audit logs, and more.
See API.md for the complete API reference.
MIT — see LICENSE.