Build Process and Optimization

**Referenced Files in This Document** - [.eleventy.js](file://.eleventy.js) - [package.json](file://package.json) - [netlify.toml](file://netlify.toml) - [cloudflare-pages.toml](file://cloudflare-pages.toml) - [worker.js](file://worker.js) - [src/assets/css/main.css](file://src/assets/css/main.css) - [src/assets/js/main.js](file://src/assets/js/main.js) - [src/assets/js/modules/search-functionality.js](file://src/assets/js/modules/search-functionality.js) - [src/_data/site.json](file://src/_data/site.json) - [src/_data/polling.js](file://src/_data/polling.js) - [src/content/knowledge/knowledge.11tydata.js](file://src/content/knowledge/knowledge.11tydata.js) - [src/content/cases/cases.11tydata.json](file://src/content/cases/cases.11tydata.json) - [.eleventyignore](file://.eleventyignore) - [tina/config.ts](file://tina/config.ts)

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 the complete build process from source to deployed assets, focusing on the Eleventy configuration, asset pipeline, optimization strategies, and search indexing. It also covers development versus production differences, environment-specific optimizations, practical build commands, and guidance for performance tuning and memory usage.

Project Structure

The project is organized around Eleventy’s conventional directories and a rich set of front-end assets:

  • Source content and templates under src
  • Global data under src/_data
  • Layouts and macros under src/_includes
  • Styles and scripts under src/assets
  • Markdown content under src/content and src/legal, src/services, etc.
  • Deployment configurations for Netlify and Cloudflare Workers
  • Search integration via Pagefind
graph TB
A["Eleventy Config<br/>.eleventy.js"] --> B["Input Dir<br/>src"]
B --> C["Templates & Pages<br/>Nunjucks, Markdown, HTML"]
B --> D["Includes & Layouts<br/>_includes"]
B --> E["Global Data<br/>_data/*.json, *.js"]
B --> F["Assets<br/>css, js, images, videos"]
C --> G["_site output"]
D --> G
E --> G
F --> G
G --> H["Static Hosting / CDN"]
H --> I["Cloudflare Worker<br/>worker.js"]

Diagram sources

  • [.eleventy.js:267-283](file://.eleventy.js#L267-L283)
  • [netlify.toml:1-4](file://netlify.toml#L1-L4)

Section sources

  • [.eleventy.js:267-283](file://.eleventy.js#L267-L283)
  • [netlify.toml:1-4](file://netlify.toml#L1-L4)

Core Components

  • Eleventy configuration defines input/output directories, template formats, passthrough copy, transforms, and environment-specific behavior.
  • Asset pipeline: CSS is composed from modular imports; JavaScript is bundled via module imports and executed at runtime.
  • Passthrough copy ensures static assets and admin assets are emitted to the output directory unchanged.
  • Pagefind search indexing runs post-build to produce a client-side search index.
  • Netlify and Cloudflare Workers configurations control build commands, environment variables, redirects, and caching headers.

Section sources

  • [.eleventy.js:1-283](file://.eleventy.js#L1-L283)
  • [package.json:5-12](file://package.json#L5-L12)
  • [netlify.toml:1-26](file://netlify.toml#L1-L26)
  • [cloudflare-pages.toml:1-17](file://cloudflare-pages.toml#L1-L17)

Architecture Overview

The build pipeline integrates Eleventy templating, static asset emission, and search indexing. Production builds enable HTML minification and Pagefind indexing. Cloudflare Workers handle member authentication and API routes, while the static assets are served via Workers’ Assets.

sequenceDiagram
participant Dev as "Developer"
participant NPM as "npm scripts<br/>package.json"
participant E as "Eleventy<br/>.eleventy.js"
participant PF as "Pagefind CLI"
participant Out as "_site"
participant CF as "Cloudflare Worker<br/>worker.js"
Dev->>NPM : npm run build
NPM->>E : eleventy
E-->>Out : Rendered HTML/CSS/JS
NPM->>PF : pagefind --site _site
PF-->>Out : pagefind index files
Out-->>CF : Static assets served via ASSETS

Diagram sources

  • [package.json:6-6](file://package.json#L6-L6)
  • [.eleventy.js:241-261](file://.eleventy.js#L241-L261)
  • [worker.js:318-320](file://worker.js#L318-L320)

Detailed Component Analysis

Eleventy Build Configuration

  • Input/output directories: input is src, output is _site, includes and layouts are under _includes.
  • Template formats: Nunjucks, Markdown, HTML; engines configured accordingly.
  • Passthrough copy: copies src/assets, src/admin, and specific files like robots.txt and favicons.
  • Watch targets: monitors CSS, JS, and _data for rebuilds during development.
  • Shortcodes and filters: reusable helpers for templating and data manipulation.
  • Collections: curated content sets for news, cases, newsletters, team, services, and knowledge.
  • Transforms:
    • Obsidian-style wiki links and callouts processing.
    • HTML minification in production mode using html-minifier-terser.
  • Environment-specific behavior: production minification gated on NODE_ENV.
flowchart TD
Start(["Eleventy Init"]) --> DirCfg["Configure dirs<br/>input/output/includes/data/layouts"]
DirCfg --> Formats["Set template formats<br/>njk, md, html"]
Formats --> Copy["Add passthrough copy<br/>assets, admin, robots, favicons"]
Copy --> Watch["Add watch targets<br/>css, js, _data"]
Watch --> Shortcodes["Register shortcodes<br/>year, currentDate"]
Shortcodes --> Filters["Register filters<br/>limit, skip, dateFormat, slug, truncate,<br/>nl2br, firstParagraph, dump/log,<br/>split, readingTime, sortBy, where, unique"]
Filters --> Collections["Define collections<br/>news, cases, newsletters, teamMembers,<br/>featuredNews, services, knowledge"]
Collections --> Transforms["Register transforms<br/>obsidianSyntax, htmlmin (prod)"]
Transforms --> End(["Ready"])

Diagram sources

  • [.eleventy.js:267-283](file://.eleventy.js#L267-L283)
  • [.eleventy.js:7-14](file://.eleventy.js#L7-L14)
  • [.eleventy.js:19-21](file://.eleventy.js#L19-L21)
  • [.eleventy.js:27-40](file://.eleventy.js#L27-L40)
  • [.eleventy.js:46-164](file://.eleventy.js#L46-L164)
  • [.eleventy.js:170-210](file://.eleventy.js#L170-L210)
  • [.eleventy.js:217-239](file://.eleventy.js#L217-L239)
  • [.eleventy.js:242-261](file://.eleventy.js#L242-L261)

Section sources

  • [.eleventy.js:1-283](file://.eleventy.js#L1-L283)

Asset Pipeline: CSS Compilation and JavaScript Bundling

  • CSS: A single main.css composes modular styles via @import statements. There is no separate build step for CSS in the Eleventy config; assets are passed through as-is.
  • JavaScript: main.js imports feature modules and initializes them on DOMContentLoaded. No bundling step is defined in the Eleventy config; runtime imports are used.
graph LR
M["src/assets/css/main.css"] --> P["Passthrough Copy<br/>.eleventy.js"]
P --> O["_site/assets/css/main.css"]
J["src/assets/js/main.js"] --> R["Runtime imports<br/>modules/*.js"]
R --> O2["_site/assets/js/main.js"]

Diagram sources

  • [.eleventy.js:7-7](file://.eleventy.js#L7-L7)
  • [src/assets/css/main.css:1-47](file://src/assets/css/main.css#L1-L47)
  • [src/assets/js/main.js:1-37](file://src/assets/js/main.js#L1-L37)

Section sources

  • [.eleventy.js:7-7](file://.eleventy.js#L7-L7)
  • [src/assets/css/main.css:1-47](file://src/assets/css/main.css#L1-L47)
  • [src/assets/js/main.js:1-37](file://src/assets/js/main.js#L1-L37)

Image Optimization with Sharp

  • The project includes Sharp as a dependency, but there is no explicit Eleventy plugin configuration for image processing in the Eleventy config. Images are currently passed through via passthrough copy.
  • Recommendation: Integrate an Eleventy image plugin (e.g., @11ty/eleventy-img) to leverage Sharp for responsive images, formats, and compression.

Section sources

  • [package.json:19-19](file://package.json#L19-L19)
  • [.eleventy.js:7-14](file://.eleventy.js#L7-L14)

Static Asset Copying

  • Passthrough copy directives ensure src/assets, src/admin, and specific files (robots.txt, favicon.*) are emitted to the output directory without modification.
  • This preserves asset URLs and enables CDN distribution.

Section sources

  • [.eleventy.js:7-14](file://.eleventy.js#L7-L14)

Pagefind Search Indexing

  • Post-build indexing: The npm build script invokes pagefind against _site and writes index files into _site/pagefind.
  • Client-side integration: The search module lazily loads /pagefind/pagefind.js, configures excerpt length, and renders results with category icons.
sequenceDiagram
participant Build as "npm run build"
participant Eleventy as "Eleventy"
participant Pagefind as "Pagefind CLI"
participant Site as "_site"
participant JS as "search-functionality.js"
Build->>Eleventy : eleventy
Eleventy-->>Site : rendered HTML
Build->>Pagefind : pagefind --site _site
Pagefind-->>Site : pagefind index files
JS->>Site : import("/pagefind/pagefind.js")
JS->>JS : configure options, render results

Diagram sources

  • [package.json:6-6](file://package.json#L6-L6)
  • [src/assets/js/modules/search-functionality.js:18-28](file://src/assets/js/modules/search-functionality.js#L18-L28)

Section sources

  • [package.json:6-6](file://package.json#L6-L6)
  • [src/assets/js/modules/search-functionality.js:1-128](file://src/assets/js/modules/search-functionality.js#L1-L128)

Development vs Production Differences

  • Development: Eleventy serves with hot reload; passthrough copy enabled; no HTML minification.
  • Production: NODE_ENV is used to enable html-minifier-terser transform; Pagefind indexing is part of the build.
flowchart TD
D["Development"] --> S["eleventy --serve"]
D --> Pcopy["Passthrough copy enabled"]
D --> NoMin["No HTML minification"]
P["Production"] --> Env["NODE_ENV=production"]
Env --> Min["Enable html-minifier-terser transform"]
Env --> PF["Run Pagefind indexing"]

Diagram sources

  • [.eleventy.js:242-261](file://.eleventy.js#L242-L261)
  • [package.json:6-6](file://package.json#L6-L6)

Section sources

  • [.eleventy.js:242-261](file://.eleventy.js#L242-L261)
  • [package.json:6-6](file://package.json#L6-L6)

Optimization Strategies

  • HTML minification: Enabled in production via html-minifier-terser with attributes like collapseWhitespace and removeComments.
  • Asset caching: Netlify headers set Cache-Control for /assets/* to immutable caching.
  • Search performance: Pagefind index reduces client-side search overhead; lazy-loading of pagefind.js avoids initial bundle cost.
  • Observations: CSS and JS are not minified or transpiled in the Eleventy config; consider adding plugins for modernization and compression if needed.

Section sources

  • [.eleventy.js:242-261](file://.eleventy.js#L242-L261)
  • [netlify.toml:22-25](file://netlify.toml#L22-L25)

Content Collections and Permalinks

  • Collections: Curated lists for news, cases, newsletters, team, services, and knowledge.
  • Permalinks: Some collections disable permalinks globally; others compute custom permalinks (e.g., knowledge base).

Section sources

  • [.eleventy.js:170-210](file://.eleventy.js#L170-L210)
  • [src/content/knowledge/knowledge.11tydata.js:4-7](file://src/content/knowledge/knowledge.11tydata.js#L4-L7)
  • [src/content/cases/cases.11tydata.json:1-2](file://src/content/cases/cases.11tydata.json#L1-L2)

Data Layer and Global Site Info

  • Global site metadata is provided via src/_data/site.json.
  • Dynamic polling data is exposed via src/_data/polling.js.

Section sources

  • [src/_data/site.json:1-20](file://src/_data/site.json#L1-L20)
  • [src/_data/polling.js:1-17](file://src/_data/polling.js#L1-L17)

CMS Integration (Tina)

  • Tina configuration defines content collections and media roots, building admin assets into the admin folder and referencing src as publicFolder.
  • The project includes scripts to build and develop the CMS alongside Eleventy.

Section sources

  • [tina/config.ts:1-331](file://tina/config.ts#L1-L331)
  • [package.json:8-9](file://package.json#L8-L9)

Deployment and Workers

  • Netlify: Build command runs npm run build; publishes _site; applies security headers and long-lived caching for assets.
  • Cloudflare: Historical Pages config remains for reference; current deployment uses Cloudflare Workers with Wrangler, serving static assets via ASSETS and handling auth/API routes in worker.js.
  • Worker responsibilities: Member portal auth, magic link issuance, session cookies, CORS handling for CMS OAuth, and live polling data endpoint.
graph TB
subgraph "Deployment"
N["Netlify<br/>netlify.toml"] --> Pub["_site publish"]
W["Wrangler<br/>cloudflare-pages.toml (deprecated)"] --> Pub
CF["Cloudflare Worker<br/>worker.js"] --> Pub
end

Diagram sources

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

Section sources

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

Dependency Analysis

  • Eleventy core and RSS plugin are declared.
  • Pagefind is used for search indexing.
  • Sharp is present for potential image processing.
  • Wrangler is used for deploying to Cloudflare Workers.
graph LR
Pkg["package.json"] --> E["@11ty/eleventy"]
Pkg --> RSS["@11ty/eleventy-plugin-rss"]
Pkg --> PF["pagefind"]
Pkg --> SH["sharp"]
Pkg --> WR["wrangler"]

Diagram sources

  • [package.json:14-30](file://package.json#L14-L30)

Section sources

  • [package.json:14-30](file://package.json#L14-L30)

Performance Considerations

  • Build commands:
    • Development: eleventy --serve
    • Production: eleventy && pagefind --site _site --output-path _site/pagefind
  • Memory and CPU:
    • Sharp is used for image processing; ensure adequate memory for heavy images.
    • Pagefind indexing is performed post-build; consider running it in CI with sufficient resources.
  • Asset delivery:
    • Long-term caching for /assets/* via Cache-Control headers.
    • Consider enabling compression (gzip/brotli) at the CDN or server level if not already handled.
  • JavaScript:
    • Runtime imports avoid bundling; consider a bundler if bundle size or load time becomes a concern.
  • CSS:
    • No minification in Eleventy; consider adding a CSS minifier if needed.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

  • Build fails due to missing environment:
    • Ensure NODE_ENV is set appropriately for production minification.
  • Pagefind not available:
    • Confirm pagefind binary is installed and the build script runs after Eleventy completes.
  • Search UI not working:
    • Verify /pagefind/pagefind.js is present in _site and the search module attempts to import it.
  • Asset not found:
    • Confirm passthrough copy includes the asset path and filenames match expectations.
  • Netlify build errors:
    • Check NODE_VERSION and build command alignment with package.json scripts.
  • Worker auth issues:
    • Ensure required secrets and KV namespaces are configured; verify session cookie handling and token TTLs.

Section sources

  • [.eleventy.js:242-261](file://.eleventy.js#L242-L261)
  • [package.json:6-6](file://package.json#L6-L6)
  • [src/assets/js/modules/search-functionality.js:18-28](file://src/assets/js/modules/search-functionality.js#L18-L28)
  • [.eleventy.js:7-14](file://.eleventy.js#L7-L14)
  • [netlify.toml:5-6](file://netlify.toml#L5-L6)
  • [worker.js:80-91](file://worker.js#L80-L91)

Conclusion

The build pipeline leverages Eleventy for templating and static generation, Pagefind for client-side search, and Cloudflare Workers for authentication and APIs. Passthrough copy preserves assets for CDN delivery, while production builds enable HTML minification and search indexing. For further optimization, consider integrating an Eleventy image plugin for Sharp-based transformations, adding a bundler for JS/CSS, and enabling compression and advanced caching strategies.

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

Appendices

Practical Build Commands

  • Development: eleventy --serve
  • Production: eleventy && pagefind --site _site --output-path _site/pagefind
  • Clean: rm -rf _site
  • Deploy preview: npm run build && wrangler dev
  • Deploy: npm run build && wrangler deploy

Section sources

  • [package.json:5-12](file://package.json#L5-L12)

Environment-Specific Optimizations

  • Production minification: html-minifier-terser transform activated when NODE_ENV equals production.
  • Asset caching: Cache-Control headers for /assets/* set to immutable.
  • Search indexing: Pagefind index generated during production builds.

Section sources

  • [.eleventy.js:242-261](file://.eleventy.js#L242-L261)
  • [netlify.toml:22-25](file://netlify.toml#L22-L25)
  • [package.json:6-6](file://package.json#L6-L6)

Asset Versioning, CDN, and Progressive Loading

  • Versioning: Not implemented in the current pipeline; consider fingerprinting or cache-busting strategies.
  • CDN: Netlify configuration publishes _site; assets are served with long-term caching.
  • Progressive loading: Pagefind is lazy-loaded; consider deferring non-critical scripts and using native lazy loading for images.

Section sources

  • [netlify.toml:1-4](file://netlify.toml#L1-L4)
  • [src/assets/js/modules/search-functionality.js:18-28](file://src/assets/js/modules/search-functionality.js#L18-L28)