eleventy-stack

11ty MVP Stack

Default tech stack and patterns for Eleventy-based rapid MVPs. These are opinionated defaults — deviations require explicit discussion (see architecture-decisions skill).

Core Stack

Layer	Technology	Version	Notes
Framework	Eleventy (11ty)	3.x	Static site generator
Templating	Nunjucks	—	Primary template engine
Runtime	Bun	1.1+	Package manager AND runtime (not Node)
Validation	Zod	4.x	Schema validation for data files
Client JS	Vanilla JavaScript	—	No React, no Vue, no framework
Language	JavaScript	—	ESM modules in scripts, no TypeScript in 11ty projects

Styling

Concern	Default
CSS framework	Tailwind CSS 4 via @tailwindcss/cli
Typography	@tailwindcss/typography for prose content
Theme	Shared tooling/theme.css with OKLCH @theme directive
Dark mode	Tailwind dark mode with [data-theme] selector
Build step	@tailwindcss/cli processes src/css/main.css → _site/css/main.css

Never use CSS-in-JS. Never use PostCSS as a plugin — use @tailwindcss/cli directly.

Data Architecture

11ty projects follow a strict data pipeline:

1. Human-authored data → JSON files in src/_data/ (e.g., recipes.json, products.json)
2. Validation → Zod schemas in src/schemas/ validate data on build
3. Generation → Scripts in scripts/ transform validated data into derived data files
4. Build → 11ty reads both authored and derived data, generates static HTML
5. Client runtime → Vanilla JS loads data into window.* for interactivity

The validate → generate → build pipeline

This is critical. Every data change must go through:

Edit data → bun run validate → bun run generate → bun run build

The prebuild script in package.json should run validation automatically.

Template Architecture

Directory	Purpose
src/_includes/layouts/	Page layouts (base.njk, etc.)
src/_includes/components/	Reusable template partials
src/_includes/macros/	Nunjucks macros for repetitive patterns
src/_data/	Global data files (JSON)
src/schemas/	Zod validation schemas
src/css/	Tailwind CSS entry point (imports shared theme)
src/js/	Client-side vanilla JavaScript
scripts/	Build utilities (validate, generate, transform)

Data/Format Separation

11ty enforces data/format separation by convention:

• Data (src/_data/): JSON files containing content — this is where all content lives
• Format (src/_includes/): Nunjucks layouts, components, macros — these only define presentation
• Never hardcode content in templates — always extract to _data/ files

Configuration Pattern

The .eleventy.js config should:

• Set passthrough copy for src/js, src/assets (NOT src/css — processed by Tailwind CLI)
• Set env global data (defaults to "development")
• Add custom filters (formatMinutes, json, etc. as needed)
• Set directory config: input src, output _site, includes _includes, data _data
• Default to Nunjucks for all template formats

Deployment

Default to GitHub Pages via GitHub Actions:

1. Trigger on push to main
2. Setup Bun
3. bun install → bun run validate → bun run build
4. Upload _site/ artifact
5. Deploy to GitHub Pages

Code Style (enforced)

• Data files use kebab-case slugs
• Nunjucks templates use component-style naming
• JavaScript files use camelCase functions
• Schemas mirror data file structure exactly
• No bundlers — files are copied as-is

Anti-patterns (never do these)

• Never use React or any JS framework in 11ty projects
• Never use CSS-in-JS or styled-components
• Never use PostCSS as a plugin — use @tailwindcss/cli for Tailwind builds
• Never use TypeScript in 11ty projects — plain JavaScript
• Never skip validation before build
• Never put derived data in _data/ manually — always generate via scripts
• Never use Node.js — use Bun for all scripts
• Never hardcode content in templates — always extract to _data/ files

Detailed Patterns

For complete file templates, configuration examples, and directory structures, read references/eleventy-patterns.md.