Lecrev

A CLI tool for deploying and managing Cloudflare Workers-based static site hosting with edge caching, custom domains, and multi-site support.

Features

• 🚀 Easy deployment - Deploy static sites to Cloudflare's edge network
• 🌐 Multi-site support - Host multiple sites with a single worker
• ⚡ Edge caching - Automatic caching with KV store for optimal performance
• 🔧 Site types - Support for static, SPA, and hybrid applications
• 🛠️ Simple CLI - Intuitive commands for all operations
• 📊 Analytics - Built-in request tracking and metrics
• 🔄 Versioned deployments - Zero-downtime deployments with instant rollback
• 🗑️ No cache purging needed - Smart cache expiration with versioned paths

Installation

npm install -g lecrev

Or use directly with npx:

npx lecrev init

Quick Start

Option 1: Scaffold a new site project

lecrev scaffold

Choose from popular frameworks like:

• Astro - Content-focused static site generator
• Next.js - React framework (configured for static export)
• Vite + React/Vue - Fast build tool with your favorite framework
• TanStack Router - Type-safe routing for React
• SvelteKit - Svelte framework with static adapter
• SolidJS - Fine-grained reactive UI
• And more!

Option 2: Initialize Lecrev infrastructure

lecrev init

This interactive setup will:

• Check Cloudflare authentication (prompts for wrangler login if needed)
• Create a project directory (if current directory is not empty)
• Create necessary resources (R2 bucket, D1 database, KV namespace)
• Initialize a Wrangler project with wrangler init
• Set up the worker code and migrations
• Run database migrations automatically
• Generate configuration files
• Optionally deploy the worker immediately

2. Deploy the worker infrastructure

lecrev deploy-worker

3. Add a domain

# Auto-generates R2 prefix as sites/example-com
lecrev add-domain example.com

4. Link your project (recommended)

# In your project directory
lecrev link example.com

5. Deploy your site

# Simple deployment after linking
lecrev deploy

# Or specify manually
lecrev deploy ./dist --domain example.com

# Deploy with environment variables for build
lecrev deploy --env API_URL=https://api.example.com NODE_ENV=production

Commands

lecrev scaffold

Scaffold a new static site project with popular frameworks. Alias: lecrev new

lecrev init

Initialize a new Lecrev project with interactive setup.

lecrev deploy-worker [options]

Deploy the Cloudflare Worker infrastructure.

Options:

• --env <environment> - Deployment environment (default: production)
• --dry-run - Show what would be deployed without deploying

lecrev deploy [local-directory] [options]

Deploy a site to a configured domain. Auto-detects and builds your project if no directory specified.

Arguments:

• [local-directory] - Optional path to deploy (auto-detected if not specified)

Options:

• -d, --domain <hostname> - Domain to deploy to (if not specified, shows a list)
• --no-build - Skip building the project
• --build-command <command> - Custom build command (default: auto-detect)
• --clean - Remove orphaned files not in the new deployment
• --env <vars...> - Environment variables to pass to build command (format: KEY=value)

Auto-detection supports:

• Vite, Next.js, Gatsby, Astro projects
• Any project with npm run build script
• Hugo, Jekyll static site generators

Note: Cache purging is no longer necessary with versioned deployments. Each deployment gets a unique path, and cache naturally expires based on TTL settings.

lecrev add-domain <hostname> [r2-prefix] [options]

Add or update a domain mapping. If R2 prefix is not provided, it will be auto-generated as sites/{domain-with-dashes}.

Options:

• -t, --type <type> - Site type: static, spa, or hybrid (default: static)
• --remote - Execute on remote database
• --routing-config <json> - Routing configuration for hybrid sites

lecrev remove-domain <hostname> [options]

Remove a domain mapping.

Options:

• --remote - Execute on remote database

lecrev list-domains [options]

List all configured domains.

Options:

• --remote - Query remote database
• --json - Output as JSON

lecrev upload-site <r2-prefix> <local-directory> [options]

Upload site files to R2.

Options:

• --hostname <hostname> - Hostname to purge cache for after upload
• --dry-run - Show what would be uploaded without uploading
• --clean - Remove orphaned files not in the local directory

lecrev purge-cache <hostname>

[Deprecated] Purge cache for a specific hostname. No longer needed with versioned deployments.

lecrev migrate [options]

Run database migrations.

Options:

• --remote - Execute on remote database
• --file <path> - Specific migration file to run

lecrev update-migrations [options]

Update database migration files to the latest version. Alias: lecrev migrations:update

Options:

• --check - Check if updates are available without applying them
• --run - Automatically run new migrations after copying

This command is useful when Lecrev adds new features that require database schema changes.

lecrev link [domain]

Link current directory to a domain for easy deployment. Creates a .lecrev file.

Arguments:

• [domain] - Domain to link (shows list if not specified)

After linking, you can deploy with just lecrev deploy.

lecrev list-deployments [hostname] [options]

List deployment history for one or all domains. Alias: lecrev deployments

Arguments:

• [hostname] - Show deployments for specific domain (shows all if not specified)

Options:

• --limit <number> - Number of deployments to show (default: 10)
• --all - Show all deployments

lecrev rollback <hostname> [options]

Rollback to a previous deployment instantly.

Options:

• --deployment <id> - Specific deployment ID to rollback to (shows list if not specified)

lecrev cleanup-deployments [hostname] [options]

Clean up old deployments to save storage space.

Arguments:

• [hostname] - Clean deployments for specific domain (cleans all if not specified)

Options:

• --keep <number> - Number of recent deployments to keep per domain (default: 5)
• --days <number> - Delete deployments older than this many days (default: 30)
• --dry-run - Show what would be deleted without deleting
• --force - Skip confirmation prompt

Site Types

Static

Traditional multi-page sites. Returns 404 for missing pages.

lecrev add-domain example.com sites/example --type static

SPA (Single Page Application)

Applications with client-side routing. Falls back to index.html for all routes.

lecrev add-domain app.example.com sites/app --type spa

Hybrid

Mixed static and SPA sites with configurable routing rules.

lecrev add-domain example.com sites/example --type hybrid \
  --routing-config '{"spaFallbackPaths":["/app/*","/dashboard/*"],"staticOnlyPaths":["/docs/*"]}'

Configuration

Lecrev stores configuration in two possible locations:

1. Global config: ~/.lecrev/config.json
2. Local config: .lecrev.json in your project directory

You can also use environment variables:

export LECREV_ACCOUNT_ID=your-account-id
export LECREV_WORKER_NAME=your-worker-name
export LECREV_DATABASE_NAME=your-database-name
export LECREV_DATABASE_ID=your-database-id
export LECREV_KV_NAMESPACE_ID=your-kv-namespace-id
export LECREV_R2_BUCKET_NAME=your-bucket-name
export LECREV_API_KEY=your-api-key
export LECREV_WORKER_URL=https://your-worker.workers.dev

Deployment Strategy

Lecrev uses versioned deployments for zero-downtime updates and instant rollbacks:

How it works

1. Each deployment creates a unique version ID (e.g., v1736425123456-abc123)
2. Files are uploaded to a versioned path in R2 (e.g., sites/example/v1736425123456-abc123/)
3. Database is atomically updated to point to the new version
4. Old cached content naturally expires based on TTL settings
5. No manual cache purging needed!

Benefits

• Zero downtime - Instant switchover to new deployment
• Instant rollback - Switch back to any previous deployment
• No cache conflicts - Each version has its own cache namespace
• Deployment history - Track all deployments with timestamps
• Storage efficiency - Clean up old deployments as needed

Cache TTL Strategy

• HTML pages: 1 minute (for quick updates)
• Hashed assets: 1 year (immutable content)
• Images/fonts: 7 days
• Other assets: 1-24 hours

Clean Deployments

When deploying sites with hashed filenames (common with modern build tools), use the --clean flag to automatically remove orphaned files from previous deployments:

lecrev deploy --clean

This removes files that existed in the previous deployment but not in the new one, keeping your deployments tidy.

Updating Lecrev

When new versions of Lecrev are released, you may need to update both the CLI and your deployed infrastructure:

1. Update the CLI

npm update -g lecrev

2. Update worker source files

lecrev update-worker

3. Update database migrations

# Check for new migrations
lecrev update-migrations --check

# Copy and run new migrations
lecrev update-migrations --run

4. Deploy the updated worker

lecrev deploy-worker

Worker Architecture

The deployed worker includes:

• Edge routing - Intelligent request routing based on domain mappings
• Caching layer - KV-based caching for optimal performance
• Static file serving - Efficient delivery from R2 storage
• SPA support - Proper handling of client-side routing
• Analytics - Request tracking and metrics collection

Requirements

• Node.js 18 or later
• Cloudflare account with Workers enabled
• Wrangler CLI (installed automatically as dependency)

License

MIT