Chrome Extension Permissions Quickstart — Developer Guide

3 min read

Permissions Quickstart

Overview

@theluckystrike/webext-permissions simplifies Chrome’s runtime permissions API with human-readable descriptions, batch operations, and proper error handling.

Install

npm install @theluckystrike/webext-permissions

Background: Manifest V3 Permissions

Brief explainer on required vs optional permissions in manifest.json. This library helps with optional runtime permissions.

{
  "permissions": ["storage"],
  "optional_permissions": ["tabs", "bookmarks", "history"]
}

Step 1: Check If a Permission Is Granted

Single — checkPermission(permission)

import { checkPermission } from "@theluckystrike/webext-permissions";

const result = await checkPermission("tabs");
// { permission: "tabs", granted: boolean, description: "Read information about open tabs" }

Returns PermissionResult: { permission: string; granted: boolean; description: string }

Batch — checkPermissions(permissions)

import { checkPermissions } from "@theluckystrike/webext-permissions";

const results = await checkPermissions(["tabs", "bookmarks", "history"]);

Step 2: Request Permissions

Single — requestPermission(permission)

import { requestPermission } from "@theluckystrike/webext-permissions";

// MUST be called from a user gesture
document.getElementById("grant-tabs")?.addEventListener("click", async () => {
  const result = await requestPermission("tabs");
  // { granted: boolean; error?: string }
});

Returns RequestResult: { granted: boolean; error?: string }

Batch — requestPermissions(permissions)

import { requestPermissions } from "@theluckystrike/webext-permissions";

const result = await requestPermissions(["tabs", "bookmarks"]);

Chrome shows ONE prompt for all. User declines = granted: false.

Step 3: Remove Permissions

import { removePermission } from "@theluckystrike/webext-permissions";

const removed = await removePermission("tabs"); // boolean

Step 4: List Granted Permissions

import { getGrantedPermissions } from "@theluckystrike/webext-permissions";

const granted = await getGrantedPermissions();
// PermissionResult[] with granted: true

Uses chrome.permissions.getAll() under the hood.

Step 5: Human-Readable Descriptions

describePermission(permission)

import { describePermission } from "@theluckystrike/webext-permissions";

describePermission("tabs");       // "Read information about open tabs"
describePermission("bookmarks");  // "Read and modify bookmarks"
describePermission("unknown");    // 'Use the "unknown" API' (fallback)

listPermissions()

import { listPermissions } from "@theluckystrike/webext-permissions";

const all = listPermissions();
// PermissionResult[] for all 50+ known Chrome permissions

PERMISSION_DESCRIPTIONS

import { PERMISSION_DESCRIPTIONS } from "@theluckystrike/webext-permissions";

// Record<string, string> with 50+ entries
PERMISSION_DESCRIPTIONS.tabs      // "Read information about open tabs"
PERMISSION_DESCRIPTIONS.cookies   // "Read and modify cookies"
PERMISSION_DESCRIPTIONS.history   // "Read and modify browsing history"

Step 6: Complete Example — Permission Manager UI

Full example: render a list of optional permissions with Grant/Revoke buttons using checkPermissions, requestPermission, removePermission, and describePermission.

API Reference Summary

Function Returns
checkPermission(perm) Promise<PermissionResult>
checkPermissions(perms) Promise<PermissionResult[]>
requestPermission(perm) Promise<RequestResult>
requestPermissions(perms) Promise<RequestResult>
removePermission(perm) Promise<boolean>
getGrantedPermissions() Promise<PermissionResult[]>
describePermission(perm) string
listPermissions() PermissionResult[]
PERMISSION_DESCRIPTIONS Record<string, string>

Next Steps

Part of the Chrome Extension Guide by theluckystrike. Built at zovo.one.

No previous article
No next article