Userscripts Safari

An open-source userscript editor for Safari

Table of Contents

• Installation
• Usage
• UI Overview
  • Browser Page
  • Settings Modal
  • Popover
• Metadata
• API
• Scripts Directory / Save Location
• Getting Help
• FAQs
• Contributing
• Support
• Privacy Policy
• License

Installation

Userscripts is available for iOS (iPadOS) and macOS. For all versions, installation is done through Apple's App Store. On macOS, versions prior to 4.x were made available to download and install directly from the repository, but due to changes in the way Apple allows developers to distribute apps built with the WebExtension API, that is no longer an option.

To run Userscripts on iOS you should be on iOS 15.1 or higher.

To run Userscripts on macOS you should running macOS 12 or higher, along with Safari 14.1 or higher.

App Store Link

Development Progress

Usage

It's recommend to read this documentation and, if you have time, watch the following video overviews to familiarize yourself with the app and extension.

Once the app is downloaded and installed the following steps should be taken:

iOS (iPadOS)

After installing the iOS App, you need two main steps to make the extension work:

• Open the App and set a directory (For saving and loading userscripts)

  • After Userscripts for ios v1.5.0, a local default directory will be set automatically
  • In earlier versions please click the Set Userscripts Directory button and select the directory

• Enable the extension in Safari (And grant permissions)

  • Manage extensions from Settings App (Settings > Safari > Extensions) or Safari App (AA button on iPhone, extension-icon on iPad, also where you open the extension's popup interface)
  • For optimal experience it's recommended that you Always Allow Userscripts for All Websites

[!NOTE]

The iOS App cannot detect whether you have enabled the extension in Safari, therefore, the App prompt will not change after you enable the extension. Currently the App interface is only used to set or change the userscripts directory.

You could select an iCloud folder for syncing scripts between macOS and iOS, but please note that there may be delays in synchronization, and you may encounter files be evictioned due to iCloud optimization, please refer to #424. (Since macOS 15 / iOS 18, please set "keep downloaded" for the folder to avoid eviction)

There are two main ways to install a user script from the iOS version:

• Visit a .user.js URL in Safari, then open the extension popup and you will see an installation prompt
  • The URL should end with .user.js in /PATH part, not the ?QUERY or #HASH parts
• You could also save files with the extension .user.js directly to the Userscripts directory you set above

[!TIP]

Both of the above work equally well in the macOS version.

The iOS version does not include the script editor provided in the macOS version, but you can always edit script files in the directory you set directly on iOS. (use any third-party code editor apps, support in-place opening and editing)

macOS

After installing Userscripts on macOS, you do not need to select a userscripts directory if you do not plan on syncing your userscripts between multiple devices. Instead you can choose to use the default directory, which is located at ~/User/Library/Containers/Userscripts/Data/Documents/scripts - again, this is default (and automatic) behavior. You only need to select a new location if you want to store your userscripts elsewhere, which is especially useful if you are using an external code editor such as Sublime Text or VSCode.

Refer to Apple's official guide page: Use Safari extensions on your Mac

Here's a short clip showing how to easily create/add a userscript in Safari using this extension on macOS

UI Overview

Browser Page:

1. Extension button - click this button to open the extension interface
2. Filter bar - use this input to filter items in the sidebar, by name
3. Sort button - changes the order of the items in the sidebar by name or modified time
4. Sidebar buttons - described left to right
   • The settings button (represented by a cog) displays the settings modal (discussed below)
   • The plus button allows users to add new items
     • New CSS is a "userscript" that expects CSS code
     • New Javascript is a prototypical userscript that expects Javascript code
     • New Remote allows the user to add a remote hosted userscript (or style) by inputting the web address (ex: https://www.k21p.com/example.user.js)
5. Item toggle - this toggle enables or disables an item
6. Item - this is the userscript (or style), clicking on it will load it's contents into the editor - you can hide descriptions in the settings area!
7. Editor buttons (top) - described left to right
   • Update button - this button allows you to update userscripts that meet the following conditions
     • metadata contains @version tag
     • metadata contains @updateURL tag
   • Download button - click this button to download a copy of your userscript
     • Note: every userscript that is displayed in the interface is already present on your local machine, at your save location - the download button offers a quick way to retrieve a copy of that file, without needing to click the settings button, and then the save location link within the settings modal
   • Trash button - moves the currently loaded userscript to the trash bin - it will subsequently be removed from the interface and save location
8. Editor buttons (bottom)
   • Discard - while editing, reverts any unsaved changes you've made to a userscript
   • Save - while editing, saves all changes you've made to a userscript
     • Command + S is the keyboard shortcut for the action

Settings Modal:

• Auto Close Brackets - toggles on/off auto closing of brackets in the editor
  • this affects the following characters: () [] {} "" ''
• Auto Hint - automatically shows completion hints while editing
• Hide Descriptions - hides the item descriptions in the sidebar
• Show Invisibles - toggles the display of invisible characters in the editor
• Javascript Linter - toggles basic Javascript linting within the editor
• Tab Size - the number of spaces a tab is equal to while editing, obviously defaults to 4 because using 2 spaces is absolute insanity
• Enable Injection - toggle on/off script injection for the pages you visit (this is the on/off switch)
• Show Toolbar Count - displays a badge on the toolbar icon with a number that represents how many enabled scripts match the url for the page you are on
• Save Location - where your file are currently located and being saved to (click the blue text to open location)
• Change Save Location (cogs icon) - this button, located directly to the right of the save location, is a shortcut for opening the host app, which will allow you to change the save location
• Global Blacklist - this input accepts a comma separated list of @match patterns (Match pattern structure), a page url that matches against a pattern in this list will be ignored for script injection

Popup:

<!-- --> <img src="/etc/popover.png" width="50%" height="50%">

10. Open Page Link - macOS only, opens the extension browser page
11. Enable Injection toggle - turns on/off page script injection (on/off switch)
12. Refresh View - refreshes the popup view
13. Available Updates View - the extension periodically checks all userscripts in your save location for updates and when an update is found, it is shown in this view
14. Folder Button - on macOS this button opens your save location directory in Finder, on iOS this button displays the "all scripts view" where you can see every script that found in your save location directory, the "all scripts view" allows you to toggle individual userscript scripts on/off regardless of the current page being displayed in the browser
15. Install Prompt - when a userscript is displayed in the browser, this alert displays, giving the user the option to install the userscript into their save location directory, tapping the prompt will take them through the installation steps
16. Matched Userscripts List - this list shows the currently matched userscripts relative to the current page being displayed in the browser, all userscripts that match to the domain will be showed, whether they are active or not. Users can click/tap the userscript to the toggle them on/off. If a userscript is active for the domain through a subframe a sub tag will be show next the to the file type indicator

Metadata

Userscripts Safari currently supports the following userscript metadata:

• @name - This will be the name that displays in the sidebar and be used as the filename - you can not use the same name for mu