fullstack-next-cloudflare

⚡ Full-Stack Next.js + Cloudflare Template

A production-ready template for building full-stack applications with Next.js 15 and Cloudflare's powerful edge infrastructure. Perfect for MVPs with generous free tiers and seamless scaling to enterprise-level applications.

Inspired by the Cloudflare SaaS Stack - the same stack powering Supermemory.ai, which serves 20k+ users on just $5/month. This template modernizes that approach with Cloudflare Workers (vs Pages), includes comprehensive D1 and R2 examples, and provides a complete development workflow.

You can read detail explanations and code architecture of this template from Devin AI on Deepwiki.

Don't forget to leave a star if you find this helpful ⭐️

Why Cloudflare + Next.js?

Cloudflare's Edge Network provides unparalleled performance and reliability:

• ⚡ Ultra-low latency - Deploy to 300+ locations worldwide
• Generous free tiers - Perfect for MVPs and side projects
• Effortless scaling - From zero to millions of users automatically
• Built-in security - DDoS protection, WAF, and more
• Global by default - Your app runs close to every user

Combined with Next.js 15, you get modern React features, Server Components, and Server Actions for optimal performance and developer experience.

️ Tech Stack

Frontend

• ⚛️ Next.js 15 - App Router with React Server Components (RSC)
• TailwindCSS 4 - Utility-first CSS framework
• TypeScript - Full type safety throughout
• Shadcn UI - Unstyled, accessible components
• React Hook Form + Zod - Type-safe form handling

☁️ Backend & Infrastructure

• Cloudflare Workers - Serverless edge compute platform
• ️ Cloudflare D1 - Distributed SQLite database at the edge
• Cloudflare R2 - S3-compatible object storage
• Cloudflare Workers AI - Edge AI inference with OpenSource models
• Better Auth - Modern authentication with Google OAuth
• ️ Drizzle ORM - TypeScript-first database toolkit

DevOps & Deployment

• ⚙️ GitHub Actions - Automated CI/CD pipeline
• Wrangler - Cloudflare's CLI tool
• ️ Preview Deployments - Test changes before production
• Database Migrations - Version-controlled schema changes
• Automated Backups - Production database safety

Data Flow Architecture

• Fetching: Server Actions + React Server Components for optimal performance
• Mutations: Server Actions with automatic revalidation
• AI Processing: Edge AI inference with Cloudflare Workers AI
• Type Safety: End-to-end TypeScript from database to UI
• Caching: Built-in Next.js caching with Cloudflare edge caching

️ Project Structure

This template uses a feature-based/module-sliced architecture for better maintainability and scalability:

…

Key Architecture Benefits:

• Feature Isolation - Each module contains its own actions, components, and logic
• Server Actions - Modern data mutations with automatic revalidation
• React Server Components - Optimal performance with server-side rendering
• Type Safety - End-to-end TypeScript from database to UI
• Testable - Clear separation of concerns makes testing easier

Getting Started

1. Prerequisites

• Cloudflare Account - Sign up for free
• Node.js 20+ and pnpm installed
• Google OAuth App - For authentication setup

2. Create Cloudflare API Token

Create an API token for Wrangler authentication:

1. In the Cloudflare dashboard, go to the Account API tokens page
2. Select Create Token > find Edit Cloudflare Workers > select Use Template
3. Customize your token name (e.g., "Next.js Cloudflare Template")
4. Scope your token to your account and zones (if using custom domains)
5. Add additional permissions for D1 database and AI access:
   • Account - D1:Edit
   • Account - D1:Read
   • Account - Cloudflare Workers AI:Read

Final Token Permissions:

• All permissions from "Edit Cloudflare Workers" template
• Account - D1:Edit (for database operations)
• Account - D1:Read (for database queries)
• Account - Cloudflare Workers AI:Read (for AI inference)

3. Clone and Setup

# Clone the repository
git clone https://github.com/ifindev/fullstack-next-cloudflare.git
cd fullstack-next-cloudflare

# Install dependencies
pnpm install

4. Environment Configuration

Create your environment file:

# Copy example environment file
cp .dev.vars.example .dev.vars

Edit .dev.vars with your credentials:

# Cloudflare Configuration
CLOUDFLARE_ACCOUNT_ID=your-account-id
CLOUDFLARE_D1_TOKEN=your-api-token

# Authentication Secrets
BETTER_AUTH_SECRET=your-random-secret-here
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

# Storage
CLOUDFLARE_R2_URL=your-r2-bucket-url

5. Authentication Setup

Better Auth Secret:

# Generate a random secret
openssl rand -base64 32
# Add to BETTER_AUTH_SECRET in .dev.vars

Google OAuth Setup: Follow the Better Auth Google documentation to:

1. Create a Google OAuth 2.0 application
2. Get your Client ID and Client Secret
3. Add authorized redirect URIs

6. Storage Setup & R2 URL Configuration

Understanding R2 URLs: Cloudflare R2 has different URL behaviors for development vs production:

• Development: R2 provides a public URL that works immediately
• Production: R2 public URLs are not meant for production use - you should set up a custom domain

Step 1: Create R2 Bucket

# Create R2 bucket for development
wrangler r2 bucket create your-app-bucket-dev

# For production, create a separate bucket
wrangler r2 bucket create your-app-bucket-prod

Step 2: Get R2 URL for Development

Enable Public Development URL:

1. Go to Cloudflare Dashboard
2. Click "R2 Object Storage" in the sidebar
3. Select your bucket from the list
4. Go to the "Settings" tab
5. Find "Public Development URL" section
6. Click "Enable Public URL"
7. Copy the displayed URL (it will be in format: https://pub-xxxxx.r2.dev)

Example URL Format:

https://pub-a1b2c3d4e5f6g7h8i9j0.r2.dev

Important Notes:

• The URL is automatically generated by Cloudflare
• No account ID needed - it's all in the provided URL
• This URL is for development only (not production)

Step 3: Add R2 URL to Environment Variables

# Add to your .dev.vars file (use the URL you copied from dashboard)
CLOUDFLARE_R2_URL=https://pub-a1b2c3d4e5f6g7h8i9j0.r2.dev

Note: Replace the example URL with the actual URL you copied from your R2 bucket settings.

For Production - Custom Domain Setup (Required):

⚠️ Important: The default R2 public URL should NOT be used in production as it's not optimized for performance and may have limitations.

Setup Custom Domain for R2:

# 1. Go to Cloudflare Dashboard → R2 Storage → Your Bucket → Custom Domains
# 2. Click "Connect Domain" and enter your desired domain (e.g., files.yourdomain.com)
# 3. Update your DNS records as instructed by Cloudflare
# 4. Wait for SSL certificate to be issued (usually a few minutes)

# Your production R2 URL will be:
# https://files.yourdomain.com

# Add this to your production secrets:
echo "https://files.yourdomain.com" | wrangler secret put CLOUDFLARE_R2_URL

R2 URL Summary:

• Development: Use URL from R2 bucket "Public Development URL" setting
• Production: Must use custom domain for better performance and reliability

How R2 URLs Work:

• Base URL: Get from R2 bucket settings (format: https://pub-xxxxx.r2.dev)
• File URLs: https://pub-xxxxx.r2.dev/{folder}/{file-name}.{extension}
• Environment Variable: Only the base URL goes into CLOUDFLARE_R2_URL
• Code: The full file paths are constructed programmatically using the base URL

️ Manual Setup (Detailed)

If you prefer to set everything up manually or want to understand each step in detail, follow this comprehensive guide.

Step 1: Create Cloudflare Resources

Create D1 Database:

# Create a new SQLite database at the edge
wrangler d1 create your-app-name

# Output will show:
# database_name = "your-app-name"
# database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Create R2 Bucket:

# Create object storage bucket
wrangler r2 bucket create your-app-bucket

# List buckets to confirm
wrangler r2 bucket list

Step 2: Configure Wrangler

Update wrangler.jsonc with your resource IDs:

{
    "name": "your-app-name",
    "d1_databases": [
        {
            "binding": "DB",
            "database_name": "your-app-name",
            "database_id": "your-database-id-from-step-1",
            "migrations_dir": "./src/drizzle"
        }
    ],
    "r2_buckets": [
        {
            "bucket_name": "your-app-bucket",
            "binding": "FILES"
        }
    ],
    "ai": {
        "binding": "AI"
    }
}

Step 3: Set Up Authentication

Generate Better Auth Secret:

# On macOS/Linux
openssl rand -base64 32

# On Windows (PowerShell)
[System.Convert]::ToBase64String([System.Security.Cryptography.RandomNumberGenerator]::GetBytes(32))

# Or use online generator: https://generate-secret.vercel.app/32

Configure Google OAuth:

1. Go to Google Cloud Console
2. Create a new project or select existing one
3. Enable Google+ API
4. Create OAuth 2.0 credentials
5. Add authorized redirect URIs:
   • http://localhost:3000/api/auth/callback/google (development)
   • https://your-app.your-subdomain.workers.dev/api/auth/callback/google (production)

Step 4: Environment Configuration

Create Local Environment File:

# .dev.vars for local development
CLOUDFLARE_ACCOUNT_ID=your-account-id
CLOUDFLARE_D1_TOKEN=your-api-token
BETTER_AUTH_SECRET=your-generated-secret
GOOGLE_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-google-client-secret
# Get this from R2 bucket settings: R2 Object Storage → Your Bucket → Settings → Public Development URL
CLOUDFLARE_R2_URL=https://pub-a1b2c3d4e5f6g7h8i9j0.r2.dev

Set Production Secrets:

# Add each secret to Cloudflare Workers
echo "your-secret-here" | wrangler secret put BETTER_AUTH_SECRET
echo "your-client-id" | wrangler secret put GOOGLE_CLIENT_ID
echo "your-client-secret" | wrangler secret put GOOGLE_CLIENT_SECRET
echo "your-r2-url" | wrangler secret put CLOUDFLARE_R2_URL

Step 5: Database Setup

Generate TypeScript Types:

# Generate Cloudflare bindings for TypeScript
pnpm run cf-typegen

Initialize Database:

# Generate initial migration from schema
pnpm run db:generate

# Apply migrations to local database
pnpm run db:migrate:local

# Verify database structure
pnpm run db:inspect:local

Optional: Seed Sample Data

# Create and run a seed script
wrangler d1 execute your-app-name --local --command="
INSERT INTO todos (id, title, description, completed, created_at, updated_at) VALUES
('1', 'Welcome to your app', 'This is a sample todo item', false, datetime('now'), datetime('now')),
('2', 'Set up authentication', 'Configure Google OAuth', true, datetime('now'), datetime('now'));
"

Step 6: Test Your Setup

Start Development Servers:

# Terminal 1: Start Wrangler (provides D1 access)
pnpm run wrangler:dev

# Terminal 2: Start Next.js (provides HMR)
pnpm run dev

# Alternative: Single command (no HMR)
pnpm run dev:cf

Verify Everything Works:

1. Open http://localhost:3000
2. Test authentication flow
3. Create a todo item
4. Check database: pnpm run db:studio:local

Ste