11ty Bundle Dev Expert

Expert assistant for working with the 11tybundle.dev project - an Eleventy-based static site that aggregates 1,600+ blog posts from 400+ authors, organized into categories, author pages, and a searchable interface.

Project Context

11tybundle.dev is built on Eleventy and serves as a comprehensive resource for Eleventy content. The site features:

Architecture Understanding

Data Pipeline

**Flow**: GitHub JSON → bundledata.js → Nunjucks templates → Static HTML

The data source is `bundledb.json` hosted in the `bobmonsour/11tybundledb` repository. This is fetched using @11ty/eleventy-fetch with a 1-day cache.

**Data Processing** occurs in `content/_data/bundledata.js` (592 lines), which:

1. Fetches raw data from GitHub

2. Transforms into structured arrays: firehose, authorList, categoryList, siteList, releaseList, startersList

3. Enriches items with favicons, descriptions, RSS links, and social links using async filters

4. Provides data via `bundledata` global data object to templates

Critical Design Decisions

**Sequential Enrichment**: Enrichment functions use sequential `for` loops instead of `Promise.all` to avoid timeout cascades when cache is empty. Never refactor these to parallel processing.

**Map-based Lookups**: Authors and categories use `Map<name, object>` for O(1) lookups instead of O(n) array.find(). Maintain this pattern for performance.

**Pre-computed Flags**: Flags like `isYoutube` are computed once during rawFirehose creation. Don't repeat URL parsing in templates.

**Negative Caching**: Failed favicon/description/RSS fetches are cached as `null` to prevent retry storms. Respect this pattern when adding new fetch operations.

Development Workflows

Build Commands

**Full Development Build** (with search):

```bash

npm run rs # Clean build with Pagefind search indexing and live server

```

**Production Build**:

```bash

npm run build # Build site to _site/

npm run postbuild # Run Pagefind indexing

npm run deploy # Clean, build, index, deploy to Cloudflare Pages

```

**Quick Development** (without search):

```bash

npm run startns # Build and serve without cleaning cache

```

**Local Testing with Subset**:

To test with a smaller dataset, comment out the remote fetch in `bundledata.js` (lines 50-62) and uncomment the local import to use `bundledbtest2.json`.

Directory Data Cascade

**Pattern**: Use `.11tydata.js` files for directory-level configuration overrides.

When adding new sections that need different layouts or configuration, create directory data files following this pattern.

Key Technical Patterns

Pagefind Search Integration

**Setup**: Search UI is initialized in `content/_layouts/base.njk` with keyboard shortcut handler (press '/' to focus search).

**Indexing**: Runs post-build via `npx pagefind --site _site`

**Markup Requirements**:

Bundle System for Assets

CSS and JavaScript are bundled via Eleventy's `{% css %}` and `{% js %}` paired shortcodes:

External Dependencies

**@11ty/eleventy-fetch**: HTTP caching layer

**Octokit**: GitHub API access for starter repo metadata (requires `GITHUB_TOKEN` environment variable)

**Pagefind**: Client-side search indexing (runs as post-build step)

**Cloudflare Pages**: Deployment target via wrangler CLI

Coding Standards

JavaScript

CSS

Accessibility

Key File Locations

**Configuration**:

**Data & Logic**:

**Templates**:

**Assets**:

**Configuration**:

Common Pitfalls to Avoid

1. **Never use `Promise.all` for enrichment functions** - causes timeouts with empty cache. Always use sequential processing.

2. **Always await async filters in templates** - Nunjucks async filters require explicit await in template code.

3. **Don't forget `crossorigin` attribute on font preloads** - required for CORS compliance.

4. **RSS feeds need `layout: false`** - must be set via directory data file, not in front matter.

5. **Respect .gitignore for generated files** - cache files in `.cache/` and build output in `_site/` should never be committed.

6. **Don't parse URLs repeatedly** - use pre-computed flags like `isYoutube` instead of parsing in loops or templates.

7. **Honor negative caching** - if a fetch returns `null`, it means the fetch failed and is cached. Don't retry immediately.

Instructions for AI Agent

When working on this project:

1. **Before making changes**, read the relevant files to understand current implementation

2. **For data pipeline changes**, focus on `content/_data/bundledata.js` and understand the sequential processing pattern

3. **For template changes**, check both the template file and any relevant `.11tydata.js` files in the directory hierarchy

4. **For new features requiring external data**, follow the negative caching pattern for failed fetches

5. **For search-related changes**, update both the Pagefind configuration and the markup with appropriate data attributes

6. **For performance optimization**, maintain the Map-based lookup pattern and pre-computed flags approach

7. **Always test locally** with `npm run startns` for quick iteration, then `npm run rs` for full build with search before deploying

8. **For large-scale data changes**, test with the subset dataset first by modifying the import in bundledata.js

Constraints