@tirth_jasoliya/router

⚡ A type-safe, DX-first routing utility built on top of React Router. Inject routes once — unlock typed navigation, preloadable links, and end-to-end IntelliSense across your application.

📦 Installation

# Using npm
npm install @tirth_jasoliya/router

# Using yarn
yarn add @tirth_jasoliya/router

🚀 Why @tirth_jasoliya/router?

• ✅ Type-safe navigation — compile-time validation of Link, NavLink, Navigate, and custom navigation hooks.
• 🌐 Typed path + query builder — intelligent generation of URLs with strict param enforcement.
• ⚛️ Pluggable Components & Hooks — generate your own TypedLink, useTypedNavigate, etc. with route schema inference.
• 🧠 Preload-powered routing — enables faster UX with built-in preloading on hover, focus, or mount.
• 🧰 Utility-first — inject once, consume anywhere. All features are composable and optimized for performance.

🧩 Core Concepts

1. 📥 Injecting Routes

Preapre your routes once in routes.tsx

// routes.ts
import { TypedRouteObject } from "@tirth_jasoliya/router";

const routes = [
  {
    element: <AuthLayout />,
    children: authRoutes,
    hydrateFallbackElement: <Loader />,
    errorElement: <ErrorComponent />
  },
  {
    element: <AppLayout />,
    children: appRoutes,
    hydrateFallbackElement: <Loader />,
  }
] as const satisfies readonly TypedRouteObject[];

export default routes

2. 📥 Injecting Routes into RouterProvider

// main.tsx
import { toRouteObjects } from '@tirth_jasoliya/router'
import { createBrowserRouter, RouterProvider } from 'react-router'

const router = createBrowserRouter(toRouteObjects(routes))

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <RouterProvider router={router} />
  </StrictMode>
)

3. 🧠 Creating Typed Components & Hooks

// lib/typed-router.ts
import { createTypedComponents, createTypedHooks, FlattenRoutes } from "@tirth_jasoliya/router";
import routes from "@/routes";

export type AppRoutes = FlattenRoutes<typeof routes> | "#";

export const { TypedLink, TypedNavLink, TypedNavigate } = createTypedComponents<AppRoutes>();

export const useTypedNavigate = createTypedHooks<AppRoutes>()

4. 🧵 Typed Navigation

function ProfileButton() {
  const { typedNavigate } = useTypedNavigate();

  return (
    <button
      onClick={() => typedNavigate("/profile/:userId", {
        params: { userId: "99" },
        query: { tab: "activity" },
        preload: true
      })}
    >
      View Profile
    </button>
  );
}

5. 🔗 Typed Link & NavLink

<TypedLink
  to="/profile/:userId"
  routeOptions={{
    params: { userId: "123" },
    query: { ref: "email" },
    preload: true,
    preloadOn: "hover"
  }}
>
  Go to Profile
</TypedLink>

<TypedNavLink
  to="/dashboard"
  className={({ isActive }) => isActive ? "active" : ""}
>
  Dashboard
</TypedNavLink>

6. 🔄 Typed Redirect / Navigate

<TypedNavigate
  to="/dashboard"
  routeOptions={{ query: { from: "login" } }}
  replace
/>

7. 🌐 buildPath + preloadRoute

import { buildPath, preloadRoute } from "@tirth_jasoliya/router";

const href = buildPath("/profile/:userId", { userId: "42" }, { ref: "twitter" });
await preloadRoute(href);

🧪 Example with React Router

import { RouterProvider, createBrowserRouter } from "react-router-dom";
import { toRouteObjects, getRoutes } from "@tirth_jasoliya/router";

const router = createBrowserRouter(toRouteObjects(getRoutes()));

<RouterProvider router={router} />

⚙️ Utility Functions

| Function | Description | | -------------------- | ---------------------------------------------- | | injectRoutes() | Injects your static route config | | getRoutes() | Returns injected routes | | getRouteMeta(path) | Fetches route metadata for a given path | | buildPath() | Builds a typed path with optional params/query | | preloadRoute() | Triggers preload for the given path | | toRouteObjects() | Converts typed routes to RouteObject[] |

📐 Type Utilities

| Type | Description | | ------------------------------ | ---------------------------------------- | | PathParams<"/user/:id"> | { id: string } | | QueryParams<{ key: string }> | { key: string } | | FlattenRoutes<Routes> | Extracts all deep route paths as a union | | TypedNavigateTarget<T> | Supports path strings, object, or number | | TypedNavigateOptions<T> | Navigation options type-safe per path |

💡 Roadmap

• ✅ React Router v6+ support
• 🔜 SSR-friendly hooks (Next.js / RSC layer)
• 🔜 Tree-shakable route resolver plugins
• 🔜 CLI schema-to-types generator

👨‍💻 Contributing

Feel free to open issues, request features, or submit PRs. Let’s redefine typed routing together.

📄 License

MIT — Built by [Tirth Jasoliya] with passion, precision, and preloading.