From e802aa211f2808bfde176606b2905e3aaccb4ef7 Mon Sep 17 00:00:00 2001
From: Aaron <aaronklinker1@gmail.com>
Date: Sat, 18 Apr 2026 09:08:09 -0500
Subject: [PATCH] docs: Update `permissions` section with per-browser warning
 (#2284)

---
 docs/guide/essentials/config/manifest.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/docs/guide/essentials/config/manifest.md b/docs/guide/essentials/config/manifest.md
index 73811151..fcdfc3d2 100644
--- a/docs/guide/essentials/config/manifest.md
+++ b/docs/guide/essentials/config/manifest.md
@@ -200,6 +200,23 @@ export default defineConfig({
 });
 ```
 
+:::warning
+
+Different browsers support different permissions. You are responsible for passing only the permissions required for each browser:
+
+```ts
+export default defineConfig({
+  manifest: ({ browser }) => ({
+    permissions:
+      browser === 'chrome'
+        ? ['storage', 'favicon', 'declarativeNetRequest']
+        : ['storage', 'webRequest'],
+  }),
+});
+```
+
+:::
+
 ## Host Permissions
 
 > [Chrome docs](https://developer.chrome.com/docs/extensions/develop/concepts/declare-permissions#host-permissions)