Userscript-builder NPM

userscript-builder

Simple tool for building userscript for tampermonkey.

ES6 modules are not supported.

Simple configuration.
Uses ES6 classes syntax.
Support css files.
No webpack
No babel
The only one third party dependency

Don't forget import css files via import 'some-css.css'. Extension is required.

Table of Content

Getting Started

Prerequisites

It works with NodeJS v10.16.0 or higher. Lower versions of NodeJS wasn't tested.

Install

Install with npm:

npm install --save-dev userscript-builder

Install with yarn:

yarn add userscript-builder --dev

Or you can use npx as well

npx userscript-builder --mode dev

Setup

Update your package.json scripts section (provide aliases)

{
  "scripts": {
    "build": "userscript-builder --mode dev",
    "release:bugfix": "userscript-builder --mode bugfix",
    "release:minor": "userscript-builder --mode minor",
    "release:major": "userscript-builder --mode major"
  }
}

Update your package.json with userscript section

{
  "name": "git-name",
  "version": "0.0.0",
  "description": "Describe your user script",
  "author": "va4ok",
  "license": "MIT",
  "userscript": {
    "entry": "./src/index.js",     // Entry file
    "dev": "./dist",               // Output folder for dev builds
    "release": "./release",        // Output folder for release builds
    "fileName": "filename",        // Output filename -> filename.user.js
    "meta": {                      // Userscript meta info
      "name": "User script name",
      "namespace": "http://tampermonkey.net/",
      "homepage": "https://openuserjs.org/scripts/va4ok",
      "match": "*://*.*",
      "grant": "none",
      "require": [
        "https://some.url.1",
        "https://some.url.2"
      ]
    }
  }
}

Fields version, description, author, license will be used in output meta.

Default properties if not specified

{
  "entry": "./src/index.js",
  "dev": "./dist",
  "release": "./release",
  "fileName": "new-userscript",

  "name": "New Userscript",
  "namespace": "http://tampermonkey.net/",
  "version": "0.0.0",
  "description": "try to take over the world!",
  "author": "You",
  "match": "http://*/*",
  "grant": "none"
}

Please visit https://www.tampermonkey.net/ for more details and options.

Build options

Dev

No version changes.

In result file will be added comments with included file location

npm run userscript-builder --mode dev
# or
npx userscript-builder --mode dev

Release-bugfix (patch)

New patch version will be increased and commited into package.json file

From result file will be removed single and multi line comments

npm run userscript-builder --mode bugfix
# or
npm run userscript-builder --mode bug
# 2.7.1 -> 2.7.2

Release-minor

New minor version will be increased and commited into package.json file

From result file will be removed single and multi line comments

npm run userscript-builder --mode minor
# or
npm run userscript-builder --mode min
2.7.1 -> 2.8.0

Release-major

New major version will be increased and commited into package.json file

From result file will be removed single and multi line comments

npm run userscript-builder --mode major
# or
npm run userscript-builder --mode maj
2.7.1 -> 3.0.0

How it works

Create your entry file with selfexecuted function

import { Class1 } from './class1/class1.js';
import { StaticClass } from './static-class/static-class.js';

(function () {
  'use strict';

  const class1 = new Class1();

  class1.doSomething();
  StaticClass.saySomething();
})();

Use ES6 classes and imports to organize you code.

import { StaticClass } from './../static-class/static-class.js';
import './class1.css';

const CLASS1_CONST = 200;
 
 export class Class1 {
   doSomething() {
     console.log('Class 1');
   }
 }

Build your user script and publish on https://openuserjs.org

// ==UserScript==
// @name         User script name
// @namespace    http://tampermonkey.net/
// @version      0.0.1
// @description  description
// @author       va4ok
// @match        *://*.*
// @grant        none
// @source       https://github.com/va4ok/userscript-builder.git
// @license      MIT
// @homepage     https://openuserjs.org/scripts/va4ok
// @require      https://some.url.1
// @require      https://some.url.2
// ==/UserScript==

// src/static-class/static-class.js
class StaticClass {
  static saySomething() {
    console.log('static class method');
  }
}

// src/class1/class1.js
const CLASS1_CONST = 200;

class Class1 {
  doSomething() {
    console.log('Class 1');
  }
}

// ./src/index.js
let notificator;

(function () {
  'use strict';

  const class1 = new Class1();

  class1.doSomething();
  StaticClass.saySomething();
})();

// CSS injection
(function(){
  const $style = document.createElement('style');

  $style.innerHTML = `/* src/class1/class1.css */
.class1-container {
  transition: height 1s ease-out;
  background-color: #3dcd59;
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  overflow: hidden;
  height: 0;
  z-index: 1000;
}`;
  document.body.appendChild($style);
})();