Engineering service
Safari extension development
We build Safari Web Extensions and port Chrome or Firefox extensions to Safari on Mac, iPhone and iPad. We handle the parts Safari does differently: the app the extension ships in, Safari's permission model, signing, and release through the App Store, TestFlight or Developer ID.
- 11+ years of experience
- 300+ projects delivered
- Remote team, clients worldwide
- NDA on request
Overview
What it is and when it fits
Safari supports Web Extensions, which share most of their API with Chrome and Firefox. The difference is that a Safari extension does not ship alone. It is packaged inside an app, signed with an Apple Developer account and distributed through the App Store or, on macOS, with Developer ID. For blocking ads and trackers, Safari also offers a separate, simpler type: the content blocker.
We convert existing extensions or build new ones, set up the app and signing, and work through the API and permission differences. Where possible, the web code stays shared with your Chrome and Firefox builds, with a thin layer of Safari-specific code and the app around it.
Who this is for
- Teams with a Chrome or Firefox extension who need it on Safari for Mac, iPhone and iPad.
- Companies that want an extension to ship together with a native macOS or iOS app.
- Ad-blocking and privacy products deciding between a Safari web extension and a content blocker.
- Developers who ran Apple's converter and hit APIs that do not work as expected.
How it works
Architecture at a glance
How a Safari web extension is put together
Toolbar popup, options
The interface users see, opened from the Safari toolbar. Talks to the background through messages.
Background (non-persistent)
A service worker or non-persistent script. Safari stops it when idle, and iOS requires it to be non-persistent.
Content script
Runs inside pages you choose. Can read and change the page, in an isolated JavaScript world.
Container app (macOS or iOS)
The app users install. Its Swift handler answers native messages from the extension.
Safari WebExtensions APIs
browser.*: tabs, storage, scripting, declarativeNetRequest, native messaging. Some APIs are missing or partial.
Web page
Only sites the user has allowed in Safari settings. Treat everything from them as untrusted input.
What we offer
What's included
Ports from Chrome or Firefox
Starting from Apple's safari-web-extension-converter, we rework the APIs and permission checks that do not carry over, after listing every gap first.
Container app and native code
Your extension logic in a Safari Web Extension target inside a macOS or iOS container app, with native code kept separate from the web code.
Onboarding for Safari permissions
A first-run flow that shows users how to turn the extension on and allow it on websites, and detects when that access is missing.
Content blockers
For ad and tracker blocking: a Safari content blocker built from JSON rules that Safari applies itself, or declarativeNetRequest rules inside a web extension.
Popups for mouse and touch
Toolbar popups and options pages that work with a mouse and keyboard on Mac and with touch on iPhone and iPad.
Signing and App Store release
Xcode signing, entitlements and App Store Connect setup, so the extension is ready for App Store review, TestFlight or Developer ID release.
Deliverables
What you get
- 01
Xcode project
App and extension targets that build from your existing extension source, so web code is not copied by hand for each release.
- 02
Gap list
Every API or manifest key Safari lacks or handles differently, with the workaround chosen for each.
- 03
Container app
A minimal app, or one with its own features, including the screens that show users how to turn the extension on.
- 04
Signed builds on TestFlight
Signed builds for each Apple platform you target, available to your testers through TestFlight.
- 05
App Store submission
The listing, privacy details and review notes prepared in App Store Connect, or a notarized Developer ID build for macOS.
- 06
Platform test notes
Results from testing on macOS, iPadOS and iOS, with the differences between them documented.
Compare
Where Safari differs
API coverage changes between Safari versions, so we check Apple's current documentation for each API your extension uses.
| Area | Chrome and Firefox | Safari |
|---|---|---|
| Packaging | A standalone extension package uploaded to a store. | The extension ships inside an app. It is built in Xcode, or, for an extension without native code, uploaded as a ZIP to App Store Connect, which packages the app without a Mac. |
| Accounts | A store developer account. | An Apple Developer Program membership, renewed every year, is needed to sign and distribute. |
| Permissions | Access is granted at install or through prompts in the browser. | Users enable the extension in Safari settings and grant access per site, so the extension must work before access is granted. |
| Background | A service worker in Chrome, an event page in Firefox. | A service worker or non-persistent background script. On iOS it must be non-persistent. |
| Content blocking | declarativeNetRequest rules, plus blocking webRequest in Firefox. | declarativeNetRequest in a web extension, or a separate content blocker extension built from JSON rules. |
| Platforms | Chrome extensions run on desktop. Firefox extensions also run on Android. | macOS, iPadOS and iOS, so touch and small screens need to be handled. |
Why it matters
What this gives you
One extension for Mac, iPhone and iPad
A single Safari build, tested on each Apple platform you target.
Installs that become active users
Onboarding that spots missing Safari permissions and explains the fix, so people who install the app also switch the extension on.
Web code shared with your other browsers
The Safari build uses the same extension source as Chrome and Firefox where possible, so fixes reach Safari users without a separate rewrite.
A port with known gaps
Every unsupported API is listed before we write code, so scope does not change halfway through.
Our approach
How a Safari extension project runs
Audit the extension
We run Apple's converter on a copy and list every warning and unsupported API before writing code.
You get: A gap list
Set up the project
We configure the app and extension targets, bundle identifiers and signing for your Apple Developer account.
You get: A project that builds and installs
Adapt the code
We rework the unsupported parts and build the flow that helps users turn on the extension and grant site access.
You get: A Safari build with a setup flow
Test on each platform
We test on macOS, and on iPadOS and iOS where your extension targets them, on physical devices where possible.
You get: Test notes per platform
Release
We prepare the App Store or TestFlight submission, or the Developer ID and notarization route on macOS, and help with review feedback.
You get: A submitted or notarized release
When this is not the right fit
- You want a Safari extension without an app. Safari extensions always ship inside one, even when App Store Connect builds it for you.
- You do not want an Apple Developer Program membership. Signing and distribution both depend on it, and it renews every year.
- Your extension relies on APIs Safari does not offer and cannot be rebuilt another way. We would say so early.
Tech stack
Technologies we use
The engines, APIs and tools we use on this service.
WebKitXcodeSwift
TypeScriptApp Store ConnectTestFlightFAQ
Common questions
Yes. We start from Apple's converter, then rework the APIs and permissions that do not carry over and build the app project around it. Converted extensions usually need adjustment, and we list the gaps first.
Not always. App Store Connect can now take a ZIP of a web extension and package it into an app for TestFlight and the App Store, without a Mac. When the extension needs native code, a custom app or detailed debugging on Apple devices, we use Xcode.
Safari Web Extensions run on macOS, iPadOS and iOS, but each platform needs its own testing. On iOS the background must be non-persistent, and the interface has to suit touch and smaller screens.
If the product only blocks ads, trackers or page elements, a content blocker is often the better fit: Safari applies its JSON rules itself, and the blocker cannot read page content, which makes privacy review simpler. If you also need a popup, page changes or sign-in, a web extension with declarativeNetRequest rules covers both.
On macOS, yes, using Developer ID signing and notarization. On iOS and iPadOS, distribution goes through the App Store or TestFlight.
Porting a working Chrome or Firefox extension typically takes 2–6 weeks, depending on the API gaps and how many Apple platforms you target. That is a typical range, not a quote. App Store review time comes on top.
Related reading
Our services
Related services
Start a project
Ship a Safari web extension
Send us your Chrome or Firefox extension or your Safari requirements. We will plan the app, signing and App Store path.
