shared-state-no-url

state-in-url — Shared state without URL sync

useSharedState is state-in-url's lightweight cross-component state primitive — no Context provider, no Redux, no Zustand store. State is shared between any components that pass the same module-scoped default-state object (identity, not deep equality). It is framework-agnostic and has no URL involvement.

Decision: use useUrlState (see state-in-url/feature-state-hook) by default. Reach for useSharedState only when the user explicitly opts out of URL sync, or when the state is sensitive / ephemeral / too large for a URL.

Setup

// features/cart/cartState.ts
export type CartState = {
  items: { id: string; qty: number }[];
  isOpen: boolean;
};

export const CART_STATE: CartState = {
  items: [],
  isOpen: false,
};

// any component
'use client';
import { useSharedState } from 'state-in-url'; // NB: top-level subpath

import { CART_STATE } from 'features/cart/cartState';

export function CartButton() {
  const { state, setState } = useSharedState(CART_STATE);

  return (
    <button onClick={() => setState((curr) => ({ ...curr, isOpen: !curr.isOpen }))}>
      Cart ({state.items.length})
    </button>
  );
}

Any other component calling useSharedState(CART_STATE) reads and writes the same store.

Core Patterns

Functional update

setState((curr) => ({ ...curr, items: curr.items.concat(newItem) }));

Read-only getState (avoid rerender)

const { getState } = useSharedState(CART_STATE);

const onSubmit = () => {
  const { items } = getState(); // doesn't subscribe to changes
  api.checkout(items);
};

SSR initial state

const { state } = useSharedState(CART_STATE, () => readFromCookie());

The second-argument function runs once for the initial value (useful for cookie-driven SSR hydration).

Common Mistakes

MEDIUM Reaching for useSharedState when URL sync is wanted

Wrong:

// Filters that the user wants to share via copy/paste link
const { state, setState } = useSharedState(FILTERS_STATE);
// Page refresh loses everything. Link sharing impossible.