|
| 1 | +# Hyperbook Copilot Instructions |
| 2 | + |
| 3 | +## Repository Overview |
| 4 | + |
| 5 | +**Hyperbook** is a TypeScript/Node.js tool for building interactive workbooks and documentation. This is a monorepo containing ~22,000 lines of code that supports modern web standards and includes features like embedded code execution environments, interactive elements, and multi-language support. |
| 6 | + |
| 7 | +### High-level Information |
| 8 | +- **Type**: CLI tool and web framework for interactive documentation |
| 9 | +- **Languages**: TypeScript (primary), JavaScript, HTML, CSS, Markdown |
| 10 | +- **Runtime**: Node.js 18+ required, browser runtime for built output |
| 11 | +- **Package Manager**: pnpm (required, version 8+) |
| 12 | +- **Build System**: esbuild (via custom scripts), TypeScript compilation, Vite |
| 13 | +- **Architecture**: Monorepo with 6 packages, 1 platform, and self-documenting website |
| 14 | + |
| 15 | +## Build and Development Instructions |
| 16 | + |
| 17 | +### Prerequisites |
| 18 | +**ALWAYS** ensure these are installed before any operations: |
| 19 | +```bash |
| 20 | +# Install pnpm if not available |
| 21 | + |
| 22 | + |
| 23 | +# Verify versions |
| 24 | +node --version # Should be 18+ |
| 25 | +pnpm --version # Should be 8+ |
| 26 | +``` |
| 27 | + |
| 28 | +### Essential Build Sequence |
| 29 | +**CRITICAL**: Always follow this exact sequence. Package dependencies require specific build order. |
| 30 | + |
| 31 | +```bash |
| 32 | +# 1. Install dependencies (ALWAYS run first) |
| 33 | +pnpm install |
| 34 | + |
| 35 | +# 2. Build packages in dependency order |
| 36 | +cd packages/types && pnpm build # No dependencies |
| 37 | +cd packages/fs && pnpm build # Depends on types |
| 38 | +cd packages/web-component-excalidraw && pnpm build # No dependencies, needed by markdown |
| 39 | +cd packages/markdown && pnpm build # Depends on types, includes emoji prebuild |
| 40 | +cd packages/hyperbook && pnpm build # Depends on fs, markdown, types |
| 41 | + |
| 42 | +# 3. Full monorepo build (after individual packages work) |
| 43 | +pnpm build |
| 44 | + |
| 45 | +# 4. Run tests |
| 46 | +pnpm test |
| 47 | + |
| 48 | +# 5. Run linting |
| 49 | +pnpm lint # May have TypeScript errors in excalidraw package (non-blocking) |
| 50 | +``` |
| 51 | + |
| 52 | +### Known Build Issues and Workarounds |
| 53 | + |
| 54 | +**TypeScript Errors in web-component-excalidraw**: |
| 55 | +- External dependency issues with @excalidraw packages |
| 56 | +- These are non-blocking for most development work |
| 57 | +- Safe to ignore unless working specifically on Excalidraw integration |
| 58 | + |
| 59 | +**Missing Locales Error**: |
| 60 | +- May occur during hyperbook package build |
| 61 | +- **Fix**: Ensure `packages/markdown/dist/locales` exists by copying from `packages/markdown/locales` |
| 62 | + |
| 63 | +### Development Commands |
| 64 | + |
| 65 | +```bash |
| 66 | +# Start development watcher (watches all packages) |
| 67 | +pnpm dev |
| 68 | + |
| 69 | +# Run tests (includes vitest for all packages) |
| 70 | +pnpm test |
| 71 | + |
| 72 | +# Run specific package commands |
| 73 | +pnpm --filter hyperbook build |
| 74 | +pnpm --filter @hyperbook/fs test |
| 75 | +pnpm --filter hyperbook-studio watch # VSCode extension |
| 76 | + |
| 77 | +# Website development (uses built hyperbook CLI) |
| 78 | +pnpm website:dev # Start dev server |
| 79 | +pnpm website:build # Build documentation site |
| 80 | + |
| 81 | +# Platform-specific commands |
| 82 | +pnpm platform:vscode:dev # VSCode extension development |
| 83 | +``` |
| 84 | + |
| 85 | +### Testing Instructions |
| 86 | +- **Test Framework**: Vitest (configured per package) |
| 87 | +- **Test Files**: Located in `packages/*/tests/` directories |
| 88 | +- **Test Coverage**: Core packages have comprehensive test suites |
| 89 | +- **Snapshots**: Some tests use snapshot testing (in `__snapshots__` folders) |
| 90 | +- **Test Requirements**: Build packages before running tests |
| 91 | +- **CI Environment**: Set `CI=true` for production test runs |
| 92 | + |
| 93 | +## Project Architecture and Layout |
| 94 | + |
| 95 | +### Repository Structure |
| 96 | +``` |
| 97 | +/ |
| 98 | +├── .github/workflows/ # CI/CD pipelines |
| 99 | +├── packages/ # Core monorepo packages |
| 100 | +│ ├── hyperbook/ # Main CLI tool and builder |
| 101 | +│ ├── fs/ # File system operations and hyperbook.json handling |
| 102 | +│ ├── markdown/ # Markdown processing with custom directives |
| 103 | +│ ├── types/ # TypeScript type definitions |
| 104 | +│ └── web-component-excalidraw/ # Excalidraw integration component |
| 105 | +├── platforms/ |
| 106 | +│ └── vscode/ # VSCode extension for Hyperbook |
| 107 | +├── website/ # Self-documenting website (de/en) |
| 108 | +├── scripts/ # Build and utility scripts |
| 109 | +├── plop-templates/ # Code generation templates |
| 110 | +└── *.config.json # Configuration files |
| 111 | +``` |
| 112 | + |
| 113 | +### Key Packages Description |
| 114 | + |
| 115 | +**packages/hyperbook** (Main CLI): |
| 116 | +- Entry point: `index.ts` |
| 117 | +- Commands: `new`, `dev`, `build` |
| 118 | +- Dependencies: All other @hyperbook packages |
| 119 | +- Build: Uses @vercel/ncc for bundling |
| 120 | +- Templates: `templates/default/` for new project scaffolding |
| 121 | + |
| 122 | +**packages/fs**: |
| 123 | +- Handles hyperbook.json configuration |
| 124 | +- File system operations for content processing |
| 125 | +- Navigation and page structure management |
| 126 | +- Testing: Extensive test suite with fixtures |
| 127 | + |
| 128 | +**packages/markdown**: |
| 129 | +- Custom markdown processing with remark/rehype |
| 130 | +- Custom directives (alerts, videos, code environments, etc.) |
| 131 | +- Asset management for built-in components |
| 132 | +- Localization support (missing translations are non-fatal) |
| 133 | + |
| 134 | +**packages/types**: |
| 135 | +- TypeScript definitions for hyperbook.json and internal APIs |
| 136 | +- Language definitions and configuration schemas |
| 137 | +- Shared types across all packages |
| 138 | + |
| 139 | +### Configuration Files |
| 140 | +- `hyperbook.json`: Main project configuration (name, language, styling, etc.) |
| 141 | +- `hyperlibrary.json`: Multi-book library configuration |
| 142 | +- `tsconfig.base.json`: Base TypeScript configuration |
| 143 | +- `pnpm-workspace.yaml`: Monorepo package definitions |
| 144 | +- `.github/workflows/`: CI/CD with pnpm, Node.js 22, test + build validation |
| 145 | + |
| 146 | +### Development Environment Setup |
| 147 | +1. **Required**: pnpm 8+, Node.js 18+ |
| 148 | +2. **VSCode**: Configured via `.vscode/` (workspace settings) |
| 149 | +3. **Linting**: TypeScript via `tsc --noEmit` in each package |
| 150 | +4. **Formatting**: Prettier with `.prettierignore` exclusions |
| 151 | +5. **Git Hooks**: Husky pre-commit running `npm test` |
| 152 | + |
| 153 | +### Validation and CI/CD |
| 154 | +**GitHub Workflows**: |
| 155 | +- `pull-request.yml`: Runs on PRs - installs deps, runs tests, builds all packages |
| 156 | +- `changeset-version.yml`: Release automation with changesets, builds VSCode extension |
| 157 | + |
| 158 | +**Pre-commit Validation**: |
| 159 | +- Husky hook runs `npm test` |
| 160 | +- Blocks commits if tests fail |
| 161 | + |
| 162 | +**Manual Validation Steps**: |
| 163 | +```bash |
| 164 | +# Full validation sequence |
| 165 | +pnpm install |
| 166 | +pnpm build # All packages |
| 167 | +pnpm test # All test suites |
| 168 | +pnpm lint # TypeScript checking |
| 169 | + |
| 170 | +# CLI functionality test |
| 171 | +./packages/hyperbook/dist/index.js --help |
| 172 | +./packages/hyperbook/dist/index.js new test-book |
| 173 | + |
| 174 | +# Website build validation |
| 175 | +pnpm website:build |
| 176 | +``` |
| 177 | + |
| 178 | +### Common File Locations |
| 179 | +- Main CLI: `packages/hyperbook/index.ts` |
| 180 | +- Core types: `packages/types/src/index.ts` |
| 181 | +- Build scripts: `scripts/build.mjs`, `scripts/buildPackage.mjs` |
| 182 | +- Templates: `packages/hyperbook/templates/default/` |
| 183 | +- Documentation: `website/en/` and `website/de/` |
| 184 | +- VSCode extension: `platforms/vscode/src/extension.ts` |
| 185 | +- Test fixtures: `packages/*/tests/fixtures/` |
| 186 | + |
| 187 | +### Dependencies and External Integrations |
| 188 | +- **Required External**: None (self-contained after build) |
| 189 | +- **Build Dependencies**: esbuild, TypeScript, various markdown processing libraries |
| 190 | +- **Optional Network**: GitHub emoji fetching (can be disabled) |
| 191 | +- **Runtime Platforms**: Node.js CLI, browser for built content, VSCode extension host |
| 192 | + |
| 193 | +## Agent Guidelines |
| 194 | + |
| 195 | +**Trust these instructions** - they are comprehensive and tested. Only explore beyond these instructions if: |
| 196 | +- You encounter errors not documented here |
| 197 | +- You need to understand specific implementation details not covered |
| 198 | +- These instructions appear outdated (check git history for recent changes) |
| 199 | + |
| 200 | +**Always validate changes** by running the build sequence and tests before finalizing any code changes. |
| 201 | + |
| 202 | +**For build failures**: Follow the workarounds exactly as documented - they are battle-tested solutions. |
0 commit comments