This package, `better-auth-audit-logs`, provides a plug-in for the `better-auth` authentication library, designed to automatically capture and store authentication lifecycle events. It is currently at version 0.3.0 and appears to have a fairly active release cadence, with several minor versions released recently. Key features include automatic logging of auth events (like sign-in, sign-up, password changes) with associated metadata such as IP address and user agent, support for custom storage backends (Prisma, Drizzle, MongoDB examples are provided), and PII redaction capabilities. It differentiates itself by offering a zero-config setup for automatic event capture when integrated with `better-auth`, and exposing query endpoints for retrieving logs, including the ability to insert custom audit entries for non-auth related administrative actions. It relies on `better-auth` for its core functionality and `zod` for schema validation.
npm install better-auth-audit-logsVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to integrate the audit log plugin into a `better-auth` server instance and how to use its client-side capabilities to list existing logs and manually insert custom audit events.
If you are using a non-Prisma adapter and have an existing `audit_log` table, explicitly set `schema.auditLog.modelName: "audit_log"` in your plugin configuration to maintain compatibility.
Ensure your `better-auth` and `typescript` peer dependencies are up-to-date by running `npm install better-auth@latest typescript@^5`.
After installing the plugin, execute `npx @better-auth/cli generate` and then apply the generated migrations using your ORM's migration tool (e.g., `npx prisma migrate dev`).
Always use `import { auditLogClient } from 'better-auth-audit-logs/client';` for client-side functionality. Importing from the main package path will lead to bundling issues or runtime errors in browser environments.Ensure `better-auth-audit-logs` is installed and the client plugin is imported as `import { auditLogClient } from 'better-auth-audit-logs/client';`.Run `npx @better-auth/cli generate` to create the migration files, then apply them using your ORM's migration command (e.g., `npx prisma migrate dev`).
Ensure `auditLogClient()` is included in the `plugins` array when calling `createAuthClient({ plugins: [auditLogClient()] })`.Review the `insertAuditLog` call and ensure all required fields are present and conform to the expected schema (e.g., `action: 'some-action'`, `status: 'success'`, `severity: 'low'`).