Wasp Framework: AI-Optimized Technical Reference

Overview

Wasp is a full-stack JavaScript framework that generates React + Node.js + Prisma boilerplate from configuration files. Created by Croatian developers, backed by Y Combinator. Current version: 0.17.1 (July 2024, beta status).

Core Value Proposition: Eliminates weekend-long setup rituals for JavaScript full-stack development by generating working auth, type-safe APIs, and deployment configs from simple configuration.

Critical Production Warnings

Version Stability

• Status: Beta (v0.17.x)
• Breaking Changes: v0.17.1 broke compatibility with v0.17.0
• Production Risk: High - suitable for prototypes, risky for mission-critical applications
• v1.0 Timeline: Targeted for late 2025 (estimate reliability: low)

Vendor Lock-in Reality

• Stack Constraint: Forces React + Node.js + Prisma - no alternatives
• Exit Strategy: wasp build generates code, but maintaining generated boilerplate is complex
• Migration Path: Most who eject rewrite 50%+ of generated code

Technical Specifications

System Requirements

• Node.js: 18+ (18.16 confirmed working)
• Operating System: macOS, Linux, WSL 2 (WSL 1 unsupported, native Windows unsupported)
• Memory: 8GB+ required (compilation uses significant resources)
• Disk Space: 200MB+ for .wasp directory plus standard node_modules
• Database: PostgreSQL (production), SQLite (development only)

Compilation Performance

• First Build: 2-5 minutes (caches for subsequent builds)
• Hot Reload: 10-30 seconds per change
• Resource Impact: High CPU usage, laptop fan activation expected

Configuration Architecture

Core File Structure

main.wasp              # Primary configuration - syntax-sensitive
schema.prisma          # Database schema - migration required after changes
src/client/            # React components (standard React)
src/server/            # Node.js backend
.wasp/                 # Generated code - NEVER EDIT (overwritten)
migrations/            # Prisma migrations - MUST commit to git
.env.server           # Environment variables - NEVER commit

Critical Configuration Points

app MyApp {
  wasp: { version: "^0.17.0" },
  auth: {
    userEntity: User,
    methods: { email: { emailVerification: { clientRoute: EmailVerificationRoute } } }
  }
}

Syntax Requirements: Missing commas break compilation with unclear error messages. Use VS Code extension for syntax highlighting.

Feature Implementation Reality

Authentication (Production-Ready)

Strengths:

• HTTP-only cookies with CSRF protection
• Session management works correctly
• OAuth integration (Google, GitHub, Discord)
• Email verification workflows

Critical Failure Points:

• Email Configuration: Gmail app passwords with trailing spaces cause "Authentication failed"
• OAuth Callbacks: Domain changes break login with "redirect_uri_mismatch" errors
• Production URLs: Must update callback URLs for staging/production or users get cryptic errors

Debugging Resources: Check Wasp email guide + NodeMailer docs for SMTP issues

Database Operations (Prisma-Based)

Performance Characteristics:

• Type-safe queries with React Query integration
• N+1 Query Problem: Generated queries not optimized - custom Prisma includes required for complex data
• UI Breaking Point: 1000+ spans make debugging large distributed transactions impossible

Migration Requirements:

• wasp db migrate mandatory after schema changes
• Failure Mode: "Unknown arg 'newColumn'" runtime errors if migrations skipped

Background Jobs (Basic Functionality)

Implementation: PgBoss (PostgreSQL only)
Limitations:

• No complex job dependencies
• SQLite unsupported
• Suitable for simple email sending only

WebSocket Support (Half-Implemented)

Reality: Documentation inadequate, connections drop on cheap hosting (Heroku)
Recommendation: Use Pusher for real-time features instead

Deployment Success Rates

Railway/Fly.io: Works intermittently
Failure Mode: "Build failed" with no diagnostic information
Debugging: Check platform-specific logs (Fly.io logs, Railway deployment logs)

Docker Considerations:

• Generated images: 500MB+ (poor for serverless cold starts)
• macOS users: Use --platform linux/amd64 or encounter architecture mismatch errors
• SSL certificates required for OAuth in production (HTTP fails)

Development Workflow

Standard Cycle

1. Modify .wasp file → 10-30 second recompilation
2. React component changes → Fast hot reload
3. Server code changes → Sometimes requires restart
4. Database schema changes → wasp db migrate required

Common Failure Recovery

1. Hot reload breaks: Restart dev server
2. Still broken: Delete .wasp/ and node_modules, restart
3. Persistent issues: Consult Discord (small community)

Testing Infrastructure

Reality: Basic support, tedious mocking setup
Community Practice: Most skip unit tests, focus on Playwright integration tests post-deployment

Resource Requirements

Time Investment

• Setup: 5 minutes (working) vs 2+ hours (when broken)
• Learning Curve: Easy for React developers
• Debugging Time: High when hitting edge cases (often first to encounter problems)

Monetary Costs (Monthly)

• Hosting: $25-100 (Railway $5+, Fly.io $10-30)
• Database: $15-50 (Supabase free tier available)
• Email: $15 (Mailgun/SendGrid free tiers)
• Total: $20-150/month depending on scale and free tier usage

Human Expertise Requirements

• Required: React knowledge
• Debugging: Haskell compiler error interpretation (Wasp compiler written in Haskell)
• Community Size: ~4k Discord members, minimal Stack Overflow presence

Comparative Analysis

vs Next.js

• Setup Time: Wasp 5min vs Next.js 30min
• Stability: Next.js rock solid vs Wasp beta chaos
• Decision Criteria: Wasp for prototypes, Next.js for production stability

vs Rails

• Auth: Both excellent (Wasp generated vs Devise)
• Real-time: Rails ActionCable vs Wasp half-baked
• Job Queues: Rails Sidekiq superior vs Wasp basic PgBoss
• Maturity: Rails ancient/stable vs Wasp beta

vs T3 Stack

• Setup Complexity: Wasp 5min vs T3 2+ hours
• Type Safety: Both excellent
• Learning Curve: Wasp easier vs T3 TypeScript complexity

Decision Matrix

Use Wasp When:

• Building prototypes or MVPs
• Standard CRUD applications with auth
• Time-to-market is critical
• Can tolerate occasional breakage
• Working on side projects

Avoid Wasp When:

• Job security depends on app stability
• Need real-time features
• Require non-React frontend
• Need MongoDB or non-PostgreSQL databases
• Complex background job requirements

Critical Success Factors

Environment Configuration

• WASP_WEB_CLIENT_URL: Must be set correctly or OAuth breaks
• Database Migrations: Test on staging before production
• Path Issues: Zsh users add export PATH=$HOME/.local/bin:$PATH to ~/.zshrc

Production Deployment Checklist

• SSL certificates configured
• OAuth callback URLs updated for all environments
• Environment variables properly set
• Database migration tested
• Monitoring configured for generated code debugging

Support Ecosystem

Community Resources

• Primary: Discord (~4k members)
• Documentation: Has gaps, lightweight on troubleshooting
• GitHub Issues: More useful than Stack Overflow
• Founder Responsiveness: High (Croatian team)

Knowledge Gaps

• Limited Stack Overflow presence
• Often first to encounter specific problems
• Debugging generated Haskell compiler errors requires community help

Operational Reality Summary

Time Savings: 20+ hours saved on auth and CRUD setup when working
Risk Assessment: High for production, excellent for learning/prototyping
Stability Timeline: Wait for v1.0 (late 2025) for production confidence
Backup Plan: Essential - Next.js or Rails for mission-critical applications

Bottom Line: Significant productivity gains for standard applications, but beta instability makes it unsuitable for applications where downtime has financial consequences.