Safari Extension Installation Guide

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

Understanding the Differences First

• Without a paid Apple Developer Program account: You can still build and enable the extension on your own Mac using Xcode. This is suitable for development, debugging, or personal use. Generally, you cannot distribute it to ordinary users. For locally built versions not officially distributed, you might need to enable Allow Unsigned Extensions in Safari's Developer menu.
• With a paid Apple Developer Program account: You can create a formal signature and distribute it via TestFlight / App Store. This is suitable for installation by other users and provides an installation experience closer to 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

There are two installation methods:

1. Download the pre-built Safari Xcode project zip from the latest GitHub Release, then open it directly with Xcode after extraction.
2. Build from source code yourself, then run it with Xcode.

Method 1: Download Safari Bundle from Latest GitHub Release

The Safari bundle will be uploaded to the latest version's Release page:

• Latest Release

1. Open the Release Page for the Corresponding Version

Simply open the "Latest Release" link above.

2. Download the Correct Safari Bundle

In the attachments on the page, download the following file:

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

For example:

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

This zip file already contains the Xcode project that can be opened directly and the necessary Safari files.

Please download this file, not all-api-hub-<version>-safari.zip.

3. Extract and Open the Project Directly with Xcode

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

The bundle already contains the files needed to run. You can usually open the project directly after extraction without needing to move directories separately.

Method 2: Build and Install from Source Code

1. Get the 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 that 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. If you don't have 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 this is a locally built version not officially distributed, enable Allow Unsigned Extensions in the Develop menu.
4. Open the Extensions tab.
5. Find All API Hub and enable it.
6. Grant permissions as needed.

Method 3: Temporary Debugging (Development Use Only)

Some macOS/Safari versions support temporary debugging loading, but this is not suitable for formal 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 unavailable, please revert to the Xcode process above. For official releases, signing and distribution should still be used.

Development Mode Debugging

Development Build

# Development 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

Why does Safari require special handling?

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

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

• Without an account: You can build and use it locally, but it's more for development/debugging/personal use and generally cannot be directly distributed to ordinary users.
• With an account: You can create a formal signature and distribute via TestFlight / App Store, which is suitable for long-term maintenance and official releases.

Can I install it directly like Chrome?

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

What if I encounter errors during the build?

Please confirm the following first:

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

Are there functional differences compared to the Chrome version?

The basic functionalities are identical. However, due to some limitations in Safari's WebExtensions API, there might be minor differences:

• The sidePanel API is not available in Safari (a popup window is used instead).
• Certain permission request methods might differ.

How do I update the extension?

• If you installed from source: Rebuild the Safari artifacts and rerun the Xcode project.
• If you installed from the latest Release: Re-download the latest all-api-hub-<version>-safari-xcode-bundle.zip, extract it, and open the new Xcode project again to run it.

Uninstall

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

Resources

• Apple Safari Web Extensions Official Documentation
• Safari Web Extension Converter Usage Guide
• WXT Framework Safari Support Documentation

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