Wasp - Full-Stack JavaScript Framework That Might Not Suck

I've burned entire weekends setting up the same auth flow for the tenth time this year. JavaScript full-stack is just configuration hell with extra steps. You spend more time reading documentation about connecting React to Express than actually building the thing your users want.

This is the pain Wasp was built to solve - and why understanding this context matters before you decide whether to bet your project on a beta framework.

The Weekend-Killing Setup Ritual

Every project starts the same way. Create React app. Install Express (or maybe Fastify this time because why not try something different). Configure Prisma and fight with database connection strings. Set up NextAuth because rolling your own auth is career suicide. Add React Query because managing server state manually is tedious.

Then spend 2 hours debugging CORS because you forgot to enable credentials. Then another hour figuring out why your cookies aren't working (it's always sameSite settings). Then fight with TypeScript across the client-server boundary until you give up and add _@ts-ignore everywhere_.

By Sunday night you've written 500+ lines of configuration boilerplate and your app still just shows "Hello World".

So These Croatian Devs Built Wasp

Two Croatian developers got tired of the same problems and built Wasp. Basically Rails for JavaScript people. You write a simple config file, it generates React + Node + Prisma code.

app todoApp {
  title: "ToDo App",
  wasp: { version: "^0.17.0" },
  auth: {
    userEntity: User,
    methods: { email: {...} }
  }
}

query getTasks {
  fn: import { getTasks } from "@server/tasks.js",
  entities: [Task]
}

This magic config file spits out working auth, type-safe API endpoints, database migrations, React Query hooks, and deployment configs. No more weekend debugging sessions trying to figure out why your JWT cookies aren't working.

When it works, you go from zero to deployed app with auth in like an hour instead of a weekend.

The Catch (Because There's Always a Catch)

It's got 17.7k GitHub stars and Y Combinator money, but it's still beta. Version 0.17.1 came out July 2024 and broke some things from 0.17.0.

Sometimes it saves you weeks. Sometimes you spend those same weeks debugging cryptic Haskell compiler errors because the Wasp compiler is written in Haskell (yeah, really).

The Discord is helpful but tiny compared to Next.js communities or Rails forums. You'll often be the first person to hit your specific problem. The GitHub issues are more useful than Stack Overflow since there aren't many Wasp questions on SO yet.

Also, you're stuck with their stack: React, Node, Prisma. Period. Want Vue? Too bad. Need MongoDB? Nope, PostgreSQL or SQLite only. No Svelte, no Nuxt, no alternatives.

Just Tell Me: Should I Use It?

If you're prototyping or building standard CRUD with auth, probably yeah. The time savings are real when it works.

If your boss will fire you when the next beta version breaks your prod deployment, stick with Next.js or Rails.

The Wasp roadmap targets 1.0 by end of 2025. Until then, it's promising but risky for production apps.

The verdict? Wasp cuts through JavaScript setup hell when it works, but the beta warnings are real. If you're building prototypes or can handle occasional breakage, the time savings are massive. If your livelihood depends on stability, stick with the boring mature options.

Next, let's look at what actually happens when you dive in and start using this thing...

You've read the pitch. Now here's the reality check: Wasp generates a ton of boilerplate so you don't have to write it. Sometimes this is amazing. Sometimes you spend 3 hours debugging generated code you didn't write and can't easily modify.

Let me walk through what actually works and what will bite you in the ass.

Auth Actually Works (Shocked Face)

Honestly, the auth stuff is pretty solid. Normally setting up authentication is a full day of reading NextAuth docs, fighting with session stores, and googling "why is my jwt token undefined" at 11 PM.

auth: {
  userEntity: User,
  methods: {
    email: { emailVerification: { clientRoute: EmailVerificationRoute } },
    google: { configFn: import { getConfig } from "@server/auth.js" }
  }
}

This generates working login/signup/logout flows with:

• Session management with HTTP-only cookies
• CSRF protection (actually works, unlike half the tutorials online)
• Email verification workflows
• Social OAuth for Google, GitHub, Discord

Course, email config is still annoying. Spent 2 hours debugging "Authentication failed" before realizing my Gmail app password had a space at the end. The SMTP error messages aren't very helpful. Check the Wasp email guide and NodeMailer docs when it breaks.

Oh, and if you change domains in production, update your OAuth callback URLs or your users get cryptic _"redirect_uri_mismatch"_ errors. Found that out at 3 AM when our staging-to-production migration broke login for half our users. Took me way too long to figure out it was just the callback URL.

GitHub OAuth, Google OAuth, Discord OAuth - they all have the same callback URL restrictions. Pro tip: set up multiple callback URLs for dev/staging/prod from day one, not when you're panicking about broken login flows.

Database Stuff (Prisma Underneath)

They use Prisma which is solid. Type safety, migrations that don't make you cry, the usual good stuff:

model User {
  id        Int      @id @default(autoincrement())
  tasks     Task[]
  createdAt DateTime @default(now())
}

model Task {
  id          Int     @id @default(autoincrement())
  description String
  isDone      Boolean @default(false)
  user        User    @relation(fields: [userId], references: [id])
  userId      Int
}

The generated queries are type-safe and integrate with React Query for caching. Less database boilerplate, fewer bugs.

Mess up the database schema migration and your app explodes at runtime with helpful errors like `Unknown arg 'newColumn'`. Always run wasp db migrate after schema changes or things break. Check the Prisma migration docs and Wasp database guide.

I hit N+1 query problems loading a dashboard with 100+ tasks. Page was taking like 8 seconds to load because each task was firing its own query to get the user info. Generated queries aren't always smart - I had to write custom Prisma includes to fix it. The Prisma performance guide helps when things get slow.

Job Queue Works Fine

Uses PgBoss for background jobs. Works fine for simple stuff like sending emails. Complex job dependencies? You're on your own. SQLite support? Nope, PostgreSQL only.

WebSocket Stuff Is Half-Baked

WebSocket support exists but the docs suck and you'll write most of the real-time code yourself. Connections drop on cheap hosting like Heroku. Just use Pusher instead if you need real-time features.

Deployment Sometimes Works

`wasp deploy fly` works when it works. When it doesn't, you get "Build failed" which tells you absolutely nothing. Check the Fly.io logs or Railway deployment logs to figure out what broke. The Wasp deployment docs are decent but light on troubleshooting.

Docker builds assume Linux. Mac users, use `--platform linux/amd64` or enjoy debugging architecture mismatch errors.

Dev Experience Is Okay

Hot reload usually works. When it breaks (often), restart everything and pray. VS Code extension is decent, no IntelliJ support yet. WebStorm users are SOL.

Generated TypeScript types get out of sync sometimes. Just restart the dev server when TypeScript starts complaining about missing types. The language server helps but isn't perfect.

Bottom Line

Good for CRUD prototypes. Probably too risky for anything your boss cares about until version 1.0 ships.

The practical reality: When Wasp works, it saves you weeks. When it breaks, you're debugging Haskell compiler errors at 2 AM. Auth and database stuff are solid. Everything else feels half-finished.

Ready to actually try it? Let's get into the installation nightmare...

So you've decided to ignore the warnings and try Wasp anyway. Smart. Wasp installation takes 5 minutes when it works, 2+ hours when it doesn't. Here's what actually happens when you try to get started - the stuff the official docs gloss over.

Installation Hell

The happy path:

curl -sSL https://get.wasp.sh/installer.sh | sh
wasp new my-app
cd my-app && wasp start

What actually happens:

macOS/Linux: Usually works fine. The installer downloads a Haskell binary and adds it to your PATH.

Windows: Must use WSL. Native Windows support doesn't exist despite being "cross-platform." The installer script fails on PowerShell and Command Prompt.

Path issues: The installer adds ~/.local/bin to your PATH in ~/.bashrc, but if you use Zsh (default on macOS), it won't work. You'll get `wasp: command not found`. Add this to `~/.zshrc`:

export PATH=$HOME/.local/bin:$PATH

Version bullshit: I'm still on Node 18.16 because 19 broke something in my other projects. Wasp works fine with 18.x but might complain if you're on some ancient version. Check Node version compatibility in the docs.

What You Actually Need

• Node.js: 18+ (I use 18.16, haven't tried 20 yet)
• Database: PostgreSQL for production, SQLite for messing around
• OS: macOS, Linux, WSL 2 (WSL 1 is garbage, don't bother)
• Memory: 8GB+ or your laptop fan goes full jet engine during builds. First-time compilation caches everything so subsequent builds are faster.
• Disk: Couple gigs for all the npm dependencies plus generated code. The .wasp/ directory alone can be 200MB+ after compilation.

Project Creation (The Pain Points)

Simple template:

wasp new my-app
cd my-app
wasp start

First-time compilation takes 2-5 minutes. Wasp generates a ton of TypeScript and installs node_modules. Your CPU fan will spin up and your laptop gets hot. I usually grab coffee during the initial build because there's nothing else to do. Check the Wasp compilation process if you're curious how it works.

AI-Powered Generation (Gimmick Alert):

wasp new my-app
## Select \"AI\" option

Mage generates apps from descriptions. Cool demo, but the generated code is basic CRUD with auth. You'll rewrite 90% of it for any real app. Better to start with empty template and build incrementally. The Wasp examples are more useful than AI generation.

Templates:

• Open SaaS: Actually decent SaaS boilerplate with Stripe, but complex for beginners
• Todo App: Standard CRUD example - boring but educational
• Blog Platform: Broken last I checked, lots of missing styles

Project Structure (What Actually Matters)

my-app/
├── main.wasp              # The magic file - edit this constantly  
├── schema.prisma          # Database schema - careful with changes
├── src/
│   ├── client/           # React components (normal React code)
│   │   ├── pages/        # Your page components
│   │   └── components/   # Reusable components
│   └── server/           # Node.js backend  
│       ├── actions/      # Database mutations
│       ├── queries/      # Database reads
│       └── jobs/         # Background jobs (if using PostgreSQL)
├── .wasp/                # Generated code - NEVER EDIT (gets overwritten)
├── migrations/           # Prisma migrations - commit these to git
└── .env.server           # Environment variables (don't commit this)

Key gotcha: The .wasp/ directory contains all generated code. It gets recreated every time you run wasp start. Don't edit files in there or your changes disappear.

Configuration Reality

The main.wasp file defines everything:

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

page MainPage {
  component: import { MainPage } from \"@client/MainPage\",
  authRequired: true  // Page won't load without login
}

query getTasks {
  fn: import { getTasks } from \"@server/tasks.js\",
  entities: [Task]  // This enables automatic cache invalidation
}

Syntax is finicky: Missing commas break compilation. The error messages don't always point to the right line. Use the VS Code extension for syntax highlighting.

Development Workflow (The Truth)

wasp start        # Start dev server (takes 30+ seconds first time)
wasp db migrate   # Run after schema changes or app breaks  
wasp build        # Build for production (takes 2-5 minutes)

Development cycle:

1. Change .wasp file
2. Wait for recompilation (10-30 seconds)
3. Change React components (fast hot reload)
4. Change server code (restart required sometimes)
5. Change database schema → run wasp db migrate or everything breaks

When things break: Restart the dev server. Still broken? Delete .wasp/ and node_modules, then restart. Still broken? Hit up Discord and hope someone else hit the same weird edge case.

Testing (Basic Support)

Testing exists but it's not great:

// src/server/tasks.test.js
import { getTasks } from './tasks.js'

test('getTasks works', async () => {
  // Mock context manually - no helpers
  const context = { user: { id: 1 }, entities: mockPrisma }
  const tasks = await getTasks({}, context)
  expect(tasks).toBeDefined()
})

Reality: Most people skip tests because the mocking setup is tedious. Better to focus on integration tests with Playwright after deployment.

Deployment (When It Works)

Railway (easiest):

wasp deploy fly
## Usually works, sometimes breaks on Node version conflicts

Self-hosting (Docker):

wasp build
## Generates Docker files
docker build -t my-app .
docker run -p 3000:3000 my-app

Production gotchas:

• Environment variables need to be set correctly or auth breaks. Missing WASP_WEB_CLIENT_URL will break OAuth redirects.
• Database migrations run automatically, but can fail if schema changes are complex. Always test migrations on a staging environment first.
• Generated Docker files are large (500MB+) due to all the dependencies. Not great for cold starts on serverless platforms.
• SSL certificates matter - HTTP won't work for OAuth in production (learned this the expensive way).

Bottom line: Great for prototypes, decent for simple production apps, painful for complex requirements. Worth trying if you're tired of configuration hell, but have a backup plan.

My honest take after using it for 6 months: The auth and basic CRUD stuff saves massive time. I probably saved 20+ hours not having to deal with NextAuth sessions and cookie nonsense. Everything else (WebSockets, complex deployments, custom integrations) feels unfinished. Perfect for side projects and MVPs. Risky for anything mission-critical where downtime costs money.

Now let's see how Wasp stacks up against the alternatives you're probably considering...