Adapted from the black-candle-technologies/wayfinder repository docs.
NOT STABLE.
An offline-first data layer and caching runtime for Next.js apps. Seamless offline experiences, request queueing, background sync, and plugin-based extensibility.
networkThenCache, cacheFirst, and staleWhileRevalidate strategies| Package | Path | Description |
|---|---|---|
@wayfinder/core |
packages/core |
Core runtime, queue management, caching strategies, plugin API |
@wayfinder/next |
packages/next |
React hooks + provider for Next.js integration |
examples/next-app |
examples/next-app |
Demo app: offline queueing, cache inspection, plugins |
Three layers:
@wayfinder/core) — the Wayfinder client class and caching/queue logic. Network retries, mutation queueing, service worker registration, background sync, plugin hooks.@wayfinder/next) — WayfinderProvider and useWayfinder() hook for offline-aware APIs in React.git clone https://github.com/black-candle-technologies/wayfinder.git
cd wayfinder
pnpm install
pnpm -r run build # build all packages
cd examples/next-app && pnpm dev # demo at http://localhost:3000
Test offline behavior: DevTools → Application → Service Workers, confirm wayfinder-sw.js is active; edit a post while offline (request queues); reconnect (queue syncs and clears). The Cache Inspector panel (bottom-left) inspects/clears cached entries.
export interface WayfinderPlugin {
name: string;
onInit?(): void;
onFetch?(url: string): void;
onMutateQueue?(env: MutationEnvelope): void;
onSync?(env: MutationEnvelope): void;
onOnline?(): void;
}
Register via <WayfinderProvider config={{ data: { defaultPolicy: 'networkThenCache' }, plugins: [...] }}>.
| Command | Description |
|---|---|
pnpm -r run build |
Build all packages |
pnpm dev |
Run example app locally |
pnpm lint |
ESLint checks |
MIT © 2025 Lane Bucher.