npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

use-offline-actions

v1.0.0

Published

React hook for an offline-first action queue: save actions while offline (persisted in localStorage), auto-sync when back online with retries and backoff, cross-tab safe, failed-item handling. Outbox pattern in one hook.

Readme

use-offline-actions

npm size

Offline-first actions in one React hook. Users keep working without internet; their actions are saved (localStorage), and sent in order as soon as the connection is back — with retries, backoff, permanent-failure handling and protection against double sending across components and tabs.

import { useOfflineQueue, PermanentError } from 'use-offline-actions';

function OrderForm() {
  const outbox = useOfflineQueue<NewOrder>({
    key: 'orders-outbox',
    handler: async (action) => {
      const res = await fetch('/api/orders', { method: 'POST', body: JSON.stringify(action.payload) });
      if (res.status === 422) throw new PermanentError('Invalid order'); // don't retry
      if (!res.ok) throw new Error(`HTTP ${res.status}`);               // retry later
    },
  });

  return (
    <>
      {!outbox.isOnline && <Banner>Offline — orders will be sent automatically</Banner>}
      {outbox.pending.length > 0 && <Badge>{outbox.pending.length} waiting to sync</Badge>}
      <button onClick={() => outbox.enqueue('createOrder', { productId: 7, qty: 2 })}>Order</button>
      {outbox.failed.map((a) => (
        <p key={a.id}>
          Failed: {a.error} <button onClick={() => outbox.retry(a.id)}>Retry</button>
          <button onClick={() => outbox.remove(a.id)}>Discard</button>
        </p>
      ))}
    </>
  );
}

Install

npm install use-offline-actions

Behaviour

  • Persisted: survives reloads and closed tabs (localStorage, or your own storage, or null for memory).
  • In order: actions are sent one by one; a retryable error pauses the queue (later actions wait) so the server sees them in the original order.
  • Retries: exponential backoff (1 s, 2 s, 4 s … max 60 s), maxAttempts (default 5), then failed.
  • Permanent errors: throw PermanentError (validation errors, 4xx) to skip retries; the queue continues.
  • No double sending: one processor per queue key — Web Locks API across tabs, an in-memory lock inside a tab, and the queue is re-read from storage before each send.
  • Auto sync: on mount, on online events, after enqueue, and on retry timers.

API

useOfflineQueue<P>(options) (alias useOfflineActions)

| Option | Default | Description | | --- | --- | --- | | handler(action) | required | Send one action; throw to retry, throw PermanentError to fail | | key | 'offline-queue' | Storage key / queue identity | | maxAttempts | 5 | Attempts before failed | | retryDelay(attempt) | 1000·2ⁿ (max 60 s) | Backoff | | storage | localStorage | { getItem, setItem } or null | | onSuccess(action, result), onFailure(action, error) | – | Callbacks |

Returns { enqueue(type, payload), pending, failed, isOnline, isSyncing, sync(), retry(id), remove(id), clear() }.

Each action: { id, type, payload, createdAt, attempts, status, error?, nextAttemptAt? } — id is a UUID you can send as an idempotency key so the server can ignore duplicates.

Also exported: useOnlineStatus() → boolean.

Tip

Use one useOfflineQueue per key (e.g. inside a context provider) and read its state from there.

License

MIT