Declarative, type-safe connectivity detection and offline action queue for web apps.
| Package | Version | Description |
|---|---|---|
@connectivity-js/core |
Framework-agnostic core — use with any framework or vanilla JS | |
@connectivity-js/react |
React adapter | |
@connectivity-js/devtools |
Framework-agnostic DevTools panel | |
@connectivity-js/react-devtools |
React DevTools panel |
- Declarative:
<Connectivity fallback={...}>for online/offline UI switching - Framework-agnostic: core has no framework dependency — works with vanilla JS, Vue, Svelte, and more
- Type-safe:
TInputandTResultfully inferred — no manual annotation - Auto-queue: offline actions are queued and flushed on reconnect
- Deduplication: rapid saves collapsed — only the latest reaches the server
- Retry: failed requests retried with configurable backoff
Note: The action queue is session-scoped (memory-backed). Pending actions are lost on page refresh or tab close. For durable delivery, implement server-side idempotency keys.
Works with vanilla JS/TS, Vue, Svelte, or any other environment.
import {
ConnectivityClient,
browserOnlineDetector,
heartbeatDetector,
actionOptions,
} from '@connectivity-js/core';
// 1. Create client and start detection
const client = new ConnectivityClient({
detectors: [
browserOnlineDetector(),
heartbeatDetector({ url: '/api/health' }),
],
gracePeriodMs: 3_000,
});
client.start();
// 2. Subscribe to connectivity state
client.subscribe((state, transition) => {
if (transition?.to === 'offline') {
document.getElementById('banner')?.classList.add('visible');
}
if (transition?.to === 'online') {
document.getElementById('banner')?.classList.remove('visible');
}
});
// 3. Define and execute actions
// request accepts any HTTP client — fetch, ky, axios, etc.
const save = actionOptions({
actionKey: 'save',
request: (input: { id: string; data: string }) => api.save(input),
dedupeKey: (input) => input.id,
whenOffline: 'queue',
});
const result = await client.execute(save, { id: '1', data: 'hello' });
if (result.enqueued) {
console.log('Offline — queued:', result.jobId);
} else {
console.log('Succeeded:', result.result);
}
// 4. Clean up
client.destroy();import {
ConnectivityProvider,
Connectivity,
browserOnlineDetector,
useConnectivity,
useAction,
} from '@connectivity-js/react';
// 1. Wrap your app
function App() {
return (
<ConnectivityProvider
detectors={[browserOnlineDetector()]}
gracePeriodMs={3_000}
>
<Connectivity fallback={<div>You're offline</div>} delayMs={3_000}>
<MyApp />
</Connectivity>
</ConnectivityProvider>
);
}
// 2. Display status
function StatusBadge() {
const { status } = useConnectivity();
if (status === 'offline') return <Badge>Offline</Badge>;
return <Badge>Online</Badge>;
}
// 3. Execute actions
function SaveButton({ id, data }: { id: string; data: string }) {
const { execute, pendingCount } = useAction({
actionKey: 'save',
request: (input: { id: string; data: string }) => api.save(input),
dedupeKey: (input) => input.id,
}, {
onSuccess: () => toast.success('Saved'),
onEnqueued: () => toast.info('Queued'),
});
return (
<button onClick={() => execute({ id, data })}>
Save {pendingCount > 0 && `(${pendingCount})`}
</button>
);
}We welcome contributions from everyone in the community. Read the detailed contribution guide.
Check out the docs for installation guides, usage examples, API reference, and more.
See LICENSE for more information.
MIT © minseong0324
