Next.js Static Export Config
Relevant source files
The following files were used as context for generating this wiki page:
The Next.js Static Export configuration in this repository is designed to facilitate the deployment of the Lou Gehrig Fan Club (LGFC) website as a static site hosted on Cloudflare Pages. This approach exports the application into a collection of static assets (HTML, CSS, JS) while offloading dynamic behavior—such as database interactions with Cloudflare D1—to Cloudflare Pages Functions.
The configuration ensures compatibility with the Cloudflare ecosystem by disabling Node.js-specific optimizations that are unavailable in the Pages environment and enforcing strict routing patterns.
Sources: next.config.ts:3-13, context.md:14-19, README.md:5-6
Core Configuration
The primary configuration is defined in next.config.ts. It leverages the export output mode, which generates an out directory containing the static version of the application.
Key Settings
| Option | Value | Description |
|---|---|---|
output | "export" | Enables the Next.js static export mode. |
trailingSlash | true | Ensures generated static routes maintain trailing slashes for consistent URL mapping. |
images.unoptimized | true | Required for Cloudflare Pages as it lacks the Node.js runtime environment for Image Optimization. |
Sources: next.config.ts:3-13
Deployment Architecture
The system utilizes a hybrid approach where the frontend is fully static, and the backend logic is handled by Cloudflare's edge infrastructure.
This diagram illustrates the flow from static build to edge deployment using Cloudflare Pages.
Sources: next.config.ts:4-13, context.md:14-19, package.json:52-54
Build and Pipeline Logic
The build process is managed through npm scripts defined in package.json. It involves cleaning previous builds, generating the static site, and executing post-build operations like copying routing configurations.
Build Scripts Breakdown
build: Runsnext buildand executespostbuild.postbuild: Copies_routes.jsonto theoutdirectory to define Cloudflare-specific routing rules for Pages Functions.dev:cf: Useswranglerto simulate the Cloudflare Pages environment locally, enabling D1 database bindings and Node.js compatibility flags.
Sources: package.json:52-56
Dependency Management
The project utilizes specific adapters to bridge Next.js with the Cloudflare runtime. For instance, the scripts/fix-package-json-conflicts.sh script enforces the presence of the @cloudflare/next-on-pages adapter to generate worker scripts for edge compatibility.
Sources: scripts/fix-package-json-conflicts.sh:63-68
Infrastructure and Snapshots
Deployment settings and metadata for the Cloudflare Pages environment are periodically captured in JSON snapshots. This includes project configuration, build settings, and custom domains, allowing for reproducible recovery.
The sequence of metadata capture for maintaining infrastructure-as-code state.
Sources: scripts/cf_pages_snapshot.sh:56-105
Conclusion
The Next.js Static Export Config represents a deliberate architectural choice to maximize performance and reduce hosting complexity by treating the Next.js App Router as a static generator. By integrating post-build scripts and Cloudflare-specific configurations (like unoptimized images and trailingSlash), the project maintains a robust pipeline that bridges static frontend delivery with dynamic edge-based data services.