Registry / security / better-auth-idle-timeout

better-auth-idle-timeout

library1.0.1jsnpmunverified

Automatically expires and revokes Better Auth sessions after a configurable period of user inactivity. Current stable version is 1.0.1, released in 2025. The plugin tracks activity via a global request hook, throttles database writes (default 60s cooldown) to prevent write-locking on rapid requests, and deletes the session on timeout. It requires TypeScript 5+ and Better Auth ^1.6.11. Key differentiator: lightweight, zero-dependency plugin model vs custom middleware solutions; tightly integrated with Better Auth's session lifecycle.

security

npm install better-auth-idle-timeout

package ↗

INSTALL

IMPORT

SIG · BETTER-AUTH-IDLE-T

better-auth-idle-timeout

securityjavascriptv1.0.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

idleTimeout

✓ import { idleTimeout } from 'better-auth-idle-timeout'

✗ import idleTimeout from 'better-auth-idle-timeout'

This is a named export, not a default export.

idleTimeout

✓ const { idleTimeout } = require('better-auth-idle-timeout')

✗ const idleTimeout = require('better-auth-idle-timeout')

CJS require must destructure the named export.

IdleTimeoutOptions (type)

✓ import type { IdleTimeoutOptions } from 'better-auth-idle-timeout'

✗ import { IdleTimeoutOptions } from 'better-auth-idle-timeout'

This is a TypeScript type – use 'import type' for isolated type imports.

Add idle timeout plugin to Better Auth server config with defaults, then run database migration.

import { betterAuth } from 'better-auth' import { idleTimeout } from 'better-auth-idle-timeout' export const auth = betterAuth({ // ... your existing config (database, email, etc.) plugins: [ idleTimeout({ timeoutMinutes: 15, // default updateThrottleSeconds: 60 // default }) ] }) // After configuring, run: // npx better-auth migrate

Debug

Known issues

gotchaSession deletion is permanent – timed-out sessions are deleted from the database, not just marked expired.

fix

Ensure your auth system handles deleted sessions gracefully (e.g., triggers session creation on next login).

affects: >=1.0.0

gotchaActivity tracking relies on signed session cookies – requests without a valid session cookie are ignored.

fix

Ensure Better Auth's session cookie is configured and signed correctly.

affects: >=1.0.0

deprecatedNone known – this is a very early release (v1.0.1). Check for future breaking changes.

fix

Monitor the GitHub repository for updates.

affects: >=1.0.0

gotchaWrite-throttling means lastActivityAt may lag by up to updateThrottleSeconds from actual user activity.

fix

Set updateThrottleSeconds to 0 to disable throttling, but be aware of increased database load.

affects: >=1.0.0

Errors

Common errors & fixes

Cannot find module 'better-auth-idle-timeout'

Package not installed or not in node_modules.

fix

Run 'npm install better-auth-idle-timeout' (or bun/pnpm equivalent).

APIError: Session expired due to inactivity

User's session idle time exceeded timeoutMinutes.

fix

User needs to re-authenticate. Increase timeoutMinutes if too aggressive.

Property 'idleTimeout' does not exist on type 'BetterAuthOptions'

Plugin not added to the plugins array, or TypeScript not recognizing the plugin declaration.

fix

Ensure 'idleTimeout()' is included in the 'plugins' array. Check that your tsconfig includes the plugin's types (automatic with npm).

Error: Database error: column 'lastActivityAt' of relation 'session' does not exist

Database schema not migrated after adding the plugin.

fix

Run 'npx better-auth migrate' or manually add the column: ALTER TABLE session ADD COLUMN lastActivityAt TIMESTAMP;

Upgrade

Version history

1.0.1latest on npm

Audit

Dependencies

better-authrequiredPeer dependency – core auth framework required for plugin to function.

typescriptoptionalPeer dependency – version 5+ required for type definitions.

Agent activity

24 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

packagebetter-auth-idle-timeout ↗