Use external editor to write your user scripts for Tampermonkey!

This tutorial will help you set up comfortable environment for developing Tampermonkey user scripts directly in your editor.

If you are reading this post, you probably already know what you are looking for and so I will cut straight to the chase. Editing Tampermonkey scripts in its built-in editor is pure pain and I am going to show you how to set it up with external editor of your choosing.

Before you start, grant Tampermonkey access to local files. It is not possible to make this work without it. Here’s how you do it:

  1. Click vertical triple-dot icon to open Chrome menu.
  2. More tools > Extensions > Tampermonkey > Details
  3. Scroll down and enable Allow access to file URLs.

Note that this is not something you should be doing without thinking with other extensions. There are security reasons for this to be disabled by default.

Once this is sorted, we can proceed further:

1. Create folder where the user script will be stored: C:\Scripts\FirstScript

2. In the folder, create main user script file: main.js and put your code including the user script header inside. It could look like this:

// ==UserScript==
// @name FirstScript
// @namespace http://tampermonkey.net/
// @version 0.1
// @description Log 'hello world' into console.
// @author You
// @match https://danieldusek.com/*
// @require utils.js
// @grant none
// ==/UserScript==
console.log('Hello world');

if (typeof logExternal === 'function') { // Function defined in utils.js
console.log('Hello from external file.');
} else { console.log('Unable to import utils.js'); }​

3. In Chrome, click Tampermonkey icon and select ‘Create a new script’:

a. Editor with pregenerated code opens. Delete everything.

b. Copy-paste only your user script headers there.

c. Add @require directive to include your main.js file, using file:// protocol and file’s absolute path:

// ==UserScript==
// @name FirstScript
// @namespace http://tampermonkey.net/
// @version 0.1
// @description Log 'hello world' into console.
// @author You
// @match https://danieldusek.com/*
// @require file://C:\Scripts\FirstScript\main.js
// @require file://C:\Scripts\FirstScript\utils.js
// @grant none
// ==/UserScript==​

d. If you have any other @require directives, put the file:// + absolute path in front of the file name too (see the utils.js file in previous code snippet).

4. Save and go load the URL matching value from @match directive header.

5. Code from the C:\Scripts\FirstScript\main.js should load and execute.

And you are done. Whenever you now edit and save the file in its location with the editor of your choice, the Tampermonkey extension will reflect the changes upon reload.

Additional notes that may be relevant to you:

  • In case you are interested in using @require directive to split your user script into multiple files, you can do that as you normally would, but then you have to also update script headers in Tampermonkey accordingly.
  • Do not name your file *.user.js (e.g. not main.user.js). Chrome will mess with loading the file.

Originally published at danieldusek.com.