# >� ADHD-Optimized Node.js + pnpm Monorepo Template [](https://github.com/nathanvale/bun-changesets-template/actions/workflows/ci.yml) [](https://codecov.io/gh/nathanvale/bun-changesets-template) [](https://github.com/nathanvale/bun-changesets-template/actions/workflows/security-scan.yml) [](https://github.com/nathanvale/bun-changesets-template/actions/workflows/matrix-testing.yml) [](https://www.npmjs.com/package/node-pnpm-changesets-template) [](https://opensource.org/licenses/MIT) [](https://libraries.io/github/nathanvale/bun-changesets-template) [](https://snyk.io/test/github/nathanvale/bun-changesets-template) [](https://nodejs.org/) [](https://pnpm.io/) [](https://codeclimate.com/github/nathanvale/bun-changesets-template) [](https://github.com/nathanvale/bun-changesets-template/network/dependencies) > **Production-ready monorepo with <8s builds, 85% less configuration, and zero > cognitive overhead** A Node.js + pnpm monorepo template specifically engineered for ADHD developers, featuring Next.js, Turborepo, Vitest, and automated releases with Changesets. Built on the principle that **cognitive load is a finite resource** that must be carefully managed. ## ( Key Features ### =� ADHD-Optimized Performance - **<8s warm builds** - Stay in flow state - **<3s test runs** - Instant validation feedback - **<2s linting** - Quick quality checks - **85% config reduction** - From 315 to 48 lines of Turborepo config ### <� Cognitive Load Reduction - **18 essential scripts only** - Down from 80+ commands - **4-command pattern** per package - `build`, `test`, `lint`, `typecheck` - **Zero decision paralysis** - Opinionated defaults that just work - **Single mental model** - Consistent tsup builds everywhere ### =� Modern Stack - **Node.js 20 LTS** - Stable, proven runtime - **pnpm workspaces** - Fast, efficient dependency management - **Turborepo 2.5+** - Intelligent build orchestration - **Vitest** - Unified testing across all packages - **Changesets** - Automated versioning and releases ## =� Quick Start ```bash # Clone and install git clone https://github.com/nathanvale/bun-changesets-template.git my-project cd my-project pnpm install # Start developing pnpm dev # Start all dev servers pnpm test # Run tests once pnpm build # Build all packages pnpm validate # Full validation suite ``` ## =� Tooling This template uses **pnpm** as the package manager for optimal performance and disk efficiency: ### Why pnpm? - **Fast installations** - Up to 2x faster than npm/yarn - **Disk efficient** - Content-addressable storage prevents duplication - **Strict dependency resolution** - Prevents phantom dependencies - **Built-in workspace support** - Native monorepo features - **npm compatibility** - Drop-in replacement for npm ### Package Manager Requirements ```bash # Install pnpm globally (if not already installed) npm install -g [email protected] # Or use corepack (recommended) corepack enable corepack prepare [email protected] --activate ``` ### Workspace Configuration The `pnpm-workspace.yaml` file defines our monorepo structure: ```yaml packages: - apps/* - packages/* - '!packages/claude-hooks' # Excluded package ``` ### Key Benefits for ADHD Developers - **Consistent commands** - Same `pnpm` prefix for all operations - **Faster feedback** - Reduced wait times maintain flow state - **Reliable installs** - Deterministic dependency resolution - **Clear mental model** - One tool, consistent behavior ## =� Project Structure ``` . � apps/ � � nextjs/ # Next.js 15 application � � vite/ # Vite React application � packages/ � � utils/ # Shared utilities � � claude-hooks/ # Claude AI hooks � � voice-vault/ # Voice recording utilities � tooling/ � � build/ # Shared tsup configuration � � tsconfig/ # TypeScript configs � turbo.json # Minimal Turborepo config (48 lines!) ``` ## >� ADHD Developer Experience ### Essential Commands Only ```bash # Core Development (Muscle Memory) pnpm dev # Start development pnpm test # Run tests pnpm build # Build everything pnpm lint # Check code quality pnpm typecheck # Type validation pnpm validate # Everything at once # Release Management pnpm changeset # Create changeset pnpm release # Publish packages ``` ### Context Recovery After interruptions, quickly restore context: ```bash pnpm validate # See what's broken pnpm test # Verify your changes git status # Check uncommitted work ``` ## <�� Build System ### Standardized tsup Configuration All packages use a shared tsup configuration for consistency: ```typescript // packages/*/tsup.config.ts import { defineConfig } from 'tsup' import baseConfig from '../../tooling/build/tsup.base' export default defineConfig({ ...baseConfig, entry: ['src/index.ts'], }) ``` ### Minimal Package Scripts Every package follows the same 4-command pattern: ```json { "scripts": { "build": "tsup", "test": "vitest run", "lint": "eslint .", "typecheck": "tsc --noEmit" } } ``` ## =� Automated Releases ### Using Changesets 1. Make your changes 2. Create a changeset: ```bash pnpm changeset ``` 3. Commit with conventional commits: ```bash pnpm commit # Interactive commit helper ``` 4. Release when ready: ```bash pnpm release ``` ## >� Testing ### Unified Vitest Configuration Single test configuration for the entire monorepo: ```bash pnpm test # Run all tests pnpm test:watch # Watch mode pnpm test:coverage # With coverage ``` ### Writing Tests ```typescript import { describe, test, expect } from 'vitest' describe('My Feature', () => { test('should work', () => { expect(true).toBe(true) }) }) ``` ### Test Environment Variables Control test output and behavior with environment variables: ```bash # Reduce test output noise (minimal output) VITEST_SILENT=true pnpm test # Enable memory debugging (shows memory usage) MEMORY_DEBUG=true pnpm test # Memory debugging overrides silent mode MEMORY_DEBUG=true VITEST_SILENT=true pnpm test # CI mode (automatically enables silent output) CI=true pnpm test ``` **VITEST_SILENT** - Reduces test output from ~350 lines to <65 lines: - Suppresses console output from tests - Uses minimal dot reporter - Still shows test failures and errors - Maintains full debugging capability ## =� Performance Metrics | Metric | Target | Actual | Status | | ----------------- | ------ | ------ | ------ | | Warm build time | <5s | <8s | � | | Test execution | <5s | <3s | � | | Lint time | <5s | <2s | � | | Config complexity | -80% | -85% | � | | Script count | <20 | 18 | � | ## =�� Configuration Philosophy ### Before (Cognitive Overload) - 80+ npm scripts - 315 lines of Turborepo config - Multiple build tools - Inconsistent patterns - Decision paralysis ### After (ADHD-Optimized) - 18 essential scripts - 48 lines of Turborepo config - Single build tool (tsup) - Consistent 4-command pattern - Zero decisions needed ## >� Contributing We welcome contributions that align with our ADHD-optimization principles: 1. **Reduce cognitive load** - Simplify, don't add complexity 2. **Maintain fast feedback** - Keep builds and tests under 10s 3. **Follow patterns** - Consistency reduces mental overhead 4. **Document clearly** - Help others avoid confusion ## =� Documentation - [Build System Guide](./docs/build-system.md) - [Package Development](./docs/packages.md) - [Testing Strategy](./docs/testing.md) - [Release Process](./docs/releases.md) - CLI mocking: see `packages/testkit/src/cli/README.md` and examples in `packages/testkit/examples/cli/` - Convex harness: see `packages/testkit/src/convex/README.md`, guide at `docs/guides/convex-harness.md`, and examples in `packages/testkit/examples/convex/` ## <� Design Principles 1. **Cognitive Load as a First-Class Concern** - Every decision filtered through cognitive impact 2. **Fast Feedback Loops** - Sub-10s for everything 3. **Progressive Complexity** - Start simple, add power without overwhelming 4. **Flow State Protection** - Minimize interruptions and context switches 5. **Dopamine-Driven Development** - Quick wins and visible progress ## =� License MIT � [Nathan Vale](https://github.com/nathanvale) --- **Built for ADHD developers, by ADHD developers.** Every line of configuration was scrutinized for cognitive overhead. If it didn't reduce mental load, it was removed. ## 🔄 CI/CD Pipeline This project features a comprehensive CI/CD pipeline with: ### 🛡️ Quality Gates - **Coverage Gates**: Minimum 70% code coverage required - **Security Scanning**: Automated vulnerability detection - **License Compliance**: Prohibited license detection - **SAST Analysis**: Static application security testing - **Secret Detection**: Hardcoded secret prevention ### 🎯 Testing Strategy - **Matrix Testing**: Cross-platform compatibility (Node 18/20/22, Ubuntu/macOS/Windows) - **Flakiness Detection**: Multi-run test execution to catch inconsistent tests - **Performance Monitoring**: Test execution time tracking - **Comprehensive Reporting**: Detailed test results with PR comments ### 🔧 Automation - **Dependabot**: Automated dependency updates - **Auto-fixing**: Linting and formatting fixes - **Release Automation**: Changesets-powered releases - **Badge Updates**: Real-time quality metrics ### 📊 Monitoring & Reporting - **Coverage Reports**: Per-package coverage analysis - **Security Advisories**: Weekly security scans - **Test Reports**: HTML reports with detailed analytics - **Performance Metrics**: Build and test performance tracking All workflows are optimized for ADHD developers with clear visual feedback, minimal noise, and actionable results.