Automating Eleventy deployments with Cloudflare Pages

This diagnostic guide details the exact configuration required to establish automated Production-Ready Deployment & CI/CD Workflows for Eleventy (11ty) on Cloudflare Pages. We focus on build pipeline optimization, secure environment variable mapping, and deterministic cache invalidation. The following procedures eliminate deployment friction and ensure reproducible static site generation.

Repository Connection & Build Configuration

Connect your GitHub or GitLab repository directly through the Cloudflare Pages dashboard. Navigate to Workers & Pages > Create a project > Connect to Git. Select the target repository containing your 11ty source code.

Configure the build settings to match Eleventy's default output structure. Set the build command to npm run build. Define the output directory as _site. Cloudflare Pages automatically detects package.json and executes npm ci before running your build script.

Specify the Node.js runtime version explicitly. Eleventy v3+ requires Node.js 18 or higher. Without this specification, the platform defaults to an older LTS release. Set the version under Settings > Build & Deploy > Node.js version.

Optimized Build Script

Standard verbose logging can trigger CI/CD timeout thresholds. Suppress non-essential output and enforce production environment flags directly in your package.json.

{
 "scripts": {
 "build": "ELEVENTY_ENV=production npx @11ty/eleventy --quiet"
 }
}

This configuration sets the environment variable, disables debug output, and triggers the standard compilation pipeline. It ensures predictable execution times across automated pipelines.

Environment Variables & Secret Injection

Cloudflare Pages injects environment variables at build time. These values must align with Eleventy's process.env expectations. Never commit .env files to version control.

Access the dashboard and navigate to Settings > Environment Variables > Add Variable. Input your key-value pairs and select the appropriate deployment environment. Variables are automatically scoped to the selected branch or environment.

Eleventy reads these values during the configuration phase. Reference them directly in eleventy.config.js or global data files using process.env.YOUR_VARIABLE_NAME. Map injected values to your configuration layer if your project requires a specific prefix.

Validate variable injection by adding a temporary console.log(process.env.YOUR_VARIABLE_NAME) to your build script. Remove this diagnostic line before merging to production.

Edge Caching & Cache Invalidation

Cloudflare Pages automatically caches static assets at the edge. Proper cache control headers prevent stale content delivery while maximizing bandwidth efficiency. Implement a _headers file in your _site/ directory, or configure Eleventy to copy it during the build process.

Separate long-term caching for immutable assets from short-term caching for HTML documents. This strategy guarantees immediate content updates without forcing users to bypass cache for unchanged resources.

/assets/*
 Cache-Control: public, max-age=31536000, immutable
/*.html
 Cache-Control: public, max-age=0, must-revalidate

The configuration above applies aggressive caching to versioned assets while forcing revalidation on HTML files. For advanced routing and cache purge automation, refer to the Cloudflare Pages Edge Caching Setup documentation.

Trigger automated cache purges upon successful deployment. Use the Cloudflare API or a post-deployment webhook to execute a targeted purge. This ensures edge nodes fetch the latest _site/ artifacts immediately after the build completes.

Common Pitfalls & Diagnostics

Build fails due to missing Node.js version specification Cloudflare Pages defaults to an older Node.js runtime. Eleventy v3+ requires Node.js 18+. Resolve this by adding a .nvmrc file to your repository root containing 18 or 20. Alternatively, configure the version directly in the Pages dashboard under Build & Deploy settings.

Environment variables not accessible in 11ty templates Variables injected by Cloudflare are available only during the Node.js build process. Eleventy does not automatically pass them to template contexts. Access them exclusively in eleventy.config.js, data files, or custom plugins using process.env. Pass resolved values to the template context via eleventy.addGlobalData() if required.

Missing dependencies during build Cloudflare executes npm ci by default, which strictly installs dependencies and devDependencies from package-lock.json. If your build fails with a Module not found error, verify that all required packages are listed correctly. Run npm install locally to regenerate the lockfile before pushing.

Frequently Asked Questions

Why does my Eleventy build fail with 'Module not found' on Cloudflare Pages? The platform runs npm ci by default, which strictly adheres to package-lock.json. Missing devDependencies or an outdated lockfile cause resolution failures. Ensure all build-time dependencies are committed, and run npm install locally to synchronize the lockfile before deployment.

How do I trigger a cache purge after an automated 11ty deployment? Use the Cloudflare API or a GitHub Actions workflow to send a POST request to /zones/{zone_id}/purge_cache. Include {"purge_everything": true} or specify exact URLs. Attach this step to a deployment success webhook to guarantee edge nodes refresh immediately.

Can I use Cloudflare Pages Functions with Eleventy? Yes. Place your serverless functions in a functions/ directory at the repository root. Cloudflare Pages deploys these alongside the _site/ directory. Functions operate independently of the static generation pipeline and only intercept requests matching their defined routes.