{"id":18150,"library":"better-auth-audit","title":"Better Auth Audit","description":"Audit log plugin for Better Auth, providing comprehensive tracking of authentication events such as sign-ins, sign-ups, password changes, and admin actions. Version 1.0.2, released with weekly cadence, supports automatic event capture, configurable storage backends, and query APIs. Differentiators include zero-config setup, typed audit events via Zod schemas, and seamless integration with Better Auth's middleware. Requires better-auth >=1.2.0 and zod >=3.0.0. Fully typed with TypeScript declarations.","status":"active","version":"1.0.2","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","typescript"],"install":[{"cmd":"npm install better-auth-audit","lang":"bash","label":"npm"},{"cmd":"yarn add better-auth-audit","lang":"bash","label":"yarn"},{"cmd":"pnpm add better-auth-audit","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency: core auth framework","package":"better-auth","optional":false},{"reason":"peer dependency: schema validation for audit events","package":"zod","optional":false}],"imports":[{"note":"ESM-only; named export.","wrong":"const auditLog = require('better-auth-audit')","symbol":"auditLog","correct":"import { auditLog } from 'better-auth-audit'"},{"note":"TypeScript only; use import type for type-only.","wrong":"import { AuditLogOptions } from 'better-auth-audit'","symbol":"AuditLogOptions","correct":"import type { AuditLogOptions } from 'better-auth-audit'"},{"note":"Different function for querying logs.","wrong":"import { auditLog } from 'better-auth-audit'","symbol":"getAuditLogs","correct":"import { getAuditLogs } from 'better-auth-audit'"}],"quickstart":{"code":"import { betterAuth } from 'better-auth';\nimport { auditLog } from 'better-auth-audit';\n\nexport const auth = betterAuth({\n  plugins: [\n    auditLog({\n      storage: 'database', // or 'memory'\n      events: ['signIn', 'signUp', 'signOut', 'passwordReset', 'adminAction'],\n      excludePaths: ['/api/health']\n    })\n  ]\n});\n\n// Later, fetch logs\nconst { getAuditLogs } = await import('better-auth-audit');\nconst logs = await getAuditLogs({ userId: 'user_123', limit: 10 });","lang":"typescript","description":"Configures the audit log plugin with Better Auth, then fetches audit logs for a specific user."},"warnings":[{"fix":"Use 'events' instead of 'eventTypes' in plugin options.","message":"Version 1.0.0 renamed 'eventTypes' option to 'events'. Old option is ignored.","severity":"breaking","affected_versions":">=1.0.0 <1.0.0"},{"fix":"Migrate to 'database' storage with a persistent adapter.","message":"The 'memory' storage backend is deprecated and will be removed in v2.0.","severity":"deprecated","affected_versions":">=1.0.0 <2.0.0"},{"fix":"Review your excluded paths and ensure authentication callback paths are not excluded.","message":"If you exclude paths using excludePaths, the plugin will not emit events for those paths. Common mistake: forgetting to include paths like '/api/auth/callback'","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Ensure zod is in your dependencies.","message":"The audit log schema uses Zod, so you must install zod even if you don't directly import it.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Update to >=1.0.0 and use named import: import { auditLog } from 'better-auth-audit';","cause":"Forgetting to import the plugin's named export correctly or using an older version where the export was different.","error":"TypeError: Cannot read properties of undefined (reading 'auditLog')"},{"fix":"Check that better-auth version is ^1.2.0 and that you passed the plugin inside the plugins array.","cause":"The plugin may not be properly initialized or the version of better-auth is incompatible.","error":"Error: Plugin 'auditLog' is not a valid Better Auth plugin."},{"fix":"Ensure all required fields (actorId, action, resource) are provided when emitting custom events.","cause":"Missing required fields in a custom audit event or misconfigured options.","error":"ZodError: [ { code: 'invalid_type', expected: 'string', received: 'undefined' } ]"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}