wasp-lang/wasp
The batteries-included full-stack framework for the AI era. Develop JS/TS web apps (React, Node.js, and Prisma) using declarative code that abstracts away complex full-stack features like auth, background jobs, RPC, email sending, end-to-end type safety, single-command deployment, and more.
Compiles Wasp DSL apps into deployable React/Node.js/Prisma full-stack web applications
The system begins when developers write .wasp specification files declaring their app structure. The Wasp compiler parses these into AST form, validates the configuration, then feeds this to code generators that produce complete React/Node.js applications. During development, the app runner sets up databases (SQLite or PostgreSQL via Docker), runs Prisma migrations, and launches both frontend and backend servers with hot reloading.
Under the hood, the system uses 2 feedback loops, 2 data pools, 2 control points to manage its runtime behavior.
A 5-component dev tool. 1592 files analyzed. Data flows through 5 distinct pipeline stages.
How Data Flows Through the System
The system begins when developers write .wasp specification files declaring their app structure. The Wasp compiler parses these into AST form, validates the configuration, then feeds this to code generators that produce complete React/Node.js applications. During development, the app runner sets up databases (SQLite or PostgreSQL via Docker), runs Prisma migrations, and launches both frontend and backend servers with hot reloading.
- Parse Wasp DSL — WaspCompiler reads .wasp files and parses the declarative syntax into an AST representation, extracting app metadata, entity definitions, page declarations, and auth provider configurations [Raw .wasp files → WaspProject]
- Generate Code Templates — CodeGenerator processes the WaspProject AST and produces complete application code using template files, generating React components for pages, Node.js API routes for operations, Prisma schemas for entities, and authentication middleware [WaspProject → Generated Application Files]
- Setup Development Environment — AppRunner initializes the development environment by calling DatabaseManager to set up either SQLite files or PostgreSQL Docker containers, then runs Prisma migrations to sync database schema [Generated Application Files → DbSetupResult]
- Launch Application Servers — AppRunner executes wasp start command with database environment variables, launching both React development server and Node.js API server with hot reloading enabled [DbSetupResult → Running Development Environment]
- Build Distribution Packages — PackageBuilder processes build artifacts to create platform-specific NPM packages, generating main packages that depend on sub-packages for different OS/architecture combinations [BuildData → NPM Package Distributions]
Data Models
The data structures that flow between stages — the contracts that hold the system together.
waspc/AST representing parsed .wasp file with app declaration containing title, database config, auth providers, pages, operations, and entities
Created during parsing of .wasp files, transformed during compilation, consumed by code generators
scripts/make-npm-packages/src/schema/input-data.tsJSON schema with version: string, tarballs: Array<{fileName: string, target: {os, arch}}>
Generated during build process, consumed by NPM package creation system
wasp-app-runner/src/db/types.tsObject with dbEnvVars: Record<string, string> containing database connection parameters
Created when setting up SQLite or PostgreSQL for development, passed to Wasp CLI commands
waspc/data/Generator/templates/Generated TypeScript interface with id, email, and provider-specific fields based on auth config
Generated from .wasp auth configuration, used throughout application runtime for user context
Hidden Assumptions
Things this code relies on but never validates. These are the things that cause silent failures when the system changes.
The makeSubPackageName function expects target object to have specific properties (os, arch) but the code only validates it against BuildDataSchema which allows any properties
If this fails: If a tarball target contains unexpected fields or missing os/arch fields, makeSubPackageName could crash with property access errors or generate invalid package names
scripts/make-npm-packages/src/index.ts:makeSubPackageName
Database setup functions (setupPostgres/setupSqlite) will always return a valid SetupDbResult with dbEnvVars property, but there's no validation of the returned object structure
If this fails: If database setup returns malformed results or null/undefined dbEnvVars, the subsequent waspMigrateDb and waspStart calls will fail with cryptic environment variable errors
wasp-app-runner/src/db/index.ts:setupDb
Database migration (waspMigrateDb) completes successfully before starting the app server (waspStart), but there's no verification that migrations actually finished or that the database is in a consistent state
If this fails: If migrations fail silently or partially complete, the app server starts with an inconsistent database schema, leading to runtime errors when operations try to access missing tables or columns
wasp-app-runner/src/dev/index.ts:startAppInDevMode
CSS custom property names generated from Object.entries(tokenObj) will always produce valid CSS variable names, but doesn't validate that keys don't contain spaces, special characters, or start with numbers
If this fails: Invalid CSS variable names like '--prefix-123invalid' or '--prefix-my key' get injected into styles, causing CSS parsing errors and broken styling without obvious error messages
waspc/data/Generator/templates/sdk/wasp/auth/forms/internal/util.ts:tokenObjToCSSVars
The data.json file at the specified input path will always be valid JSON and not exceed memory limits when loaded synchronously
If this fails: Large build data files (>1GB) cause out-of-memory crashes, while malformed JSON files throw parse errors that don't indicate which specific field or line is invalid
scripts/make-npm-packages/src/index.ts:fs.readJsonSync
The context.user property is either a valid AuthUser object or null/undefined, but doesn't validate that user object has required fields like id or email before passing to authenticated operations
If this fails: If authentication middleware provides a malformed user object missing critical fields, authenticated operations receive incomplete user data and may fail with property access errors or security bypasses
examples/kitchen-sink/src/rpcTests/operations/server.ts:testingAction
TypeScript setup (waspTsSetup) must complete before starting the app in any mode, but there's no validation that the setup actually succeeded or that generated TypeScript files are valid
If this fails: If TypeScript setup fails or generates broken type definitions, the subsequent development or build process starts with invalid TypeScript configuration, leading to cryptic compilation errors that don't point to the root cause
wasp-app-runner/src/index.ts:runWaspApp
The number of tarballs in BuildData will be reasonable (probably <100) for synchronous processing, but doesn't handle scenarios with thousands of platform-specific builds
If this fails: With hundreds of platform targets, the synchronous package creation process blocks for minutes without progress feedback and may hit filesystem limits for concurrent directory operations
scripts/make-npm-packages/src/index.ts:data.tarballs.map
The isWaspTypescriptConfigProject function can reliably detect TypeScript projects by reading directory contents, but doesn't account for symbolic links, permission issues, or network mounted filesystems
If this fails: On systems with restricted file permissions or when the project directory is a symlink, TypeScript detection fails silently and setup is skipped, causing subsequent compilation errors that appear unrelated to TypeScript configuration
wasp-app-runner/src/index.ts:isWaspTypescriptConfigProject
Session IDs will always be non-empty strings, but the z.string() validator allows empty strings which could represent invalid sessions
If this fails: Empty session IDs pass validation and get treated as valid sessions throughout the auth system, potentially allowing unauthorized access or causing session management to fail unpredictably
waspc/data/Generator/templates/sdk/wasp/auth/responseSchemas.ts:SessionResponseSchema
System Behavior
How the system operates at runtime — where data accumulates, what loops, what waits, and what controls what.
Data Pools
Stores generated React components, API routes, and configuration files that can be inspected but should not be manually edited
Contains compiled binaries and tarballs for different platforms before packaging into distributable NPM packages
Feedback Loops
- Hot Reload Development Loop (auto-scale, balancing) — Trigger: File changes in .wasp or application source files. Action: AppRunner detects changes, regenerates affected code, and reloads development servers. Exit: Developer stops development server.
- Database Migration Loop (convergence, balancing) — Trigger: Changes to entity definitions in .wasp files. Action: System generates new Prisma schema and runs migrations to update database structure. Exit: Database schema matches entity definitions.
Delays
- Code Generation Phase (compilation, ~2-5 seconds) — Complete application rebuild when .wasp files change, blocking development server restart
- Docker Database Startup (warmup, ~5-10 seconds) — First-time PostgreSQL setup waits for Docker container initialization before proceeding with migrations
Control Points
- Database Type Selection (architecture-switch) — Controls: Whether to use SQLite for simple development or PostgreSQL with Docker for production-like setup. Default: SQLite or PostgreSQL based on app config
- Development vs Build Mode (env-var) — Controls: Whether to run with hot reloading and development features or build optimized production bundles. Default: dev or build
Technology Stack
Implementation language for the Wasp compiler that parses DSL and generates code
Target runtime for generated frontend applications with type-safe RPC communication
Target runtime for generated backend APIs and authentication middleware
Database ORM automatically configured and integrated into generated applications
Provides PostgreSQL database containers for local development environments
Build tool and development server for the generated React applications
Key Components
- WaspCompiler (orchestrator) — Parses .wasp DSL files into AST, validates configuration, and coordinates generation of complete React/Node.js applications
waspc/ - CodeGenerator (transformer) — Takes parsed Wasp AST and produces actual application files including React components, API routes, database schemas, and auth flows
waspc/data/Generator/ - AppRunner (orchestrator) — Manages development lifecycle by setting up databases, running migrations, and launching development servers for Wasp applications
wasp-app-runner/src/index.ts - DatabaseManager (adapter) — Abstracts database setup for SQLite and PostgreSQL, handling Docker containers for PostgreSQL and file creation for SQLite
wasp-app-runner/src/db/index.ts - PackageBuilder (processor) — Creates platform-specific NPM packages from build artifacts, generating main packages and sub-packages for different OS/architecture combinations
scripts/make-npm-packages/src/index.ts
Explore the interactive analysis
See the full architecture map, data flow, and code patterns visualization.
Analyze on CodeSeaRelated Dev Tool Repositories
Frequently Asked Questions
What is wasp used for?
Compiles Wasp DSL apps into deployable React/Node.js/Prisma full-stack web applications wasp-lang/wasp is a 5-component dev tool written in TypeScript. Data flows through 5 distinct pipeline stages. The codebase contains 1592 files.
How is wasp architected?
wasp is organized into 4 architecture layers: Wasp Compiler (waspc), Generated Runtime, Development Tools, Examples & Documentation. Data flows through 5 distinct pipeline stages. This layered structure keeps concerns separated and modules independent.
How does data flow through wasp?
Data moves through 5 stages: Parse Wasp DSL → Generate Code Templates → Setup Development Environment → Launch Application Servers → Build Distribution Packages. The system begins when developers write .wasp specification files declaring their app structure. The Wasp compiler parses these into AST form, validates the configuration, then feeds this to code generators that produce complete React/Node.js applications. During development, the app runner sets up databases (SQLite or PostgreSQL via Docker), runs Prisma migrations, and launches both frontend and backend servers with hot reloading. This pipeline design reflects a complex multi-stage processing system.
What technologies does wasp use?
The core stack includes Haskell (Implementation language for the Wasp compiler that parses DSL and generates code), TypeScript/React (Target runtime for generated frontend applications with type-safe RPC communication), Node.js (Target runtime for generated backend APIs and authentication middleware), Prisma (Database ORM automatically configured and integrated into generated applications), Docker (Provides PostgreSQL database containers for local development environments), Vite (Build tool and development server for the generated React applications). A focused set of dependencies that keeps the build manageable.
What system dynamics does wasp have?
wasp exhibits 2 data pools (Generated Code Cache, Build Artifacts Repository), 2 feedback loops, 2 control points, 2 delays. The feedback loops handle auto-scale and convergence. These runtime behaviors shape how the system responds to load, failures, and configuration changes.
What design patterns does wasp use?
3 design patterns detected: DSL to Code Generation, Multi-Platform Binary Distribution, Development Environment Orchestration.
Analyzed on April 20, 2026 by CodeSea. Written by Karolina Sarna.