Skip to main content

Documentation Index

Fetch the complete documentation index at: https://extension.js.org/llms.txt

Use this file to discover all available pages before exploring further.

Keep your extension capable without asking for more privilege than the feature requires. Extension.js compiles and validates your extension, but the browser still enforces permissions, host_permissions, and optional_* fields from manifest.json. Good permission design improves trust and reduces issues during store review.

​
Permission strategy

NeedPrefer
Core API access required for the extension to functionpermissions
Host access required on installhost_permissions
Capability you can request lateroptional_permissions
Domain access that only some users needoptional_host_permissions

​
Common patterns

​
Background-driven feature

Use permissions for the browser APIs you need and add only the host patterns required by the feature: 
{
  "manifest_version": 3,
  "permissions": ["storage", "tabs", "scripting"],
  "host_permissions": ["https://example.com/*"]
}

​
Optional capability

If the first-run experience does not require a feature, keep it optional: 
{
  "manifest_version": 3,
  "permissions": ["storage"],
  "optional_permissions": ["notifications"],
  "optional_host_permissions": ["https://api.example.com/*"]
}

​
Practical rules

  • Ask for API permissions only when the feature truly needs them.
  • Keep host_permissions scoped to the smallest working set of origins.
  • Prefer optional permissions for secondary or premium features.
  • Re-audit permissions whenever you add background actions, content-script injection, or remote API calls.

​
Permission design by feature type

FeatureUsually involves
Content-script enhancement on a known sitehost_permissions for that site, sometimes scripting
Popup or options UI onlyoften no host permissions at all
Programmatic injectionscripting plus matching host permissions
Cross-tab workflowstabs and sometimes activeTab
Persisted settingsstorage
Notifications or badgesnotifications, action-related manifest fields

​
Common mistakes

  • Using broad wildcards like <all_urls> when you only need one or two origins.
  • Mixing host_permissions into a feature that could instead use a narrower user-triggered workflow.
  • Forgetting that content scripts, web-accessible resources, and script injection via chrome.scripting all have different security implications.
  • Documenting permissions in feature docs without explaining why each permission exists.

​
Review checklist

  1. List every user-facing feature.
  2. Map each feature to the exact API and host permissions it needs.
  3. Move non-core permissions to optional permissions where possible.
  4. Remove stale permissions left over from old experiments.
  5. Re-test install prompts and browser-store expectations after changes.

​
Next steps