A command-line tool that turns a Google Chrome extension into a Safari Web
Extension. It unpacks the extension, checks what Safari will refuse, rewrites the
manifest, injects a runtime shim for the `chrome.*` APIs Safari does not
implement, then runs Apple's `safari-web-extension-packager` and `xcodebuild` to
produce a signed app. The result can be loaded straight into Safari for
development or built through Xcode for TestFlight.
## What it does
### Input
Give it a `.zip`, a `.crx`, an `.xpi`, an unpacked extension directory, or a URL.
A Chrome Web Store link or a direct `.crx`/`.zip` download link is fetched for
you. The archive type comes from the file's magic bytes rather than its
extension, so a CRX someone renamed to `.zip` still works. Pass several inputs to
convert them in one run.
### Analysis
viaduct detects MV2 versus MV3 and reports what will break before it converts
anything. You get a readable `CONVERSION_REPORT.md`, and `--analyze --json`
prints the same findings as a machine-readable payload: issue counts,
`autoFixed`/`blocking` totals, a `convertible` verdict that uses the same gate as
a real conversion, the per-issue list, the permissions that were removed, and the
bundle id and name.
### Manifest rewrite
- Removes Chrome-only keys (`update_url`, `key`, `minimum_chrome_version`).
- Strips permissions Safari does not implement, such as `tabGroups`,
`offscreen`, `sidePanel`, and `debugger`.
- Converts an MV3 service worker into a non-persistent background page, and
forces `persistent: false` on MV2 backgrounds too, because Safari rejects a
persistent MV3 background outright ("a manifest_version >= 3 must be
non-persistent"). It also strips `background.type: "module"`, a known cause of
popups that fail silently.
- Injects `browser_specific_settings.safari` with a minimum version (`15.4` by
default, changed with `--min-safari`) and no maximum cap. An `18.*` cap hides
the extension on Safari 18 and later, including Safari 26.
- Flags icons Safari cannot render (anything that is not PNG), `content_scripts`
that use `world: "MAIN"` (Safari 18.4 and up only), and a missing App Store
description.
- Flags hardcoded `chrome-extension:///` URLs in JS, CSS, and HTML. Safari
gives every install its own origin, so these need `chrome.runtime.getURL()`.
- Checks `commands` shortcuts. A chord with no primary modifier is dropped by
Safari without a word, and ChromeOS-only modifiers like `Search` have no
Safari equivalent.
- Checks `_locales` and `__MSG_*__` placeholders, so an unresolvable
`name`/`description` reference does not ship as a literal placeholder string.
- Flags URL match patterns left behind in `permissions` under MV3, a common
migration slip. Safari ignores them there; they belong in `host_permissions`.
- Validates the `version` string. A missing, non-numeric, or out-of-range version
is rejected by Apple's `CFBundleShortVersionString` and fails the build.
- Clears `use_dynamic_url` on `web_accessible_resources`. Chrome rotates those
URLs per session and Safari cannot serve such an entry at all, so
`chrome.runtime.getURL()` hands back a URL that 404s. Anything loaded that way
(a content script's injected CSS, an ``, a ``, an iframe `src`)
fails without an error, which is a frequent reason an in-page panel toggles but
never appears.
### Toolbar buttons Safari never clicks
Safari 26 does not dispatch `action.onClicked` to a converted background, and it
does not fire `commands.onCommand` either. A popup-less toolbar button that
toggles in-page UI, a sidebar or an overlay, is therefore dead on arrival.
viaduct has two ways to revive it and tries them in this order.
The first is an in-page hotkey, and it is preferred because it never involves a
popover. The toggle really happens inside the content script, in its
`runtime.onMessage` listener. The shim loads ahead of the bundle's content script
and captures those listeners; viaduct then reads, statically, the message the
`onClicked` handler sends to the tab (something like `{type:"TOGGLE_SHELL"}`) and
generates a content script that replays that message to the captured listeners
when you press a keyboard shortcut. The toggle happens with no toolbar popup and
no popover at all. The shortcut reuses a declared `commands` key when there is
one, since Safari cannot fire `onCommand` and that key is otherwise dead weight
(the inert command is removed), and falls back to `Ctrl+Shift+Y`. When this path
is wired the toolbar button is deliberately left inert, because giving it a popup
would summon Safari's un-closable popover. It needs two things: a statically
determinable message, and an extension that has content scripts.
The second path is a synthetic popup, used only when the hotkey cannot be wired.
viaduct adds a tiny transparent `default_popup` that wakes the background on
click through `runtime.getBackgroundPage()`, which is the only call that wakes a
suspended Safari background (`runtime.sendMessage` does not), then replays the
captured `onClicked` listeners inside the background realm so their
`tabs.sendMessage` actually reaches the content script, deduped down to a single
toggle. This path carries a Safari limitation you will see: a toolbar popup
always draws a popover that script cannot close, since `window.close`, `blur`,
and refocus are all ignored, so a popover flashes up and goes away on your next
interaction.
### Runtime shim
The shim is injected into content scripts and into every extension HTML page:
popup, options, side panel. It:
- Routes `storage.sync` to `storage.local`, since Safari has no iCloud sync.
- Stubs `sidePanel`, `identity`, `notifications`, `tabGroups`, `debugger`, and
`offscreen` so evaluating a module does not throw and leave you a blank page.
The `sidePanel` fallback opens whichever panel page the extension actually
configured, from the manifest's `side_panel.default_path` or a
`setOptions({path})` call, instead of guessing at a filename.
- Completes `chrome.i18n` by backfilling `detectLanguage`, `getUILanguage`, and
`getAcceptLanguages` without clobbering Safari's native `getMessage`, so code
calling the missing `detectLanguage` degrades to `und` rather than throwing.
- Makes keyboard-shortcut management work without `chrome://extensions/shortcuts`,
which Safari does not have. `chrome.commands.getAll()` is rebuilt from the
manifest so an extension's own shortcut UI has something to show, and a
navigation to `chrome://extensions/shortcuts` or `chrome://settings` is
swallowed instead of opening a dead tab. Shortcuts themselves are edited in
Safari, under Settings, Extensions. The analyzer warns when the source
hardcodes one of those links.
### Staging, packaging, install
- Side-panel pages wired up as the action popup get sized automatically, so the
popup is not a tiny collapsed window.
- Staging copies a clean tree and drops dev cruft (`*.map`, `*.ts`, `README`,
lockfiles, store metadata) while keeping any file the manifest declares as a
runtime asset. A web-accessible `LICENSE.txt` or a deliberately served `.map`
will not go missing and 404 in Safari.
- The extension is packaged into an Xcode project, bundle identifiers are
patched, and the app is optionally built ad-hoc or team-signed.
- The bundle identifier is verified on the compiled `.appex` rather than on the
project files, so the wrong extension never gets registered with Safari.
- With `--install` the built host app is moved into `~/Applications`, with no
copy left behind, and registered with Safari. When it is team-signed it
survives Safari restarts.
## Requirements
- macOS with a full Xcode install, not just the Command Line Tools, for the
packaging and build steps. Both `xcrun safari-web-extension-packager` and
`xcodebuild` come with Xcode.
- Node.js 18 or newer.
- No runtime dependencies. TypeScript is the only dev dependency.
You can check the toolchain at any time:
```
viaduct --doctor
```
## Install
```
npm install -g @magicelk235/viaduct
viaduct [options]
```
The command is `viaduct`. It is macOS only, because it needs Xcode. See
Requirements above.
## Build from source
```
npm install
npm run build
```
That compiles `src/` into `dist/`. The CLI entry point is `dist/cli.js`.
Run it directly with Node:
```
node dist/cli.js [options]
```
Or link it as a global command:
```
npm link
viaduct [options]
```
## Usage
Convert straight from a Chrome Web Store link and let viaduct download the CRX:
```
viaduct "https://chromewebstore.google.com/detail/ublock-origin/cjpalhdlnbpafiamejdnhcphjbkeiagm"
```
A direct `.crx` or `.zip` URL works the same way:
```
viaduct "https://example.com/my-extension.crx"
```
Analyze an extension and report the issues without converting it:
```
viaduct ./my-extension.zip --analyze
```
Issues are tagged so you can tell what needs your attention from what the
converter already dealt with. `[auto-fixed]` means the manifest rewrite resolves
it and there is nothing for you to do. `[shimmed]` means Safari rejects the API
or permission but the injected shim emulates it, so the feature still works, and
you only need a real migration if the shim's documented limitation matters to
you. The summary line and the `--analyze --json` payload both carry `autoFixed`
and `shimmed` counts, which are disjoint, so CI can see how much the converter
absorbed.
Stage for Safari 18's "Add Temporary Extension", which skips Xcode entirely and
is the fastest way to iterate:
```
viaduct ./my-extension.zip --temp-load
```
Then, in Safari: under Settings, Advanced, turn on "Show features for web
developers"; under Settings, Developer, turn on "Allow Unsigned Extensions";
then use the Develop menu, "Add Temporary Extension", and pick the staged
folder. Temporary extensions have to be re-added every time Safari restarts.
Generate an Xcode project without building it:
```
viaduct ./my-extension.zip --no-build
```
Full conversion with an ad-hoc build, using a clean copy that is safe for CI and
TestFlight:
```
viaduct ./my-extension.zip --ci
```
Without `--ci`, resources are symlinked instead, so your edits show up live
during development. Use `--ci` to clean-copy them into the project.
Convert several extensions in one go:
```
viaduct ./one.zip ./two.crx ./unpacked-dir
```
Batch runs give each extension its own default `./_Safari` output, so
`--output`, `--report`, `--app-name`, `--bundle-id`, and `--json` are
single-extension flags and are rejected here.
## Options
```
-o, --output Output directory (default: ./_Safari)
--bundle-id Reverse-DNS bundle id (default: com.viaduct.)
--app-name Host app name (default: extension name)
--min-safari Safari strict_min_version (default: 15.4; use 18.4 for world:MAIN)
--platforms
all | macos | ios (default: macos)
--ci Clean-copy resources (CI/TestFlight-safe)
--temp-load Stage only, for Safari 18 "Add Temporary Extension"
--zip Also emit a distributable .zip of the staged extension
--clean Wipe the output directory before staging
--no-build Generate the Xcode project but do not run xcodebuild
--open-xcode Open the generated .xcodeproj in Xcode when done
--install Install the built app to ~/Applications + register w/ Safari
--verify After --install, check Safari registered/enabled it
--install-dir
Install target directory (default: ~/Applications)
--uninstall Remove the installed .app + unregister it
--no-safari-restart With --install, don't quit/relaunch Safari or set the toggle
--background-launch With --install, launch the host app hidden: the extension
still registers, but no window opens over your work
--team [] Sign with an Apple Team ID. --team auto (or plain
--install) auto-detects it from Xcode, a provisioning
profile, or your signing certificate. Omit for ad-hoc.
--no-shim Do not generate/inject the compatibility shim
--no-oauth-bridge Do not wire the Safari OAuth/externally_connectable bridge
--keep-module Keep background.type:"module" (default strips it)
--debug Emit the shim with debug tracing enabled. Traces persist
to a bounded ring buffer (last 2000 entries) in
storage.local under __viaduct_debug_log__; read it with
--logs. Dev builds only — never ship a --debug build.
--force Convert despite blocking errors
--strict Treat warnings as blocking too (CI gate). With --analyze,
exit 1 if any warning or error is present.
--analyze Analyze and report only (also previews the manifest rewrites)
--json With --analyze, print a machine-readable JSON report
--report With --analyze, also write the report to
(.json if --json, else Markdown)
--config Load defaults from (default: ./viaduct.config.json
if present). JSON keyed by long-flag name; CLI flags win.
--doctor Verify xcrun/packager/xcodebuild availability
--list List Safari Web Extensions registered with pluginkit
--logs Dump the persisted debug log of an installed --debug
build. matches the app name or bundle id; reads
Safari's on-disk storage, so Safari can stay open.
-q, --quiet Suppress progress messages (warnings/errors still print)
-v, --verbose Verbose output
-h, --help Show this help
--version Print the viaduct version and exit
```
## Installing a built app
Easiest is to let the tool do it. It moves the built app into `~/Applications`,
leaving no duplicate behind, registers it with LaunchServices, and launches it
once so Safari picks up the extension:
```
viaduct ./my-extension.zip --install
```
Then enable the extension in Safari, under Settings, Extensions.
To remove an app you installed earlier, which unregisters it from LaunchServices
and deletes it from the install directory:
```
viaduct --uninstall # ~/Applications
viaduct --uninstall --install-dir # custom directory
```
### Persisting across Safari restarts (team signing)
How long the extension sticks around depends on how it was signed.
Ad-hoc, with no `--team`, means Safari only loads it while "Allow Unsigned
Extensions" is on in the Develop menu, and that setting resets every time Safari
restarts. With `--install` the tool flips the toggle and bounces Safari for you;
pass `--no-safari-restart` if you would rather it did not.
Team-signed, with `--team`, uses a real Apple Developer certificate. Safari loads
the extension without the unsigned toggle and it survives quitting Safari.
`--team auto`, which is also what plain `--install` does, finds your Team ID in
Xcode so you never have to know or type it:
```
viaduct ./my-extension.zip --install # auto-detects the team
viaduct ./my-extension.zip --install --team auto # same, explicit
viaduct ./my-extension.zip --install --team V8K8L3ZSD5 # exact id
```
Auto-detection reads the team Xcode cached (`IDEProvisioningTeamByIdentifier` or
`IDEProvisioningTeams`, in both the `com.apple.dt.Xcode` and
`com.apple.dt.xcodebuild` domains) plus the codesigning identities in your
keychain, then uses the provisioning profiles on disk to choose between them,
newest first, so when there are several the team you provisioned for most
recently wins. Each source covers a few layouts, because which preference key
gets written, where profiles live, and what your certificate is called all vary
with the Xcode version. A team id that appears *only* in a profile is ignored:
profiles outlive the account that installed them, and handing xcodebuild a team
you have no account for fails every build. The team id is all the build needs,
since xcodebuild runs with `-allowProvisioningUpdates` and Xcode mints the
development certificate itself. If nothing usable turns up, the run tells you and
falls back to ad-hoc signing.
Signing is not taken on trust. When a team does reach xcodebuild, the signature
is read back off the built app and checked, so a build that quietly came out
ad-hoc fails instead of handing you an extension that vanishes the next time
Safari quits. An ad-hoc fallback that was announced up front is a warning rather
than a failure, since you asked for "a team if there is one" and there wasn't
one. If an auto-detected team turns out not to be able to sign, an expired
certificate for instance, the build is retried ad-hoc so the conversion still
finishes. A team you named yourself with `--team ` fails instead, because
that was a deliberate request.
A free personal Apple team works, but its provisioning profile expires roughly
every 7 days, so re-run the command to re-sign. A paid Developer Program account
lasts about a year.
If you would rather install by hand, copy the app path the run prints:
```
cp -R "_Safari/.app" ~/Applications/
open "~/Applications/.app"
```
## Tested extensions
Dark Reader, Claude in Chrome, and TWP (Translate Web Pages) are verified working
on the current build. Cloaked gets as far as a real sign-in window, which is
where testing stopped for want of an account. Grammarly, LastPass, and several
others were verified in an earlier round and are due a re-check. The wiki keeps
the full list, including what was actually exercised in Safari and what is still
untested: [Tested Extensions][tested].
[tested]: https://github.com/magicelk235/Viaduct-CLI/wiki/Tested-Extensions
## Limitations
- **Ad and content blockers built on blocking `webRequest`, full uBlock Origin
among them, cannot block network requests in Safari.** WebKit decides each
request before extension JavaScript runs and ignores the blocking return
value. No shim can change that, because the decision happens below JS. The
extension still installs and its cosmetic and element-hiding features still
run, and viaduct reports this class of extension as an `error`. For real ad and
tracker blocking on Safari, convert the extension's `declarativeNetRequest`
build instead, for example **uBlock Origin Lite** (uBOL). Safari honors DNR
rulesets, so uBOL blocks for real once converted.
- APIs with no Safari equivalent are stubbed so the extension loads, but the
feature behind them does not work. The analyzer reports each one with a
suggested remediation.
- Extensions that authenticate with `chrome.identity` or a hardcoded
`chrome-extension://` OAuth redirect cannot complete login. The OAuth client is
registered on the provider's server against the original Chrome extension
identity and scheme, which Safari cannot reproduce. Fixing it needs the
provider to register a Safari redirect or a hosted HTTPS callback flow, and it
is not something conversion alone can do.
- `storage.sync` is mapped to `storage.local`. Data persists, but it does not
sync across devices.
- Native messaging (`connectNative` and `sendNativeMessage`) has no Chrome-style
host manifest or host binary in Safari; messages route to the containing macOS
app instead. The analyzer flags it, and you implement the response in the app's
`SafariWebExtensionHandler` (`beginRequest`).
- `declarativeNetRequest` `modifyHeaders` rules are dropped, from static rulesets
and from dynamic `updateSessionRules`/`updateDynamicRules` calls alike. Safari
accepts such a rule and then never applies it (verified against a live server,
with a `block` rule in the same call blocking correctly), and one header name off
WebKit's allowlist makes the whole update throw and takes the working rules with
it. Spoofing `user-agent`/`referer`, stripping `Cookie`, a CORS bypass or a
response-header rewrite all need a native-messaging proxy instead.
The tool also warns when static rulesets use `regexFilter`, since Safari
supports only a limited regex subset and silently drops rules it cannot
compile, and when the number of enabled rules exceeds what Safari honors, since
the overflow is ignored.
## License
Licensed under the [PolyForm Shield License 1.0.0](LICENSE). Copyright (c) 2026
Yehonatan Cohen (magicelk235). You may freely use, modify, and share it, but you
may not use the Viaduct CLI to build a product that competes with it.