Highlights
- Chrome uses a manifest.json file, while Safari requires a manifest.plist file. Adapt your extension's manifest file to the Property List (plist) format used by Safari.
- Chrome and Safari may have differences in API names and implementations. Ensure that you update your extension code to use Safari's equivalent APIs and adjust any functionality that relies on Chrome-specific APIs.
- Chrome extensions often use background pages or event pages for background processes. In Safari, the architecture may differ, and you may need to refactor your background script to align with Safari's extension model.
- Review and update permissions in your extension to match Safari's requirements. Additionally, be aware of any security-related considerations, as Safari may have specific rules and restrictions.
- Major browsers like Firefox and Edge are also transitioning to manifest V3.
- Thoroughly test your extension on Safari to identify and resolve any compatibility issues. Use Safari's developer tools for debugging, and ensure that your extension functions seamlessly on the Safari browser.
Coditude Makes Migration Easy: Convert your Chrome Extension to Safari today.
Apple has now made it easier for developers to convert an existing Chrome/Edge/Firefox extension to a Safari Web Extension. In their release of XCode 12, they have introduced the Safari Web Extension Converter tool which gives you the ability to convert extensions made for other browsers to Safari Web Extensions. With XCode 13, you can even convert the extensions into iOS Safari extensions using the same command. What are iOS extensions? And why are they a big deal? Find out here.
Now without further ado, let's get started.
Note: This needs XCode 12 or greater and Safari 14 or greater.
We will be working with the "NewTabWallpaper" extension built for Chrome which shows new wallpaper with its location whenever a new tab is opened.
Download or clone the project at, migrating-chrome-extension-to-safari-example.
Let's convert this extension to a Safari Web Extension.
Select The Correct Xcode For Conversion
Open the terminal in macOS and select the right XCode if you have multiple versions installed.
sudo xcode-select -s <Supported XCode app path>Convert The Extension
Run the XCode command-line tool to convert the extension.
xcrun safari-web-extension-converter <path to extension>This will create a new project for Safari Web Extension and will open the project in Xcode.
Run The Safari Extension
Build the project through the start button. Make sure the macOS scheme is selected.
It will open a popup like the one below once it's built and running.
- Click “Quit and Open Safari Extension Preferences.”
- This opens Safari Preferences with an extensions list.
- Tick the checkbox next to the “NewTabWallpaper” extension to enable it.
- If an extension is not visible in the list, you may want to allow unsigned extensions.
- Safari Preference > Advances > Check “Show Develop menu in menu bar” then,
- Menu bar > Develop > Allow Unsigned Extensions. Now, enable the extension from the extensions list.
- Once the extension is enabled, you will get a popup asking for consent.
- Click “Use for New Windows and Tabs”.
- Now, open a new tab in Safari Browser and you can see it working.
I used XCode 13 to convert this extension, So you can see it running on iOS Safari too.
Assess Browser Compability
Once you decide to convert your extension to a Safari extension, here is all you will need to know before migrating.
Moreover, Safari Web Extension has some limitations while working with web extension APIs. It will be wise to assess your extension compatibility with other browsers and vice-versa. Apple has that covered in this article.
Coditude has over a decade of experience developing Browser Extensions. If you have any questions or queries about building/converting an extension, our dedicated Safari extension and plugin development team will be happy to answer them for you. Just drop us a line at Browser Extension Services.
