browser-extension-capabilities

Zero-dependency library for analyzing browser extension capabilities from manifest files

A lightweight, zero-dependency TypeScript library for analyzing browser extension manifests and extracting their capabilities. Useful for extension development tools, analysis tools, and browser extension marketplaces.

What are Browser Extension Capabilities?

Browser extension capabilities represent the functional interfaces and execution environments that an extension can utilize. These are the different ways an extension can interact with the browser, web pages, and users. Each capability corresponds to specific manifest fields and defines where and how the extension's code can run.

For example:

Background Capability: Allows the extension to run persistent code in the background
Content Scripts Capability: Enables the extension to interact with web page content
Popup Capability: Provides a user interface through browser toolbar buttons
Options Capability: Offers configuration pages for user settings

Features

Comprehensive Detection: Detects all major browser extension capabilities and interfaces
User-Friendly Output: Returns descriptive capability objects with explanations
Cross-Browser Support: Works with Chrome, Firefox, Edge, and other Chromium-based browsers

Installation

npm install browser-extension-capabilities

Usage

import {
  getExtensionCapabilities,
  getExtensionCapabilitiesAsync,
  analyzeExtensionManifest,
} from 'browser-extension-capabilities'

// 1) Sync (path)
const caps1 = getExtensionCapabilities('./path/to/extension/manifest.json', {
  includeFields: true,
  normalizeNames: true,
  includeCompatibility: true,
})

// 2) Async (path)
const caps2 = await getExtensionCapabilitiesAsync(
  './path/to/extension/manifest.json',
  { strict: true },
)

// 3) Direct object
import * as fs from 'fs'
const manifest = JSON.parse(fs.readFileSync('./path/to/manifest.json', 'utf8'))
const caps3 = analyzeExtensionManifest(manifest, { normalizeNames: true })

console.log(caps1)
// [
//   { capability: 'background', id: 'background', description: 'Background service worker or page for persistent functionality', fields: ['background.service_worker'] },
//   { capability: 'content_scripts', id: 'content_scripts', description: 'Content scripts that run on web pages to interact with page content', fields: ['content_scripts'] },
//   { capability: 'popup', id: 'action_popup', description: 'Toolbar popup UI', fields: ['action.default_popup'] },
// ]

Supported Capabilities

Capability	Description	Manifest Fields
background	Background service worker or page for persistent functionality	`background.page`, `background.scripts`, `background.service_worker`
content_scripts	Content scripts that run on web pages to interact with page content	`content_scripts`
popup	Toolbar popup UI	`action.default_popup`, `browser_action.default_popup`, `page_action.default_popup`
sidebar	Side panel UI	`side_panel.default_path`, `sidebar_action.default_panel`
devtools	Developer tools panel	`devtools_page`
options	Options page for user configuration	`options_ui.page`, `options_page`
newtab	New tab page override	`chrome_url_overrides.newtab`
bookmarks	Custom bookmarks page replacement	`chrome_url_overrides.bookmarks`
history	History page override	`chrome_url_overrides.history`
sandbox	Sandboxed pages for isolated execution	`sandbox.pages`
web_resources	Web-accessible resources exposed to web pages	`web_accessible_resources`
omnibox	Omnibox keyword integration	`omnibox.keyword`
commands	Keyboard shortcuts and command actions	`commands`
settings_homepage	Browser settings override: homepage	`chrome_settings_overrides.homepage`
settings_search_provider	Browser settings override: search provider	`chrome_settings_overrides.search_provider`
settings_startup_pages	Browser settings override: startup pages	`chrome_settings_overrides.startup_pages`
declarative_net_request	Declarative network request rules	`declarative_net_request.rule_resources`
tts_engine	Text-to-speech engine	`tts_engine.voices`

API Reference

`getExtensionCapabilities(manifestPath: string, options?: GetCapabilitiesOptions): ExtensionCapability[]`

Analyzes a browser extension manifest from a file path and returns an array of capability objects.

Parameters

manifestPath (string): Direct path to the extension's manifest.json file
options (optional): See Options below

Returns

ExtensionCapability[]: Array of capability objects with capability, description, and optionally id and fields when enabled via options

Example

import { getExtensionCapabilities } from 'browser-extension-capabilities'

const capabilities = getExtensionCapabilities('./my-extension/manifest.json', {
  includeFields: true,
  normalizeNames: true,
})

capabilities.forEach(({ capability, id, description, fields }) => {
  console.log(`${id ?? capability}: ${description}`, fields ?? [])
})

`getExtensionCapabilitiesAsync(manifestPath: string, options?: GetCapabilitiesOptions): Promise<ExtensionCapability[]>`

Async variant of the path-based API. Respects the same options and error handling semantics.

`analyzeExtensionManifest(manifest: ExtensionManifest, options?: GetCapabilitiesOptions): ExtensionCapability[]`

Analyzes a manifest object directly without reading from disk.

Types

interface ExtensionCapability {
  capability: string
  description: string
  id?: string // normalized manifest-aligned name (e.g., "web_accessible_resources")
  fields?: string[] // manifest fields that triggered this capability
  compatibility?: {
    safari?: boolean
    notes?: string
    docs?: string
  }
}

interface GetCapabilitiesOptions {
  strict?: boolean // throw on missing/invalid manifest when true
  includeFields?: boolean // include manifest field paths in each capability
  normalizeNames?: boolean // include normalized id aligned with manifest naming
  includeCompatibility?: boolean // include Safari-focused compatibility metadata per capability
}

Compatibility metadata (Safari-focused)

When includeCompatibility: true is set, each capability may include a compatibility object with conservative Safari support and notes.

Example output snippet:

{
  "capability": "sidebar",
  "description": "Side panel UI",
  "id": "sidebar",
  "compatibility": {
    "safari": false,
    "notes": "Chromium uses side_panel; Firefox uses sidebar_action. Safari does not provide an equivalent sidebar UI API.",
    "docs": "https://developer.mozilla.org/docs/Mozilla/Add-ons/WebExtensions/user_interface"
  }
}

Error Handling

The library gracefully handles various error scenarios:

Missing manifest file: Returns [{ capability: "manifest", description: "Basic extension manifest configuration" }] (or throws when strict: true)
Invalid JSON: Returns fallback capability with error logging (or throws when strict: true)
Malformed manifest: Attempts to extract available capabilities and falls back gracefully