offline-first-react

Offline-first React 18+ primitives: network status, cached queries, a durable mutation queue, optional conflict handling, and service worker helpers. Peer dependency: React only (no other runtime deps).

Install

npm install offline-first-react

pnpm add offline-first-react
yarn add offline-first-react

Peer: react >= 18.0.0

Package name vs repository

| | | | ------------------- | --------------------------------------------------------------------------------------------------- | | npm package | offline-first-react | | Source & issues | bhuvaneshwararaja/react-offline-first |

The name react-offline-first is already used on npm by another project, so this library is published under offline-first-react. Import from offline-first-react in application code.

Usage

import {
  OfflineProvider,
  useOfflineQuery,
  useMutation,
  useNetworkStatus,
} from 'offline-first-react';

function App() {
  return (
    <OfflineProvider
      config={{
        storeName: 'my-app',
        maxRetries: 3,
        conflictStrategy: 'client-wins',
      }}
    >
      <Main />
    </OfflineProvider>
  );
}

Entry points (subpath exports)

| Import | Purpose | | ------------------------------ | ---------------------------------------------------------- | | offline-first-react | Provider, hooks, adapters, registerServiceWorker, types | | offline-first-react/hooks | Tree-shakeable hook re-exports | | offline-first-react/adapters | MemoryAdapter, IndexedDBAdapter, LocalStorageAdapter | | offline-first-react/sw | registerServiceWorker helper |

Service worker

Optional Background Sync: ship dist/offline-first-sync-worker.js from the package build as your public sw.js (or merge into your own worker). See the technical specification in the repo.

Documentation

• Full spec: docs/tech-doc.md (in the GitHub repository)

Contributing

Contributing · Code of Conduct · Security

CI (lint, tests, Codecov, type-check, bundle size, examples, Storybook) runs in ci.yml. Releases use Changesets via release.yml.

Clone and build

git clone https://github.com/bhuvaneshwararaja/react-offline-first.git
cd react-offline-first
pnpm install
pnpm run build
pnpm test

Build outputs: dist/index.mjs / dist/index.cjs, dist/hooks/index.mjs, dist/adapters/index.mjs, dist/sw.js, dist/offline-first-sync-worker.js.

Examples (monorepo)

pnpm install
pnpm run build
pnpm --filter @example/todo-app dev
pnpm --filter @example/notes-sync dev

Storybook

pnpm run storybook

License

MIT