Stack-Nav

Ultra-lightweight (<1KB), headless state-based router for React with strict TypeScript support.

Why Stack-Nav

Traditional routers (like React Router or TanStack Router) are overkill for desktop apps or simple web tools. Stack-Nav was built for:

• 🖥️ Desktop Apps: Perfect for Tauri or Electron where URL parsing is unnecessary.
• 📦 Zero Bloat: No dependencies. Just React useSyncExternalStore.
• 🛡️ Strict Types: Full autocompletion and compile-time safety for routes and parameters. If you skip a required parameter, TypeScript will let you know immediately.
• 🔙 Native History: Full support for browser back/forward buttons.

Quick Start

1. Define Routes & Hook

import { createStackRouter } from "stack-nav";

type Routes = {
  home: undefined;
  profile: { id: number };
};

export const useNav = createStackRouter<Routes>("home");

2. Implementation

import { RouterView } from "stack-nav";
import { useNav } from "./nav";

const App = () => {
  const { currentScreen, navigate } = useNav();

  return (
    <RouterView<Routes>
      currentScreen={currentScreen}
      screens={{
        home: () => <button onClick={() => navigate("profile", { id: 1 })}>Go</button>,
        profile: () => {
            const { params } = useNav("profile");

            return (
                <>
                    <h1>Profile View</h1>
                    <p>Your user ID: {params.id}</p>
                </>
            )
        }
      }}
      fallback={<div>404</div>}
    />
  );
};

API

• useNav("screen name"): Returns { currentScreen, params, navigate, goBack, history }. (param types auto inferred by the screen name)

• <RouterView />: Helper to render the active screen mapping.

Installation

bun add stack-nav
# or
npm install stack-nav