FS Router Variable Routes Issues

After discussing the recent issues of the Hilla FS Router internally, we found several issues that need to be addressed.

The main issue is to understand how different variable parameters interact with each other.
We have three variable parameters that are already implemented but for now they could incorrectly interact with each other.
They are the following:

  • Required Parameter (users/:userId).
  • Optional Parameter (users/:userId?)
  • Wildcard (users/*)

We also have a couple of specific route types that allow us to handle route nesting:

  • Layout (@layout.tsx file). This route type allows us to specify a wrapper around all the descendants for the current URL segment.
  • Index (@index.tsx file). This route type allows us to specify a resolution for the parent route segment that could also have children.
    For example, if you have https://example.com/users which is a list, and you also want each user to have a link like https://example.com/users/123, you must use Index route type for the list.

Also, to make Flow routes integrated seamlessly we have the wildcard route with a Flow component as a fallback for each list of children at any nesting level.

So, let’s check what interactions we have.


If we have a mix of Required/Optional/Wildcard routes including Flow Fallback the route that comes later will never be called because the route that comes first will take over it

NOTE: partial URL parameters are not supported in ReactRouter 6

export default {
  path: 'users',
  children: [
    { path: ':userId' },
    { path: '*' }, // will never be resolved

It makes impossible to use any Flow route in the directory that contains a variable parameter route.
It also requires us to sort the routes more thoroughly because if the variable route is sorted before the regular route, it won’t allow the regular route to resolve.

So, my question here is the following:

  • What is the expected router behavior here for you?
  • Is it ok to omit the Flow Fallback if there is any of variable route present in the directory?
  • How should we handle multiple variable routes in a single directory? Should it be just a compile-time error with an undefined behavior?

About actions that are following from the description, I have these:

  • The variable route should always be at the end of the sequence of routes.


The Optional route looks redundant because in the easy case it could be simply re-made by using Index and Required routes.
The Optional route also creates a set of complicated scenarios, e.g. how the URL should be resolved in this case:


The Optional routes exist in React Router but there is pretty limited documentation about how to use it correctly.

My questions here are the following:

  • What would you expect from the router with Optional route?
  • How to resolve the complex cases like I’ve mentioned above?
  • Do we need to have the optional route as a part of FS Router at all?

File vs Index

We also have a case when the user has specified both a directory and a file with the same name.
The question: what is the expected outcome for this case, especially considering everything said above.

The possible solutions are the following:

  • You cannot create a file and a directory with the same name. To implement this scenario, use Index route.
  • The file has the bigger priority over the directory.

I mostly tend to choose the first option but in the internal discussion we chose the second one.
However, it was done before the issues above were found.

My questions here are the following:

  • What would you expect from the router in this case?
1 Like

Thank you for making the discussion in the forum transparent. It is not easy to find a perfect solution, as many requirements have to be taken into account. As a guideline, I would say that not all scenarios can be considered equally well. You should therefore concentrate on making the FS Router as intuitive as possible in conjunction with Hilla. The option of integrating flow views is great, but should not be at the expense of the developer experience. I would therefore be ok with making a few exceptions or compromises when integrating Flow. For example, I think it would be ok to omit the Flow Fallback if there is any of variable route present in the directory.

Regarding optional routes, I would like to see them as part of FS Router. Sure, your example points out some issues, but I think you shouldn’t exclude a feature, because there are some rough edge cases.

Regarding the case, where you have a directory and a file with the same name, I would prefer that this is possible, but one of them has a higher priority.

1 Like

Thanks for your answer!

What makes you want to be able to have a file and a directory with the same name?

It sounds pretty convincing to me to have an @index route for this case, so files responsible for the same route don’t spread across the parent directory. Do I miss something thinking this way?

Your are right @ausginer, using index route should be ok. I have no specific example in mind, where I need a directory and a file with the same name :wink: