Content Workers - Cloudflare Edge Starter

A pure edge runtime starter template for Content Workers CMS optimized for Cloudflare Workers without Node.js compatibility layer.

🚀 Features

• Pure Edge Runtime: Zero Node.js dependencies - uses only Web APIs
• Ultra-Light Bundle: <100KB vs 2.5MB (Node.js CMS)
• Lightning Fast: Sub-50ms cold starts
• Native Cloudflare APIs: D1 Database and KV Storage integration
• Edge-First Design: Built specifically for Cloudflare Workers
• No Compatibility Layer: Pure edge runtime without nodejs_compat flag

📋 Prerequisites

• Node.js 20+ or 22+
• npm 10+
• Cloudflare account (for deployment)
• Wrangler CLI (for Cloudflare Workers development)

Wrangler Installation

For the best experience with Cloudflare Workers development:

# Install Wrangler globally (recommended)
npm install -g wrangler@latest

# Or use the local version (may have dependency issues)
npm install

Note: If you encounter workerd module errors, install Wrangler globally or use the Content Workers dev server instead.

🛠️ Quick Start

1. Install Dependencies

npm install

2. Setup Wrangler (Optional)

For Cloudflare Workers development with D1 and KV:

# Automated setup (installs and configures Wrangler)
npm run setup-wrangler

# Or manual setup
npm install -g wrangler@latest
wrangler auth login

3. Generate Security Keys

npm run generate-keys

This creates a .dev.vars file with secure random keys.

4. Choose Development Mode

# Interactive mode selector
npm run dev:select

# Or directly:
npm run dev              # Pure Edge Runtime with D1/KV (port 8787) - DEFAULT
npm run dev:cw           # Content Workers dev server (port 6548) - FALLBACK

Pure Edge Development:

1. Pure Edge Runtime (npm run dev) - DEFAULT

   • Uses D1 Database and KV Storage
   • Zero Node.js dependencies
   • Runs on http://localhost:8787
   • Production-accurate edge environment

2. Content Workers Dev Server (npm run dev:cw) - FALLBACK

   • Uses Edge Adapter with SQLite (shows compatibility warnings)
   • Fast startup and hot reload
   • Runs on http://localhost:6548
   • Fallback for development when Wrangler has issues

5. Access Admin Panel

Visit http://localhost:6548/admin to access the Content Workers admin interface.

🏗️ Development Commands

Content Workers CLI

npm run dev              # Start development server
npm run build            # Build for production
npm run serve            # Serve built application
npm run migrate          # Run database migrations
npm run migrate:fresh    # Reset and re-run migrations

Wrangler Commands

npm run cf:local         # Local Workers simulation
npm run cf:dev           # Build and run with Wrangler
npm run cf:deploy        # Build and deploy to Cloudflare
npm run wrangler:dev     # Direct Wrangler dev mode

Database Commands

npm run wrangler:d1:list    # List D1 databases
npm run wrangler:d1:create  # Create new D1 database

🗄️ Database Configuration

Development (SQLite)

Uses local SQLite database (content-workers-edge.sqlite) for development.

⚠️ Note: SQLite shows warnings in edge runtime but works for development.

Production (D1)

Configure D1 database in wrangler.toml:

[[d1_databases]]
binding = "DB"
database_name = "content-workers-edge-db"
database_id = "your-d1-database-id"

Create D1 database:

wrangler d1 create content-workers-edge-db

Alternative: LibSQL/Turso

Uncomment LibSQL configuration in cw.config.ts and set environment variables:

DATABASE_URL=libsql://your-database.turso.io
TURSO_AUTH_TOKEN=your-auth-token

🔧 Configuration

Environment Variables

Required variables (auto-generated by npm run generate-keys):

CW_ENCRYPTION_KEY=64-character-random-string
CW_COOKIE_SECRET=64-character-random-string
CW_REFRESH_TOKEN_SECRET=64-character-random-string
CW_ACCESS_TOKEN_SECRET=64-character-random-string

Optional variables:

DATABASE_URL=libsql://your-database.turso.io  # For LibSQL/Turso
TURSO_AUTH_TOKEN=your-auth-token              # For LibSQL/Turso

Collections

Pre-configured collections:

• Pages: Basic page content with slugs
• Blogs: Blog posts with categories and tags

Customize in src/collections/ directory.

🚀 Deployment

1. Configure Wrangler

Update wrangler.toml with your project details:

name = "your-app-name"

2. Set Production Environment Variables

wrangler secret put CW_ENCRYPTION_KEY
wrangler secret put CW_COOKIE_SECRET
wrangler secret put CW_REFRESH_TOKEN_SECRET
wrangler secret put CW_ACCESS_TOKEN_SECRET

3. Deploy

npm run cf:deploy

🔌 Edge-Compatible Plugins

Only use plugins that support pure edge runtime:

✅ Compatible

• @content-workers/plugin-pages - Page management
• @content-workers/auth-github - GitHub OAuth
• @content-workers/auth-google - Google OAuth
• @content-workers/plugin-resend - Email via Resend

❌ Not Compatible (Node.js only)

• @content-workers/plugin-nodemailer - Uses Node.js APIs
• @content-workers/plugin-s3 - Uses Node.js file system
• @content-workers/plugin-redis - Uses Node.js networking

📁 Project Structure

cloudflare-edge-starter/
├── src/
│   ├── collections/          # Content collections
│   │   ├── pages.ts         # Page collection
│   │   └── blogs.ts         # Blog collection
│   └── index.ts             # Entry point (if needed)
├── scripts/
│   └── generate-keys.js     # Security key generator
├── cw.config.ts             # Content Workers configuration
├── wrangler.toml            # Cloudflare Workers configuration
├── .dev.vars                # Development environment variables
├── package.json             # Dependencies and scripts
└── README.md                # This file

🐛 Troubleshooting

CSS Build Errors

If you encounter cssnano preset errors:

npm install cssnano cssnano-preset-lite --save-dev

Database Connection Issues

1. Ensure .dev.vars file exists with proper keys
2. Check D1 database configuration in wrangler.toml
3. Run migrations: npm run migrate:fresh

Wrangler Authentication

wrangler auth login

Edge Runtime Warnings

Some adapters may show warnings about Node.js compatibility. This is expected in development mode when using SQLite or other Node.js-based adapters.

Wrangler Issues

Error: Cannot find module 'workerd'

This is a common Wrangler dependency issue. Solutions:

1. Install Wrangler globally (recommended):

   npm install -g wrangler@latest

2. Use Content Workers dev server instead:

   npm run dev  # Uses port 6548, no Wrangler required

3. For Windows users:

   • Install Visual Studio Build Tools
   • Or use WSL2 for better compatibility
   • Or use Docker for development

4. Clean installation:

   rm -rf node_modules package-lock.json
   npm install

📚 Learn More

• Content Workers Documentation
• Cloudflare Workers Documentation
• D1 Database Documentation
• Wrangler CLI Documentation

📄 License

MIT License - see LICENSE file for details.