{"id":15364171,"url":"https://github.com/kellnerd/userscript-bundler","last_synced_at":"2025-04-15T09:29:57.226Z","repository":{"id":153230904,"uuid":"628247426","full_name":"kellnerd/userscript-bundler","owner":"kellnerd","description":"Node.js tools to build userscripts and bookmarklets from ES modules","archived":false,"fork":false,"pushed_at":"2024-11-21T11:49:51.000Z","size":88,"stargazers_count":9,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-28T18:51:48.918Z","etag":null,"topics":["bookmarklet","bookmarklet-generator","bundler","userscript","userscript-builder"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kellnerd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-04-15T11:03:38.000Z","updated_at":"2024-12-10T19:21:10.000Z","dependencies_parsed_at":"2024-01-29T22:29:48.143Z","dependency_job_id":"bc010818-0d6c-462d-bc7c-0988097c2669","html_url":"https://github.com/kellnerd/userscript-bundler","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kellnerd%2Fuserscript-bundler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kellnerd%2Fuserscript-bundler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kellnerd%2Fuserscript-bundler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kellnerd%2Fuserscript-bundler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kellnerd","download_url":"https://codeload.github.com/kellnerd/userscript-bundler/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249042668,"owners_count":21203332,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bookmarklet","bookmarklet-generator","bundler","userscript","userscript-builder"],"created_at":"2024-10-01T13:10:27.704Z","updated_at":"2025-04-15T09:29:57.205Z","avatar_url":"https://github.com/kellnerd.png","language":"JavaScript","readme":"# userscript-bundler\n\nNode.js tools to build userscripts and bookmarklets from ES modules.\n\n## Features\n\n- Bundle multiple JavaScript modules into a single userscript (or bookmarklet) using [rollup](https://www.rollupjs.org/)\n- Generate userscript metadata blocks automatically with default values\n- Minify bookmarklets using [terser](https://terser.org/)\n- Generate a README file with descriptions, userscript install buttons and bookmarklet code blocks\n\nThe default build function provides all these features, but you can also write your own based on the provided tools.\n\n## Usage\n\n1. Install the package:\n\n\t```sh\n\tnpm install --save-dev kellnerd/userscript-bundler\n\t```\n\n\tYou can also install a specific version with `npm install --save-dev kellnerd/userscript-bundler#v0.8.5` (where the part after the hash can be any tag or commit).\n\n2. Create a build script and save it, e.g. as `build.js`:\n\n\t```js\n\timport { build } from '@kellnerd/userscript-bundler';\n\n\tbuild({\n\t\t// default values below, you can leave out options unless you want to change them\n\t\tuserscriptSourcePath: 'src/userscripts/',\n\t\tbookmarkletSourcePath: null,\n\t\t// bookmarklets are optional and have to be enabled:\n\t\t// bookmarkletSourcePath: './src/bookmarklets/',\n\t\tdocSourcePath: 'doc/',\n\t\toutputPath: 'dist/',\n\t\treadmePath: 'README.md',\n\t});\n\t```\n\n3. Move the introduction of your previous README file into `doc/_header.md` or create this file.\n\n\tThe build script in this example will automatically generate your README file and use `doc/_header.md` as the document header.\n\tAll other Markdown files in the specified doc folder will be appended to the end of the final README.\n\n4. Create a new module which serves as entry point of your userscript in your userscript source folder, e.g. `example.user.js`:\n\n\t```js\n\tconsole.log('Hello world!');\n\t```\n\n5. Specify the userscript's metadata in an accompanying `example.meta.js` file:\n\n\t```js\n\t/** @type {import('@kellnerd/userscript-bundler').EnhancedUserscriptMetadata} */\n\tconst metadata = {\n\t\tname: 'Example',\n\t\tauthor: 'John Doe', // optional, falls back to your GitHub username\n\t\tdescription: 'Enhances the functionality of example.com.',\n\t\tmatch: '*://example.com/*',\n\t};\n\n\texport default metadata;\n\t```\n\n6. 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):\n\t1. Specify your userscript's features in the `EnhancedUserscriptMetadata.features` property (in `example.meta.js`).\n\t2. Create a Markdown file with the same basename in your documentation folder (`doc/example.md`).\n\n7. *(Optional)* Create a new module which serves as entry point of your bookmarklet in your bookmarklet source folder, e.g. `exampleBookmarklet.js`:\n\n\t```js\n\t/** \n\t * The first block comment in this file will be used as description of the bookmarklet.\n\t * The name of the bookmarklet will be the title-cased version of the camel-cased filename,\n\t * i.e. \"Example Bookmarklet\" for this example.\n\t */\n\t\n\tconsole.log('Hello world!');\n\t```\n\n8. Ensure that your `package.json` file contains the URL of your GitHub repository, it is needed to automatically generate update URLs for your userscripts.\n\n\t```jsonc\n\t{\n\t\t// ...\n\t\t\"repository\": {\n\t\t\t\"type\": \"git\",\n\t\t\t\"url\": \"https://github.com/\u003cusername\u003e/\u003crepository\u003e.git\"\n\t\t},\n\t\t\"type\": \"module\",\n\t\t\"devDependencies\": {\n\t\t\t\"@kellnerd/userscript-bundler\": \"github:kellnerd/userscript-bundler\",\n\t\t\t// ...\n\t\t}\n\t}\n\t```\n\n9.  Now you can execute your build script: `node build.js`\n\n\tIt will create bundled versions of all your userscripts in the `outputPath` folder and add a section to the README for each script.\n\n\tIn 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.\n\nIf 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`.\nThe result will be output directly on screen and no files will be modified.\n\n## Showcases\n\nIf 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.\n\n- https://github.com/kellnerd/musicbrainz-scripts\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkellnerd%2Fuserscript-bundler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkellnerd%2Fuserscript-bundler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkellnerd%2Fuserscript-bundler/lists"}