{"id":18154,"library":"better-auth-offline","title":"better-auth-offline","description":"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.","status":"active","version":"0.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/MrLightful/better-auth-offline","tags":["javascript","better-auth","offline","offline-first","local","local-first","pwa","cache","service-worker","typescript"],"install":[{"cmd":"npm install better-auth-offline","lang":"bash","label":"npm"},{"cmd":"yarn add better-auth-offline","lang":"bash","label":"yarn"},{"cmd":"pnpm add better-auth-offline","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency required for plugin integration","package":"better-auth","optional":false}],"imports":[{"note":"Package is ESM-only; CommonJS require() will fail. TypeScript types are bundled.","wrong":"const offlinePlugin = require('better-auth-offline');","symbol":"offlinePlugin","correct":"import { offlinePlugin } from 'better-auth-offline';"},{"note":"OfflineOptions is a TypeScript type, not a runtime value. Use 'import type' to avoid runtime errors.","wrong":"import { OfflineOptions } from 'better-auth-offline';","symbol":"OfflineOptions","correct":"import type { OfflineOptions } from 'better-auth-offline';"},{"note":"Exported for inspection if needed; typically not used directly.","wrong":"","symbol":"defaultAllowlist","correct":"import { defaultAllowlist } from 'better-auth-offline';"}],"quickstart":{"code":"import { createAuthClient } from 'better-auth/react';\nimport { offlinePlugin } from 'better-auth-offline';\n\nconst authClient = createAuthClient({\n  plugins: [offlinePlugin()],\n});\n\n// Usage: auth client will now cache GET responses like getSession.\nconst session = await authClient.getSession();","lang":"typescript","description":"Quick setup of better-auth-offline plugin with better-auth client, enabling automatic caching of auth API responses for offline use."},"warnings":[{"fix":"Stay updated with releases; check changelog for breaking changes.","message":"The 'offlinePlugin' function may change its signature in future versions.","severity":"deprecated","affected_versions":">=0.0.1 <0.1.0"},{"fix":"Use the header only for UI indicators (e.g., 'showing cached data').","message":"Cached responses include X-Offline-Cache header; do not rely on this header for security decisions.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Do not expect mutation responses to be served offline.","message":"Mutations like signIn and signOut are never cached; cache is cleared on these operations.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Ensure better-auth is at version 1.0.0 or higher.","message":"Peer dependency better-auth >=1.0.0 required; incompatible with older versions.","severity":"breaking","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Install the package: npm install better-auth-offline. Ensure tsconfig.json includes moduleResolution: 'node' or 'bundler'.","cause":"Package not installed or TypeScript cannot resolve types.","error":"Cannot find module 'better-auth-offline' or its corresponding type declarations."},{"fix":"Use named import: import { offlinePlugin } from 'better-auth-offline';","cause":"Importing default export incorrectly.","error":"Error: offlinePlugin is not a function"},{"fix":"Add offlinePlugin() to the plugins array when creating auth client.","cause":"Plugin not included in createAuthClient config; auth client used without plugin.","error":"TypeError: Cannot read properties of undefined (reading 'getSession')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}