WebExtensionTemplate
Create a browser extension for Chrome, Firefox and Safari in no time.
WebExtensionTemplate lets you skip the boilerplate and write a Web Extension with TypeScript and Svelte or React.
Features
- Popup window written in Svelte (or React) when you click the extension toolbar icon
- Extension settings page written in Svelte (or React)
- Lightning-fast build process to compile source code with esbuild
- Build scripts to package the extension for Chrome, Firefox and Safari
- Sourcemaps for local builds
- Minifies production builds
- iOS and macOS container apps written in SwiftUI for the Safari extension (no Swift / SwiftUI knowledge required to use)
- Prettier formatting
- webextension-polyfill to add a couple missing Promise-based APIs to Chrome
Future roadmap
- Separate branch with the popup and settings page written in React
- Tests
Setup
First, fork this repository. Then, follow the steps below. By the end of this, you should be able to search across the project for REPLACEME
and get no results.
All browsers
- Update
Extension/_locales/en/messages.json
with an extension name and description - Update
Extension/README.md
with your app's name - Open
Extension/package.json
and update...name
with your app's nameauthor
with your namelicense
with the app's license
- Open
Extension/public/settings.html
and update the<title>
with your app's name - Delete the
<link>
inExtension/settings.html
if you don't like the provided CSS - Create a toolbar icon for your app
- Should be a small, simple glyph that makes sense when monochromatic in Safari
- Make versions in 16, 19, 32, 38, 48 and 72-pixel sizes saved to
Extension/images
- Should be named
toolbar_Qpx.png
whereQ
is 16, 19, etc
- Make an app icon that is 1024 x 1024
- Copy versions of it to
Extension/images
in 48, 96, 128, 256 and 512-pixel sizes - Should be named
app_icon_Qpx.png
, whereQ
is 48, 96, etc
- Copy versions of it to
Firefox
- Update
manifest.json
with a Firefox extension id (undergecko
>id
) in the formatappname@domain.com
Safari
Do the following steps in Xcode.
Note: “Open the project config” means double-click the app name at the top of the file view in Xcode.
- Change the Safari app name to your app’s name
- Open
Shared (App)/Models.swift
and updateAPP_NAME
with your app's name - Create a new bundle identifier in the format
com.domain.App-Name
- Open the project config and go to
AppName (iOS)
> Signing & Capabilities and update the bundle id - Repeat for the macOS app
- Open the project config and go to
- Create a new bundle identifier. It should be your app bundle identifier with
.Extension
added onto the end. So if your app bundle ID iscom.domain.App-Name
, this should becom.domain.App-Name.Extension
- Open the project config and go to
AppName Extension (iOS)
> Signing & Capabilities and update the bundle id with the extension bundle id - Repeat for the macOS extension
- Update
MAC_EXTENSION_BUNDLE_ID
inShared (App)/Models.swift
with the extension bundle ID as well
- Open the project config and go to
- Update
macOS (App)/AppDelegate.swift
with a help documentation link - Under project config > Signing & Capabilities, set the team for both apps and both extensions
- Under project config > General, update the display name for iOS and macOS
- Rename both files named
REPLACEME.entitlements
to beYour App Name.entitlements
- Open the project config and to go to App Name (macOS) > Build Settings and find the setting for “Code Signing Entitlements.” Replace
REPLACEME.entitlements
with the name of your new entitlements file - Repeat for App Name Extension (macOS) > Build Settings > Code Signing Entitlements
- Open the project config and to go to App Name (macOS) > Build Settings and find the setting for “Code Signing Entitlements.” Replace
- Open the project config and go to App Name Extension (macOS) > Build Settings and find the setting for “Bundle Display Name.” Update its value with your app’s name
- Repeat for App Name Extension (iOS)
- Go to Product > Schemes > Manage Schemes… and update the iOS and macOS schemes with your app’s name
- iOS app icon:
- Add the app icon to
iOS (App)/iOS Assets
asAppIcon
with all the required sizes - Add a copy of the app icon named
Icon.png
inShared (App)/Resources
- Add the app icon to
- macOS app icon
- Reduce the size of the app icon by 20% while keeping the canvas the same size
- Add the app icon to
macOS (App)/macOS Assets
asAppIcon
with all the required sizes
Building your extension
All npm
commands should be run in Extension
. Safari extensions should be built in Xcode.
Browser | Local | Production |
---|---|---|
Chrome | npm run build |
npm run build:chrome |
Firefox | npm run build |
npm run build:firefox |
Safari | Product > Build | Product > Archive |
console.log
calls are stripped out of prod builds- The Chrome build script generates a zip that can be uploaded to the Chrome Web Store
- The Firefox build script generates a zip for the Mozilla Add-On Store as well as a zip of the source code for the store review
Other notes
- Firefox does not support service workers in the background, so I would maintain a separate branch
firefox
that runsdist/background.js
as a background script