Looking at the options I immediately thought there's clearly an option missing.

Let's start with a little of my history

I started programming at the age 12 before I even knew that what I was doing was called programming. My first steps into the web were in PHP. You know, I needed to have that "cool" clan website that me and all my other 12 year old friends could post messages on talking about how "cool" we were playing medal of honor. Thus my introduction to file based routing. It was awesome, easy to understand and to find whatever horribly named php file I had that rendered that music filled flash animation intro page. Again, needed to express how "cool" my clan was.

After high school I got my resume out there will all that PHP experience I had built up. I'd get call after call of interviewers interested in me because they liked my resume, but the moment they found out I just finished high school they all just assumed I wouldn't want to work for them. Which lead me to college and learning things like Java, C# and eventually ASP webforms (which was still very much file based). After getting that degree, I started a job at a design agency.

Now I was fresh into my career and ASP.NET MVC 3 was the new hotness. This was when config based routing started getting injected into my veins. There were default conventions for my controllers and actions but as more and more versions of Microsoft's framework were released, there were more and more config options to change things to my liking.

Now, I'll save you 15 years of personal history of using different web technologies and frameworks like .NET, PHP, Knockout, Durandal, Aurelia, Angular and React; and fast forward to being a Remix supporter.

File based routing was back and with it the rush of nostalgia. The memories of being a teenager working on my silly hobby listening to the sweet rhythm of Suga Suga by Baby Bash. Boy did I miss file based routing. There was something so simple about having your URL match the file system. No longer was I pouring through config files to figure out where that button was that I needed to update.

So which should you choose?

It depends, everyone's favorite answer. I love file based routing because for me, it's easier to wrap my head around my routes and find them. File based routing is great for small to medium sized apps, but often, over time as you add feature after feature, file based routing starts to get messy. Which brings me to one of my favorite things about Remix: levers!

There are tradeoffs for just about everything in life. Some are better than others for the situation. Remix gives you tons of levers to pull and push depending on what you need. That includes the ability to pull that lever from "file based routing" to "config based routing".

There is one thing about levers that often gets overlooked: it's not a toggle button, it's not binary, it's not a simple on and off switch. You can take that lever (or as the roller skating DJ side of me likes to think of it more like a slider) and push it as far as you need to in either direction. Is your project starting to get too big and needs some reorganizing? Do it. Want to keep some file based routing? Do it.

Some of this, some of that, and a little of both

At work we've got a new shiny SaaS product (+4 years in the making). Overtime we've gone from CRA straight to Remix and slowly converting our pages to use the loaders and actions. This product has what our product team calls "modules" which are different feature sets that our customers can enable or disable. Some of these features are larger than others and it was important to make sure these features didn't accidentally bleed into one another.

We created a custom routing configuration for Remix that would more easily allow us to keep these "modules" separated. Here's what a typical remix project's "app" folder often looks like for our company:

/app
    /components
    /helpers
    /routes
    /utils

This is fine for smaller projects, but our project needed some separation. Nothing super special about this, but this is what we ended up with:

/app
    /auth
    /core
    /feature-1
    /feature-2
    /portal
    /shared

Under each of these "module" folders, they each have their own routes, components, helpers and utilities. That way, each "module" can have it's own components that are only related to it's module. Anything that is shared across multiple modules, like a button for example, can be found under the "shared" module. Here's a quick description of what some of these "modules" do that'll hopefully give enough context to how we split things in the code further down:

• auth - all routes related to handling Azure B2C authentication, signups, invites, etc.

• core - this is the core module that every customer has. It has settings, users, permissions, navigation, etc.

• shared - there are no routes here, this is just a shared place to put more generic components, helpers and utilities.

• feature-X - these are what our product team calls "modules" that differ which are enabled from customer to customer.

• portal - part of our product is helping our customers gather documents and forms from their suppliers. When our customer needs a document from one of their supplier, they create a document upload task. An email gets sent to that supplier with a specialized URL that allows them to complete the task assigned to them easily without having to log in. This module really should probably be a separate site since authentication and the look and feel are very different, but this was a very early feature.

Alright, let's get to some code. Here's our routes config for Remix:

import { loadModuleRoutes } from './module-routes.js'

/** @type {import('@remix-run/dev').AppConfig} */
var appConfig = {
  routes: async defineRoutes => {
    return loadModuleRoutes(
      appConfig.appDirectory, 
      [
        { 
          path: 'auth' 
        },
        { 
          path: 'portal', 
          prefix: 'portal',
          layout: 'portal/routes/__portal-layout',
        },
        {
          path: 'feature-1',
            prefix: 'feature-1',
          rootLayout: 'core/routes/__global-layout',
          layout: 'feature-1/routes/__feature-1-layout',
        },
        { 
          path: 'core', 
          rootLayout: 'core/routes/__global-layout'
        }
      ],
      defineRoutes,
    )
  },
  // rest of remix config here...
}

export default appConfig

Let's briefly talk about what's going on here. We have a custom module-routes.js file that exports a loadModuleRoutes function. This function takes 3 arguments. First the app directory (aka "app"), second an array of our desired modules, and last is the defineRoutes function provided by Remix. The part that is most interesting is our array of modules, here's the properties:

• path - this is the folder path to our module that contains file based routing in a routes folder (app/[path]/routes).

• prefix (optional) - this is if we want to prefix the url with a segment. In the example above for our "portal" module, we prefix with "portal" so all routes in that module are under the URL /portal/*. (You'll note that we have multiple modules that don't have prefixes. Core adds things like /users/* and /settings whereas Auth adds /login, /signup, etc.

• rootLayout - most of our modules share the same navigation shell. This property points to what file path is our main layout, the piece that adds all of the styling, navigation, etc.

• layout - some modules need to setup their own layout to populate any providers that they might need. I could have done a pathless layout in the module itself, but we didn't want to clutter the routes folder when we were already halfway configured for it.

Now for the loadModuleRoutes code. A couple of disclaimers: we wrote this code a year or so ago, future Kevin rarely likes past Kevin's styling of coding so I'm sure there are problems. There are better ways to do things, but I rather finish writing this post than clean this guy up. I've added a few more comments in the code to explain some details.

import { flatRoutes } from 'remix-flat-routes'

export function loadModuleRoutes(appDirectory, moduleConfigs, defineRoutes) {
    appDirectory = appDirectory || 'app'
    const routes = {}

    for (const moduleConfig of moduleConfigs) {
        // load module routes from `remix-flat-routes`
        const moduleRoutes = flatRoutes(`${moduleConfig.path}/routes`, defineRoutes, {
            appDir: appDirectory,
        })

        // loop over each route and add parent routes, prefixes, etc.
        for (const key of Object.keys(moduleRoutes)) {
            const route = moduleRoutes[key]

            // if no parentId, default to `root`    
            route.parentId = route.parentId || 'root'

            // if our module has a prefix,            
            // our current route's parent is root,
            // and we aren't the layout
            // add the prefix to the route path 
            if (
                moduleConfig.prefix &&
                route.parentId === 'root' &&
                route.id !== moduleConfig.layout
            ) {
                // if we have path, add the prefix on the front
                if (route.path) {
                    route.path = moduleConfig.prefix + '/' + route.path
                } else {
                    // otherwise we're the index of the module
                    // set our path to the prefix  
                    route.path = moduleConfig.prefix
                }
            }

            // if our module has a layout defined,
            // our parent route is the root and
            // we aren't the layout, set our parent to the layout
            if (
                moduleConfig.layout &&
                route.parentId === 'root' &&
                route.id !== moduleConfig.layout
            ) {
                route.parentId = moduleConfig.layout
            }

            // if our module has a root layout defined,
            // our parent route is the root and
            // we aren't the root layout, set our parent to the root layout
            if (
                moduleConfig.rootLayout &&
                route.parentId === 'root' &&
                route.id !== moduleConfig.rootLayout
            ) {
                route.parentId = moduleConfig.rootLayout
            }
        }

        // merge our module routes to our full routes object
        mergeRoutes(moduleRoutes, routes)
    }

    return routes
}

Hopefully the comments in that file make it clear what we're doing. This is a great way to get the best of both worlds. Being able to have some extra configuration to break things up into feature modules that our product team wants, but still be able to take advantage of file based routing with co-located components.

Pull the levers that help you solve the problem you have.

One of the benefits of removing code is you no longer have to maintain it. It's just gone. You'll never ask yourself, "Is this code still needed?" if it doesn't exist. Have you ever opened up your codebase and found some code written way too long ago and wondered if it was safe to remove? It's kind of like this:

"Not sure if it's safe to remove this bit, so we'll leave it there just in case."
- some developer

Now the magic question is, how do we find code to remove? Insert Knip

What is Knip?

Now normally when you are browsing the Twitter 𝕏 developer crowd you typically end up with a bunch of hot takes, arguments over whose framework sucks, blah blah blah. But for every 50 hot takes, occasionally you will land on something useful posted on 𝕏. That's where I first heard about Knip. The creators describe it as:

"Knip finds unused files, dependencies and exports in your JavaScript and TypeScript projects. Less code and dependencies lead to improved performance, less maintenance and easier refactorings."

Now this isn't the first tool of its kind. Many different languages and frameworks have similar tools to help you find unused code. The trick is helping Knip know more about your project so it can help you find all those magical lines of code just waiting to be deleted.

An Existing Complex Project

For the rest of this article, I'll talk about the steps I've taken on a project at work to get it up and running using Knip. Due to the private nature of the project, I'll be focusing more on Knip and less on the decisions that were made on the project itself.

Initial Setup and Run

First thing first, let's install it as a dev dependency, add it as a script in our package.json and just run it and see what happens.

Install Knip:

npm install knip --save-dev

Updated our package.json scripts:

{
  "scripts": {
    "knip": "knip"
  }
}

Now let's run it and see what happens:

npm run knip

Now if you have any sizable project, once this finishes turning the numbers, you'll likely get a giant list of unused things to delete. Our project had so many things that my terminal in vscode wouldn't even show me the whole thing. It was massive.

False Positives & Default Configuration

Skimming the list of what has been reported by Knip, I learned quickly that a huge amount of the findings were NOT safe to delete. In fact, tons of what was shown there were things I knew were being used everywhere. Let's check out the default configuration for Knip.

A simplified example of their defaults from their documentation is:

{
  "entry": ["index.js", "src/index.js"],
  "project": ["**/*.js"]
}

Our project at work is built with Remix. If you've used that framework before you'll immediately know that Remix has several entry files: "root.tsx", "entry.client.tsx" and "entry.server.tsx" files along with every single route file.

Fortunately, Knip has several plugins that get automatically detected for us and used to make it smarter for understanding your code. It even has a plugin for Remix.

Their Remix plugin will be enabled when it finds any dependencies or dev dependencies that include @remix-run in the name. If it detects Remix, it will add a whole load of entry files:

{
  "remix": {
    "entry": [
      "remix.config.js",
      "remix.init/index.js",
      "app/root.tsx",
      "app/entry.{client,server}.{js,jsx,ts,tsx}",
      "app/routes/**/*.{js,ts,tsx}",
      "server.{js,ts}"
    ]
  }
}

This is fantastic if your project doesn't modify any of the default conventions in Remix, it should just work. But what do you do if you've heavily modified your Remix routing conventions? Well, you're in luck because our project does exactly that.

Disabling Built-In Plugins

Our project at work customizes how routing works in Remix because of its scale and product requirements. Typically with Remix, you'll see an "app" folder that contains other folders like "components", "routes", etc. We've customized our routing to be split into logical modules that our product team has defined. You can think of these are features customers can turn on and off depending on what they pay for. We also have a few modules that are dedicated to authentication, core sections that all customers get, and even shared components that are used across multiple modules.

So an example of our file structure may look roughly like this:

app
├── auth
│   ├── helpers
│   ├── routes
│   └── services
├── core
│   ├── components
│   ├── helpers
│   └── routes
├── module-1
│   ├── components
│   ├── helpers
│   ├── routes
│   └── utils
├── module-2
│   ├── components
│   └── routes
└── shared
    └── compoents

As you as see, the Remix plugin for Knip isn't exactly what we want, so we need to disable it and configure new entry points for our application. We'll create a knip.json file in the root to use as our config. We'll also add a "$schema" value at the top to help vscode give us some intellisense.

{
  "$schema": "https://unpkg.com/knip@2/schema.json",
  "remix": false,
  "entry": [
    "server.js",
    "remix.config.js",
    "app/root.tsx",
    "app/entry.{client,server}.tsx",
    "app/{auth,core,module-1,module-2}/routes/**/{index,_layout}.{ts,tsx}",
    "app/{auth,core,module-1,module-2}/routes/*.{ts,tsx}",
    "app/core/routes/__global-layout.tsx"
  ],
  "project": [
    "remix.config.js", 
    "server.js", 
    "module-routes.js", 
    "app/**/*.{tsx,ts}"
  ],
}

Let's walk through each section and give a quick summary of what we're doing here.

  "remix": false,

This disables their built-in Remix plugin.

  "entry": [
    "server.js",
    "remix.config.js",
    "app/root.tsx",
    "app/entry.{client,server}.tsx",
    "app/core/routes/__global-layout.tsx"
    "app/{auth,core,module-1,module-2}/routes/*.{ts,tsx}",
    "app/{auth,core,module-1,module-2}/routes/**/{index,_layout}.{ts,tsx}",
  ],

Here we've defined our new entry files. Most of this is similar to the Remix plugin until we get to the section about our modules and their routes. The other files should be easy to understand so I'll talk about the last 3.

app/core/routes/__global-layout.tsx

We have a global layout that has the primary navigation for our application that most modules use. We have configurations where an individual module can opt out of the global layout if they want to build some other kind of navigation or perhaps be used as an unauthenticated section.

app/{auth,core,module-1,module-2}/routes/*.{ts,tsx}

This entry includes any ts or tsx files that are in the root of our routes folder.

app/{auth,core,module-1,module-2}/routes/**/{index,_layout}.{ts,tsx}

This one is a bit more hairy without some context. To try not to bore you, I'll try to make this quick, we're using Kiliman's remix-flat-routes for our routing. We love being able to co-locate components, hooks, utilities, and any other files we need that are only used for a specific route. This helps us not bloat our other folders with code that is only used for a single page. Remix v2 by default uses a flat routes convention but we've opted into using Kiliman's flat routes library because of its ability to have "Nested folders" while still enjoying the flat files convention and co-locating our code.

Example using default flat routes with Remix:

routes
├── admin
├── admin._index
├── admin.users._index
├── admin.users.$userId._index
├── admin.users.$userId.edit
├── admin.users.create
├── admin.settings._index
├── some-route
├── some-route._index
├── some-route.nested-item._index
├── some-other
└── some-other._index

Imagine having other 50+ routes. This is where the "Nested folders" come in. You can simply add group routes in another folder and as long as it's suffixed with "+" it won't be treated as a flat route but a grouping of flat routes.

Example using remix-flat-routes with "Nested folders":

routes
├── admin+
│   ├── _index
│   ├── users._index
│   ├── users.$userId._index
│   ├── users.$userId.edit
│   ├── users.create
│   ├── settings._index
│   └── _layout.tsx
├── some-route+
│   ├── _index
│   ├── nested-item._index
│   └── _layout.tsx
└── some-other+
    ├── _index
    └── _layout.tsx

Now when I'm looking at our routes, I'm greeted with fewer folders that group my routes in logical ways.

  "project": [
    "remix.config.js", 
    "server.js", 
    "module-routes.js", 
    "app/**/*.{tsx,ts}"
  ],

Our project root has lots of different folders. Several of those folders are strictly for our QA team for them to write automation that is separate from our application. So we're defining all the files we want Knip to check. We've got 3 root files then everything else is every file under our "app" directory.

Let's run Knip again and see if our list is any better. Spoiler alert, it's not yet. We have a MASSIVE list still, many falling under Unused exported types or Unused exported types in namespaces.

Unused Exported Types

397 unused exported types. That's a lot of "unused" exported types. Let's first talk about what this is, why my project has so many of them, and what we can do about it.

What is an unused exported type?

Hopefully, the phrase speaks for itself, but it is a TypeScript type or interface that is being exported, but is never imported into another file.

export type FavoriteColor = 'red' | 'blue' | 'green'

export interface Person {
  name: string
  age: number
  favoriteColor: FavoriteColor
}

/** 
 * Some other code in the same file, that may or may not reference 
 * our `FavoriteColor` or `Person` types. Note no other files 
 * reference these 2 types.
*/

If nothing in your code base is importing these types, then they will be listed by knip.

Why does my project have so many of these?

Our project has a pattern for how we create React components. Here's an example below.

export interface ButtonProps {
  // button props here
}

export const Button = (props: ButtonProps) => {
  // return button here
}

When we make a component, we export the component itself and that gets used throughout our application. Along with each component, we define an interface with its properties. We also export this type, in cases where another component that consumes it, wants to use its prop type.

After you've built hundreds of components like this, it makes sense why knip has such a large list of unused exports. Now what to do about it?

What are my options to remove these unused exported types?

The obvious answer is to stop exporting it. Boom problem solved. But that wasn't a solution that I was happy with because I'm a stubborn developer and I exported the type for a reason. That reason was "just in case" a consumer wanted to use it.

So now what? Luckily there are some configuration options we can use with Knip.

{
  "ignoreExportsUsedInFile": {
    "interface": true,
    "type": true,
    "enum": true
  },
}

You can either set ignoreExportsUsedInFile for everything by setting that property to true or you can opt into certain things being ignored. As you can see from the example above. We've decided to ignore exports used in files for interfaces, types and enums.

Conclusion

We've made a lot of progress in getting Knip up and going on a fairly large project. We still have some more work to go but we're already starting to see some benefits and finding lots of unused code. You know what unused code means... I get to delete it!

The Scenario

Let's first lay out the scenario. I was tasked with creating a form, one of the fields in our form was to select an assignee (think of an assignee as an existing contact in your app). When you click a "select assignee" you get a modal dialog with tools to help you find who you are looking for, you select it, then hit the submit button for the modal. This updates the form with the selected assignee.

We have 2 forms, the main form on the page, and one in our dialog form. In the HTML world, this is pretty straightforward and works fine. The idea is the dialog would be at the bottom of the body, you can submit the dialog form and then javascript would take over, validate that form and populate that data in the main form.

<form>
    <input type='hidden' name='assigneeId' />
    <button type='button'>Select Assignee</button>
    <!-- other fields and such -->
</form>

<dialog id='select-assignee'>
    <form>
        <!-- UI to search and find an assignee -->
        <input type='hidden' name='assigneeId' />
        <button type='submit'>Select</button>
    </form>
</dialog>

"Why isn't the dialog inside the main form? why have 2 forms?" - no one

When you press the Select Assignee button in the main form, we open the dialog. That dialog can be canceled at any time by closing it out by pressing ESC, hitting the X close button or clicking Cancel. We don't want to change the underlying form until they submit the dialog form.

React Portals

One of my favorite features of React is how easy it is to create dialogs that render their dom at the bottom of your body. This is pretty standard practice to get all the z-indexing to work nicely and have your dialog be on top of everything on your page. The added benefit here is that your portaled element still has access to all the parent contexts. Portaling something in React, keeps it as a child in React's virtual dom.

Let's look at a striped down version of our main form and dialog form in React.

function MainForm() {
    return <form>
        <input type='hidden' name='assigneeId' />
        <button type='button'>Select Assignee</button>
        <DialogForm />
        {/* other fields and such */}
    </form>
}

function DialogForm() {
    return React.createPortal(<dialog id='select-assignee'>
        <form>    
            {/* UI to search and find an assignee */}
            <input type='hidden' name='assigneeId' />
            <button type='submit'>Select</button>
        </form>
    </dialog>, document.body)
}

If you know the virtual dom well, you've probably already put two and two together. Even though the rendered HTML looks like our first example, React's component tree looks different. Our two forms are still nested.

MainForm
    - form
        - input
        - button
        - DialogForm
            - form
                - input
                - button

So when you submit the dialog form, you are also submitting the main form. As someone who has spent 20+ years with HTML, this threw me. I knew about the virtual dom, and I feel like I know a lot more than most React devs. For whatever reason this didn't make sense until I fully isolated it then the lightbulb came on.

Solutions

As with all things, there are many ways to potentially fix this. 3 come to mind quickly.

1. Move <DialogForm> outside of the main form.

2. event.stopPropagation() on the submit handler for the dialog form.

3. Don't use a <form> in the dialog form.

1. Move <DialogForm> Outside of the Main Form

This is a solution and one that will work. In my scenario at work, having more context would tell you this was not an easy option. At work, we create many different form elements. Ranging from <TextField /> to <DatePicker /> to <AssigneeSelector />. You see where I'm going with this. Our end goal is to allow our developers to build forms quickly that have complicated fields. Building a form is as simple as...

<Form>
    <TextField label='Title' name='title' />
    <Select label='type' name='type' />
    <AssigneeSelector label='Assignee' name='assigneeId' />
</Form>

2. event.stopPropagation() on the Submit Handler for the Dialog Form

Depending on the complexity of the dialog form. This solution works rather well and allows our nested form to work without trying to submit our main form.

interface DialogFormProps {
    open?: boolean
    onSelected: (assigneeId: string) => void
}

function DialogForm({ open, onSelected}: DialogFormProps) {
    const onSubmit = (event: React.FormEvent) => {
        event.preventDefault()
        event.stopPropagation()
        // do validation on the form
        onSelected(selectedAssigneeId)
    }

    return React.createPortal(<dialog id='select-assignee'>
        <form onSubmit={onSubmit}>    
            {/* UI to search and find an assignee */}
            <input type='hidden' name='assigneeId' />
            <button type='submit'>Select</button>
        </form>
    </dialog>, document.body)
}

3. Don't use a <form> in the Dialog Form.

There's a lot to be considered with an option like this. It all depends on the complexity of the form in your dialog. Are there lots of fields that need validation to run against? Are you using a 3rd party validation tool that knows how to handle forms? etc.

We have a few of these components that don't use a <form> because the dialog might be a simple list that you scroll through and select a single item from. Not hard to handle a little state and there's virtually no validation needed. Did you select something or not?

Final Remarks

React's virtual dom is not a perfect 1 to 1 match of what gets rendered in the browser's dom. Portaling elements give you a lot of power to get dialogs, toasts, dropdowns, etc flexibility of where they render in the browser's dom. But at the end of the day, it's React's virtual dom that is handling events just because your HTML forms aren't nested, doesn't mean your React forms aren't.