baqk

Smart back navigation with state preservation for React apps.

The Problem

User filters a list, clicks into a detail page, hits back — filters are gone. history.back() can't carry state, and sessionStorage alone doesn't know which page to restore. baqk solves this with a hybrid navId + sessionStorage approach that preserves state, scroll position, and navigation context across any number of levels.

Install

npm install @thrylm/baqk

ESM-only. Requires react >= 18.

~3.5 kB gzipped (core + hook). Each adapter adds ~500 B.

Quick Start

// app.tsx — wrap your app with the adapter
import { BaqkAdapter } from "@thrylm/baqk/adapters/react-router";

function App() {
  return (
    <BaqkAdapter>
      <Routes>{/* ... */}</Routes>
    </BaqkAdapter>
  );
}

// products.tsx — listing page
import { useBaqk, useTrailClick } from "@thrylm/baqk";
import { Link } from "react-router-dom";

function ProductList() {
  const { restoredState, saveState } = useBaqk<{ filters: Filters }>();
  const trailClick = useTrailClick("Products");

  // Restore filters synchronously — no useEffect
  const [filters, setFilters] = useState(
    () => restoredState?.filters ?? defaultFilters,
  );

  // Save state whenever filters change
  useEffect(() => { saveState({ filters }); }, [filters]);

  return products.map((p) => (
    <Link to={`/products/${p.id}`} onClick={trailClick}>
      {p.name}
    </Link>
  ));
}

// product-detail.tsx — detail page
import { useBaqk } from "@thrylm/baqk";

function ProductDetail() {
  const { goBack, previousEntry } = useBaqk({
    fallbackPath: "/products",
  });

  return (
    <div>
      <button onClick={() => goBack()}>
        {previousEntry ? `← ${previousEntry.label}` : "← Products"}
      </button>
      {/* ... */}
    </div>
  );
}

Adapters

React Router

import { BaqkAdapter } from "@thrylm/baqk/adapters/react-router";

<BaqkAdapter>
  <RouterProvider router={router} />
</BaqkAdapter>

Next.js App Router

import { BaqkAdapter } from "@thrylm/baqk/adapters/next";

<BaqkAdapter>
  {children}
</BaqkAdapter>

TanStack Router

import { BaqkAdapter } from "@thrylm/baqk/adapters/tanstack";

<BaqkAdapter>
  <RouterProvider router={router} />
</BaqkAdapter>

Generic (any router)

import { BaqkAdapter } from "@thrylm/baqk";

<BaqkAdapter
  navigate={(path, options) =>
    options?.replace ? myRouter.replace(path) : myRouter.push(path)
  }
  getCurrentPath={() => window.location.pathname + window.location.search}
>
  {children}
</BaqkAdapter>

All router-specific adapters accept optional sessionKey and storage props. The generic adapter additionally requires navigate and getCurrentPath.

API Reference

useTrailClick(label?)

Returns an onClick handler that pushes a trail entry without navigating. Attach it to same-tab internal <Link>/anchor navigations — the link handles navigation natively, no preventDefault needed.

import { useTrailClick } from "@thrylm/baqk";

function ProductList() {
  const trailClick = useTrailClick("Products");

  return products.map((p) => (
    <Link to={`/products/${p.id}`} onClick={trailClick}>
      {p.name}
    </Link>
  ));
}

Behavior:

• Saves scroll position and pushes the current page onto the trail
• Skips on modifier keys (meta, ctrl, shift, alt), middle-click, or defaultPrevented
• Skips new-tab, download, external, and hash-only anchor clicks
• Captures path at click time via getCurrentPath() (reads window.location, compatible with nuqs/shallow updates)
• Does NOT call preventDefault() or navigate — the underlying link handles that
• Shares the same navId as useBaqk() (both use ensureNavId which is idempotent)

useBaqk<T>(options?)

Options (BaqkOptions)

| Option | Type | Default | Description | |--------|------|---------|-------------| | fallbackPath | string | undefined | Path to navigate to when goBack() is called with no trail | | autoSaveScroll | boolean | true | Automatically save/restore scroll position |

Return value (BaqkResult<T>)

| Property | Type | Description | |----------|------|-------------| | goBack | (fallbackPath?) => void | Pop the trail and navigate back, or use fallback | | previousEntry | TrailEntry \| null | The most recent trail entry (the page you'd go back to) | | saveState | (state: T) => void | Save state for the current page | | restoredState | T \| null | Synchronously available saved state (lazy ref pattern) | | wasRestored | boolean | Whether state was restored for this page | | clear | () => void | Clear the trail and all associated state |

TrailEntry

interface TrailEntry {
  path: string;
  navId: string;
  label?: string;
  timestamp: number;
}

BaqkAdapterProps (router-specific adapters)

| Prop | Type | Description | |------|------|-------------| | children | ReactNode | — | | sessionKey | string? | Namespace for storage isolation (e.g. user ID) | | storage | StorageAdapter? | Custom storage backend (defaults to sessionStorage) |

GenericBaqkAdapterProps (generic adapter)

Extends BaqkAdapterProps with:

| Prop | Type | Description | |------|------|-------------| | navigate | (path: string, options?: { replace?: boolean }) => void | Navigation function | | getCurrentPath | () => string | Returns current path + search params |

How It Works

• Each page visit gets a unique navId stamped into history.state
• When useTrailClick fires, the current page's path + navId are pushed onto a trail stack in sessionStorage
• State and scroll position are keyed by sessionKey:navId, so they survive navigations
• goBack pops the trail, navigates to the previous path, and re-stamps the navId — triggering automatic state + scroll restoration
• restoredState is computed synchronously via a lazy ref (no useEffect, no flash of default state)

Advanced

Session key

Use sessionKey to isolate trails per user or session:

<BaqkAdapter sessionKey={user.id}>

Custom storage

import { createMemoryStorage } from "@thrylm/baqk";

<BaqkAdapter storage={createMemoryStorage()}>

createBaqkAdapter factory

Build an adapter for any router:

import { createBaqkAdapter } from "@thrylm/baqk";

const MyBaqkAdapter = createBaqkAdapter(() => {
  // Return a RouterAdapter: { getCurrentPath, navigate, getHistoryState, replaceHistoryState }
  return useMyRouter();
});

Limits

• Trail stack: max 50 entries (oldest evicted with their state)
• State size: max 100 KB per entry (oversized state is silently dropped with a console warning)

License

MIT