IdleSession

Seamless, multi-tab session orchestration for the modern web.

IdleSession is a high-performance, dependency-free ES Module for managing session lifecycles in modern web applications. It eliminates the "timer wars" common in multi-tab environments and is a native-first successor to jquery-idletimer.

Live Demo

Try it in your browser: thorst.github.io/idle-session

Key Features

• Synchronized Multi-Tab State — Uses the native BroadcastChannel API to ensure activity in any open tab resets the session timer globally across all instances.
• Native-First Architecture — Zero dependencies, zero jQuery, zero bloat. Built for 2026 standards.
• Performance-Optimized — Passive, throttled event listeners ensure zero UI jank and zero timer spam during high-frequency events like mousemove.
• Resilient Heartbeats — Heartbeats only fire when the user is active. Transient network failures are swallowed; only 401/403 responses trigger logout.
• Session Warning Dialog — Automatically injects an accessible <dialog> element before timeout (configurable via warningBefore), letting users extend their session.
• Network Awareness — Differentiates between transient network failures and hard authorization failures (401/403).

Installation

npm install idle-session

Or via CDN (no install needed):

<script type="module">
  import { IdleSession } from 'https://cdn.jsdelivr.net/npm/idle-session/IdleSession.js';
</script>

Quick Start

import { IdleSession } from 'idle-session';

const session = new IdleSession({
    timeout: 10 * 60 * 1000, // 10 minutes
    onHeartbeat: async () => {
        try {
            const res = await fetch('/api/keep-alive', { method: 'POST' });
            if (res.status === 401 || res.status === 403) throw new Error('Unauthorized');
        } catch (err) {
            if (err.message === 'Unauthorized') throw err;
            // Swallow network errors — session stays active, retries next interval.
        }
    },
    onLogout: () => window.location.href = '/login?reason=session_expired'
});

Configuration Reference

All options are optional. Pass any combination to the constructor to override the defaults.

| Option | Type | Default | Description | | :--- | :--- | :--- | :--- | | timeout | number | 900000 (15m) | Idle time in ms before onLogout is triggered. | | heartbeatInterval | number | 300000 (5m) | How often (ms) to ping the server when activity is detected. | | warningBefore | number | 60000 (1m) | How many ms before timeout to show the warning. Set to 0 to disable. | | channelName | string | 'session_sync' | BroadcastChannel name for cross-tab sync. Override if you run multiple independent apps on the same origin. | | onHeartbeat | async function | POSTs to /api/keep-alive | Custom async function to ping your backend. Throwing triggers logout. | | onLogout | function | Redirects to /logout | Callback executed when the session expires or is forcibly revoked. | | onWarning | function | Built-in <dialog> | Called instead of the built-in warning modal when the session is about to expire. Receives { extend, logout } — call extend() to reset the session, logout() to force-end it. If omitted, the default styled <dialog> is used. |

Examples

Basic Setup

Use the defaults for zero-config protection:

const session = new IdleSession();

Custom API Client

Override onHeartbeat to use a custom HTTP client or send auth headers:

const session = new IdleSession({
    onHeartbeat: async () => {
        const response = await apiClient.post('/auth/keep-alive', {
            sessionID: localStorage.getItem('sid')
        });
        // Throwing here triggers automatic logout across all tabs
        if (response.status !== 200) throw new Error('Session terminated by server');
    }
});

Custom Logout Behavior

Override onLogout to run cleanup before redirecting:

const session = new IdleSession({
    onLogout: async () => {
        await analytics.track('session_expired');
        localStorage.clear();
        window.location.href = '/login?reason=timeout';
    }
});

Custom Warning UI

Provide onWarning to replace the built-in dialog with your own UI. The callback receives { extend, logout }:

const session = new IdleSession({
    onWarning: ({ extend, logout }) => {
        // Show your own modal, toast, banner — anything.
        myModal.open({
            onStayLoggedIn: extend,   // resets the idle timer
            onLogOut:       logout,   // ends the session immediately
        });
    }
});

The default built-in dialog is used only when onWarning is not provided.

Bootstrap Modal

If your app already uses Bootstrap, pass onWarning and wire it to a Bootstrap modal:

<!-- In your HTML -->
<div class="modal fade" id="sessionModal" tabindex="-1" aria-labelledby="sessionModalLabel" aria-hidden="true">
  <div class="modal-dialog">
    <div class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title" id="sessionModalLabel">Session Expiring</h5>
      </div>
      <div class="modal-body">
        Your session is about to expire due to inactivity.
      </div>
      <div class="modal-footer">
        <button type="button" class="btn btn-secondary" id="sessionLogout">Log Out</button>
        <button type="button" class="btn btn-primary" id="sessionExtend">Stay Logged In</button>
      </div>
    </div>
  </div>
</div>

const modalEl = document.getElementById('sessionModal');
const bsModal = new bootstrap.Modal(modalEl, { backdrop: 'static', keyboard: false });

document.getElementById('sessionExtend').addEventListener('click', () => bsModal.hide());
document.getElementById('sessionLogout').addEventListener('click', () => bsModal.hide());

const session = new IdleSession({
    onWarning: ({ extend, logout }) => {
        document.getElementById('sessionExtend').onclick = () => { extend(); bsModal.hide(); };
        document.getElementById('sessionLogout').onclick = () => { logout(); bsModal.hide(); };
        bsModal.show();
    }
});

Tailwind + Headless UI / Alpine.js Modal

If you use Tailwind CSS, you can build a modal inline and toggle it via a flag. This example uses Alpine.js, a common lightweight companion to Tailwind:

<!-- In your HTML -->
<div x-data="sessionWarning()" x-show="open" class="fixed inset-0 z-50 flex items-center justify-center bg-black/50">
  <div class="bg-white rounded-2xl shadow-xl p-6 w-full max-w-sm mx-4">
    <h2 class="text-lg font-semibold text-gray-900">Session Expiring</h2>
    <p class="mt-2 text-sm text-gray-500">Your session is about to expire due to inactivity.</p>
    <div class="mt-6 flex justify-end gap-3">
      <button @click="doLogout()" class="px-4 py-2 text-sm text-gray-600 hover:text-gray-900">Log Out</button>
      <button @click="doExtend()" class="px-4 py-2 text-sm bg-indigo-600 text-white rounded-lg hover:bg-indigo-700">Stay Logged In</button>
    </div>
  </div>
</div>

// Alpine.js component — exposes open/extend/logout to the template above
function sessionWarning() {
    return {
        open: false,
        _extend: null,
        _logout: null,
        doExtend() { this.open = false; this._extend?.(); },
        doLogout() { this.open = false; this._logout?.(); },
        show({ extend, logout }) {
            this._extend = extend;
            this._logout = logout;
            this.open = true;
        }
    };
}

// Grab the Alpine component instance after Alpine has initialized
document.addEventListener('alpine:initialized', () => {
    const warningComponent = Alpine.$data(document.querySelector('[x-data="sessionWarning()"]'));

    const session = new IdleSession({
        onWarning: ({ extend, logout }) => warningComponent.show({ extend, logout })
    });
});

Styling the Built-in Dialog

If you omit onWarning, the default <dialog> can be themed without touching the library — just set CSS custom properties anywhere in your stylesheet:

/* Example: match a dark application theme */
:root {
    --idle-bg:          #1c1f26;
    --idle-color:       #e8eaf0;
    --idle-heading:     #f59e0b;
    --idle-muted:       #9ca3af;
    --idle-border:      #2e3340;
    --idle-accent:      #6366f1;
    --idle-accent-text: #ffffff;
}

| Property | Controls | Default | | :--- | :--- | :--- | | --idle-bg | Dialog background | #ffffff | | --idle-color | Body text | #111827 | | --idle-heading | Heading color | inherits --idle-color | | --idle-muted | Subtext and secondary button | #6b7280 | | --idle-border | Dialog border and button borders | #e5e7eb | | --idle-accent | Primary button background | #2563eb | | --idle-accent-text | Primary button text | #ffffff |

Cleanup / SPA Route Changes

Call destroy() to remove all event listeners, clear timers, close the BroadcastChannel, and remove any open warning dialog. Essential when unmounting the session in a single-page application:

// React / Vue / etc.
onUnmount(() => session.destroy());

// Or when reinitializing with new config
session.destroy();
session = new IdleSession({ timeout: newTimeout });

Network Resilience

The module treats the network as unreliable. Transient network failures inside onHeartbeat should be caught and swallowed — only throw on hard auth failures (401/403) so that connectivity blips do not end the session. The default onHeartbeat already does this. If you provide a custom onHeartbeat, follow the same pattern:

onHeartbeat: async () => {
    try {
        const res = await fetch('/api/keep-alive', { method: 'POST' });
        if (res.status === 401 || res.status === 403) throw new Error('Unauthorized');
    } catch (err) {
        if (err.message === 'Unauthorized') throw err;
        // Network errors are swallowed — session stays active, retries next interval.
    }
}

A 401 or 403 response is treated as a hard termination signal, triggering an immediate and synchronized logout across all open tabs.

Browser Compatibility

| Feature | Chrome | Firefox | Safari | Edge | | :--- | :---: | :---: | :---: | :---: | | BroadcastChannel | v54+ | v38+ | v15.4+ | v79+ | | <dialog> element | v37+ | v98+ | v15.4+ | v79+ |

Testing

This library uses a two-tier testing strategy.

Prerequisites

After cloning the repository, run the following before any test or coverage commands:

npm install              # install dev dependencies
npx playwright install   # download Playwright browser binaries (required once per machine)

To verify the dev server runs correctly before testing:

npm run dev   # starts Vite at http://localhost:5173 — open in a browser to confirm

Unit & Integration Tests

Runs all core logic through every branch — including error handling and multi-tab state synchronization — using Playwright.

npm test

For a detailed coverage report:

npm run coverage
# View the generated coverage/ folder

Smoke Tests

Designed to run against a staging or pre-production environment. Confirms the module initializes correctly, that your Content Security Policy permits BroadcastChannel and fetch, and that there are no race conditions with your DOM.

npx playwright test tests/smoke.spec.js

License

MIT