---
title: "\U0001F9EA Typed Routes"
contributors:
  - mhevery
  - RumNCodeDev
updated_at: '2023-06-23T23:07:42Z'
created_at: '2023-06-23T23:07:42Z'
---

import PackageManagerTabs from '~/components/package-manager-tabs/index.tsx';

# 🧪 Typed Routes
**Stage:** `prototyping`

Provides type safe way of building URLs within the application.

## Installation

1. 

<PackageManagerTabs>
<span q:slot="pnpm">
```shell
pnpm install github:QwikDev/qwik-labs-build#main
```
</span>
<span q:slot="npm">
```shell
npm install github:QwikDev/qwik-labs-build#main
```
</span>
<span q:slot="yarn">
```shell
yarn add github:QwikDev/qwik-labs-build#main
```
</span>
<span q:slot="bun">
```shell
bun install github:QwikDev/qwik-labs-build#main
```
</span>
</PackageManagerTabs>

2. update `vite.config.ts`
   ```typescript
   // ...
   import { qwikTypes } from '@builder.io/qwik-labs/vite';

   export default defineConfig(() => {
     return {
       plugins: [
        // ...
        qwikTypes() // <== Add `qwikTypes()` to the list of plugins
       ],
       // ...
     };
   });
   ```
3. Run build so that it generates `~/routes.gen.d.ts` and `~/routes.config.tsx` files.
3. To create a typesafe link:
   ```typescript
   import { AppLink } from '~/routes.config';

   export default component$(() => {
     // ...
     return (
       // ...
       <AppLink route="/your/[appParam]/link/" param:appParam={"some-value"}>
         Link text
       </AppLink>
     );
   });
   ```


# Declarative Routing
This is a package originally created by Jack Herrington aka *"The Blue Collar Coder"* for type safe routing inside NextJS applications and has been adapted for use inside QwikCity

## Installation
1. 

<PackageManagerTabs>
<span q:slot="pnpm">
```shell
pnpm dlx declarative-routing init
```
</span>
<span q:slot="npm">
```shell
npx declarative-routing init
```
</span>
<span q:slot="yarn">
```shell
yarn dlx declarative-routing init
```
</span>
<span q:slot="bun">
```shell
bunx declarative-routing init
```
</span>
</PackageManagerTabs>

## Setup
The initialization process will create some important files for you.

### .src/declarativeRoutes
- `makeRoute.ts` - Used for defining page routes
- `index.ts` - Where all of your route files will be imported from.
- `hooks.ts` - A file with two custom hooks `useParams` & `useSearchParams` used to access type safe route urls, params, and searchParams

### Each of your route directories
- routeInfo.ts - Where you name the route, and provide a `zod` schema for the `params` and `search` (search params)

## Usage

### Declare Route Details
```typescript title="/src/routes/pokemon/[pokemonId]/routeInfo.ts"
import { z } from "zod";

export const Route = {
  name: "PokemonDetail",
  params: z.object({
    pokemonId: z.coerce.number(),
  }),
};
```

### Inside Component
There are a few different ways you can use Declarative Routes inside your component.

1. Use *RouteName*.Link
```typescript title="myComponent.tsx"
import { PokemonDetail } from "~/declarativeRoutes";

export default component$(() => {
  // ...
  return (
    // ...
    <PokemonDetail.Link pokemonId={1}>Bulbasaur</PokemonDetail.Link>
  );
});
```

2. Use the standard Link and use the *RouteName* as a function to return the path
```typescript title="myComponent.tsx"
import { Link } from "@builder.io/qwik-city";
import { PokemonDetail } from "~/declarativeRoutes";

export default component$(() => {
  // ...
  return (
    // ...
    <Link href={PokemonDetail({ pokemonId: 1 })}>Bulbasaur</Link>
  );
});
```
3. Use *RouteName*.ParamsLink
```typescript title="myComponent.tsx"
import { PokemonDetail } from "~/declarativeRoutes";

export default component$(() => {
  // ...
  return (
    // ...
    <PokemonDetail.ParamsLink params={{ pokemonId: 1 }}>Bulbasaur</PokemonDetail.ParamsLink>
  );
});
```
4. Get the params from a *RouteName*

```typescript title="myComponent.tsx"
import { PokemonDetail } from "~/declarativeRoutes";

export default component$(() => {
  // Typescript will know the correct params and their types
  const { pokemonId } = useParams(PokemonDetail);
  // ...
  return (
    // ...
  );
});
```

## Add or Change Routes
If you add a new route, or move an existing route, simply run 

<PackageManagerTabs>
<span q:slot="pnpm">
```shell
pnpm dlx declarative-routing build
```
</span>
<span q:slot="npm">
```shell
npx declarative-routing build
```
</span>
<span q:slot="yarn">
```shell
yarn dlx declarative-routing build
```
</span>
<span q:slot="bun">
```shell
bunx declarative-routing build
```
</span>
</PackageManagerTabs>

and this will rerun the process and update any changes needed

## Links
- [GitHub](https://github.com/ProNextJS/declarative-routing)
- [QwikCity Setup Instructions](https://github.com/ProNextJS/declarative-routing/blob/main/docs/qwikcity.md)
- [Example Repos](https://github.com/ProNextJS/declarative-routing/tree/main/examples/qwikcity)
