Routes and Remix's file structure

As we learned in the Outlet component lesson, Remix uses a file-based routing system. This means that the file structure of your project maps directly to the URL structure of your app.

But what else does this convention allow us to do?

Sibling routes

All files inside the routes folder are children of the root.tsx file. This means that the root.tsx file is the parent for the whole app.

Directoryapp
- root.tsx // parent route
- Directoryroutes
  - _index.tsx // child route

However, files that sit at the same level as others within the routes folder are called siblings.

Any file that we add next to the _index.tsx file will become its sibling, and direct children of root.tsx:

Directoryapp
- Directoryroutes
  - _index.tsx
  - about-us.tsx // sibling route
  - contact.tsx // sibling route

For example, head back over to your browser, and type in the URL http://localhost:3000/news. Hit return and you should see a page not found message:

Page not found

This is to be expected. We haven’t created a route file for /news yet. Let’s create a new file called news.tsx in the routes folder and add the following code to it:

export default function NewsPage() {
  return (
    <main className="flex flex-col py-24">
      <div className="container">
        <h1 className="text-h1">News</h1>
      </div>
    </main>
  )
}

Save the file and head back to your browser. Refresh the page and you should see the new “News” page:

News page

The root.tsx file is still rendering the code for the header and footer, but now the Outlet component we placed earlier is rendering the NewsPage component as its child route.

There are some golden rules to follow when creating route files in Remix:

The file name must end with a .tsx extension
It must be placed inside the routes folder
It must export a React component as the default export, e.g.
app/routes/news.tsx
```
export default function NewsPage() {
  // component code here
}
```
The file name must match the route URL, e.g.
- routes/news.tsx maps to /news.
- routes/about-us.tsx maps to the /about-us URL.
- Spelling, case and special characters are important.
  
  If we named the file AboutUs.tsx, then the URL would be /AboutUs, which is not what we want for the URL in a web app.

Remix route conventions

root.tsx

about-us.tsx

http://localhost:3000/about-us

About Us

HomeAboutContact

Nested routes

What if we want to create a page for each news category, e.g. /news/technology, /news/sport, /news/entertainment etc?

In Remix, this is achieved through a combination of nested and dynamic routes, where one route becomes the child of another.

Add another file to the routes folder called news.$category.tsx:

Inside your new news/$category.tsx file, add the following code:

export default function NewsCategoryPage() {
  return (
    <div className="container py-16">
      <h2 className="text-h2">Generic news category page</h2>
    </div>
  )
}

Open app/routes/news.tsx.

To see a child route rendered in the browser at /news, we also need to add an Outlet component to this file, just like we did earlier in the root.tsx file.

Add the code below to app/routes/news.tsx:

import { Outlet } from 'react-router'

export default function NewsPage() {
  return (
    <main className="flex flex-col py-24">
      <div className="container">
        <h1 className="text-h1">News</h1>
      </div>

      <Outlet />
    </main>
  )
}

Save the file again and head back to your browser.

Visit the URL http://localhost:3000/news/technology.

You should now see the news.$category.tsx route rendered as a child of the “News” page:

Try changing the word ‘technology’ in the URL to ‘sport’, ‘entertainment’, or any other word.

You will see the same generic news category page rendered for each category. We will explain why later.

Just like we did in root.tsx, by adding an Outlet component to the news.tsx file, we have converted it into a parent route that can render child routes.

Let’s add a sub-navigation menu to the parent news page.

Open news.tsx.

Add the code shown below:

import { NavLink, Outlet } from 'react-router'

export default function NewsPage() {
  return (
    <main className="flex flex-col py-24">
      <div className="container">
        <h1 className="text-h1">News</h1>
        <div className="flex space-x-4 py-4">
          <NavLink
            to="technology"
            prefetch="intent"
            className={({ isActive }) =>
              `${isActive ? 'text-blue-300 underline underline-offset-8' : 'text-blue-500'}`
            }
          >
            Technology
          </NavLink>
        </div>
      </div>

      <Outlet />
    </main>
  )
}

The NavLink component is a special Remix <Link> that knows whether it is “active” or not. It does this via a special isActive boolean that Remix supplies for us.

If the user is on the page that the NavLink links to, then isActive turns true and we can apply a different style to the link text via a callback function.

In the example here, we are applying a lighter blue color to the text and an underline to the link when it is active:

<NavLink
  to="technology"
  prefetch="intent"
  className={({ isActive }) =>
    `${isActive ? 'text-blue-300 underline underline-offset-8' : 'text-blue-500'}`
  }
>
  Technology
</NavLink>

More information

You can read more about the NavLink component here in the Remix documentation.

Challenge: extra news categories

Create further NavLinks for the following news categories in the news.tsx file:

Entertainment
Business

When you’ve finished, your final NewsPage component should behave something like this:

Single dynamic route

Don’t worry that the child pages all have the same content. We will fix this in the next lesson.

Solution

Add the following code to app/routes/news.tsx:

import { NavLink, Outlet } from 'react-router'

export default function NewsPage() {
  return (
    <main className="flex flex-col py-24">
      <div className="container">
        <h1 className="text-h1">News</h1>
        <div className="flex space-x-4 py-4">
          <NavLink
            to="technology"
            prefetch="intent"
            className={({ isActive }) =>
              `${isActive ? 'text-blue-300 underline underline-offset-8' : 'text-blue-500'}`
            }
          >
            Technology
          </NavLink>

            <NavLink
              to="entertainment"
              prefetch="intent"
              className={({ isActive }) =>
                `${isActive ? 'text-blue-300 underline underline-offset-8' : 'text-blue-500'}`
              }
            >
              Entertainment
            </NavLink>

            <NavLink
              to="business"
              prefetch="intent"
              className={({ isActive }) =>
                `${isActive ? 'text-blue-300 underline underline-offset-8' : 'text-blue-500'}`
              }
            >
              Business
            </NavLink>
        </div>
      </div>

      <Outlet />
    </main>
  )
}

Save the file and head back to your browser. Refresh the page and you should see the new links in the sub-navigation menu.

Extra news categories

Updating the index page

Remember the code we commented out in app/root.tsx? Let’s use it to update the app/routes/_index.tsx file.

Open app/root.tsx.
Select all the commented code, then cut it so it can be pasted elsewhere:

Open app/routes/_index.tsx.

Replace the JSX currently inside the return statement brackets by pasting the copied code over it.

import { type MetaFunction } from '@remix-run/node'

export const meta: MetaFunction = () => [{ title: 'Epic News' }]

export default function Index() {
  return (
      <main className="grid h-full place-items-center">
        <h1 className="text-mega">
          Hello from{' '}
          <pre className="prose rounded-lg bg-primary p-6 text-primary-foreground">
            app/routes/_index.tsx
          </pre>
        </h1>
      </main>
      {/* <main className="grid h-full place-items-center">
        <h1 className="text-mega">Your Journey Begins!</h1>
        <p className="text-base text-gray-600 md:text-lg lg:text-xl">
          Welcome to Epic News, where the latest developments in tech are found.
        </p>
      </main> */}
  )
}

Uncomment the code by removing {/* and */} from the beginning and end of the code block, then save it:

import { type MetaFunction } from '@remix-run/node'

export const meta: MetaFunction = () => [{ title: 'Epic News' }]

export default function Index() {
  return (
    {/* <main className="grid h-full place-items-center">
      <h1 className="text-mega">Your Journey Begins!</h1>
      <p className="text-base text-gray-600 md:text-lg lg:text-xl">
        Welcome to Epic News, where the latest developments in tech are found.
      </p>
    </main> */}
  )
}

Fix all the broken imports that appear in the app/routes/_index.tsx file.
Imports that begin with a tilde (~) shouldn’t need fixing, as they are relative to the app directory. However, those that begin with a dot (.) are relative to the current file, and will need to be updated.
You can do this by adding the necessary imports at the top of the file. You will need to look carefully at which files you are importing, and from where they are being imported. From this, you will then need to update the import path accordingly.
Automatically sort the imports in both app/routes/_index.tsx and app/routes/root.tsx by using the VS Code keyboard shortcut Shift + Alt + O (on Windows) or Shift + Option + O (on Mac).
Visit http://localhost:3000/ in your browser.

You should see your original code from the root.tsx lesson displayed on the page:

Challenge: The empty news page

We’ve got a little problem.

If we visit http://localhost:3000/news directly, the page looks pretty empty:

Empty news page

Using what you have learned about the _index.tsx special filename and Remix’s file naming convention for parents and children, can you work out how to display the text below when someone visits the http://localhost:3000/news URL directly?

News page with welcome text

When the user clicks on a category, the welcome message shown in the screenshot above should be replaced with the category page.

You can use the code below for the news welcome page content.

export default function NewsPageIndex() {
  return (
    <main className="container py-24">
      <h2 className="text-4xl">
        Select a news category from the choices above...
      </h2>
    </main>
  )
}

The question is: where will you place it?

TIPS

You will need to create a new file in the routes folder to solve this challenge. But what will you call it?
Remember that _index.tsx is a special filename that Remix looks for when a user visits the parent route URL directly.
Placing _index.tsx suffixed to the word news in a filename will mean that the file will be served from the URL http://localhost:3000/news.

After you’ve had a go, check your solution with the one below.

Solution

Because the news.tsx file is the parent route, we can follow Remix’s naming conventions and create a file called news._index.tsx inside our routes folder.

Do this now:
- Directoryapp
  - Directoryroutes
    news.tsx
    news._index.tsx < New file

Add the following code to the new file. This will be the welcome message displayed when the user visits the /news URL:

export default function NewsPageIndex() {
  return (
    <main className="container py-24">
      <h2 className="text-4xl">
        Select a news category from the choices above...
      </h2>
    </main>
  )
}

With this code in place, refresh your page.
When the user visits http://localhost:3000/news, they will see the welcome message displayed on the page, and this will then be replaced by the different category pages when they click on a link:

Fix the empty news page

Summary

In this lesson, we have:

looked at how Remix’s file structure and naming conventions map to the URL structure of application paths in the browser
reviewed how the root.tsx file is the parent layout module for the whole app, and how sibling and child routes are created by adding files to the routes folder
looked at how to create a nested route by naming a file with a period (.) in it
learned how to render the child route in the parent route using the Outlet component
seen, in the ‘Extra Credit’ solution above, how to use the _index.tsx naming convention to render a welcome message when the user visits the parent route URL.
learned how to use the NavLink component to create navigation links between the different routes, and how to apply different styles to the links when they are active.

What’s next?

In the next tutorial, we will look at how to incorporate dynamic routes into our app, and how access the dynamic parts of the URL inside a loader function.