https://github.com/daniguardiola/browser-namespace
Cross-browser support for the "browser" namespace in browser extensions. Fully typed.
https://github.com/daniguardiola/browser-namespace
browser-extensions chrome chrome-extensions javascript typescript web-extensions
Last synced: 8 months ago
JSON representation
Cross-browser support for the "browser" namespace in browser extensions. Fully typed.
- Host: GitHub
- URL: https://github.com/daniguardiola/browser-namespace
- Owner: DaniGuardiola
- License: mit
- Created: 2023-12-12T17:21:39.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-02-28T22:52:34.000Z (over 2 years ago)
- Last Synced: 2025-10-10T08:14:43.888Z (8 months ago)
- Topics: browser-extensions, chrome, chrome-extensions, javascript, typescript, web-extensions
- Language: TypeScript
- Homepage:
- Size: 475 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# browser-namespace
Cross-browser support for the `browser` namespace in browser extensions. Fully typed.
```bash
npm i browser-namespace
```
```ts
import { browser } from "browser-namespace";
await browser.storage.local.set(data); // for example
```
## What this package is
Some browsers use the `browser` API namespace, while others use `chrome`. This package unifies both and provides a fully typed API.
It essentially does this:
```ts
export const browser: BrowserAPI = window.browser ?? window.chrome;
```
The types come from [`@types/webextension-polyfill`](https://www.npmjs.com/package/@types/webextension-polyfill).
## What this package is not
In contrast with [webextension-polyfill](https://github.com/mozilla/webextension-polyfill), which does a lot more, this package limits itself to providing a convenient, unified and fully typed namespace.
Support for specific features still depends on the browser and version. For this reason, types might be inaccurate. Performing feature detection is recommended.
## Chrome-specific namespace
If you need any Chrome-specific APIs, you can use the `chrome` namespace:
```ts
import { chrome } from "browser-namespace";
await chrome.debugger.sendCommand(/* ... */); // for example
```
The types are derived from [`@types/chrome`](https://www.npmjs.com/package/@types/chrome). The reason these types are copied instead of imported is because they declare `chrome` as a global variable, which might be unwanted. The version in this repo is patched to fix that.
Again, support for specific features depends on the browser and version.
## Types
The types for both browser and Chrome API namespaces can be imported directly.
There are types for the APIs themselves (corresponding to the types of the `browser` and `chrome` runtime objects):
```ts
import type { BrowserAPI, ChromeAPI } from "browser-namespace";
```
Additionally, the TypeScript namespace declarations are also exported:
```ts
import type { Browser, Chrome } from "browser-namespace";
```
These are useful to access certain types. Some examples:
- `Browser.Runtime.Port`, returned from `browser.runtime.connect`.
- `Chrome.debugger.Debuggee`, passed to `chrome.debugger.attach`.