Vite-plugin-tm-userscript NPM

vite-plugin-tm-userscript

npm.io npm.io npm.io

English | 中文

Recommended to use vite-plugin-monkey
推荐使用功能更丰富的 vite-plugin-monkey

Tampermonkey userscript developing & build plugin based on vite.

Features

Configure Tampermonkey's Userscript Header via a separate config file or the tmHeader field in package.json
Automatically add used grant when building for production
Import all grant by default in development mode, and add all grant methods to unsafeWindow
Through simple configuration, the imported external package can be require and automatically imported UNPKG CDN, see the plugin configuration below for details

Usage

Install

yarn add vite-plugin-tm-userscript -D
# OR
npm install vite-plugin-tm-userscript -D

Configure `vite.config.ts`

import { defineConfig } from 'vite'
import Userscript from 'vite-plugin-tm-userscript'

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    Userscript({
      externalGlobals: ['vue']
    })
  ]
})

Configure Userscript Header

There are five ways to configure Userscript Header, the priority is as follows

Plugin option headers
header.config.json
header.config.js
header.config.txt
tmHeader field in package.json

Among them, header.config.txt uses Tampermonkey header annotation configuration, will not be processed, directly inserted into the script header

The other four formats are configured in json format, and multiple attribute configurations such as match are represented by an array, and grant and require are automatically added after processing

See example/header.config.js for example configuration

For specific property configuration, see Tampermonkey Documentation

Plugin Configuration

export interface TMPluginOptions {
  entry?: string;
  autoGrant?: boolean;
  headers?: TmHeaderConfig;
  externalGlobals?: string[] | Record<string, string | string[]>;
}

`headers`

See Configure Userscript Header

For example

// vite.config.js
import { defineConfig } from 'vite'
import Userscript from 'vite-plugin-tm-userscript'

export default defineConfig({
  plugins: [
    Userscript({
      entry: 'main.js',
      headers: {
        name: 'Test',
        namespace: 'https://www.nanoka.top',
        author: 'asadahimeka',
        description: 'No description',
        source: 'https://github.com/asadahimeka/userscripts',
        supportURL: 'https://github.com/asadahimeka/userscripts/issues',
        license: 'MIT',
        match: 'https://test.com/*',
        require: 'https://lib.baomitu.com/arrive/2.4.1/arrive.min.js',
        'run-at': 'document-start',
      },
    }),
  ],
})

`externalGlobals`

Configure external packages, such as vue, axios, etc., to reduce the package size, and automatically declare require

Three configuration forms, CDN can be customized, if CDN is not configured, UNPKG CDN is used by default

// 1
Userscript({
  externalGlobals: ['jquery']
})

// 2
Userscript({
  externalGlobals: {
    'jquery': 'jQuery'
  }
})

// 3
Userscript({
  externalGlobals: {
    'jquery': ['jQuery', 'https://cdn.bootcdn.net/ajax/libs/jquery/3.6.0/jquery.min.js']
  }
})

// =>

return {
  rollupOptions: {
    external: ['jquery']
    output: {
      globals: {
        jquery: 'jQuery'
      }
    }
  }
}

// @require https://cdn.bootcdn.net/ajax/libs/jquery/3.6.0/jquery.min.js

`autoGrant`

boolean type, defaults to true

Automatically analyze the Tampermonkey grant used in the code and add it to the Userscript Header declaration

`entry`

Entry file, default is src/main.js or src/main.ts

Example

See the example folder

Notice

Vite Configuration Additional Instructions

Production build mode will force the configuration of config.build:

Camel case of the name (required) attribute of the package name package.json to build, and the file name to build is also related to it
The file packaging format is iife, no compression, no separation of css files
Additionally configured rollupOptions to support other features

Disable CSP(Content-Security-Policy)

In development mode, the script of vite needs to be injected through the script tag. Some websites have enabled CSP(Content-Security-Policy), resulting in an error. You can install the Chrome plugin Disable Content-Security-Policy or Always Disable Content-Security-Policy, to disable CSP(Content-Security-Policy), open the plug-in during development (remember to close it at other times to ensure the security of web browsing).

Also, you can change Tampermonkey options(open extension://iikmkjmpaadaobahmlepeloendndfphd/options.html#nav=settings) at Security, set Modify existing content security policy (CSP) headers to Remove entirely (possibly unsecure).