How to create a Safari extension

Today's Best Tech Deals

Picked by Macworld's Editors

Top Deals On Great Products

Picked by Techconnect's Editors

Safari extensions, first introduced with version 5 of Apple's Web browser, allow developers to create all sorts of clever add-ons to augment and enhance the surfing experience. If you know a little bit about HTML, CSS, and JavaScript (or even just one of the three) you're already well equipped to create a Safari extension.

But since Apple's documentation can seem intimidating, here's a tutorial to walk you through creating your first extension, using any custom CSS or JavaScript code you write. In this example, I’ve made an extension that makes look a lot like another popular Mac site, along with some extra functionality. If you're interested, you can download the complete code of the extension I created here.

(Want to use the finished Daring Macworldball Safari extension? It's available for download. Right-click the link and select Save Linked File to "Downloads" or Save Linked File As. Here are installation instructions if you need them.)

Step 1: Get certified

Before you can build and install your custom extensions, you'll need to get a free developer certificate from Apple. Go here, and sign up for the Safari Developer Program. After registering as a Safari Developer, you'll get redirected to the Member Center. Then, you can click to launch the Developer Certificate Utility. Apple will walk you through the process, which will include launching Keychain Access on your Mac at one point. Once you finish this step, you don't have to worry about it anymore.

Step 2: Enable the Develop menu

If you haven't yet enabled Safari's Develop menu, you'll need to do so to start building your first extension. Open Preferences in the Safari menu, choose the Advanced tab, and check the box marked Show Develop menu in menu bar.

Step 3: Create the Extension

From the Develop menu, choose Show Extension Builder. Click the Plus button in the bottom left corner of the window and choose New Extension. In the Save dialog box that appears, name your extension (I called mine Daring Macworldball) and save it wherever you'd like.


Step 4: Start filling out details

The first few fields you'll see in the Extension Builder window are mostly self-explanatory; you provide the display name for the extension, your name, a description, and a link to your Website. That information becomes useful if you publicize your extension and share it with others.

Tweak the Bundle Identifier, too. Replace the "yourcompany" text with your name or your company's name.

Then scroll further down to the Extension Website Access section. You need to indicate whether your extension should load itself on every Web page you visit, or only on specific URLs. For this example, choose Some from the dropdown.

We want this extension to work on every URL, so in the Allowed Domain field that appears, type in *—the asterisk ensures that any subdomains are covered, too.

Step 5: Prepare to code

This next step is where things get a smidgen confusing. Extensions work by loading external HTML, JavaScript, and CSS files that you provide. Now, you need to switch away from Safari and locate the extension folder that you created earlier. Using your favorite text or code editor, create a file in that folder called macworld.css.

Once the file's in place, switch back to Safari and the Extension Builder window. Scroll down to Injected Extension Content and hit the New Stylesheet button. Choose your newly-created CSS file from the dropdown that appears.

Step 6: CSS magic

Now, go back into your editor and start adding some custom CSS. Here's a snippet of the code that I dropped in.

Save your changes, then switch back to Safari again. Click the Install button at the top of the Extension Builder window. This—surprise!—installs your extension; you can see it in the Extensions panel of Safari's Preferences now, too.

As you make tweaks to your CSS files (or other files that you create for your extension), the Extension Builder's Reload button will become your best friend. Rather than hitting Safari's Refresh button each time you tweak your extension, you simply hit Reload, and that causes Safari to re-inject your custom code into the page without your needing to refresh.

Note that because of the way Safari prioritizes extensions' CSS, you'll need to make liberal use of the !important operator to ensure that your custom code has the intended effect.

Step 7: JavaScript, too!

Now, modifying a site's CSS is fun, but there's a lot more you can do with Safari Extensions. Our new extension certainly looks very Daring Fireball-esque, but the header is all wrong. Rather than simply hide it with CSS, we'll tweak its contents via JavaScript.

First, go back to the folder where you created your CSS file. Create a new file there called macworld.js. Then head back into the Extensions Builder, find Injected Extension Content, and hit the New Script button next to End Scripts. (Start Scripts execute before the page loads; End Scripts wait until the DOM is finished rendering.) Choose your newly created script.

Here's the code I dropped into my JavaScript file (you can also download the code). Remember, since you're making a Safari Extension, your code need only work in Safari; cross-platform gotchas aren't a concern here.

Step 8: Give it away

If you're ready to package up your new extension to share with others, just hit the Build Package button at the top right of the Extension Builder window. That will create a standalone .safariextz file that you can post online or share via e-mail.

Wrapping up using the Daring Macworldball Safari extension.

Extensions, of course, can also take advantage of other Safari interface options, like custom bars, context menu items, and toolbar entries, but those are a bit beyond the scope of this tutorial. Now that you're this far, though, you should be able to make more sense of Apple's documentation on them. Armed with the information you already have, however, you're well-equipped to create all sorts of Safari extensions to manipulate the Web pages you visit.

Note: When you purchase something after clicking links in our articles, we may earn a small commission. Read our affiliate link policy for more details.
Shop Tech Products at Amazon