Safari Extension Installation Guide

This document introduces how to install the All API Hub extension in the Safari browser.

Differences at a Glance

  • No paid Apple Developer Program account: You can still build and enable the extension on your own Mac using Xcode, suitable for development, debugging, or personal use. Generally, it cannot be distributed to regular users. Locally built versions that are not officially distributed might require enabling Allow Unsigned Extensions in the Safari Developer menu.
  • With a paid Apple Developer Program account: You can perform official signing and distribute through TestFlight / App Store, suitable for installation by other users. The installation experience will also be closer to that of ordinary Safari extensions.

System Requirements

  • macOS 11.0 Big Sur or later
  • Safari 14.0 or later
  • Xcode 13.0 or later (for building)

Installation Methods

Safari currently recommends using the following two methods:

  1. Build from source code yourself, then run with Xcode
  2. Download the pre-built Safari Xcode bundle from GitHub Releases, unzip, and open directly with Xcode

Recommendation If you just want to get it running on your Mac as quickly as possible, prioritize "Method Two: Download Release Bundle". If you need to modify code, debug, or verify local changes, use "Method One: Build from Source Code".

Method One: Build from Source Code and Install

1. Get Source Code and Build Safari Artifacts

# Clone or download the project source code
git clone https://github.com/qixing-jk/all-api-hub.git
cd all-api-hub

# Install dependencies
pnpm install

# Build the Safari version
pnpm run build:safari

After the build is complete, the compiled artifacts will be output to .output/safari-mv2/.

2. Use Safari Web Extension Converter to Generate Xcode Project

xcrun safari-web-extension-converter .output/safari-mv2/

If you want to customize the output directory, App name, and Bundle Identifier, you can also use:

xcrun safari-web-extension-converter .output/safari-mv2/ \
  --project-location /path/to/all-api-hub-safari-project \
  --app-name "All API Hub" \
  --bundle-identifier "io.github.qixingjk.allapihub"

This step will generate an Xcode project to host the Safari extension.

3. Build and Run in Xcode

  1. Open the newly generated Xcode project.
  2. Ensure your Mac is selected as the target device.
  3. Click Product > Run, or press Cmd + R.
  4. On the first run, Xcode will ask you to handle signing. Without a paid account, you can usually use Personal Team for local debugging.
  5. After a successful build, Safari will prompt you to enable the extension.

4. Enable the Extension in Safari

  1. Open Safari.
  2. Click Safari > Settings in the menu bar.
  3. If it's a locally built version not officially distributed, go to the Develop menu and enable Allow Unsigned Extensions.
  4. Open the Extensions tab.
  5. Find All API Hub and enable it.
  6. Grant permissions as needed.

Method Two: Download Safari Xcode Bundle from GitHub Releases

1. Download the Correct Safari Asset

Go to the Releases page and download a file named similarly to this:

all-api-hub-<version>-safari-xcode-bundle.zip

For example:

all-api-hub-3.29.0-safari-xcode-bundle.zip

Do not just download all-api-hub-<version>-safari.zip.

WHY: all-api-hub-<version>-safari.zip is just the Safari compiled artifact itself and does not contain a runnable Xcode project. What is suitable for direct unzipping and opening with Xcode is safari-xcode-bundle.zip.

2. What You'll See After Unzipping

After unzipping all-api-hub-<version>-safari-xcode-bundle.zip, the directory will typically contain:

  • all-api-hub-<version>-safari.zip
  • safari-mv2/
  • The Xcode project directory generated by the converter

This design aims to place the "compiled Safari extension files" and the "Xcode project" within the same bundle, preventing the project from reporting missing files when opened.

3. Open the Bundle's Project Directly with Xcode

  1. In the unzipped directory, find the Xcode project.
  2. Double-click the project file, or open it with Xcode.
  3. Ensure your Mac is selected as the target device.
  4. Click Product > Run.
  5. After Safari prompts you, enable the extension in Safari > Settings > Extensions.

4. When You Might Need Other Files in the Bundle

  • safari-mv2/: The compiled extension directory referenced by the Xcode project.
  • all-api-hub-<version>-safari.zip: For archiving, comparison, or redistributing the compiled artifacts.

In most cases, you only need to unzip the entire bundle and should not move any single directory out of it.

Method Three: Temporary Debugging (Development Use Only)

Some macOS/Safari versions support temporary debugging loading, but it's not suitable for official installation or distribution:

pnpm run build:safari

Then enable developer mode in Safari:

  1. Open Safari > Settings > Advanced.
  2. Check "Show Develop menu in menu bar".
  3. In the menu bar, click Develop > Allow Unsigned Extensions.
  4. In Safari > Settings > Extensions, enable the extension.

Note If this method is not available, revert to the Xcode process above. Official releases should still use signed distribution.

Development Mode Debugging

Development Build

# Development mode build (hot reloading)
pnpm run dev -- -b safari

Debugging the Extension

  1. Debugging Background Scripts/Popups:

    • In Safari, right-click the extension icon.
    • Select Inspect or open the Web Inspector.

  2. Debugging Content Scripts:

    • On any webpage, right-click the page.
    • Select Inspect Element.
    • View extension-related logs in the console.

Frequently Asked Questions

Q: Why does Safari require special handling?

A: Safari extensions need to be packaged as macOS applications for installation and distribution, which differs from Chrome/Edge/Firefox directly installing .crx or .xpi files.

Q: What's the difference between having a developer account and not having one?

A:

  • No account: You can build and use it locally, but it's more for development, debugging, or personal use. It generally cannot be directly distributed to regular users.
  • With an account: You can perform official signing and distribute through TestFlight / App Store, suitable for long-term maintenance and official releases.

Q: Can I install it directly like Chrome?

A: No. Safari cannot be directly unpacked and loaded for official installation like Chrome. Local usage typically goes through Xcode, while official distribution goes through TestFlight / App Store.

Q: What should I do if I encounter errors during the build?

A: Ensure:

  • Xcode command-line tools are installed: xcode-select --install
  • Xcode license has been accepted: sudo xcodebuild -license accept
  • Node.js version is >= 18

Q: Are there functional differences between the Safari version and the Chrome version?

A: The basic functionalities are identical. However, due to some limitations in the Safari WebExtensions API, certain features might have slight differences:

  • The sidePanel API is not available in Safari (popups are used instead).
  • Some permission request methods might differ.

Q: How do I update the extension?

A:

  • If you installed from source: Rebuild the Safari artifacts and rerun the Xcode project.
  • If you downloaded the bundle from Releases: Download the new safari-xcode-bundle.zip, unzip it, and open the new Xcode project to run.

Uninstall

  1. Open Safari.
  2. Go to Safari > Settings > Extensions.
  3. Uncheck All API Hub.
  4. Delete the macOS application generated by Xcode.

Resources

If you have any issues, please report them in GitHub Issues.

Last Updated:
Contributors: github-actions[bot], qixing-jk