Introduction to Cloudflare Pages
By the end of this module you will understand the Cloudflare Pages architecture, its place in the JAMstack ecosystem, and why migrating from a self-hosted Docusaurus server to GitHub + Cloudflare Pages is a production-grade decision.
What Is Cloudflare Pages?
Cloudflare Pages is a JAMstack hosting platform built on top of Cloudflare's global edge network (330+ Points of Presence). It provides:
- Zero-config CI/CD — connect a Git repository and every push triggers a build + deploy
- Global CDN delivery — your static assets are served from the edge closest to your visitor
- Serverless functions — via Pages Functions (backed by Cloudflare Workers)
- Unlimited bandwidth — no egress fees, ever
- Automatic HTTPS — every project and preview gets a valid TLS certificate
flowchart TB
DEV["Developer\n(git push)"] --> GITHUB["GitHub Repository\n(source of truth)"]
GITHUB -->|webhook trigger| CF_BUILD["Cloudflare Pages\nBuild Pipeline"]
CF_BUILD -->|build command| ARTIFACT["Build Artifact\n(static files + functions)"]
ARTIFACT -->|deploy| CF_NET["Cloudflare Global Network\n(330+ PoPs)"]
CF_NET -->|serve from nearest edge| USER1["User — Tokyo"]
CF_NET -->|serve from nearest edge| USER2["User — London"]
CF_NET -->|serve from nearest edge| USER3["User — São Paulo"]
style GITHUB fill:#24292e,color:#fff,stroke:#555
style CF_BUILD fill:#f6821f,color:#fff,stroke:#e5711e
style CF_NET fill:#2563eb,color:#fff,stroke:#1e40af
style ARTIFACT fill:#16a34a,color:#fff,stroke:#15803d
Core Concepts
The JAMstack Model
JAMstack stands for JavaScript, APIs, Markup. The key principle: your HTML is pre-built at deploy time (not at request time), so there is no server to maintain, patch, or scale.
| Layer | Self-Hosted Docusaurus | GitHub + Cloudflare Pages |
|---|---|---|
| Build | Manual or CI script on your server | Automatic on every git push |
| Serving | Nginx/Caddy on a VPS | Cloudflare's global CDN |
| SSL | Let's Encrypt (manual renewal) | Automatic, managed by Cloudflare |
| Scaling | Your server's limits | Infinite — edge distributed |
| Availability | Your VPS uptime | 99.99%+ SLA |
| Cost | VPS fees + time | Free (up to 500 builds/month) |
Build Pipeline
When you push to your repository, Cloudflare Pages:
- Clones your repository at that commit
- Installs dependencies (
npm cioryarn install) - Runs your build command (
npm run build) - Uploads the output directory to Cloudflare's edge storage
- Atomically activates the new deployment (zero-downtime)
Deployment Types
| Type | URL Pattern | Trigger |
|---|---|---|
| Production | your-project.pages.dev or custom domain | Push to production branch |
| Preview | <commit-hash>.your-project.pages.dev | Push to any other branch |
| Direct Upload | Same as above | wrangler pages deploy CLI |
Pages vs Workers
Cloudflare Pages and Workers are complementary:
| Pages | Workers | |
|---|---|---|
| Primary use | Static sites + full-stack apps | Serverless API / edge logic |
| Deployment unit | Full project (assets + functions) | Individual Worker script |
| Functions | Via functions/ directory (file-based routing) | Via fetch handler |
| Asset serving | Built-in (static files) | Must use Workers Static Assets |
| CI/CD | Git-native, automatic | wrangler deploy |
Under the hood, Pages Functions are Workers. They share the same runtime, bindings (KV, D1, R2), and limits. The only difference is how they're deployed and routed.
Why Migrate From Self-Hosted Docusaurus?
If you are running Docusaurus inside a Docker container (e.g., Nginx serving the build/ output), here is why GitHub + Cloudflare Pages is superior:
Operational Simplification
Before (Self-Hosted):
Docusaurus repo → manual build → scp/rsync to VPS → Nginx serves files
Risk: server crash, SSL expiry, bandwidth bill, manual updates
After (GitHub + Cloudflare Pages):
Docusaurus repo → git push → Cloudflare builds & deploys → edge serves files
Risk: essentially zero
Performance
- Edge serving: files are cached at 330+ locations vs one VPS
- HTTP/3 + QUIC: enabled by default on Cloudflare Pages
- Brotli compression: automatic for text assets
- Image optimization: via Cloudflare's Polish (optional)
Cost
| Item | Self-Hosted VPS | Cloudflare Pages |
|---|---|---|
| Compute | $5–$20/month | $0 |
| Bandwidth | ~$0.01/GB | $0 (unlimited) |
| SSL renewal | Time cost | $0 (automatic) |
| DDoS protection | $0 (basic) or $$$ | $0 (included) |
| Total | $60–$240/year | $0/year |
Free Tier Limits
| Resource | Free Tier |
|---|---|
| Projects | Unlimited |
| Builds per month | 500 |
| Concurrent builds | 1 |
| Custom domains | Unlimited |
| Preview deployments | Unlimited |
| Bandwidth | Unlimited |
| Pages Functions requests | 100,000/day |
| Build timeout | 20 minutes |
| Maximum asset size | 25 MB per file |
| Total assets per deployment | 20,000 files |
For a Docusaurus documentation site with infrequent updates, 500 builds/month is more than enough. If you CI/CD very aggressively (e.g., every commit on feature branches), consider squashing commits or only triggering builds on main.
Cloudflare Pages vs Alternatives
| Feature | Cloudflare Pages | Vercel | Netlify | GitHub Pages |
|---|---|---|---|---|
| Free bandwidth | Unlimited | 100 GB | 100 GB | 100 GB/month soft |
| Free builds | 500/month | 6,000 min | 300 min | Unlimited |
| Edge functions | ✅ Workers | ✅ Edge Functions | ✅ Edge Functions | ❌ |
| Custom domains | Unlimited | 50 on free | 100 on free | 1 per repo |
| Deploy previews | ✅ Unlimited | ✅ | ✅ | ❌ |
| DDoS protection | ✅ Included | ❌ | ❌ | ❌ |
| Private repo support | ✅ | ✅ | ✅ | ❌ (free) |
| Zero cold starts | ✅ (Workers) | ❌ | ❌ | N/A |
Key Takeaways
- Cloudflare Pages is a JAMstack platform: build once at deploy time, serve from the edge forever.
- The migration from self-hosted Docusaurus → GitHub + Cloudflare Pages eliminates server maintenance, reduces cost to zero, and improves global performance.
- Git push = deployment — no SSH, no
rsync, no manual steps. - Free tier covers unlimited bandwidth, unlimited projects, and 500 builds/month — more than enough for most documentation sites.
- Pages Functions (Workers) let you add server-side logic without leaving the platform.
What's Next
- Continue to Setting Up GitHub + Cloudflare Pages to walk through the complete migration from self-hosted Docusaurus.