Browser Lifecycle

Typed browser session lifecycle — visibility, focus, connectivity, idle detection, cross-tab sync, and plugins in one headless API.

Install

npm install @jayoncode/browser-lifecycle

pnpm add @jayoncode/browser-lifecycle

yarn add @jayoncode/browser-lifecycle

Example: pause work when the tab is hidden

import { createBrowserLifecycle } from "@jayoncode/browser-lifecycle";

const lifecycle = createBrowserLifecycle({ autoStart: true });

lifecycle.on("page:hidden", () => {
  pauseMedia();
  flushTelemetry();
});

lifecycle.on("page:visible", () => {
  resumeMedia();
});

// Read consolidated state at any time
const { visibility, focus, connectivity } = lifecycle.getSnapshot();

// Teardown on route unmount or app shutdown
await lifecycle.dispose();

One instance per tab replaces scattered document / window listeners with typed events and a readonly snapshot.

Verify event ordering →

Problem → approach

Typical pain	Browser Lifecycle
document, window, and navigator listeners scattered across features	One createBrowserLifecycle() session with typed on() handlers
Tab visibility, focus, and connectivity each wired differently	Modules normalize signals; getSnapshot() exposes consolidated state
SSR crashes or silent no-ops when APIs are missing	Capability detection and SSR-safe defaults before modules attach

Overview

createBrowserLifecycle() orchestrates browser signals through a module pipeline. Consumers subscribe to events or poll getSnapshot(); modules (visibility, focus, connectivity, idle, cross-tab) compose behind a single session boundary.

Concern	API surface
Lifecycle	start(), dispose(), phase events
Signals	on(event, handler), onEvent(handler)
State	getSnapshot() — readonly session state
Extension	Plugin hooks, module configuration
Diagnostics	getRuntimeDiagnostics() for development

Designed for SSR-safe capability detection and framework-agnostic integration (React, Vue, vanilla, etc.).

Documentation path

Foundation

#	Guide	Topics	Playground
1	Tutorial	Install, session, subscribe, dispose	Dashboard
2	Core concepts	Session, snapshot, events, modules	State

Core modules

#	Guide	Topics	Playground
3	Visibility	Page Visibility API	Visibility
4	Events	Subscription model	Events
5	Session core	Phases, startup order	Lifecycle

Configuration and extension

#	Guide	Topics	Playground
6	Core infrastructure	Config, capabilities, SSR	Configuration
7	Usage guide	Production patterns	Developer tools
8	Plugins	Module registration	Plugins

Package fit

Requirement	Module / event
Pause background work on tab hide	page:hidden / page:visible
React to window focus	window:focus / window:blur
Offline-aware UI	connectivity:*
Idle timeout / autosave triggers	Idle module
Cross-tab coordination	Cross-tab sync
SSR / capability guards	Core infrastructure

Reference

Resource	Link
API (TypeDoc)	/packages/browser-lifecycle/api/
Framework examples	/packages/browser-lifecycle/examples/
Best practices	/packages/browser-lifecycle/best-practices/
Patterns	/packages/browser-lifecycle/patterns/
FAQ	/packages/browser-lifecycle/faq/
Playground guide	/packages/browser-lifecycle/playground/playground

Version

Current npm version: v0.2.0 (@jayoncode/browser-lifecycle). See Migration and Changelog for release history.