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

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 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 (:id) and

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