better-auth-offline

0.0.2 verified Sat Apr 25 auth: no javascript

An offline-first plugin for better-auth v1+ that caches auth API responses in IndexedDB, allowing apps to function without network connectivity. Released as v0.0.2 (latest) with patch-level updates. Automatically caches allowlisted GET endpoints (e.g., /get-session) and serves cached data when network fails. Includes configurable allowlist, custom storage adapters, online status tracking, and SSR support. Differentiates from generic caching libraries by being a drop-in plugin for better-auth, handling cache invalidation on sign-in/sign-out to prevent cross-user data leaks, and adding an X-Offline-Cache header for detection.

Common errors

error Cannot find module 'better-auth-offline' or its corresponding type declarations. ↓

cause Package not installed or TypeScript cannot resolve types.

fix

Install the package: npm install better-auth-offline. Ensure tsconfig.json includes moduleResolution: 'node' or 'bundler'.

error Error: offlinePlugin is not a function ↓

cause Importing default export incorrectly.

fix

Use named import: import { offlinePlugin } from 'better-auth-offline';

error TypeError: Cannot read properties of undefined (reading 'getSession') ↓

cause Plugin not included in createAuthClient config; auth client used without plugin.

fix

Add offlinePlugin() to the plugins array when creating auth client.

Warnings

deprecated The 'offlinePlugin' function may change its signature in future versions. ↓

fix Stay updated with releases; check changelog for breaking changes.

gotcha Cached responses include X-Offline-Cache header; do not rely on this header for security decisions. ↓

fix Use the header only for UI indicators (e.g., 'showing cached data').

gotcha Mutations like signIn and signOut are never cached; cache is cleared on these operations. ↓

fix Do not expect mutation responses to be served offline.

breaking Peer dependency better-auth >=1.0.0 required; incompatible with older versions. ↓

fix Ensure better-auth is at version 1.0.0 or higher.

Install

npm install better-auth-offline

yarn add better-auth-offline

pnpm add better-auth-offline

Imports

offlinePlugin

wrong

const offlinePlugin = require('better-auth-offline');

correct

import { offlinePlugin } from 'better-auth-offline';

Package is ESM-only; CommonJS require() will fail. TypeScript types are bundled.

OfflineOptions
wrong
```
import { OfflineOptions } from 'better-auth-offline';
```
correct
```
import type { OfflineOptions } from 'better-auth-offline';
```
OfflineOptions is a TypeScript type, not a runtime value. Use 'import type' to avoid runtime errors.
defaultAllowlist
```
import { defaultAllowlist } from 'better-auth-offline';
```
Exported for inspection if needed; typically not used directly.

Quickstart

Quick setup of better-auth-offline plugin with better-auth client, enabling automatic caching of auth API responses for offline use.

import { createAuthClient } from 'better-auth/react';
import { offlinePlugin } from 'better-auth-offline';

const authClient = createAuthClient({
  plugins: [offlinePlugin()],
});

// Usage: auth client will now cache GET responses like getSession.
const session = await authClient.getSession();