• Home
  • Blog
  • Projects
  • Bookshelf
  • About
← Back to all posts

On File-System Routing Conventions

Published ....
Last modified ....

Share this post on BlueskySee discussion on Bluesky

Over the past few weeks (and really past few months) I've been tinkering with a few different ideas to building out a web application framework like Next.js, Remix, or others.

Through that experimentation - I've come to realize that file-system based routing conventions are actually pretty tricky to find the right balance between developer experience, ease to implement (from a framework perspective), and runtime performance.

Let's take a look at a few options:

  • folder-as-route-segment[1]Jump to footnote
  • file-as-route-segment

    • Folder as Route Segment

    This seems to be the most widely adopted pattern that I've seen, you can tell you're working with this pattern when you have a ton of page.tsx, index.tsx, or <some-specific-file-name>.tsx files within your codebase.

    This system leverages the names of folders to indicate the route segment that the handler (e.g. page.tsx, route.ts, etc) should be used to handle the request.

    Next.js's AppRouter opted to use this paradigm.

    An example filesystem might look like:

    app/
  page.tsx # handles `/` route
  blog/
    page.tsx # handles `/blog` route
  dashboard/
    page.tsx # handles `/dashboard` route
    settings/
      page.tsx # handles `/dashboard/settings` route

    File as Route Segment

    This one seems to be maybe slightly less adopted from what I've seen (but that might be a bit of recency bias). In this abstraction, the name of the file itself is also the name of the route segment.

    The Next.js Pages Router used this paradigm.

    Here's an example filesystem where this paradigm is used:

    pages/
  index.tsx # handles `/` route
  blog.tsx # handles `/blog` route
  dashboard/
    index.tsx # handles `/dashboard` route
    settings.tsx # handles `/dashboard/settings` route

    Trade Offs

    As I was working on my latest iteration with exploring building a web framework, I was trying to figure out what the best strategy would be.

    One of the trade offs I've personally noticed (and I think a lot of others have as well) with the folder-as-route-segment approach is your codebase fills up with many page.tsx files. It can be difficult to easily track down the right handler for a specific route segment. You usually need to search within your codebase for something like <route-segment-name>/page (and even then it can get a bit messy when dealing with dynamic route segments or catch all segments).

    On the other hand, the file-as-route-segment approach leads to some ambiguity with how routes should be handled. Sometimes this can be exposed to the developer using the framework too! For example, using the above filesystem (copied below):

    pages/
  index.tsx # handles `/` route
  blog.tsx # handles `/blog` route
  dashboard/
    index.tsx # handles `/dashboard` route
    settings.tsx # handles `/dashboard/settings` route

    Did you notice that technically we could also use pages/dashboard.tsx? In that case, what happens if you have both dashboard/index.tsx and dashboard.tsx? It's possible different frameworks would handle this differently - and sometimes that handling might be counterintuitive to the end developer.

    This one actually gets a bit more confusing when we start introducing "meta route segments", e.g. layout.tsx (a layout component that wraps the page contents) - where should that layout.tsx live in the file-as-route-segment approach? If its under the dashboard/ directory - then it might be weird to see dashboard.tsx get wrapped in dashboard/layout.tsx!

    Summary

    I don't think there's one silver bullet approach that makes sense, is easy to disambiguate, and generally "works as expected" for all use cases.

    I've sadly opted to continue using the folder-as-route-segment approach to avoid some of the ambiguity that arises with the file-as-route-segment approach - but I still don't like that pages are all named the same!

    Have you found a better approach? Please let me know!

    Footnotes:

    ↩Back to reference

    For the context of this blog post, a route segment is the name of a specific slice of the requested path. Usually this is / delimited, e.g. if we have a path that is /foo/bar/baz, then the segments are 'foo', 'bar', and 'baz'.

    Tags:

    Web DevelopmentNext.jsGarbanzoOpinion

    Bluesky Post and Comments:

    Loading comments...

    Loading...

    Matt Hamlin

    Matt Hamlin

    @matthamlin.me

    On File-System Routing Conventions: matthamlin.me/blog/2025/fe...
    On File-System Routing Conventions

    On File-System Routing Conventions

    Some rough thoughts on building a file-system routing based web application

    https://matthamlin.me/blog/2025/february/on-file-system-routing-conventions
    1 year agoView on bsky.app
    1
    2
    0
    0

    Related Posts

    Web Development

    Website Redesign v11

    ....

    I've once again updated my personal website, this time powered by my own RSC framework and a custom CMS solution as well!

    Onboarding Your New AI Teammate

    ....

    Are we reinventing the wheel when it comes to onboarding new AI agents to a codebase, when we already have primitives available for onboarding humans?

    Quick Tip - Theme Aware Images

    ....

    Have you ever found the need to change the image you render on a web page based on the current preferred color scheme of your theme?

    Async Class Creation In JavaScript

    ....

    Have you ever wanted to create a class in JavaScript or TypeScript but also have the initialization be async? Here's a quick tip on a pattern that I've used in the past!

    Website Redesign v10

    ....

    I recently launched a rewrite and redesign of this personal website, I figured I'd talk a bit about the changes and new features that I added along the way!

    Server Side Rendering Compatible CSS Theming

    ....

    A quick tip to implementing CSS theming that's compatible with Server Side Rendered applications!

    Podcasting By Hand

    ....

    A brief overview on how we launched The Bikeshed Podcast, including a deep dive in our recording and distribution workflows!

    Quick Tip - Specific Local Module Declarations

    ....

    A quick tip outlining how to provide specific TypeScript type definitions for a local module!

    You're Building Software Wrong

    ....

    Slicing software: why vertical is better than horizontal.

    Single File Web Apps

    ....

    What if you could author an entire web application in a single file?

    Resetting Controlled Components in Forms

    ....

    A quick way to handle resetting internal state in components when a parent form is submitted!

    A Quick Look at Import Maps

    ....

    A brief look at Import Maps and package.json#imports to support isomorphic JavaScript applications!

    Recommended Tech Talks

    ....

    A collection of tech talks that I regularly re-watch and also recommend to everyone!

    Request for a (minimal) RSC Framework

    ....

    Some features and functionality that I'd like within a React Server Component compatible framework.

    Bluesky Tips and Tools

    ....

    A (running) collection of Bluesky tips, tools, packages, and other misc things!

    The Bookkeeping Pattern

    ....

    A quick look at a small but powerful pattern I've been leveraging as of late!

    TSLite

    ....

    A proposal for a minimal variant of TypeScript!

    Monorepo Tips and Tricks

    ....

    Sharing a few core recommendations when working within monorepos to make your life easier!

    Next.js with Deno v2

    ....

    This is a quick post noting that Next.js should now work with Deno v2!

    Don't Break the Implicit Prop Contract

    ....

    React components have a fundamental contract that is often unstated in their implementation, and you should know about it!

    A Better useSSR Implementation

    ....

    Replace that old useState and useEffect combo for a new and better option!

    My Current Dev Setup

    ....

    A quick look at the applications and tools that I (generally) use day to day for web development!

    Abstract Your API

    ....

    Proposing a solution for sharing core "business" logic across services!

    Tip: Request and Response Headers

    ....

    There's a common gotcha when creating Web Request and Response instances with Headers!

    Using Feature Toggles to De-risk Refactors

    ....

    Feature toggles are often underused by most software development teams, and yet offer so much value during not only feature development but also refactors

    Hohoro

    ....

    A quick introduction to my new side project, hohoro. An incremental JS/TS library build tool!

    Custom Favicon Recipes

    ....

    Two neat tricks for enhancing your site's favicon!

    Corporate Sponsored OSS

    ....

    The various risks and pitfalls of open source software run by corporations.

    The Library-Docs Monorepo Template

    ....

    A monorepo template for managing a library and documentation together.

    Building Better Beacon

    ....

    How we solved an almost show-stopping production bug, and how you can avoid it in your own projects.

    Project Deep Dive: Tails

    ....

    A(nother) deep dive into one of my recent side projects; tails - a plain and simple cocktail recipe app.

    Churn Anxiety

    ....

    When did semver major changes become so scary?

    Service Monitors and Observability

    ....

    Leveraging service monitors properly to improve service observability.

    On Adopting CSS-in-JS

    ....

    A brief recap of how Wayfair changed it's CSS approach not once but twice in the span of 5 years!

    Project Deep Dive: Microfibre

    ....

    A deep dive into one of my recent side projects; microfibre - a minimal text posting application

    Pair Programming

    ....

    Pair programming can be good sometimes - but not all the time

    Suspense Plus GraphQL

    ....

    A few thoughts on using Suspense with GraphQL to optimize application data loading

    You've Launched, Now What?

    ....

    A few thoughts on what to do after you launch a new project

    Taking a Break

    ....

    A few quick thoughts on burn out and taking a break

    Managing Complex UI Component State

    ....

    A few thoughts on managing complex UI component state within React

    Understanding React 16.3 Updates

    ....

    A quick overview of the new lifecycle methods introduced in React 16.3

    CSS in JS

    ....

    A few thoughts and patterns for using styled-jsx or other CSS-in-JS solutions

    Redesign v6

    ....

    A few thoughts on the redesign of my personal site, adopting Next.js and deploying via Now

    JavaScript Weirdness

    ....

    A few weird things about JavaScript

    Calendar

    ....

    Building a calendar web application

    Next.js

    Server Side Rendering Compatible CSS Theming

    ....

    A quick tip to implementing CSS theming that's compatible with Server Side Rendered applications!

    The Bookkeeping Pattern

    ....

    A quick look at a small but powerful pattern I've been leveraging as of late!

    Next.js with Deno v2

    ....

    This is a quick post noting that Next.js should now work with Deno v2!

    Opinion

    Build Momentum

    ....

    The trick to successful habits and getting shit done is to just get started and build momentum.

    The AI Development Conundrum

    ....

    Is it a good or a bad thing to offload writing code to AI agents and Large Language Models?

    Using Feature Toggles to De-risk Refactors

    ....

    Feature toggles are often underused by most software development teams, and yet offer so much value during not only feature development but also refactors

    Funport: True Dynamic Imports in webpack

    ....

    webpack, and tools built on it like Next.js, don't support true dynamic imports, but I found a way to trick the system!

    Project Deep Dive: Tails

    ....

    A(nother) deep dive into one of my recent side projects; tails - a plain and simple cocktail recipe app.

    Project Deep Dive: Microfibre

    ....

    A deep dive into one of my recent side projects; microfibre - a minimal text posting application

    Redesign v6

    ....

    A few thoughts on the redesign of my personal site, adopting Next.js and deploying via Now