react-session-timer-alert-lib

A simple and reusable React component that displays a session timeout warning modal to the user. It allows the user to either extend their session or log out.

This library monitors user activity and session timers across multiple browser tabs.

Installation

To install the library, you can use npm or yarn:

npm install react-session-timer-alert-lib
# or
yarn add react-session-timer-alert-lib

Usage

The package includes a ready-to-use UI: no extra CSS, Tailwind, or theme setup is required. Import the SessionTimeoutModal component and place it in your main application layout file (e.g., App.tsx). It will be invisible until the session is about to expire, then show a centered modal with a countdown and two actions.

Basic Usage

import { SessionTimeoutModal } from 'react-session-timer-alert-lib';

const App = () => {
  const handleTimeout = () => {
    alert('Session expired!');
  };

  return (
    <div>
      <h1>My Application</h1>
      <SessionTimeoutModal onTimeout={handleTimeout} />
    </div>
  );
};

Advanced Usage with Custom Text and Events

You can customize the text and the events that reset the timer by passing additional props.

import { SessionTimeoutModal } from 'react-session-timer-alert-lib';

const App = () => {
  const handleTimeout = () => {
    alert('Session expired!');
  };

  return (
    <div>
      <h1>My Application</h1>
      <SessionTimeoutModal
        onTimeout={handleTimeout}
        idleTimeMs={5 * 60 * 1000}
        warningDurationMs={2 * 60 * 1000}
        title="Session Expiring"
        bodyText={
          <>
            Your session is about to end.
            <br />
            You will be logged out automatically.
          </>
        }
        signOutButtonText="Logout Now"
        keepSignedInButtonText="Keep Session"
        events={['click', 'scroll']}
      />
    </div>
  );
};

Styling

All of the CSS needed for the modal is baked into the component via inline styles. Consumers of the package do not need to install Tailwind, add a stylesheet, or configure any CSS toolchain – just render SessionTimeoutModal and it will look like the screenshot shown in the example.

Component Props

| Prop | Type | Default | Description | |---------------------|----------------|------------------------|-----------------------------------------------------------------------------| | idleTimeMs | number | 30 * 60 * 1000 (30m) | Total duration of inactivity in milliseconds before the session expires. | | warningDurationMs | number | 5 * 60 * 1000 (5m) | The time in milliseconds before expiration when the warning modal appears. | | onTimeout | () => void | Required | A callback function that is executed when the session finally times out. | | events | string[] | ['mousemove', 'mousedown', 'keydown', 'scroll', 'click', 'touchstart'] | An array of DOM event names that should reset the session timer. | | title | React.ReactNode | 'Your session is about to expire!' | The title of the modal. | | bodyText | React.ReactNode | undefined | The body text of the modal. If not provided, a default message will be shown. | | signOutButtonText | React.ReactNode | 'No, Sign me out' | The text for the sign-out button. | | keepSignedInButtonText | React.ReactNode | 'Yes, Keep me signed in' | The text for the keep-signed-in button. |

For Library Developers

Instructions for building, debugging, and publishing the library.

Project Structure

• src/: Contains the source code.
  • hooks/useSessionTimeout.ts: The core logic for tracking session time and user activity.
  • SessionTimeoutModal.tsx: The React component for the modal UI.
  • index.ts: The main entry point that exports the public API.
• dist/: The compiled output directory (generated after build).

How to Build

To compile the TypeScript source code into distributable JavaScript files, run the build script:

npm run build

This command uses tsup to bundle the code into both CommonJS (.js) and ESModule (.mjs) formats, and it also generates the necessary TypeScript declaration files (.d.ts). The output will be placed in the dist folder.

How to Debug

For local development and debugging, you can link this library to another local project.

1. Start the watcher:

   In the react-session-timer-alert-lib directory, run the development script. This will watch for file changes and automatically rebuild the library.

   npm run dev

2. Link the library:

   In a separate terminal, still in the react-session-timer-alert-lib directory, create a global link.

   npm link

3. Use it in another project:

   Navigate to the root directory of the application where you want to test the library and link it.

   # Example: cd ../my-test-app

npm link react-session-timer-alert-lib ```

Now, your test application will use your local build of the library. Any changes you make in the library's source code will be automatically recompiled and reflected in your test application (you may need to refresh the browser).

How to Publish

To publish a new version of the package to the npm registry:

1. Login to npm:

   If you are not already logged in, you will need to authenticate with npm.

   npm login

2. Update the version:

   Before publishing, it's good practice to update the version number in package.json according to Semantic Versioning (SemVer).

   # Examples:

npm version patch # 1.0.0 -> 1.0.1 npm version minor # 1.0.0 -> 1.1.0 npm version major # 1.0.0 -> 2.0.0 ```

3. Build the package:

   Ensure you have the latest changes built.

   npm run build

4. Publish:

   Run the publish command. The prepublishOnly script in package.json will automatically run a build one last time to ensure the latest code is published.

   npm publish