Multi-Tenancy with Subdomains & Custom Domains on Cloudflare

A production-ready Next.js application demonstrating multi-tenancy with subdomains and custom domains, deployed on Cloudflare Workers.

🚀 What You'll Build

• ✅ Subdomain routing: Each tenant gets tenant.yourdomain.com
• ✅ Custom domains: Users can add example.com pointing to their content
• ✅ Automatic SSL: Certificates provisioned via Cloudflare for SaaS
• ✅ Global edge: Deployed on Cloudflare Workers for worldwide performance
• ✅ Tenant-specific content and pages
• ✅ Shared components and layouts across tenants
• ✅ Redis for tenant data storage
• ✅ Admin interface for managing tenants
• ✅ Emoji support for tenant branding
• ✅ Support for local development with subdomains
• ✅ Compatible with Cloudflare Workers preview deployments
• ✅ DNS configuration instructions for custom domains

📖 Complete Guide

📚 Read the full tutorial →

Tech Stack

• Next.js 15 with App Router
• React 19
• Cloudflare Workers for hosting
• OpenNext for Next.js compatibility
• Upstash Redis for data storage
• Cloudflare for SaaS for custom domains
• Tailwind 4 for styling
• shadcn/ui for the design system

The detailed guide covers:

• Architecture overview with diagrams
• Step-by-step Cloudflare configuration
• Custom domain DNS setup (CNAME, TXT, DCV delegation)
• Complete code examples and troubleshooting

⚡ Quick Start

Prerequisites

• Node.js 18.17.0 or later
• pnpm (recommended) or npm/yarn
• Cloudflare account with Workers enabled
• Upstash Redis account (for production)

Installation

git clone https://github.com/florianheysen/platforms-cf-worker.git
cd platforms-cf-worker
pnpm install

Environment Setup

Create .env.local:

# Cloudflare API
CLOUDFLARE_API_TOKEN=your_api_token
CLOUDFLARE_ZONE_ID=your_zone_id
CLOUDFLARE_ACCOUNT_ID=your_account_id

# Root domain
ROOT_DOMAIN=yourdomain.com
PROTOCOL=https

# Redis (Upstash)
UPSTASH_REDIS_REST_URL=your_redis_url
UPSTASH_REDIS_REST_TOKEN=your_redis_token

Development

pnpm dev

Access:

• Main site: http://localhost:3000
• Admin panel: http://localhost:3000/admin
• Test tenant: http://test.localhost:3000

Deployment

pnpm deploy

🏗️ Architecture

User Request → Cloudflare Edge → Next.js Middleware → Tenant Detection → Content

Key Components:

• Next.js 15 with App Router
• OpenNext for Cloudflare Workers compatibility
• Cloudflare for SaaS for custom domains & SSL
• Upstash Redis for tenant data
• Tailwind CSS for styling

🎯 Features

• ✅ Subdomain routing (tenant.yourdomain.com)
• ✅ Custom domains (example.com) with automatic SSL
• ✅ Admin interface for tenant management
• ✅ Redis-based data storage
• ✅ Global edge deployment
• ✅ Local development support

📚 Resources

• Complete Tutorial - Detailed guide with diagrams
• Cloudflare for SaaS - Official documentation
• OpenNext - Next.js → Workers adapter
• Upstash Redis - Serverless Redis

🚀 Deployment

This application is designed to be deployed on Cloudflare Workers using OpenNext. To deploy:

1. Push your repository to GitHub
2. Configure Cloudflare Workers and Cloudflare for SaaS
3. Set up environment variables in Cloudflare Workers
4. Deploy using wrangler deploy

Cloudflare Setup

1. Add your domain to Cloudflare:

   • Add your root domain to Cloudflare
   • Set up wildcard DNS record (*.yourdomain.com) pointing to your Workers app

2. Enable Cloudflare for SaaS:

   • Go to SSL/TLS → Custom Hostnames
   • Enable Custom Hostnames
   • Configure fallback origin to your Workers app

3. Deploy the application:

   pnpm deploy

4. Configure custom domains:

   • Users can add custom domains through the settings page
   • Custom domains are automatically added to Cloudflare for SaaS
   • Users configure CNAME records pointing to your Cloudflare domain

Custom Domain Setup

1. Navigate to [subdomain].yourdomain.com/settings
2. Enter the custom domain (e.g., example.com)
3. The domain will be automatically added to Cloudflare for SaaS
4. Configure DNS with the provided CNAME record pointing to your Cloudflare domain
5. Verify domain ownership (may require TXT record or nameserver change)
6. SSL certificate will be automatically generated by Cloudflare
7. The custom domain will route to the same content as the subdomain

Required Environment Variables for Custom Domains

To enable custom domain functionality, you need to set up Cloudflare API access:

1. CLOUDFLARE_API_TOKEN: Your Cloudflare API token with Custom Hostnames permissions
2. CLOUDFLARE_ZONE_ID: Your Cloudflare zone ID (found in domain dashboard)
3. CLOUDFLARE_ACCOUNT_ID: Your Cloudflare account ID (found in domain dashboard)
4. ROOT_DOMAIN: Your root domain (e.g., yourdomain.com)
5. PROTOCOL: Protocol to use (https)

Domain Verification

When users add custom domains, Cloudflare may require domain verification:

• TXT Record: Add a TXT record to your DNS settings
• Nameservers: Switch to Cloudflare's nameservers (provided in Cloudflare dashboard)

🤝 Contributing

Feel free to open issues and pull requests for improvements!

📄 License

MIT License - see LICENSE file for details.