Cloudflare Pages Deployment
Relevant source files
The following files were used as context for generating this wiki page:
The Lou Gehrig Fan Club (LGFC) website utilizes Cloudflare Pages for hosting and deployment, specifically leveraging a static export build process. The deployment infrastructure integrates Next.js (App Router) with Cloudflare-specific features such as D1 for data storage and custom API functions to handle dynamic content like FAQs and library submissions.
Sources: README.md:5-7, context.md:12-14
Build and Adaptation Process
The project is structured as a Next.js application that undergoes a static export before being deployed to Cloudflare Pages. This process involves cleaning previous builds, executing the Next.js build, and post-processing steps to ensure routing compatibility.
Build Lifecycle
- Build Execution: The
npm run buildcommand removes previous.nextandoutdirectories before runningnext build. - Routing Post-build: A
postbuildscript copies the_routes.jsonfile into theoutdirectory to define routing rules for Cloudflare. - Cloudflare Adaptation: For environments using the
@cloudflare/next-on-pagesadapter, the process includes runningnpx @cloudflare/next-on-pagesto generate the necessary worker infrastructure (.open-next/worker.js).
Sources: package.json:52-54, scripts/fix-package-json-conflicts.sh:62-64
Deployment Configuration
The deployment relies on specific configuration flags for the Cloudflare environment, including Node.js compatibility and D1 database bindings.
| Script | Command | Purpose |
|---|---|---|
dev:cf | wrangler pages dev out --compatibility-date=2025-10-30 --compatibility-flags=nodejs_compat --d1=DB | Local emulation of the Cloudflare Pages environment. |
build:cf | npm run build | Standard build command aliased for Cloudflare compatibility. |
cf:adapt | npx @cloudflare/next-on-pages@latest | Adapts the Next.js build for Cloudflare Workers/Pages. |
Sources: package.json:51-55, scripts/fix-package-json-conflicts.sh:63
Snapshot and Recovery System
The repository includes a robust snapshot mechanism to capture the state of the Cloudflare Pages project. This ensures that project metadata, custom domains, and deployment records are backed up for recovery and auditing purposes.
Snapshot Components
The cf_pages_snapshot.sh script interacts with the Cloudflare API to generate three primary JSON artifacts stored in snapshots/cloudflare/:
- Project Metadata: Captures build settings, production branch info, and environment variable names (redacting values for security).
- Domain Config: Stores custom domain names and their validation status.
- Deployment Records: Fetches the latest 3 deployment IDs, source commit SHAs, and status.
Sources: scripts/cf_pages_snapshot.sh:110-125, snapshots/cloudflare/README.md:8-14
The snapshot process runs daily via GitHub Actions or on-demand via workflow_dispatch.
Sources: scripts/cf_pages_snapshot.sh:37-41, snapshots/cloudflare/README.md:46-48
Deployment Management and Operations
The project provides specialized scripts to review, promote, and troubleshoot Cloudflare builds.
Build Review
The review-cloudflare-builds.sh script analyzes deployment logs from the last 72 hours. It categorizes builds as Successful, Failed, Canceled, or In Progress and provides recommendations for rerunning specific commits or rolling back.
Sources: scripts/review-cloudflare-builds.sh:10-14, scripts/review-cloudflare-builds.sh:140-165
Deployment Promotion (Rollback)
Promotion of specific deployments is handled via promote-cloudflare-deployment.sh. This script identifies a deployment ID based on a target Git commit SHA and uses the Cloudflare "restore" API endpoint to activate that specific version.
Sources: scripts/promote-cloudflare-deployment.sh:25-30, scripts/promote-cloudflare-deployment.sh:42-45
Security and Governance
Deployment security is maintained through environment variable redaction and strict authentication requirements for API interactions.
- API Authentication: Scripts require
CLOUDFLARE_API_TOKEN,CF_ACCOUNT_ID, andCF_PAGES_PROJECTenvironment variables. - Data Protection: Snapshot files are safe to commit to the repository because they explicitly redact environment variable values and do not store API tokens.
- CI Gates: The repository enforces "safety gates," such as ZIP artifact blocking and documentation header checks, to prevent non-compliant code from reaching deployment.
Sources: scripts/cf_pages_snapshot.sh:15-27, snapshots/cloudflare/README.md:38-42, README.md:61-63
Conclusion
Cloudflare Pages Deployment for the LGFC project is a highly automated system that prioritizes reproducible builds and configuration visibility. By utilizing a combination of Next.js static exports, Cloudflare API-driven snapshots, and specialized management scripts, the project ensures high availability and rapid recovery capabilities for the public website and authenticated FanClub areas.