Registry / auth-security / better-auth-offline

better-auth-offline

library0.0.2jsnpmunverified

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.

auth-security web-framework

npm install better-auth-offline

github ↗package ↗

INSTALL

IMPORT

SIG · BETTER-AUTH-OFFLIN

better-auth-offline

auth-securityjavascriptv0.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

offlinePlugin

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

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

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

OfflineOptions

✓ import type { OfflineOptions } from 'better-auth-offline';

✗ import { 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.

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();

Debug

Known issues

deprecatedThe 'offlinePlugin' function may change its signature in future versions.

fix

Stay updated with releases; check changelog for breaking changes.

affects: >=0.0.1 <0.1.0

gotchaCached 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').

affects: >=0.0.1

gotchaMutations like signIn and signOut are never cached; cache is cleared on these operations.

fix

Do not expect mutation responses to be served offline.

affects: >=0.0.1

breakingPeer dependency better-auth >=1.0.0 required; incompatible with older versions.

fix

Ensure better-auth is at version 1.0.0 or higher.

affects: >=0.0.1

Errors

Common errors & fixes

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

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: offlinePlugin is not a function

Importing default export incorrectly.

fix

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

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

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

fix

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

Upgrade

Version history

0.0.2latest on npm

Audit

Dependencies

better-authrequiredpeer dependency required for plugin integration

Agent activity

27 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/MrLightful/better-auth-offline ↗

packagehttps://www.npmjs.com/package/better-auth-offline ↗