TypeScript 281 FILES 8 FINDINGS

HOW ELYSIA
ACTUALLY WORKS

Ergonomic framework for humans. The fastest TypeScript framework built for Bun. Conventions, patterns, and architecture extracted from the elysiajs/elysia repository by sourcebook.

VIEW_REPO north_east

QUICK_REF:

Validation: TypeBox schemas Error handling: Custom error classes

WHAT_MATTERS

→
This is a publishable library — focus on public API surface, avoid breaking exported types
→
src/types.ts is a hub file (imported by 17 files) — changes here ripple everywhere
→
Uses custom error classes — throw specific error types instead of generic Error

KEY_FINDINGS

Source code lives in src/ but some code files exist at the root. Keep application code in src/.

HIGH

This is a publishable library, not an application. Focus changes on the public API surface.

HIGH

Project uses barrel exports (index.ts files that re-export). Import from the directory, not from deep paths.

HIGH

3 barrel export files found

Project uses custom error classes. Throw specific error types instead of generic Error.

HIGH

Uses TypeBox (@sinclair/typebox) for validation via Elysia's t schema builder.

HIGH

TypeBox-based type system via Elysia's t schema builder

Hub files (most depended on): src/types.ts (imported by 17 files); src/utils.ts (imported by 14 files); src/context.ts (imported by 12 files); src/cookies.ts (imported by 11 files); src/error.ts (imported by 11 files). Changes here have the widest blast radius.

HIGH

Circular import chains detected: sucrose.ts → utils.ts; context.ts → server.ts → types.ts → index.ts; error.ts → schema.ts → index.ts. Avoid adding to these cycles.

HIGH

3 dead code candidates: build.ts, src/formats.ts, src/universal/request.ts.

HIGH

smart_toy USING_AI_TOOLS

→this is a library — don't break the public API surface
→use custom error classes, not generic Error
→check file importance before editing hub files

CLAUDE.MD expand_more

# CLAUDE.md

This file provides guidance to Claude Code when working with this codebase.
Generated by [sourcebook](https://github.com/maroondlabs/sourcebook). Review and edit — the best context comes from human + machine together.

## Quick Reference

- **validation:** Uses TypeBox (@sinclair/typebox) for validation via Elysia's t schema builder.
- **error handling:** Project uses custom error classes. Throw specific error types instead of generic Error.

## Commands

- **Dev:** `bun run --watch example/a.ts`
- **Build:** `rm -rf dist && bun build.ts`
- **Test:** `bun run test:functionality && bun run test:types && bun run test:node`

## Critical Constraints

- **Library:** This is a publishable library, not an application. Focus changes on the public API surface.
- **Core modules:** Hub files (most depended on): src/types.ts (imported by 17 files); src/utils.ts (imported by 14 files); src/context.ts (imported by 12 files); src/cookies.ts (imported by 11 files); src/error.ts (imported by 11 files). Changes here have the widest blast radius.
- **Circular dependencies:** Circular import chains detected: sucrose.ts → utils.ts; context.ts → server.ts → types.ts → index.ts; error.ts → schema.ts → index.ts. Avoid adding to these cycles.

## Stack

TypeScript

## Core Modules (by structural importance)

- `src/types.ts`
- `src/universal/utils.ts`
- `src/utils.ts`
- `src/error.ts`
- `src/context.ts`

## Conventions & Patterns

- **Import conventions:** Project uses barrel exports (index.ts files that re-export). Import from the directory, not from deep paths.
- **Dominant patterns:**
  - Uses TypeBox (@sinclair/typebox) for validation via Elysia's t schema builder.
  - Project uses custom error classes. Throw specific error types instead of generic Error.

## Before Making Changes

- **Check file importance** before editing. Hub files (listed in Core Modules) affect many other files — changes here have the widest blast radius.
- **Follow existing patterns.** This project has established conventions (listed above). Match them instead of introducing new approaches.
- **Respect constraints.** Review the Critical Constraints section before making structural changes.

If the sourcebook MCP server is available (`sourcebook serve`), verify before acting:
- `get_blast_radius` — check what breaks if you edit a hub file
- `query_conventions` — confirm the right pattern before adding new code
- `get_pressing_questions` — get a briefing before editing an unfamiliar file

## What to Add Manually

The most valuable context is what only you know. Add:

- Architectural decisions and why they were made
- Past incidents that shaped current conventions
- Deprecated patterns to avoid in new code
- Domain-specific rules or terminology
- Environment setup beyond what .env.example shows

GENERATED IN ~3 SECONDS WITH

npx sourcebook init

VIEW ON GITHUB star

FROM_THE_BLOG

Why AI agents fail on real codebases arrow_forward Why auto-generated context makes agents worse arrow_forward

RELATED_REPOS

HONO EXPRESS

HOW ELYSIAACTUALLY WORKS

WHAT_MATTERS

KEY_FINDINGS

npx sourcebook init

FROM_THE_BLOG

RELATED_REPOS

HOW ELYSIA
ACTUALLY WORKS