Greasemonkey 4 Announcement

Greasemonkey has been a Firefox extension for well over a decade, with version 0.3.5 dating from 2005.  We've grown and changed a lot over that time.  With the upcoming Firefox 57 release, we need to change even more.  Mozilla is completely replacing the extension system in Firefox, to align with the budding Browser Extension standard, based on/shared with Google Chrome.

As a result, version 4 of Greasemonkey is a nearly complete re-write.  Its interface and feature set have been rebuilt in order to best to work with coming Firefox versions.  A variety of compromises have been made.  We've elected to make a rare backwards incompatible change.

If you are a regular user, please continue reading Greasemonkey 4 For Users.

If you are a developer, please continue reading Greasemonkey 4 For Script Authors.

Greasemonkey 4 For Script Authors

As mentioned in the main post, Greasemonkey 4 is changing to be compatible with the Browser Extension API.  At its core, this set of APIs is completely asynchronous.  Greasemonkey's old "GM_" APIs are typically synchronous.

Why?

There exist other user script engines which have already done the work of bridging the gap.  Greasemonkey has elected to move exclusively towards a more performant asynchronous model.  Eventually in the future, such scripts will be faster.

What?

The Greasespot Wiki has been updated to explain Greasemonkey 4 in detail.  Here's a quick summary.

First, there is only an embedded editor.  Browser Extensions have no access to the file system, so you can no longer author user scripts in your familiar text editor.

There is only one object provided to user scripts now, named GM.  It has several properties.  One of them is info – the equivalent of the old GM_info.  There are also several methods of this object: getResourceUrl, deleteValue/getValue/listValues/setValue, xmlHttpRequest.

To use these methods you still need @grant, and use the new name, e.g.:

// @grant GM.setValue

The new form has a dot, where the old form has an underscore.  You may specify both @grants, if you'd like to be compatible with Greasemonkey 4 and other user script engines at the same time.  As of today, there is no support for: GM_log (use console.log), GM_addStyle, GM_registerMenuCommand, nor GM_getResourceText.

In general these methods work like their old counterparts, but their return values are Promises. The async and await keywords make asynchronous promises easy to work with.  For example:

// ==UserScript==
// @name     GM set/get demo
// @grant    GM.getValue
// @grant    GM.setValue
// ==/UserScript==

(async function() {
console.log('Starting the get/set demo ...');
let i = await GM.getValue('i', 0);
console.log(`This time, i was ${i}.`);
GM.setValue('i', i+1);
})();

Here the GM.getValue() method actually returns a promise, but the await keyword transparently converts that to its resolved value, allowing us to write code just as if the value was directly returned – with neither callbacks nor promise resolution.  See the documentation on async and await.

If you'd like your script to be compatible with Greasemonkey 4 and also Greasemonkey 3 (or other user script engines), we have provided a polyfill, which makes new-style API calls work on top of older engines.  To use it: 1) keep your old-API @grant line, 2) add a new-API @grant line, 4) require the polyfill script, 4) switch your code to use new-API style (and probably async/await).  So the above example might look like:

// ==UserScript==
// @name     GM set/get demo
// @require  https://greasemonkey.github.io/gm4-polyfill/gm4-polyfill.js// @grant    GM.getValue
// @grant    GM_getValue// @grant    GM.setValue
// @grant    GM_setValue
// ==/UserScript==
...

With the exact same new-API style code as above.  Such a script can be installed in either Greasemonkey 4 or Greasemonkey 3 (or TamperMonkey, or ViolentMonkey, etc.) and work as intended.

unsafeWindow

Due to the more limited abilities that the new extension system gives us, we are currently unable to make @grant none scripts work in the same way.  Most importantly, they have a different connection to unsafeWindow.  For the short term at least, it's a good idea to adopt cloneInto and exportFunction.

Naming

Do note that new style APIs have slightly different names.  In short, a consistent naming style has been adopted: all words and acronyms get a consistent case.  So what was before GM_getResourceURL is now GM.getResourceUrl.  What was GM_xmlhttpRequest is now GM_xmlHttpRequest.  In the near future the Greasespot Wiki will be updated with all details of the new APIs, including exact names with case.

Feedback

We welcome feedback, reach out via the greasemonkey-users discussion group.  Please also keep in mind the volunteer nature of this open source project when doing so!

Greasemonkey 4 For Users

As mentioned in the main post, Greasemonkey 4 is changing how it runs user scripts.  Many user scripts will continue to run as expected, but this will break some scripts.  If you rely on such scripts, you might want to install Violentmonkey or Tampermonkey, both of which provide better compatibility for existing scripts.

Scripts

If you'd prefer to stick with Greasemonkey, you'll need to wait for the script to be updated to be compatible.  Find the original author of your script, and ask them to update for Greasemonkey 4 compatibility.  Referencing this post may help.  And please know that we'll continue working to improve further and further as time goes on!

Features

Due to the external deadline (when Firefox 57 comes, Greasemonkey 3 won't work anymore) not all features you're used to are available.  For example: Firefox Sync and script auto update are missing.  There are no per-script settings (custom include/exclude), and some of the UI is still quite basic.  This as well will be improved in the future.

We welcome feedback, reach out via the greasemonkey-users discussion group.  Please also keep in mind the volunteer nature of this open source project when doing so!

Greasemonkey 3.12 Release

The entire list of bugs handled in this release is also available via the 3.12 milestone on GitHub. Note that as always it takes some time for Mozilla to review the new version.  If you're interested in staying on the bleeding edge, try installing the development channel beta release.  If you are using this version and notice problems, it's best to log an issue or let us know at greasemonkey-dev (and be clear that it's with this version).

Fixed bugs:

• Repair rare breakage in GM_getValue/GM_setValue. (#2506) 

New features:

• Migrate existing scripts to a WebExtension (for Firefox 57+) compatible data storage location.  (#2551)

Greasemonkey 3.11 Release

The entire list of bugs handled in this release is also available via the 3.10 milestone on GitHub. Note that as always it takes some time for Mozilla to review the new version.  If you're interested in staying on the bleeding edge, try installing the development channel beta release.  If you are using this version and notice problems, it's best to log an issue or let us know at greasemonkey-dev (and be clear that it's with this version).

Fixed bugs:

• Repair broken language check. (#2488)
• Compatibility with new strict process sandbox. (#2485)

Greasemonkey 3.10 Release

The entire list of bugs handled in this release is also available via the 3.10 milestone on GitHub. Note that as always it takes some time for Mozilla to review the new version.  If you're interested in staying on the bleeding edge, try installing the development channel beta release.  If you are using this version and notice problems, it's best to log an issue or let us know at greasemonkey-dev (and be clear that it's with this version).

Fixed bugs:

• Fix compatibility with Firefox 54. (#2480)

Greasemonkey 3.9 Release

The entire list of bugs handled in this release is also available via the 3.9 milestone on GitHub. Note that as always it takes some time for Mozilla to review the new version.  If you're interested in staying on the bleeding edge, try installing the development channel beta release.  If you are using this version and notice problems, it's best to log an issue or let us know at greasemonkey-dev (and be clear that it's with this version).

Feature enhancements:

• Improve the performance of GM_getValue/GM_setValue. (#2197, #2025)
• Add a rich tooltip to the Greasemonkey toolbar button.  (#2377, #2418)
• GM_getResourceText supports a second (responseType) parameter, for better compatibility with binary files. (#2376)

Fixed bugs:

• Global exclude rules no longer require a Firefox restart to take effect. (#2410)
• A web page whose url ends in ".user.js" could fail to load. (#2407)
• A script whose name ends in ".db" could fail. (#2402)

Greasemonkey 3.8 Release

The entire list of bugs handled in this release is also available via the 3.8 milestone on GitHub. Note that as always it takes some time for Mozilla to review the new version.  If you're interested in staying on the bleeding edge, try installing the development channel beta release.  If you are using this version and notice problems, it's best to log an issue or let us know at greasemonkey-dev (and be clear that it's with this version).

Feature enhancements:

• Scripts can now detect whether they are operating in Private Mode or not. (#2199)

Fixed bugs:

• Corrected a situation wherein some scripts could be executed twice. (#2371) 
• Improved reliability of Sync service. (#2351)
• Improved handling of HTML pages served with .user.js URLs. (#2280)

Greasemonkey 3.7 Release

The entire list of bugs handled in this release is also available via the 3.7 milestone on GitHub. Note that as always it takes some time for Mozilla to review the new version.  If you're interested in staying on the bleeding edge, try installing the development channel beta release.  If you are using this version and notice problems, it's best to log an issue or let us know at greasemonkey-dev (and be clear that it's with this version).

Feature enhancements:

• Added a (subtle) indicator for scripts that can not / will not download updates. (#2358)

Fixed bugs:

• Using @resource URLs for images could fail to work in multi-process Firefox. (#2341)
• Invalid metadata in the template prevented the "New Script" feature. (#2336)
• Drag-and-drop install of a script could launch two install windows. (#2292)

Greasemonkey 3.6 Release

The entire list of bugs handled in this release is also available via the 3.6 milestone on GitHub. Note that as always it takes some time for Mozilla to review the new version.  If you're interested in staying on the bleeding edge, try installing the development channel beta release.  If you are using this version and notice problems, it's best to log an issue or let us know at greasemonkey-dev (and be clear that it's with this version).

Feature enhancements:

• Better support for scripts with a very large number of @include/@exclude/@match rules. (#2318)
• Display a notification to the user when there is a problem parsing an edited script. (#2319)
• In GM_info the serving URL for an @resource is listed. (#2281)
• Added support for @run-at document-idle. (#2109)

Fixed bugs:

• Repair compatibility of @resource files and certain serving contexts for recent versions of Firefox. (#2326)
• Correctly refresh files when changing (e.g.) @require lines in a script. (#2311)
• Repaired binary behavior of GM_xmlhttpRequest. (#2265)

Greasemonkey 3.5 Release

The entire list of bugs handled in this release is also available via the 3.5 milestone on GitHub. Note that as always it takes some time for Mozilla to review the new version.  If you're interested in staying on the bleeding edge, try installing the development channel beta release.  If you are using this version and notice problems, it's best to log an issue or let us know at greasemonkey-dev (and be clear that it's with this version).

Feature enhancements:

• Restored "more" link in Add-ons Manager, add metadata support to fill it. (#1944)
• The Options window can (usually) be resized. (#2194)
• Allow scripting about:reader pages. (#2195) 
• Various performance/efficiency enhancements. (#2243, #2259)
• Allow .cmd file as editor on Windows. (#2271)

Fixed bugs:

• The GM_getValue API behavior matches the documentation. (#2151)
• Repaired the Greasemonkey menus. (#2270, #2273, #2276)

The Location Hack Is Dead

For most of Greasemonkey's history (since version 0.5 in 2005, until version 2.0 in 2014, still today if the script @grants privileged APIs) scripts were guaranteed to operate in a restricted scope.  Interacting with scripts on the page was difficult.  The "location hack" was a technique designed to bridge this gap.

As of Firefox 39.0.3 (due to a security related update) the location hack was broken.  All the user scripts which relied on it broke along with that update.

This post is just to get the word out that the location hack is no longer necessary.  Read more at the wiki's Content Script Injection page, but the short answer is that if your script previously needed the location hack, you should be able to replace it with window.eval() and continue on your way.

Greasemonkey 3.4.1 Release

This is a quick release to fix one data corruption bug introduced in 3.4: Update checks can cause a script to be removed, rather than updated (#2274).

Greasemonkey 3.4 release

The entire list of bugs handled in this release is also available via the 3.4 milestone on GitHub. Note that as always it takes some time for Mozilla to review the new version.  If you're interested in staying on the bleeding edge, try installing the development channel beta release.  If you are using this version and notice problems, it's best to log an issue or let us know at greasemonkey-dev (and be clear that it's with this version).

Feature enhancements:

• Added features to GM_openInTab. (#2257)
• Improved performance and memory efficiency. (#2225, #2237)
• Remember user script sort order. (#2128)

Fixed bugs:

• Work around a Firefox bug that broke GM_openInTab when e10s is not enabled. (#2234)
• Fixed a bug in the "view script source" feature preventing the tab from opening correctly. (#2202)
• Correctly handle uninstalled scripts and user @match preferences through Sync. (#2186, 2188)
• Improved the behavior of cloneInto to work in more cases. (#2070)
• Scripts that are run-at document-start will run on about:blank. (#2041)

Greasemonkey 3.3 Release

The entire list of bugs handled in this release is also available via the 3.2 milestone on GitHub. Note that as always it takes some time for Mozilla to review the new version.  If you're interested in staying on the bleeding edge, try installing the development channel beta release.  If you are using this version and notice problems, it's best to log an issue or let us know at greasemonkey-dev (and be clear that it's with this version).

Feature enhancements:

• Allow the script preference window flex size, especially useful for smaller displays. (#2191)
• The script preference editor now allows editing @match (as well as @include and @exclude like always).  (#2126)
• GM_getResourceURL is now compatible with favicons.  (#1955)
• Web sites should not be able to detect that Greasemonkey is installed. (#1787)

Fixed bugs:

• Web pages whose URLs end with .user.js should load properly. (#2178)
• Repair memory leak related to GM_registerMenuCommand().  (#2067)

Greasemonkey 3.2 Release

The entire list of bugs handled in this release is also available via the 3.2 milestone on GitHub. Note that as always it takes some time for Mozilla to review the new version.  If you're interested in staying on the bleeding edge, try installing the development channel beta release.  If you are using this version and notice problems, it's best to log an issue or let us know at greasemonkey-dev (and be clear that it's with this version).

Feature enhancements:

• The GM_openInTab() API officially supports an open_in_background argument, and always respects user configuration when not specified. (#2105, #2106, #2107)
• The GM_xmlhttpRequest() API is now compatible with responseType: 'arraybuffer'. (#2045)
• Script updates always check the server, never using the browser cache. (#1878)
• Now @match rules can be customized in script settings. (#1703)

Fixed bugs:

• More consistently send cookies  with GM_xmlhttpRequest(). (#2181)
• Calling abort() on the result of GM_xmlhttpRequest() should no longer cause errors. (#2154)
• Fix GM_registerMenuCommand() for @run-at document-start scripts. (#2139)
• Restore operation of the GM_info.version property. (#2132)
• The GM_xmlhttpRequest() API will no longer leak cookies from the regular session, when operating in a Private Browsing session. (#2050)
• Checking for add-on updates will enforce a server timeout, so it does not potentially hang forever. (#2029)
• Repair navigation to HTML pages whose URL happens to end in .user.js. (#1998)

Greasemonkey 3.1 Release

The entire list of bugs handled in this release is also available via the 3.1 milestone on GitHub. Note that as always it takes some time for Mozilla to review the new version.  If you're interested in staying on the bleeding edge, try installing the development channel beta release.  If you are using this version and notice problems, it's best to log an issue or let us know at greasemonkey-dev (and be clear that it's with this version).

This release targets primarily new bugs introduced in version 3.0.

Fixed bugs:

• Fix @noframes feature. (#2110)
• Fix injecting scripts into about:blank. (#2108)
• Display localized script name/description correctly. (#2102)
• Correct GM_openInTab() to only open one tab. (#2094)
• Repair default script editor. (#2073)

Greasemonkey 3.0 Release

Mozilla is planning to add multi process support to Firefox.  Bill McCloskey has a detailed article explaining why.  In short: security, performance, stability.  It just so happens that the underlying Firefox changes drastically affect the inner workings of Greasemonkey.

The Greasemonkey developers have been working hard to rewrite significant portions of the extension.  There are no new features, but the internals have changed quite a lot.  As a result this release is bumping the major version number, to 3.0.

Ideally, you don't notice anything.  Once multi process Firefox is enabled by default, everything should continue to work as normal.  But this is a "point oh" release.  Perhaps we've missed something?  Please let us know if you have any problems!

Note that as always it takes some time for Mozilla to review the new version.  If you're interested in staying on the bleeding edge, try installing the development channel beta release.

Greasemonkey 2.3 Release

The entire list of bugs handled in this release is also available via the 2.2 milestone on GitHub. Note that as always it takes some time for Mozilla to review the new version.  If you're interested in staying on the bleeding edge, try installing the development channel beta release.  If you are using this version and notice problems, it's best to log an issue or let us know at greasemonkey-dev (and be clear that it's with this version).

Enhancements and changes:

• Added @noframes metadata imperative. (#1859)

Fixed bugs:

• Improved disk usage of script values' SQLite databases. (#2036)
• Fixed the responseType feature for GM_xmlhttpRequest(). (#2032)
• Fixed a null variable reference in Firefox Sync. (#2014, #2017)

Greasemonkey 2.2 Release

The entire list of bugs handled in this release is also available via the 2.2 milestone on GitHub. Note that as always it takes some time for Mozilla to review the new version.  If you're interested in staying on the bleeding edge, try installing the development channel beta release.  If you are using this version and notice problems, it's best to log an issue or let us know at greasemonkey-dev (and be clear that it's with this version).

Enhancements and changes:

• Added a "New User Script" button into the Add-ons Manager. (#1972)
• Scripts will always execute (or not) based on their original URL, before any possible history.replaceState() changes by the content scripts. (#1970)
• Script @name and @description values can be localized for multiple languages. (#1963)

Fixed bugs:

• User scripts will never execute with chrome privileges. (#1988)
• Improved Drag-and-Drop into the Add-ons Manager. (#1980)
• Correctly show all Unicode characters when selecting View Script Source. (#1940)
• Repair GM_xmlhttpRequest() for XML type responses. (#1937)
• Fix the position of tabs created with GM_openInTab(). (#1897)
• Do not falsely trigger the install dialog when e.g. editing a script via the GitHub web interface. (#1875)
• Fixed an error when pressing cancel in the install dialog. (#1862)
• GM_log() no longer truncate at NUL bytes. (#1061)