English for Wasp Framework Developers
Vocabulary for developers building full-stack apps with Wasp — the declarative config DSL, entities, actions, queries, and auth — for teams discussing full-stack scaffolding in English.
Wasp is a full-stack framework that uses a declarative configuration language (main.wasp) to wire up a React frontend, a Node.js backend, and a Prisma-backed database with far less boilerplate than assembling the pieces yourself. Its vocabulary blends familiar full-stack terms — “entities,” “queries,” “actions” — with its own DSL concepts. If your team evaluates or builds with Wasp, here’s the English you’ll need for design discussions and code reviews.
The Config Language
main.wasp file — the central declarative file where you define pages, routes, entities, and operations; Wasp generates the boilerplate glue code from it.
“Before touching any React code, check the main.wasp file — the route and page wiring is declared there, not scattered across the codebase.”
Declarative configuration — describing what your app needs (a route, an auth-protected page) rather than writing the how by hand. “Adding a new authenticated route is one line in the config — Wasp generates the guard logic for us instead of us writing it manually.”
Code generation — Wasp reads the config and generates the supporting React Router setup, Express routes, and Prisma client wiring automatically. “Don’t hand-edit the generated files — they’re regenerated on every build, so any manual change there will just be overwritten.”
Data and Operations
Entity
An entity is a Wasp concept mapped directly to a Prisma model — the core data types your app persists.
“We added a
Commententity to the schema, and Wasp automatically made a Prisma-backed table for it — no separate migration file to write by hand.”
Query
A query in Wasp is a read operation — a typed function you define on the backend that the frontend calls through an auto-generated, type-safe hook.
“The
getTasksquery is fully typed end-to-end — if I add a field on the backend, TypeScript immediately flags every place on the frontend that needs updating.”
Action
An action is a write operation — the counterpart to a query, used for anything that mutates data (creating, updating, deleting).
“We split the
updateTaskaction from thegetTasksquery deliberately — Wasp automatically invalidates and refetches the right queries after an action runs.”
Automatic Cache Invalidation
Wasp queries are automatically invalidated and refetched when a related action runs, so the frontend stays in sync without manually calling refetch() everywhere.
“We didn’t write a single cache-invalidation call by hand — Wasp knows the
updateTaskaction affects thegetTasksquery and refreshes it automatically.”
Auth and Pages
Full-stack auth — Wasp provides built-in support for username/password, social login, and email verification flows, generated from a few config lines rather than a separate auth library integration.
“Setting up Google login took maybe ten minutes — the auth flow, session handling, and protected routes are all handled by Wasp’s built-in auth.”
Protected page — a page declared in the config as requiring authentication; Wasp generates the redirect logic for unauthenticated visitors automatically.
“Marking the dashboard page as
authRequired: truewas enough — anonymous visitors are redirected to login without us writing that check manually.”
Job — a Wasp concept for background or scheduled tasks (like sending a digest email), configured declaratively and run outside the request/response cycle.
“The weekly digest email is defined as a scheduled job in the config — it runs independently of any user request.”
Deployment and Ejecting
Ejecting — the (rare, last-resort) process of stepping outside Wasp’s generated scaffolding to hand-write parts of the app when the framework’s abstractions don’t fit a specific need.
“We haven’t had to eject anything yet — the built-in operations have covered every use case so far, which says a lot about how well-scoped the abstraction is.”
Full-stack deploy — Wasp can deploy the frontend, backend, and database together with one command, rather than coordinating three separate deploy pipelines.
“
wasp deployhandled provisioning the database and deploying both the client and server — it’s the fastest zero-to-production setup I’ve used for a side project.”
Explaining Wasp to a Team
| Situation | Phrase |
|---|---|
| Justifying the framework choice | ”For an MVP with a standard CRUD shape, Wasp gets us a typed, full-stack app with auth working in days instead of weeks.” |
| Explaining generated code | ”Don’t edit the generated Prisma client directly — change the entity in main.wasp and let Wasp regenerate it.” |
| Describing the query/action split | ”Queries are for reads, actions are for writes — and Wasp automatically refetches the right queries after a related action runs.” |
| Discussing framework limits | ”If we outgrow the built-in operations for a specific complex flow, we can eject that piece without rewriting the whole app.” |
Common Mistakes
- Calling every backend function a “query” — in Wasp’s vocabulary, reads are queries and writes are actions, and mixing them up confuses the automatic cache invalidation.
- Saying “I edited the generated file” as if that’s a normal workflow — generated files are meant to be regenerated, not hand-maintained.
- Describing Wasp as “just a UI library” — it configures the frontend, backend, and database together, which is a different scope than a component library.
Practice Exercise
- Explain, in two sentences, the difference between a Wasp query and a Wasp action to someone new to the framework.
- Write a short PR description for adding a new entity and its corresponding query and action.
- Draft a message explaining why the team chose Wasp for a specific MVP, focused on time-to-first-deploy.