Add initial CLAUDE.md

Author: andrewiggins

CLAUDE.md

@@ -0,0 +1,113 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This project compares implementations of webpages with increasing complexity across multiple JavaScript frameworks (React, Preact, Vue, Svelte, Solid, lit-html). Each framework implements the same set of applications (e.g., "hello-world", "7GUIs-counter", "7GUIs-flight-booker") to enable direct comparison of bundle sizes, code patterns, and complexity.
+
+## Project Structure
+
+- **`frameworks/`**: Contains separate workspace packages for each framework
+  - Each framework folder has `src/` with app implementations (one folder per app)
+  - Each framework has its own `rollup.config.js` and build configuration
+  - Uses `bundleHelpers.js` to generate Rollup configs that create both development and minified production builds
+
+- **`scripts/`**: Build tooling and website generation
+  - `build.js`: Main build script - compiles frameworks, generates static site with bundle analysis
+  - `dev.js`: Development server with hot reload watching for framework changes
+  - `data.js`: Collects bundle sizes (raw, minified, gzip, brotli) and source code for comparison
+  - `components/`: Preact components for the comparison website UI
+  - `routes/`: Page generators for intro, summary, and app comparison views
+  - `bundles/`: Shared CSS/JS bundles for the static site
+
+- **`lib/`**: Shared utility code used across all framework implementations (e.g., CRUD logic, date utilities)
+
+- **`tests/`**: Jest + Puppeteer end-to-end tests organized by app and framework
+
+- **`dist/`**: Build output (not committed to git)
+  - `frameworks/[framework-name]/[app-name]/`: Compiled app bundles with stats
+  - Static HTML pages showing comparisons
+
+## Common Commands
+
+### Development
+```bash
+npm start                    # Start dev server with no watchers
+npm run dev [framework...]   # Start dev server and watch specific framework(s)
+npm run dev all             # Watch all frameworks and rebuild site on changes
+npm run dev scripts         # Only watch and rebuild site assets
+npm run dev react preact    # Watch only React and Preact frameworks
+```
+
+### Building
+```bash
+npm run build               # Build all frameworks and generate comparison site
+npm run build [framework]   # Build specific framework(s) by package name prefix
+npm run serve              # Serve built site from dist/ directory
+```
+
+### Testing and Type Checking
+```bash
+npm test                   # Run all Puppeteer tests (requires built site)
+npm run test:debug        # Run tests with Puppeteer debug output
+npm run tsc               # Type check all workspaces with TypeScript
+```
+
+### Code Quality
+```bash
+npm run format            # Format all code with Prettier
+npm run lint-staged       # Run pre-commit hooks manually
+```
+
+## Build System Architecture
+
+The build system has two main phases:
+
+1. **Framework Builds** (parallel per framework):
+   - Each framework workspace has a Rollup config generated by `bundleHelpers.js`
+   - For each app in `src/`, creates two bundles: unminified (`.js`) and minified (`.min.js`)
+   - Outputs to `dist/frameworks/[framework]/[app]/` with bundle visualization HTML
+   - The `generateConfigs()` helper automatically discovers app folders and creates configs
+
+2. **Site Generation** (in `scripts/build.js`):
+   - Scans all framework build outputs and extracts bundle sizes (raw, gzip, brotli)
+   - Compiles Preact components for the comparison UI
+   - Generates static HTML pages:
+     - Intro page (landing)
+     - Summary view (tables comparing all frameworks)
+     - Individual app views (side-by-side source and bundle comparisons)
+   - Builds and minifies shared CSS/JS bundles
+   - Outputs `sizes.json` with all bundle size data
+
+## Key Implementation Details
+
+- **Monorepo Structure**: Uses npm workspaces - root package.json defines workspaces for `frameworks/*`, `scripts/`, and `tests/`
+
+- **Framework Independence**: Each framework workspace is self-contained with its own dependencies and build config
+
+- **Shared Code**: The `lib/` folder contains framework-agnostic utilities that all implementations can use (e.g., CRUD operations, date parsing)
+
+- **Consistent App Names**: All frameworks implement the same apps with identical folder names (e.g., `hello-world`, `7GUIs-counter`). This enables automated comparison.
+
+- **Bundle Analysis**: Each build produces:
+  - Development bundle (readable, with source maps)
+  - Production bundle (minified with Terser)
+  - Bundle visualization HTML (via rollup-plugin-visualizer)
+  - Size metrics (raw, minified, gzip, brotli) collected by `data.js`
+
+- **Watch Mode**: `dev.js` uses nodemon to watch framework source and rebuild site when changes are detected. Individual frameworks use Rollup's watch mode.
+
+## Adding a New Framework
+
+1. Create a new folder in `frameworks/[new-framework]/`
+2. Add `package.json` with name `[framework]-apps` and build/watch scripts
+3. Create `rollup.config.js` using `bundleHelpers.js` (see existing frameworks for examples)
+4. Implement apps in `src/[app-name]/index.js` or `index.jsx`
+5. Add framework to root `package.json` workspaces array if not already covered by glob
+
+## Adding a New App
+
+1. Add the app folder to `src/` in each framework you want to support
+2. The build system auto-discovers new app folders in each framework's `src/` directory
+3. Tests should be added to `tests/apps/[app-name]/` with framework-specific test files