TypeScript 5,141 FILES 6 FINDINGS

HOW WASP
ACTUALLY WORKS

The fastest way to develop full-stack web apps with React and Node.js. Conventions, patterns, and architecture extracted from the wasp-lang/wasp repository by sourcebook.

VIEW_REPO north_east

QUICK_REF:

Routing: Express app routes Data fetching: React Query (useQuery/useMutation)

WHAT_MATTERS

→
Uses Express routes for API endpoints — follow this pattern for new routes
→
Data fetching uses React Query — use useQuery/useMutation for new data operations
→
Barrel exports pattern — import from the directory, not from deep paths

KEY_FINDINGS

Tests are co-located with source files (*.test.ts next to *.ts). Keep this pattern.

HIGH

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

HIGH

10 barrel export files found

API endpoints use Express app routes. Follow this pattern for new routes.

HIGH

11 files use Express app routes

Data fetching uses React Query (useQuery/useMutation). Follow this pattern for new data operations.

HIGH

9 files use React Query

Hub files (most depended on): waspc/.../middleware/operations.ts (31 files); waspc/.../FeatureContainer.tsx (21 files); waspc/.../sdk/wasp/src/components/FeatureContainer.tsx (21 files); waspc/.../actions/index.ts (18 files); waspc/.../definitions.ts (17 files). Changes here have the widest blast radius.

HIGH

Circular imports detected: Link.tsx → index.ts (repeated). Avoid adding to these cycles.

HIGH

smart_toy USING_AI_TOOLS

→use Express routes for API endpoints
→use React Query for data fetching (useQuery/useMutation)
→follow barrel export patterns for imports

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

- **routing:** API endpoints use Express app routes
- **data fetching:** Data fetching uses React Query (useQuery/useMutation)

## Critical Constraints

- **Testing:** Tests are co-located with source files (*.test.ts next to *.ts). Keep this pattern.
- **Core modules:** Hub files (most depended on): waspc/.../middleware/operations.ts (31 files); waspc/.../FeatureContainer.tsx (21 files); waspc/.../actions/index.ts (18 files); waspc/.../definitions.ts (17 files). Changes here have the widest blast radius.
- **Circular dependencies:** Circular imports detected: Link.tsx → index.ts (repeated). Avoid adding to these cycles.

## Stack

Vite + React, Tailwind CSS, Express, TypeScript

## Core Modules (by structural importance)

- `waspc/.../middleware/operations.ts`
- `waspc/.../FeatureContainer.tsx`
- `waspc/.../sdk/wasp/src/components/FeatureContainer.tsx`
- `waspc/.../actions/index.ts`
- `waspc/.../definitions.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:**
- API endpoints use Express app routes. Follow this pattern for new routes.
- Data fetching uses React Query (useQuery/useMutation). Follow this pattern for new data operations.

## 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

NEXT.JS EXPRESS

HOW WASPACTUALLY WORKS

WHAT_MATTERS

KEY_FINDINGS

npx sourcebook init

FROM_THE_BLOG

RELATED_REPOS

HOW WASP
ACTUALLY WORKS