View source for Building and Shipping a Safari Web Extension on macOS (Manifest V3, 2025 Edition): A Complete Step-by-Step Guide


<span id="quick-overview"></span>
= 1) Quick overview =

<blockquote>Quick version notes (today)

* '''Manifest V3 is supported in Safari''' (initially from Safari '''15.4+''') and remains supported in current Safari. ([https://webkit.org/blog/12445/new-webkit-features-in-safari-15-4/?utm_source=chatgpt.com WebKit])
* Latest '''Xcode''' release (stable): '''Xcode 26 (17A324)''' (Apple’s official releases page).
* Use the latest '''macOS''' and '''Safari''' available in '''System Settings → General → Software Update'''; verify your '''Safari''' version in '''Safari → About Safari'''. Apple’s docs describe Safari Web Extensions, how to run them, and how to distribute them via App Store Connect. ([https://developer.apple.com/documentation/SafariServices/safari-web-extensions?utm_source=chatgpt.com Apple Developer])
</blockquote>

'''What is a Safari Web Extension?''' A Safari Web Extension lets you add features to Safari using the same '''WebExtensions''' APIs used by Chrome, Firefox, and Edge. You write HTML/CSS/JS, plus a JSON file called a '''manifest''' that tells the browser what your extension can do. Safari ships an '''Xcode template''' that wraps your web extension inside a small '''Mac app''' so users can install it from the Mac App Store. ([https://developer.apple.com/documentation/safariservices/creating-a-safari-web-extension?utm_source=chatgpt.com Apple Developer])

'''How it differs from legacy Safari App Extensions''' Legacy “Safari App Extensions” were Mac-only and had different APIs. '''Safari Web Extensions''' use the cross-browser WebExtensions model and are the modern choice. (Apple still documents app extensions, but new projects should use Web Extensions.) ([https://developer.apple.com/documentation/safariservices/building-a-safari-app-extension?utm_source=chatgpt.com Apple Developer])

'''Typical use cases'''

* Toolbars and popups (quick actions)
* Content scripts that change pages (e.g., highlighting, note-taking)
* Context menus (right-click actions)
* DevTools panels (for debugging tools)
* Optional bridge to your Mac app (“native messaging”) ([https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/devtools_panels?utm_source=chatgpt.com MDN Web Docs])

'''How the pieces fit'''

<pre>+---------------- macOS host app (Xcode target) ----------------+
|  - Ships on App Store, installs the extension into Safari     |
|  - Can exchange messages with the extension (&quot;native messaging&quot;)|
|                                                                |
|  +---------- Safari Web Extension (Xcode target) -----------+  |
|  | manifest.json (MV3)                                       | |
|  |                                                           | |
|  |  Service worker (background.js)  &lt;--- listens for events  | |
|  |           ^                        (alarms, messages, etc)| |
|  |           |                                                | |
|  |  Popup (popup.html/js)   --- sendMessage ---&gt;             | |
|  |           |                                                | |
|  |  Options page (options.html/js) -- chrome.storage.* --&gt;   | |
|  |           |                                                | |
|  |  Content scripts (content.js) &lt;--- tabs.sendMessage ---   | |
|  |           |                                                | |
|  |  Context menus (via chrome.contextMenus)                  | |
|  +-----------------------------------------------------------+ |
+----------------------------------------------------------------+</pre>
'''Mini-glossary'''

* '''Manifest V3''': The current extension format. Uses a '''service worker''' (event-driven background script) instead of always-running pages. ([https://developer.chrome.com/docs/extensions/develop/migrate/what-is-mv3?utm_source=chatgpt.com Chrome for Developers])
* '''Content script''': JS that runs inside web pages you match.
* '''Host app''': The tiny Mac app Xcode creates to install/ship your extension.

'''Checklist'''

* ☐ Decide your feature (we’ll build a “reading highlight” toggle).
* ☐ You’re OK writing HTML/CSS/JS.
* ☐ You have a Mac that can run the latest macOS + Xcode.


-----

<span id="prerequisites-version-checks"></span>
= 2) Prerequisites &amp; version checks =

'''Minimums and “latest”'''

* '''Safari + MV3''': Safari '''15.4+''' supports MV3 + service workers. Use the newest Safari you have. ([https://webkit.org/blog/12445/new-webkit-features-in-safari-15-4/?utm_source=chatgpt.com WebKit])
* '''Xcode''': Install the latest Xcode (today: '''26 (17A324)''').
* '''Apple Developer Program''' (required to distribute on the Mac App Store, or to get Developer ID for notarized outside-store distribution). ([https://developer.apple.com/macos/distribution/?utm_source=chatgpt.com Apple Developer])

'''Install Xcode + Command Line Tools'''

<ol style="list-style-type: decimal;">
<li><p>Install '''Xcode''' from the Mac App Store (or developer.apple.com).</p></li>
<li><p>Install '''Command Line Tools''':</p>
<syntaxhighlight lang="bash">xcode-select --install</syntaxhighlight>
<p>(Apple’s docs also mention this approach.) ([https://developer.apple.com/library/archive/technotes/tn2339/_index.html?utm_source=chatgpt.com Apple Developer])</p></li></ol>

'''Enable the Develop menu in Safari'''

* Safari → '''Settings''' → '''Advanced''' → '''Show Develop menu in menu bar'''.
* For development with local builds, turn on '''Develop → Allow Unsigned Extensions'''. (Apple’s sample docs point to this exact menu.) ([https://docs.developer.apple.com/documentation/SafariServices/modernizing-safari-web-extensions?utm_source=chatgpt.com Apple Developer])

'''Confirm versions'''

<syntaxhighlight lang="bash"># Xcode:
xcodebuild -version

# macOS:
sw_vers

# Command Line Tools path (optional):
xcode-select -print-path</syntaxhighlight>
'''Checklist'''

* ☐ Xcode installed and opens
* ☐ Command Line Tools installed
* ☐ Safari’s '''Develop''' menu shown (+ Allow Unsigned Extensions during development)


-----

<span id="project-setup-in-xcode-from-scratch"></span>
= 3) Project setup in Xcode (from scratch) =

# '''Create the host app'''

* Open Xcode → '''File → New → Project… → App (macOS)'''.
* Product Name: <code>ReadingHighlight</code>
* Team: your developer team
* '''Bundle ID''': reverse-DNS like <code>com.example.readinghighlight</code>
* Interface: SwiftUI or AppKit (either works; we don’t need UI).
* Language: Swift

<ol start="2" style="list-style-type: decimal;">
<li>'''Add the extension target'''</li></ol>

* '''File → New → Target… → Safari Web Extension'''.
* Name: <code>ReadingHighlight Extension</code>
* Xcode will create a separate '''extension''' target and a shared folder with web files (manifest, scripts). Apple documents this flow. ([https://developer.apple.com/documentation/safariservices/creating-a-safari-web-extension?utm_source=chatgpt.com Apple Developer])

<ol start="3" style="list-style-type: decimal;">
<li>'''Signing &amp; capabilities'''</li></ol>

* In '''Signing &amp; Capabilities''' for both the app and the extension:
** Select your '''Team'''.
** Ensure '''App Sandbox''' is enabled for the host app if you plan to ship on the Mac App Store. ([https://developer.apple.com/documentation/xcode/configuring-the-macos-app-sandbox?utm_source=chatgpt.com Apple Developer])

<ol start="4" style="list-style-type: decimal;">
<li>'''Project structure (what you’ll see)'''</li></ol>

<pre>ReadingHighlight (Mac app)
└─ ReadingHighlight Extension (Safari Web Extension)
   ├─ manifest.json
   ├─ background.js       (service worker)
   ├─ content.js          (runs on pages)
   ├─ popup.html / popup.js
   ├─ options.html / options.js
   └─ icons/              (extension icon assets)</pre>
'''Checklist'''

* ☐ Mac app builds
* ☐ Extension target exists
* ☐ Team/signing selected; Sandbox on if shipping to App Store


-----

<span id="starter-extension-manifest-v3"></span>
= 4) Starter extension (Manifest V3) =

We’ll build the example feature you asked for: a '''toolbar popup''' that toggles a “reading highlight” mode on any page (paragraphs get a gentle background). There’s also a '''keyboard shortcut''' and a '''context menu''' (“Highlight selection”). We’ll save user settings in '''chrome.storage.sync'''. (Storage APIs and messaging are standardized across browsers.) ([https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/storage?utm_source=chatgpt.com MDN Web Docs])

<blockquote>Put these files into the '''extension''' folder in your Xcode project (the folder that already has a <code>manifest.json</code>).
</blockquote>
<span id="manifest.json-mv3"></span>
=== <code>manifest.json</code> (MV3) ===

<syntaxhighlight lang="json">{
  "manifest_version": 3,
  "name": "Reading Highlight",
  "description": "Toggle a gentle reading highlight on any page. Context-menu to highlight selection. Options to choose style.",
  "version": "1.0.0",
  "icons": {
    "16": "icons/icon-16.png",
    "32": "icons/icon-32.png",
    "48": "icons/icon-48.png",
    "128": "icons/icon-128.png"
  },

  "action": {
    "default_title": "Reading Highlight",
    "default_popup": "popup.html",
    "default_icon": {
      "16": "icons/icon-16.png",
      "32": "icons/icon-32.png"
    }
  },

  "permissions": [
    "storage",
    "tabs",
    "activeTab",
    "contextMenus"
  ],

  "host_permissions": [
    "<all_urls>",
    "https://api.quotable.io/*"
  ],

  "background": {
    "service_worker": "background.js",
    "type": "module"
  },

  "options_ui": {
    "page": "options.html",
    "open_in_tab": true
  },

  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["content.js"],
      "run_at": "document_idle"
    }
  ],

  "commands": {
    "toggle-highlight": {
      "suggested_key": {
        "default": "Alt+Shift+H",
        "mac": "Command+Shift+H"
      },
      "description": "Toggle reading highlight on the current page"
    }
  }
}</syntaxhighlight>
'''Notes'''

* '''host_permissions''' allow network calls (our sample fetch) and let scripts run on matching pages. (See MDN ''match patterns'' + ''host_permissions'' docs.) ([https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns?utm_source=chatgpt.com MDN Web Docs])
* '''commands''' defines our keyboard shortcut. ([https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/commands?utm_source=chatgpt.com MDN Web Docs])

<span id="background.js-service-worker"></span>
=== <code>background.js</code> (service worker) ===

<syntaxhighlight lang="js">/* background.js (MV3 service worker)
   - Creates a context menu
   - Routes messages between popup and content scripts
   - Handles keyboard command
   - Demonstrates a small network fetch
*/

chrome.runtime.onInstalled.addListener(() => {
  chrome.contextMenus.create({
    id: "highlight-selection",
    title: "Reading Highlight: Highlight selection",
    contexts: ["selection"]
  });
});

chrome.contextMenus.onClicked.addListener(async (info, tab) => {
  if (info.menuItemId === "highlight-selection" && tab?.id) {
    chrome.tabs.sendMessage(tab.id, { type: "APPLY_HIGHLIGHT_TO_SELECTION" });
  }
});

chrome.commands.onCommand.addListener(async (cmd) => {
  if (cmd === "toggle-highlight") {
    const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
    if (tab?.id) chrome.tabs.sendMessage(tab.id, { type: "TOGGLE_HIGHLIGHT" });
  }
});

// Example network request (requires host_permissions for the domain)
chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => {
  if (msg?.type === "GET_QUOTE") {
    fetch("https://api.quotable.io/random")
      .then(r => r.json())
      .then(data => sendResponse({ ok: true, quote: data.content }))
      .catch(err => sendResponse({ ok: false, error: String(err) }));
    return true; // keep the message channel open for async sendResponse
  }
});</syntaxhighlight>
''(Context menus and messaging APIs are standard WebExtensions.'') ([https://developer.chrome.com/docs/extensions/reference/api/contextMenus?utm_source=chatgpt.com Chrome for Developers])

=== <code>content.js</code> ===

<syntaxhighlight lang="js">/* content.js
   - Applies/removes a subtle highlight class on paragraphs
   - Optionally highlights current selection
   - Reads user style from chrome.storage.sync
*/

const STYLE_ID = "__reading_highlight_style__";
const HIGHLIGHT_CLASS = "reading-highlighted";

async function getUserStyle() {
  const { rh_style } = await chrome.storage.sync.get({
    rh_style: { color: "rgba(255, 250, 205, 0.6)", underline: false }
  });
  return rh_style;
}

function ensureStyleTag(style) {
  let tag = document.getElementById(STYLE_ID);
  const underline = style.underline ? "underline" : "none";
  if (!tag) {
    tag = document.createElement("style");
    tag.id = STYLE_ID;
    document.documentElement.appendChild(tag);
  }
  tag.textContent = `
    .${HIGHLIGHT_CLASS} p {
      background: ${style.color};
      transition: background 150ms ease-in-out;
    }
    .${HIGHLIGHT_CLASS} p:hover { filter: brightness(0.98); }
    .${HIGHLIGHT_CLASS} p span.rh-selection {
      background: ${style.color};
      text-decoration: ${underline};
    }
  `;
}

function toggleHighlight() {
  document.documentElement.classList.toggle(HIGHLIGHT_CLASS);
}

function highlightSelectionInline() {
  const sel = window.getSelection();
  if (!sel || sel.rangeCount === 0) return;

  const range = sel.getRangeAt(0);
  if (range.collapsed) return;

  const span = document.createElement("span");
  span.className = "rh-selection";
  range.surroundContents(span);
  sel.removeAllRanges();
}

chrome.runtime.onMessage.addListener(async (msg) => {
  if (msg?.type === "TOGGLE_HIGHLIGHT") {
    const style = await getUserStyle();
    ensureStyleTag(style);
    toggleHighlight();
  }
  if (msg?.type === "APPLY_HIGHLIGHT_TO_SELECTION") {
    const style = await getUserStyle();
    ensureStyleTag(style);
    highlightSelectionInline();
  }
});</syntaxhighlight>
=== <code>popup.html</code> ===

<syntaxhighlight lang="html"><!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Reading Highlight</title>
    <style>
      body { font: 14px -apple-system, system-ui, sans-serif; min-width: 240px; padding: 12px; }
      button { padding: 8px 10px; border-radius: 8px; border: 1px solid #ccc; cursor: pointer; }
      .row { display: flex; gap: 8px; align-items: center; }
      small { color: #555; display: block; margin-top: 8px; }
    </style>
  </head>
  <body>
    <div class="row">
      <button id="toggle">Toggle highlight</button>
      <button id="quote">Get quote</button>
    </div>
    <small>Tip: Keyboard shortcut Command+Shift+H (Mac) / Alt+Shift+H (others)</small>
    <script src="popup.js"></script>
  </body>
</html></syntaxhighlight>
=== <code>popup.js</code> ===

<syntaxhighlight lang="js">document.getElementById("toggle").addEventListener("click", async () => {
  const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
  if (tab?.id) chrome.tabs.sendMessage(tab.id, { type: "TOGGLE_HIGHLIGHT" });
});

document.getElementById("quote").addEventListener("click", async () => {
  const resp = await chrome.runtime.sendMessage({ type: "GET_QUOTE" });
  if (resp?.ok) alert("Quote: " + resp.quote);
  else alert("Failed to fetch quote.");
});</syntaxhighlight>
=== <code>options.html</code> ===

<syntaxhighlight lang="html"><!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Reading Highlight – Options</title>
    <style>
      body { font: 14px -apple-system, system-ui, sans-serif; padding: 16px; max-width: 560px; }
      label { display: block; margin: 12px 0 6px; }
      input[type="color"] { width: 64px; height: 32px; }
    </style>
  </head>
  <body>
    <h1>Reading Highlight – Options</h1>
    <label>Highlight color
      <input id="color" type="color" value="#fffacd" />
    </label>
    <label>
      <input id="underline" type="checkbox" />
      Underline highlighted selection
    </label>
    <button id="save">Save</button>
    <p id="status" role="status"></p>
    <script src="options.js"></script>
  </body>
</html></syntaxhighlight>
=== <code>options.js</code> ===

<syntaxhighlight lang="js">async function load() {
  const { rh_style } = await chrome.storage.sync.get({
    rh_style: { color: "rgba(255, 250, 205, 0.6)", underline: false }
  });

  // Convert rgba to hex if needed (simple fallback)
  const defaultHex = "#fffacd";
  const colorInput = document.getElementById("color");
  if (rh_style.color.startsWith("#")) colorInput.value = rh_style.color;
  else colorInput.value = defaultHex;

  document.getElementById("underline").checked = !!rh_style.underline;
}

async function save() {
  const color = document.getElementById("color").value;
  const underline = document.getElementById("underline").checked;

  try {
    await chrome.storage.sync.set({ rh_style: { color, underline } });
    const status = document.getElementById("status");
    status.textContent = "Saved!";
    setTimeout(() => (status.textContent = ""), 1200);
  } catch (e) {
    alert("Failed to save: " + e);
  }
}

document.getElementById("save").addEventListener("click", save);
load();</syntaxhighlight>
'''About icons''' Provide PNGs at '''16, 32, 48, 128''' (and optionally 256). Put them in <code>/icons</code> and reference them in <code>manifest.json</code>. Keep them square and readable at 16px.

'''Checklist'''

* ☐ All files created under the extension folder
* ☐ Manifest is MV3 (has <code>manifest_version: 3</code> + <code>background.service_worker</code>) ([https://webkit.org/blog/12445/new-webkit-features-in-safari-15-4/?utm_source=chatgpt.com WebKit])
* ☐ Icons referenced exist


-----

<span id="build-run"></span>
= 5) Build &amp; run =

# '''Build''' the app in Xcode (<code>⌘B</code>).
# '''Run''' the app (<code>⌘R</code>). The app launches; it primarily exists to install/host the extension.
# Open '''Safari → Settings → Extensions''' and '''enable''' “Reading Highlight Extension”.
# (If building unsigned for local dev) '''Develop → Allow Unsigned Extensions''' in Safari. ([https://docs.developer.apple.com/documentation/SafariServices/modernizing-safari-web-extensions?utm_source=chatgpt.com Apple Developer])

'''Reloading &amp; testing changes'''

* After code changes, build again in Xcode. Safari will pick up the new build; disable/enable once if needed. Apple documents the update loop. ([https://developer.apple.com/documentation/safariservices/running-your-safari-web-extension?utm_source=chatgpt.com Apple Developer])

'''Debugging (Web Inspector)'''

* Open '''Develop''' menu → '''Extensions''' → inspect your '''background service worker''' and any '''content scripts'''. (Safari Web Inspector is the dev tool to debug JS/DOM/Network.) ([https://developer.apple.com/library/archive/documentation/AppleApplications/Conceptual/Safari_Developer_Guide/Debugger/Debugger.html?utm_source=chatgpt.com Apple Developer])

'''Common pitfalls'''

* The extension won’t show? You probably forgot to '''enable''' it in Safari Settings.
* Console logs from background appear only when the '''service worker is running'''. It spins up on events (MV3 design). ([https://developer.chrome.com/docs/extensions/develop/migrate/what-is-mv3?utm_source=chatgpt.com Chrome for Developers])
* Permissions errors? Check <code>permissions</code> and <code>host_permissions</code>. ([https://developer.chrome.com/docs/extensions/develop/concepts/declare-permissions?utm_source=chatgpt.com Chrome for Developers])
* Caching: If a page doesn’t reflect your content script, reload the tab.

'''Checklist'''

* ☐ App runs
* ☐ Extension enabled in Safari
* ☐ You can toggle highlight from the popup and via shortcut


-----

<span id="expanding-the-extension-mini-tutorials"></span>
= 6) Expanding the extension (mini-tutorials) =

<span id="a-context-menus-already-added"></span>
== A) Context menus (already added) ==

We created one in <code>background.js</code> with <code>chrome.contextMenus.create</code> and wired its click handler. (Requires <code>&quot;contextMenus&quot;</code> permission.) ([https://developer.chrome.com/docs/extensions/reference/api/contextMenus?utm_source=chatgpt.com Chrome for Developers])

<span id="b-messaging-patterns"></span>
== B) Messaging patterns ==

* '''Popup → background''': <code>chrome.runtime.sendMessage({type: ...})</code>
* '''Background → content''': <code>chrome.tabs.sendMessage(tabId, { ... })</code>
* '''Content → background''': <code>chrome.runtime.sendMessage({ ... })</code> Docs: MDN/Chrome messaging. ([https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/runtime/sendMessage?utm_source=chatgpt.com MDN Web Docs])

<span id="c-storage-sync"></span>
== C) Storage &amp; sync ==

* We used <code>chrome.storage.sync</code>. It’s async and works in background/popup/content. (Handle errors.) ([https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/storage?utm_source=chatgpt.com MDN Web Docs])

<span id="d-network-requests"></span>
== D) Network requests ==

* Use <code>fetch</code> in the service worker or content script. Add matching '''host_permissions''' for the origin. (We added <code>https://api.quotable.io/*</code>.) ([https://developer.chrome.com/docs/extensions/develop/concepts/match-patterns?utm_source=chatgpt.com Chrome for Developers])

<span id="e-devtools-panel-optional"></span>
== E) DevTools panel (optional) ==

Add this to <code>manifest.json</code>:

<syntaxhighlight lang="json">"devtools_page": "devtools.html"</syntaxhighlight>
Create <code>devtools.html</code> + <code>devtools.js</code> and use <code>chrome.devtools.panels.create(...)</code> to add a panel. ([https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/devtools_panels?utm_source=chatgpt.com MDN Web Docs])

<span id="f-typescript-bundling-optional"></span>
== F) TypeScript + bundling (optional) ==

Keep your Xcode folder as the '''output''' of your bundler.

'''Suggested layout'''

<pre>/ext-src      (TS/JS source, Vite or webpack)
/ext-build    (bundled output; points into the Xcode extension folder)</pre>
'''Vite quick config (<code>vite.config.ts</code>)'''

<syntaxhighlight lang="ts">import { defineConfig } from "vite";

export default defineConfig({
  build: {
    outDir: "ext-build",
    rollupOptions: {
      input: {
        background: "ext-src/background.ts",
        content: "ext-src/content.ts",
        popup: "ext-src/popup.html",
        options: "ext-src/options.html"
      }
    }
  }
});</syntaxhighlight>
Then copy (or output directly) into the Xcode extension folder and update <code>manifest.json</code> to reference the '''built''' filenames.

<span id="g-native-app-bridge-advanced"></span>
== G) Native app bridge (advanced) ==

Safari supports a '''native messaging''' bridge between the extension and its containing Mac app. Add <code>&quot;nativeMessaging&quot;</code> to <code>permissions</code>. On the native side, Xcode generates a <code>SafariWebExtensionHandler.swift</code> for your extension; implement <code>beginRequest</code> to receive messages. ([https://developer.apple.com/documentation/safariservices/messaging-between-the-app-and-javascript-in-a-safari-web-extension?utm_source=chatgpt.com Apple Developer])

'''manifest.json (add permission)'''

<syntaxhighlight lang="json">"permissions": ["storage", "tabs", "activeTab", "contextMenus", "nativeMessaging"]</syntaxhighlight>
'''Swift (in the extension target) — <code>SafariWebExtensionHandler.swift</code>'''

<syntaxhighlight lang="swift">import SafariServices
import os

let log = Logger(subsystem: "com.example.readinghighlight", category: "Extension")

class SafariWebExtensionHandler: NSObject, NSExtensionRequestHandling {
  func beginRequest(with context: NSExtensionContext) {
    guard let item = context.inputItems.first as? NSExtensionItem,
          let message = item.userInfo?[SFExtensionMessageKey] as? [String: Any] else {
      context.completeRequest(returningItems: nil, completionHandler: nil)
      return
    }

    log.debug("Received native message: \(String(describing: message))")

    // Simple echo
    let reply = NSExtensionItem()
    reply.userInfo = [ SFExtensionMessageKey: ["ok": true, "echo": message] ]
    context.completeRequest(returningItems: [reply], completionHandler: nil)
  }
}</syntaxhighlight>
'''JS (service worker)'''

<syntaxhighlight lang="js">// Send a message to the native app:
async function pingNative(payload) {
  return await chrome.runtime.sendNativeMessage("com.example.readinghighlight", payload);
}</syntaxhighlight>
'''Notes'''

* You must keep the '''bundle IDs''' aligned (Xcode templates do this).
* Native messaging requires that permission; Apple documents the flow. ([https://developer.apple.com/documentation/safariservices/messaging-between-the-app-and-javascript-in-a-safari-web-extension?utm_source=chatgpt.com Apple Developer])

'''Checklist'''

* ☐ Context menu works
* ☐ Messages flow between popup, background, content
* ☐ Options persist via storage
* ☐ (Optional) DevTools panel appears
* ☐ (Advanced) Native messaging echo works


-----

<span id="testing"></span>
= 7) Testing =

'''Manual test checklist'''

* ☐ First run: extension enables successfully
* ☐ Popup toggle highlights paragraphs
* ☐ Keyboard shortcut toggles highlight
* ☐ Context menu highlights selection
* ☐ Options change color/underline, and persist after restart
* ☐ Network fetch shows a quote (and permissions are correct)

'''Automated ideas'''

* '''Lint''': ESLint for JS/TS.
* '''Unit tests''': functions in content/background can be factored and tested with Vitest/Jest.
* '''Integration''': Use '''WebDriver''' (<code>safaridriver</code>) to open pages and simulate clicks/keys (Enable via <code>safaridriver --enable</code> and Develop → '''Allow Remote Automation'''). ([https://developer.apple.com/documentation/safari-developer-tools/macos-enabling-webdriver?utm_source=chatgpt.com Apple Developer])

'''MV3 worker nuance in Safari''' Service workers are event-driven; open the Extension Background page in Web Inspector to see logs when it’s awake. (MV3 design detail.) ([https://developer.chrome.com/docs/extensions/develop/migrate/what-is-mv3?utm_source=chatgpt.com Chrome for Developers])


-----

<span id="packaging-signing-notarization-distribution"></span>
= 8) Packaging, signing, notarization &amp; distribution =

'''Ship on the Mac App Store'''

# In Xcode, set '''Release''' signing to '''Apple Distribution''' (your team).
# '''Archive''' your Mac app (Product → Archive), then '''Distribute''' to App Store Connect.
# Prepare your product page (icon, screenshots, description, permissions rationale, privacy policy). ([https://developer.apple.com/app-store/guidelines/?utm_source=chatgpt.com Apple Developer])

'''Package an existing web extension (CLI/web)'''

<ul>
<li><p>Apple provides a '''Safari web extension packager''' (CLI &amp; web) to package and distribute via App Store Connect.</p>
<ul>
<li><p>CLI:</p>
<syntaxhighlight lang="bash">xcrun safari-web-extension-packager /path/to/extension</syntaxhighlight></li>
<li><p>Web UI option is documented too. ([https://developer.apple.com/documentation/safariservices/packaging-a-web-extension-for-safari?utm_source=chatgpt.com Apple Developer])</p></li></ul>
</li></ul>

'''Outside the Mac App Store (direct distribution)'''

* Sign with '''Developer ID''' and '''notarize''' your app (required by Gatekeeper for outside-store apps). You can notarize via Xcode or <code>notarytool</code>. ([https://support.apple.com/guide/security/app-code-signing-process-sec3ad8e6e53/web?utm_source=chatgpt.com Apple Support])

'''App Sandbox'''

* App Store distribution requires '''App Sandbox'''; add only the entitlements you truly need. ([https://developer.apple.com/documentation/xcode/configuring-the-macos-app-sandbox?utm_source=chatgpt.com Apple Developer])

'''Checklist'''

* ☐ Archive succeeds and is signed
* ☐ App Store assets ready (icons, screenshots, text)
* ☐ Privacy policy URL ready
* ☐ If outside store: notarization is successful


-----

<span id="chromefirefox-portability"></span>
= 9) Chrome/Firefox portability =

'''Keep code portable'''

* Stick to standard '''WebExtensions''' APIs (runtime, storage, tabs, contextMenus, commands). Use MDN/Chrome docs as references. ([https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json?utm_source=chatgpt.com MDN Web Docs])

'''Convert an existing Chrome extension'''

<ul>
<li><p>Use Apple’s '''converter''' to bootstrap an Xcode project:</p>
<syntaxhighlight lang="bash">xcrun safari-web-extension-converter /path/to/your/chrome-extension</syntaxhighlight>
<p>The converter checks unsupported manifest keys and generates a project. ([https://developer.apple.com/news/?id=qiz0arxc&utm_source=chatgpt.com Apple Developer])</p></li></ul>

'''Safari quirks to note'''

* MV3 '''service workers''' are not persistent; design for short-lived wakeups (use events, alarms). ([https://developer.chrome.com/docs/extensions/develop/migrate/what-is-mv3?utm_source=chatgpt.com Chrome for Developers])
* Some APIs (e.g., blocking <code>webRequest</code> in MV3) behave differently or are restricted; plan for '''declarative''' or page-level strategies where needed. (Developers commonly hit “non-persistent background page cannot listen to webRequest events”.) ([https://github.com/mdn/browser-compat-data/issues/24571?utm_source=chatgpt.com GitHub])

'''Checklist'''

* ☐ Avoid Chrome-only APIs
* ☐ Watch for MV3 differences across browsers
* ☐ Use converter for existing projects


-----

<span id="troubleshooting-faq"></span>
= 10) Troubleshooting &amp; FAQ =

'''“Refused to load … due to Content Security Policy”'''

* Don’t inline JS in HTML; keep scripts in separate files and list them in the manifest. (MV3 CSP is strict.) See MDN manifest docs for keys. ([https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json?utm_source=chatgpt.com MDN Web Docs])

'''Signing failures during archive'''

* Verify '''Team''', provisioning profiles, and that both app + extension targets are signed consistently.

'''Service worker “not waking”'''

* Trigger via events (commands, context menu, messages). Open the background inspector from '''Develop → Extensions''' to see logs. (MV3 is event-driven.) ([https://developer.chrome.com/docs/extensions/develop/migrate/what-is-mv3?utm_source=chatgpt.com Chrome for Developers])

'''Missing permissions'''

* Add to <code>permissions</code> (for API access) and <code>host_permissions</code> (for site access). Changing them prompts users on update. ([https://developer.chrome.com/docs/extensions/develop/concepts/declare-permissions?utm_source=chatgpt.com Chrome for Developers])

'''Storage quota'''

* Keep sync data small; fall back to <code>chrome.storage.local</code> for larger data. (See MDN storage for concepts.) ([https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/storage?utm_source=chatgpt.com MDN Web Docs])

'''Debugging tips'''

* Use '''console.log''' generously. Inspect '''content scripts''' on the page via Web Inspector. ([https://developer.apple.com/library/archive/documentation/AppleApplications/Conceptual/Safari_Developer_Guide/Debugger/Debugger.html?utm_source=chatgpt.com Apple Developer])

'''Checklist'''

* ☐ Check Safari’s '''Extensions''' pane for enablement
* ☐ Use '''Develop''' menu inspectors
* ☐ Re-build after manifest changes


-----

<span id="security-privacy"></span>
= 11) Security &amp; privacy =

* '''Least privilege''': Request only the <code>permissions</code> and <code>host_permissions</code> you truly need. Users see permission prompts. ([https://developer.apple.com/documentation/safariservices/managing-safari-web-extension-permissions?utm_source=chatgpt.com Apple Developer])
* '''Data handling''': Don’t store sensitive data (passwords, tokens) in plain text. Be clear in your App Store metadata about what you collect and why. (Follow App Store guidelines.) ([https://developer.apple.com/app-store/guidelines/?utm_source=chatgpt.com Apple Developer])
* '''Network''': Pin domains in <code>host_permissions</code>; avoid <code>&lt;all_urls&gt;</code> unless necessary. ([https://developer.chrome.com/docs/extensions/develop/concepts/match-patterns?utm_source=chatgpt.com Chrome for Developers])

'''Checklist'''

* ☐ Permissions minimized
* ☐ Privacy policy published
* ☐ No secrets stored in extension code


-----

<span id="next-steps"></span>
= 12) Next steps =

* Polish '''Options UI''' (previews, reset defaults).
* Add an '''iCloud-style sync''' experience by sticking with <code>chrome.storage.sync</code> and testing across your devices running Safari. (Support varies by browser; verify behavior.) ([https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/storage?utm_source=chatgpt.com MDN Web Docs])
* Add more commands / keyboard shortcuts (and let users configure them). ([https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/commands?utm_source=chatgpt.com MDN Web Docs])
* Consider '''iOS/iPadOS''' support later—the same extension can ship in an iOS app bundle, but this guide focuses on macOS. (Apple documents multi-platform distribution.) ([https://developer.apple.com/documentation/SafariServices/safari-web-extensions?utm_source=chatgpt.com Apple Developer])


-----

<span id="official-docs-references-for-further-reading"></span>
== Official docs &amp; references (for further reading) ==

* '''Safari Web Extensions Overview / Create / Run / Distribute''' (Apple) ([https://developer.apple.com/documentation/SafariServices/safari-web-extensions?utm_source=chatgpt.com Apple Developer])
* '''Enable unsigned extensions for development''' (Apple sample note) ([https://docs.developer.apple.com/documentation/SafariServices/modernizing-safari-web-extensions?utm_source=chatgpt.com Apple Developer])
* '''MV3 support introduced''' (Safari 15.4) (WebKit blog + Apple release notes) ([https://webkit.org/blog/12445/new-webkit-features-in-safari-15-4/?utm_source=chatgpt.com WebKit])
* '''Manifest &amp; APIs''': MDN manifest.json, storage, commands, menus; Chrome’s messaging + contextMenus reference. ([https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json?utm_source=chatgpt.com MDN Web Docs])
* '''Match patterns &amp; host_permissions''' (MDN/Chrome) ([https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns?utm_source=chatgpt.com MDN Web Docs])
* '''Native messaging bridge''' (Apple) ([https://developer.apple.com/documentation/safariservices/messaging-between-the-app-and-javascript-in-a-safari-web-extension?utm_source=chatgpt.com Apple Developer])
* '''Package for App Store Connect''' – '''safari-web-extension-packager''' (Apple) ([https://developer.apple.com/documentation/safariservices/packaging-a-web-extension-for-safari?utm_source=chatgpt.com Apple Developer])
* '''Xcode latest release''' (Apple)
* '''Notarization &amp; distribution outside the store''' (Apple) ([https://developer.apple.com/documentation/security/notarizing-macos-software-before-distribution?utm_source=chatgpt.com Apple Developer])
* '''WebDriver (Safari) for automated testing''' (Apple + Selenium) ([https://developer.apple.com/documentation/safari-developer-tools/macos-enabling-webdriver?utm_source=chatgpt.com Apple Developer])


-----

<span id="section-by-section-checklists-recap"></span>
== Section-by-section checklists (recap) ==

* '''Overview''': understand pieces ✔️
* '''Prereqs''': Xcode + CLT installed; Develop menu on ✔️
* '''Setup''': macOS app + Safari Web Extension target; signing ✔️
* '''Starter MV3''': manifest + background + content + popup + options + icons ✔️
* '''Build &amp; run''': enable in Safari; use Web Inspector ✔️
* '''Features''': context menu, messaging, storage, fetch, DevTools, TS, native bridge ✔️
* '''Testing''': manual list + WebDriver notes ✔️
* '''Ship''': sign, archive, package, notarize; App Store assets ✔️
* '''Portability''': use standard APIs; converter; watch MV3 quirks ✔️
* '''Troubleshooting''': CSP, signing, worker lifecycles, permissions ✔️
* '''Security &amp; privacy''': least privilege; clear disclosures ✔️
* '''Next steps''': polish, shortcuts, multi-platform ✔️


-----