This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

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.

Documentation: https://tinyhttp.v1rtl.site

This is a pnpm monorepo with packages in the packages/ directory:

• @tinyhttp/app - Core application framework (main package)
• @tinyhttp/router - Routing functionality
• @tinyhttp/req - Request extensions
• @tinyhttp/res - Response extensions
• Other packages - Utilities like cookie handling, proxy-addr, content-disposition, etag, etc.

Each package follows this structure:

• src/ - TypeScript source files
• dist/ - Compiled output (generated by tsc)
• tsconfig.json - Extends root config, sets rootDir to src/ and outDir to dist/
• package.json - Package metadata with "type": "module" for ESM

Tests are organized separately:

• tests/core/ - Core App class tests
• tests/modules/ - Individual package/module tests
• tests/wares/ - Middleware tests
• test_helpers/ - Shared test utilities (e.g., InitAppAndTest)

# Install dependencies (root and all packages)
pnpm i && pnpm i -r

# Build all packages
pnpm build

# Run all tests with coverage
pnpm test

# Run tests in watch mode (development)
pnpm test:dev

# Lint and format
pnpm check  # runs Biome check
pnpm lint   # lint only
pnpm format # format only

# Run tests in a specific directory
vitest --dir tests/core
vitest --dir tests/modules

# Run a single test file
vitest tests/modules/router.test.ts

# Run tests with coverage for specific files
vitest run --coverage --dir tests/core

# Build a specific package
cd packages/app && pnpm build

# Install dependencies across all packages
pnpm i -r

The App class extends Router and serves as the main entry point. Key responsibilities:

• Middleware management - Stores middleware in App.middleware[] array
• Error handling - Custom onError handler (default: onErrorHandler)
• 404 handling - Custom noMatchHandler
• Settings & configuration - App.settings object (views directory, trust proxy, view cache, etc.)
• Template engines - Stored in App.engines object
• Request/Response extensions - Applied via extendMiddleware and applyExtensions
• Async error handling - Middleware wrapped in applyHandler catches async errors

The attach method is the core request handler that processes the middleware chain.

Handles route matching and middleware execution. Uses regexparam for path-to-regexp style routing.

• Request (packages/req/) - Extensions like req.accepts(), req.get(), req.is(), etc.
• Response (packages/res/) - Extensions like res.send(), res.json(), res.status(), etc.

These are applied to Node's IncomingMessage and ServerResponse via extension functions.

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:

const { fetch, app, server } = InitAppAndTest(handler, route?, method?, settings?)
await fetch('/path').expect(200, 'expected body')

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.

This project uses changesets for version management:

# Create a changeset (describe changes)
pnpm chgset:run

# Version packages and update CHANGELOG
pnpm chgset:version

# Publish to npm
pnpm release

# Full pre-release check (lint, build, test)
pnpm prerelease

• Formatter/Linter: Biome (replaces ESLint + Prettier)
• Target: ES2022, Node.js 16.10.0+ (for @tinyhttp/app)
• Module system: ESM only ("type": "module")
• TypeScript: Strict mode enabled
• Uses .js extensions in imports even in TypeScript files (ESM requirement)

• Single quotes, no semicolons
• 2-space indentation, 120 char line width
• No trailing commas
• Bracket spacing enabled

• regexparam - Path matching (similar to path-to-regexp)
• header-range-parser - HTTP range header parsing
• supertest-fetch - HTTP testing utility
• vitest - Test runner with coverage via v8
• Biome - Linting and formatting