litecms 0.1.0

package/README.md

@@ -0,0 +1,1387 @@
+# litecms
+
+A super lightweight and type-safe CMS for Next.js websites. Auto-generated admin forms from Zod schemas with S3-compatible storage support.
+
+## Installation
+
+```bash
+bun add litecms
+# or
+npm install litecms
+```
+
+### Peer Dependencies
+
+```bash
+bun add react react-dom next zod
+# Optional: for image storage
+bun add @aws-sdk/client-s3
+```
+
+## Quick Start
+
+### 1. Define a Schema
+
+```typescript
+// cms/schemas/home.ts
+import { z } from 'zod';
+import { defineSchema } from 'litecms/schema';
+
+export const HomePageDef = defineSchema({
+    schema: z.object({
+        heroTitle: z.string().min(1),
+        heroSubtitle: z.string().optional(),
+        heroImage: z.string().optional(),
+        ctaText: z.string().min(1),
+        ctaUrl: z.string().url(),
+        showInNav: z.boolean().default(false),
+    }),
+    fields: {
+        heroTitle: { 
+            label: 'Hero Title', 
+            placeholder: 'Welcome to...',
+            order: 1,
+        },
+        heroSubtitle: { 
+            label: 'Subtitle', 
+            type: 'textarea', 
+            rows: 3,
+            order: 2,
+        },
+        heroImage: {
+            label: 'Hero Image',
+            type: 'image',
+            helpText: 'Upload or select a background image',
+            order: 3,
+        },
+        ctaText: { label: 'CTA Button Text', order: 4 },
+        ctaUrl: { label: 'CTA URL', type: 'url', order: 5 },
+        showInNav: {
+            label: 'Show in Navigation',
+            type: 'checkbox',
+            helpText: 'Display this page in the main nav',
+            group: 'Settings',
+            order: 10,
+        },
+    },
+    defaults: {
+        heroTitle: '',
+        heroSubtitle: '',
+        heroImage: '',
+        ctaText: 'Get Started',
+        ctaUrl: '/',
+        showInNav: false,
+    },
+});
+
+// Export the schema and types for use elsewhere
+export const HomePageSchema = HomePageDef.schema;
+export type HomePageData = z.infer<typeof HomePageDef.schema>;
+```
+
+### 2. Create a Server Action
+
+```typescript
+// cms/actions/home.ts
+'use server';
+
+import { revalidatePath } from 'next/cache';
+import { createSaveAction } from 'litecms/server';
+import { HomePageSchema, type HomePageData, HomePageDef } from '../schemas/home';
+import { db } from '@/lib/db'; // Your database
+
+export const saveHome = createSaveAction(HomePageSchema, {
+    save: async (data) => {
+        await db.upsert('pages', { key: 'home', data });
+    },
+    revalidatePath: '/',
+    onRevalidate: revalidatePath,
+    // Optional: add auth check
+    checkAuth: async () => {
+        const session = await getSession();
+        return !!session?.user;
+    },
+});
+
+export async function getHomePageData(): Promise<HomePageData> {
+    const data = await db.get('pages', 'home');
+    if (!data) return HomePageDef.defaults;
+    const result = HomePageSchema.safeParse(data);
+    return result.success ? result.data : HomePageDef.defaults;
+}
+```
+
+### 3. Create CMS Config
+
+```typescript
+// cms/config.ts
+import { createCmsConfig, definePage } from 'litecms/admin/config';
+import { HomePageDef } from './schemas/home';
+import { saveHome, getHomePageData } from './actions/home';
+
+export const cmsConfig = createCmsConfig({
+    siteName: 'My Site',
+    adminTitle: 'Content',
+    basePath: '/admin',
+    publicSiteUrl: '/',
+    // Required for image uploads
+    storage: {
+        uploadEndpoint: '/api/storage/upload',
+        listEndpoint: '/api/storage/list',
+    },
+    pages: [
+        definePage({
+            slug: 'home',
+            title: 'Homepage',
+            description: 'Edit the main landing page content',
+            path: '/', // Public URL path (used for navigation building)
+            definition: HomePageDef,
+            action: saveHome,
+            getData: getHomePageData,
+            order: 1,
+        }),
+        definePage({
+            slug: 'settings',
+            title: 'General',
+            definition: SiteSettingsDef,
+            action: saveSiteSettings,
+            getData: getSiteSettings,
+            order: 99,
+            group: 'Settings', // Groups pages in the sidebar
+        }),
+    ],
+});
+```
+
+### 4. Create Admin Layout
+
+The admin layout can be a client or server component. Here's a client component example with authentication:
+
+```typescript
+// app/admin/layout.tsx
+'use client';
+
+import { useRouter } from 'next/navigation';
+import { useEffect } from 'react';
+import { CmsAdminLayout } from 'litecms/admin';
+import { extractLayoutProps } from 'litecms/admin/config';
+import { cmsConfig } from '@/cms/config';
+import { useSession, signOut } from '@/lib/auth-client';
+
+export default function AdminLayout({ 
+    children 
+}: { 
+    children: React.ReactNode 
+}) {
+    const router = useRouter();
+    const { data: session, isPending } = useSession();
+
+    useEffect(() => {
+        if (!isPending && !session) {
+            router.push('/login');
+        }
+    }, [isPending, session, router]);
+
+    const handleLogout = async () => {
+        await signOut();
+        router.push('/login');
+    };
+
+    if (isPending || !session) {
+        return null;
+    }
+
+    return (
+        <CmsAdminLayout 
+            {...extractLayoutProps(cmsConfig)}
+            onLogout={handleLogout}
+        >
+            {children}
+        </CmsAdminLayout>
+    );
+}
+```
+
+### 5. Create Admin Page
+
+```typescript
+// app/admin/[slug]/page.tsx
+import { CmsAdminPage } from 'litecms/admin';
+import { extractPageProps } from 'litecms/admin/config';
+import { cmsConfig } from '@/cms/config';
+import { notFound } from 'next/navigation';
+
+type PageProps = {
+    params: Promise<{ slug: string }>;
+};
+
+export default async function AdminPage({ params }: PageProps) {
+    const { slug } = await params;
+    const props = await extractPageProps(cmsConfig, slug);
+    
+    if (!props) return notFound();
+    
+    return <CmsAdminPage {...props} />;
+}
+
+export function generateStaticParams() {
+    return cmsConfig.pages.map((page) => ({
+        slug: page.slug,
+    }));
+}
+```
+
+### 6. Set Up Storage API Routes (Optional)
+
+For image uploads, create API routes:
+
+```typescript
+// app/api/storage/upload/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { storage } from '@/lib/storage';
+import { auth } from '@/lib/auth';
+import { headers } from 'next/headers';
+
+export async function POST(request: NextRequest) {
+    // Check authentication
+    const session = await auth.api.getSession({
+        headers: await headers(),
+    });
+
+    if (!session) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+
+    const formData = await request.formData();
+    const file = formData.get('file') as File | null;
+
+    if (!file) {
+        return NextResponse.json({ error: 'No file provided' }, { status: 400 });
+    }
+
+    // Validate file type
+    if (!file.type.startsWith('image/')) {
+        return NextResponse.json({ error: 'Only image files allowed' }, { status: 400 });
+    }
+
+    const result = await storage.uploadFile(file);
+
+    return NextResponse.json({
+        success: true,
+        url: result.url,
+        key: result.key,
+    });
+}
+```
+
+```typescript
+// app/api/storage/list/route.ts
+import { NextResponse } from 'next/server';
+import { storage } from '@/lib/storage';
+import { auth } from '@/lib/auth';
+import { headers } from 'next/headers';
+
+export async function GET() {
+    const session = await auth.api.getSession({
+        headers: await headers(),
+    });
+
+    if (!session) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+
+    const files = await storage.listFiles();
+
+    return NextResponse.json({
+        success: true,
+        files,
+    });
+}
+```
+
+```typescript
+// lib/storage.ts
+import { createStorageClient } from 'litecms/storage';
+
+export const storage = createStorageClient({
+    endpoint: process.env.STORAGE_URL!,
+    region: process.env.STORAGE_REGION || 'us-east-1',
+    accessKeyId: process.env.STORAGE_ACCESS_KEY!,
+    secretAccessKey: process.env.STORAGE_SECRET_KEY!,
+    bucket: process.env.STORAGE_BUCKET || 'mybucket',
+    forcePathStyle: true, // Required for Minio and S3-compatible services
+    publicUrlBase: '/api/storage/images',
+});
+
+// Export individual functions for convenience
+export const { uploadFile, listFiles, deleteFile, getFile } = storage;
+```
+
+---
+
+## API Reference
+
+### Schema (`litecms/schema`)
+
+#### `defineSchema(definition)`
+
+Define a schema with field metadata for form generation.
+
+```typescript
+import { z } from 'zod';
+import { defineSchema } from 'litecms/schema';
+
+const MySchema = defineSchema({
+    schema: z.object({ ... }),
+    fields: { ... },
+    defaults: { ... },
+});
+```
+
+**Types:**
+
+```typescript
+type SchemaDefinition<T extends z.ZodRawShape> = {
+    /** The Zod schema */
+    schema: z.ZodObject<T>;
+    /** Field metadata keyed by field name */
+    fields: { [K in keyof T]?: FieldMeta };
+    /** Default values */
+    defaults: z.infer<z.ZodObject<T>>;
+};
+
+type FieldMeta = {
+    /** Display label for the field */
+    label: string;
+    /** Whether the field is editable in the admin panel (default: true) */
+    editable?: boolean;
+    /** Input type override */
+    type?: 'text' | 'textarea' | 'number' | 'email' | 'url' | 'select' | 'checkbox' | 'image';
+    /** Placeholder text */
+    placeholder?: string;
+    /** Help text shown below the input */
+    helpText?: string;
+    /** Options for select fields */
+    options?: Array<{ value: string; label: string }>;
+    /** Number of rows for textarea (default: 3) */
+    rows?: number;
+    /** Order in the form (lower = higher priority) */
+    order?: number;
+    /** Group name for organizing fields into collapsible sections */
+    group?: string;
+    /** Accepted file types for image fields (default: 'image/*') */
+    accept?: string;
+};
+```
+
+#### `getEditableFields(definition)`
+
+Extract editable field info from a schema definition. Used internally by form components.
+
+```typescript
+import { getEditableFields } from 'litecms/schema';
+
+const fields = getEditableFields(HomePageDef);
+// Returns: FieldInfo[] with name, meta, and required flag
+```
+
+---
+
+### Server (`litecms/server`)
+
+#### `createSaveAction(schema, options)`
+
+Create a type-safe server action for form submission.
+
+```typescript
+import { createSaveAction } from 'litecms/server';
+import { revalidatePath } from 'next/cache';
+
+export const saveHome = createSaveAction(HomePageSchema, {
+    save: async (data) => {
+        await db.upsert('pages', { key: 'home', data });
+    },
+    revalidatePath: '/',
+    onRevalidate: revalidatePath,
+    checkAuth: async () => {
+        const session = await getSession();
+        return !!session;
+    },
+});
+```
+
+**Types:**
+
+```typescript
+type ActionOptions<TData> = {
+    /** Callback to save data */
+    save: (data: TData) => Promise<void>;
+    /** Path to revalidate after successful save */
+    revalidatePath?: string;
+    /** Callback to revalidate (pass revalidatePath from next/cache) */
+    onRevalidate?: (path: string) => void;
+    /** Optional auth check. Return true if authorized. */
+    checkAuth?: () => Promise<boolean>;
+};
+
+type ActionState<T = unknown> = {
+    success: boolean;
+    data?: T;
+    errors?: {
+        fieldErrors?: Record<string, string[]>;
+        formError?: string;
+    };
+};
+```
+
+#### `parseFormDataToObject(formData)`
+
+Parse FormData into a plain object with automatic type coercion. Handles:
+
+- Empty strings → `undefined` (for optional fields)
+- Number coercion for numeric values
+- Boolean coercion for checkbox fields (`'true'`, `'on'`, `'false'`)
+- Nested objects using dot notation (`address.city`)
+- Arrays using bracket notation (`tags[0]`, `navLinks[0].label`)
+
+```typescript
+import { parseFormDataToObject } from 'litecms/server';
+
+const data = parseFormDataToObject(formData);
+```
+
+#### `parseFormData(schema, formData)`
+
+Parse FormData and validate against a Zod schema. Returns parsed data or null.
+
+```typescript
+import { parseFormData } from 'litecms/server';
+
+const data = parseFormData(MySchema, formData);
+if (data) {
+    // data is typed as z.infer<typeof MySchema>
+}
+```
+
+---
+
+### Admin (`litecms/admin` and `litecms/admin/config`)
+
+#### `createCmsConfig(config)`
+
+Create the main CMS configuration.
+
+```typescript
+import { createCmsConfig, definePage } from 'litecms/admin/config';
+
+export const cmsConfig = createCmsConfig({
+    siteName: 'My Site',           // Shown in admin header
+    adminTitle: 'Content',         // Admin panel title
+    basePath: '/admin',            // Base path for admin routes
+    publicSiteUrl: '/',            // Link to public site
+    storage: {                     // Required for image fields
+        uploadEndpoint: '/api/storage/upload',
+        listEndpoint: '/api/storage/list',
+    },
+    pages: [
+        definePage({ ... }),
+    ],
+});
+```
+
+**Types:**
+
+```typescript
+type CmsConfig = {
+    siteName?: string;
+    adminTitle?: string;
+    basePath?: string;
+    publicSiteUrl?: string;
+    pages: CmsPageConfig[];
+    storage?: ImageUploadConfig;
+};
+
+type CmsPageConfig = {
+    /** URL slug for the admin page (e.g., 'home', 'about') */
+    slug: string;
+    /** Display name in navigation */
+    title: string;
+    /** Description shown below the title (helps guide users) */
+    description?: string;
+    /** Public URL path (e.g., '/', '/about'). Used for navigation building. */
+    path?: string;
+    /** Schema definition */
+    definition: SchemaDefinition<any>;
+    /** Server action to save data */
+    action: (prevState: ActionState, formData: FormData) => Promise<ActionState>;
+    /** Function to fetch current data */
+    getData: () => Promise<any>;
+    /** Icon name (optional) */
+    icon?: string;
+    /** Order in navigation (lower = higher) */
+    order?: number;
+    /** Group in navigation sidebar */
+    group?: string;
+};
+
+type ImageUploadConfig = {
+    uploadEndpoint: string;
+    listEndpoint?: string;
+};
+```
+
+#### `definePage(config)`
+
+Type-safe helper to define a page config with proper inference.
+
+```typescript
+definePage({
+    slug: 'home',
+    title: 'Homepage',
+    description: 'Edit homepage content',
+    path: '/',
+    definition: HomePageDef,
+    action: saveHome,
+    getData: getHomePageData,
+    order: 1,
+    group: 'Pages',
+})
+```
+
+#### `extractLayoutProps(config)` and `extractPageProps(config, slug)`
+
+Extract serializable props from CMS config for use in components.
+
+```typescript
+import { extractLayoutProps, extractPageProps } from 'litecms/admin/config';
+
+// In layout
+<CmsAdminLayout {...extractLayoutProps(cmsConfig)} />
+
+// In page
+const props = await extractPageProps(cmsConfig, slug);
+<CmsAdminPage {...props} />
+```
+
+#### `CmsAdminLayout`
+
+Admin layout component with sidebar navigation.
+
+```tsx
+import { CmsAdminLayout } from 'litecms/admin';
+
+<CmsAdminLayout
+    adminTitle="Content"
+    siteName="My Site"
+    basePath="/admin"
+    publicSiteUrl="/"
+    pages={[{ slug: 'home', title: 'Home', group: 'Pages' }]}
+    currentSlug="home"           // Optional: override auto-detection
+    onLogout={() => signOut()}   // Optional: logout handler
+>
+    {children}
+</CmsAdminLayout>
+```
+
+#### `CmsAdminPage`
+
+Admin page component that renders the form.
+
+```tsx
+import { CmsAdminPage } from 'litecms/admin';
+
+<CmsAdminPage
+    title="Homepage"
+    description="Edit the main landing page"
+    fields={fields}              // FieldInfo[] from extractPageProps
+    values={currentData}
+    action={saveAction}
+    storage={storageConfig}      // For image fields
+    styles={customStyles}        // Optional style overrides
+    submitText="Save"
+    successMessage="Changes saved!"
+/>
+```
+
+---
+
+### Components (`litecms/components`)
+
+Components for building custom admin forms.
+
+#### `CmsForm`
+
+Form wrapper that integrates react-hook-form with server actions.
+
+```tsx
+import { CmsForm, CmsSubmitButton, CmsFormError, CmsFormSuccess } from 'litecms/components';
+
+<CmsForm
+    schema={MySchema}
+    action={saveAction}
+    defaultValues={data}
+    onSuccess={(data) => console.log('Saved!', data)}
+>
+    {/* Your field components */}
+    <CmsFormError />
+    <CmsFormSuccess>Saved successfully!</CmsFormSuccess>
+    <CmsSubmitButton pendingText="Saving...">Save</CmsSubmitButton>
+</CmsForm>
+```
+
+#### `useCmsForm()`
+
+Hook to access form state within CmsForm.
+
+```tsx
+import { useCmsForm } from 'litecms/components';
+
+function MyComponent() {
+    const { isPending, formError, showSuccess } = useCmsForm();
+    // ...
+}
+```
+
+#### `CmsField`
+
+Renders text, textarea, select, number, email, or url inputs.
+
+```tsx
+import { CmsField } from 'litecms/components';
+
+<CmsField
+    name="title"
+    label="Page Title"
+    type="text"              // 'text' | 'textarea' | 'select' | 'number' | 'email' | 'url'
+    placeholder="Enter title..."
+    helpText="This appears in the browser tab"
+    options={[{ value: 'a', label: 'Option A' }]}  // For select type
+    rows={5}                 // For textarea type
+    required
+    disabled={false}
+    className="custom-wrapper"
+    labelClassName="custom-label"
+    inputClassName="custom-input"
+    errorClassName="custom-error"
+    helpClassName="custom-help"
+/>
+```
+
+#### `CmsCheckbox`
+
+Boolean checkbox input.
+
+```tsx
+import { CmsCheckbox } from 'litecms/components';
+
+<CmsCheckbox
+    name="showInNav"
+    label="Show in Navigation"
+    helpText="Display this page in the nav bar"
+/>
+```
+
+#### `CmsHiddenField`
+
+Hidden input for non-editable values.
+
+```tsx
+import { CmsHiddenField } from 'litecms/components';
+
+<CmsHiddenField name="internalId" value="abc123" />
+```
+
+#### `CmsImageField`
+
+Image picker with upload support and gallery.
+
+```tsx
+import { CmsImageField } from 'litecms/components';
+
+<CmsImageField
+    name="heroImage"
+    label="Hero Image"
+    helpText="Upload or select an image"
+    required
+    accept="image/png,image/jpeg"  // Default: 'image/*'
+    storage={{
+        uploadEndpoint: '/api/storage/upload',
+        listEndpoint: '/api/storage/list',
+    }}
+/>
+```
+
+#### `CmsAutoForm`
+
+Auto-generates a complete form from a `SchemaDefinition`. Use this when you have direct access to the schema definition in client components.
+
+```tsx
+import { CmsAutoForm } from 'litecms/components';
+
+<CmsAutoForm
+    definition={HomePageDef}
+    action={saveHome}
+    values={currentData}
+    submitText="Save Changes"
+    submitPendingText="Saving..."
+    successMessage="Changes saved!"
+    onSuccess={(data) => console.log('Success!', data)}
+    styles={{
+        wrapper: 'max-w-2xl',
+        submitButton: 'bg-blue-500 text-white px-4 py-2',
+    }}
+/>
+```
+
+#### `CmsSimpleForm`
+
+Form component that accepts pre-extracted field info. Use this in server components or when fields need to be serialized (like with `extractPageProps`).
+
+```tsx
+import { CmsSimpleForm } from 'litecms/components';
+
+// Typically used via CmsAdminPage, but can be used directly:
+<CmsSimpleForm
+    fields={fieldInfoArray}      // FieldInfo[] (serializable)
+    action={saveAction}
+    values={currentData}
+    storage={storageConfig}
+    submitText="Save"
+    submitPendingText="Saving..."
+    successMessage="Changes saved"
+/>
+```
+
+---
+
+### Storage (`litecms/storage`)
+
+#### `createStorageClient(config)`
+
+Create an S3-compatible storage client.
+
+```typescript
+import { createStorageClient } from 'litecms/storage';
+
+export const storage = createStorageClient({
+    endpoint: process.env.S3_ENDPOINT!,        // e.g., 'https://minio.example.com'
+    region: 'us-east-1',                       // Default: 'us-east-1'
+    accessKeyId: process.env.S3_ACCESS_KEY!,
+    secretAccessKey: process.env.S3_SECRET_KEY!,
+    bucket: 'my-bucket',
+    forcePathStyle: true,                      // Required for Minio (default: true)
+    publicUrlBase: '/api/storage/images',      // URL prefix for serving files
+});
+```
+
+**Returns:**
+
+```typescript
+type StorageClient = {
+    /** Upload a file to storage */
+    uploadFile: (file: File, path?: string) => Promise<{ url: string; key: string }>;
+    /** List files in storage */
+    listFiles: (prefix?: string) => Promise<FileInfo[]>;
+    /** Delete a file from storage */
+    deleteFile: (key: string) => Promise<void>;
+    /** Get file content as buffer */
+    getFile: (key: string) => Promise<{ buffer: ArrayBuffer; contentType: string | undefined }>;
+    /** The underlying S3 client (for advanced usage) */
+    s3Client: S3Client;
+    /** The bucket name */
+    bucket: string;
+    /** The public URL base */
+    publicUrlBase: string;
+};
+
+type FileInfo = {
+    key: string;
+    url: string;
+    lastModified?: Date;
+    size?: number;
+};
+```
+
+**Usage:**
+
+```typescript
+// Upload
+const { url, key } = await storage.uploadFile(file);
+const { url, key } = await storage.uploadFile(file, 'custom/path/image.jpg');
+
+// List
+const files = await storage.listFiles();           // Default prefix: 'images/'
+const files = await storage.listFiles('uploads/');
+
+// Delete
+await storage.deleteFile(key);
+
+// Get file content
+const { buffer, contentType } = await storage.getFile(key);
+```
+
+---
+
+## Field Types
+
+| Type | Description |
+|------|-------------|
+| `text` | Single-line text input (default) |
+| `textarea` | Multi-line text input |
+| `number` | Numeric input |
+| `email` | Email input with validation |
+| `url` | URL input with validation |
+| `select` | Dropdown select (requires `options`) |
+| `checkbox` | Boolean checkbox |
+| `image` | Image picker with upload (requires storage config) |
+
+## Field Grouping
+
+Organize fields into collapsible groups in the admin form:
+
+```typescript
+fields: {
+    heroTitle: { label: 'Hero Title', group: 'Hero Section', order: 1 },
+    heroSubtitle: { label: 'Subtitle', group: 'Hero Section', order: 2 },
+    footerText: { label: 'Footer Text', group: 'Footer', order: 10 },
+    metaTitle: { label: 'SEO Title', group: 'SEO', order: 20 },
+}
+```
+
+## Non-Editable Fields
+
+Mark fields as `editable: false` to exclude them from the form. They will be preserved as hidden inputs:
+
+```typescript
+fields: {
+    internalNotes: {
+        label: 'Internal Notes',
+        editable: false, // Won't show in form, but value is preserved
+    },
+    features: {
+        label: 'Features',
+        editable: false, // Complex arrays often need custom editors
+    },
+}
+```
+
+## Styling
+
+Override default styles with className props:
+
+```tsx
+<CmsAutoForm
+    definition={def}
+    action={action}
+    styles={{
+        wrapper: 'max-w-2xl',
+        field: 'mb-4',
+        label: 'text-sm font-bold',
+        input: 'border-2 rounded-lg',
+        error: 'text-red-600 text-xs',
+        help: 'text-gray-500 text-xs',
+        group: 'p-4 border rounded',
+        groupTitle: 'text-lg font-semibold',
+        formError: 'bg-red-50 p-4 rounded',
+        formSuccess: 'bg-green-50 p-4 rounded',
+        submitButton: 'bg-blue-500 text-white px-4 py-2',
+    }}
+/>
+```
+
+---
+
+## Integration Guide: Better Auth + Drizzle
+
+litecms works great with [Better Auth](https://better-auth.com) for authentication and [Drizzle ORM](https://orm.drizzle.team) for database access. Here's a complete setup guide.
+
+### Prerequisites
+
+```bash
+bun add better-auth drizzle-orm postgres
+bun add -D drizzle-kit
+```
+
+### 1. Database Setup with Drizzle
+
+Create the database schema files:
+
+```typescript
+// app/db/auth-schema.ts
+import { pgTable, text, timestamp, boolean } from "drizzle-orm/pg-core";
+
+export const user = pgTable("user", {
+    id: text("id").primaryKey(),
+    name: text("name").notNull(),
+    email: text("email").notNull().unique(),
+    emailVerified: boolean("email_verified").notNull().default(false),
+    image: text("image"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+});
+
+export const session = pgTable("session", {
+    id: text("id").primaryKey(),
+    expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
+    token: text("token").notNull().unique(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+    ipAddress: text("ip_address"),
+    userAgent: text("user_agent"),
+    userId: text("user_id")
+        .notNull()
+        .references(() => user.id, { onDelete: "cascade" }),
+});
+
+export const account = pgTable("account", {
+    id: text("id").primaryKey(),
+    accountId: text("account_id").notNull(),
+    providerId: text("provider_id").notNull(),
+    userId: text("user_id")
+        .notNull()
+        .references(() => user.id, { onDelete: "cascade" }),
+    accessToken: text("access_token"),
+    refreshToken: text("refresh_token"),
+    idToken: text("id_token"),
+    accessTokenExpiresAt: timestamp("access_token_expires_at", { withTimezone: true }),
+    refreshTokenExpiresAt: timestamp("refresh_token_expires_at", { withTimezone: true }),
+    scope: text("scope"),
+    password: text("password"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+});
+
+export const verification = pgTable("verification", {
+    id: text("id").primaryKey(),
+    identifier: text("identifier").notNull(),
+    value: text("value").notNull(),
+    expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+});
+```
+
+```typescript
+// app/db/schema.ts
+import { pgTable, text, timestamp, jsonb } from "drizzle-orm/pg-core";
+
+// CMS documents table - stores all page content as JSON
+export const cmsDocuments = pgTable("cms_documents", {
+    key: text("key").primaryKey(),        // e.g., 'home', 'about', 'site-settings'
+    data: jsonb("data").notNull(),        // The page data as JSON
+    content: text("content"),             // Optional: rendered content for search
+    updatedAt: timestamp("updated_at", { withTimezone: true })
+        .notNull()
+        .defaultNow(),
+    updatedBy: text("updated_by"),        // Optional: track who made changes
+});
+```
+
+```typescript
+// app/db/index.ts
+import postgres from 'postgres';
+import { drizzle } from 'drizzle-orm/postgres-js';
+import * as schema from './schema';
+import * as authSchema from './auth-schema';
+
+const url = process.env.DATABASE_URL ?? process.env.POSTGRES_URL;
+
+if (!url) throw new Error('Missing DATABASE_URL env var');
+
+// Prevent multiple connections in development
+const globalForDb = globalThis as unknown as { _sql?: postgres.Sql };
+
+const sql = globalForDb._sql ?? postgres(url, {
+    max: process.env.NODE_ENV === 'production' ? 10 : 1,
+    idle_timeout: 20,
+});
+
+if (process.env.NODE_ENV !== 'production') globalForDb._sql = sql;
+
+export const db = drizzle(sql, { schema: { ...schema, ...authSchema } });
+
+export * as authSchema from './auth-schema';
+```
+
+```typescript
+// drizzle.config.ts
+import type { Config } from "drizzle-kit";
+
+export default {
+    schema: ["./app/db/schema.ts", "./app/db/auth-schema.ts"],
+    out: "./drizzle",
+    dialect: "postgresql",
+    dbCredentials: {
+        url: process.env.DATABASE_URL!,
+    },
+} satisfies Config;
+```
+
+Run migrations:
+
+```bash
+bun drizzle-kit generate
+bun drizzle-kit migrate
+```
+
+### 2. Better Auth Configuration
+
+```typescript
+// app/lib/auth.ts
+import { betterAuth } from "better-auth";
+import { drizzleAdapter } from "better-auth/adapters/drizzle";
+import { nextCookies } from "better-auth/next-js";
+import { db, authSchema } from "@/app/db";
+
+export const auth = betterAuth({
+    database: drizzleAdapter(db, {
+        provider: "pg",
+        schema: authSchema,
+    }),
+    emailAndPassword: {
+        enabled: true,
+    },
+    plugins: [nextCookies()],
+});
+```
+
+```typescript
+// app/lib/auth-client.ts
+"use client";
+
+import { createAuthClient } from "better-auth/react";
+
+export const authClient = createAuthClient();
+
+export const { signIn, signOut, signUp, useSession } = authClient;
+```
+
+### 3. Auth API Route
+
+```typescript
+// app/api/auth/[...all]/route.ts
+import { auth } from "@/app/lib/auth";
+import { toNextJsHandler } from "better-auth/next-js";
+
+export const { GET, POST } = toNextJsHandler(auth.handler);
+```
+
+### 4. Server Actions with Drizzle
+
+```typescript
+// app/admin/actions.ts
+'use server';
+
+import { eq } from 'drizzle-orm';
+import { revalidatePath } from 'next/cache';
+import { createSaveAction } from 'litecms/server';
+import { db } from '../db';
+import { cmsDocuments } from '../db/schema';
+import { auth } from '../lib/auth';
+import { headers } from 'next/headers';
+import {
+    HomePageSchema,
+    type HomePageData,
+    homePageDefaults,
+} from '../cms/schema';
+
+// Generic helper to save any document
+async function saveDocument(key: string, data: unknown) {
+    await db
+        .insert(cmsDocuments)
+        .values({
+            key,
+            data: data,
+            updatedAt: new Date(),
+        })
+        .onConflictDoUpdate({
+            target: cmsDocuments.key,
+            set: {
+                data: data,
+                updatedAt: new Date(),
+            },
+        });
+}
+
+// Generic helper to get any document
+async function getDocument<T>(key: string): Promise<T | null> {
+    const doc = await db.query.cmsDocuments.findFirst({
+        where: eq(cmsDocuments.key, key),
+    });
+    return (doc?.data as T) ?? null;
+}
+
+// Auth check helper
+async function checkAuthenticated(): Promise<boolean> {
+    const session = await auth.api.getSession({
+        headers: await headers(),
+    });
+    return !!session;
+}
+
+// Homepage actions
+export const saveHome = createSaveAction(HomePageSchema, {
+    save: async (data) => saveDocument('home', data),
+    revalidatePath: '/',
+    onRevalidate: revalidatePath,
+    checkAuth: checkAuthenticated,
+});
+
+export async function getHomePageData(): Promise<HomePageData> {
+    const data = await getDocument<HomePageData>('home');
+    if (!data) return homePageDefaults;
+    const result = HomePageSchema.safeParse(data);
+    return result.success ? result.data : homePageDefaults;
+}
+```
+
+### 5. Protected Admin Layout
+
+```typescript
+// app/admin/layout.tsx
+'use client';
+
+import type { ReactNode } from 'react';
+import { useRouter } from 'next/navigation';
+import { useEffect } from 'react';
+import { CmsAdminLayout } from 'litecms/admin';
+import { extractLayoutProps } from 'litecms/admin/config';
+import { cmsConfig } from '../cms/config';
+import { useSession, signOut } from '../lib/auth-client';
+
+export default function AdminLayout({ children }: { children: ReactNode }) {
+    const router = useRouter();
+    const { data: session, isPending } = useSession();
+
+    // Redirect to login if not authenticated
+    useEffect(() => {
+        if (!isPending && !session) {
+            router.push('/login');
+        }
+    }, [isPending, session, router]);
+
+    const handleLogout = async () => {
+        await signOut({
+            fetchOptions: {
+                onSuccess: () => {
+                    router.push('/login');
+                    router.refresh();
+                },
+            },
+        });
+    };
+
+    // Show nothing while checking auth
+    if (isPending || !session) {
+        return null;
+    }
+
+    return (
+        <CmsAdminLayout
+            {...extractLayoutProps(cmsConfig)}
+            onLogout={handleLogout}
+        >
+            {children}
+        </CmsAdminLayout>
+    );
+}
+```
+
+### 6. Login Page
+
+```typescript
+// app/login/page.tsx
+"use client";
+
+import { useState } from "react";
+import { useRouter } from "next/navigation";
+import Link from "next/link";
+import { signIn } from "@/app/lib/auth-client";
+
+export default function LoginPage() {
+    const router = useRouter();
+    const [email, setEmail] = useState("");
+    const [password, setPassword] = useState("");
+    const [error, setError] = useState<string | null>(null);
+    const [loading, setLoading] = useState(false);
+
+    const handleSubmit = async (e: React.FormEvent) => {
+        e.preventDefault();
+        setError(null);
+        setLoading(true);
+
+        try {
+            const result = await signIn.email({
+                email,
+                password,
+                callbackURL: "/admin",
+            });
+
+            if (result.error) {
+                setError(result.error.message || "Invalid credentials");
+            } else {
+                router.push("/admin");
+                router.refresh();
+            }
+        } catch {
+            setError("An error occurred. Please try again.");
+        } finally {
+            setLoading(false);
+        }
+    };
+
+    return (
+        <div className="min-h-screen flex items-center justify-center bg-gray-50 px-4">
+            <div className="max-w-md w-full space-y-8">
+                <div className="text-center">
+                    <h1 className="text-3xl font-bold text-gray-900">Admin Login</h1>
+                    <p className="mt-2 text-gray-600">
+                        Sign in to access the content manager
+                    </p>
+                </div>
+
+                <form onSubmit={handleSubmit} className="mt-8 space-y-6">
+                    <div className="space-y-4">
+                        <div>
+                            <label htmlFor="email" className="block text-sm font-medium text-gray-700">
+                                Email address
+                            </label>
+                            <input
+                                id="email"
+                                type="email"
+                                required
+                                value={email}
+                                onChange={(e) => setEmail(e.target.value)}
+                                className="mt-1 block w-full px-4 py-3 border border-gray-300 rounded-lg"
+                                placeholder="admin@example.com"
+                            />
+                        </div>
+
+                        <div>
+                            <label htmlFor="password" className="block text-sm font-medium text-gray-700">
+                                Password
+                            </label>
+                            <input
+                                id="password"
+                                type="password"
+                                required
+                                value={password}
+                                onChange={(e) => setPassword(e.target.value)}
+                                className="mt-1 block w-full px-4 py-3 border border-gray-300 rounded-lg"
+                            />
+                        </div>
+                    </div>
+
+                    {error && (
+                        <div className="p-3 text-sm text-red-600 bg-red-50 rounded-lg">
+                            {error}
+                        </div>
+                    )}
+
+                    <button
+                        type="submit"
+                        disabled={loading}
+                        className="w-full py-3 px-4 rounded-lg text-white bg-blue-600 hover:bg-blue-700 disabled:opacity-50"
+                    >
+                        {loading ? "Signing in..." : "Sign in"}
+                    </button>
+
+                    <p className="text-center text-sm text-gray-600">
+                        Need an account?{" "}
+                        <Link href="/signup" className="text-blue-600 hover:text-blue-500">
+                            Sign up
+                        </Link>
+                    </p>
+                </form>
+            </div>
+        </div>
+    );
+}
+```
+
+### 7. Protected API Routes
+
+When using storage or other API routes, check authentication:
+
+```typescript
+// app/api/storage/upload/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { storage } from '@/lib/storage';
+import { auth } from '@/app/lib/auth';
+import { headers } from 'next/headers';
+
+export async function POST(request: NextRequest) {
+    // Check authentication using Better Auth
+    const session = await auth.api.getSession({
+        headers: await headers(),
+    });
+
+    if (!session) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+
+    // ... rest of upload logic
+}
+```
+
+### Environment Variables
+
+```bash
+# .env.local
+
+# Database (PostgreSQL)
+DATABASE_URL="postgresql://user:password@localhost:5432/mydb"
+
+# Better Auth
+BETTER_AUTH_SECRET="your-secret-key-min-32-chars"
+BETTER_AUTH_URL="http://localhost:3000"
+
+# Storage (optional, for image uploads)
+STORAGE_URL="http://localhost:9000"
+STORAGE_ACCESS_KEY="minioadmin"
+STORAGE_SECRET_KEY="minioadmin"
+STORAGE_BUCKET="mybucket"
+```
+
+### File Structure
+
+```
+app/
+├── admin/
+│   ├── [slug]/
+│   │   └── page.tsx          # Dynamic admin pages
+│   ├── actions.ts            # Server actions with Drizzle
+│   ├── layout.tsx            # Protected layout with Better Auth
+│   └── page.tsx              # Admin index/redirect
+├── api/
+│   ├── auth/
+│   │   └── [...all]/
+│   │       └── route.ts      # Better Auth handler
+│   └── storage/
+│       ├── upload/
+│       │   └── route.ts      # Protected upload
+│       └── list/
+│           └── route.ts      # Protected list
+├── cms/
+│   ├── config.ts             # CMS configuration
+│   └── schema.ts             # Zod schemas
+├── db/
+│   ├── auth-schema.ts        # Better Auth tables
+│   ├── index.ts              # Drizzle client
+│   └── schema.ts             # CMS tables
+├── lib/
+│   ├── auth.ts               # Better Auth server
+│   ├── auth-client.ts        # Better Auth client
+│   └── storage.ts            # Storage client
+├── login/
+│   └── page.tsx              # Login page
+└── signup/
+    └── page.tsx              # Signup page
+drizzle/
+└── ...                       # Generated migrations
+drizzle.config.ts
+```
+
+## License
+
+MIT © Timo Weiss