Chicane

https://github.com/swan-io/chicane
Admin
Chicane is a simple and safe router for React and TypeScript, offering typed routes,...
Tokens:12,124
Snippets:50
Trust Score:9
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Chicane

Source: https://github.com/swan-io/chicane/blob/main/docs/docs/getting-started.md

Provides commands to install the Chicane library using Yarn or npm. Ensure you have Node.js and a package manager (Yarn or npm) installed.

```bash
$ yarn add @swan-io/chicane
# --- or ---
$ npm install --save @swan-io/chicane
```

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

### Run Chicane Example App

Source: https://github.com/swan-io/chicane/blob/main/README.md

Provides instructions to clone the Chicane repository, navigate to the example directory, install dependencies, and run the example application using either Yarn or npm. This allows users to see the router in action.

```bash
$ git clone git@github.com:swan-io/chicane.git
$ cd chicane/example

$ yarn install && yarn dev
# --- or ---
$ npm install && npm run dev
```

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

### Install Dependencies with pnpm

Source: https://github.com/swan-io/chicane/blob/main/docs/README.md

Installs all necessary project dependencies using the pnpm package manager. This is the first step before running any other development commands.

```shell
pnpm install
```

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

### Start Local Development Server

Source: https://github.com/swan-io/chicane/blob/main/docs/README.md

Starts a local development server for the Docusaurus website. Changes are typically reflected live without requiring a server restart. Opens the site in a browser window.

```shell
pnpm start
```

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

### Build Static Website

Source: https://github.com/swan-io/chicane/blob/main/docs/README.md

Generates the static content for the website into the 'build' directory. This output can be served by any static hosting service.

```shell
pnpm build
```

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

### Install @swan-io/chicane

Source: https://github.com/swan-io/chicane/blob/main/README.md

Installs the @swan-io/chicane package using either Yarn or npm package managers. This is the first step to integrate the router into your React project.

```bash
$ yarn add @swan-io/chicane
# --- or ---
$ npm install --save @swan-io/chicane
```

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

### Deploy Website (SSH)

Source: https://github.com/swan-io/chicane/blob/main/docs/README.md

Deploys the website using SSH. This command is convenient for building the site and pushing it to the 'gh-pages' branch, especially when using GitHub Pages for hosting.

```shell
USE_SSH=true pnpm deploy
```

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

### Deploy Website (No SSH)

Source: https://github.com/swan-io/chicane/blob/main/docs/README.md

Deploys the website without using SSH. Requires specifying your GitHub username. This command builds the site and pushes to the 'gh-pages' branch, suitable for GitHub Pages hosting.

```shell
GIT_USER=<Your GitHub username> pnpm deploy
```

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

### Code Block Font Styling

Source: https://github.com/swan-io/chicane/blob/main/example/index.html

Sets a specific monospace font family for all code elements, ensuring consistent and readable display of programming code snippets.

```css
code {
  font-family: source-code-pro, Menlo, Monaco, Consolas, "Courier New", monospace;
}
```

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

### Body Styling with Font Resets

Source: https://github.com/swan-io/chicane/blob/main/example/index.html

Applies base margin and font styles to the HTML body, including a system font stack and smoothing properties for cross-platform consistency. This ensures a clean slate for UI design.

```css
body {
  margin: 0;
  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto", "Oxygen", "Ubuntu", "Cantarell", "Fira Sans", "Droid Sans", "Helvetica Neue", sans-serif;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}
```

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

### Matching Routes with useRoute Hook

Source: https://github.com/swan-io/chicane/blob/main/docs/docs/matching-some-routes.md

Demonstrates how to use the `useRoute` hook from a custom router to get the current route. It then utilizes the `ts-pattern` library's `match` function to conditionally render different React components (`Home`, `UserArea`, `NotFound`) based on the route's name. This approach leverages ts-pattern for exhaustivity checks.

```tsx
import { Header } from "./Header";
import { Home } from "./Home";
import { NotFound } from "./NotFound";
import { Router } from "./router";
import { UserArea } from "./UserArea";

export const App = () => {
  // Then pass the route subset this component should listen to (the order isn't important)
  const route = Router.useRoute(["Home", "UserArea"]);

  // And then, simply make each route return its component
  return (
    <>
      <Header />

      {match(route)
        .with({ name: "Home" }, () => <Home />)
        .with({ name: "UserArea" }, () => <UserArea />)
        .otherwise(() => (
          <NotFound />
        ))}
    </>
  );
};
```

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

### Render Routes with Union Params in React App (TypeScriptX)

Source: https://github.com/swan-io/chicane/blob/main/docs/docs/route-pattern-syntax.md

Provides an example of how to use the `useRoute` hook and `match` utility from Chicane to render components based on routes with union parameters. It shows how the captured parameter types are correctly inferred.

```tsx
const App = () => {
  const route = Router.useRoute(["Projects", "Users"]);

  return match(route)
    .with({ name: "Projects" }, ({ params: { env } }) => (
      // env type is "live" | "sandbox"
      <Projects env={env} />
    ))
    .with({ name: "Users" }, ({ params: { statuses } }) => (
      // statuses type is Array<"invited" | "enabled" | "banned"> | undefined
      <Users statuses={statuses} />
    ))
    .otherwise(() => null);
};
```

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

### Get Current Location

Source: https://github.com/swan-io/chicane/blob/main/docs/docs/lower-level-api.md

Retrieves the current application location, parsed into its path segments, search parameters, and raw string representations. It also provides a method to convert the location back into a string.

```ts
import { getLocation 
/*, Location */ } from "@swan-io/chicane";

type Location = {
  path: string[]; // path split on `/`
  search: Record<string, string | string[]>;
  raw: { path: string; search: string };
  toString(): string; // returns the imploded location
};

const location: Location = getLocation();
console.log(location.path);
```

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

### Get Route from Location with Router.getRoute

Source: https://github.com/swan-io/chicane/blob/main/docs/docs/router.md

Retrieves route information from a given location string or the current browser location. It matches the location against a provided subset of routes and returns the matched route name and parameters.

```typescript
const routeA = Router.getRoute(["Home", "UserArea"]);
const routeB = Router.getRoute(["User"], "/users/1");

// Example usage:
// if (routeB && routeB.name === "User") {
//   console.log(routeB.params.userId); // "1"
```

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

### Integrate Chicane Paths with React Router Routes

Source: https://github.com/swan-io/chicane/blob/main/ADOPTION.md

Update your react-router-dom setup to use the path definitions generated by @swan-io/chicane. This ensures that your route declarations in the `Routes` component align with the type-safe paths created by chicane.

```tsx
import { BrowserRouter, Route, Routes } from "react-router-dom";
import { paths } from "./router";

// Assuming Home, Teams, Team, NewTeam are your page components
// import Home from './pages/Home';
// import Teams from './pages/Teams';
// import Team from './pages/Team';
// import NewTeam from './pages/NewTeam';

<BrowserRouter>
  <Routes>
    {/* we use paths from router.ts */}
    <Route path={paths.Home} element={<Home />} />
    <Route path={paths.Teams} element={<Teams />} />
    <Route path={paths.Team} element={<Team />} />
    <Route path={paths.NewTeam} element={<NewTeam />} />
  </Routes>
</BrowserRouter>;

```

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

### Create Chicane Router

Source: https://github.com/swan-io/chicane/blob/main/docs/docs/creating-your-router.md

Demonstrates the basic usage of Chicane's `createRouter` function to define application routes. Each route is given a name and a URL pattern, ensuring type safety for route parameters.

```ts
import { createRouter } from "@swan-io/chicane";

export const Router = createRouter({
  Home: "/",
  About: "/about",
  UserList: "/users",
  UserDetail: "/users/:userId",
});
```

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

### Define Routes and Create Chicane Router

Source: https://github.com/swan-io/chicane/blob/main/ADOPTION.md

Create a router configuration file using TypeScript. This involves defining application routes with potential search parameters and then initializing the @swan-io/chicane router. The generated link creation functions are exported for use in components.

```typescript
import { createRouter } from "@swan-io/chicane";

// Here we list all our application pages
const routes = {
  Home: "/",
  Teams: "/teams?:created", // chicane supports search params declaration
  Team: "/teams/:teamId",
  NewTeam: "/teams/new",
  // Note that chicane "createGroup" works perfectly here! (for routes nesting)
} as const;

// We avoid exporting chicane routing functions
const { getRoute, useRoute, push, replace, ...rest } = createRouter(routes);

// We exports all the link creation functions
export const Router = rest;

// We export paths (without search params, as react-router-dom doesn't support them)
export const paths = (Object.keys(routes) as (keyof typeof routes)[]).reduce(
  (acc, key) => ({ ...acc, [key]: routes[key].replace(/[?#].*/, "") }),
  {} as Record<keyof typeof routes, string>,
);
```

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

### Using the Link Component

Source: https://github.com/swan-io/chicane/blob/main/docs/docs/linking-to-a-route.md

Demonstrates how to use the `Link` component from Chicane to create navigation links to different routes within your application. It shows basic usage with route generation functions.

```tsx
import { Link } from "@swan-io/chicane";
import { Router } from "./router";

const Header = () => (
  <div>
    <h1>My super app</h1>
    <Link to={Router.Home()}>Home</Link>
    <Link to={Router.Users()}>Users</Link>
  </div>
);
```

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

### Organize Nested Routes with Chicane createGroup

Source: https://github.com/swan-io/chicane/blob/main/docs/docs/creating-your-router.md

Shows how to use `createGroup` to organize nested routes efficiently, reducing repetition in route definitions. This helper function allows grouping routes under a common path prefix.

```ts
import { createRouter, createGroup } from "@swan-io/chicane";

export const Router = createRouter({
  Home: "/",
  About: "/about",

  ...createGroup("User", "/users", {
    Area: "/*",
    List: "/",
    Detail: "/:userId",
  }),
});
```

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

### Listen to Routes with Router.useRoute

Source: https://github.com/swan-io/chicane/blob/main/docs/docs/router.md

Hooks into the router to listen for route changes. It takes an array of route names and returns the currently matched route name and its parameters if it's one of the specified routes.

```typescript
const route = Router.useRoute(["Home", "UserArea"]);

// Example usage:
// if (route && route.name === "UserArea") {
//   console.log(route.params);
// }
```

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

### Navigate with Router.push

Source: https://github.com/swan-io/chicane/blob/main/docs/docs/router.md

Navigates to a specified route by name, optionally passing route parameters. This action adds a new entry to the browser's history stack.

```typescript
Router.push("Home");
Router.push("UserDetail", { userId: "123" });
```

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

### ts-pattern Interop with Router.P

Source: https://github.com/swan-io/chicane/blob/main/docs/docs/router.md

Provides integration with the ts-pattern library for advanced route matching. It exposes pattern matchers for each route defined in the router, enabling type-safe conditional logic.

```tsx
import { createRouter } from "@swan-io/chicane";
import { match, P } from "ts-pattern";

const Router = createRouter({
  Home: "/",
  UserArea: "/users/*",
  User: "/users/:userId",
});

const App = () => {
  const route = Router.useRoute(["Home", "UserArea", "User"]);

  return match(route)
    .with(Router.P.Home(P._), () => <Home />)
    .with(Router.P.UserArea(P._), () => <UserArea />)
    .with(Router.P.User({ userId: P.select() }), (id) => <User id={id} />)
    .otherwise(() => null);
};

// Assuming Home, UserArea, User are React components.
```

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

### Creating a Custom Link Component

Source: https://github.com/swan-io/chicane/blob/main/docs/docs/linking-to-a-route.md

Shows how to build a custom `Link` component using the `useLinkProps` hook provided by Chicane. This allows for more control over link behavior and styling, such as applying active classes.

```tsx
import { useLinkProps } from "@swan-io/chicane";
import cx from "classnames";

const Link = ({ to, replace, className, activeClassName, ...props }) => {
  const { active, onClick } = useLinkProps({ href: to, replace });

  return (
    <a
      {...props}
      href={to}
      onClick={onClick}
      className={cx(className, active && activeClassName)}
    />
  );
};
```

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

### Implement Route Focus Reset with useFocusReset Hook

Source: https://github.com/swan-io/chicane/blob/main/docs/docs/route-focus.md

Demonstrates how to use the `useFocusReset` hook from `@swan-io/chicane` to automatically manage focus on route changes. This hook enhances accessibility by directing focus to the relevant content area, reducing keyboard navigation steps. It requires a `route` object and a `containerRef` for its operation.

```tsx
import { useFocusReset } from "@swan-io/chicane";
import { useRef } from "react";

export const App = () => {
  const route = Router.useRoute(["Home", "UserArea"]);
  const containerRef = useRef(null);

  useFocusReset({ route, containerRef });

  return (
    <>
      <Header />

      <div ref={containerRef}>
        {match(route)
          .with({ name: "Home" }, () => <Home />)
          .with({ name: "UserArea" }, () => <UserArea />)
          .otherwise(() => (
            <NotFound />
          ))}
      </div>
    </>
  );
};
```

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

### Basic Usage of @swan-io/chicane Router

Source: https://github.com/swan-io/chicane/blob/main/README.md

Demonstrates creating a typed router with named routes and using it within a React component with ts-pattern for route matching. It highlights strongly typed route parameters for improved developer experience.

```tsx
import { createRouter } from "@swan-io/chicane";
import { match } from "ts-pattern";

const Router = createRouter({
  Home: "/",
  Users: "/users",
  User: "/users/:userId",
});

const App = () => {
  const route = Router.useRoute(["Home", "Users", "User"]);

  // route object is a discriminated union
  return match(route)
    .with({ name: "Home" }, () => <h1>Home</h1>)
    .with({ name: "Users" }, () => <h1>Users</h1>)
    .with({ name: "User" }, ({ params }) => <h1>User {params.userId}</h1>) // params are strongly typed
    .otherwise(() => <h1>404</h1>);
};
```

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

### InferRoutes Utility

Source: https://github.com/swan-io/chicane/blob/main/docs/docs/utility-types.md

Demonstrates how to use `InferRoutes` from `@swan-io/chicane` to extract route types and parameters. It shows the creation of a router and the subsequent inference of route names and their associated parameters.

```typescript
import { createRouter, InferRoutes } from "@swan-io/chicane";

export const Router = createRouter({
  UserList: "/users",
  UserDetail: "/users/:userId",
});

// A map of route names and their associated params
type Routes = InferRoutes<typeof Router>;

export type RouteName = keyof Routes;
export type RouteParams<T extends RouteName> = Routes[T];
```

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

### Server-side Rendering with ServerUrlProvider

Source: https://github.com/swan-io/chicane/blob/main/docs/docs/server-side-rendering.md

Demonstrates how to implement server-side rendering by wrapping the application with `ServerUrlProvider`. This component is crucial for providing the correct server URL context to the client-side application during SSR. It integrates with Express.js for handling requests.

```tsx
import { ServerUrlProvider } from "@swan-io/chicane";
import express from "express";
import { renderToString } from "react-dom/server";
import { App } from "../client/App";

const app = express();

app.use("*", (req, res) => {
  const html = renderToString(
    <ServerUrlProvider value={req.originalUrl}>
      <App />
    </ServerUrlProvider>,
  );

  // …
});

```

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

### Define Simple Path in Chicane Routes (TypeScript)

Source: https://github.com/swan-io/chicane/blob/main/docs/docs/route-pattern-syntax.md

Demonstrates how to assign a basic URL pattern to a route definition using the `createRouter` function. This is the most straightforward way to map a route name to a static path.

```ts
const Router = createRouter({
  Home: "/",
  UserList: "/users"
});
```

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

### Create Router Functionality with Chicane

Source: https://github.com/swan-io/chicane/blob/main/docs/docs/top-level-api.md

The `createRouter` function initializes a routing configuration. It accepts an object mapping route names to their path patterns. An optional `basePath` option can be provided to prefix all defined routes.

```TypeScript
import { createRouter } from "@swan-io/chicane";

export const Router = createRouter({
  Home: "/",
  UserList: "/users",
  UserDetail: "/users/:userId",
});
```

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

### Programmatic Navigation

Source: https://github.com/swan-io/chicane/blob/main/docs/docs/linking-to-a-route.md

Details the functions available for navigating programmatically within the application. These methods allow for controlled navigation from JavaScript code without user interaction.

```APIDOC
Router.push(routeName, routeParams)
  - Navigates to a specified route by pushing a new entry onto the browser history stack.
  - Parameters:
    - routeName: The name of the route to navigate to.
    - routeParams: Optional parameters for the route.

Router.replace(routeName, routeParams)
  - Navigates to a specified route by replacing the current entry in the browser history stack.
  - This method does not create a new history entry, making it suitable for redirects or form submissions.
  - Parameters:
    - routeName: The name of the route to navigate to.
    - routeParams: Optional parameters for the route.
```

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

### Handle Wildcard Routes in React App (TypeScriptX)

Source: https://github.com/swan-io/chicane/blob/main/docs/docs/route-pattern-syntax.md

Demonstrates how to use Chicane's routing in a React application to handle wildcard routes. The `useRoute` hook can match a route defined with a wildcard, allowing a parent component to render a child component responsible for its subroutes.

```tsx
const App = () => {
  const route = Router.useRoute(["Home", "UserArea"]);

  return match(route)
    .with({ name: "Home" }, () => <Home />)
    .with({ name: "UserArea" }, () => <UserArea />)
    .otherwise(() => null);
};
```

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

### Unsafe Navigation Functions

Source: https://github.com/swan-io/chicane/blob/main/docs/docs/lower-level-api.md

Offers direct, 'unsafe' methods for programmatic navigation, similar to `Router.push` and `Router.replace`. These functions accept a unique string argument for navigation, bypassing the typical structured location object.

```ts
import { pushUnsafe, replaceUnsafe } from "@swan-io/chicane";

pushUnsafe("/");
replaceUnsafe("?name=frank");
```

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

### Chicane Link Component for Routing

Source: https://github.com/swan-io/chicane/blob/main/docs/docs/components.md

Documentation for the Chicane Link component, which creates links to URLs handled by the router. It accepts props for navigation control and styling, including defining the target route and optional replacement behavior.

```ts
type LinkProps = {
  to: string; // The route you're linking to (required)
  replace?: boolean; // Replace instead of push (defaults to `false`)
  activeClassName?: string;
  activeStyle?: React.CSSProperties;
  // …and any prop <a> takes
};
```

```tsx
import { Link } from "@swan-io/chicane";

const App = () => (
  <>
    <Link to={Router.Home()}>Home</Link>
    <Link to={Router.UseDetail({ userId: "123" })}>User</Link>
  </>
);
```

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

### Define Query Parameters in Chicane Routes (TypeScript)

Source: https://github.com/swan-io/chicane/blob/main/docs/docs/route-pattern-syntax.md

Illustrates how to specify query parameters in a route pattern using the `:paramName` syntax after a `?`. Multiple query parameters are separated by `&`. These parameters are nullable strings in the route's params object.

```ts
const Router = createRouter({
  Home: "/",
  UserArea: "/users/*",
  UserList: "/users?:sortBy",
  UserDetail: "/users/:userId"
});
```

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

### Type-Safe Link Creation and Navigation

Source: https://github.com/swan-io/chicane/blob/main/ADOPTION.md

Utilize the exported link creation functions from the chicane router to generate type-safe `to` props for react-router-dom's `Link` component and for use with `useNavigate`. This prevents runtime errors related to incorrect parameter passing.

```tsx
import { Link, useNavigate } from "react-router-dom";
import { Router } from "./router";

const SomePage = () => {
  const navigate = useNavigate();

  return (
    <>
      <Link to={Router.Home()}>Back to home page</Link>
      <Link to={Router.Team({ teamId: "foo" })}>Team foo page</Link>
      <Link to={Router.Team({ teamId: "bar" })}>Team bar page</Link>

      <button
        onClick={(event) => {
          event.preventDefault();
          navigate(Router.Teams({ created: "baz" }), { replace: true });
        }}
      >
        Click me
      </button>
    </>
  );
};

```

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

### Define Path Parameters in Chicane Routes (TypeScript)

Source: https://github.com/swan-io/chicane/blob/main/docs/docs/route-pattern-syntax.md

Shows how to include dynamic segments (parameters) in a URL pattern using the `:paramName` syntax. These parameters are captured and provided as non-nullable strings in the route's params object.

```ts
const Router = createRouter({
  Home: "/",
  UserList: "/users",
  UserDetail: "/users/:userId"
});
```

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

### Manage Subroutes with Wildcards in React Component (TypeScriptX)

Source: https://github.com/swan-io/chicane/blob/main/docs/docs/route-pattern-syntax.md

Shows a child React component (`UserArea`) handling its own subroutes when matched via a wildcard in the parent. It uses `useRoute` to match specific routes within its scope, demonstrating delegation of routing logic.

```tsx
const UserArea = () => {
  const route = Router.useRoute(["UserList", "UserDetail"]);

  return match(route)
    .with({ name: "UserList" }, () => <UserList />)
    .with({ name: "UserDetail" }, ({ params: { userId } }) => (
      <UserDetail userId={userId} />
    ))
    .otherwise(() => null);
};
```

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

### Link Component Props

Source: https://github.com/swan-io/chicane/blob/main/docs/docs/linking-to-a-route.md

Defines the available properties for the Chicane `Link` component. This includes the destination route, optional replacement behavior, and styling for active links.

```APIDOC
LinkProps:
  to: string; // The route you're linking to (required)
  replace?: boolean; // Replace instead of push (defaults to `false`)
  activeClassName?: string;
  activeStyle?: React.CSSProperties;
  // ...and any prop <a> takes
```

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

### Encode and Decode Search Parameters

Source: https://github.com/swan-io/chicane/blob/main/docs/docs/lower-level-api.md

Provides utilities to serialize JavaScript objects into URL query strings (`encodeSearch`) and parse URL query strings back into JavaScript objects (`decodeSearch`). Handles multiple values for the same parameter.

```ts
import { encodeSearch, decodeSearch } from "@swan-io/chicane";

encodeSearch({ invitation: "542022247745", users: ["frank", "chris"] });
// -> "?invitation=542022247745&users=frank&users=chris"

decodeSearch("?invitation=542022247745&users=frank&users=chris");
// -> { invitation: "542022247745", users: ["frank", "chris"] }
```

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

### Define Wildcard Route in Chicane Routes (TypeScript)

Source: https://github.com/swan-io/chicane/blob/main/docs/docs/route-pattern-syntax.md

Explains the use of wildcards (`*`) in route patterns to match any path segment or sequence of segments. This is useful for delegating subroute management to child components.

```ts
const Router = createRouter({
  Home: "/",
  UserArea: "/users/*", // will match "/users" and "/users/:userId"
  UserList: "/users",
  UserDetail: "/users/:userId"
});
```

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

### Subscribe to Location Changes

Source: https://github.com/swan-io/chicane/blob/main/docs/docs/lower-level-api.md

Allows subscribing to real-time changes in the application's location. A callback function is invoked whenever the location updates, receiving the new `Location` object as an argument.

```ts
import { subscribeToLocation } from "@swan-io/chicane";

// Assuming Location type is defined as above
// import { Location } from "@swan-io/chicane";

subscribeToLocation((location: Location) => {
  console.log("Location changed!");
  console.log(location);
});
```

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

### useFocusReset Hook for Route Focus Management

Source: https://github.com/swan-io/chicane/blob/main/docs/docs/hooks.md

Manages focus on the updated route within a specified container. It takes a `route` object and a `containerRef` to programmatically set focus when the route changes.

```tsx
import { useFocusReset } from "@swan-io/chicane";
import { useRef } from "react";

export const App = () => {
  const route = Router.useRoute(["Home", "UserArea"]);
  const containerRef = useRef(null);

  useFocusReset({ route, containerRef });

  return (
    <>
      <Header />

      <div ref={containerRef}>
        {match(route)
          .with({ name: "Home" }, () => <Home />)
          .with({ name: "UserArea" }, () => <UserArea />)
          .otherwise(() => (
            <NotFound />
          ))}
      </div>
    </>
  );
};

```

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

### Create Group for Nested Routes with Chicane

Source: https://github.com/swan-io/chicane/blob/main/docs/docs/top-level-api.md

The `createGroup` function simplifies defining nested routes with common prefixes and search parameters. It takes a route name, a base path, and an object of subroutes, allowing for cleaner route organization and avoiding repetition.

```TypeScript
import { createRouter, createGroup } from "@swan-io/chicane";

export const Router = createRouter({
  Home: "/",

  ...createGroup("User", "/users", {
    Area: "/*", // UserArea: "/users/*"
    List: "/", // UserList: "/users"
    Detail: "/:userId", // UserDetail: "/users/:userId"
  }),

  ...createGroup("Book", "/books?:isEditor", {
    Area: "/*", // BookArea: "/books/*?:isEditor"
    List: "/?:byAuthor", // BookList: "/books?:isEditor&:byAuthor"
    Detail: "/:bookId", // BookDetail: "/books/:bookId?:isEditor"
  }),
});
```

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

### Navigate without History with Router.replace

Source: https://github.com/swan-io/chicane/blob/main/docs/docs/router.md

Navigates to a specified route by name, optionally passing route parameters, without creating a new entry in the browser's history. This is useful for replacing the current page state.

```typescript
Router.replace("Home");
Router.replace("UserDetail", { userId: "123" });
```

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

### Generate URL with Router.RouteName

Source: https://github.com/swan-io/chicane/blob/main/docs/docs/router.md

Generates a URL for a specific route, optionally taking route parameters. This method is specific to each defined route name within the Router configuration.

```typescript
Router.UserDetail({ userId: "123" }); // Returns "/users/123"
```

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

### Define Union Parameters in Chicane Routes (TypeScript)

Source: https://github.com/swan-io/chicane/blob/main/docs/docs/route-pattern-syntax.md

Demonstrates how to constrain path parameter types by defining union types using the `:name{a|b|…}` syntax. This allows for more specific type checking and validation of dynamic segments.

```ts
const Router = createRouter({
  Home: "/",
  Projects: "/:env{live|sandbox}/projects",
  Users: "/users?:statuses{invited|enabled|banned}[]"
});
```

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

### Define Array Query Parameters in Chicane Routes (TypeScript)

Source: https://github.com/swan-io/chicane/blob/main/docs/docs/route-pattern-syntax.md

Explains how to define query parameters that can accept multiple values, such as for filters. Suffixing a parameter with `[]` indicates it should be treated as an array, resulting in a nullable string array in the params object.

```ts
const Router = createRouter({
  Home: "/",
  UserArea: "/users/*",
  UserList: "/users?:sortBy&:status[]",
  UserDetail: "/users/:userId"
});
```

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

### useLinkProps Hook for Anchor Element Props

Source: https://github.com/swan-io/chicane/blob/main/docs/docs/hooks.md

Provides props for an `<a>` element, useful for creating custom Link components. It returns `active` state and an `onClick` handler, managing navigation state.

```tsx
import { useLinkProps } from "@swan-io/chicane";

const MyCustomLink = ({ to, className, activeClassName, ...props }) => {
  const { active, onClick } = useLinkProps({ href: to, replace, target });

  return (
    <a
      {...props}
      onClick={onClick}
      className={cx(className, active && activeClassName)}
    />
  );
};

```

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

### useBlocker Hook for Navigation Confirmation

Source: https://github.com/swan-io/chicane/blob/main/docs/docs/hooks.md

Blocks navigation and prompts the user for confirmation, which is useful for preventing data loss from unsaved form states. It takes a boolean condition and a confirmation message.

```tsx
import { useBlocker } from "@swan-io/chicane";

const App = () => {
  const { formStatus } = useForm(/* … */);

  useBlocker(
    formStatus === "editing",
    "Are you sure you want to stop editing this profile?",
  );

  // …
};

```

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

### useLocation Hook for Current Location

Source: https://github.com/swan-io/chicane/blob/main/docs/docs/hooks.md

Returns the current, up-to-date location object and updates automatically when the location changes. Useful for reacting to URL changes within the application.

```tsx
import { useLocation } from "@swan-io/chicane";

const App = () => {
  const location = useLocation();

  React.useEffect(() => {
    console.log("Location changed!");
    console.log(location);
  }, [location]);

  // …
};

```
Tokens:
Raw