Type Route

https://github.com/zilch/type-route
Admin
Type Route is a flexible, type-safe routing library for React built on the same core library that...
Tokens:30,950
Snippets:264
Trust Score:5.6
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### User Route Example

Source: https://github.com/zilch/type-route/blob/main/docs/api-reference/parameter-definition/param.md

Example of defining a route with a path parameter for user ID and query parameters for pagination and search.

```APIDOC
## POST /user/:userId

### Description
Defines a route for a specific user, identified by a userId in the path.

### Method
POST

### Endpoint
/user/:userId

### Parameters
#### Path Parameters
- **userId** (string) - Required - The unique identifier for the user.

### Request Example
```json
{
  "userId": "123e4567-e89b-12d3-a456-426614174000"
}
```

### Response
#### Success Response (200)
- **message** (string) - A success message.

#### Response Example
```json
{
  "message": "User data retrieved successfully"
}
```
```

```APIDOC
## GET /user

### Description
Retrieves a list of users, with optional search and pagination parameters.

### Method
GET

### Endpoint
/user

### Parameters
#### Query Parameters
- **page** (number) - Optional - The page number for pagination. Defaults to 1.
- **search** (string) - Optional - A search term to filter users.

### Request Example
```json
{
  "page": 2,
  "search": "john"
}
```

### Response
#### Success Response (200)
- **users** (array) - A list of user objects.
- **total** (number) - The total number of users available.

#### Response Example
```json
{
  "users": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "John Doe"
    }
  ],
  "total": 100
}
```
```

--------------------------------

### Install Type Route and React

Source: https://github.com/zilch/type-route/blob/main/README.md

Install Type Route and its peer dependency React using npm. Ensure React version 16.8 or later is installed.

```bash
npm install type-route react
```

--------------------------------

### Define and Use a Route with Array Query Parameter

Source: https://github.com/zilch/type-route/blob/main/docs/guides/custom-query-string.md

Defines a route named 'example' that accepts an array of strings as a query parameter 'arrayValue'. The href is then logged to the console.

```typescript
const { routes } = createRouter(config, {
  example: defineRoute(
    {
      arrayValue: param.query.array.string,
    },
    () => `/example`
  ),
});

console.log(routes.example({ arrayValue: ["foo", "bar"] }).href); // logs out "/example?arrayValue[]=foo,bar
```

--------------------------------

### Create a Type Route Router

Source: https://github.com/zilch/type-route/blob/main/README.md

Define your application routes using `createRouter` and `defineRoute`. This example sets up home, user list with optional pagination, and user detail routes.

```typescript
import { createRouter, defineRoute, param } from "type-route";

export const { RouteProvider, useRoute, routes } = createRouter({
  home: defineRoute("/"),
  userList: defineRoute(
    {
      page: param.query.optional.number,
    },
    () => "/user"
  ),
  user: defineRoute(
    {
      userId: param.path.string,
    },
    (p) => `/user/${p.userId}`
  ),
});
```

--------------------------------

### Efficient Page Layout with Type Route

Source: https://github.com/zilch/type-route/blob/main/docs/guides/page-layout.md

This example demonstrates an efficient layout pattern where Header and Footer components remain mounted across route changes, preventing unnecessary unmounts and remounts. This is the recommended approach for performance.

```tsx
import React, { useState, useEffect } from "react";
import { createRouter, defineRoute } from "type-route";

const { routes, useRoute } = createRouter({
  home: defineRoute("/"),
  foo: defineRoute("/foo"),
  bar: defineRoute("/bar"),
});

function App() {
  const route = useRoute();

  return (
    <>
      <Header />
      {route.name === "home" && <HomePage />}
      {route.name === "foo" && <FooPage />}
      {route.name === "bar" && <BarPage />}
      {route.name === false && <NotFoundPage />}
      <Footer />
    </>
  );
}

function Header() {
  return (
    <nav>
      <a {...routes.home().link}>Home</a>
      <a {...routes.foo().link}>Foo</a>
      <a {...routes.bar().link}>Bar</a>
    </nav>
  );
}

function Footer() {
  return (
    <footer>
      <div>Footer</div>
    </footer>
  );
}

function HomePage() {
  return <div>Home Page</div>;
}

function FooPage() {
  return <div>Foo Page</div>;
}

function BarPage() {
  return <div>Bar Page</div>;
}

function NotFoundPage() {
  return <div>Bar Page</div>;
}

```

--------------------------------

### Extending Route Definitions Example

Source: https://github.com/zilch/type-route/blob/main/docs/api-reference/route-definition/extend.md

Demonstrates how to use `defineRoute` and `extend` to create a router with nested and extended routes. The `userPost` route shows extending with new parameters and a path function.

```typescript
const user = defineRoute(
  {
    userId: param.path.string,
  },
  (p) => `/user/${p.userId}`
);

const { routes, listen } = createRouter({
  home: defineRoute("/"),
  userSummary: user.extend("/"),
  userSettings: user.extend("/settings"),
  userPostList: user.extend("/post"),
  userPost: user.extend(
    {
      postId: param.path.string,
    },
    (p) => `/post/${p.postId}`
  ),
});
```

--------------------------------

### Implement Non-Uniform Redirects with Parameter Transformation

Source: https://github.com/zilch/type-route/blob/main/docs/guides/redirects.md

Handle redirects where parameter transformation is needed. This example shows how to convert age to year of birth and uses `replace()` for immediate redirection.

```tsx
import { createRouter, defineRoute, param } from "type-route";
import React, { useEffect } from "react";
import ReactDOM from "react-dom";

const { routes, useRoute, RouteProvider } = createRouter({
  new: defineRoute(
    {
      yearOfBirth: param.query.number,
    },
    (p) => "/new"
  ),
  old: defineRoute(
    {
      ageInYears: param.query.number,
    },
    (p) => "/old"
  ),
});

function App() {
  const route = useRoute();

  useEffect(() => {
    if (route.name === "old") {
      routes
        .new({
          yearOfBirth: new Date().getFullYear() - route.params.ageInYears,
        })
        .replace();
    }
  }, [route]);

  if (route.name === "old") {
    return <div>Redirecting...</div>;
  }

  if (route.name === "new") {
    return <div>New Page {route.params.yearOfBirth}</div>;
  }

  return <div>Not Found</div>;
}

ReactDOM.render(
  <RouteProvider>
    <App />
  </RouteProvider>,
  document.querySelector("#root")
);
```

--------------------------------

### Inefficient Page Layout with Type Route

Source: https://github.com/zilch/type-route/blob/main/docs/guides/page-layout.md

This example demonstrates an inefficient layout pattern where Header and Footer components are remounted on every page change. Use this pattern only if component remounting is desired.

```tsx
import React, { useState, useEffect } from "react";
import { createRouter, defineRoute } from "type-route";

const { routes, useRoute } = createRouter({
  home: defineRoute("/"),
  foo: defineRoute("/foo"),
  bar: defineRoute("/bar"),
});

function App() {
  const route = useRoute();

  return (
    <>
      {route.name === "home" && <HomePage />}
      {route.name === "foo" && <FooPage />}
      {route.name === "bar" && <BarPage />}
      {route.name === false && <NotFoundPage />}
    </>
  );
}

function Header() {
  return (
    <nav>
      <a {...routes.home().link}>Home</a>
      <a {...routes.foo().link}>Foo</a>
      <a {...routes.bar().link}>Bar</a>
    </nav>
  );
}

function Footer() {
  return (
    <footer>
      <div>Footer</div>
    </footer>
  );
}

function HomePage() {
  return (
    <>
      <Header />
      <div>Home Page</div>
      <Footer />
    </>
  );
}

function FooPage() {
  return (
    <>
      <Header />
      <div>Foo Page</div>
      <Footer />
    </>
  );
}

function BarPage() {
  return (
    <>
      <Header />
      <div>Bar Page</div>
      <Footer />
    </>
  );
}

function NotFoundPage() {
  return (
    <>
      <Header />
      <div>Bar Page</div>
      <Footer />
    </>
  );
}

```

--------------------------------

### MemoryHistorySessionOpts Type

Source: https://github.com/zilch/type-route/blob/main/docs/api-reference/types/session-opts.md

Options for configuring memory history. Use `initialEntries` to pre-populate history and `initialIndex` to set the starting point. Useful for SSR.

```typescript
type MemoryHistorySessionOpts = {
  type: "memory";

  /**
   * An array of urls representing the what items should
   * start in history when the router is created. This can be useful
   * in a variety of scenarios including server-side rendering
   * (https://type-route.zilch.dev/guides/server-side-rendering).
   */
  initialEntries?: string[];

  /**
   * The index of the current url entry when the router is created.
   */
  initialIndex?: number;
};
```

--------------------------------

### Implement Complex Route Parameters with ValueSerializer

Source: https://github.com/zilch/type-route/blob/main/docs/guides/complex-route-parameters.md

A full example demonstrating the integration of a custom Date serializer into a type-route router configuration.

```tsx
import { createRouter, defineRoute } from "type-route";
import React, { useState, useEffect } from "react";
import ReactDOM from "react-dom";

const date: ValueSerializer<Date> = {
  parse(raw) {
    const value = Date.parse(raw);
    if (isNaN(value)) {
      return noMatch;
    }
    return new Date(value);
  },
  stringify(value) {
    return value.toISOString();
  },
};

const { useRoute, routes } = createRouter({
  example: defineRoute(
    {
      minDate: param.query.ofType(date),
      maxDate: param.query.ofType(date),
    },
    () => `/users`
  ),
});

function App() {
  const route = useRoute();
  const [minDate] = useState(new Date("3/3/3"));
  const [maxDate] = useState(new Date("12/12/12"));

  return (
    <>
      <nav>
        <a {...routes.example({ minDate, maxDate }).link}>Example</a>
      </nav>
      {route.name === "example" && <ExamplePage route={route} />}
      {route.name === false && <NotFoundPage />}
    </>
  );
}

function ExamplePage(props: { route: Route<typeof routes.example> }) {
  const { route } = props;

  return (
    <div>
      {route.params.minDate.toDateString()} -{" "}
      {route.params.maxDate.toDateString()}
    </div>
  );
}

function NotFoundPage() {
  return <div>Not Found</div>;
}

ReactDOM.render(<App />, document.querySelector("#root"));
```

--------------------------------

### Usage of Route.replace

Source: https://github.com/zilch/type-route/blob/main/docs/api-reference/route/replace.md

Examples of using replace with defined routes to update the browser history.

```tsx
const { routes } = createRouter({
  home: defineRoute("/"),
  post: defineRoute({ postId: param.path.string }, (p) => `/post/${p.postId}`),
});

routes.home().replace();
routes.post({ postId: "abc" }).replace();
```

--------------------------------

### Define and Create Routes with Type Route

Source: https://github.com/zilch/type-route/blob/main/docs/api-reference/types/route.md

Defines routes using `defineRoute` and creates a router with `createRouter`. This setup is essential for managing application navigation and typing route parameters.

```tsx
import { createRouter, defineRoute, Route, param } from "type-route";

const user = defineRoute(
  {
    userId: param.path.string,
  },
  (p) => `/user/${p.userId}`
);

const { routes } = createRouter({
  home: defineRoute("/"),
  user,
  userSettings: user.extend("/settings"),
  userActivity: user.extend("/activity"),
});

const groups = {
  user: createGroup([routes.user, routes.userSettings, routes.userActivity]),
};
```

--------------------------------

### noMatch Usage Example

Source: https://github.com/zilch/type-route/blob/main/docs/api-reference/miscellaneous/no-match.md

This example demonstrates how to use the `noMatch` constant within a custom `ValueSerializer` for a Date type. If the input string cannot be parsed into a valid Date, `noMatch` is returned, and Type Route will not consider this route a match.

```APIDOC
## Custom Date ValueSerializer with noMatch

### Description
This example shows how to create a custom `ValueSerializer` for `Date` objects. The `parse` function returns `noMatch` if the input string is not a valid date format, preventing the route from matching.

### Method
N/A (This is a constant and a custom serializer implementation)

### Endpoint
N/A

### Parameters
N/A

### Request Body
N/A

### Response
N/A

### Code Example
```ts
import {
  noMatch,
  ValueSerializer,
  createRouter,
  defineRoute,
  param,
} from "type-route";

const date: ValueSerializer<Date> = {
  parse(raw) {
    const value = Date.parse(raw);

    if (isNaN(value)) {
      return noMatch;
    }

    return new Date(value);
  },
  stringify(value) {
    return value.toISOString();
  },
};

const opts: RouterOpts = {
  session: {
    type: "memory",
    initialEntries: ["/date-test/invalid-date"],
  },
};

const { routes, session } = createRouter(opts, {
  dateTest: defineRoute(
    {
      date: param.path.ofType(date),
    },
    (p) => `/date-test/${p.date}`
  ),
});

console.log(session.getInitialRoute().name); // Expected output: false (due to noMatch)
```

### Explanation
- The `date` object implements the `ValueSerializer` interface.
- The `parse` method attempts to parse the input `raw` string into a `Date` object.
- If `Date.parse(raw)` results in `NaN` (Not a Number), it means the string is not a valid date, and `noMatch` is returned.
- Returning `noMatch` signals to Type Route that this parameter cannot be satisfied with the given input, and the route will not be considered a match.
- The `stringify` method converts a `Date` object back into an ISO string format.
- The example route `dateTest` uses this custom `date` serializer for its `date` path parameter.
- When the router is initialized with an invalid date string (`/date-test/invalid-date`), the `dateTest` route does not match because `noMatch` was returned, and `session.getInitialRoute().name` logs `false`.
```

--------------------------------

### Route Access Control Example

Source: https://context7.com/zilch/type-route/llms.txt

Implement access control logic by checking route group membership. Redirect unauthenticated users to the login page if they attempt to access protected routes.

```typescript
// Access control example
function requireAuth(route: Route<typeof routes>) {
  if (groups.authenticated.has(route)) {
    const isLoggedIn = checkUserSession();
    if (!isLoggedIn) {
      routes.login().replace();
      return false;
    }
  }
  return true;
}
```

--------------------------------

### Implement 404 Handling with TypeRoute

Source: https://github.com/zilch/type-route/blob/main/docs/guides/no-match-404.md

In a React application, use `useRoute` to get the current route. Check if `route.name` is `false` to render a 'Not Found' component.

```tsx
import React, { useState, useEffect } from "react";
import ReactDOM from "react-dom";
import { createRouter, defineRoute } from "type-route";

const { routes, useRoute, RouteProvider } = createRouter({
  home: defineRoute("/"),
  foo: defineRoute("/foo"),
  bar: defineRoute("/bar"),
});

function App() {
  const route = useRoute();

  return (
    <>
      <nav>
        <a {...routes.home().link}>Home</a>
        <a {...routes.foo().link}>Foo</a>
        <a {...routes.bar().link}>Bar</a>
        <a href="/path-that-does-not-match-a-defined-route">Not Found</a>
      </nav>
      {route.name === "home" && <div>Home</div>}
      {route.name === "foo" && <div>Foo</div>}
      {route.name === "bar" && <div>Bar</div>}
      {route.name === false && <div>Not Found</div>}
    </>
  );
}

ReactDOM.render(
  <RouteProvider>
    <App />
  </RouteProvider>,
  document.querySelector("#root")
);
```

--------------------------------

### Accessing Route href - TypeRoute

Source: https://github.com/zilch/type-route/blob/main/docs/api-reference/route/href.md

Demonstrates how to access the `href` property for various route definitions, including base routes, routes with optional and required query parameters, and routes with path parameters. This example requires importing `createRouter`, `defineRoute`, and `param` from 'type-route'.

```typescript
import { createRouter, defineRoute, param } from "type-route";

const { routes } = createRouter({
  base: defineRoute("/base"),

  optionalQueryParameter: defineRoute(
    {
      notRequired: param.query.optional.string,
    },
    () => "/optional-query-parameter"
  ),

  requiredQueryParameter: defineRoute(
    {
      required: param.query.string,
    },
    () => "/required-query-parameter"
  ),

  pathParameter: defineRoute(
    {
      required: param.path.string,
    },
    (p) => `/path-parameter/${p.required}`
  ),
});

console.log("==========================");

console.log(routes.base().href);

console.log(routes.optionalQueryParameter().href);

console.log(
  routes.optionalQueryParameter({
    notRequired: "example",
  }).href
);

console.log(
  routes.requiredQueryParameter({
    required: "example",
  }).href
);

console.log(
  routes.pathParameter({
    required: "example",
  }).href
);
```

--------------------------------

### Define a Wildcard Route with Trailing Parameter

Source: https://github.com/zilch/type-route/blob/main/docs/guides/wildcard-routes.md

Use `param.path.trailing.optional.string` to define a wildcard route that matches any path starting with a specific prefix. This is useful for dynamic URL structures.

```tsx
import { createRouter, defineRoute, param } from "type-route";

const { routes } = createRouter({
  example: defineRoute(
    {
      slug: param.path.trailing.optional.string,
    },
    (p) => `/static/${p.slug}`
  ),
});
```

--------------------------------

### Initialize Router with createRouter

Source: https://context7.com/zilch/type-route/llms.txt

Configures the router with route definitions and optional settings like hash-based routing or base paths.

```typescript
import { createRouter, defineRoute, param } from "type-route";

// Create router with route definitions
export const { RouteProvider, useRoute, routes, session } = createRouter({
  home: defineRoute("/"),
  userList: defineRoute(
    {
      page: param.query.optional.number.default(1),
      search: param.query.optional.string,
    },
    () => "/users"
  ),
  user: defineRoute(
    {
      userId: param.path.string,
    },
    (p) => `/users/${p.userId}`
  ),
  post: defineRoute(
    {
      postId: param.path.string,
      commentId: param.query.optional.string,
    },
    (p) => `/posts/${p.postId}`
  ),
});
```

```typescript
import { createRouter, defineRoute } from "type-route";

const { routes, session } = createRouter(
  {
    session: { type: "hash" }, // Use hash-based routing
    baseUrl: "/app",           // Base path for all routes
    arrayFormat: {
      separator: ",",
      queryString: "multiKeyWithBracket",
    },
  },
  {
    home: defineRoute("/"),
    dashboard: defineRoute("/dashboard"),
  }
);
```

--------------------------------

### Using useRoute Hook

Source: https://github.com/zilch/type-route/blob/main/docs/api-reference/router/use-route.md

Demonstrates how to set up RouteProvider and use the useRoute hook to display the current route name. Ensure your application is wrapped in RouteProvider.

```tsx
const { RouteProvider, useRoute } = createRouter({ ... });

ReactDOM.render(<RouteProvider><App/></RouteProvider>, document.querySelector("#main"));

function App() {
  const route = useRoute();

  return <div>
    {route.name}
  </div>;
}
```

--------------------------------

### createRouter

Source: https://github.com/zilch/type-route/blob/main/docs/api-reference/router/create-router.md

Initializes a new router instance with specified route definitions and optional configuration.

```APIDOC
## createRouter

### Description
Initializes a router. By default, the underlying session history instance is configured based on the environment (browser or non-browser).

### Parameters
- **routeDefinitions** (RouteDefinitionBuilderCollection) - Required - The collection of route definitions.
- **routerOpts** (RouterOpts) - Optional - Configuration options for the router.

### Request Example
```tsx
const { routes } = createRouter({
  home: defineRoute("/"),
  postList: defineRoute(
    {
      page: param.query.optional.number,
    },
    (p) => `/post`
  ),
  post: defineRoute(
    {
      postId: param.path.string,
    },
    (p) => `/post/${p.postId}`
  ),
});
```

### Response
- **Router** (Object) - Returns a Router object containing the configured routes and navigation utilities.
```

--------------------------------

### Check Route Match in TypeRoute

Source: https://github.com/zilch/type-route/blob/main/docs/guides/no-match-404.md

Use `session.getInitialRoute()` to get the current route. If the URL doesn't match any defined routes, it returns `false`.

```typescript
import { createRouter, defineRoute } from "type-route";

const { session } = createRouter({
  home: defineRoute("/"),
  foo: defineRoute("/foo"),
  bar: defineRoute("/bar"),
});

const route = session.getInitialRoute();
console.log(route.name);
// This will log either "home", "foo", "bar", or (if the url
// doesn't match one of these routes) the boolean false.
```

--------------------------------

### Initialize Router with createRouter

Source: https://github.com/zilch/type-route/blob/main/docs/api-reference/router/create-router.md

Defines the function signature for creating a router instance.

```tsx
createRouter(routeDefinitions: RouteDefinitionBuilderCollection): Router
createRouter(routerOpts: RouterOpts, routeDefinitions: RouteDefinitionBuilderCollection): Router
```

--------------------------------

### Listening for Route Changes

Source: https://github.com/zilch/type-route/blob/main/docs/api-reference/router/session.md

Demonstrates how to use the `listen` function to subscribe to route changes and how to remove the listener.

```APIDOC
## Listening for Route Changes

### Description
The `listen` function creates a new route change listener. It is invoked whenever the application's route changes, providing the next matching route. If the URL doesn't match any route, an object with `name: false` and `params: {}` is provided.

### Example

```typescript
const { session } = createRouter({
  home: defineRoute("/"),
  post: defineRoute({ postId: param.path.string }, (p) => `/post/${p.postId}`),
});

// Creates a new listener
const removeListener = session.listen((nextRoute) => {
  console.log(nextRoute);
  // logs:
  // { name: false, params: {} }
  // or
  // { name: "home", params: {} }
  // or
  // { name: "post", params: { postId: "abc" }}
  // (where "abc" is whatever was matched from the url)
});

// Removes the listener
removeListener();
```
```

--------------------------------

### Define and use routes in React

Source: https://github.com/zilch/type-route/blob/main/docs/introduction/simple-react-example.md

Initializes the router with defined paths and parameters, then uses the RouteProvider to manage navigation state within the React component tree.

```tsx
import React from "react";
import ReactDOM from "react-dom";
import { createRouter, defineRoute, Route, param } from "type-route";

const { RouteProvider, useRoute, routes } = createRouter({
  home: defineRoute("/"),
  userList: defineRoute(
    {
      page: param.query.optional.number,
    },
    () => "/user"
  ),
  user: defineRoute(
    {
      userId: param.path.string,
    },
    (p) => `/user/${p.userId}`
  ),
});

function App() {
  const route = useRoute();

  return (
    <>
      <Navigation />
      {route.name === "home" && <HomePage />}
      {route.name === "userList" && <UserListPage route={route} />}
      {route.name === "user" && <UserPage route={route} />}
      {route.name === false && <>Not Found</>}
    </>
  );
}

function Navigation() {
  return (
    <nav>
      <a {...routes.home().link}>Home</a>
      <a {...routes.userList().link}>User List</a>
      <a
        {...routes.userList({
          page: 2,
        }).link}
      >
        User List Page 2
      </a>
      <a
        {...routes.user({
          userId: "abc",
        }).link}
      >
        User "abc"
      </a>
    </nav>
  );
}

function HomePage() {
  return <div>Home</div>;
}

function UserListPage(props: { route: Route<typeof routes.userList> }) {
  const { route } = props;

  return (
    <div>
      User List
      <br />
      Page: {route.params.page || "-"}
    </div>
  );
}

function UserPage(props: { route: Route<typeof routes.user> }) {
  const { route } = props;

  return <div>User {route.params.userId}</div>;
}

ReactDOM.render(
  <RouteProvider>
    <App />
  </RouteProvider>,
  document.querySelector("#root")
);
```

--------------------------------

### Initialize and render RouteProvider

Source: https://github.com/zilch/type-route/blob/main/docs/api-reference/router/route-provider.md

Wraps the application component with RouteProvider to enable routing functionality.

```tsx
const { RouteProvider } = createRouter({ ... });

ReactDOM.render(<RouteProvider><App/></RouteProvider>, document.querySelector("#main"));
```

--------------------------------

### defineRoute - With Parameters and Path Aliases

Source: https://github.com/zilch/type-route/blob/main/docs/api-reference/route-definition/define-route.md

Creates a route definition with parameters and multiple path aliases.

```APIDOC
## POST /api/routes/complex

### Description
Creates a route definition with parameters and multiple path aliases.

### Method
POST

### Endpoint
/api/routes/complex

### Parameters
#### Query Parameters
- **params** (object) - Required - A map of variable names to parameter definitions.
- **paths** (array) - Required - An array of strings representing the primary path and its aliases, which can include path parameters.

### Request Example
{
  "params": {
    "userId": "param.path.string"
  },
  "paths": [
    "/user/${userId}",
    "/users/${userId}"
  ]
}

### Response
#### Success Response (200)
- **routeDefinition** (object) - The created route definition.

#### Response Example
{
  "routeDefinition": {
    "primaryPath": "/user/:userId",
    "aliases": ["/users/:userId"]
  }
}
```

--------------------------------

### Create and Use Route Groups

Source: https://github.com/zilch/type-route/blob/main/docs/api-reference/route-group/create-group.md

Demonstrates how to define routes, create nested groups using createGroup, and check if a route belongs to a group using the has function. Ensure all necessary imports are present.

```typescript
import { defineRoute, createRouter, createGroup, param } from "type-route";

const user = defineRoute(
  {
    userId: param.path.string
  },
  p => `/user/${p.userId}`
);

const { routes } = createRouter({
  home: defineRoute("/"),
  userSummary: user.extend("/"),
  userSettings: user.extend("/settings"),
  userPostList: user.extend("/post"),
  userPost: user.extend(
    {
      postId: param.path.string
    },
    p => `/post/${p.postId}`
  )
});

const postGroup = createGroup([routes.userPostList, routes.userPost]);

const groups = {
  post: postGroup,
  user: createGroup([
    routes.userSummary,
    routes.userSettings,
    postGroup
  ])
};

const route = session.getInitialRoute();

if (groups.user.has(route)) {
  console.log(route.name;) // "userSummary" | "userSettings" | "userPostList" | "userPost"
}
```

--------------------------------

### defineRoute - With Parameters

Source: https://github.com/zilch/type-route/blob/main/docs/api-reference/route-definition/define-route.md

Creates a route definition with path and query parameters.

```APIDOC
## POST /api/routes/with-params

### Description
Creates a route definition with path and query parameters.

### Method
POST

### Endpoint
/api/routes/with-params

### Parameters
#### Query Parameters
- **params** (object) - Required - A map of variable names to parameter definitions.
- **path** (function) - Required - A function that returns the route path based on path parameters.

### Request Example
{
  "params": {
    "userId": "param.path.string",
    "page": "param.query.number",
    "search": "param.query.optional.string"
  },
  "path": "(p) => `/user/${p.userId}/posts?page=1&search=hello`"
}

### Response
#### Success Response (200)
- **routeDefinition** (object) - The created route definition.

#### Response Example
{
  "routeDefinition": {
    "path": "/user/:userId/posts",
    "query": ["page", "search"]
  }
}
```

--------------------------------

### Parameter Definitions

Source: https://github.com/zilch/type-route/blob/main/docs/api-reference/parameter-definition/param.md

Lists all available parameter definitions for path, query, and state parameters, including modifiers like optional and default.

```APIDOC
## Parameter Types and Modifiers

### Path Parameters
- `param.path.string`
- `param.path.number`
- `param.path.boolean`
- `param.path.ofType(valueSerializer)`
- `param.path.optional.string`
- `param.path.optional.number`
- `param.path.optional.number.default(value)`
- `param.path.optional.boolean`
- `param.path.optional.boolean.default(value)`
- `param.path.optional.ofType(valueSerializer)`
- `param.path.optional.ofType(valueSerializer).default(value)`
- `param.path.trailing.string`
- `param.path.trailing.number`
- `param.path.trailing.boolean`
- `param.path.trailing.ofType(valueSerializer)`
- `param.path.trailing.optional.string`
- `param.path.trailing.optional.string.default(value)`
- `param.path.trailing.optional.number`
- `param.path.trailing.optional.number.default(value)`
- `param.path.trailing.optional.boolean`
- `param.path.trailing.optional.boolean.default(value)`
- `param.path.trailing.optional.ofType(valueSerializer)`
- `param.path.trailing.optional.ofType(valueSerializer).default(value)`

### Query Parameters
- `param.query.string`
- `param.query.number`
- `param.query.boolean`
- `param.query.ofType(valueSerializer)`
- `param.query.optional.string`
- `param.query.optional.string.default(value)`
- `param.query.optional.number`
- `param.query.optional.number.default(value)`
- `param.query.optional.boolean`
- `param.query.optional.boolean.default(value)`
- `param.query.optional.ofType(valueSerializer)`
- `param.query.optional.ofType(valueSerializer).default(value)`

### State Parameters
- `param.state.string`
- `param.state.number`
- `param.state.boolean`
- `param.state.ofType(valueSerializer)`
- `param.state.optional.string`
- `param.state.optional.string.default(value)`
- `param.state.optional.number`
- `param.state.optional.number.default(value)`
- `param.state.optional.boolean`
- `param.state.optional.boolean.default(value)`
- `param.state.optional.ofType(valueSerializer)`
- `param.state.optional.ofType(valueSerializer).default(value)`

### Parameter Position Details

#### Path
Path parameters are part of the URL path. Example: `/user/:userId`.

```tsx
// Example for path parameter
defineRoute(
  {
    userId: param.path.string
  },
  p => `/user/${p.userId}`
);
```

#### Query
Query parameters are part of the URL query string. Example: `?page=1&search=term`.

```tsx
// Example for query parameter
defineRoute(
  {
    page: param.query.number
  },
  () => `/users?page=1`
);
```

#### State
State parameters are stored in the browser's history and are not visible in the URL.

### Parameter Modifiers

#### Optional
Makes a parameter optional. For path parameters, it must be at the end of the path.

```tsx
// Example for optional query parameter
defineRoute(
  {
    page: param.query.optional.number
  },
  () => `/users`
);
```

#### Default
Assigns a default value to an optional parameter if it's not provided.

```tsx
// Example for optional number with default
defineRoute(
  {
    count: param.query.optional.number.default(10)
  },
  () => `/items`
);
```
```

--------------------------------

### Configure Server-Side Rendering with Fastify

Source: https://github.com/zilch/type-route/blob/main/docs/guides/server-side-rendering.md

Uses router.session.reset to initialize the memory history with the requested URL before rendering the React application to a string.

```tsx
import fastify from "fastify";
import ReactDOM from "react-dom/server";
import React from "react";
import { App, session, RouteProvider } from "../client";

const app = fastify();

app.get("/*", (request, response) => {
  session.reset({
    type: "memory",
    initialEntries: [request.req.url],
  });

  const appHtml = ReactDOM.renderToString(
    <RouteProvider>
      <App />
    </RouteProvider>
  );

  response.type("text/html");
  response.send(
    `<body><div id="app">${appHtml}</div><script src="http://localhost/bundle.js"></script></body>`
  );
});

app.listen(3000);
```

--------------------------------

### Display Current Route in React Component

Source: https://github.com/zilch/type-route/blob/main/README.md

Use the `useRoute` hook to get the current route information and conditionally render components based on the route name. Type inference ensures type safety for route parameters.

```tsx
import React from "react";
import { useRoute, routes } from "./router";
import { HomePage } from "./HomePage";
import { UserListPage } from "./UserListPage";
import { UserPage } from "./UserPage";
import type { Route } from "type-route";

export function Page() {
  const route = useRoute();

  return (
    <>
      {route.name === "home" && <HomePage />}
      {route.name === "userList" && <UserListPage route={route} />}
      {route.name === "user" && <UserPage route={route} />}
      {route.name === false && "Not Found"}
    </>
  );
}

function HomePage() {
  return <div>Home Page</div>;
}

function UserListPage({ route }: { route: Route<typeof routes.userList> }) {
  return <div>UserList Page: {route.params.page}</div>;
}

function UserPage({ route }: { route: Route<typeof routes.user> }) {
  return <div>User: {route.params.userId}</div>;
}
```

--------------------------------

### Accessing Route Action

Source: https://github.com/zilch/type-route/blob/main/docs/api-reference/route/action.md

Demonstrates how to check the 'action' property of a route. The initial route's action is always null.

```typescript
const route = routes.home();
console.log(route.action); // null
route.push();
console.log(route.action); // push
```

--------------------------------

### Define Routes with Path and Query Parameters

Source: https://github.com/zilch/type-route/blob/main/docs/api-reference/parameter-definition/param.md

Demonstrates defining routes with path parameters like `userId` and query parameters like `page` and `search`. The `page` parameter has a default value of 1.

```typescript
import { createRouter, defineRoute, param } from "type-route";

export const { routes } = createRouter({
  user: defineRoute(
    {
      userId: param.path.string
    },
    p => `/user/${param.path.string}`
  ),
  userList: defineRoute({
    {
      page: param.query.optional.number.default(1),
      search: param.query.optional.string
    },
    () => `/user`
  })
});
```

--------------------------------

### Create Router and Define Routes without React

Source: https://github.com/zilch/type-route/blob/main/docs/guides/type-route-without-react.md

Use 'type-route/core' to create a router and define routes with path and query parameters. Integrate with session for route updates and initial route retrieval.

```typescript
import { createRouter, defineRoute, param, Route } from "type-route/core";

const { routes, session } = createRouter({
  home: defineRoute("/"),
  userList: defineRoute(
    {
      page: param.query.optional.number,
    },
    () => "/users"
  ),
  user: defineRoute(
    {
      userId: param.path.string,
    },
    (p) => `/users/${p.userId}`
  ),
});

const nav = document.createElement("nav");
nav.appendChild(link("Home", routes.home()));
nav.appendChild(link("User List", routes.userList({ page: 1 })));
nav.appendChild(link("User", routes.user({ userId: "abc" })));
document.body.prepend(nav);

renderPage(session.getInitialRoute());

session.listen((nextRoute) => {
  renderPage(nextRoute);
});

function renderPage(route: Route<typeof routes>) {
  const root = document.querySelector("#root");

  if (route.name === "home") {
    root.innerHTML = "Home";
  } else if (route.name === "userList") {
    root.innerHTML = `UserList Page: ${route.params.page || "-"}`;
  } else if (route.name === "user") {
    root.innerHTML = `User ${route.params.userId}`;
  } else {
    root.innerHTML = "Not Found";
  }
}

function link(label: string, to: Route<typeof routes>) {
  const element = document.createElement("a");
  element.innerHTML = label;
  element.href = to.link.href;
  element.onclick = to.link.onClick;
  return element;
}
```

--------------------------------

### Connect Router to React Application

Source: https://github.com/zilch/type-route/blob/main/README.md

Wrap your entire application with the `RouteProvider` component returned by `createRouter` to enable routing.

```tsx
import React, { useState, useEffect } from "react";
import ReactDOM from "react-dom";
import { RouteProvider } from "./router";
import { Page } from "./Page";
import { Navigation } from "./Navigation";

function App() {
  return (
    <>
      <Navigation />
      <Page />
    </>
  );
}

ReactDOM.render(
  <RouteProvider>
    <App />
  </RouteProvider>,
  document.querySelector("#root")
);
```

--------------------------------

### Define simple and parameterized routes

Source: https://github.com/zilch/type-route/blob/main/docs/api-reference/route-definition/define-route.md

Basic usage for static paths and advanced usage for paths requiring path or query parameters.

```tsx
defineRoute("/");
```

```tsx
defineRoute(
  {
    userId: param.path.string,
    page: param.query.number,
    search: param.query.optional.string,
  },
  (p) => `/user/${p.userId}/posts`
);
```

--------------------------------

### defineRoute - Basic Usage

Source: https://github.com/zilch/type-route/blob/main/docs/api-reference/route-definition/define-route.md

Creates a route definition for a simple path.

```APIDOC
## POST /api/routes

### Description
Creates a route definition for a simple path.

### Method
POST

### Endpoint
/api/routes

### Parameters
#### Query Parameters
- **path** (string) - Required - The path for the route.

### Request Example
{
  "path": "/"
}

### Response
#### Success Response (200)
- **routeDefinition** (object) - The created route definition.

#### Response Example
{
  "routeDefinition": {
    "path": "/"
  }
}
```

--------------------------------

### useRoute Hook Usage

Source: https://github.com/zilch/type-route/blob/main/docs/api-reference/router/use-route.md

Demonstrates how to use the `useRoute` hook within a React component after wrapping the application with `RouteProvider`.

```APIDOC
## useRoute Hook

### Description
The `useRoute` hook returns the current route object, providing access to route-specific information like the route name.

### Prerequisites
To use the `useRoute` hook, your application must be wrapped in a `RouteProvider` component, typically provided by a router setup.

### Usage Example

```tsx
import React from 'react';
import ReactDOM from 'react-dom';
import { createRouter, RouteProvider, useRoute } from '@your-router-library'; // Assuming a router library

// Assume createRouter is configured with your routes
const { RouterComponent } = createRouter({ ... });

function App() {
  const route = useRoute();

  return (
    <div>
      <h1>Current Route</h1>
      <p>Route Name: {route.name}</p>
      {/* Other route properties can be accessed here */}
    </div>
  );
}

ReactDOM.render(
  <RouteProvider>
    <App />
  </RouteProvider>,
  document.querySelector("#main")
);
```

### Return Value
- **route** (object) - An object containing information about the current route. This object typically includes properties such as `name`, `path`, `params`, etc., depending on the router implementation.
```

--------------------------------

### React Integration with useRoute and RouteProvider

Source: https://context7.com/zilch/type-route/llms.txt

Wrap your application in RouteProvider to enable route subscriptions and use the useRoute hook to access the current route state.

```typescript
import React from "react";
import ReactDOM from "react-dom";
import { createRouter, defineRoute, param, Route } from "type-route";

const { RouteProvider, useRoute, routes } = createRouter({
  home: defineRoute("/"),
  userList: defineRoute(
    { page: param.query.optional.number.default(1) },
    () => "/users"
  ),
  user: defineRoute(
    { userId: param.path.string },
    (p) => `/user/${p.userId}`
  ),
});

// Type-safe route components
function UserPage({ route }: { route: Route<typeof routes.user> }) {
  // route.params.userId is guaranteed to exist and be a string
  return <div>User ID: {route.params.userId}</div>;
}

function UserListPage({ route }: { route: Route<typeof routes.userList> }) {
  // route.params.page is guaranteed to be a number (default: 1)
  return <div>Page: {route.params.page}</div>;
}

function App() {
  const route = useRoute();

  // Route matching with type narrowing
  if (route.name === "home") {
    return <div>Welcome Home</div>;
  }

  if (route.name === "userList") {
    return <UserListPage route={route} />;
  }

  if (route.name === "user") {
    return <UserPage route={route} />;
  }

  // route.name === false means no route matched
  if (route.name === false) {
    return <div>404 - Page Not Found</div>;
  }

  return null;
}

// Mount application with RouteProvider
ReactDOM.render(
  <RouteProvider>
    <App />
  </RouteProvider>,
  document.querySelector("#root")
);
```

--------------------------------

### Configuring Array Query String Format

Source: https://github.com/zilch/type-route/blob/main/docs/guides/custom-query-string.md

Configures the router to use multi-key format with brackets for array values.

```ts
import { createRouter, defineRoute, param, RouterOpts } from "type-route";

const opts: RouterOpts = {
  arrayFormat: {
    separator: ",",
    queryString: "multiKeyWithBracket",
  },
};

const { routes } = createRouter(opts, {
  example: defineRoute(
    {
      arrayValue: param.query.array.string,
    },
    () => `/example`
  ),
});

console.log(routes.example({ arrayValue: ["foo", "bar"] }).href); // logs out "/example?arrayValue[]=foo&arrayValue[]=bar
```

--------------------------------

### Listen for Route Changes

Source: https://github.com/zilch/type-route/blob/main/docs/api-reference/router/session.md

Demonstrates how to register a listener for route changes and how to remove it using the returned function.

```tsx
const { session } = createRouter({
  home: defineRoute("/"),
  post: defineRoute({ postId: param.path.string }, (p) => `/post/${p.postId}`),
});

// Creates a new listener
const removeListener = session.listen((nextRoute) => {
  console.log(nextRoute);
  // logs:
  // { name: false, params: {} }
  // or
  // { name: "home", params: {} }
  // or
  // { name: "post", params: { postId: "abc" }}
  // (where "abc" is whatever was matched from the url)
});

// Removes the listener
removeListener();
```

--------------------------------

### defineRoute - With Path Aliases

Source: https://github.com/zilch/type-route/blob/main/docs/api-reference/route-definition/define-route.md

Creates a route definition with multiple path aliases.

```APIDOC
## POST /api/routes/with-aliases

### Description
Creates a route definition with multiple path aliases.

### Method
POST

### Endpoint
/api/routes/with-aliases

### Parameters
#### Query Parameters
- **paths** (array) - Required - An array of strings representing the primary path and its aliases.

### Request Example
{
  "paths": ["/dashboard", "/"]
}

### Response
#### Success Response (200)
- **routeDefinition** (object) - The created route definition.

#### Response Example
{
  "routeDefinition": {
    "primaryPath": "/dashboard",
    "aliases": ["/"]
  }
}
```

--------------------------------

### Define Simple Redirects with Multiple Paths

Source: https://github.com/zilch/type-route/blob/main/docs/guides/redirects.md

Use an array of strings in defineRoute to map multiple paths to a single route. The first path is primary, and subsequent paths will redirect to it.

```tsx
import { createRouter, defineRoute, param } from "type-route";

createRouter({
  dashboard: defineRoute(["/dashboard", "/"]),
  user: defineRoute(
    {
      userId: param.path.string,
    },
    (p) => [`/user/${p.userId}`, `/users/${p.userId}`]
  ),
});
```

--------------------------------

### Define Multiple Path Parameters with Text

Source: https://github.com/zilch/type-route/blob/main/docs/api-reference/parameter-definition/param.md

Shows how to define multiple path parameters (`foo`, `bar`) when there is intervening text between them within the URL segment. This allows for more complex URL structures.

```typescript
defineRoute(
  {
    foo: param.path.number,
    bar: param.path.number,
  },
  (p) => `/leading-text-${p.foo}-trailing-text/${p.bar}/test`
);
```

--------------------------------

### Using RouteGroup.has for Type Narrowing

Source: https://github.com/zilch/type-route/blob/main/docs/api-reference/route-group/has.md

Demonstrates defining routes, creating a group, and using the has method to safely access route parameters.

```tsx
import { defineRoute, createRouter, createGroup, param } from "type-route";

const user = defineRoute(
  {
    userId: param.path.string,
  },
  (p) => `/user/${p.userId}`
);

const { routes } = createRouter({
  home: defineRoute("/"),
  user,
  userSettings: user.extend("/settings"),
  userActivity: user.extend("/activity"),
});

const groups = {
  user: createGroup([routes.user, routes.userSettings, routes.userActivity]),
};

if (groups.user.has(route)) {
  console.log(route.params.userId);
}
```

```tsx
if (groups.user.has(route)) {
  console.log(route.params.userId);
}
```

--------------------------------

### Create a User Page Component

Source: https://github.com/zilch/type-route/blob/main/docs/guides/code-splitting.md

A React component for displaying user details, which expects route parameters. This component is designed to be dynamically imported.

```typescript
import React from "react";
import { Route } from "type-route";
import { routes } from "./router";

type Props = {
  route: Route<typeof routes.user>;
};

export default function UserPage(props: Props) {
  const { route } = props;

  return <div>User {route.params.userId}</div>;
}
```
Tokens:
Raw