> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hana.leafphp.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Hana Router
> Incredibly powerful file-based routing powered by React Router
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.
```bash theme={"theme":"ayu-dark"}
npm install @hanabira/router
```
Open your Vite config file and add the Hana plugin with optional config
```typescript theme={"theme":"ayu-dark"}
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`.
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
```tsx theme={"theme":"ayu-dark"}
const App = ({ children }) => {
return <>{children};
};
export default App;
```
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
```html theme={"theme":"ayu-dark"}
Vite + React + TS
```
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:
```tsx home.tsx theme={"theme":"ayu-dark"}
export default function Home() {
return
Hello World
}
```
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](http://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](/routing/dynamic)
## Navigating between pages
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:
```tsx theme={"theme":"ayu-dark"}
import { Link,useNavigate } from '@hanabira/router';
export default function Home() {
const navigate = useNavigate();
return (
About
);
}
```
You can find the full docs on [the navigation page](/routing/navigating)
## **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.
```tsx src/pages/_app.tsx theme={"theme":"ayu-dark"}
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 = ({ 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**](/routing/errors) 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**](/routing/layouts) section to learn more.