Production Optimizations

**Referenced Files in This Document** - [package.json](file://package.json) - [.eleventy.js](file://.eleventy.js) - [netlify.toml](file://netlify.toml) - [cloudflare-pages.toml](file://cloudflare-pages.toml) - [worker.js](file://worker.js) - [wrangler.jsonc](file://wrangler.jsonc) - [README.md](file://README.md)

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion
  10. Appendices

Introduction

This document explains production-specific build optimizations implemented in the project. It focuses on:

  • Conditional transform loading controlled by the NODE_ENV environment variable
  • html-minifier-terser configuration and its impact on bundle size and performance
  • Asset optimization strategies and cache headers
  • Production build best practices
  • Examples of custom production transforms
  • Performance monitoring and debugging production-only features
  • Build-time optimization techniques and deployment considerations

Project Structure

The project is a static site generated by Eleventy and served via Cloudflare Workers. Production optimizations are primarily implemented in the Eleventy configuration and the Worker runtime.

graph TB
subgraph "Build"
ELE[".eleventy.js<br/>Production transforms"]
PKG["package.json<br/>Scripts and deps"]
end
subgraph "Runtime"
WRK["worker.js<br/>Auth, APIs, caching"]
WRC["wrangler.jsonc<br/>Workers config"]
end
subgraph "Hosting"
NET["netlify.toml<br/>Headers and redirects"]
CFP["cloudflare-pages.toml<br/>Legacy Pages config"]
end
SRC["Source content and templates"]
SRC --> ELE
PKG --> ELE
ELE --> |"Generates"| ASSETS["_site/<assets>"]
ASSETS --> WRK
WRK --> |"Static assets binding"| ASSETS
WRK --> NET
WRK --> CFP
WRC --> WRK

Diagram sources

  • [.eleventy.js:241-261](file://.eleventy.js#L241-L261)
  • [package.json:5-12](file://package.json#L5-L12)
  • [worker.js:301-320](file://worker.js#L301-L320)
  • [wrangler.jsonc:1-35](file://wrangler.jsonc#L1-L35)
  • [netlify.toml:14-25](file://netlify.toml#L14-L25)
  • [cloudflare-pages.toml:1-17](file://cloudflare-pages.toml#L1-L17)

Section sources

  • [.eleventy.js:267-283](file://.eleventy.js#L267-L283)
  • [package.json:5-12](file://package.json#L5-L12)
  • [README.md:556-587](file://README.md#L556-L587)

Core Components

  • Eleventy production transforms controlled by NODE_ENV
  • html-minifier-terser configuration applied only in production
  • Cloudflare Worker routing, caching, and observability
  • Static asset headers for security and long-term caching
  • Legacy Pages configuration retained for reference

Section sources

  • [.eleventy.js:241-261](file://.eleventy.js#L241-L261)
  • [worker.js:233-276](file://worker.js#L233-L276)
  • [netlify.toml:14-25](file://netlify.toml#L14-L25)
  • [cloudflare-pages.toml:1-17](file://cloudflare-pages.toml#L1-L17)

Architecture Overview

Production traffic flows through the Worker, which serves static assets and exposes protected routes and APIs. Eleventy’s production transform pipeline reduces HTML size and improves load performance.

sequenceDiagram
participant Browser as "Browser"
participant Worker as "Cloudflare Worker"
participant Assets as "Static Assets (_site)"
participant Eleventy as "Eleventy Build"
Browser->>Worker : Request /
Worker->>Assets : Fetch static HTML/CSS/JS
Assets-->>Worker : HTML/CSS/JS
Worker-->>Browser : Response with headers and cached assets
Note over Eleventy,Worker : During build, NODE_ENV=production enables transforms

Diagram sources

  • [.eleventy.js:241-261](file://.eleventy.js#L241-L261)
  • [worker.js:301-320](file://worker.js#L301-L320)
  • [netlify.toml:22-25](file://netlify.toml#L22-L25)

Detailed Component Analysis

Conditional Transform Loading Based on NODE_ENV

  • The htmlmin transform is registered only when NODE_ENV equals "production".
  • This ensures minification runs only in production builds, avoiding unnecessary overhead in development.

Implementation highlights:

  • Guarded registration inside an environment check
  • Applies to .html outputs only
  • Uses html-minifier-terser for aggressive whitespace and comment removal

Impact:

  • Reduced HTML payload sizes
  • Faster network transfer and parse times in production

Section sources

  • [.eleventy.js:241-261](file://.eleventy.js#L241-L261)
  • [README.md:634-635](file://README.md#L634-L635)

html-minifier-terser Configuration and Options

The production transform applies the following options:

  • collapseBooleanAttributes: true
  • collapseWhitespace: true
  • decodeEntities: true
  • includeAutoGeneratedTags: false
  • removeComments: true
  • removeEmptyAttributes: true
  • removeRedundantAttributes: true
  • sortAttributes: true
  • sortClassName: true
  • useShortDoctype: true

Effects:

  • Removes redundant whitespace and comments
  • Sorts attributes and class names for deterministic output
  • Strips auto-generated tags and shortens DOCTYPE
  • Improves compression ratios and parsing performance

Recommendations:

  • Keep this transform gated by NODE_ENV to avoid impacting dev builds
  • Monitor HTML size deltas post-deploy to validate savings

Section sources

  • [.eleventy.js:244-257](file://.eleventy.js#L244-L257)

Asset Optimization Strategies and Cache Headers

  • Security headers apply to all routes:
    • X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy
  • Long-term caching for static assets under /assets/*:
    • Cache-Control: public, max-age=31536000, immutable
  • API caching for polling data:
    • Cache-Control: public, max-age=300, stale-while-revalidate=3600

Benefits:

  • Stronger security posture
  • Reduced bandwidth and latency for static assets
  • Controlled caching for dynamic endpoints

Section sources

  • [netlify.toml:14-25](file://netlify.toml#L14-L25)
  • [worker.js:233-238](file://worker.js#L233-L238)

Production Build Best Practices

  • Use NODE_ENV=production to enable transforms
  • Run the build script to generate _site and Pagefind assets
  • Deploy via Wrangler to Cloudflare Workers

Evidence:

  • Build script invokes Eleventy and Pagefind
  • Wrangler configuration binds _site as static assets
  • README documents the production build and deploy flow

Section sources

  • [package.json:6](file://package.json#L6)
  • [README.md:556-587](file://README.md#L556-L587)
  • [wrangler.jsonc:9-12](file://wrangler.jsonc#L9-L12)

Custom Production Transforms

  • obsidianSyntax transform converts Obsidian wiki links and callouts to HTML during build
  • htmlmin transform minifies HTML in production

These transforms are applied during Eleventy’s transform pipeline and only in production.

Section sources

  • [.eleventy.js:216-239](file://.eleventy.js#L216-L239)
  • [.eleventy.js:241-261](file://.eleventy.js#L241-L261)

Performance Monitoring and Debugging Production-Only Features

  • Worker observability is enabled in wrangler.jsonc
  • Worker routes expose health and metrics indirectly via logs and response headers
  • For debugging, temporarily disable production transforms or set NODE_ENV to development for local builds

Section sources

  • [wrangler.jsonc:6-8](file://wrangler.jsonc#L6-L8)
  • [.eleventy.js:241-261](file://.eleventy.js#L241-L261)

Build-Time Optimization Techniques

  • Eleventy passthrough copy for assets and admin
  • Watch targets for efficient incremental builds
  • Pagefind indexing included in the build script

Section sources

  • [.eleventy.js:7-22](file://.eleventy.js#L7-L22)
  • [package.json:6](file://package.json#L6)

Deployment Considerations

  • Cloudflare Workers serves static assets and handles auth/API routes
  • Legacy Cloudflare Pages configuration retained for reference
  • Netlify configuration defines headers and redirects

Section sources

  • [worker.js:301-320](file://worker.js#L301-L320)
  • [cloudflare-pages.toml:1-17](file://cloudflare-pages.toml#L1-L17)
  • [netlify.toml:1-25](file://netlify.toml#L1-L25)

Dependency Analysis

graph LR
ELE[".eleventy.js"]
PKG["package.json"]
MIN["html-minifier-terser"]
SHARP["sharp"]
PF["pagefind"]
WRK["worker.js"]
WRC["wrangler.jsonc"]
NET["netlify.toml"]
PKG --> ELE
ELE --> MIN
PKG --> SHARP
PKG --> PF
ELE --> |"Outputs"| ASSETS["_site"]
ASSETS --> WRK
WRC --> WRK
NET --> WRK

Diagram sources

  • [package.json:14-29](file://package.json#L14-L29)
  • [.eleventy.js:242-243](file://.eleventy.js#L242-L243)
  • [worker.js:301-320](file://worker.js#L301-L320)
  • [wrangler.jsonc:1-35](file://wrangler.jsonc#L1-L35)
  • [netlify.toml:1-25](file://netlify.toml#L1-L25)

Section sources

  • [package.json:14-29](file://package.json#L14-L29)
  • [.eleventy.js:242-243](file://.eleventy.js#L242-L243)

Performance Considerations

  • Enable production transforms only in production builds to avoid bloating development bundles
  • Use long-term caching for immutable assets to reduce repeat downloads
  • Monitor cache headers and adjust max-age/stale-while-revalidate for dynamic endpoints
  • Keep build scripts minimal and targeted to reduce CI/CD time

[No sources needed since this section provides general guidance]

Troubleshooting Guide

  • Verify NODE_ENV is set to "production" during build to activate transforms
  • Confirm html-minifier-terser is installed and required in production mode
  • Check Worker observability settings for runtime insights
  • Validate static asset headers and redirects in hosting configs

Section sources

  • [.eleventy.js:241-261](file://.eleventy.js#L241-L261)
  • [package.json:18](file://package.json#L18)
  • [wrangler.jsonc:6-8](file://wrangler.jsonc#L6-L8)
  • [netlify.toml:14-25](file://netlify.toml#L14-L25)

Conclusion

The project implements targeted production optimizations:

  • Conditional transforms controlled by NODE_ENV
  • Aggressive HTML minification via html-minifier-terser
  • Robust security headers and long-term caching for assets
  • Worker-based routing, caching, and observability
  • Clear build and deployment procedures

These practices collectively improve performance, security, and reliability in production.

[No sources needed since this section summarizes without analyzing specific files]

Appendices

  • Build and deploy commands are defined in package.json scripts
  • README provides detailed deployment and environment setup guidance

Section sources

  • [package.json:5-12](file://package.json#L5-L12)
  • [README.md:556-587](file://README.md#L556-L587)