Router Config API

in Tempeh, working with routes is fairly easy and all the necessary apis can be retrieved through the routerBuilder factory function that will be used in a global config file often named as route.config.ts.

import { routeBuilder } from "tempeh";
 
const { Navigate, createRoute, useTempehRouter } = routeBuilder({
  // we can add additional base urls here.
  // For example, if we have a SSO setup and auth service is on a different domain.
  additionalBaseUrls: {
    API: "https://api.example.com",
    AUTH: "https://auth.example.com",
  },
  // since we primarily want to manage the Next.js routes.
  defaultBaseUrl: "/",
}).getInstance();
 
 
export { Navigate, createRoute, useTempehRouter };

We got three main functions from the routerBuilder.getInstance function:

1. Navigate: This function is used to navigate to a different route. Think of it as a Link component in Next.js. where you can pass the pathname, searchParams, etc. and the base urls will be taken from one of the base urls provided in the router.config.ts file. This can be useful to navigate to external pages.
2. createRoute: This function is used to create a route. This gives us the utilities to create declarative routes in our Next.js application. read more at routes page.
3. useTempehRouter: This is a hook that can be used to get the current route information. This is patched with the Next.js router object and can be used to get the current route information. It enhances the current Next.js router object with the defined base urls and better API. It only returns push, replace and prefetch as rest of the functions returned by useRouter are not route dependent.

Navigate

import { Navigate } from "./route.config";
// Home.tsx
import * as React from "react";
 
export const Home = () => {
  return (
    <div>
      <h1>Home</h1>
      <Navigate
        base="AUTH"
        path={"/sign-in"}
        searchParams={{
          redirectUrl: "https://example.com",
        }}
      >
        Home
      </Navigate>
    </div>
  );
};

As you can see, we are using the Navigate component to navigate to a different route.

createRoute

import { object } from "zod";
import * as React from "react";
import { createRoute } from "./route.config.ts";
 
const {
  Link,
  navigate,
  parseParams,
  parseSearchParams,
  useParams,
  useRouter,
  useSearchParams,
} = createRoute({
  name: "/",
  fn: () => "/",
  paramsSchema: z.object({}),
});
 
 
export const Home = () => {
  return (
    <div>
      <h1>Home</h1>
    </div>
  );
};

As you can see, we are using the createRoute function to create a route. This gives us the utilities to create declarative routes in our Next.js application.

• Link: This is a component that can be used to link any page to the / route (name of the route provided in the createRoute function).
• navigate: Think of this as function that can be used to navigate to the / route. It takes the params and searchParams as arguments and returns a complete url.
• useParams: This can be used to get the params of the current route. if the params of the url are not valid as per the schema, it will throw an error. Built on top of Next.js useParams hook, It will return the params of the current route with the schema validation. You will have end to end type safety powered by your own zod schema. It takes optional argument of safe which if enabled, hook instead of throwing error, it will return a union of error or valid route params.
• useSearchParams: This can be used to get the searchParams of the current route. if the searchParams of the url are not valid as per the schema, it will throw an error. Built on top of Next.js useSearchParams hook, It will return the searchParams of the current route with the schema validation. You will have end to end type safety powered by your own zod schema. It takes optional argument of safe which if enabled, hook instead of throwing error, it will return a union of error or valid route searchParams.
• useRouter: This hook can be used to get the current route information. This is patched with the Next.js router object and can be used to get the current route information. It enhances the current Next.js router object with the defined base urls and better API. It only returns push, replace and prefetch as rest of the functions returned by useRouter are not route dependent.
• parseParams: This function can be used to parse the params of the route. It takes the params and the schema as arguments and returns the parsed params.
• parseSearchParams: This function can be used to parse the searchParams of the route. It takes the searchParams and the schema as arguments and returns the parsed searchParams.

Using the useRouter hook returned from the createRoute function

// file name = "app/workspace/[workspaceid]/page.tsx"
import { object, string } from "zod";
 
const workspaceRouteInfo = createRoute({
  name: "/workspace/:workspaceId",
  fn: ({ workspaceId }) => `/workspace/${workspaceId}`,
  paramsSchema: object({
    workspaceId: string(),
  }),
});
 
// file name = "app/components/header.tsx"
import { workspaceRouteInfo } from "../page";
import { useRouter } from "next/navigation";
import { useEffect } from "react";
 
export const Home = () => {
  const router = workspaceRouteInfo.useRouter(useRouter);
 
  useEffect(() => {
    // read the workspaceId from the local Storage
    const workspaceId = localStorage.getItem("workspaceId");
    if (workspaceId) {
      router.push({
        params: { workspaceId },
      });
    }
  }, []);
  return (
    <>
      <header>
        <Logo />
        <nav>
          {/**
        navbar stuff
        */}
        </nav>
      </header>
      <main></main>
    </>
  );
};

As you can see here, we are using the useRouter hook returned from the createRoute function to get the Next.js router object. This can be used to push to a different route, refresh the current route, etc. We need to pass the useRouter hook to the useRouter function to get the Next.js router object. This is done to make sure that the Next.js router object is patched with the route builder engine. You can also pass your own patched router object to the useRouter function of created tempeh route as long as it has the same shape as the Next.js router object.