Convert a Chrome Extension to Safari Web Extension

Last Update: 2021-01-12

Part A: Safari Web Extension Development

Here we use Simple Gmail Notes (Source Code) for the example.

  1. Make sure you have Safari 14 and Xcode 12 installed

  2. In the terminal, use Xcode command for the conversion

    xcrun safari-web-extension-converter <your extension folder>

    (click Yes for default options)

  3. A brand new Xcode project folder will be created, and Xcode will be automatically launched to open the new project.

    The Xcode project will be linked to the source web extension folder, so you need to make sure both source and generated folder exist and have a consistent relative path.

  4. Without doing anything further in Xcode, just click run to launch the extension

  5. Safari will be opened, yet extension will not appear at first sight. You need to do the following steps first:

    a. safari -> preferences -> enable development menu

    b. safari -> develop menu -> click allow unsigned extension (need to do this every time safari is restarted)

    c: safari -> preferences -> extensions tab -> click the extension

    d: open the web site, click the icon near the address bar, and allow the access

  6. Now the extension should be able to be launched, and you could see the content script in the Safari debug console.

  7. To check the background script, in the Safari, click Develop -> Web Extension Background Pages

  8. Tip: while WebExtensions API is an open standard, Apple has not (yet) implemented the full spec. You could find limitations of current phase here.

Part B: Distribute Safari Web Extension to App Store

  1. Go to App Store Connect, create an identity via

  2. In App store connect, create an app of ‘macApp’

    In the bundle ID drop down, just select the one newly created


  3. Go to Xcode, click Project -> target -> app target, update app category and bundle identifier (use the one in the App Store)

  4. Click extension target of project, update bundle identifier.

    Note the the project identifier should prefix the extension identifier. E.g. if project identifier is ‘’, then extension identifier should be something like ‘’

  5. In Xcode -> assets -> make sure all icons are provided

  6. Update the extension name in the swift file of app

  7. In Xcode click Product -> Archive

  8. Distribute window should automatically appear after the archive action. (If not, click Window -> Organize -> Distribute App)

  9. Select App Store Connect

  10. Open a browser, go to App store connect, click the app, and now you should be able to select the build

    (If the build is not available, check your App Store email and see if there are any error reports.)

  11. Upload all the screenshots and add descriptions to App Store Connect

  12. You are now good to start a review process, good luck :)

Update 2020-12-30: After a few weeks of back and forth, we finally launched the app into Mac Extension Store. Some major comments from Apple:

  1. Cannot have any donation related content, unless you are a non-profit organization
  2. Cannot have any payment, unless via Apple gateway
  3. Cannot mention COVID 19, unless you are officially granted
  4. Extension name must be changed from ‘Simple Gmail Notes’ to ‘Simple Notes for Gmail’