Skip to main content
Amid the chaos of overcomplicated tech, file-based routing turned out to be a nice addition for a few reasons:
  • No need to think about what router to use
  • Creating a new route in a specified directory automatically creates a route
  • No need to create a route map, handle children and all of that
  • Layouts, loading states and route props automatically handled by router

​
Getting Started

Hana Router is automatically added to projects generated using create-hana-app, but if you already have a React project running Vite, you can easily add the router to your project.
1

Install the router

npm install @hanabira/router
2

Add the vite plugin

Open your Vite config file and add the Hana plugin with optional config
import { defineConfig } from 'vite';
import { hana } from '@hanabira/router';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [
    react(),
    hana({
      root: __dirname,
      typescript: true,
      usePageTransition: true,
      mode: 'history',
    }),
  ],
});
A local preview of your documentation will be available at http://localhost:3000.
3

Setup router files

The next step is to create an src/pages folder which will hold all your routes.If you feel the need to have a root file which you can use for initializing libraries like swr, react query or toast libraries, then you can create an src/pages/_app.(jsx/tsx) file which accepts a bunch of children and displays them
const App = ({ children }) => {
  return <>{children}</>;
};

export default App;
4

Update index.html file

Every Vite project ships with an index.html file which loads the entire application. To switch your application to Hana router, you need to update the entry script to .hana/_app.tsx, don’t worry this script will be automatically created by hana on build/dev
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Vite + React + TS</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/.hana/_app.tsx"></script>
  </body>
</html>
And…that’s it!
As mentioned, Hana uses file-based routing, which means creating a file in the pages directory will automatically add a new route for you. For example, let’s add an src/pages/home.tsx file:
home.tsx
export default function Home() {
  return <div>Hello World</div>
}
You will imediately be able to access this page by visiting /home in your browser. It’s that straightforward. Hana will use the slugified version of the file name as the route name without the extension.

​
Ignored Files

We mentioned that every JavaScript or TypeScript file in the pages directory is compiled into a route. However, there are some files that are ignored by the router. These files are:
  • Files that start with an underscore (_)
  • Files that end with .d.ts
These are seen as type declarations or setup files, and will be ignored by the router. Now moving on to files that will actually be loaded, let’s look at index routes

​
Index Routes

Hana automatically maps index files (index.jsx/index.tsx) to the directory name. For example, if you create a file called index.tsx in the pages/home directory, it will create a route for /home. An index.jsx file in the pages directory will create a route for /.
  • pages/index.tsx -> /
  • pages/home/index.jsx -> /home

​
Nested Routes

The router allows you to nest your components within folders to create nested routes. For example, you can add a new /dashboard/settings route by nesting a settings.tsx file inside a dashboard folder or by an index.tsx file inside a settings folder inside a dashboard folder.
  • pages/dashboard/settings.tsx -> /dashboard/settings
  • pages/dashboard/settings/index.tsx -> /dashboard/settings

​
Dynamic Routing

Dynamic routing is the idea of creating routes that aren’t fixed. For example, leaf’s x.com profile is x.com/leafphp, but yours is x.com/username. Since there’s no real way for X to know what username you’d set, your profile link can’t be hardcoded, and so we call that a dynamic route. Hana’s router provides everything you’ll need for dynamic routing right out of the box, and you can find the full documentation here After you’ve added your routes, the next thing is creating a link between them, whether it’s through a navbar, footer or redirects, you can do so easily: 
import { Link,useNavigate } from '@hanabira/router';

export default function Home() {
  const navigate = useNavigate();

  return (
    <div>
      <Link to="/about">About</Link>
      <button onClick={() => navigate('/about')}>About</button>
    </div>
  );
}
You can find the full docs on the navigation page

​
Setup Files

Setup files are files that start with an underscore (_). These files are used to set up different functionality for your app. For example, you can use a setup file to set up global styles or components that should be available to all routes.

​
_app.tsx

The _app.tsx file is used to set up global styles or components that should be available to all routes. It is also used to wrap all routes in a layout component. This file is heavily inspired by Next.js’ _app.tsx file. The example below sets up Hana Store.
src/pages/_app.tsx
import { PersistedState, createStore } from '@hanabira/store';

import './index.css';

createStore({
  state: {
    count: 0,
  },
  reducers: {
    increment(state) {
      return {
        count: state.count + 1,
      };
    },
  },
  plugins: [PersistedState],
});

const Application: React.FC<React.PropsWithChildren> = ({ children }) => {
  return <>{children}</>;
};

export default Application;

​
_error & _404

Hana allows you to set up error handlers for both 500 and 404 errors. You can check out the error handling section to learn more.

​
_loading

Hana allows you to set up a loading component that is shown when a route is loading. You can check out the loading component section to learn more.