Create Custom Extensions in Safari: A How-To Guide

Creating custom extensions for Safari lets you tailor your browsing experience beyond the built-in features. This guide walks you through the options available—from using Apple’s official framework to building lightweight tools with JavaScript—so you can decide which path fits your skills and needs.

Understanding Safari Extension Types

Safari supports two main kinds of extensions: web extensions and app extensions. Web extensions are the modern, cross-browser standard that Apple adopted in Safari 14 (macOS Big Sur). They use HTML, CSS, and JavaScript, and the same codebase can be ported to Chrome, Firefox, and Edge with minimal changes. App extensions, on the other hand, are built with native code (Swift or Objective-C) and are distributed through the Mac App Store. They can access more system features, like the share sheet or Today widgets, but they require deeper platform knowledge.

For most people creating a custom extension, web extensions are the right choice. They are easier to write, debug, and maintain, and Apple provides a conversion tool to migrate older legacy extensions to this format.

Prerequisites and Tools You Need

Before you start, you need a Mac running macOS Big Sur or later, with Xcode installed from the Mac App Store. Xcode includes the Safari Extension Converter, which automatically transforms a Chrome or Firefox extension into a Safari web extension. You also need a free Apple Developer account to enable the Develop menu in Safari; a paid account is only required if you plan to distribute through the App Store.

If you are building from scratch, you will use Xcode’s template called “Safari Web Extension App.” This creates a container app that embeds your extension. The extension itself is a folder containing a manifest.json file, background scripts, content scripts, and popup HTML pages.

Step-by-Step: Building a Basic Web Extension

Here is the typical workflow to create a custom Safari extension:

1. Open Xcode and choose File > New > Project.
2. Select the Safari Web Extension App template under the macOS tab.
3. Name your project and choose a location. Xcode creates a workspace with two targets: the app and the extension.
4. In the extension folder, edit the manifest.json file. This defines the extension’s name, version, permissions, and the files it uses.
5. Write your JavaScript code in the background script (e.g., background.js) and content script (e.g., content.js). The background script handles events like toolbar clicks; the content script can modify web pages.
6. Add a popup HTML file if you want a toolbar button that shows a menu.
7. Build and run the app target. This launches Safari with your extension installed in development mode.
8. Enable the extension in Safari’s preferences under the Extensions tab.

After you make changes, rebuild and relaunch the app. The extension updates automatically while in development.

Key Files and Their Roles

• manifest.json — The heart of your extension. It declares the name, version, permissions, and which scripts run. Safari uses a slightly different structure than Chrome, but the converter handles the differences.
• background.js — Runs in the background and responds to browser events, such as clicking the toolbar icon or receiving messages from content scripts.
• content.js — Injected into web pages. It can read and modify the DOM, but it cannot access the page’s JavaScript variables for security reasons.
• popup.html — The small window that appears when you click the toolbar button. It can contain buttons, forms, or any HTML you like.
• Resources folder — Holds images, icons, and other static assets referenced in the manifest.

Testing and Debugging

To test your extension, enable the Develop menu in Safari: go to Safari > Settings > Advanced and check “Show features for web developers.” Then, from the Develop menu, you can open the Web Inspector for your extension’s background page. This gives you a console to log messages and inspect variables, just like in a normal web page. For content scripts, you can inspect the page itself and see any errors in the console.

Common issues include missing permissions in the manifest, incorrect file paths, or forgetting to reload the extension after changes. If a script does not run, check that the manifest’s “content_scripts” section matches the URLs you target. Use the wildcard pattern "*://*/*" to match all HTTP and HTTPS pages.

Distribution and Alternatives

Once your extension works locally, you have two distribution options. You can keep it private by running the app from Xcode whenever you need it, or you can package it for the Mac App Store. The App Store route requires a paid Apple Developer account (99 USD per year) and a review process. Apple has specific guidelines for extensions: they must be useful, stable, and respect user privacy. You cannot include code that downloads additional executable code.

If you do not want to use Xcode at all, there is a simpler alternative: create a JavaScript bookmarklet. This is a bookmark that runs a small script on the current page. It is not a true extension, but it can perform simple tasks like removing clutter or converting units. To create one, you add a bookmark with a URL starting with javascript: followed by your code. This works on any browser and requires no developer account.

Frequently Asked Questions

Do I need a paid Apple Developer account to create a Safari extension?

No. A free Apple ID is enough to build and test extensions locally on your own Mac. You only need the paid account if you want to submit to the Mac App Store or share with others via that channel.

Can I convert my existing Chrome extension to Safari?

Yes. Apple provides the Safari Extension Converter in Xcode. It imports your Chrome extension’s files and produces a Safari web extension with the necessary adjustments. However, you may need to manually fix APIs that differ between browsers, such as browser-specific functions.

Why is my extension not showing up in Safari?

First, ensure you built and ran the container app. Then check Safari’s Settings > Extensions to see if the toggle is off. If it still does not appear, look at the console in Web Inspector for errors. Also verify that your manifest.json is valid JSON and that all referenced files exist.

Can I write an extension without Xcode?

Technically, you can write the JavaScript and HTML files in any text editor, but you still need Xcode to package and install it into Safari. The only no-Xcode alternative is a bookmarklet, which is limited to single-page scripts.

Are Safari extensions safe to install?

Extensions from the Mac App Store are reviewed by Apple. For extensions you build yourself, you are responsible for the code. Always be cautious with extensions that request broad permissions, such as access to all websites or your browsing history.

How do I update my extension after making changes?

In development, just rebuild and run the app again. Safari will reload the extension. If you distributed via the App Store, you submit a new version for review, and users update through the App Store.

Related

• Is Funimation Safe? What to Know Before You Stream
• Snapdragon 6s Gen 4 vs Gen 3: Which Chip Is Faster?
• Honor X5 Plus 4G: Key Specs and Regional Details