File Based Routing confusion

[rieger-jared]

Hi all,

I'm evaluating whether react router would be a good fit for my team. We enjoy using file based routing so we find that this feature is quite important to us to adopt it. However I'm struggling with the mental model of the routing behaviour and what I'm expecting to work is not.

I have the follow tree structure

app
├── app.css
├── data.ts
├── root.tsx
├── routes
 │   ├── contacts
 │    │   └── route.tsx
 │   ├── contacts_.$contactId
 │    │   └── route.tsx
 │   ├── contacts_.$contactId.addresses
 │    │   └── route.tsx
 │   ├── contacts_.$contactId.addresses.$addressId
 │    │   └── route.tsx
 │   └── route.tsx
└── routes.ts

The nested param routes don't seem to map to my expected routes. I'm expecting that we'd have

/contacts -> /contacts/route.tsx
/contacts/1 -> /contacts/1/route.tsx
/contacts/1/addresses -> /contacts/1/addresses/route.tsx
/contacts/1/addresses/1 -> /contacts/1/addresses/1/route.tsx

What actually happens

/contacts -> /contacts/route.tsx
/contacts/1 -> /contacts/1/route.tsx
/contacts/addresses -> /contacts/addresses/route.tsx
/contacts/1/addresses ->  /contacts/1/route.tsx
/contacts/1/addresses/1 ->  /contacts/1/route.tsx
/contacts/addresses/1 -> 404

Now ideally I would've thought this nesting would work, but other than /contacts working everything else results in a 404.

app
├── app.css
├── data.ts
├── root.tsx
├── routes
│   ├── contacts
│   │   ├── $contactId
│   │   │   ├── addresses
│   │   │   │   ├── $addressId.tsx
│   │   │   │   └── route.tsx
│   │   │   └── route.tsx
│   │   └── route.tsx
│   └── route.tsx
└── routes.ts

How does the routing behaviour actually work? I've read these docs but I'm not sure how that shows how to handle nested file routing.

[sergiodxa]

The _ at the beginning or end of a route segment change how the file convention treat the route.

In your case you have routes/contacts (let's ignore if it's contacts.tsx or contacts/route.tsx as it doesn't affect here), this defines a route at /contacts.

Then the rest of your routes start with routes/contacts_.something, the _ at the end here tells the router you want /contacts in the URL but you don't want to be nested inside the routes/contacts UI.

So using your whole example:

├── routes
│   ├── contacts
│   │   └── route.tsx
│   ├── contacts_.$contactId
│   │   └── route.tsx
│   ├── contacts_.$contactId.addresses
│   │   └── route.tsx
│   ├── contacts_.$contactId.addresses.$addressId
│   │   └── route.tsx

This will defined these URLs:

• /contacts -> matches root + routes/contacts
• /contacts/:contactId -> matches root + routes/contacts_.$contactId
• /contacts/:contactId/addresses -> matches root + routes/contacts_.$contactId + contacts_.$contactId.addresses
• /contacts/:contactId/addresses/:addressId -> matches root + routes/contacts_.$contactId + contacts_.$contactId.addresses + contacts_.$contactId.addresses.$addressId

See how the routes/contacts route is only used on /contacts, after that every other route is using /contacts/ in the URL but is not using the UI. If you want to reuse the UI you need to remove the _ from contacts_ in the other routes.

---

Related to the docs section you linked about using folders for organization, the file convention is flat based, that means you don't nest folder to nest routes.

You use the file names following conventions like using . to split in segments (basically every . becomes a /) and using _ to define if you want a route to be pathless (do not include any segment in the URL) by starting the segment with _, or to add the path but not the UI (what you did) by ending the segment with _

So folders here are used to organize code for that specific route. This means that you can do:

• routes/contacts_.$contactId.addresses.$addressId.tsx
• routes/contacts_.$contactId.addresses.$addressId/route.tsx

And both files will be considered the same route, so instead of using the file name (first example) to know how the route will work you use you can use the folder name (second example).

The second way allows you to add other files like maybe a component, a utility function, tests, assets like images or CSS files. etc. so you can end up with:

routes/contacts_.$contactId.addresses.$addressId
├── route.tsx
├── route.test.tsx
├── components/carousel.tsx
├── hooks/use-carousel-state.ts
├── assets/styles.css
├── assets/placeholder.png
└── utils.ts

And only the route.tsx will be used as the route file, every other file is ignored by the convention.

---

All of that said, if you're not convinced on the convention, the routes.ts let's you define routes manually or even come up with a custom convention, use any pattern you want to find what files exists in your app folder and then define routes yourself using those files.