context-detect

Overview

Suppose you're a piece of code running in some context of some browser's javascript engine, and you need to determine what your API options are. This won't tell you your specific options, but it will tell you what type of environment (context) you're saddled with. That's its sole purpose, to tell you in which browser and context you are currently executing.

The library is designed to work in main, isolated, background, extension page, action popup, worker, and shared worker contexts. Not for use in server-side contexts such as Node.

Installation

npm

npm install @rshaker/context-detect

unpkg

<script src="https://unpkg.com/@rshaker/context-detect/dist/contextDetect.js"></script>

Usage

Node

import { detectContext, getBrowserName } from "@rshaker/context-detect";

console.info("detectContext", detectContext()); // "main-world"
console.info("getBrowserName", getBrowserName()); // "chrome"
console.info("navigator.userAgent", navigator.userAgent);

Browser

<head>
    <script src="../../dist/contextDetect.js"></script>
</head>

<body>
    Open the console to see the results
    <script>
        console.info("detectContext", contextDetect.detectContext());
        console.info("getBrowserName", contextDetect.getBrowserName());
        console.info("navigator.userAgent", navigator.userAgent);
    </script>
</body>

Building

The library built by this project is intended for use by web extension developers, and is best integrated into projects via the npm package manager.

# Clone the repo
git clone [email protected]:rshaker/context-detect.git
cd context-detect

# Requires node v22.12.0+
nvm use
npm install

# Hermetic browser installation requires `PLAYWRIGHT_BROWSERS_PATH=0`
npm run playwright:install-browsers

# Build the library (dist/), in development or production mode
npm run build:dev
npm run build:prod

# Build the test extensions (webext/chrome, webext/edge, webext/firefox)
npm run build:webext:dev

# Run the Playwright suite against the development build
npm run test

# Build the npm tarball and check it
npm run pack

# Check the public API against the previous release
npm run test:compat

Documentation

Full API documentation (generated with TypeDoc) is available under the docs directory. Auto-generated docs contains class, interface, and type details for all modules. npm run docs writes it to docs/dist/.

Releasing

Development happens on main. A release is a vX.Y.Z tag; pushing it makes a GitHub Release with the npm tarball attached and the matching section of CHANGELOG.md as notes, and npm run release:publish then publishes that same tarball to npm. docs/releasing.md describes the branches, versions, tags and the release sequence; docs/release-checks.md is the manual checklist run before a release is tagged.

Basic detection logic

| Browser | Service Worker? | Extension Protocol? | getViews Popup? | Extension API? | Result Context | |--------------|-----------------|--------------------|-----------------|---------------|-----------------------| | Chromium | Yes | - | - | - | Background Worker | | Chromium | No | Yes | Yes | - | Popup (Action) | | Chromium | No | Yes | No | - | Extension Page | | Chromium | No | No | - | Yes | Isolated World | | Chromium | No | No | - | No | Main World | | Firefox | Yes | - | - | - | Background Worker | | Firefox | No | Yes | Yes | - | Popup (Action) | | Firefox | No | Yes | No | - | Extension/Background | | Firefox | No | No | - | Yes | Isolated World | | Firefox | No | No | - | No | Main World | | Safari | - | Yes | - | - | Extension Page | | Safari | - | No | - | - | Web Page |

Prerequisites

• Node.js (22.12.0+)
• npm (10.9.0+)

License

MIT