Remix Flat Routes – An Evolution in Routing

Hi, I'm Michael Porter. You may know me online as Killamon, which is short for Killamonjaro. I've been a big fan of volcanoes for a long time. I'm excited to be speaking to you today at RemixConf Europe. My presentation will be on Remix Flat Routes and Evolution in Routing.

First, I'll start by giving a brief introduction on the current routing convention as we know it today. Here is a typical routing structure. It consists of a pathless layout for public pages, like the about page, a user section with its own layout which has a list view, a user detail view, as well as an edit page. Remix uses folders to determine the parent layout. It is expected that the parent layout will include an outlet to render its children. In this example, there is no user ID folder because we want the edit page to use the same user's layout as the other routes. Since the edit page is not nested, we use the dot for flat layout instead of the nested layout. When you create a nested layout, Remix requires you to create a folder for its children, plus a file for the layout itself. Unfortunately, one of the drawbacks of this convention is that the folder in a layout file ends up separated in your editor, since folders are typically displayed first. This can be annoying, especially on large applications with many routes.

As you know, Next.js recently introduced their own take on nested layouts. Let's compare their convention with Remix. Here is the same routing structure as the previous example. Next.js uses parentheses for pathless layouts, similar to Remix's double underscore prefix. The one thing you'll notice is that Next.js requires a folder for every segment of the route. The leaf route is a file named page. If a route segment adds a layout, you create a layout file. With Next., layouts and pages are separate things, whereas Remix doesn't differentiate. Again, looking back at our user edit route, Next.js looks for the closest layout, which is user slash layout. Another major difference with Remix is that Remix uses named exports for things like meta, links, headers, error boundary, etcetera. And Next.js uses separate files for each. This can result in a large number of files, depending on your app's needs. It led one person on Twitter to tweet this screenshot. Granted, this is an extreme example. One of the benefits of a folder for each route, though, is that Next.js does let you co-locate supporting files in the route folder.

Things like CSS, components, images, etcetera. This is one of the main things Remix devs have been asking for. We'll discuss how Remix FlatRoutes supports this shortly.

Now that we have that out of the way, let's discuss the new Remix FlatRoutes convention. It's currently a separate MPM package, but will be included in a future version of Remix as core functionality.

So what are the goals of the Remix FlatRoutes? Make it easier to see the route your app is designed. Just pop open the Routes folder, and they're all right there. Since the file system typically sorts folders first, when you have dozens of routes, it's hard to see which folders have layouts and which don't today. Now all related routes are sorted together. Allow co-location of support files with routes. You'll see how you can keep your styles, components, and other supporting files with your routes. Decrease refactor and redesign friction. While code editors are pretty good at fixing up imports when you move files around, and Remix does have the tilde import alias, it's just generally easier to refactor code base that doesn't have a bunch of nested folders. Remix will no longer require this. Additionally, when redesigning the user interface, it's simpler to adjust the names of the files rather than creating and deleting folders and moving routes around to change the way they nest. And finally, help apps migrate to Remix. Existing apps typically don't have a nested routes folder structure like today's conventions. Moving to Remix is arduous because you have to deal with all of the imports. Also, as we saw with Next's new nested layouts, FlatRoutes make it easier to migrate from other frameworks to Remix.

So Remix FlatRoutes was first introduced as a gist by Brian Florence back on April 7th of this year. He posted the link on the Remix board, and I just happened to see it. And I was intrigued because I, too, was looking to simplify my routing structure. Less than two weeks later, I made the first commit implementing the FlatRoutes spec. The trickiest part was trying to figure out how to determine the parent layout when there were no folders. Simply a dot separated file name. We'll discuss how that was implemented in a little while. An interesting point is that it wasn't until a month later that Next.js posted the first layouts RFC, describing their new nested layouts convention, which is now available as an experimental feature in Next.js 13. As I mentioned before, Remix FlatRoutes is currently implemented as a separate package. To add it to your app, simply npm install dash d RemixFlatRoutes. Since routes are determined at build time, this is a dev dependency and is not needed at run time.

One of the things about Remix is that although it's opinionated, it does have some escape hatches that let you add your own customizations. In this case, it's the routes configuration where you can add your own routes in addition to the default convention.

Since Remix assumes the files in the routes folder use the default convention, you'll need to tell Remix to ignore all files in the routes folder. Finally, call the FlatRoutes function to scan the folder using the new FlatRoutes convention. In the future, you'll be able to specify which convention you want to use directly through the Remix config file.

RemixFlatRoutes changes some of the file naming conventions that we're used to. For example, for pathless layouts, use a single underscore instead of a double underscore prefix. The params prefix remains the same, the dollar sign, but I'll show you how we can change that later. Instead of using folders for routes, the filename includes the entire route, so use the dot instead of slash to separate URL segments. And finally, to handle scenarios like our user edit route, the underscore suffix specifies the segment is not a layout because it has no outlet. I'll demonstrate this later.

Remix FlatRoute supports two configurations, flat files and flat folders. Flat files will typically be used for simpler apps as everything is in the filename and there are no folders. Here is the same example we used before, but using the flat files convention. Notice that there are no folders. The entire URL structure is visible at a glance without having to drill down into separate folders. We still have to identify the index route, in this case, users slash index. Notice how we named the file users dot index. The leading underscore here is simply to sort the index route before the other child routes.

As I mentioned, we are using dots instead of folders to separate the paths. But without folders, how does Remix know what the parent layout is? To determine the parent layout, Remix Flat Routes finds the longest matching prefix, and that determines the parent layout. Here we see that public prefix of public dot about matches the public TSX layout. Same with users. Remember in the previous example, where we didn't want the edit route to nest under user ID? There, we used dots in the file name to deal with it. But how do you deal with that when everything uses dots? Remix Flat Route allows you to use a trailing underscore on a parent route to specify that this is not a layout. As you can see in the edit route, the user ID should not be treated as a parent layout, hence the underscore. This ensures that users that user ID prefix is not matched with that route. And Remix will then look to the next segment for a matching layout, which is the users layout.

Although Flat File simplifies the routing convention considerably, it does so with some drawbacks. There are no folders.

We cannot co-locate supporting files with our routes. Even if we were to add rules to ignore these other files, it would require you to import them with the full path, not exactly simplifying things. Flat folders look just like Flat Files. The main difference is that instead of the routing being a simple file name, the folder itself is the route name. The route file, index.tsx, is located inside the folder. This is similar to the Next.js page file.

Remix doesn't differentiate between routes and layouts. Again, layouts are simply routes with outlets. So, index.tsx or layout.tsx mean the same thing. They are simply aliases and are mainly used to be more descriptive when looking at your routes. Remix supports multiple aliases for the route file. You can use either index, route, layout, or page, as well as add the underscore prefix. This helps sort route and layout files to the top of the file list when co-locating files.

As we stated before, one of the main benefits of the Flat Folders convention is to support co-location. Here we are co-locating support files like CSS, components, server files, images, etc. Your route file will now let you import these assets as a relative import. I've been experimenting with splitting my route file into a route and a route server file. The main reason is that I use Zod for validation, and the package is kind of heavy. By only defining and using the Zod schema in the server file, I guarantee that Zod does not end up in the client bundle.

So now that we've seen the benefits of Flat Routes, how do we migrate our existing app? The Remix Flat Routes package includes a migration tool. Simply run the command mpx migrate-flat-routes and specify the source and target folders. The folders must be different to prevent the tool from overwriting your original routes. You can specify whether you want flat files or flat folders. Here's a screenshot of the routes from the sample Fakebooks app before and after migration. You can see that it lets you quickly see how your routes are structured without having to expand the folders. One way to verify that the migration went smoothly is to run the mpx-remix-routes command on the original routes as well as the migrated routes. Since remix-flat-routes creates the same route configuration that was generated by the default convention, the routes should be identical both in hierarchy and paths. The only differences are the file names, and maybe some sorting.