DEV Community: Carlos Precioso

[Boost]

Carlos Precioso — Tue, 28 Jul 2026 10:14:15 +0000

Licto for Wasp

Jul 28

Made with Wasp: how Searchcraft built a full-stack SaaS around their Rust search engine

#rust #webdev #saas #opensource

5 min read

Roll your own file-based router in under 50 lines of code

Carlos Precioso — Thu, 23 Jul 2026 12:04:08 +0000

Nowadays, web frameworks come with ✨ magic ✨. Some more than others, but all of them have some. The magic is usually in the form of conventions: do things their way and the framework helps you out; wander off the happy path and you're on your own.

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: [
    // highlight-next-line
    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>
      [About us](https://wasp.sh/about-us)
    </>
  );
}

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:

// highlight-next-line
const ROUTE_GROUP_REGEX = /^\(.*\)$/; // Wrapped in parentheses

// ...

const urlRoute = filePath
  .split(path.sep)
  .slice(0, -1) // Removes the "page.tsx" part
  // highlight-next-line
  .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:

// highlight-start
const isPrerender = filePath.includes("(prerender)");
const isAuth = filePath.includes("(auth)");
// highlight-end

// ...

return route(
  `${routeName}Route`,
  "/" + urlRoute,
  page(
    ref({
      importDefault: `${routeName}Page`,
      from: absoluteFilePath,
    }),
    // highlight-next-line
    { authRequired: isAuth },
  ),
  // highlight-next-line
  { 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?:

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

// ...

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
  // highlight-start
  .map((part) => part.replace(OPTIONAL_SEGMENT_REGEX, ":$1?")) // Convert optional segments
  .map((part) => part.replace(DYNAMIC_SEGMENT_REGEX, ":$1")) // Convert dynamic segments
  // highlight-end
  .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("RootRoute", "/", page(RootPage), { prerender: true }),
    route("AboutUsRoute", "/about-us", page(AboutUsPage), { prerender: true }),
    route("ProductIdRoute", "/products/:productId", page(ProductIdPage)),
    route("DashboardRoute", "/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!

[Boost]

Carlos Precioso — Tue, 12 May 2026 09:36:12 +0000

vincanger for Wasp

May 12

Open Vibe -- Ship your SaaS with AI. Without getting stuck.

#webdev #ai #saas #vibecoding

5 min read

A gentle intro to npm workspaces, with visuals

Carlos Precioso — Tue, 07 Apr 2026 15:14:07 +0000

I am a founding engineer at Wasp - a full-stack TypeScript framework based on React, Node.js, and Prisma. Like Rails, but for JavaScript. A Wasp app is built as a multi-package setup - frontend, backend and shared code all live in a single repo as separate packages managed by npm workspaces.

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:

Graph

Lockfile

"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:

Graph

Lockfile

"##fake-project-root##":
  dependencies:
    workspace-a: local
    workspace-b: local

"workspace-a@local":
  dependencies:
    left-pad: ^1.0.0

"workspace-b@local":
  dependencies:
    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

By pretending all workspaces are dependencies of a single root package, the package manager reuses its existing algorithm. It finds one version of core-pad that works for both, installs it once, and any workspace that imports it gets the same object.

Workspaces can depend on each other by name

The problem

If you have two separate packages and want one to depend on the other, you have two options:

Publish the dependency to the registry, then install it in the other package. Straightforward, but if you're iterating quickly, the publish-install cycle kills your flow.
Use a local file dependency. Edit the imports to point to the local path. This works, but it's brittle: if you move packages around or share the code with someone else, paths break. If the dependency has its own dependencies, you have to install them manually. And you need to remember to switch paths back before publishing.

Neither is great. What you actually want is to say "my package depends on pkg-b" and have the package manager figure out that pkg-b is just in the folder next to you. That's exactly what workspaces do!

The solution

This seems straightforward to implement. The package manager knows where all workspaces are, so it could point to the right folder when it finds a matching dependency name. But there's a catch: the dependency resolution of the package manager (npm, Yarn) is separate from the import resolution of the runtime (Node.js).

If you've ever looked into your node_modules and found dependencies nested inside other dependencies instead of a flat structure, this is why. The package manager has no influence on how Node.js finds imports³, all it can do is lay them out on disk in a way that Node.js will understand.

How Node.js finds packages

The high-level idea is simple:

If the import is a relative or absolute path (./, ../, or /), Node.js follows that path directly.
Otherwise, it looks for the import name in the nearest node_modules folder, starting from the current file's directory, walking up the folder tree until it finds a match or reaches the filesystem root.

For example, if we want to import e.g. left-pad, Node.js checks these folders in order:

From ~/projects/app/src/utils.js:

~/projects/app/src/node_modules/left-pad
~/projects/app/node_modules/left-pad
~/projects/node_modules/left-pad
~/node_modules/left-pad

Symlinks tie it all together

We know we don't want multiple copies of the same workspace in different node_modules folders, because that would bring back all the problems we discussed. Instead, we can use symlinks. As a refresher: they are special files that just "redirect" to another file or folder when accessed.

So now, this just becomes a problem of how to arrange the symlinks in the node_modules folders for Node.js. And the solution: we'll create a symlink to each workspace in the top-level node_modules folder. Since Node.js walks up the directory tree looking for that folder, every workspace will eventually find the root one:

package-root/
- node_modules/
  - sub-a (symlink to sub-a)
  - sub-b (symlink to sub-b)
  - sub-c (symlink to sub-c)
- sub-a/
  - package.json
  - ...
- sub-b/
  - package.json
  - ...
- sub-c/
  - package.json
  - ...

Here's an example:

import { foo } from "sub-b";
console.log(foo());

export function foo() {
  return "Hello from sub-b!";
}

How does Node.js resolve the import in sub-a/index.js?

package-root/sub-a/node_modules/sub-b → doesn't exist
package-root/node_modules/sub-b → symlink to package-root/sub-b/, follow it
package-root/sub-b → found it!

By placing symlinks in the top-level node_modules, any workspace can import any other workspace by name, and Node.js finds it correctly.

When (not) to use workspaces

While workspaces are pretty useful, they are not a silver bullet. That is, you shouldn't go link every project in your ~/dev folder just yet. Instead, they should be treated as a scoped feature, with a clear sweet spot.

In general, workspaces work best for projects that:

Consist of multiple packages
Will be developed in tandem
Share many dependencies
Call each other frequently

That's why workspaces are mostly used in monorepos: almost by definition, they satisfy all of these criteria. Wasp uses them outside the monorepo context, but that's because we generate packages for each part of your app, that are tightly coupled and evolve together.

On the other hand, I'd discourage using workspaces when:

You don't have a good reason to split a single codebase or repo into multiple packages. Workspaces solve problems, but it's better if you don't have those problems in the first place.
Your packages are mostly independent and don't share many dependencies. I wouldn't use workspaces to link all the random libraries in my ~/dev folder. It could lead to random interference between dependencies, or implicit relationships.
You have cyclic dependencies. Without a clear story of which packages depend on which⁴, workspaces can allow any package depend on any other carelessly, and that can lead to a tangled web of dependencies.
Your project is split across multiple repositories. Workspaces would make them no longer self-contained. Unless you're very sure of your use case, either unlink the repos altogether or merge them into a single monorepo.

Why does Wasp care about workspaces?

When you run the Wasp compiler, it generates app code into a .wasp/ folder inside your project. And part of that generated code is three different packages: one for the SDK we generate from your Wasp spec, and a frontend and backend package that contain the final codebase for your deployed apps.

Those three packages are tightly coupled, with frequent imports across packages, and also to your own code. They also share many dependencies, and we want to avoid any chance of mismatches or duplication between them.

As part of our push for Wasp 1.0, we wanted to make this situation easier to work with, and we realized workspaces were a perfect fit for our problems. We worked on a project internally called Wasp Citizen, so we could capitalize on workspaces to ease our dependency mismatch issues.

Since Wasp v0.19, this is at work in every Wasp project. Your app still works as a single-package project and you don't need to learn anything new; but internally, the generated packages are structured as workspaces. This translates to a better experience for you, fewer weird bugs for us, and quicker installs for everyone.

And with this knowledge, if you want, now you can add your own workspaces to your Wasp project too, and have them play nicely with the generated ones!

Go off!

Workspaces are a powerful tool that help you organize your code, avoid dependency errors, and speed up your development workflow. I hope this post has given you a good understanding of how they work under the hood and when to use them. If you find yourself in a situation where workspaces could help you, give them a try!

Until next time, happy coding!

Yarn has a great glossary that you can check out if you want to get specific definitions for a package-manager-related term, and pointers to which feature they're a part of. ↩
This is one of the reasons React requires a single copy in your app. React relies on a single instance to track internal state (hooks, context, and reconciler). If you had two copies, components created with one wouldn't be recognized by the other, leading to cryptic errors. ↩
Some newer runtimes have the package manager integrated directly into execution, so they can control both installation and resolution, and simply point to the right folder. For example, Deno doesn't even install dependencies in your project folder. Instead, it keeps a single global copy in an internal cache that it can programmatically reference. ↩
Yarn has some great features that force you to be exhaustive about how your workspaces are structured. By default, you have to explicitly declare which other workspaces you depend on. They also have a workspace constraints feature that lets you enforce rules on which packages can depend on which others. This one has a steep learning curve, but it's worth it if you're working on a very big monorepo. ↩