state-in-url 6.1.2 → 6.2.0

package/skills/nextjs-ssr/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: nextjs-ssr
+description: >
+  SSR-safe useUrlState in Next.js App Router. Forward searchParams from server
+  pages (awaiting the Promise in Next.js 15+), call useSearchParams() in pure
+  client components, decide between useHistory true/false, and use a Proxy
+  (formerly middleware) to expose query params to server layouts. App Router
+  only — Pages Router is not supported. Load this skill for any use of
+  state-in-url/next or anytime URL state must be correct on first paint.
+type: framework
+library: state-in-url
+framework: react
+library_version: '6.1.3'
+requires:
+  - feature-state-hook
+sources:
+  - 'asmyshlyaev177/state-in-url:packages/urlstate/next/useUrlState/useUrlState.ts'
+  - 'asmyshlyaev177/state-in-url:packages/example-nextjs16/src/middleware.ts'
+  - 'asmyshlyaev177/state-in-url:README.md#with-server-side-rendering'
+---
+
+This skill builds on `state-in-url/feature-state-hook`. Read it first for the module-scoped default-state rule.
+
+# state-in-url — Next.js App Router SSR
+
+Without `searchParams`, the first render of a `useUrlState` component has no URL knowledge. It renders defaults, then a client `useEffect` re-syncs from the URL → visible flash and a React hydration warning. The fix is to feed the URL into the hook on the server (via `searchParams` prop or a Proxy header) so the very first render is correct.
+
+App Router only. Pages Router uses `next/router`, which `state-in-url/next` does not support — there are no plans to add it.
+
+## Setup
+
+### Server page forwarding `searchParams` (recommended)
+
+```typescript
+// app/jobs/page.tsx  (Server Component)
+import { JobsList } from './JobsList';
+
+export default async function Page({
+  searchParams,
+}: {
+  searchParams: Promise<Record<string, string | string[] | undefined>>;
+}) {
+  const sp = await searchParams; // Next.js 15+: searchParams is a Promise
+  return <JobsList searchParams={sp} />;
+}
+```
+
+```typescript
+// app/jobs/JobsList.tsx
+'use client';
+import { useUrlState } from 'state-in-url/next';
+import { JOBS_STATE } from 'features/jobs/jobsState';
+
+export function JobsList({ searchParams }: { searchParams: object }) {
+  const { urlState, setUrl } = useUrlState(JOBS_STATE, { searchParams });
+  return <pre>{JSON.stringify(urlState)}</pre>;
+}
+```
+
+### Pure client component using `useSearchParams`
+
+When you can't (or don't want to) thread `searchParams` from a server parent:
+
+```typescript
+'use client';
+import { useSearchParams } from 'next/navigation';
+import { useUrlState } from 'state-in-url/next';
+import { JOBS_STATE } from 'features/jobs/jobsState';
+
+export function useJobsState() {
+  const searchParams = useSearchParams();
+  return useUrlState(JOBS_STATE, { searchParams });
+}
+```
+
+## Core Patterns
+
+### `useHistory` — choosing the URL update mode
+
+| Setting | Mechanism | Effect | Use when |
+|---|---|---|---|
+| `useHistory: true` (default) | `window.history.pushState` / `replaceState` | No `_rsc` round-trip per URL change | URL state is client-only UI (filters, drawers, tabs) |
+| `useHistory: false` | `next/navigation`'s `router.push` / `router.replace` | RSC refetches on every URL change | URL state must refetch server data (e.g. `searchParams` drives a DB query in the page) |
+
+```typescript
+useUrlState(FORM_STATE, { searchParams, useHistory: false });
+```
+
+Default is `true`. Flip to `false` only when the server page needs to re-render with the new query.
+
+### Decoding state on the server for data fetching
+
+```typescript
+// app/jobs/page.tsx
+import { decodeState } from 'state-in-url/encodeState';
+import { JOBS_STATE } from 'features/jobs/jobsState';
+import { fetchJobs } from 'lib/jobs';
+
+export default async function Page({ searchParams }) {
+  const sp = await searchParams;
+  const state = decodeState(new URLSearchParams(sp as Record<string, string>), JOBS_STATE);
+  const jobs = await fetchJobs({ status: state.status });
+  return <JobsList searchParams={sp} jobs={jobs} />;
+}
+```
+
+### Reading URL state in a server layout (Proxy workaround)
+
+Server layouts don't receive `searchParams`. Set up a Proxy (Next.js 16+ — `middleware.ts` still works as a deprecated alias) to surface the query string as a request header, then decode in the layout. With this setup the layout renders correctly on first paint with no extra rerenders.
+
+```typescript
+// proxy.ts  (or middleware.ts, same content)
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+
+export function proxy(request: NextRequest) {
+  const sp = (request.url.includes('_next') ? '' : request.url).split('?')[1] ?? '';
+  const headers = new Headers(request.headers);
+  headers.set('searchParams', sp);
+  return NextResponse.next({ request: { headers } });
+}
+```
+
+```typescript
+// app/jobs/layout.tsx
+import { headers } from 'next/headers';
+import { decodeState } from 'state-in-url/encodeState';
+import { JOBS_STATE } from 'features/jobs/jobsState';
+
+export default async function Layout({ children }: { children: React.ReactNode }) {
+  const sp = (await headers()).get('searchParams') ?? '';
+  const initial = decodeState(sp, JOBS_STATE);
+
+  return (
+    <>
+      <LayoutHeader initial={initial} />
+      {children}
+    </>
+  );
+}
+```
+
+## Common Mistakes
+
+### CRITICAL Not passing `searchParams` in Next.js App Router
+
+Wrong:
+
+```typescript
+// page.tsx (server)
+export default function Page() { return <Form />; }
+
+// Form.tsx (client)
+const { urlState } = useUrlState(FORM_STATE);  // missing searchParams
+```
+
+Correct:
+
+```typescript
+// page.tsx
+export default async function Page({ searchParams }) {
+  const sp = await searchParams;
+  return <Form searchParams={sp} />;
+}
+
+// Form.tsx
+const { urlState } = useUrlState(FORM_STATE, { searchParams });
+```
+
+`searchParams` makes the **initial** state correct. Without it, the first render uses defaults, then a client `useEffect` re-syncs from the URL on the next tick — causing a visible flash and a hydration warning. URL state still survives refresh either way (URL is the source of truth), but the initial paint is wrong. With a Proxy feeding the layout, no extra rerender happens at all. Most common Next.js issue (#40, #60).
+
+Source: GitHub issues #40, #60 (asmyshlyaev177/state-in-url); maintainer interview
+
+### HIGH Forgetting to await `searchParams` in Next.js 15+
+
+Wrong:
+
+```typescript
+export default function Page({ searchParams }) {
+  return <Form searchParams={searchParams} />; // Promise, not the value
+}
+```
+
+Correct:
+
+```typescript
+export default async function Page({ searchParams }) {
+  const sp = await searchParams;
+  return <Form searchParams={sp} />;
+}
+```
+
+Next.js 15 changed page-level `searchParams` to a Promise. The library silently decodes nothing from an unresolved Promise.
+
+Source: Next.js 15 migration notes
+
+### HIGH Using `state-in-url/next` in a Pages Router project
+
+Wrong:
+
+```typescript
+// pages/index.tsx
+import { useUrlState } from 'state-in-url/next'; // imports next/navigation
+```
+
+Correct:
+
+Use App Router (`app/` directory). The library does not support Pages Router and there are no plans to add support. If you must stay on Pages Router, build a custom hook with `useUrlStateBase` and a `next/router`-backed router object.
+
+Source: README "Gotchas" #3
+
+### MEDIUM Setting `useHistory: false` unnecessarily
+
+Wrong:
+
+```typescript
+useUrlState(FORM_STATE, { searchParams, useHistory: false });
+// every keystroke triggers a Next.js _rsc payload fetch
+```
+
+Correct:
+
+```typescript
+useUrlState(FORM_STATE, { searchParams });
+// useHistory defaults to true → window.history, no server round-trip
+```
+
+`useHistory: false` is only correct when the server page must re-fetch on URL changes. For UI-only state (filters, drawers, tabs) it triples request traffic.
+
+Source: JSDoc on `useUrlState` params; vercel/next.js#59167
+
+### MEDIUM Trying to read `searchParams` in a server layout directly
+
+Wrong:
+
+```typescript
+export default function Layout({ children, searchParams }: any) {
+  // searchParams is always undefined in layouts
+}
+```
+
+Correct:
+
+Use the Proxy + header pattern shown above (`proxy.ts` setting `searchParams` header → layout reads via `headers()` and `decodeState`). With this in place there is no initial lag or extra rerender.
+
+Source: README "Using hook in layout component"; packages/example-nextjs16/src/middleware.ts; maintainer interview
+
+## See also
+
+- `state-in-url/feature-state-hook` — base pattern; required reading.
+- `state-in-url/input-handling` — for text-input UX with the Next.js hook.

package/skills/react-router-remix-setup/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: react-router-remix-setup
+description: >
+  Set up useUrlState for React Router v7 (state-in-url/react-router), React
+  Router v6 (state-in-url/react-router6 — moved here in 6.0.0), and Remix v2
+  (state-in-url/remix). The hook API is identical across all three; only the
+  import path and per-call NavigateOptions (preventScrollReset, state, replace)
+  differ. Load this skill when wiring useUrlState into any non-Next.js
+  React router or migrating from an older import path.
+type: framework
+library: state-in-url
+framework: react
+library_version: '6.1.3'
+requires:
+  - feature-state-hook
+sources:
+  - 'asmyshlyaev177/state-in-url:packages/urlstate/react-router/useUrlState/'
+  - 'asmyshlyaev177/state-in-url:packages/urlstate/react-router6/useUrlState/'
+  - 'asmyshlyaev177/state-in-url:packages/urlstate/remix/useUrlState/'
+  - 'asmyshlyaev177/state-in-url:CHANGELOG.md#600-2025-08-05'
+---
+
+This skill builds on `state-in-url/feature-state-hook`. Read it first for the module-scoped default-state rule.
+
+# state-in-url — React Router and Remix
+
+The hook signature, return shape, and behavior of `useUrlState` are identical across React Router v6, v7, and Remix v2. Three things differ:
+
+| Aspect | Difference |
+|---|---|
+| Import path | `state-in-url/react-router` (v7), `state-in-url/react-router6` (v6), `state-in-url/remix` (Remix v2) |
+| `setUrl` per-call options | Accepts `NavigateOptions` from `react-router` (e.g. `preventScrollReset`, `state`, `replace`) |
+| SSR | Remix v2 routes can hydrate from loader data; React Router CSR-only by default |
+
+## Setup
+
+### React Router v7
+
+```typescript
+import { useUrlState } from 'state-in-url/react-router';
+
+type FiltersState = { sort: 'name' | 'date'; page: number };
+const FILTERS_STATE: FiltersState = { sort: 'name', page: 1 };
+
+export function FiltersBar() {
+  const { urlState, setUrl } = useUrlState(FILTERS_STATE);
+  return <button onClick={() => setUrl({ page: urlState.page + 1 })}>Next</button>;
+}
+```
+
+### React Router v6 (since state-in-url 6.0.0)
+
+```typescript
+// Note the /react-router6 subpath
+import { useUrlState } from 'state-in-url/react-router6';
+
+type FiltersState = { sort: 'name' | 'date'; page: number };
+const FILTERS_STATE: FiltersState = { sort: 'name', page: 1 };
+
+export function FiltersBar() {
+  const { urlState, setUrl } = useUrlState(FILTERS_STATE);
+  return <button onClick={() => setUrl({ page: urlState.page + 1 })}>Next</button>;
+}
+```
+
+### Remix v2
+
+```typescript
+import { useUrlState } from 'state-in-url/remix';
+
+type FiltersState = { sort: 'name' | 'date'; page: number };
+const FILTERS_STATE: FiltersState = { sort: 'name', page: 1 };
+
+export default function Route() {
+  const { urlState, setUrl } = useUrlState(FILTERS_STATE);
+  return <button onClick={() => setUrl({ page: urlState.page + 1 })}>Next</button>;
+}
+```
+
+## Core Patterns
+
+### Pass NavigateOptions per call
+
+```typescript
+setUrl({ tab: 'b' }, { replace: false, preventScrollReset: true });
+```
+
+`replace: false` creates a new history entry (push) instead of replacing.
+`preventScrollReset: true` keeps the page scroll position after the navigation — important when URL state controls in-page UI rather than route content.
+
+### `basename` support
+
+Both `useUrlState` hooks for React Router respect the router's `basename`. No extra configuration is needed in the hook.
+
+```typescript
+// router setup
+<BrowserRouter basename="/admin">
+  <App />
+</BrowserRouter>
+// URL state updates happen at /admin?... not /...
+```
+
+### Functional update preserving other fields
+
+```typescript
+setUrl((curr) => ({ ...curr, page: curr.page + 1 }));
+```
+
+## Common Mistakes
+
+### CRITICAL Importing `/react-router` for a React Router v6 project
+
+Wrong:
+
+```typescript
+// react-router v6 project
+import { useUrlState } from 'state-in-url/react-router'; // targets v7 since 6.0.0
+```
+
+Correct:
+
+```typescript
+import { useUrlState } from 'state-in-url/react-router6';
+```
+
+As of state-in-url v6.0.0 (Aug 2025) the v6 implementation moved to its own subpath. `/react-router` now targets React Router v7 only. Agents trained on older code will use the wrong import.
+
+Source: CHANGELOG v6.0.0 BREAKING CHANGES (asmyshlyaev177/state-in-url)
+
+### HIGH Using the deprecated `useUrlState({ allParamsObj })` signature
+
+Wrong:
+
+```typescript
+useUrlState({ defaultState: FORM_STATE, replace: true }); // removed in v5.0.0
+```
+
+Correct:
+
+```typescript
+useUrlState(FORM_STATE, { replace: true });
+```
+
+state-in-url v5.0.0 removed the old object-wrapped call shape. Defaults are now passed positionally; options go in the second argument.
+
+Source: CHANGELOG v5.0.0 BREAKING CHANGES (asmyshlyaev177/state-in-url)
+
+### CRITICAL `defaultState` defined inside the React component
+
+(Cross-skill failure — also in `feature-state-hook`.)
+
+Wrong:
+
+```typescript
+export function Filters() {
+  const defaults = { sort: 'name' };
+  const { urlState } = useUrlState(defaults);
+}
+```
+
+Correct:
+
+```typescript
+type FiltersState = { sort: 'name' | 'date' };
+const FILTERS_STATE: FiltersState = { sort: 'name' };
+
+export function Filters() {
+  const { urlState } = useUrlState(FILTERS_STATE);
+}
+```
+
+Same identity rule as Next.js. A fresh default object each render breaks sharing and initial-state seeding.
+
+Source: GitHub issues #57, #60, #69 (asmyshlyaev177/state-in-url)
+
+## See also
+
+- `state-in-url/feature-state-hook` — base pattern.
+- `state-in-url/input-handling` — for text-input UX inside a router-driven page.
+- `state-in-url/form-library-integration` — for pairing with `react-hook-form`.

package/skills/shared-state-no-url/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: shared-state-no-url
+description: >
+  Use useSharedState (from state-in-url, NOT a framework subpath) as a
+  framework-agnostic cross-component state primitive when URL sync is
+  explicitly NOT wanted. Same module-scoped default-state-identity rule
+  as useUrlState. A lightweight Context.Provider replacement that works
+  in React, Next.js, Vite, Remix without setup. Load this skill when the
+  user wants shared state but specifies "no URL", or for state that is
+  sensitive, ephemeral, or too large to live in the URL.
+type: core
+library: state-in-url
+library_version: '6.1.3'
+sources:
+  - 'asmyshlyaev177/state-in-url:packages/urlstate/useSharedState/'
+  - 'asmyshlyaev177/state-in-url:README.md#usesharedstate-hook-for-reactjs'
+---
+
+# 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
+
+```typescript
+// features/cart/cartState.ts
+export type CartState = {
+  items: { id: string; qty: number }[];
+  isOpen: boolean;
+};
+
+export const CART_STATE: CartState = {
+  items: [],
+  isOpen: false,
+};
+```
+
+```typescript
+// 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
+
+```typescript
+setState((curr) => ({ ...curr, items: curr.items.concat(newItem) }));
+```
+
+### Read-only `getState` (avoid rerender)
+
+```typescript
+const { getState } = useSharedState(CART_STATE);
+
+const onSubmit = () => {
+  const { items } = getState(); // doesn't subscribe to changes
+  api.checkout(items);
+};
+```
+
+### SSR initial state
+
+```typescript
+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:
+
+```typescript
+// Filters that the user wants to share via copy/paste link
+const { state, setState } = useSharedState(FILTERS_STATE);
+// Page refresh loses everything. Link sharing impossible.
+```
+
+Correct:
+
+```typescript
+import { useUrlState } from 'state-in-url/next';
+const { urlState, setUrl } = useUrlState(FILTERS_STATE, { searchParams });
+```
+
+`useSharedState` has no URL involvement. Pick `useUrlState` whenever state should survive a refresh or be shareable; pick `useSharedState` only when the user explicitly says "no URL".
+
+Source: Maintainer interview
+
+### HIGH Default state defined inside the React component
+
+Wrong:
+
+```typescript
+function CartButton() {
+  const initial = { items: [], isOpen: false };
+  useSharedState(initial); // different identity in every component → no sharing
+}
+```
+
+Correct:
+
+```typescript
+// cartState.ts (module scope)
+export type CartState = { items: { id: string; qty: number }[]; isOpen: boolean };
+export const CART_STATE: CartState = { items: [], isOpen: false };
+
+function CartButton() {
+  useSharedState(CART_STATE);
+}
+```
+
+Same identity-based sharing rule as `useUrlState`. A non-static default breaks cross-component sharing silently — each call creates an independent store.
+
+Source: Inferred from `useUrlState` pattern (shared internals)
+
+### MEDIUM Storing actual secrets in shared state
+
+Wrong:
+
+```typescript
+const SESSION_STATE = { token: '', userId: '' };
+useSharedState(SESSION_STATE);
+```
+
+Correct:
+
+Use a proper auth store (cookies, secure storage, framework auth helper). `useSharedState` is in-memory and reasonable for app state, but it's not a vault — any component on the page can read it via the shared identity.
+
+## When NOT to use this skill
+
+- The data should be shareable by URL → `state-in-url/feature-state-hook` instead.
+- The data is server cache (lists, paginated queries) → `@tanstack/react-query` or `swr`.
+- The data is persisted user prefs across sessions → `localStorage` or a settings API.
+
+## See also
+
+- `state-in-url/feature-state-hook` — when URL sync IS wanted (the default choice).