Porting Extensions with safari-web-extension-converter

This article explores how Apple’s xcrun safari-web-extension-converter command-line tool simplifies the process of porting existing Chrome and Firefox extensions to the Safari web browser. By automating the creation of a native Xcode project, wrapping standard web technologies, and identifying API incompatibilities, the tool allows developers to quickly transition their extensions to macOS and iOS ecosystems without rewriting their core codebase.

Automated Xcode Project Generation

Unlike Chrome and Firefox, which distribute extensions as standalone compressed packages, Safari requires web extensions to be bundled inside a native macOS or iOS application. Building this wrapper manually in Xcode can be time-consuming for web developers unfamiliar with Apple's native development environment.

The xcrun safari-web-extension-converter tool solves this by automatically generating a fully configured Xcode project. When you point the tool at your existing extension directory, it creates the required native app container, links your web extension files (HTML, CSS, and JavaScript), and configures the necessary build targets for distribution through the App Store.

Compatibility Warnings and Manifest Analysis

During the conversion process, the tool reads and analyzes the extension's manifest.json file. While Safari supports the industry-standard WebExtensions API, there are still slight differences in API support among browsers.

Once the converter finishes running, it outputs a compatibility report directly in the terminal. This report highlights specific keys, permissions, or JavaScript APIs present in your Chrome or Firefox extension that Safari does not currently support. This immediate feedback saves developers hours of manual debugging by pinpointing exactly which parts of the code need workarounds or polyfills.

Streamlined Cross-Platform Support

Safari Web Extensions can run on macOS, iOS, and iPadOS. The converter tool configures the generated Xcode project to support all of these platforms simultaneously. By default, it generates a universal project containing both macOS and iOS app targets that share the same underlying web extension code. Developers can also use specific flags to limit the conversion to a single platform if desired.

How to Use the Tool

To use the converter, you must have Xcode installed on a Mac. Open the Terminal application and run the following command, replacing the path with the location of your existing unpacked extension folder (the folder containing your manifest.json file):

xcrun safari-web-extension-converter /path/to/your/extension

When executed, the tool provides an interactive prompt to configure your project, or you can pass flags to automate the setup:

  • --project-location: Specifies where the new Xcode project should be saved.
  • --app-name: Sets the name of the generated wrapper application.
  • --bundle-identifier: Defines the unique bundle ID required for Apple Developer signing.
  • --swift or --objc: Chooses the language for the native wrapper app (Swift is the default).
  • --mac-only or --ios-only: Restricts the generated project to a single platform.
  • --copy-resources: Copies the extension files into the new project rather than referencing the original files.

Maintaining a Unified Codebase

By default, the converter tool references your existing extension files in their original location rather than duplicating them, unless the --copy-resources flag is used. This architecture is deliberate. It allows developers to maintain a single source of truth for their HTML, CSS, and JavaScript files. When you update your core extension code for Chrome or Firefox, those changes are automatically reflected in your Safari Xcode project, drastically reducing the overhead of multi-browser maintenance.