# Routing
Routing in Qwik Router is file-system based like [Next.js](https://nextjs.org/docs/routing/introduction), [SvelteKit](https://kit.svelte.dev/docs/routing), [SolidStart](https://start.solidjs.com/core-concepts/routing) or [Remix](https://remix.run/docs/en/main/guides/routing). Files and directories in the `src/routes` have a role in the routing of your application.
- **Directories:** Define the URL segments to match by the router.
- **`index.tsx/mdx` files:** Define a [page](/docs/pages/).
- **`index.ts` file:** Define an [endpoint](/docs/endpoints/).
- **`layout.tsx` files:** Define nested [layout](/docs/layout/) and/or a [middleware](/docs/middleware/).
[Video](https://cdn.builder.io/o/assets%2FYJIGb4i01jvw0SRdL5Bt%2Fabf8f471ba884b938d0863d85ed4c50f%2Fcompressed?apiKey=YJIGb4i01jvw0SRdL5Bt&token=abf8f471ba884b938d0863d85ed4c50f&alt=media&optimized=true)
## Directory-based routing
Only the directory names are used to match the incoming requests to pages/endpoint/middleware.
For example, if you have a file at `src/routes/some/path/index.tsx`, it will be mapped to the URL path `https://example.com/some/path`.
```bash title="Directory layout"
src/
`-- routes/
|-- contact/
| `-- index.mdx # https://example.com/contact
|-- about/
| `-- index.md # https://example.com/about
|-- docs/
| `-- [id]/
| `-- index.ts # https://example.com/docs/1234
| # https://example.com/docs/anything
|-- [...catchall]/
| `-- index.tsx # https://example.com/anything/else/that/didnt/match
|
`-- layout.tsx # This layout is used for all pages
```
- **`[id]`** is a directory that represents a dynamic route segment, in this example `id` is the string parameter accessible by `useLocation().params.id`.
- **`[...catchall]`** is a directory that represents a dynamic catch-all route, in this example `catchall` is the string parameter accessible by `useLocation().params.catchall`.
- **`index.tsx|mdx` files** are the pages/endpoints/middleware.
- **`layout.tsx` files** are the layouts.
### Dynamic route segments
Special named directories with square brackets, such as `[paramName]` and `[...catchAll]` can be used to match route segments which are dynamic:
```bash title="Directory layout"
src/routes/blog/index.tsx → /blog
src/routes/user/[username]/index.tsx → /user/:username (/user/foo)
src/routes/post/[...all]/index.tsx → /post/* (/post/2020/id/title)
```
```bash title="Directory layout"
src/
`-- routes/
|-- blog/
| `-- index.tsx # https://example.com/blog
|-- post/
| `-- [...all]/
| `-- index.tsx # https://example.com/post/2020/id/title
`-- user/
`-- [username]/
`-- index.tsx # https://example.com/user/foo
```
The folder `[username]` can be any of the thousands of users that you have in your database. It would be impractical to create a route for each user. Instead, you need to define a Route Parameter (a part of the URL) that will be used to extract the `[username]`.
```tsx title="src/routes/user/[username]/index.tsx"
import { component$ } from '@qwik.dev/core';
import { useLocation } from '@qwik.dev/router';
export default component$(() => {
const loc = useLocation();
return
Hello {loc.params.username}!
;
});
```
## `index` files
Inside the `src/routes` directory, all files named `index` are considered pages/endpoint/middleware, Qwik supports the following extensions: `.ts`, `.tsx`, `.md` and `.mdx`.
Pages/endpoint/middleware are the leaf nodes of the routing tree, i.e., **the modules that will handle the request and return an HTTP response**.
### Page `index.tsx`
When an `index.tsx` or `index.ts` file exports a Qwik component as the default export, Qwik Router will render the component and return an HTML response as a webpage.
```tsx title="src/routes/index.tsx"
import { component$ } from '@qwik.dev/core';
export default component$(() => {
return
Hello World
;
});
```
### Endpoint `index.ts`
An `index.ts` file can access the HTTP request directly and return a raw HTTP response without involving any Qwik Component. This is done by exporting any of the following methods: `onRequest`, `onGet`, `onPost`, `onPut` or `onDelete` depending on how you want to handle a specific HTTP request.
```tsx title="src/routes/index.ts"
import type { RequestHandler } from '@qwik.dev/router';
export const onGet: RequestHandler = ({ json }) => {
json(200, { message: 'Hello World' });
};
```
In the last example, there is no default export. This is because you are not rendering a Qwik component, but rather you are handling the request directly and returning a JSON response. This is useful for implementing RESTful APIs or any other type of HTTP endpoint.
### Page + Endpoint
In Qwik Router there is no clear separation between pages and endpoints. An `index.tsx` file handles both and exports a Qwik component or an `onRequest` method. However, it's possible to combine both approaches. For example, you can export an `onRequest` method that will handle the request, and then render a Qwik component.
```tsx title="src/routes/index.tsx"
import { component$ } from '@qwik.dev/core';
import type { RequestHandler } from '@qwik.dev/router';
export const onRequest: RequestHandler = ({ headers, query, json }) => {
headers.set('Cache-Control', 'private');
if (query.get('format') === 'json') {
json(200, { message: 'Hello World' });
}
};
export default component$(() => {
return
Hello World
;
});
```
In this example, a request handle will always set the `Cache-Control` header to `private` and the page will be rendered as an HTML page, but if the request contains a `format=json` query param, the endpoint will return a JSON response instead.
## `layout.tsx` files
Layout modules are very similar to `index` files. Both can handle requests and render Qwik components. However, layouts are designed to work like middleware, allowing to **share UI and request handling (middleware)** to a set of routes.
Usually, different pages need some common request handling and share some UI. For example, picture a dashboard site where all the pages are under the `/admin/*` directory:
- **Shared request handling:** The request cookies need to be validated before even rendering the page, otherwise, render a blank 401 page.
- **Shared UI:** All pages share a common header showing the user's name and profile picture.
Instead of repeating the same code in each route, use layouts to automatically reuse common parts. Layouts also support adding middleware to the route.
Take this `src/routes` directory as an example:
```bash title="Directory layout"
src/
`-- routes/
|-- admin/
| |-- layout.tsx <-- This layout is used for all pages under /admin/*
| `-- index.tsx
|-- layout.tsx <-- This layout is used for all pages
`-- index.tsx
```
### Middleware Layouts
Layouts can implement request handling using any of the following methods: `onRequest`, `onGet`, `onPost`, `onPut` or `onDelete`. This means they can be used to implement middleware. For example, they can be used to validate the request cookies before rendering the page.
For the route `https://example.com/admin`, the `onRequest` methods will be executed in the following order:
1. `src/routes/layout.tsx`'s `onRequest`
2. `src/routes/admin/layout.tsx`'s `onRequest`
3. `src/routes/admin/index.tsx`'s `onRequest`
4. `src/routes/admin/index.tsx`'s component
An `onRequest` handler in `src/routes/index.tsx` doesn't get executed.
### Full Execution order
```bash
1 --> [entry.express.ts or entry.preview.ts]
2 --> [plugin@some-name.ts] #Alphabetical order
3 --> [server$]
4 --> [entry.ssr.ts]
5 --> [root.tsx]
6 --> [layout.tsx onRequest -> onGet/onHttpVerb]
7 --> [globalLoaders]
8 --> [routeLoaders]
9 --> [jsx/components on a route]
```
### Nested Layouts
Layouts also **provide a way to add common UI to the rendered page**. For example, if you want to add a common header to all of the routes, add a Header component to the root layout.
For the given example, the Qwik components will be rendered in the following order:
1. `src/routes/layout.tsx`'s component
2. `src/routes/admin/layout.tsx`'s component
3. `src/routes/admin/index.tsx`'s component
```tsx
```
## SPA Navigation
With Qwik, the distinction between MPA and SPA disappears; every app can be both at the same time.
The choice is no longer an architectural design determined at the beginning of the project,
instead, this decision can be made for every link.
Qwik provides a `` component and `useNavigate()` hook.
These can be used to initiate an SPA refresh or navigation between pages.
The `Link` component is the recommended way to navigate as it uses the HTML `` tag,
which is the most accessible way to move between pages.
However, if you need to navigate programmatically, you can use the `useNavigate()` hook.
```tsx
import { component$ } from '@qwik.dev/core';
import { Link, useNavigate } from '@qwik.dev/router';
export default component$(() => {
const nav = useNavigate();
return (