Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/kellnerd/userscript-bundler
Node.js tools to build userscripts and bookmarklets from ES modules
https://github.com/kellnerd/userscript-bundler
bookmarklet bookmarklet-generator bundler userscript userscript-builder
Last synced: 2 days ago
JSON representation
Node.js tools to build userscripts and bookmarklets from ES modules
- Host: GitHub
- URL: https://github.com/kellnerd/userscript-bundler
- Owner: kellnerd
- License: mit
- Created: 2023-04-15T11:03:38.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-03-05T16:12:18.000Z (7 months ago)
- Last Synced: 2024-04-16T08:58:51.736Z (6 months ago)
- Topics: bookmarklet, bookmarklet-generator, bundler, userscript, userscript-builder
- Language: JavaScript
- Homepage:
- Size: 84 KB
- Stars: 7
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# userscript-bundler
Node.js tools to build userscripts and bookmarklets from ES modules.
## Features
- Bundle multiple JavaScript modules into a single userscript (or bookmarklet) using [rollup](https://www.rollupjs.org/)
- Generate userscript metadata blocks automatically with default values
- Minify bookmarklets using [terser](https://terser.org/)
- Generate a README file with descriptions, userscript install buttons and bookmarklet code blocks
The default build function provides all these features, but you can also write your own based on the provided tools.
## Usage
1. Install the package:
```sh
npm install --save-dev kellnerd/userscript-bundler
```
You can also install a specific version with `npm install --save-dev kellnerd/userscript-bundler#v0.8.4` (where the part after the hash can be any tag or commit).
2. Create a build script and save it, e.g. as `build.js`:
```js
import { build } from '@kellnerd/userscript-bundler';
build({
// default values below, you can leave out options unless you want to change them
userscriptSourcePath: 'src/userscripts/',
bookmarkletSourcePath: null,
// bookmarklets are optional and have to be enabled:
// bookmarkletSourcePath: './src/bookmarklets/',
docSourcePath: 'doc/',
outputPath: 'dist/',
readmePath: 'README.md',
});
```
3. Move the introduction of your previous README file into `doc/_header.md` or create this file.
The build script in this example will automatically generate your README file and use `doc/_header.md` as the document header.
All other Markdown files in the specified doc folder will be appended to the end of the final README.
4. Create a new module which serves as entry point of your userscript in your userscript source folder, e.g. `example.user.js`:
```js
console.log('Hello world!');
```
5. Specify the userscript's metadata in an accompanying `example.meta.js` file:
```js
/** @type {import('@kellnerd/userscript-bundler').EnhancedUserscriptMetadata} */
const metadata = {
name: 'Example',
author: 'John Doe', // optional, falls back to your GitHub username
description: 'Enhances the functionality of example.com.',
match: '*://example.com/*',
};
export default metadata;
```
6. If you want to include additional documentation besides the brief userscript description in the generated README, there are two possibilities (which are not mutually exclusive):
1. Specify your userscript's features in the `EnhancedUserscriptMetadata.features` property (in `example.meta.js`).
2. Create a Markdown file with the same basename in your documentation folder (`doc/example.md`).
7. *(Optional)* Create a new module which serves as entry point of your bookmarklet in your bookmarklet source folder, e.g. `exampleBookmarklet.js`:
```js
/**
* The first block comment in this file will be used as description of the bookmarklet.
* The name of the bookmarklet will be the title-cased version of the camel-cased filename,
* i.e. "Example Bookmarklet" for this example.
*/
console.log('Hello world!');
```
8. Ensure that your `package.json` file contains the URL of your GitHub repository, it is needed to automatically generate update URLs for your userscripts.
```jsonc
{
// ...
"repository": {
"type": "git",
"url": "https://github.com//.git"
},
"type": "module",
"devDependencies": {
"@kellnerd/userscript-bundler": "github:kellnerd/userscript-bundler",
// ...
}
}
```
9. Now you can execute your build script: `node build.js`
It will create bundled versions of all your userscripts in the `outputPath` folder and add a section to the README for each script.
In case you have created an identically named bookmarklet, it will be included in the same section, all other bookmarklets have separate sections after the userscript sections.
If you want to compile a single minified bookmarklet from a module or a standalone JavaScript file you can alternatively run `node bookmarkletify.js exampleBookmarklet.js`.
The result will be output directly on screen and no files will be modified.
## Showcases
If you are using this package to build your own userscripts or bookmarklets, you can create a pull request to be included in the following list.
- https://github.com/kellnerd/musicbrainz-scripts