Better Auth Audit

1.0.2 verified Sat Apr 25 auth: no javascript

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.

Common errors

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

cause Forgetting to import the plugin's named export correctly or using an older version where the export was different.

fix

Update to >=1.0.0 and use named import: import { auditLog } from 'better-auth-audit';

error Error: Plugin 'auditLog' is not a valid Better Auth plugin. ↓

cause The plugin may not be properly initialized or the version of better-auth is incompatible.

fix

Check that better-auth version is ^1.2.0 and that you passed the plugin inside the plugins array.

error ZodError: [ { code: 'invalid_type', expected: 'string', received: 'undefined' } ] ↓

cause Missing required fields in a custom audit event or misconfigured options.

fix

Ensure all required fields (actorId, action, resource) are provided when emitting custom events.

Warnings

breaking Version 1.0.0 renamed 'eventTypes' option to 'events'. Old option is ignored. ↓

fix Use 'events' instead of 'eventTypes' in plugin options.

deprecated The 'memory' storage backend is deprecated and will be removed in v2.0. ↓

fix Migrate to 'database' storage with a persistent adapter.

gotcha 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' ↓

fix Review your excluded paths and ensure authentication callback paths are not excluded.

gotcha The audit log schema uses Zod, so you must install zod even if you don't directly import it. ↓

fix Ensure zod is in your dependencies.

Install

npm install better-auth-audit

yarn add better-auth-audit

pnpm add better-auth-audit

Imports

auditLog

wrong

const auditLog = require('better-auth-audit')

correct

import { auditLog } from 'better-auth-audit'

ESM-only; named export.

AuditLogOptions

wrong

import { AuditLogOptions } from 'better-auth-audit'

correct

import type { AuditLogOptions } from 'better-auth-audit'

TypeScript only; use import type for type-only.

getAuditLogs

wrong

import { auditLog } from 'better-auth-audit'

correct

import { getAuditLogs } from 'better-auth-audit'

Different function for querying logs.

Quickstart

Configures the audit log plugin with Better Auth, then fetches audit logs for a specific user.

import { betterAuth } from 'better-auth';
import { auditLog } from 'better-auth-audit';

export const auth = betterAuth({
  plugins: [
    auditLog({
      storage: 'database', // or 'memory'
      events: ['signIn', 'signUp', 'signOut', 'passwordReset', 'adminAction'],
      excludePaths: ['/api/health']
    })
  ]
});

// Later, fetch logs
const { getAuditLogs } = await import('better-auth-audit');
const logs = await getAuditLogs({ userId: 'user_123', limit: 10 });