How can I develop my userscript in my favourite IDE and avoid copy-pasting it to the Tampermonkey's editor every time?

Question

For security reasons, Tampermonkey scripts are not saved in accessible files, but in a plugin data. The only way to edit them is to use Tampermonkey's integrated editor.

However, I'd rather use IDE, with all its features. I also want to use webpack to pack the script from multiple files.

To do that, I need a way to programmatically change the script in Tampermonkey to a new version. So far, what I did was manually copy & paste the new script into Tampermonkey's editor and that's really exhausting.

How can I do this automatically?

Answer 1

I found my own way to it, so it's not official or anything, feel free to make your own adjustments. You'll be able to code in your editor and see the changes reflected in the browser without a nuisance.

Set up

We'll make our TM script to be without code but @require a local file. This way we can edit it locally and changes will take effect on browser reload, without copy-pasting.

1. Go to Chrome -> Extensions (or paste 'chrome://extensions' to your URL bar) and find the TamperMonkey 'card'. Click details. On the page that opens, allow it access to file URLs:

2. Save your script file wherever you want in your filesystem. Save the entire thing, including the ==UserScript== header. I'm using macOS, so my path is: /Users/me/Scripts/SameWindowHref.user.js

3. Now, go to the TM's dashboard in your browser, open the script in question in its TM editor and delete everything except the entire ==UserScript== header

4. Add to the header a @require property pointing to the script's absolute path.

At this point, TM's editor should look something like this:

Possible gotcha: Using the file:// URI scheme at the beginning of your @require path is now required. On Windows systems would be:

// @require      file://C:\path\to\userscript.user.js

For macOS and *nix, you need three slashes in a row:

// @require      file:///path/to/userscript.user.js

Execution Contexts

If you have multiple JavaScript files, each specified with a @require key, it is important to understand how and when each script is executed. This is important when using external libraries (like jQuery), or when breaking up the monolith of a script you have there in a few files.

The @require paths can reference *.user.js or simply *.js files, and any UserScript-style comment headers in these files have no effect.

From the main script's ==UserScript== header, all @require files are text-concatenated in the order specified, with a single newline separating each file. This amalgamation is then executed as one large script. Note that this means any function or variable declared in the outermost scope of any file behaves as if it was declared in the outermost scope of every file, and certain syntactic errors in one file may influence how subsequent files are interpreted. Additionally, to enable Strict mode on all of your files, 'use strict'; must be the first statement of the first @require'd file.

After all the @require files are run, the primary UserScript (the one accessed by TamperMonkey's editor) is run in a separate context. If Strict mode is desired, it must also be enabled here.

Given such opportunity for confusion, it is good practice for each file to wrap all code within an IIFE (and a function-level 'use strict';) in order to limit the scope to individual files.

Workflow

Now every time that script matches (@match), TamperMonkey will directly load and run the code straight from the file on disk, whichever path is in @require.

I use VSCode, so that's where I work on the script, but any text editor will do. It should look like this:

Notice how TM's editor and your IDE/Editor have the same header. You can now close the TM's editor. If everything is correct, you won't need it open anymore.

Now, every change in the code is saved automatically by this particular editor. If yours doesn't autosave, remember to save before going to the browser to test it.

Lastly, you'll have to reload the website to see the changes, just like before.

Bonus tips

Consider using it git. It's not beginner-friendly but it will make you look cool, helps to have a sane development experience (can roll back changes and easily try parallel ideas), and if you pair it with GitHub you can release new updates to your future users for free.

Working with GitHub (or other SCMs)

You have to add an @updateURL tag followed by the URL with the raw file from GitHub or whatever provider you chose. GitHub's example:

Note that a @version tag is required to make update checks work. The vast majority of devs won't need the @downloadURL tag, so unless your script has a massive follower base, use @updateURL.

TM will check for updates as often as it's configured; from the settings tab:

Externals sets how often the scripts called from your script's @require are checked to update (e.g., jQuery).

You can also "force" an update check:

Using external libraries (like jQuery)

It must be present in at least the header shown in TM's editor for Chrome to load it. However, I recommend keeping both headers the same (the shown in TM and the local file) to avoid confusion and maybe weird bugs. Then, you just @require it like this:

// @require      https://cdnjs.cloudflare.com/ajax/libs/jquery/3.4.1/jquery.min.js

RTFM

Take a look at TM's documentation page; it doesn't bite! It's actually very concise, and with a quick read you'll have a big picture of what you can do without much effort!

Answer 2

in server mode, you can add your code entry as script src

// ==UserScript==
// @name               dev:example
// @namespace          https://github.com/lisonge
// @version            1.0.1
// @author             lisonge
// @description        default description zh
// @icon               https://vitejs.dev/logo.svg
// @match              https://i.songe.li/
// @grant              GM.info
// @grant              GM.deleteValue
// @grant              GM.getValue
// @grant              GM.listValues
// @grant              GM.setValue
// @grant              GM.getResourceUrl
// @grant              GM.notification
// @grant              GM.openInTab
// @grant              GM.registerMenuCommand
// @grant              GM.setClipboard
// @grant              GM.xmlHttpRequest
// @grant              unsafeWindow
// @grant              window.close
// @grant              window.focus
// @grant              GM_info
// @grant              GM_getValue
// @grant              GM_setValue
// @grant              GM_deleteValue
// @grant              GM_listValues
// @grant              GM_addValueChangeListener
// @grant              GM_removeValueChangeListener
// @grant              GM_getResourceText
// @grant              GM_getResourceURL
// @grant              GM_addElement
// @grant              GM_addStyle
// @grant              GM_openInTab
// @grant              GM_registerMenuCommand
// @grant              GM_unregisterMenuCommand
// @grant              GM_notification
// @grant              GM_setClipboard
// @grant              GM_xmlhttpRequest
// @grant              GM_download
// @grant              GM.addStyle
// @grant              GM.addElement
// @grant              window.onurlchange
// @grant              GM_log
// @grant              GM_getTab
// @grant              GM_saveTab
// @grant              GM_getTabs
// @grant              GM_cookie
// ==/UserScript==

;(({
  entryList = [],
  mountGmApi = false
}) => {
  window.GM;
  const monkeyWindow = window;
  if (mountGmApi) {
    const _unsafeWindow = Reflect.get(monkeyWindow, "unsafeWindow");
    if (_unsafeWindow) {
      Reflect.set(_unsafeWindow, "unsafeWindow", _unsafeWindow);
      console.log(`[vite-plugin-monkey] mount unsafeWindow to unsafeWindow`);
      const mountedApiList = [];
      Object.entries(monkeyWindow).filter(([k]) => k.startsWith("GM")).forEach(([k, fn]) => {
        Reflect.set(_unsafeWindow, k, fn);
        mountedApiList.push(k);
      });
      console.log(
        `[vite-plugin-monkey] mount ${mountedApiList.length} GM_api to unsafeWindow`
      );
    }
  }
  (() => {
    Object.defineProperty(document, "__monkeyWindow", {
      value: monkeyWindow,
      writable: false,
      enumerable: false
    });
    console.log(`[vite-plugin-monkey] mount monkeyWindow to document`);
  })();
  const createScript = (src) => {
    const el = document.createElement("script");
    el.src = src;
    el.type = "module";
    el.dataset.source = "vite-plugin-monkey";
    el.dataset.entry = "";
    return el;
  };
  const { head } = document;
  entryList.reverse().forEach((s) => {
    head.insertBefore(createScript(s), head.firstChild);
  });
  console.log(
    `[vite-plugin-monkey] mount ${entryList.length} entry module to document.head`
  );
})({
  "entryList": [
    "http://127.0.0.1:5173/@vite/client",
    "http://127.0.0.1:5173/src/main.ts"
  ],
  "mountGmApi": false
});

now you can use My library vite-plugin-monkey, its consistent with the normal web app development experience, just like vue/react

Hot Module Replacement

Answer 3

You can use the ViolentMonkey extension instead of TamperMonkey. ViolentMonkey has a feature to regularly check for updates to a local file, making the development process much more streamlined.

During the installation of the userscript, simply check the "Track local file before this window is closed" checkbox and leave the installation dialog tab open. The userscript will be automatically updated when changes are made to the file on disk, without any user intervention required. Simply refresh the page on which the script is running, and the new version of the userscript will be loaded.

Here is a screenshot of the "Track local file" checkbox in the ViolentMonkey installation dialog:

Answer 4

to the @require-approach in Carles' answer I'd like to add a rather nice solution for Firefox devs (or any other) where local file access is not possible:

use nginx as a simple local HTTP server as follows:

• download nginx and unzip somewhere, e.g. C:\nginx

• adjust <nginx-dir>/conf/nginx.conf to serve your projects (e.g. C:\my-project\src\tampermonkey.myapp.js) scripts directly and immediately (no caching) on access:

  server {
    ...
    location / {
      #root   html;
      root    C:/my-project/;
      ...
  
      # kill cache
      expires -1;
  

• start nginx, e.g. via cmd /c "C:\nginx\nginx.exe"

  • (stop it later e.g. via cmd /c "C:\nginx\nginx.exe -s stop")

• change the @require accordingly (removing everything below //==/UserScript==) (and save it):

  // ==UserScript==
  //@name         My App Addon
  //@match        http://foo
  //@require      http://localhost/src/tampermonkey.myapp.js
  //==/UserScript==
  

• done

Answer 5

I would indeed use @require, but if you have design changes also use GM_addStyle

// @require     file:///
// @grant       GM_addStyle

Answer 6

Trim21 provides, probably the best large-scale UserScript development solution so far, using webpack to cooperate LiveReloadPlugin realizes modular development and automated testing.

Here is the project.

It can use ES5/ES6 and TypeScript to develop modular scripts on IDE. It's really easy to use!

Integrated LiveReloadPlugin, you can directly refresh any @matchURL.

It is better than the previous scheme, which greatly improves the development efficiency of UserScript！

Answer 7

Rather than setting up Nginx, or having to configure Chrome to allow local files you can just use ngrok to proxy the local files.

This example assumes your files are in the /dist directory and you have installed nodejs.

npx serve -p 5000 ./dist & npx ngrok http 5000 --log stdout

or using package.json which you can run using npm start:

  "scripts": {
    "start": "npm-run-all -l -p serve watch ngrok",
    "build": "webpack",
    "watch": "webpack --watch",
    "serve": "npx serve -p 5000 ./dist",
    "ngrok": "ngrok http 5000 --log stdout"
  },

This will serve the files on port 5000 and give you the external URL, look for this line in the console output:

addr=http://localhost:5000 url=https://101b-110-150-114-111.ngrok.io

Then create a userscript like this:

// ==UserScript==
// @name         Script Name
// @namespace    http://example.com/
// @version      0.1
// @description  Description
// @author       Your Name
// @match        https://example.com/*
// @grant        none
// ==/UserScript==

(function() {
  var ngrokUrl = 'https://101b-110-150-114-111.ngrok.io'; // <-- Update this
  var remoteScript = document.createElement('script');
  remoteScript.src = ngrokUrl  + '/bundle.js?ts='+(+new Date());
  document.body.appendChild(remoteScript);
})();

This will inject a script stored in ./dist/bundle.js and reload it everytime the page refreshes.

Note If you don't sign up for ngrok account your connection will time out after two hours and you will need to restart it and update the ngrokUrl URL.

Answer 8

Hack around: I needed to reference a static image file, so I converted the image to a base64 string and then added it directly to the script. I believe, a similar approach could also work for other files of small size.