Skip to content

DEPLOYMENT.md

Latest commit

 

History

History
224 lines (169 loc) · 5.76 KB

DEPLOYMENT.md

File metadata and controls

224 lines (169 loc) · 5.76 KB

Cloudflare Pages Deployment Guide

This project is configured for deployment on Cloudflare Pages, providing a fast, secure, and globally distributed hosting solution.

Prerequisites

  1. Cloudflare Account: Sign up at cloudflare.com
  2. Wrangler CLI: Install globally 
    npm install -g wrangler
# or
bun install -g wrangler
  3. Authentication: Login to Cloudflare 
    wrangler login

Deployment Methods

Method 1: Direct Deploy with Wrangler CLI

  1. Build the project:

    bun run pages:build

  2. Deploy to Cloudflare Pages:

    # Deploy to preview
bun run pages:deploy

# Deploy to production
bun run pages:deploy:production

Method 2: Git Integration (Recommended)

  1. Connect Repository:

    • Go to Cloudflare Dashboard → Pages
    • Click "Create a project"
    • Connect your GitHub/GitLab repository
    • Select the deltaview repository

  2. Configure Build Settings:

    Build command:        bun run pages:build
Build output directory: dist
Root directory:       /
Environment variables: (none required by default)

  3. Framework preset: Select "None" or "Static Site"

  4. Branch deployment:

    • Production branch: main or master
    • Preview branches: All other branches

Method 3: CI/CD with GitHub Actions

Create .github/workflows/deploy.yml:

name: Deploy to Cloudflare Pages

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      deployments: write
    steps:
      - uses: actions/checkout@v4
      
      - uses: oven-sh/setup-bun@v1
        with:
          bun-version: latest
      
      - name: Install dependencies
        run: bun install
      
      - name: Build
        run: bun run pages:build
      
      - name: Deploy to Cloudflare Pages
        uses: cloudflare/pages-action@v1
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          projectName: deltaview
          directory: dist
          gitHubToken: ${{ secrets.GITHUB_TOKEN }}

Required Secrets (add in GitHub repository settings):

  • CLOUDFLARE_API_TOKEN: Get from Cloudflare Dashboard → My Profile → API Tokens
  • CLOUDFLARE_ACCOUNT_ID: Get from Cloudflare Dashboard → Workers & Pages

Configuration Files

wrangler.toml

Main configuration for Cloudflare Workers/Pages. Defines:

  • Project name
  • Build output directory
  • Environment variables
  • Custom domains (optional)

public/_headers

HTTP headers for security and caching:

  • Security headers (XSS protection, CSP, etc.)
  • Cache control for static assets
  • Asset immutability for optimal performance

public/_redirects

SPA routing configuration:

  • Redirects all routes to index.html
  • Ensures React Router works correctly

Custom Domain Setup

  1. Add domain in Cloudflare Dashboard:

    • Pages → Your Project → Custom domains
    • Add your domain (e.g., deltaview.refactorroom.com)

  2. Update DNS:

    • Add CNAME record pointing to your Pages URL
    • Or use Cloudflare's automatic DNS setup

  3. Update wrangler.toml:

    [env.production]
routes = [
  { pattern = "yourdomain.com", custom_domain = true }
]

Environment Variables

Add environment variables in:

  • Dashboard: Cloudflare Dashboard → Pages → Project → Settings → Environment variables
  • Local: Create .dev.vars file (gitignored)

Example .dev.vars:

NODE_ENV=production
API_URL=https://api.example.com

Local Development with Cloudflare

Test your site locally with Cloudflare's environment:

# Build first
bun run pages:build

# Run local Pages dev server
bun run pages:dev

This simulates the Cloudflare Pages environment locally.

Monitoring & Analytics

  • Dashboard: View analytics at Cloudflare Dashboard → Pages → Your Project
  • Real-time logs: Use wrangler pages deployment tail
  • Web Analytics: Enable in Cloudflare Dashboard for privacy-friendly analytics

Rollback & Version Control

Cloudflare Pages keeps all deployments:

  1. Go to Dashboard → Pages → Your Project → Deployments
  2. Select any previous deployment
  3. Click "Rollback to this deployment"

Performance Features

Cloudflare Pages automatically provides:

  • ✅ Global CDN with 275+ locations
  • ✅ HTTP/3 and QUIC support
  • ✅ Automatic HTTPS with certificates
  • ✅ DDoS protection
  • ✅ Brotli compression
  • ✅ Image optimization (with Cloudflare Images)

Troubleshooting

Build Failures

  • Check build command in dashboard matches bun run pages:build
  • Ensure dist directory is set as build output
  • Verify all dependencies are in package.json

404 Errors on Routes

  • Ensure public/_redirects file exists
  • Verify SPA fallback is configured: /* /index.html 200

Assets Not Loading

  • Check public/_headers for correct cache headers
  • Verify asset paths are relative or absolute
  • Check browser console for CORS errors

Additional Resources

Scripts Reference

Script Description
bun run pages:build Build production bundle for Cloudflare Pages
bun run pages:deploy Deploy to preview environment
bun run pages:deploy:production Deploy to production
bun run pages:dev Run local Cloudflare Pages dev server

For support, visit Cloudflare Community or Discord.