|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## About tinyhttp |
| 6 | + |
| 7 | +tinyhttp is a modern Express-like web framework written in TypeScript, compiled to native ESM with minimal dependencies. It provides Express middleware compatibility while targeting recent Node.js versions without legacy polyfills. |
| 8 | + |
| 9 | +## Project Structure |
| 10 | + |
| 11 | +This is a **pnpm monorepo** with packages in the `packages/` directory: |
| 12 | + |
| 13 | +- **`@tinyhttp/app`** - Core application framework (main package) |
| 14 | +- **`@tinyhttp/router`** - Routing functionality |
| 15 | +- **`@tinyhttp/req`** - Request extensions |
| 16 | +- **`@tinyhttp/res`** - Response extensions |
| 17 | +- **Other packages** - Utilities like cookie handling, proxy-addr, content-disposition, etag, etc. |
| 18 | + |
| 19 | +Each package follows this structure: |
| 20 | +- `src/` - TypeScript source files |
| 21 | +- `dist/` - Compiled output (generated by `tsc`) |
| 22 | +- `tsconfig.json` - Extends root config, sets rootDir to `src/` and outDir to `dist/` |
| 23 | +- `package.json` - Package metadata with `"type": "module"` for ESM |
| 24 | + |
| 25 | +Tests are organized separately: |
| 26 | +- `tests/core/` - Core App class tests |
| 27 | +- `tests/modules/` - Individual package/module tests |
| 28 | +- `tests/wares/` - Middleware tests |
| 29 | +- `test_helpers/` - Shared test utilities (e.g., `InitAppAndTest`) |
| 30 | + |
| 31 | +## Common Commands |
| 32 | + |
| 33 | +### Development workflow |
| 34 | +```bash |
| 35 | +# Install dependencies (root and all packages) |
| 36 | +pnpm i && pnpm i -r |
| 37 | + |
| 38 | +# Build all packages |
| 39 | +pnpm build |
| 40 | + |
| 41 | +# Run all tests with coverage |
| 42 | +pnpm test |
| 43 | + |
| 44 | +# Run tests in watch mode (development) |
| 45 | +pnpm test:dev |
| 46 | + |
| 47 | +# Lint and format |
| 48 | +pnpm check # runs Biome check |
| 49 | +pnpm lint # lint only |
| 50 | +pnpm format # format only |
| 51 | +``` |
| 52 | + |
| 53 | +### Running specific tests |
| 54 | +```bash |
| 55 | +# Run tests in a specific directory |
| 56 | +vitest --dir tests/core |
| 57 | +vitest --dir tests/modules |
| 58 | + |
| 59 | +# Run a single test file |
| 60 | +vitest tests/modules/router.test.ts |
| 61 | + |
| 62 | +# Run tests with coverage for specific files |
| 63 | +vitest run --coverage --dir tests/core |
| 64 | +``` |
| 65 | + |
| 66 | +### Package-level operations |
| 67 | +```bash |
| 68 | +# Build a specific package |
| 69 | +cd packages/app && pnpm build |
| 70 | + |
| 71 | +# Install dependencies across all packages |
| 72 | +pnpm i -r |
| 73 | +``` |
| 74 | + |
| 75 | +## Architecture Notes |
| 76 | + |
| 77 | +### App Class (packages/app/src/app.ts) |
| 78 | + |
| 79 | +The `App` class extends `Router` and serves as the main entry point. Key responsibilities: |
| 80 | + |
| 81 | +- **Middleware management** - Stores middleware in `App.middleware[]` array |
| 82 | +- **Error handling** - Custom `onError` handler (default: `onErrorHandler`) |
| 83 | +- **404 handling** - Custom `noMatchHandler` |
| 84 | +- **Settings & configuration** - `App.settings` object (views directory, trust proxy, view cache, etc.) |
| 85 | +- **Template engines** - Stored in `App.engines` object |
| 86 | +- **Request/Response extensions** - Applied via `extendMiddleware` and `applyExtensions` |
| 87 | +- **Async error handling** - Middleware wrapped in `applyHandler` catches async errors |
| 88 | + |
| 89 | +The `attach` method is the core request handler that processes the middleware chain. |
| 90 | + |
| 91 | +### Router (packages/router/) |
| 92 | + |
| 93 | +Handles route matching and middleware execution. Uses `regexparam` for path-to-regexp style routing. |
| 94 | + |
| 95 | +### Request/Response Extensions |
| 96 | + |
| 97 | +- **Request** (`packages/req/`) - Extensions like `req.accepts()`, `req.get()`, `req.is()`, etc. |
| 98 | +- **Response** (`packages/res/`) - Extensions like `res.send()`, `res.json()`, `res.status()`, etc. |
| 99 | + |
| 100 | +These are applied to Node's IncomingMessage and ServerResponse via extension functions. |
| 101 | + |
| 102 | +### Testing Pattern |
| 103 | + |
| 104 | +Tests use `supertest-fetch` for HTTP assertions and vitest for the test runner. The `InitAppAndTest` helper (in `test_helpers/`) creates an app instance, starts a server, and returns a fetch function for making requests: |
| 105 | + |
| 106 | +```typescript |
| 107 | +const { fetch, app, server } = InitAppAndTest(handler, route?, method?, settings?) |
| 108 | +await fetch('/path').expect(200, 'expected body') |
| 109 | +``` |
| 110 | +
|
| 111 | +### Vitest Configuration |
| 112 | +
|
| 113 | +The `vitest.config.ts` dynamically creates path aliases for all packages in `packages/` directory, mapping `@tinyhttp/{package}` to `packages/{package}/src`. This allows tests to import from source directly without building. |
| 114 | +
|
| 115 | +## Release Process |
| 116 | +
|
| 117 | +This project uses changesets for version management: |
| 118 | +
|
| 119 | +```bash |
| 120 | +# Create a changeset (describe changes) |
| 121 | +pnpm chgset:run |
| 122 | + |
| 123 | +# Version packages and update CHANGELOG |
| 124 | +pnpm chgset:version |
| 125 | + |
| 126 | +# Publish to npm |
| 127 | +pnpm release |
| 128 | + |
| 129 | +# Full pre-release check (lint, build, test) |
| 130 | +pnpm prerelease |
| 131 | +``` |
| 132 | +
|
| 133 | +## Code Style |
| 134 | +
|
| 135 | +- **Formatter/Linter**: Biome (replaces ESLint + Prettier) |
| 136 | +- **Target**: ES2022, Node.js 14.21.3+ |
| 137 | +- **Module system**: ESM only (`"type": "module"`) |
| 138 | +- **TypeScript**: Strict mode enabled |
| 139 | +- Uses `.js` extensions in imports even in TypeScript files (ESM requirement) |
| 140 | +
|
| 141 | +## Key Dependencies |
| 142 | +
|
| 143 | +- **regexparam** - Path matching (similar to path-to-regexp) |
| 144 | +- **header-range-parser** - HTTP range header parsing |
| 145 | +- **supertest-fetch** - HTTP testing utility |
| 146 | +- **vitest** - Test runner with coverage via v8 |
| 147 | +- **Biome** - Linting and formatting |
0 commit comments