AphexCMS

A Sanity-inspired, database-agnostic CMS built with SvelteKit V2 (Svelte 5)

✨ Features

• 🎨 Sanity-inspired UI - Responsive 3-panel admin interface
• 🔌 Database Agnostic - PostgreSQL included, MongoDB/SQLite via adapters
• ☁️ Storage Flexible - Local filesystem or S3-compatible (R2, AWS S3, MinIO)
• 🔐 Auth Agnostic - Bring your own auth (Better Auth included by default)
• 📝 Type-Safe Schemas - Define content models with full TypeScript support
• ✅ Real-time Validation - Field-level validation with Sanity-style fluent API
• 🔄 Auto-Save - Never lose work with smart draft management
• 📦 Hash-Based Publishing - Sanity-style change detection with future versioning support
• 🏢 Multi-Tenancy - Built-in organization support with Row-Level Security
• 🔑 API Keys - Programmatic access with rate limiting
• 🚀 GraphQL Plugin - Auto-generated GraphQL API from your schemas
• 📚 Reference Resolution - Nested depth control with circular protection

📦 Packages

💡 Architecture deep-dive: See ARCHITECTURE.md for detailed design patterns and internals.

💡 Adding UI components: Run pnpm shadcn <component-name> to add shadcn-svelte components to @aphexcms/ui

🚀 Quick Start

Using create-aphex (Recommended)

The fastest way to get started:

pnpm create aphex my-app
# or
npm create aphex my-app
# or
npx create-aphex my-app

This will:

• Prompt you for a project name
• Scaffold a full Aphex CMS project
• Generate a .env file with all required environment variables
• Provide next steps for starting your project

Then:

cd your-project-name
pnpm install
pnpm db:start      # Start PostgreSQL via Docker
pnpm db:push       # Push database schema
pnpm dev           # Start development server

🎉 Admin UI: http://localhost:5173/admin

Manual Installation (Development)

If you want to contribute to Aphex or work with the monorepo:

# Clone and install
git clone https://github.com/IcelandicIcecream/aphex.git
cd aphex
pnpm install

# Configure environment
cd apps/studio
cp .env.example .env
# Default values work for local development
cd ../..

# Start database and migrate
pnpm db:start
pnpm db:migrate

# Start dev server
pnpm dev

🎉 Admin UI: http://localhost:5173/admin

Storage Configuration (Optional)

By default, uses local filesystem. For cloud storage:

pnpm add @aphexcms/storage-s3

// apps/studio/src/lib/server/storage/index.ts
import { s3Storage } from '@aphexcms/storage-s3';

export const storageAdapter = s3Storage({
    bucket: env.R2_BUCKET,
    endpoint: env.R2_ENDPOINT,
    accessKeyId: env.R2_ACCESS_KEY_ID,
    secretAccessKey: env.R2_SECRET_ACCESS_KEY,
    publicUrl: env.R2_PUBLIC_URL
}).adapter;

// aphex.config.ts
import { storageAdapter } from './src/lib/server/storage';

export default createCMSConfig({
    storage: storageAdapter // Pass your adapter
});

📖 Defining Content Schemas

Content models live in your app as TypeScript objects:

// apps/studio/src/lib/schemaTypes/page.ts
export const page: SchemaType = {
    name: 'page',
    type: 'document',
    title: 'Page',
    fields: [
        {
            name: 'title',
            type: 'string',
            title: 'Title',
            validation: (Rule) => Rule.required().max(100)
        },
        {
            name: 'slug',
            type: 'slug',
            title: 'URL Slug',
            source: 'title', // Auto-generate from title
            validation: (Rule) => Rule.required()
        },
        {
            name: 'content',
            type: 'array',
            title: 'Content Blocks',
            of: [{ type: 'textBlock' }, { type: 'imageBlock' }, { type: 'catalogBlock' }]
        },
        {
            name: 'author',
            type: 'reference',
            title: 'Author',
            to: [{ type: 'author' }] // Reference to other documents
        }
    ]
};

Register schemas in your config:

// aphex.config.ts
import { page, author, textBlock } from './src/lib/schemaTypes';

export default createCMSConfig({
    schemaTypes: [page, author, textBlock]
    // ...
});

Available field types: string, text, number, boolean, slug, url, date, datetime, image, file, array, object, reference

🛠️ Tech Stack

• SvelteKit V2 - Framework with Svelte 5 runes
• Drizzle ORM - Type-safe database queries
• Better Auth - Authentication & sessions
• Turborepo - Monorepo build system
• Tailwind CSS v4 - Styling
• shadcn-svelte - UI components

🎨 Admin Interface

The admin UI is a responsive 3-panel layout inspired by Sanity Studio:

• Desktop: Side-by-side panels (types → documents → editor)
• Mobile: Stack navigation with breadcrumbs
• Real-time validation with inline error messages
• Auto-save every 2 seconds (never lose work!)
• Nested reference editing via modal overlays
• Drag-and-drop array field reordering

🔍 API Features

Reference Resolution with Depth Control

# Just IDs (default)
GET /api/documents/123

# Resolve first-level references
GET /api/documents/123?depth=1

# Resolve nested references
GET /api/documents/123?depth=2

Circular reference protection prevents infinite loops. Max depth: 5.

GraphQL API

GraphQL is built into cms-core and enabled by default. To customize:

export default createCMSConfig({
    graphql: {
        path: '/api/graphql',
        enableGraphiQL: true
    }
});

Visit /api/graphql for GraphiQL interface with auto-generated schema.

🛠️ Development Commands

# Development
pnpm dev              # Start all packages in watch mode
pnpm dev:studio       # Start studio app only
pnpm dev:package      # Start cms-core package only
pnpm dev:docs         # Start dev server

# Building
pnpm build            # Build all packages (Turborepo)
pnpm preview          # Preview production build

# Database
pnpm db:start         # Start PostgreSQL (Docker)
pnpm db:push          # Push schema changes (dev)
pnpm db:generate      # Generate migrations
pnpm db:migrate       # Run migrations (prod)
pnpm db:studio        # Open Drizzle Studio

# Code Quality
pnpm lint             # Prettier + ESLint check
pnpm format           # Format code with Prettier
pnpm check            # Type-check all packages

# UI Components (shadcn-svelte → @aphexcms/ui)
pnpm shadcn button    # Add button component
pnpm shadcn dialog    # Add dialog component
# Components shared between cms-core & studio

🔐 Authentication

Batteries included with Better Auth:

• ✅ Session-based auth (email/password)
• ✅ API keys with rate limiting (10k requests/day)
• ✅ Multi-tenancy with organizations
• ✅ Row-Level Security (RLS)

API Key Usage

curl http://localhost:5173/api/documents?docType=page \
  -H "x-api-key: your-api-key-here"

Generate keys from /admin/settings.

Bring your own auth: Implement the AuthProvider interface to use Auth.js, Lucia, or custom solutions.

🤝 Contributing

Code Standards

• ✅ Format before committing: pnpm format
• ✅ Type-check: pnpm check
• ✅ Use Svelte 5 runes ($state, $derived, $effect)
• ✅ Follow Conventional Commits

Adding Features

• Database Adapters: Implement DatabaseAdapter interface in a new package + AuthProvider
• Storage Adapters: Implement StorageAdapter interface
• Field Types: Add Svelte component + TypeScript type
• Plugins: Implement CMSPlugin interface

See ARCHITECTURE.md for detailed extension guides.

Reporting Issues

Include:

• OS, Node version, pnpm version
• Steps to reproduce
• Expected vs actual behavior
• Error logs (browser console + terminal)

📚 Documentation

• ARCHITECTURE.md - Deep dive into design patterns and internals
• CONTRIBUTING.md - Development guidelines and PR process

🎯 Roadmap

Shipped

• CLI scaffolding — pnpm create aphex / npm create aphex@latest (published as create-aphex)
• CI/CD pipeline — release.yml + sync-template.yml + Changesets
• Unified Local/HTTP/GraphQL API — one schema, three surfaces, Zod-validated contracts
• Auto-generated GraphQL — queries, mutations, filters, GraphiQL
• Draft/published workflow — hash-based change detection + auto-save
• Version history — rolling per-document versions with configurable maxVersions (GET /api/documents/{id}/versions)
• Multi-tenancy — organizations with parent/child hierarchy + Postgres RLS
• Email + invitations — Better Auth + Resend/Nodemailer adapters, Mailpit in dev
• Capability-based access control — editable built-in roles, custom per-org roles, schema-level and field-level access rules, policy functions
• API keys — rate-limited, per-organization, with either coarse read/write scopes or a fine-grained capabilities allowlist
• In-memory caching — InMemoryCacheAdapter for published reads + API-key lookups
• Preview config — preview: { select: { title, subtitle } } (with dot-paths) on document + object types; rendered in document list, array item rows, and reference picker
• Singletons — schemas marked singleton: true expose a SingletonCollection<T> surface with get/update/getSingletonId and hide Create/Delete in admin
• Base template — full auth/storage/email/cache setup, synced from apps/studio
• Standalone build — pnpm build works without any .env (server modules guarded with building flag); Dockerfile + Procfile ship in the template for Docker / buildpack deploys
• One-line Vite config — aphex() plugin bundles HMR + dayjs alias + SSR/optimizeDeps tuning so consumers don't copy boilerplate
• Fast schema HMR — schema edits hot-swap the engine config without restarting the Vite dev server (~10× faster than restart-on-change)
• Documentation site — docs.getaphex.com with LLM-friendly llms.txt, per-page markdown, and "Copy / Open in ChatGPT / Open in Claude" actions

Near-term (Priority)

• Polish admin UI — fix half-baked implementations (see issues)
• Template library — more starters beyond base (newsletter, marketing site, docs, portfolio)
• Rich text / block editor — TipTap-backed portable-text–style field
• Plugin ecosystem — documented plugin API + first-party plugins (search, image transforms)
• Image transforms — on-the-fly resize / format / crop (see TODO-image-transforms.md)
• Contributor docs expansion — adapter authoring guides, field type authoring guide

Mid-term

• Content preview system — signed draft URLs for previewing unpublished content in frontends
• Migration tools — import/export utilities for content portability between instances
• Webhook system — event-driven integrations on publish / unpublish / delete
• Scheduled publishing — publish-at / unpublish-at timestamps
• Media library enhancements — folders, tags, bulk actions
• Redis-backed cache adapter — drop-in replacement for InMemoryCacheAdapter
• Advanced field types — code editor, color picker, geopoint

Long-term

• Localization (i18n) support — multi-language content with field-level or document-level translation
• Real-time collaboration — multiplayer editing with presence awareness
• Approval workflows — review → approve → publish with role gating
• Monitoring & observability — built-in analytics, slow-query tracking, audit log UI
• MySQL / SQLite adapters — additional first-party DatabaseAdapter implementations

🙏 Acknowledgments

Inspired by Sanity.io • Built with SvelteKit, Drizzle ORM, Better Auth, and shadcn-svelte