Wasp is a full-stack web framework for React and Node.js (imagine Rails for TypeScript, with but with frontend included and wired up out-of-the-box), and we've been building it for a little over five years (as a full-time thing). For almost all of that time, we saw design and "branding" as something we shouldn't spend too much time on.

A framework is mostly code, we thought: you drive it from a CLI and your editor, there is little visual to look at, and these days an agent reads the docs for you half the time anyway. The most loved frameworks kind of prove the point, with Django and Rails famous and famously plain.

Turns out we were wrong, though not in the way you'd expect. What made design start to matter wasn't users or growth - it was us, the people building Wasp and the community around it.

This is the story of how we figured that out, and of the rebrand it led to, which shipped as part of Launch Week #12 - the same week Wasp went fully TypeScript-native.

Five years of not having a design​

Wasp has always had a logo, colors and fonts (ok, the fonts were whatever shipped with Docusaurus). So when I say we didn't have a design, I mean we never sat down to think about it as a whole. There was no central story, no backbone holding everything together, just a bunch of pages that happened to be ours.

Here's how it typically went down: with every big release (v0, Alpha, Beta), I'd sit down and convince Martin (my twin brother and co-founder) to let me "rebrand" Wasp. And every single time, I'd do almost the exact same thing: look around for some inspiration (thanks, Supabase), then patch, okay, steal, a few sections together into something that looked decent enough, and ship it.

And early on, that was the right call. When you're still proving the product deserves to exist, obsessing over a design system is a great way to burn weeks you don't really have. Plenty of founders do the opposite. They polish pixels on something nobody wants yet (and we witnessed that many times) and we were determined not to be them.

But design debt compounds, just like code debt does. Over five years, Wasp itself grew up a lot, and it grew much faster than its design did, until at some point it just overgrew it. The framework got serious, but the brand stayed improvised. You can kind of watch it happen across our old landing pages:

stic (before it was called wasp), 2019

01 / 04

‹›

And once our design felt broken, there was little motivation to keep it right, so it just kept getting worse. At one point we needed to show a roadmap on the site, so Martin just screenshotted our GitHub project board and pasted it straight in. Low-res, rounded corners not quite matching, with some random background bleeding out around the edges. It stayed up like that for an embarrassingly long time:

Or take the "How does it work?" section right below it. The diagram was originally drawn as a transparent SVG, which broke once the site got a dark mode, so someone slapped a white background behind it to "fix" it. Now it looked fine on the dark version, and noticeably worse everywhere else. Add the orange highlight pills next to the copy, styled in a completely different visual language than anything else on the page, and the whole thing kind of looked like three different sites stitched together:

At some point we just started to feel bad about how unpolished it looked. We couldn't really tell you what users made of it (probably not much), but we could feel it ourselves: Wasp had grown into a serious product that people use for serious things, and it was about time it started looking like one.

Looking unpolished made us feel unpolished​

There was also another reason for finally taking design seriously, harder to pin down, but looking back it's pretty obvious.

Looking unpolished slowly does something to you. Every time we shipped a great feature next to a website that looked like a slightly abandoned student project, it sent a quiet little signal we never really meant to send: that maybe we don't actually care all that much. And that signal doesn't only go out to users; it also comes back in. A product that looks like nobody sweated the details slowly starts to feel like one to the people building it, even when, internally, the opposite is completely true.

You don't really notice it on any given day, but over five years it compounds. You hesitate a bit before posting the screenshot. You add a caveat before the demo ("ignore how it looks for a second, just look at what it does"). You quietly stop wanting to share Wasp with someone whose opinion you actually care about, because they might judge the wrapper instead of the thing inside. And it gets hard to pour your full energy into something you're a tiny bit embarrassed by.

So in a real sense, a good part of this rebrand wasn't for users at all. It was for us. We wanted to be able to look at every surface Wasp touches and not flinch, and to feel like the way Wasp looks finally matches how much we actually care about it. Looking back, that's not really vanity but basic hygiene, and we should've done it sooner.

The product changed, so the skin had to​

When we made the call to go all-in on TypeScript, we knew it wasn't a facelift. It changed what Wasp fundamentally is: not a custom language you have to learn, but a framework that meets you where you already are.

That forced an uncomfortable question: if someone landed on wasp.sh today, would they actually see that? Honestly, no. The old look still said "quirky side project with a custom language", while the new Wasp is something else: a serious, full-stack TypeScript framework you'd reach for to build a real product. The caterpillar was getting its wings (ok, wasp, but you get the idea), and it couldn't really keep wearing the old skin.

So instead of asking ourselves "what looks nice?", we ended up asking a much better question: what is Wasp, actually?

Wasp is a spec. So the brand is a blueprint.​

The core idea behind Wasp has always been the same, DSL or no DSL: you declare what your app is (routes, pages, auth, jobs, the whole skeleton), and Wasp handles all the plumbing under the hood. The high-level spec you define in TypeScript is essentially an engineering drawing of your application, and the framework just builds it.

(Quick side note: "Wasp" itself stands for Web Application SPecification - which is basically how we've always thought about it.)

But before we landed there, we explored a lot of other directions. Some internal attempts (mostly me prompting Nano Banana), and we also briefly worked with a few designers who came back with their own takes. AI turned out to be genuinely useful in this phase: you can iterate on entire landing-page mockups in a few minutes and quickly see what does and what doesn't feel like Wasp, and build intuition for what you like. Here's one of mine:

And here's a small sample of what the designers sent over:

After cycling through enough of these, the visual direction we wanted got pretty obvious. Wasp's brand should look like what it is: a technical spec. Blueprints, schematics, annotated diagrams: the kind of stuff engineers draw before they go and build.

That single idea ended up driving basically everything in the new identity:

Monospace first. Our primary typeface is JetBrains Mono, backed by IBM Plex Mono. Monospace is the native typography of our world and we just really like how it looks. We were deliberating about using monospace literally everywhere, but in the end decided to settle on titles and subtitles, while the body text in the docs and the blog is IMB Plex Sans - easier on the eyes, but still feels close to the monospace aesthetic.

Three colors, and that's it. Wasp Yellow (#F5C842), Ink Black (#111), and a warm paper tone we call Blueprint Paper (#F7F5F0). Yellow and black because, well, wasp. Paper because real engineering drawings live on paper, not on gradients.

Sharp corners, visible structure. 90° angles, 2px strokes, no rounded-blob softness anywhere. Our illustrations aren't there to decorate the page. They're schematics: boxes, connectors, annotations, the architecture of your app drawn like a circuit diagram.

The mark. The =} symbol, set in a solid square. It's pulled straight from code, works at any size from a favicon to a billboard, and if you squint a bit it still reads as a wasp's wings and antennae. It didn't arrive fully formed, though. The project actually started life as stick (yes, there was a literal photo of a wooden stick), then stic (Specification to Implementation Compiler), and finally wasp. The =} itself only showed up around the Alpha launch in 2020, sitting inside a yellow circle. The 2026 rebrand was basically the moment we finally squared it off and stopped fiddling with it:

Light, on purpose. One thing we very deliberately kept: Wasp stays light theme-first. It would have been the easy, default move to go dark-mode-everything and look like every other devtool out there. But people have always told us that Wasp's look feels happy (warm and approachable in a category that mostly reads as cold and serious), and we didn't want to just throw that away to become another Linear clone. The world already has plenty of near-black landing pages with a purple gradient on top. Blueprint paper is bright, optimistic, and it's ours.

Constraints are the whole point - both in design and code​

Here's the part we honestly didn't expect: the best thing about the new brand isn't really how it looks, but how fast it now makes us move.

Two fonts, three colors, one illustration style, and only sharp corners. It sounds restrictive on paper, and it is, but in the best possible way. Before, no one really knew what to reach for, so everyone would just do their own thing each time. Now there's almost nothing to decide. A launch banner, a chart for Twitter, a docs page, a sticker - they all kind of assemble themselves from the same small kit. It's actually the same philosophy as Wasp itself: strong defaults and clear structure don't limit you - they free you up to focus on the parts that actually matter.

We even wrote ourselves a proper brandbook in the end, partly because we genuinely needed one, and partly because after five years of winging it, it just felt really, really good to finally have one.

We shipped it like a rolling release​

We didn't flip a switch one morning and unveil a finished new site. We rolled it out the same way we ship software: piece by piece, swapping new parts in while the old ones were still live.

So for a while, wasp.sh was a bit of a Frankenstein (honestly, it kind of still is). A shiny new hero sitting on top of an old footer, new buttons next to old cards, fonts not quite agreeing with each other across the page. It looked pretty rough, but the old site already looked rough, so a half-migrated version was still a step up, not a regression. The bar, luckily for us, was very forgiving.

And honestly, the awkwardness actually helped. Having a half-finished site sitting out in the open was a little embarrassing, which was kind of the whole point. Nobody really wants a Frankenstein page on the internet with their name on it, so we kept sprinting to fix the next piece before too many people saw it in that state. The embarrassment basically became a deadline we couldn't ignore.

And it was the only realistic way we were ever going to get it done. If we'd waited to perfect every pixel and ship it all at once, we'd genuinely still be waiting today. Wasp moves too fast for a big-bang redesign. By the time it was "done", half of it would already be stale. Shipping it in pieces is what actually kept us moving.

Designing it changed what we think Wasp is​

Another thing we found really valuable about this whole process had nothing to do with how anything looked.

To draw a thing, you first have to know what the thing actually is. So every design decision kept bouncing back at us as a product question: who is this really for, what do we stand for, what do we actually want to say. Before we knew it, the rebrand had quietly turned into a rewrite. We reworked our words, our positioning, our whole story, and then the new words changed the design, and the new design changed the words again. The two kept reshaping and reinforcing each other.

That loop is exactly why we're glad we didn't just hand this whole thing off to someone external. An agency can absolutely make you look good. What it can't really do is the part that turned out to matter most: the way designing the brand forces you to understand, and sometimes redraw, the product itself. That kind of thing only really happens when the people building the product are also the ones drawing it.

What do you think?​

The new look is now live on wasp.sh, across our docs, and everywhere else Wasp shows up. Like everything we ship, it'll keep evolving, and we'd love your honest take: the good, the bad, and the "did it really have to be monospace?".

Come tell us on Discord, Twitter/X, or GitHub. 🐝

One of the main tricks they pull is quietly turning your folder structure into a config file. Create app/about-us/page.tsx in a Next.js app and https://localhost:3000/about-us magically starts working. Rename the file, and the URL changes with it. The framework is reading your file tree and turning it into a routing table.

That is called file-based routing, and it's usually magic your framework either hands you or it doesn't; and when it does, you rarely get to customize it, the conventions are baked in. Want a folder name to carry special meaning, or a logged-in.tsx/logged-out.tsx split per route? Your only option is to post a feature request and wait, or go without.

In Wasp, we really like explicitness, so we've resisted shipping a file-based router. That's changing now, but of course, we're not just adding the magic conventions and moving on. We're giving you a way to choose and design your own magic.

Wait, what's Wasp?​

Wasp is a batteries-included full-stack web framework for TypeScript. It covers your frontend, backend, and database as one cohesive whole.

And one of our core ideas is that the entry point to all this full-stack goodness is through an explicit Spec. Instead of hiding your app's structure behind implicit conventions, you declare its features (like routes, authentication, queries, cron jobs, etc) directly in code. Wasp then compiles and stitches these pieces together:

import { app, route, page } from "@wasp.sh/spec";

// `type: ref` means we just want to point to these files, not execute them now:
import MainPage from "./src/pages/MainPage" with { type: "ref" };
import UserPage from "./src/pages/LoginPage" with { type: "ref" };

export default app({
  // Some example configurations, we'll skip them in the future:
  name: "my-app",
  wasp: { version: "^0.24.0" },
  auth: { userEntity: "User", google: {} },

  // The spec is where you declare your app's features:
  spec: [
    route("MainRoute", "/", page(MainPage)),
    route("LoginRoute", "/login", page(UserPage, { authRequired: true })),
  ],
});

We chose this approach because explicit code is easier to reason about than hidden magic. This transparency makes the codebase easier to navigate for your team, and it gives AI code assistants a clear, structured map of your application to work with.

That explicitness is the whole philosophy, and it's exactly why we've deliberately never shipped file-based routing. We just didn't want to bake that pile of implicit conventions into the framework.

The Spec is just a program​

But here's the part that makes it exciting. We recently updated our spec so that it lives in a main.wasp.ts file. And instead of being a static JSON file that the framework reads, it is just a standard Node.js program, written in TypeScript. You can pull in libraries from npm, read from disk, call an API, use environment variables, anything! The only rule is that you export an app at the end. That's all we need.

So the Spec is explicit, but it's also programmable. And nothing says those route and page calls have to be typed out by hand.

That's the entire trick. You can write a function that walks your src/ folder and returns the same route and page objects you'd otherwise write manually. File-based routing stops being internal magic, and becomes a few lines of ordinary code that live in your repo, that you can read, and more importantly, customize.

So even though we never shipped file-based routing, "we didn't ship it" doesn't mean "you can't have it". You add it yourself, with exactly the conventions you want. You get the best of both worlds, and nobody has to argue about defaults. Sorry if you liked the arguing.

The simplest possible router​

Let's build that. Because the route list is just an array of objects, the simplest possible "router" is one we write out by hand:

// The `ref` helper is the dynamic version of `with { type: "ref" }` imports, so we'll use it to build programmatically.
import { app, page, route, ref } from "@wasp.sh/spec";

export default app({
  spec: [
    route(
      "RootRoute",
      "/",
      page(ref({ importDefault: "RootPage", from: "./src/page.tsx" })),
    ),
    route(
      "AboutUsRoute",
      "/about-us",
      page(
        ref({ importDefault: "AboutUsPage", from: "./src/about-us/page.tsx" }),
      ),
    ),
  ],
});

That's a functioning router already, but the unsatisfying part is that we had to type it out ourselves. So let's generate it instead, by looking at the project files.

The step up: generate the routes from the filesystem​

We'll pick a very simple convention: a page.tsx inside a folder makes it a route. So src/about-us/page.tsx serves https://my-app.com/about-us, and src/page.tsx serves https://my-app.com/.

Here's the whole thing:

import { page, ref, route } from "@wasp.sh/spec";
import { pascalCase } from "es-toolkit";
import { globSync } from "node:fs";
import * as path from "node:path";

export const fileBasedRoutes = (baseDir: string) => {
  return globSync("**/page.tsx", { cwd: baseDir })
    .sort() // Make the list stable between runs
    .map((filePath) => {
      const absoluteFilePath = path.resolve(baseDir, filePath);

      const urlRoute = filePath
        .split(path.sep)
        .slice(0, -1) // Removes the "page.tsx" part
        .join("/");

      const routeName = pascalCase(urlRoute) || "Root";

      return route(
        `${routeName}Route`,
        "/" + urlRoute,
        page(
          ref({
            importDefault: `${routeName}Page`,
            from: absoluteFilePath,
          }),
        ),
      );
    });
};

That's the entire idea. Find every page.tsx, turn its folder path into a URL path and a name, and produce the route()s. For the route name we can even lean on an npm package to get a clean name; it's just an ordinary npm dependency, like in any Node project.

There's nothing clever going on here, it's plain filesystem glue. An inexperienced dev could write this without much trouble. It never reaches into Wasp's internals, and it only calls the same public route, page, and ref functions you'd use by hand.

Wiring it into your app is one line:

// main.wasp.ts
import { app } from "@wasp.sh/spec";
import { fileBasedRoutes } from "./lib/file-based-routes.wasp";

export default app({
  // ...
  spec: [
    fileBasedRoutes("src"),

    // Any other Specs your app uses (job(), query(), action(), ...)
    // ...
  ],
});

fileBasedRoutes returns an array of route objects, and we drop it straight into spec. Voilà, you have file-based routing!

Everything Wasp already does still works​

Because we're producing normal route and page spec objects, the rest of Wasp neither knows nor cares that they were generated. So all the features you'd expect keep working, including type-safe links:

import { Link } from "wasp/client/router";

export default function MainPage() {
  return (
    <>
      <h1>Main page</h1>
      <Link to="/about-us">About us</Link>
    </>
  );
}

The <Link> component is fully typechecked with the routes your function generated. Generate a route from a folder, and you will get autocomplete and type errors for it everywhere. Nice.

Now make it yours: route groups​

Here's where it gets fun. This is your code, so bend it to your project. Say you want route groups: folders that organize your files without showing up in the URL. The usual convention is to wrap them in parentheses, like (marketing).

It's a one-line filter:

const ROUTE_GROUP_REGEX = /^\(.*\)$/; // Wrapped in parentheses

// ...

const urlRoute = filePath
  .split(path.sep)
  .slice(0, -1) // Removes the "page.tsx" part
  .filter((part) => !ROUTE_GROUP_REGEX.test(part)) // Remove any route groups
  .join("/");

Now src/(marketing)/about-us/page.tsx still serves /about-us, but you can keep your marketing pages tidily grouped.

A convention for prerender and auth​

Now let's say that in your project, there are two settings you're reaching for constantly: marking a page as auth-required, or marking it for prerendering. Let's invent a convention for both, reusing the route-group syntax we just added: an (auth) group makes everything inside require auth, and a (prerender) group marks pages for prerendering.

We detect those folders and thread the result into the spec objects:

const isPrerender = filePath.includes("(prerender)");
const isAuth = filePath.includes("(auth)");

// ...

return route(
  `${routeName}Route`,
  "/" + urlRoute,
  page(
    ref({
      importDefault: `${routeName}Page`,
      from: absoluteFilePath,
    }),
    { authRequired: isAuth },
  ),
  { prerender: isPrerender },
);

These are your conventions. Don't like parentheses for this? Use a .auth.tsx suffix, a "use auth" directive, or a config file next to the page; whatever reads best for your team. The spec doesn't dictate the shape, you do!

Dynamic and optional segments​

Wasp routing also supports dynamic (:id) and optional (:id?) segments. Written out in the spec by hand, they look like this:

route("ProductRoute", "/products/:productId", page(ProductPage)),
route("ArticleRoute", "/articles/:slug?", page(ArticlePage)),

The : character is not allowed in file paths, so let's copy Next.js's bracket syntax for this: [productId] becomes :productId, and [[productId]] becomes :productId?:

const DYNAMIC_SEGMENT_REGEX = /^\[(.*)\]$/; // Wrapped in square brackets
const OPTIONAL_SEGMENT_REGEX = /^\[\[(.*)\]\]$/; // Wrapped in two square brackets

// ...

const urlRoute = filePath
  .split(path.sep)
  .slice(0, -1) // Removes the "page.tsx" part
  .filter((part) => !ROUTE_GROUP_REGEX.test(part)) // Remove any route groups
  .map((part) => part.replace(OPTIONAL_SEGMENT_REGEX, ":$1?")) // Convert optional segments
  .map((part) => part.replace(DYNAMIC_SEGMENT_REGEX, ":$1")) // Convert dynamic segments
  .join("/");

Or you can invent your own syntax. The point is that it's just code, so you do you.

45 lines later​

We're done!

import { page, ref, route } from "@wasp.sh/spec";
import { pascalCase } from "es-toolkit";
import { globSync } from "node:fs";
import * as path from "node:path";

const ROUTE_GROUP_REGEX = /^\(.*\)$/; // Wrapped in parentheses
const DYNAMIC_SEGMENT_REGEX = /^\[(.*)\]$/; // Wrapped in square brackets
const OPTIONAL_SEGMENT_REGEX = /^\[\[(.*)\]\]$/; // Wrapped in two square brackets

export const fileBasedRoutes = (baseDir: string) => {
  return globSync("**/page.tsx", { cwd: baseDir })
    .sort() // Make the list stable between runs
    .map((filePath) => {
      const absoluteFilePath = path.resolve(baseDir, filePath);

      const isPrerender = filePath.includes("(prerender)");
      const isAuth = filePath.includes("(auth)");

      const urlRoute = filePath
        .split(path.sep)
        .slice(0, -1) // Removes the "page.tsx" part
        .filter((part) => !ROUTE_GROUP_REGEX.test(part)) // Remove any route groups
        .map((part) => part.replace(OPTIONAL_SEGMENT_REGEX, ":$1?")) // Convert optional segments
        .map((part) => part.replace(DYNAMIC_SEGMENT_REGEX, ":$1")) // Convert dynamic segments
        .join("/");

      const routeName = pascalCase(urlRoute) || "Root";

      return route(
        `${routeName}Route`,
        "/" + urlRoute,
        page(
          ref({
            importDefault: `${routeName}Page`,
            from: absoluteFilePath,
          }),
          { authRequired: isAuth },
        ),
        { prerender: isPrerender },
      );
    });
};

That's it. You can start using these conventions as you see fit. For example, with the folder layout below:

src/
├── (prerender)/
│   └── (marketing)/
│       ├── page.tsx
│       └── about-us/
│           └── page.tsx
├── products/
│   └── [productId]
│       └── page.tsx
└── (auth)/
    └── dashboard/
        └── page.tsx

...our function produces this spec:

export default app({
  spec: [
    fileBasedRoutes("src"),

    // the above call ⬆️ will turn into the following specs ⬇️

    route("RootPage", "/", page(RootPage), { prerender: true }),
    route("AboutUsPage", "/about-us", page(AboutUsPage), { prerender: true }),
    route("ProductIdPage", "/products/:productId", page(ProductIdPage)),
    route("DashboardPage", "/dashboard", page(DashboardPage), { authRequired: true }),
  ],
});

Add more files in that (auth), and those pages become auth-required; name a folder [[slug]] and you get an optional segment. We've covered the most useful bits of Wasp's routing and exposed them through an entirely new API surface, and all of it lives in under 50 lines you can read end to end in a minute.

And the same trick isn't limited to routes. Because the spec is just data your program returns, you can generate any of it the same way: api(), query(), job(), or action(), all from your own file layout. With other frameworks you might need weird hacks or an escape hatch to do this, but in Wasp there's nothing to escape from.

This is the whole reason we keep going on about the spec being a first-class, programmable thing. It means that file-based routing didn't have to become a Wasp feature with a dozen options and an opt-out. It just became a small file you can control. Meta-meta-framework, anyone?

Roll your own​

Want a more full-featured file-based router than the version above? We are building one you can use or learn from: wasp-lang/file-based-routing. We're still working on it, but it has quite a few more features than the one here. Other people might create their own libraries, and you can use those too!

But the whole point of this post is that you don't have to use anyone's library. Run wasp new, copy our starting example, and build the conventions that fit your project.

The future​

The same "spec is just a program" idea doesn't stop at routing. We're actively working on full-stack modules: the idea that you'll be able to pull libraries that don't only contain backend or frontend code, but full-stack code, defined as a Spec. File-based routing might be a part of those specs in the future! But it all goes towards giving you the magic of conventions without losing control and explicitness when you want it.

If you come up with something good, we'd genuinely love to see it, come share it on our Discord!

Take payments, for example. Normally, we install the Stripe SDK or some nice payments UI library, but it always requires manual wiring. And that wiring bit, figuring out how to integrate libraries written by different people, is one of the most annoying parts of the job.

Yeah yeah, I know what you are thinking. LLMs are writing most of the code these days, who cares? Ok, but it's already been established: what's good for humans is good for LLMs. They like to be lazy too.

Agents love working with legos​

Opus, GPT, and the rest of the models out there adore "legos" (pre-built pieces of functionality): they speed up the scaffolding process and result in more secure apps. You shouldn't trust your agent with hand-rolled components, especially with parts that need to be vetted (auth, payments...). When you trust the agent with that, you pay for more tokens and have no idea where the security holes are.

But imagine those agents had access to well-tested, full-stack implementations of auth, payments, file upload, admin dashboard, etc. Ideally, these packaged legos would hide most of the complexity from us and offer our agents control knobs for the most important configuration. For example, the agents would only be dealing with 2 env variables and maybe 2 or 3 lines of config for tested, reliable, and secure Google auth.

Matt Pocock talks about how LLMs struggle when a feature is split across too many layers and too much ad hoc glue. He focuses on the concept of "deep modules" from A Philosophy of Software Design as one of the methods that help agents work in your codebase. We can define deep modules as a standalone part of our app that exposes a simple way to use it (a thin interface), but hides all the internal complexities of the actual implementation.

The legos I described are nothing more than deep modules themselves, having a thin interface for the agent to interact with while the complexity is tucked away.

Legos have a name: full-stack modules​

While developing Wasp, a JS full-stack framework, we keep researching other ecosystems (Rails, Laravel, Django, etc.) and finding ways how they figured out developer productivity. We kept finding these reusable legos, so we gave them a name: "full-stack modules". Let's define what we mean by that exactly.

We usually talk about applications in two ways:

1. One is by technical layers: backend server, frontend client, database.
2. The other is by vertical slices: a complete feature that runs through the whole stack. Payments is our standard example: backend logic, the button the user clicks, and the database model that stores the state. A full-stack module is one of these vertical slices.

In Rails and Laravel, you can install packages that ship a slice like this. Add the package and payments are covered. You are not assembling a model, a backend, and a UI by hand. You can install one package which was developed against the stable shape of these frameworks.

That is a real advantage developers in Rails and Laravel ecosystems have, and it matters even more in the AI age. You ship faster if you don't spend days figuring out payments. You are also safer if you lean on a battle-tested package instead of something you wrote (or generated) under time pressure. The same logic applies to LLMs. We rarely review every line they produce. So, the less custom glue we ask them to write, the better.

Researching full-stack modules in 11 frameworks​

To better understand the common patterns, I wanted to "feel" how full-stack modules work elsewhere. I can read the docs only so much, so I prefer playing around with code, trying to make some changes and see what kind of pushback the API will give me.

I gathered all the frameworks/libraries/tools that sounded interesting to me and looked like they had something to teach me. Then I sketched an app that would somehow use a full-stack module.

To make it easy to compare, I created a static HTML prototype and tried to flesh out the requirements:

• users can sign up / log in
• they can browse products
• they can buy products with Stripe
• they can see their purchased items

In all of the frameworks, we want to see the same webshop (same design, same capabilities).

Our webshop is made out of auth, payments, and products modules. In this exercise, we told the agent that the "payments" module must be implemented as a full-stack module. The idea was for the module to be reusable, and it can't make any assumptions about where it will be used.

We took all these requirements and built the same app in 11 different frameworks. See the list here: https://fsm-research.static.miho.dev

Playing around with the same webshop across different frameworks helped us understand how full-stack modules can be implemented. Different frameworks had different levels of support, which made the experience more or less enjoyable.

For example:

1. In some frameworks, sharing a full-stack feature is much more polished.
   1. For example, in Orchard Core, you define a Startup class which has the ability to register services, database migrations, and add client and server routes as soon as the payments module is registered.
   2. In Rails, once you install the payments engine, based on the Rails folder conventions, you get views, models, controllers, etc. automatically registered.
2. But in some, the experience of sharing a module was more hands-on.
   1. My experience with RedwoodJS was a bit less smooth. I had to install the package twice, once in the web app and then again in the api app. I had to manually define queries and re-export pages to get them registered.

Some of that is due to the design of the frameworks (e.g. serverless-first assumptions), some of it was due to wanting to allow more flexibility (e.g. database implementation is not owned by the framework).

For fun, we built a (very subjective) tier list of frameworks we tried based on their level of support for what we call full-stack modules: https://fsm-research.static.miho.dev/fsm-tier-list

Why there are no full-stack modules in JS​

Hm, if full-stack modules are so great, why aren't they a JS standard? I think it's useful to first define what full-stack modules need to be viable in an ecosystem.

Full-stack modules need:

1. A way to ship runtime code (React components, Node.js server code, etc.)
2. A way to ship glue (code that describes how pieces fit together)
3. A way to distribute an installable unit

JavaScript ecosystem has no shortage of great libraries, and in great part that's due to how easy it is to ship code with npm. I'd say that sorts out points 1 and 3: it's easy to ship and install libraries.

But, it's impossible to ship "glue" code, the code that connects, e.g. the Stripe SDK on the backend, the payment button, and your database storage layer. I mean, how could it work if there are so many different standards for every little thing in JS?

There is no standard full-stack layer you can rely on when shipping a library, so you can't really ship full-stack libraries.

One of the core reasons is that many popular frameworks are frontend-first, and nobody dares to own the full-stack concept: client, server, and the database. You need to opt into owning (and accept the maintenance burden) everything if you want to provide a consistent development surface.

When you have some stable surface, your libraries can actually make assumptions and be "braver", e.g. they can assume how the routing works or how to expose webhooks in your app.

Wasp is doing something about it​

So what are we doing about it? We are building a truly full-stack framework. We control the frontend, the backend, and the database layer. That puts us in a good position to ship a full-stack module system on a predictable stack, and later grow it into a registry.

The core feature of Wasp is its spec file, a TypeScript config where you describe your app's features like client routing, server queries and actions, async jobs, etc. You still write React and Node.js to implement your features, while Wasp's spec file is where you write the "glue" code.

The cool thing about the "glue" code being written in a TypeScript spec file means that we can also package it alongside the React and Node.js code. We then arrive at a full-stack module.

One package which ships:

• React and Node.js code,
• and the spec file that explains how to wire it all together.

I can hear you saying "This is all very exciting, but let's see some code", so, okay, okay, let's take a quick look at some of the technical details. Beware, this is all very experimental, but the concept is solid.

Let's see how we can extract a full-stack feature from your Wasp app, so you can reuse it in the next project or even across all your company's internal tooling.

Here's an example Wasp spec file:

// main.wasp.ts
// Regular Wasp app: the app owns the payments wiring.

import { action, api, app, page, query, route } from "@wasp.sh/spec";

import { LandingPage } from "./src/landing-page/LandingPage" with { type: "ref" };
import { PricingPage } from "./src/payment/PricingPage" with { type: "ref" };
import { CheckoutResultPage } from "./src/payment/CheckoutResultPage" with { type: "ref" };
import { generateCheckoutSession, getCustomerPortalUrl } from "./src/payment/operations" with { type: "ref" };
import { paymentsMiddlewareConfigFn, paymentsWebhook } from "./src/payment/webhook" with { type: "ref" };

export default app({
  // ...

  spec: [
    route("LandingPageRoute", "/", page(LandingPage), { prerender: true }),

    // Payments "glue" code
    route("PricingPageRoute", "/pricing", page(PricingPage), {
      prerender: true,
    }),
    route(
      "CheckoutResultRoute",
      "/checkout",
      page(CheckoutResultPage, { authRequired: true }),
    ),
    query(getCustomerPortalUrl, { entities: ["User"] }),
    action(generateCheckoutSession, { entities: ["User"] }),
    api("POST", "/payments-webhook", paymentsWebhook, {
      entities: ["User"],
      middlewareConfigFn: paymentsMiddlewareConfigFn,
    }),

    // ...
  ],
});

We see that to implement payments we need:

• two client pages: /pricing and /checkout
• two operations: getCustomerPortalUrl and generateCheckoutSession
• and a webhook endpoint at /payments-webhook

For each of those pieces, we also have runtime code in files like PricingPage.tsx and operations.ts.

So if we wanted to share this as an installable full-stack feature, we need to package both the runtime and the spec code. This way, Wasp knows how to wire the feature once installed.

Let's say we shipped stripePayments as an npm package. This is how using the full-stack module would look:

// main.wasp.ts
// Wasp app with a full-stack payments module.

import { app, page, route } from "@wasp.sh/spec";
import { stripePayments } from "@acme/stripe-payments/spec";

import { LandingPage } from "./src/landing-page/LandingPage" with { type: "ref" };

export default app({
  // ...

  spec: [
    route("LandingPageRoute", "/", page(LandingPage), { prerender: true }),

    stripePayments("Payments", {
      entities: { User: "User" },

      plans: {
        hobby: {
          kind: "subscription",
          priceIdEnvVar: "PAYMENTS_HOBBY_SUBSCRIPTION_PLAN_ID",
        },
        pro: {
          kind: "subscription",
          priceIdEnvVar: "PAYMENTS_PRO_SUBSCRIPTION_PLAN_ID",
        },
        credits10: {
          kind: "credits",
          amount: 10,
          priceIdEnvVar: "PAYMENTS_CREDITS_10_PLAN_ID",
        },
      },
    }),

    // ...
  ],
});

In our example, you:

• import stripePayments from @acme/stripe-payments/spec,
• configure it with your app's payment plans,
• get the client pages, operations, and webhook endpoints set up automatically!

One extra fun fact: since the spec file is written in TypeScript, you can even fetch the info about your payment plans from a CMS or an API.

Full-stack modules will not fit every use case. So there should be escape hatches:

1. Shipping FSMs as npm packages gives authors flexibility to expose lower-level primitives. Users can rewire the high-level design without rewriting the implementation.
2. And of course, you can take the FSM code as a reference implementation and tweak it, reimplement pieces of it, etc.
3. Or even better, fork it with your tweaks and maintain an internal version specific to your organisation that you can use across your internal apps.

Open SaaS could become Open Anything​

At Wasp, we've built and maintain the most popular open-source SaaS boilerplate starter, Open SaaS.

It's already packed with features:

• payments
• auth methods
• file upload
• an LLM wrapper example
• etc.

But we're reluctant to add new ones, because it's already common for users to delete many features from the template to customize it (which is pretty meh from a DX perspective).

Let's imagine what full-stack modules would mean for starters like these. Instead of shipping a starter with all the features, you could maybe start with a nice design system and tell users to install features they need. A user building an LLM-powered site with subscriptions would only install the payments and LLM full-stack modules. Some other user might install only the admin panel and S3 file uploads full-stack modules, etc.

And those are only the modules we thought of so far. Imagine when the ecosystem has hundreds of community built modules, this starter becomes the most powerful starter in the world. And of course, the same modules could be used by any Wasp app out there.

Conclusion​

We've seen in other ecosystems how powerful these legos/full-stack modules are. Developers and LLMs that use them get more done plus have higher confidence in their apps.

We think it's possible to bring the same idea to the JS ecosystem.

The pieces we need to make it happen:

• a stable full-stack surface to work against,
• a way to ship together React components, Node.js code, and the "glue" code.

And that's exactly what we want to build with Wasp. Follow us on X or join our Discord to follow along.

Welcome to Day 3 of Launch Week #12, a.k.a. Community Day. This is the one where we step out of the way and let the Waspeteers do the talking. 🐝

We get one question more than any other: "okay, but what do people actually build with Wasp?" Today's the answer.

Four apps, four verticals that have basically nothing to do with each other (video tooling, UK property tech, e-commerce, and early-childhood education), all paid, all in production, all built by people from the Wasp community. It's been a minute since Vol. 1 back in 2023, and the bar has moved. Let's get into it.

CutCue - the AI editing intern for streamers (Wasp + Python workers)​

Try it out: cutcue.io · Pricing: €29 to €189/mo

Imagine you just streamed for six hours on Twitch and now you have to pull the three best clips for YouTube. Normally that's an evening of scrubbing the VOD with a coffee. Drop the recording into CutCue and you get back a timeline already marked up with highlights, chapter breaks, brand mentions, moments that could lose you ad revenue (e.g. swearing), and chat peaks, automatically.

The cool bit: the markers don't sit in some web dashboard you have to copy-paste from. CutCue exports straight into Premiere Pro, DaVinci Resolve, Vegas, Audacity, and Reaper, so they show up exactly where your timeline expects them. You open your editor, and the AI's homework is already on the canvas.

Under the hood: a Wasp app orchestrating four to five Dockerized Python workers (audio extraction, chapter detection, fingerprinting, queue management), self-hosted on Hetzner, built stateless from day one so it can scale horizontally when it needs to. The kicker: shipped by a backend-heavy engineer who'd never written React before this project.

"I described it usually as a baseline or a toolkit, the foundation for my project, which takes over the important stuff like session management, user payment, all the things which usually take a long time to build yourself and make stable and secure."

- the CutCue founder

Brick - a website builder for UK property operators​

Try it out: onbrick.co.uk · Pricing: £45 to £119/mo

Picture this: you're a UK landlord with three properties, and a prospective tenant just asked for your website. You... don't have one. Brick is the fastest way out of that conversation.

You tell it your business name and what kind of property you run (rent-to-rent, serviced accommodation, HMO, deal sourcing, development), and it spins up a full website in about five minutes: AI-generated copy tuned to your niche, a chatbot that captures leads while you're at a viewing, GDPR pages, SSL, daily backups, the lot. Each property niche gets its own template, so the sites don't all look the same.

ChatBuster - the AI chat that closes the sale, live on Shopify and WordPress​

Try it out: chatbuster.com · Pricing: from $40/mo · Where: Shopify App Store + WordPress.org

If you've ever shopped on a Shopify store and pinged the chat widget at midnight to ask "do you ship to Canada?", ChatBuster is the thing on the other end. Except now it's AI, trained on the merchant's actual catalog, theme, and policies, so it answers with the right number, the right policy, and the right SKU.

Under the hood: live catalog sync (SKUs, prices, stock update as the merchant updates), proactive prompts you can trigger on scroll or schedule, and order tracking through the store's API. A merchant installs it from the Shopify App Store or WordPress.org (the WP plugin went live in May 2026), flips one toggle, and it's working five minutes later. No developer required.

And it's not theoretical. Real merchants are already leaving five-star reviews:

PlanRelief - AI lesson plans for daycare and early-years educators​

Try it out: planrelief.io · Pricing: free to try · For: educators of ages 0 to 12

Imagine you're a daycare teacher and you spent the afternoon watching kids in the play corner. You jot down "Mia experimented with mixing colours." PlanRelief takes that one-line observation, plus a theme you pick ("rainbows and seasons"), and generates a full lesson plan: learning objectives, materials list, assessment strategies, the activity flow, ready to hand to a supervisor.

The pitch line is exactly what you'd want it to be: "paperwork done in minutes, not hours." Free to try, no credit card.

Build anything with Wasp, ship it, and get paying customers​

Four apps, zero overlap. Creator tools, property tech, e-commerce, classroom. All paid SaaS. All running in production. All built on the same framework you can install with one command.

That's the whole point of Community Day, really: when we say Wasp is a real fullstack framework, we mean real. Apps in real verticals, with real customers paying real money. The lineup looks very different from Vol. 1, and it'll look very different again the next time we do this.

If you've built something on Wasp that should be in Vol. 3, come say hi on Discord or X/Twitter. We'd love to feature you next time.

And if you haven't started yet, you're one command away:

npm i -g @wasp.sh/wasp-cli@latest

See you on Day 4. 🐝

Wasp is an opinionated, batteries-included full-stack JS/TS web app framework, built around the concept of an explicit spec for defining full-stack features of your app.

Today is a big day: we dropped our custom spec language and replaced it with a new, TypeScript-native way to define your full-stack app at a high level: the TypeScript Spec!

Read on for the why and the what, or if you want to try it out right now, go to the quick start guide.

Quick recap of the last 5 years​

Wasp is an opinionated, batteries-included, truly full-stack, spec-driven JS/TS web app framework, in spirit similar to RoR/Laravel/Django/Meteor, but reimagined from scratch for modern JS.

“Truly full-stack” because Wasp covers frontend, backend, and the database; Wasp’s goal is to capture the web app development end-to-end, in its entirety, as one cohesive whole.

“Spec-driven” because of Wasp’s unique, central concept of the spec (specification). It's in the name: Web App SPecification == Wasp.

Spec is a dedicated logic layer where you define your app at the full-stack level, that ties all parts of the stack together, and then you implement it all in the underlying technologies you are used to: React, Node, Prisma, … . It is the place where you are not writing frontend, backend, or database logic, you are writing "full-stack" logic.

So far, the spec layer in Wasp was implemented as a standalone language (DSL), with our own custom compiler and tooling. Turns out that was more trouble than it was worth, and it started blocking us in further growing Wasp into what we want it to become, so by popular demand, we switched to spec in TypeScript!

Read on to learn more about it, how it works and what it unlocks.

The Wasp TypeScript Spec​

You write the Wasp TypeScript Spec (TS Spec) in *.wasp.ts files by constructing the app spec object.

You do so by using the spec constructors from @wasp.sh/spec: page, route, query, job, api, … . That is your "vocabulary" that you use to specify the parts of your web app, and then compose them all together into one big app spec object.

import { app, page, query, route } from "@wasp.sh/spec";
import { MainPage } from "./src/MainPage" with { type: "ref" }; // React
import { getTasks } from "./src/tasks" with { type: "ref" }; // Node.js

export default app({
  wasp: { version: "^0.24.0" },
  title: "ToDo App",
  auth: {
    userEntity: "User",
    methods: { google: {}, gitHub: {}, email: {} },
    onAuthFailedRedirectTo: "/login"
  },
  spec: [
    route("RootRoute", "/", page(MainPage, {
      authRequired: true
    })),
    query(getTasks, { entities: ["Task"] })
  ]
});

Wasp takes the spec and the rest of your code (React, Node.js, schema.prisma, …), and builds them into a full-stack app.

In the example above, this app will have:

• Full-stack auth working out of the box (supporting Google, GitHub, or email & password auth).
• The src/MainPage.tsx React component mounted as the home page at /.
• The getTasks function from src/tasks.ts made callable from the client (e.g. from MainPage.tsx) via RPC, either directly or via TanStack Query.

💡 If you used the old Wasp DSL, you might be thinking at this point "hey this looks the same as before, maybe even a bit more verbose". True, but this is where the similarities stop, and exciting new possibilities start: read on.

While writing the spec, you are just writing TypeScript.
You can use third-party libraries, you can split the spec into multiple TypeScript files, you can define your own helper functions, use for loops, read from the disk, inspect env vars, you can organize your app vertically by features together with their spec, launch a rocket, … .
The only thing Wasp requires from you is that you export an app spec object from the main.wasp.ts file.

import { readFile } from "fs/promises";
import { app, page, route } from "@wasp.sh/spec";

import { authSpec } from "./src/auth/auth.wasp";
import { cardsSpec } from "./src/cards/cards.wasp";

import MainPage from "./src/cards/MainPage" with { type: "ref" };
import Layout from "./src/Layout" with { type: "ref" };

export default app({
  name: "waspello", // A Trello clone app made with Wasp!
  wasp: { version: "^0.24.0" },
  title: (await readFile("appTitle.txt", "utf-8")).trim(), // Reading from disk.
  auth: {
    userEntity: "User",
    methods: {
      usernameAndPassword: {},
      google: {},
    },
    onAuthFailedRedirectTo: "/login",
  },
  client: {
    rootComponent: Layout,
  },
  spec: [
    route("MainRoute", "/", page(MainPage, { authRequired: true })),
    // Parts of specification extracted into their own files.
    authSpec,
    cardsSpec,
  ],
});

// A specification for the "cards" functionality.

import { action, query, type Spec } from "@wasp.sh/spec";

import { withFields } from "../utils.wasp"; // Custom helper function.

import { createCard, updateCard } from "./cards" with { type: "ref" };
import {
  createList,
  createListCopy,
  deleteList,
  getListsAndCards,
  updateList,
} from "./lists" with { type: "ref" };

export const cardsSpec: Spec = [
  ...withFields({ entities: ["List"] }, [
    action(createList),
    action(updateList),
  ]),
  ...withFields({ entities: ["Card"] }, [
    action(createCard),
    action(updateCard),
  ]),
  ...withFields({ entities: ["List", "Card"] }, [
    query(getListsAndCards),
    action(deleteList, { entities: ["Log"] }),
    action(createListCopy),
  ]),
];

Those with { type: ref } imports you might have noticed in the code examples above?
That is how you connect the spec with the implementation (currently React, Node.js, Prisma), how you connect the full-stack "story" with the specific parts of the stack.
A bit of bundler magic happens there: with { type: ref } imports don't actually get evaluated, so no importing really happens, but instead they get transformed into objects that "reference" the import for later evaluation, that you then pass to the spec. You can even construct these directly as objects, inline, if you wish (useful if you are creating them dynamically): ref({ import: "getTasks", from: "./src/queries" }).

// Ref import
import { getTasks } from "./src/tasks" with { type: "ref" };
// gets transformed by bundler into
const getTasks = ref({ import: "getTasks", from: "./src/tasks" });
// where `ref` comes from
import { ref } from "@wasp.sh/spec";

That's it really! Wasp gives you the building blocks, and you do what you want with them, with the full power of TypeScript behind you.

Do not try this at home: implementing file-based routing in TS Spec​

An example of what is uniquely doable with Wasp's new TypeScript Spec (and wasn't possible with the old DSL): implementing file-based routing.

By default, Wasp doesn't come with file-based routing: instead, you define your routes explicitly in the spec:

// ...
  route("MainRoute", "/", page(Main, { authRequired: true })),
  route("SignupRoute", "/signup", page(SignupPage)),
  route("LoginRoute", "/login", page(LoginPage)),
// ...

But, let's say you want file-based routing nevertheless. With the new TypeScript spec you can do that in Wasp!

You could create, let's say, a fileRouter.wasp.ts that exports a helper function that reads the contents of the src/ dir and based on dirs and files produces an array of route and page spec objects.

For example, a file at path src/pages/(auth)/report/[id].tsx could result in

route("ReportRoute", "/report/:id", page(ReportPage, { authRequired: true }))

Import that function in your main.wasp.ts and add its output to the app.spec array, and that is it, you implemented your own custom file-based routing! What does this make Wasp: a meta-meta-framework?

If you are interested in the exact implementation, stay tuned: we will be publishing it as a separate post soon. If you implement it on your own in the meantime though, please share it with us, we would love to see how you did it!

Why spec(ification) at all?​

We mentioned the "spec" so many times in this article, but why should you care about it?

Why do we at Wasp care about it so much that we have spent years making and remaking the whole web framework around this idea, when every other "normal" JS web framework out there is focusing on data fetching, hydration strategies, tight integration with the UI library, … ?

All web frameworks, by definition, capture the domain/essence of what a web app is, give it structure, introduce their concepts, and then let you fill in the gaps, effectively separating the specification (what you want) from the implementation (how you want it). This lets you focus on the details of your business logic, what your app is really about (essential complexity), and implement it exactly how you want it, while the framework handles the rest of the details for you (accidental complexity) as you specified it.

What we are doing with the spec(ification) at Wasp though, is making that specification a first-class citizen in your app.

It's not convention based (e.g. magic names, dir structure, …), it's not implicit, it's not tied up in the runtime of the underlying stack. Instead, it is explicit, malleable, programmable, standalone, stack-agnostic, extendable. It has its own Turing-complete logic layer (thank you TypeScript), and just as you could write frontend or backend logic so far, now you can also write "app"/"full-stack" logic next to it. That logic has its own standalone runtime and can affect how the rest of the code is used and generated.

This means you can organize your spec as you want, you can reuse it, share/distribute it.

Right now the Wasp spec comes with a predefined "vocabulary": route, query, job, … , but we are excited about the idea of "extensible spec": being able to add your own "words" to it.

Or, imagine being able to take the whole vertical slice of your app, truly full-stack (fe, be, db, env, even infra), and making it a reusable, distributable unit with a defined interface (in spec) that can then be used and configured from anybody's spec. We are working on this currently under the working name of Full Stack Modules (FSMs).

Additionally, although now implemented in TypeScript, spec is standalone and therefore also stack and language agnostic. We could support writing (additional) backend logic in Python, Go or Rust in the future, you would just specify them in the spec (e.g. as queries and actions). We could add other frontend libraries next to React and spec wouldn’t change.

To summarize: we are doing the "spec" because we are excited about what gets unlocked when you make full-stack logic a "first-class" citizen in a batteries-included web framework.

Spec and AI​

Per design, as a full-stack, batteries-included framework, Wasp is in a position to work great with AI, due to the same reasons as Ruby on Rails, Laravel and others: less code to write, stronger constraints, clear best practices, one cohesive codebase, ... .

Wasp's spec, however, brings additional promise of serving as a central place where one can easily get a high-level overview of the app and the intention behind it, before getting lost in the implementation. Not just for AI, but also for you, especially if leaning harder into the "vibes".

Spec-driven approach to AI engineering is a popular method these days, with tools like OpenSpec or GitHub Spec Kit, where you write down the specification in Markdown files.
Wasp's spec takes this a level further: your spec is an actual, compiled part of your app, not Markdown files that drift with time. It is though much more constrained in what it can express at the moment, but we are excited to see how it evolves (e.g. once we make it extensible).

Finally, there is the possibility of Full Stack Modules, that Wasp spec unlocks: imagine being able to have truly full-stack pieces that you can test in isolation, reuse / distribute, and know they work? This means you can give AI bigger building blocks than normal, and ensure some things just can't get messed up: if I am using a Stripe payments full-stack module, AI can't just mess it up by accident.

Spec and you​

If you find all this interesting, we would love to hear from you (you can find us in our Discord server). This is the first iteration of the new TypeScript spec and any feedback helps us improve it: what you liked, what you didn't, what you would like to see in the future, anything goes.

You can try Wasp quickly by running npm i -g @wasp.sh/wasp-cli@latest, then wasp new, and then just follow the instructions, or go to our docs for detailed instructions and a tutorial.

If you are wondering why some part of Wasp is the way it is or how we plan to evolve it, you might find some answers quickly in our GitHub issues: we capture all our future ideas and plans there in the open (all ready for Cloudflare to slop-fork us, and then some). For a more high-level overview, there is Wasp Roadmap.

What's next?​

Wasp works as it is: we know of people selling startups made with Wasp, building internal apps in Fortune 500 companies, using it in banks. But we are still keeping Wasp in Beta till we fully flesh out the spec side of the story and also bring all the parts of it to the level we are satisfied with.

There are a couple of main categories of improvements we are chasing at the moment:

1. Spec: Further improving TS Spec design (e.g. bring data models into it), Full Stack Modules, spec extensibility, …
2. Wasp 1.0: Refurbishing core parts of Wasp (Auth, Operations, Jobs, Db, Routing/rendering, …) to bring them up to speed with the rest of Wasp, tightening our deployment/production features, …
3. Width: Explore adding support for other ORMs (e.g. Drizzle), other frontend libraries (e.g. Svelte, Vue), better support for mobile, maybe even add some infra as code and also support for other backend languages, …

As mentioned above, you can find much more detail on all of these in our GitHub issues and on the Wasp Roadmap.

Credits​

Big thanks to everybody who put in the time and effort to help us deliver the TS Spec and supported us on the way! Special thanks to @Reikon95, @Genyus, @devagrawal09, @AlemTuzlak, and the whole Wasp community, especially the amazing people on our Discord server.

A few weeks ago, we published a post with a title that raised a few eyebrows: "5 years and $5M later: inventing our own programming language was a mistake." Five years. One whole DSL. And we said it out loud, in public, on the internet, where it stays forever.

A lot of you wrote in afterwards (179, to be precise). Some to commiserate, some to cheer, a couple to ask if we were okay (we are, thank you). But the most common question by far was the obvious one:

"Okay… so what are you going to do about it?"

This is the moment where we answer that.

Caterpillars don't apologize for being caterpillars 🐛​

They just turn into something cooler, with wings (I know this doesn't work 100% for wasps, but licentia poetica, right?).

Welcome to Launch Week #12, a.k.a. MeTSamorphosis: the week Wasp finally sheds the DSL and emerges in its true, fully TypeScript-native form. No more learning a config language to use a framework. No more "wait, why is this a .wasp file?" Just TypeScript, all the way down, the same language you're already writing the rest of your app in.

This is the biggest shift in Wasp's history, so TS Spec is unapologetically the star of this launch. But it's far from the only thing we've got for you. There's pre-rendering/SSR support, a brand-new look for Wasp, and a few more surprises landing across the week. TS Spec leads the way, but none of the rest is filler.

But first - Thank you!​

Before we dive in, none of what's coming this week happens without you. The community around Wasp has never felt more alive, more people are shipping real apps with it than ever, and we don't take that for granted. So, genuinely: thank you. 🙏

The cocoon cracks open on Monday, June 15 🗓️​

There's no launch party without a nice, cozy community call to kick it all off! We're assembling on Monday, June 15th, 8 AM PT / 11 AM ET / 5 PM CET. Martin and I will be there live to walk you through TS Spec, take your questions, and probably get a little emotional about it.

Make sure to register for the event on our Discord and smash that "Interested" button so you don't miss it.

Here's some of what's hatching this week. A few of these are locked and loaded. A couple are still in the cocoon and might land later, or show up as a surprise. 🤫

🦋 The Big One - Adiós DSL, TS Spec is here​

This is the one. After five years, Wasp is now a TypeScript framework, end to end. You define your app (pages, routes, auth, jobs, the works) in TypeScript, with full type-safety and editor support, instead of a separate DSL you had to learn first.

We'll publish the full announcement to kick things off, walking through what changed, why it's better, and how to migrate. If you've ever wanted Wasp's superpowers without the "wait, what's this file" tax, this is the one for you.

⚡ New wings - SSR & pre-rendering​

A fresh form needs a fresh set of wings. We're also showing off server-side rendering / pre-rendering in Wasp: better SEO, faster first paint, and all the things you've been (politely, mostly) asking us for.

It's already live, so you don't even have to wait for the launch — check out the prerendering docs and try it on your app today.

Vinny also put together a video walking through it end to end. Keep an eye on YouTube for "Wasp now supports prerendering." 📺

🐝 The swarm - Community Day​

A Wasp tradition we love: the spotlight goes to you, the builders.

We're dropping "Made with Wasp, Vol. 2", a fresh roundup of genuinely cool apps people shipped on Wasp, plus videos and write-ups from community members on what they built and how Wasp helped. Real users showing real things hits different than us claiming Wasp is good, so we'll let them do the talking.

🎨 New look, who dis - the Rebrand​

A metamorphosis you can see. Wasp is getting a brand-new look (new visual identity, new vibe, the whole thing), and Boi's TS suit is just the start of it.

We'll also show you the new brand and, more interestingly, the story behind it: we'll talk through why we did it, how we got there, and what we were going for. (Spoiler: we have… opinions about monospace fonts.)

🚀 Out into the world - easier deploys​

A framework is only as good as the places it can fly to, so we've been working on making Wasp even easier to deploy to more of your favorite platforms. We're not spilling all the details yet, but if there's a host you've been wishing was one click away, keep an eye out. 👀

And because we can't help ourselves, there might be one more thing tucked away for you, too. You'll have to show up to find out.

See you on the other side of the cocoon 🐝​

That's the week: the molt, the wings, the swarm, the new look, and the take-off. We've been working toward this one for a long time, and we honestly can't wait to show you.

As always, we want all of your feedback: the good, the bad, and the "did Boi really need a suit." So come find us on Discord, Twitter/X, or GitHub. We're there.

To stay in the loop, follow us on X and join the Discord. See you Monday. 🐝🐝

Interestingly, he was able to build a functioning SaaS with paying customers, but he encountered endless problems whenever he tried to modify the app in any way.

So he tried to onboard a developer to help him. The dev opened the repo, went quiet for two minutes, and said: "what is this."

Six months of prompting led to a Frankenstein's monster of a codebase that is such a tangled mess, he's probably better off starting over from scratch. In his words, "nobody was thinking about structure. the AI just kept adding. new file here, duplicate function there, 3 different ways to handle the same thing across the codebase."

As the creator and maintainer of Open SaaS, I get a lot of people asking for help when building a SaaS with AI. And they get stuck for the same handful of reasons. Usually one of two ways: the first 70% comes together almost too easily and the last 30% becomes next to impossible, or you ship something that works, but you lack any understanding of what you built (like the redditor above), and therefore don't understand what you need to do to modify, extend, or improve your app.

So, with that in mind, let's look at some of my favorite ways you can avoid these problems, build something you understand, and stay in control.

📺 Prefer to watch? I walk through all five of these workflow tips with live demos in this video.

TL;DR​

The way out of a tangled, vibe-coded SaaS isn't to throw it all away and start over, rather it's a process that allows you to stay in control. AI is a great builder but you need to stay in charge of the decision making and understand the implementation process to avoid bigger problems down the line. Here are five tips that help you stay the architect:

1. Give your agent rails to run on — start on a solid SaaS boilerplate (like Open SaaS) and feed it official, AI-friendly docs (llms.txt) via memory and skill files.
2. Converse, don't command — don't open with "build me X." Have the agent interview you (clarify-first) and brainstorm options with pros and cons before it writes any code.
3. Understand the systems you're building on — you don't need to read every line of code, but you do need to know what a database, a payments provider, etc. actually do, so you can debug and ask the right questions.
4. Build in vertical slices — ship thin, working slices that touch the whole stack (UI → database), one small testable milestone at a time, instead of half-finished layers.
5. Verify each slice before moving on — test every milestone as you build so small problems surface early, not six months from now.

The good news and the bad news​

I won't oversell it. These five tips don't magically make your agent perform better for you without you having to put in some work.

The bad news is: it's still hard work.

The good news is: it's a lot easier than it used to be (and you don't need to know how to code to launch a SaaS this way).

If you're willing to understand some core concepts, and be patient and persistent, you'll definitely be able to build your idea, overcome issues, and get it launched.

So let's get into it.

The root cause: you let AI be the architect​

Here's the one mistake underneath all the others. "Nobody was thinking about structure. The AI just kept adding."

AI can be an incredible builder and a terrible architect at the same time. It optimizes for "make this work right now," not "keep this coherent over months." And it's so good at the building part that it's easy to get lazy and quietly hand over the architect role, or in some cases not think deeply about the architecture planning to begin with. Don't do this.

Your job is to be the architect and stay the architect. To do this, you need to work with your agent to plan every step of the process and implement things in a methodical manner. Everything below is a concrete way to make that happen.

1. Give your agent rails to run on​

When you're building software, there are a million ways to achieve the same thing. Rather than letting your agent guess at every turn, give it a predetermined path to follow.

The simplest way is to start on a solid boilerplate. A SaaS starter has the generic pieces (auth, payments, emails, jobs) already decided and wired up, so you just add your unique feature set. It also gives the agent patterns to imitate: it can look at how payments were wired up and slot your new feature in the same way, instead of inventing a third way to do it.

There are great options out there. ShipFast and SuperStarter are popular paid ones (around $300 each). Open SaaS is free and open source, has had people contributing to and hardening it for years, and is the most popular SaaS starter on GitHub with 14,500+ stars. Whichever you pick, you can't really go wrong as they all give your agent good code rails to work within.

The second set of rails is knowledge rails: always feed the agent the official, up-to-date docs of the tools you're using. Human docs are full of HTML and JavaScript fluff that eats your agent's context and buries the part that matters. That's why a lot of tools now publish an llms.txt which is a raw, AI-friendly version of their docs.

You don't want to paste those URLs in by hand every time, so put them where the agent will actually see them: memory files (AGENTS.md / CLAUDE.md) and skill files. Open SaaS ships with a short memory file that tells the agent where to find its llms.txt docs. For everything else, I keep a FetchDocs skill that holds the correct llms.txt URL for each tool, so the agent fetches the exact up-to-date guide it needs for the task at hand.

2. Converse, don't command​

The biggest prompting mistake people make is starting a fresh session with "build me X." You're the architect, but you might not yet know exactly what you want or the best way to build it. The good news is that the agent probably knows strategies you've never touched.

So have a conversation. Think of it as talking to a really smart, really patient friend who knows everything about software engineering and product development.

Here are two prompt types that I use all the time and that do most of the heavy lifting for me:

• Clarify-first: tell it your idea and have it interview you until you both reach a complete, shared understanding. ("I'd like to add a chatbot feature — ask me any questions you have so we reach a mutual understanding before moving forward.") It'll ask who it's for, which LLM provider, floating widget or dedicated page, whether to persist conversations — and you answer until the fog clears.
• Brainstorm with pros and cons: when you don't know your options, ask for several variations with their tradeoffs. ("Give me three implementation strategies with pros and cons, and we'll decide before building.") Three to five is usually the sweet spot, and the agent will even flag its own recommendation so you can weigh it against your constraints (like a budget you don't want to blow).

The point is to stop, take a step back, and not command right away. By commanding, you create an app that's a complete, tangled mess like the one from the reddit post above, because the agent will perform whatever request you give it, and that request might be a bad one.

By having a conversation with your agent, it will help you decide what the best course of action is. And when you decide, you have a better understanding of what's going on, and where things go wrong when they do.

3. Understand the systems you're building on​

A SaaS is just a bunch of existing tools pieced together in a creative way to solve a problem. You don't need to read every line of code, but you do need to understand the things being pieced together, like what a database is, how your payments provider is pieced together, and how the other pieces generally work.

That understanding is what lets you debug and ask the right questions when something breaks, instead of flailing in the wrong direction. A great move you can use along with your SaaS boilerplate starter is to ask your agent e.g.: fetch the llms.txt docs from Stripe and explain at a high level how payments work in my current codebase. Using your SaaS starter code to explain the concepts is the best way to learn. You can even start at a very high level (e.g. "explain like I'm five") before going deeper.

If that whole learning curve feels overwhelming and you want your hand held through it, I'm building Open Vibe, a free, open-source curriculum that lives inside your agent, set up on top of Open SaaS, and tutors you on the fundamentals while you build.

4. Build in vertical slices​

This is probably my favorite approach, and is the direct antidote to "the AI just kept adding." Instead of building half-finished layers, build thin, working slices that touch the whole stack, from the UI in the browser down to the database, so the feature actually does something at every step.

Say I want to make a generated schedule shareable in the planner app I'm building. I wouldn't say "make it shareable and build it." Instead, I'd ask the agent to design a feature plan with small milestones, one goal each, using a vertical slice approach.

As a result, we get a plan that we can get the agent to implement in small steps, and test that each small addition works before moving on, rather than implementing all the parts of a new feature in one shot and hoping that it works (or that we can debug it easily).

Such a plan for our sharing feature might look something like this:

1. Read a schedule by its ID at a public URL. Go to /schedule/<id>, see the schedule. Testable on its own.
2. Add a share button plus the small bit of data handling behind it.
3. Add a share token and the rest of the hardening.
4. ...

Each milestone is testable, vertically sliced, and has exactly one goal. Again, the complexity builds up in steps you can verify instead of one big leap.

Once the agent designs a plan you're happy with, save the plan to a file (schedule-sharing-implementation-plan.md) so you can reference it later in the chat, e.g.: "reference @schedule-sharing-implementation-plan.md and build milestone two."

That file is also a great context-management trick. Remember, agents don't have memory, only the context of the current session, and performance degrades as that context fills up. So I treat each milestone as a fresh session and /clear or /compact the conversation before moving on to the next milestone.

After clearing or starting a new session, I point the agent back at the implementation plan, and move on to the next milestone with a clean slate.

5. Verify each slice before moving on​

Vertical slices are only worth it if you actually test each one. It's better to surface small issues now, instead of six months from now like our poor protagonist in this story.

You can do it the "manual way", which is when something fails, copy the error, paste it into your agent with a bit of context, and let it fix it. Agents are surprisingly good at this. But hopping between terminal windows gets tedious, and some bugs are stubborn.

So hand the loop to the agent. One great tool is Claude Code's run-skill-generator. It's a skill that comes with Claude and it learns how to start your specific app within a running session and saves it as a custom reusable skill (e.g. /run-mysaasapp). You (or your agent) can run this skill and it essentially gives the agent "eyes" to see your client and server code, along with their respective logs.

With this run skill in hand, you can just say something like run my saas app and fix the issue. It will start the app with your /run-mysaasapp skill, read the server logs, drive the browser like a human would, find the error, fix it, and confirm it's running, completely hands-off.

The way out​

By staying the architect, and providing your agent with good structure and process, you can avoid most of the problems that plague builders trying to create their SaaS idea with AI.

I walk through all five of these with live demos (e.g. fetching llms.txt docs, the clarify-and-brainstorm prompts, the vertical-slice plan, and the agent fixing its own startup error) in the video:

▶️ How To Build A SaaS with AI. Without Getting Stuck.

And if you want the rails to start on:

• Open SaaS (free, open source, 14.5k+★): opensaas.sh
• Docs: docs.opensaas.sh
• Discord (come say hi, we're happy to help): discord.gg/rzdnErX

The blank page problem​

Single-page applications work by shipping an empty HTML shell to the browser, then letting JavaScript render everything on the client. That's great for rich interactive applications, but it means anything that reads your HTML before JavaScript runs sees... nothing.

This used to be "just" an SEO problem. But the web has changed. Googlebot did start running JavaScript; but new crawlers and AI assistants like ChatGPT, Claude, and Perplexity are trying to get your content to answer user questions. If your site is invisible to them, you're leaving traffic and visibility on the table.

The traditional fixes aren't great either. You could set up a separate static site generator, maintain a full SSR server, or bolt on a prerendering service. Each one adds complexity, infrastructure, and another thing to maintain. For a framework that prides itself on curation, we wanted something better.

The fix: prerender: true​

Here's what it looks like in Wasp 0.23:

route LandingRoute {
  path: "/",
  to: LandingPage,
  prerender: true
}

page LandingPage {
  component: import { LandingPage } from "@src/LandingPage"
}

That's it. One field. No config files, no extra server, no separate build pipeline.

When you run wasp build, Wasp renders that route's component to static HTML at build time. When a browser or crawler hits that URL, they get real, meaningful content immediately. Then React hydrates the page on the client for full interactivity. Your users get instant content, and your crawlers get something to actually read.

Every route without prerender keeps working exactly as before. You opt in per route, so you can choose which pages get prerendered and which stay dynamic. It's flexible and non-intrusive.

When to use it​

Prerendering is perfect for pages where the content is known at build time:

• Landing pages and marketing pages
• About, pricing, and FAQ pages
• Any mostly-static content that doesn't depend on the logged-in user

When not to use it​

Prerendering generates HTML once, at build time. That means it's not the right tool for pages that need to be different for each request:

• User dashboards and authenticated pages, where content depends on who's logged in, so there's nothing meaningful to render ahead of time.
• Pages that rely heavily on browser APIs, like reading from localStorage, geolocation, or other client-specific data that isn't available at build time.

For these cases, the regular SPA behavior works just fine. Prerendering is an opt-in upgrade for the pages that benefit from it, not something you need on every route.

How we got here​

This feature didn't happen overnight. We published a public RFC ("Deep Freeze") outlining the design, then built it in two stages: first the SSR rendering machinery under the hood, then the user-facing prerender field that wires it all together.

This is also a foundation. The SSR infrastructure we built opens the door to more rendering strategies down the road. Prerendering static routes is just the beginning, and rendering on the server in response to a request is on our roadmap for the future.

Giving back​

At the core of our prerendering approach is a Vite plugin built on the Vite Environments API. It handles the SSR rendering pipeline, HTML generation, and hydration wiring. We designed it from the get go as a self-contained project, and we're planning to extract it from our codebase and open-source this foundation once we stabilize it, so that other projects and frameworks can build on top of it too. Stay tuned.

Try it out​

If you're on Wasp 0.23, you can start prerendering routes right now. Pick your landing page, add prerender: true, build, and deploy. That's the whole migration.

Check out the full prerendering docs for details on how it works, limitations, and troubleshooting.

We'd love to hear how it works for you, come chat with us on Discord!

Our initial idea was to build a new programming language that would abstract common web app patterns while also working with any stack (we started with React, Node.js and Prisma) when you need to go deeper. Think Terraform, but for your web app stack instead of cloud infrastructure.

Five years in, we realize it was a mistake. Creating a new language makes sense for certain problems and domains, but in this case, it wasn't a fit and brought us more trouble than it was worth.

This post is about why we thought it was a good idea, what we learned, and why we're replacing our custom language with TypeScript, while Wasp itself stays the same under the hood.

TL;DR​

This is a long post. Here are the key things covered, so you can jump to what interests you without reading everything:

• Having switched web dev stacks for years, we thought it would be cool to create a "universal framework" that could work with any stack. We concluded we need to create a new language to achieve that.
• Developers resonated with the problem Wasp was solving, but the language was a tough sell. "Lang" in the name made them think our aim was to replace JavaScript (it wasn't) and were skeptical of how it'd work with their tooling.
• Many developers loved Wasp once they gave it a try. But getting them to try it out was the hard part.
• Adoption still grew, but as we kept pushing towards 1.0 we realised the "language" concern wasn't going away. Also, maintaining a good IDE experience for a custom language proved to be way harder than expected.
• It turned out having a custom language wasn't Wasp's core value. It was maintaining a high-level specification of the entire full-stack app, making it easier to reason about for both humans and AI.
• We decided to replace Wasp's config language with TypeScript. It is "only" an interface change, while everything else stays the same.

Why we thought creating a new language was a good idea​

My brother and I both come from a traditional Computer Science background, where we focused mostly on algorithms and applying them to areas such as bioinformatics and machine learning. We never considered ourselves web developers, and were even somewhat opposed to it ("look at these folks just painting buttons the whole day, while I'm writing all the cool algorithms."). Obviously, we didn't know enough.

Still, we had one entrepreneurial friend in our group who was always doing something on the side, and he would pull us in whenever he'd land a bigger project. Each of these projects had something that made it "interesting" for us (e.g., building a news portal that also needed a recommendation engine, or an option trading analytics platform), but at the end of the day, it was mostly a classic web development job.

That way, we got exposed to things like PHP (we built a complete CMS from scratch in it and then later realized there were frameworks and even off-the-shelf solutions we could have used), Java/JBoss, and also Backbone.js, Angular.js, and React as they were popping up, along with the build tools (remember Bower, Grunt, and Gulp)?

2013 and later marked the era of reactive front-end frameworks, and each new one was something you absolutely had to use in your latest project, because that was part of what made your project/startup cool. The result was that each new project we started, we started with almost a completely different stack from the last one and had to re-learn all the patterns that we just figured out - authentication, routing, state management, …

We got tired of switching and stitching stacks​

Before, one would just choose between Spring Boot, Django, or Rails and have everything handled and managed. Now, I had to first pick each library, then make React, Redux, Webpack, Express, Passport, and Sequelize work together.

No system was in charge, with a full understanding of the web app, and that feeling of responsibility didn't really sit well with Martin and me.

Having gone through this stack-switching dance a few times (eventually landing on React, Node.js, and Mongoose at the time), we thought - isn't there a better way? It felt like we were constantly reinventing the same thing, spending most of our time managing our stack rather than writing our unique business logic.

There's a name for this: accidental complexity. The work that has nothing to do with your actual problem, but you can't avoid it because of the tools you're using. That's exactly what we were feeling.

What if I could just say what I want, once?​

We asked ourselves: what if you could simply write what you want, and that's it? For example:

• "I want my app to have authentication with Google and GitHub"
• "I want to have a route /profile, which is available only to authenticated users"
• "I want a cron job that runs this function every day at 5pm"

Obviously, this is too conversational-y, so we imagined boiling it down to something more structured, like:

• auth: Google, GitHub
• page Profile -> /profile, authRequired: true
• job updateStats: run function doSomeCalc from stats.js every day at 5pm

It would basically be a way to define your app's requirements at a higher, implementation-free level (aka specification). We felt something like this could and should be possible, but with the tools we had, we had to implement each of these requirements scattered across the stack at what felt like an abstraction level too low.

Our goal was never to replace the existing stack. You'd still implement most of your logic in a specific runtime (e.g., React or Node.js). But there'd be a central backbone which holds everything together.

If you're curious, this is a code excerpt showing what the DSL looked like in its final form:

app todoApp {
  title: "ToDo App",  // visible in the browser tab
  auth: { // full-stack auth out-of-the-box
    userEntity: User,
    methods: { google: {}, gitHub: {}, email: {...} }
  }
}

route RootRoute { path: "/", to: MainPage }
page MainPage {
  authRequired: true, // Limit access to logged in users.
  component: import Main from "@client/Main" // <-- Your React code.
}

query getTasks {
  fn: import { getTasks } from "@server/tasks", // <-- Your Node.js code.
	entities: [Task] // Automatic cache invalidation.
}

The key insight for us was that the web app domain changes very slowly compared to the velocity at which web dev implementation techniques evolve. Both ten years ago and today, we refer to pages, routes, API endpoints, and data models. In the meantime, the UI implementation went full circle from server templates to the rich client and back to server actions.

Our goal with Wasp was to let developers express as much as possible at the domain level, and let the system handle the (latest) implementation details. That way, whatever they build will last much longer and be easier to understand.

Why create a new language from scratch? Why not use the existing ones?​

While our understanding of the problem has mostly proven correct, because we experienced it first-hand, this was where we took the wrong turn.

There were two main reasons why we opted to design a new language from scratch, with its own custom compiler, rather than use, e.g., TypeScript or Python as a "host" language:

• We wanted to have a full control over the syntax, and make it as clean and boilerplate-free as possible.
• We envisioned Wasp as a runtime-agnostic tool, eventually. E.g. maybe you write a piece of a typical CRUD logic in Node.js, but then some data-heavy stuff you'd rather do in Python which has better libraries for it.

While we considered using TypeScript (and that was some of the early feedback we got, to have an embedded DSL, which is basically just a library, instead of the explicit DSL), it felt "wrong" to us at the time, as if we'd betray the core principles and a big vision we had for Wasp.

In a way, we were very excited to ship Wasp as a standalone language because we believed it would make a stronger statement and make it clear it's not another typical language-bound framework (e.g., Rails or Django), but something more general.

To be completely honest, we were also excited about the fact that we get to work on something so "cool" and foundational, such as a language and a compiler. Martin and I are both Haskell aficionados, and this was the perfect nail to hit with our functional hammer.

Reception: You loved the idea and tolerated the language​

After about a year of working on Wasp, releasing an Alpha version, and launching it to developers, we found a small tribe of excited early adopters and were accepted into Y Combinator. We raised our pre-seed round shortly afterward, which enabled us to assemble the team and go build the first "real" version.

Things were slow at the beginning as we were getting everything off the ground, but developers acutely felt the pain of boilerplate and were tired of stack-stitching, so Wasp gained momentum, especially after we entered Beta.

You might also remember that at a similar time, back in 2021, a couple of other "Rails for JS" frameworks appeared on the scene, like RedwoodJS (by the creator of GitHub) and BlitzJS. They quickly got solid community traction, and it became clear to us that we're on the track to solve a very important problem.

Still, talking to developers, the question of "But why did you create a new language?" kept popping up in different contexts. There were a few main objections we kept hearing.

I see "wasp-lang" - does this replace JavaScript?​

Although we never meant to replace the existing web dev stack, but rather complement it (with Wasp, you still write 90% of your code in React & Node.js), the notion of the "lang" suffix was simply too strong to convey that.

Whenever a developer read "wasp-lang.dev", their mind automatically went to "oh, this is something like Rust/Java", and it was very hard to remove that lens once it came up. It immediately put Wasp into the "looks cool, but it's way too early" bucket.

We were very excited about building a language and even highlighted it, but we underestimated how strong the term's meaning already is.

Is this going to work with my IDE and existing tooling?​

Even if you gave the language thing the benefit of the doubt, the next question is, "Does this come with its own ecosystem?" Developers know how much work it is to create a new standard and how much time it takes to grow the ecosystem around it.

This isn't for me, I don't want to learn Haskell​

We're using Haskell internally for our compiler, but end users will never see it and will use only TypeScript. It's similar to how Prisma's core was initially developed in Rust, and Terraform's HCL in Go.

Still, our initial marketing around using Haskell worked out a bit too well for our own good. The Haskell community is small, but engaged, enthusiastic, and very hungry for real-world projects, especially around developer tooling.

Sharing our progress with the community was often very well accepted, but also reinforced Wasp as a "Haskell-based language", especially if you just glanced over the title.

Pair that up with the fact that on the GitHub repo page in the "Languages" bar, it said "Haskell: 90%" (we later found a way to circumvent this), and you got yourself a perfectly executed wrong positioning.

It's the packaging issue​

Many developers who actually tried Wasp loved it and didn't mind the language much. They could ship faster than ever without spending weeks learning the stack, and keep using React & Node.js. But getting developers to make that leap from "what is this?" to "I will give it a go" was really hard.

We kept pushing. With Beta, adoption soared, and we started seeing startups built with Wasp getting acquired, as well as enterprises building internal tools and deploying them into their local infra setup (in the end, the Wasp app is just static frontend files + a single Docker image for the backend).

To get past the "this is a weird new framework, why should I try it?" barrier, we built products on top of Wasp (an open-source SaaS boilerplate starter and our own "early" Lovable) that shifted the decision to a higher level. It worked great and brought many people to Wasp.

Still, the core issue persisted. Developers who came to Wasp couldn't understand what we were building, so they couldn't get excited about it.

The final nail - trying to make IDE support work​

We always assumed that if our language proves to be a wrong choice, it will be because our users told us so. It turned out to be the opposite: while developers who adopted Wasp were happy to keep using it, we started having more and more issues with it internally.

One of the main things we underestimated was how much work it takes to develop the necessary tooling for a custom language, especially IDE/editor support. The bar developers expect today, especially in the JS world, is incredibly high, and the line between an IDE and a compiler is getting blurred.

Once we dove deeper into building tooling for a custom language, we quickly realized the entire ecosystem is built for "standard" JavaScript and TypeScript frameworks. Anything else, and you're on your own, hitting walls really fast.

We ended up developing our own language server and a VS Code extension for it, but since Wasp used Prisma's DSL as an embedded language and had many references to React & Node.js files, we still only reached 80% of where we wanted to be.

Goodbye Wasp language, welcome TypeScript​

With all the accumulated pain around maintaining a custom language, and the constant friction of getting new developers to give it a try, we realized the root cause is deeper than "developers are afraid to try a new web framework".

The usage kept growing, and more and more people were shipping their Wasp apps to production, but whatever we tried, it would always ultimately come back to "I really like what you're doing with Wasp, but why a custom language?". It felt like we were constantly driving with a handbrake pulled up.

Finally, the ergonomics we aimed for with the language didn't turn out to be as important as we thought. Developers are perfectly happy using TypeScript, a language they are familiar with, even if it requires a few extra lines and braces.

Language was never the moat. It's having a high-level understanding of your entire app at compile time.​

When we started Wasp, the terms "language" and "specification" were basically synonyms to us. We couldn't imagine one without the other.

But watching developers use Wasp and seeing what they are excited about, it became clear it was never the language. It was the fact that Wasp has a full understanding of their entire app via a high-level spec (e.g., main.wasp, now main.wasp.ts), which lets them easily grasp how their app works at a glance and feel in control.

One way in which we tried to make it more tangible is by having a wasp studio command - if you run it in your terminal, you'll see how Wasp "sees" your app at compile time, and can reason about it before generating the target code:

Having this kind of "support system" made the process of building an app a much more managed experience. With AI and developers reviewing generated code less frequently, this became even more valuable, especially for a new generation of builders with less technical backgrounds (so-called "vibe-coders").

And this app-level understanding doesn't change at all with the switch from Wasp's custom language to TypeScript. We only swapped the "front end" of the compiler, or how you define a high-level app spec in Wasp.

TypeScript SDK - from an experiment to production​

// Page & route definition
const loginPage = app.page('LoginPage', {
  component: { importDefault: 'Login', from: '@src/pages/auth/Login' }
});
app.route('LoginRoute', { path: '/login', to: loginPage });

// Query
app.query('getTasks', {
  fn: { import: 'getTasks', from: '@src/queries' },
  entities: ['Task']
});

// Async job
app.job('mySpecialJob', {
  executor: 'PgBoss',
  perform: {
    fn: { import: 'foo', from: '@src/jobs/bar' },
    executorOptions: {
      pgBoss: { retryLimit: 1 }
    }
  },
  entities: ['Task']
});

export default app;

We introduced the TypeScript SDK for Wasp as an experimental, early preview feature to gauge feedback. And we've received very positive feedback - some of our new users immediately opted for it and never even tried using the Wasp language. This has been a signal for us to keep going.

After testing it internally and within the Wasp community, we're now confident this is the way forward. Besides circumventing the initial "why a new language" question, it solves all the problems we've been fighting for years.

Every editor works out of the box. Developers can use conditionals, loops, and imports (e.g., you could implement your own file-based routing!). Splitting the spec across multiple files becomes trivial. And it gives us a solid foundation for the advanced features we've been wanting to build, like Full Stack Modules.

DSL, thanks for all the fish - we'd never come this far without you​

Looking back, Wasp probably wouldn't have come to life if we hadn't started the way we did. It was our best way to express what we wanted to build at the time, paired up with some personal biases, and well, what we simply thought was fun. It was the curiosity of "We know this sounds like a crazy idea, but we really want to see if it can work" that kept us pushing even when no one was watching.

The DSL approach kept us honest to our vision that the specification should be separate from the implementation. We're still curious about opening support for other languages and runtimes (e.g., Python or Rust) and about the benefits of having a full picture of your app at compile time and being able to reason about it before generating the target code (which opens space for supporting different architectures, optimizations, etc.).

Your AI agent might like Wasp, too​

Finally, as AI agents write more and more of our code, we see many developers looking for tools that provide more structure and opinions upfront, which in turn makes adding features more predictable and the generated code easier to understand and review.

Wasp fits perfectly here, since it spans the full stack of your app and ensures everything works together at all times. It's why many developers have also found renewed love for "old-school" monolithic frameworks such as Django, Rails, and Laravel. Wasp aims to provide the same experience and that feeling of "it just all works", but for the JS ecosystem.

We repeatedly hear from developers using Wasp that it is the stack that works best with AI, and some of them even went so far as to try 10 different solutions before settling on Wasp.

We are shipping TypeScript-first Wasp soon​

In the next few weeks, we're hosting Launch Week, during which we'll ship the TypeScript SDK as the primary way to use Wasp. We've already seen the excitement within our community, and can't wait to hear what you think about it.

If you've ever been curious about Wasp, now is the perfect time to give it a try. No new language to learn. Just TypeScript, and everything Wasp does for you under the hood.

To stay in the loop, join our Discord, or follow Wasp or me on X/Twitter.

So you open Claude Code and vibe code your way to a working MVP in a weekend. But you quickly hit a wall trying to debug something and lack the knowledge to express what it is you actually want.

In the end, you may get something that works, but you have no idea how it works.

Following static tutorials or blindly vibe coding isn't a great way to build professional apps or web dev skills. Without the fundamental knowledge of how the technologies work you'll have a lot of trouble fixing problems, or properly extending the functionality of your app.

That's why we built Open Vibe.

What Open Vibe is​

Open Vibe is a free, open-source course where an AI coding agent tutors you while you build real full-stack web apps on your own machine, and in your own terminal (and/or editor).

• 100% free, open-source, and no signup required.
• Works with Claude Code, Cursor, Codex, Copilot, Open Code, or any agent that can read files and run tools.
• Built by the Wasp team (the same people behind Open SaaS, the #1 free SaaS boilerplate on GitHub).

There's no platform to log into, no $299 video library to wade through.

You just paste a one-line prompt into your agent of choice, and the curriculum loads. From that point on, you get a guided curriculum that teaches you the fundamentals of building professional-grade web apps with AI. But since the course lives in your agent, you're free to ask it whatever you want and take the course in any direction that suits your interests.

v1.0 is live today. Setup and Module 0 are out, with new modules dropping next week.

How it actually works​

We wanted to make Open Vibe as simple as possible. After you install a coding agent (we suggest Claude Code's $17 Pro Plan for the best experience), just follow these steps:

1. Paste the install prompt. One short prompt to your agent (full text in the "Get started" section below). The agent fetches the raw file, loads the curriculum, skills, instructions, and interactive diagrams, and from that moment knows every module and every checkpoint.

2. Build alongside your tutor. The agent guides and watches you in realtime as you build your app, stepping in to help out whenever you need it. It paces with you, explains important concepts, quizzes you, and pair-programs the parts you don't yet trust yourself with. Stop, ask, branch off, and come back to the guided curriculum whenever you want. There's no video to rewind to find the bit you missed, and your agent is always there to help you.

3. Learn with interactive diagrams on your real app. This course is hands-on, but also interactive. We built interactive explainers on top of the apps you build to help explain important topics like the request cycle, auth flows, git, and database writes.

Interactive Diagrams show up on top of your running apps as you build.

Open Vibe takes advantage of the tools we have today to provide a living course you interact with, so you build the skills you need to ship apps like a pro.

What you'll build​

The course is currently broken down into three phases (this may change as we keep iterating):

• Phase 1 — Basics. You build on top of a real full-stack Task Management app: login, database, the works. Setup and Module 0 are available now. Modules 1–3 cover data, styling, and how the front-end and back-end actually wire together.
• Phase 2 — Your app from scratch. Spec your own idea, scaffold a new project, and ship it end-to-end with the agent pairing the whole way. You'll learn tools like Git/GitHub, and how to deploy apps to the web.
• Phase 3 — A real SaaS. Build on Open SaaS, a free $300-value SaaS template the Wasp team maintains. Auth, payments, an admin dashboard, file uploads, AI integrations, deploy, and more.

Open SaaS gives you auth, payments, an admin dashboard, and AI integrations out of the box, so Phase 3 is about shipping a real product, not wiring boilerplate.

You'll finish with three real apps in your GitHub, and the best part is that you'll actually understand what they are and how you built them.

Why now​

Coding with an AI agent is how people build in 2026. But the ones who ship confidently, and with speed, understand the fundamentals.

If you're non-technical and trying to build by guess-and-check prompting, you know how tedious it can be.

Meanwhile, influencers and bootcamps are still selling video libraries and a Slack channel for hundreds of dollars. But the tutorials are static, obsolete by next month, and basically only teach you how to copy.

Both approaches miss this new fact: the agent in your terminal/editor is patient, current, and super knowledgeable. It knows how to code really well, and how to solve almost any problem... if you know what to ask of it!

Open Vibe is the missing layer: a curriculum for the agent, so it tutors you, teaching you the skills you need to vibe code like a pro while you build professional-grade web apps.

The goal isn't to ship apps you don't understand faster. It's to ship apps you do understand, fast.

Get started​

Just open your agent of choice and paste:

I'm starting the "Ship Your First App" course. Run curl -fsSL https://openvibe.sh/llms.txt and follow the file's instructions.

That's it. The agent handles the rest.

If you get stuck, the Discord has actual humans on it, or you can leave us feedback on our feedback form. If you want to fork the course, run your own class with it, or contribute a module, the repo is on GitHub.

Free forever. Fork it. Run your own class with it. We just want more people building real things.

This was about the same time we launched Open SaaS, our free, open-source SaaS starter. Using the same logic, you'd have expected that AI would have killed boilerplate starters by now. But we noticed the opposite trend.

Open SaaS just crossed 14,000 GitHub stars and its entire growth happened right in the middle of the vibe coding boom.

This surprised us. So we decided to talk to 40 of our users to learn why they turned to Open SaaS.

A renewed Energy to Build.​

After conducting 40+ user interviews, we noticed a trend: AI was unlocking all kinds of new builders.

Career devs, DevOps engineers, PMs, an ex-woodworker, a marketer with zero coding experience, and more were getting inspired to start on their Ideas. These were people who always had a SaaS idea but never had the time or skills, or people who were getting inspired to build new apps on top of AI.

Regardless of which type they were, it was AI that unlocked them.

"Two years ago I didn't believe I could build an application... So it's like kind of magic for me." — Leo, ex-marketer who built Messync

"If there was no Wasp, I don't think I would even start building this." — Sergio, 20-year backend veteran who built CTOBox

Another one of our users with no React or Node.js experience built a SaaS app and sold it to a major accounting firm for ~$100k.

And the most surprising fact of all: about half of those interviewed were people who had never built a full-stack app before.

AI gave them the confidence and inspiration to start, but a lot of them turned to Open SaaS to help them focus their efforts.

AI Can Do 90%. The Last 10% Is the Hardest.​

AI tools are getting insanely good. With Claude Design you can scaffold a professional-looking landing page in about an hour. Slap it into Claude Code, add on more components and CRUD logic, and you're almost done.

But it's things like Stripe webhooks, auth edge cases, environment management, deployment, and background jobs that really trip up builders.

These aren't necessarily code problems, they're architecture problems. And AI is great at generating code within a clean, working architecture, but you've got to have one first.

"Open SaaS made me feel secure, like I am not cutting any corners. Just using AI would make it harder to sleep at night." — Robbie, musician who built PeakMastering

"With Next.js App Router, I was constantly fighting the LLM to get the syntax right. Svelte runes were just the Wild West." — TK Garrett, ex-woodworker who built PlotTree

Good Code Makes AI Code Better​

After talking with Open SaaS users, we heard the same thing over and over again: having a solid, clean codebase to start with drastically improved the perfomance of AI-coding agents and tools.

And that makes sense, because when you use an opinionated, boilerplate codebase like Open SaaS, you've effectively already decided the architecture of your app for the AI and it no longer needs to spend resources on these decisions, or communicating with you in order to make them.

In the end, you can just let AI handle WHAT you want built because Open SaaS (or any other good boilerplate) already handles HOW it should be built.

Combining them solves for that tedious 10% that kills most projects.

"If you start with Open SaaS, 80% of the pains of vibe coding are taken care of for you already." — Kenny Rogers, vibe coding educator

"It covers 99% of what I need without me babysitting the AI." — TK Garrett

This is why Open SaaS grew steadily to 14k stars through every AI milestone — Cursor blowing up, Karpathy coining "vibe coding," and Claude Code launching.

The Starting Line Just Got More Crowded​

AI is empowering more people to become builders and entrepreneurs. But you still have to actually ship something, and few end up doing that.

The ones who do, they tend not to build or reinvent auth and payments from scratch. They start with a foundation that handles it for them, point their AI tools at it, and focus on what makes their app unique.

That's how Open SaaS got to 14,000 GitHub stars.

Most people aren't interested in the boilerplate. They're interested in their ideas. Open SaaS is just the fastest way to go from idea to production.

Don't let the 10% block you from shipping your SaaS.

Try Open SaaS​

Open SaaS is free, open-source, and ready to go. We're constantly updating it to be the best full-featured SaaS boilerplate out there. Here's what you get out of the box:

• Auth with Email, Google, GitHub, Slack, and more (no 3rd-party service needed)
• Background Jobs with PG Boss (no 3rd-party)
• Payments with Stripe, Polar.sh, or LemonSqueezy
• AI Agent Skills and Memory files included
• ShadCN UI components
• Example apps to learn from
• Email with SendGrid, Mailgun, or SMTP
• End-to-end type safety

Star us on GitHub if you think more people should know about it.

Marcel Coetzee is a data scientist and AI consultant based in South Africa. With a background in actuarial science and data science, he runs his own consultancy. He also builds SaaS products on the side. His latest project, Hireveld, is a job board tackling South Africa's broken hiring market. He built it entirely with Wasp after trying nearly every other stack out there.

Tell us about yourself. How did you end up building web apps as a Python developer?​

My path has been a bit unconventional. I started in actuarial science, which involves insurance, mathematical statistics and risk modeling. From there I moved into data science, then data engineering, and eventually into building products. Python has been my main language through all of that.

Today I run my own consultancy doing data engineering and AI work. But I've always wanted to build my own things too, so I started learning the JavaScript ecosystem and working on SaaS products on the side. I'm not a JS native by any means, but with the rise of agentic coding tools, I realized I could finally turn my ideas into real full-stack applications without spending years mastering every corner of Node and React.

What's Hireveld, and what problem are you solving?​

Hiring in South Africa is expensive and opaque. Recruitment agencies take a massive cut of annual salary. The established job boards charge thousands of rands just to post a single listing. And too many roles still get filled through personal connections rather than merit.

I built Hireveld to change that. Employers post for free, applicants get ranked anonymously, and employers pay a flat fee to reveal candidates. It's simple, it's cheap, and it puts merit first. The whole thing runs on Wasp - auth, background jobs for expiring old listings, transactional email, payment integration, the works.

You mentioned trying about 10 different stacks before landing on Wasp. What happened?​

Yeah, I went through quite the journey. I started with PocketBase because I liked the idea of owning my code and not being locked into a cloud platform. It's a solid tool, but I quickly realized I needed PostgreSQL for search, background jobs, and a frontend that wasn't stitched together by hand. It just didn't scale to what I was building.

Then I tried Next.js, Nuxt, Svelte - they're decent, but those codebases can grow extremely quickly. As someone who's still relatively new to the JS ecosystem, I'd hit the limits of my knowledge fast. I even tried Django, thinking I'd stick with Python, but it's accumulated so much over the years. Too much magic, too much stuff.

My philosophy is: the projects that succeed expose as few abstractions as possible to the user. I try to keep myself at the highest level of abstraction I can. When I found Wasp on GitHub, the config file clicked for me immediately. You declare what you want - auth, database, jobs, email - and it all works together. I was writing actual product code on day one instead of gluing infrastructure together.

Don't prioritize the important over the urgent. With other stacks I was spending time on infrastructure decisions that felt important but weren't getting me closer to a product. Wasp let me focus on the urgent thing: shipping.

You're a big advocate for agentic coding. How does Wasp fit into that workflow?​

This is where Wasp really shines, and honestly I think more people need to know about it. I've been building Hireveld almost entirely through agentic coding - Claude Code in the terminal - and after trying 10 different things, Wasp is by far the best experience for AI-assisted development.

Here's why: context is the precious commodity. Every line of code in your project takes a chunk of the model's context window. Wasp keeps the codebase tight and small.

The .wasp config file means the AI can understand your entire app's architecture at a glance - your routes, your auth setup, your jobs, your entities. Instead of the agent crawling through hundreds of files trying to figure out how things connect, it's all declared in one place. And because Wasp is opinionated and constrained, the agent doesn't try to do 50 different things. When something is wrong, the compiler screams. That tight feedback loop is exactly what agentic coding needs.

Wasp respects the model's context length. It keeps things tidy. The constraint is the feature - it's what keeps both you and the AI from spiraling into a 20,000-line mess.

I should say - I'm not blindly vibe coding. I know where my files are, I know my routes, I hand-edit the main.wasp file when I need to. I take testing seriously, both e2e and unit tests. QA is the layer where you, the human, decide what you actually want to build. But Wasp gives me the structure to stay at a high level and be productive, even as someone whose main language is Python. Also bring my data science background to bear by simulating data to gauge how the system would react to real traffic.

You also contributed back to Wasp - tell us about the Microsoft Auth integration.​

Hireveld targets the South African enterprise market, and enterprises run on Microsoft. They need Entra ID (Azure AD) for single sign-on - it's non-negotiable. When I started building, Wasp didn't have a Microsoft OAuth provider. With most frameworks, that would mean either paying a fortune for a third-party service or building a fragile custom integration that becomes tech debt.

But Wasp's codebase is approachable enough that I could build the provider myself and contribute it back. The PR process was great - Carlos and the team were welcoming and helpful. That's the sweet spot I was looking for: a framework that's batteries-included enough that I'm not rebuilding auth from scratch, but open enough that when I need something custom, I can add it without fighting the framework.

The community in general has been one of the best parts. The developers are genuinely friendly, my contributions felt valued, and I can tell the team takes agentic coding seriously - they maintain a Claude Code skill, they keep their prompts updated, they engage with the tooling ecosystem. That's an unusual level of involvement for a framework team.

What would you say to a developer considering Wasp for their next project?​

If you're building a full-stack web app in 2026 and you're using AI tools to code - which you should be - try Wasp. Seriously. I went through PocketBase, Next.js, Nuxt, Svelte, Django, and more. Wasp is the only one where I felt like I was building my product from day one instead of fighting my tools.

It gave me auth, type-safe full-stack operations, background jobs, and transactional email - all wired together from a single config file. Everything else - the ranking algorithm, payments, file storage - I built on top of what Wasp provided. That separation is what made it possible to ship as a solo developer.

And if you're coming from Python or another ecosystem and you're intimidated by the JavaScript world - don't be. Wasp abstracts away enough of the complexity that you can stay at a high level and be productive. I'm proof of that.

Wasp is the full-stack framework for the agentic era. It's the one that lets you focus on what you're building, not how you're building it.

Marcel Coetzee is a data scientist, AI consultant, and SaaS builder based in South Africa. You can find him on GitHub and reach out to him on coetzee.marcel2@gmail.com

TL;DR​

We gave Claude Code the exact same feature prompt for two identical apps - one built with Next.js, the other built with Wasp - and measured everything that Claude Code did to implement the feature.

Not surprisingly, the savings were proportional to the amount of actual total code/tokens the Wasp framework abstracts away, which we also measured by running a static token count across both codebases. In this case, the Wasp version reduced total code/tokens by ~40%.

Because the framework allows Claude Code to get the same work done in fewer tokens, it delivers a ~70% higher token efficiency (output per token).

So, if you're using AI coding tools daily, your framework choice might be your single biggest lever for improving your AI's ability to generate accurate, complex code, quickly and cheaply.

What Wasp Actually Is​

Wasp is a full-stack framework for React, Node.js, and Prisma with batteries-included. Think Rails or Laravel-like productivity for the JS ecosystem but where authentication, routing, operations, database, and cron jobs are defined declaratively as config.

You write business logic and Wasp handles the boilerplate and glue code for you.

Here's a simple example of a Wasp app's config file:

import { App } from 'wasp-config'

const app = new App('todoApp', {
  title: 'ToDo App',
  wasp: { version: '^0.21' },
  // head: []
});

app.auth({
  userEntity: User,
  methods: {
    google: {},
    email: {...}
  }
});

const mainPage = app.page('MainPage', {
  component: { importDefault: 'Main', from: '@src/pages/MainPage' }
});
app.route('RootRoute', { path: '/', to: mainPage });

app.query('getTasks', {
  fn: { import: 'getTasks', from: '@src/queries' },
  entities: ['Task']
});

app.job('taskReminderJob', {
  executor: 'PgBoss',
  perform: {
    fn: { import: 'sendTaskReminder', from: '@src/workers/taskReminder' }
  },
  schedule: { cron: "*/5 * * * *" },
  entities: ['Task']
});

export default app;

Wasp's opinionated approach via its config gives AI tools (and developers) a big advantage: it acts as a large "specification" that both you and your AI coding agents already understand and agree on.

This gives AI one common pattern to follow, fewer decisions to make, less boilerplate to write, and fewer tools to stitch together, making the entire development process more reliable.

Show, Don't Tell​

Before the numbers mean anything, here's how Wasp's "declarative config" compares to Next.js's equivalent.

In this example, we're comparing the fundamental auth setup from the actual test apps. The first tab shows Wasp, and the second tab shows Next.js. Click between the tabs to see the difference.

app.auth({
  userEntity: 'User',
  methods: {
    email: {
      fromField: {
        name: 'SaaS App',
        email: 'hello@example.com'
      },
      emailVerification: {
        clientRoute: 'EmailVerificationRoute'
      },
      passwordReset: {
        clientRoute: 'PasswordResetRoute'
      },
    },
  },
  onAfterSignup: { import: 'onAfterSignup', from: '@src/auth/hooks' },
  onAuthFailedRedirectTo: '/login',
  onAuthSucceededRedirectTo: '/dashboard',
});

// lib/auth/session.ts
import { SignJWT, jwtVerify } from 'jose';
import { cookies } from 'next/headers';

const key = new TextEncoder().encode(process.env.AUTH_SECRET);

type SessionData = {
  user: { id: number };
  expires: string;
};

export async function signToken(payload: SessionData) {
  return await new SignJWT(payload)
    .setProtectedHeader({ alg: 'HS256' })
    .setIssuedAt()
    .setExpirationTime('1 day from now')
    .sign(key);
}

export async function verifyToken(input: string) {
  const { payload } = await jwtVerify(input, key, { algorithms: ['HS256'] });
  return payload as SessionData;
}

export async function setSession(user: NewUser) {
  const expiresInOneDay = new Date(Date.now() + 24 * 60 * 60 * 1000);
  const session: SessionData = {
    user: { id: user.id! },
    expires: expiresInOneDay.toISOString(),
  };
  const encryptedSession = await signToken(session);
  (await cookies()).set('session', encryptedSession, {
    expires: expiresInOneDay,
    httpOnly: true, secure: true, sameSite: 'lax',
  });
}

export async function getSession() {
  const session = (await cookies()).get('session')?.value;
  if (!session) return null;
  return await verifyToken(session);
}

export async function hashPassword(password: string) {
  return hash(password, SALT_ROUNDS);
}

export async function comparePasswords(plainText: string, hashed: string) {
  return compare(plainText, hashed);
}

// middleware.ts — route protection + token refresh
import { signToken, verifyToken } from '@/lib/auth/session';

const protectedRoutes = '/dashboard';

export async function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;
  const sessionCookie = request.cookies.get('session');
  const isProtectedRoute = pathname.startsWith(protectedRoutes);

  if (isProtectedRoute && !sessionCookie) {
    return NextResponse.redirect(new URL('/sign-in', request.url));
  }

  let res = NextResponse.next();

  if (sessionCookie && request.method === 'GET') {
    try {
      const parsed = await verifyToken(sessionCookie.value);
      const expiresInOneDay = new Date(Date.now() + 24 * 60 * 60 * 1000);
      res.cookies.set({
        name: 'session',
        value: await signToken({
          ...parsed,
          expires: expiresInOneDay.toISOString(),
        }),
        httpOnly: true, secure: true, sameSite: 'lax',
        expires: expiresInOneDay,
      });
    } catch (error) {
      res.cookies.delete('session');
      if (isProtectedRoute) {
        return NextResponse.redirect(new URL('/sign-in', request.url));
      }
    }
  }
  return res;
}

As you can see, Wasp's config is much more concise and readable than Next.js's.

Why This Matters for AI​

Now that you can see the abstraction gap, here's why it compounds for AI:

1. Performance degrades as context window fills up

   AI tools are stateless and have a finite context window and performance degrades long before it's completely full. A larger codebase fills it faster, which means earlier message compression, less room for reasoning, and degraded output. Developers also have to maintain detailed memory and skill files to help AI understand the app structure and implementation expectations.

2. Signal-to-noise ratio

   More tokens isn't just more expensive, it's more noise. Wasp's config is pure signal for AI, acting like a spec and concise map of the app the AI can follow. Next.js's equivalent is spread across route files, API handlers, middleware, and config. Higher noise = higher chance of mistakes.

3. Every LLM call to the API re-reads the codebase

   AI tools don't remember between turns. Each turn re-reads the session conversation and codebase context from scratch. A bigger codebase means every single turn costs more. In our test, cache reads alone cost $1.71 with Next.js vs. $1.09 for Wasp.

4. It compounds over a project's lifetime

   This test only measured one full-stack feature (db model, server operation, client page), and the differences were already significant (2.5M tokens vs. 4.0M tokens). In larger codebases, these differences quickly compound.

The Full Results​

Combined: Planning + Implementation Phases​

Here are the main takeaways:

• Output tokens (what the AI wrote): nearly identical — $0.21 vs $0.21
• Cache creation (what the AI first loaded): Next.js 113% more — $2.82 vs $1.32
• Cache read (what the AI re-read each turn): Next.js 57% more — $1.71 vs $1.09

Cache creation cost. By caching your prompts, Claude optimizes your API usage by reusing prompts. But while reading from cache is cheap, creating new cache entries is still expensive. Next.js had 2.2x more cache creation tokens (343K vs 155K), at $6.25/M that's $2.15 vs $0.97. The bigger codebase means more new content being loaded into cache.

Cache read cost. Each LLM call to the API re-reads the growing context. The Next.js codebase is bigger so each read costs more: $1.14 vs $0.67. Output tokens were nearly identical (~5,400), meaning the AI wrote roughly the same amount of code but had to read far more to do it.

The main differences comes from the Next.js codebase being bigger, meaning more tokens to load and re-read across every single API call to get the same output.

Context Efficiency: a New Evaluation Metric​

The savings mirror what Wasp abstracts: authentication, routing, database management, operations, and jobs are defined in the config, so AI doesn't need to read, navigate, or generate layers of glue code.

And while this is a new approach in the framework space, Wasp is just following a general principle here: tools that make coding easier for humans make it easier for AI, too. They offload structural work and let the AI focus on business logic, giving a clearer path to generating complex code more accurately.

Think of it as a new evaluation metric for any framework: "context efficiency", or how much of an AI's context window goes to signal vs. boilerplate. Add it alongside DX, performance, and ecosystem when choosing your stack in the AI-assisted coding era.

Methodology​

First, we took Vercel's official SaaS starter app in Next.js and converted it to a Wasp (React, Node.js, Prisma) app.

Then, we made sure to use the same models (Opus for planning and implementation, Haiku for exploring), same framework-agnostic prompt, and same plan-then-implement flow, outlined in the test protocol.

Finally, we created measurement scripts to pull metrics from Claude Code's detailed JSONL session transcripts.

We used Anthropic's API pricing as of March 2026 (per 1M tokens), e.g.:

Fairness caveats: Claude has seen far more Next.js training data (advantage: Next.js). Wasp's codebase is ~40% smaller, but that's the point. And this is a single feature test, not a comprehensive benchmark.

Explore the comparison yourself: both apps, the test protocol, and measurement scripts are in the comparison repo.

Try Wasp​

Want to try Wasp? Get started with:

npm i -g @wasp.sh/wasp-cli@latest

Then start a new Wasp app:

wasp new my-app
wasp start

And don't forget to add the Wasp Agent Plugin / Skills to turn your agent into a Wasp framework expert!

Getting this right was harder than expected, and this post is what we learned. We'll dig into how npm workspaces actually work: how dependencies get resolved and hoisted, how Node.js finds modules at runtime, and help you build intuition/mental model that will come in useful when debugging this setup.

Your side project started as a single folder with a hundred lines of code. Now it's a full-stack app with a React frontend, an Express backend, and a shared library of types and helpers that both sides need. You might be copy-pasting files between folders like it's 2005, and the cracks are showing: a type definition got updated in one place but not the other, and now your API responses don't match what the frontend expects. Something has to change.

The first step would probably be splitting your code into multiple packages. But without the right tools, you'll quickly find yourself drowning in running npm install in five different folders, or fighting runtime errors because React is installed three times.To fix this, modern package managers introduced workspaces. Intended to allow you to manage multiple packages within a single repository without the dependency headaches, workspaces are widely used in many projects, but their inner workings are often misunderstood.

In this post, we'll dig into the magic that makes them tick: how package managers resolve shared dependencies across packages, and how Node.js finds them at runtime.

Enter workspaces​

Workspaces are a feature in npm, Yarn, pnpm, and others that let you organize multiple JavaScript packages in a single project. And while each package acts as its own encapsulated unit, they can still depend on one another with no extra ceremony.

Two main behaviors make this work: shared dependencies (if two packages depend on react, they both use the same installed version) and cross-package imports (a pkg-a can just import pkg-b by name).

The building blocks are interesting and require a dive into how package managers and Node.js work. The feature also comes after a long evolution of tooling and JS development practices, so let's start with some history.

A brief history​

It seems like the second half of the 2010s was when the professionalization of JS development started to trickle down to the average developer. The rise of Babel and Webpack gave us a modern development experience, one that more closely resembled what other languages had enjoyed for years. We finally had a proper module system, and the ability to target newer language versions, while still supporting older runtimes.

Our history of workspaces starts in 2015, when the 6to5 project realized they didn't want to work only on ES6 code, but also on everything that came after it. They renamed themselves to Babel and started working on modularizing the codebase, knowing they'd need well-separated concerns to keep up with the ever-evolving language.

Babel maintainers wanted to distribute the new version as a collection of plugins you could pick and choose, but couldn't afford to manage each one independently. So when they split all their code into different packages, they did so in the shape of a monorepo. That decision kickstarted the development of what would eventually be called workspaces.

Their internal tooling was soon released as Lerna. Lerna's main job was to allow packages in a monorepo to seamlessly require() one another as if they were already published, instead of having to edit, publish, and reinstall each one independently.

A few months later in 2017, Yarn came along. Yarn was created to solve some problematic behaviors of npm at the time, and dramatically improved performance and reliability. Alongside features like reproducible lockfiles and heavy caching, Yarn also introduced workspaces as a first-class citizen. This was no surprise, as Yarn was created by some of the same people who had worked on Babel and Lerna.

Soon, Yarn exploded in popularity, and in time, other package managers followed suit. pnpm added workspaces support in 2018, and npm followed in 2020. Nowadays, after a long evolution, workspaces are supported in all the mainstream package managers and widely used in both open and closed source projects.

Problems and solutions​

The exact definition of what a workspace is depends on the package manager you're using. The definition I gave above is more of an observation of what the main package managers have in common than a prescriptive specification. There isn't a common "workspaces spec". Each package manager has its own take, with different configuration formats, commands, and even different ways to declare dependencies.

That said, there's a core of functionality you can expect across package managers: you declare a root folder that contains multiple sub-packages. Each sub-package is called a workspace, and the whole set is a project¹. From there, three features usually become available:

• Each workspace is its own full package, as if it were an independent project. Each workspace has its own package.json, where it declares dependencies, configuration, and scripts without worrying about the insides of other packages.

• All dependencies are resolved together across the project, as if it were a single package. If two workspaces depend on the same package, it gets installed once and shared (assuming compatible version ranges).

• Workspaces can depend on each other by name, as if they were regular dependencies. In a project with many workspaces, pkg-a can import pkg-b and everything works.

Workspaces give us the best of both worlds: the encapsulation of small packages with the convenience of shared dependencies.

The first feature is just the natural way of working with multiple packages, so it doesn't require much explanation. Let's look at the other two: why they're useful and how they're implemented. The exact implementation details depend on the package manager, so we'll use npm as a reference here, since it's the most widely used. The general concepts apply across the board.

The dependencies of the whole project are resolved together​

The problem​

Imagine testing a project with many interconnected packages ...say, 157 of them. You'd have to find out which packages depend on which others, run npm install in each folder, and deal with the ongoing headache of keeping dependency versions in sync. Worse: if each package had its own node_modules, you'd end up with tons of copies of the same dependencies installed in different places.

Multiple copies aren't just a waste of disk space, they can cause bugs. In JavaScript, the same class defined in two different files is considered different, even if the code is identical²:

export class MyClass {}

export class MyClass {}

import * as foo from "./foo/my-class";
import * as bar from "./bar/my-class";

new foo.MyClass() instanceof foo.MyClass; // true
new foo.MyClass() instanceof bar.MyClass; // false!

For shared dependencies to work correctly, they need to be installed once, in a single place. That way, when different pieces of code import the same dependency, they get the same object.

The solution​

Most package managers already deduplicate dependencies for a single project. So to get this behaviour for free with workspaces, they cheat a bit: they treat all workspaces as dependencies of a single, "fake" root package. The existing resolution algorithm gets reused without changes.

You can see this in any workspaces lockfile. Here's a simplified example for a regular package with no workspaces:

"my-simple-package":
  dependencies:
    left-pad: ^1.0.0
    right-pad: ^1.0.0

"left-pad@^1.0.0":
  resolved: 1.1.0
  dependencies:
    core-pad: ^1.1.0

"right-pad@^1.0.0":
  resolved: 1.4.0
  dependencies:
    core-pad: ^1.4.0

"core-pad@^1.1.0,^1.4.0":
  resolved: 1.4.5

The package depends on both left-pad and right-pad, which both depend on core-pad with different version ranges. The package manager found a single version of core-pad that satisfies both and installed it once.

Here's the same scenario in a workspaces project: