Skip to main content

Building for Safari

LightningAddon supports Safari Web Extensions. The architecture is compatible: we use browser/chrome APIs (Safari provides both), Manifest V3, and service workers. No source code changes are required.

Requirements​

  • macOS – Safari's build tooling requires macOS
  • Xcode Command Line Tools – xcrun safari-web-extension-packager is included

Build​

  1. Build the Chrome extension (Safari uses the same output):

    pnpm build:chrome

  2. Package for Safari:

    pnpm build:safari

    This runs pnpm build:chrome then xcrun safari-web-extension-packager apps/extension/dist and produces an Xcode project. Use --no-prompt and --no-open for non-interactive builds.

Local Testing​

  • Safari 26+: You can load a temporary extension directly from a folder. In Safari: Settings > Developer > Add Temporary Extension… and select apps/extension/dist. No packaging required for quick testing.
  • Packaged build: The packager output can be opened in Xcode to build and run a macOS app that includes the Safari extension.

Store Distribution​

To distribute via the Mac App Store or Safari Extensions Gallery:

  1. Apple Developer account – Required for App Store Connect
  2. Package – Run pnpm build:safari; the packager creates an Xcode project
  3. Configure – Set bundle ID, signing, and app metadata in Xcode
  4. Submit – Archive and upload via App Store Connect

For detailed steps, see Apple's Safari Web Extensions documentation.

Caveats​

  • Safari's MV3 implementation may differ from Chrome in some APIs (e.g. webRequest limitations). LightningAddon avoids unsupported APIs.
  • Store review and approval follow Apple's process and timelines.