{"id":15560,"library":"bundlemonkey","title":"Bundlemonkey Userscript Bundler","description":"Bundlemonkey is a userscript bundler designed for fast and efficient development of browser userscripts, leveraging esbuild for lightning-fast compilation. Currently stable at version 0.7.6, the package sees a moderate release cadence, primarily focusing on dependency updates, with occasional feature enhancements and breaking changes between minor versions (e.g., v0.7.0, v0.5.0). Its key differentiators include robust TypeScript support, module bundling capabilities, and a unique feature for type-safe header comments, which streamlines metadata management and reduces errors. It integrates seamlessly with popular userscript managers like Tampermonkey, Violentmonkey, and Greasemonkey, providing a 'watch' mode for continuous development feedback. The project structure encourages modularity, allowing users to define scripts within dedicated source directories.","status":"active","version":"0.7.6","language":"javascript","source_language":"en","source_url":"https://github.com/mkobayashime/bundlemonkey","tags":["javascript","typescript"],"install":[{"cmd":"npm install bundlemonkey","lang":"bash","label":"npm"},{"cmd":"yarn add bundlemonkey","lang":"bash","label":"yarn"},{"cmd":"pnpm add bundlemonkey","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core bundler engine for lightning-fast compilation; internal dependency.","package":"esbuild","optional":false}],"imports":[{"note":"This function is central to defining userscript metadata and the main executable code. Bundlemonkey is primarily designed for ESM projects, so CommonJS 'require' should generally be avoided.","wrong":"const { defineUserScript } = require('bundlemonkey');","symbol":"defineUserScript","correct":"import { defineUserScript } from 'bundlemonkey';"},{"note":"Used for programmatic bundling. The 'bundle' export was deprecated and replaced by 'build' in v0.7.0. The 'build' function now also returns the generated output.","wrong":"import { bundle } from 'bundlemonkey';","symbol":"build","correct":"import { build } from 'bundlemonkey';"},{"note":"Enables programmatic watch mode, rebuilding userscripts automatically on changes. Introduced in v0.7.0 alongside the 'build' function.","wrong":"import { bundle } from 'bundlemonkey';","symbol":"watch","correct":"import { watch } from 'bundlemonkey';"}],"quickstart":{"code":"npx bundlemonkey --create\n# Follow prompts to initialize your project\n\n# Then, open src/your-script-name/index.user.ts and modify it:\n// src/your-script-name/index.user.ts\nimport { defineUserScript } from \"bundlemonkey\";\n\nexport default defineUserScript({\n  name: \"My New Userscript\",\n  version: \"1.0.0\",\n  description: \"A quickstart script.\",\n  match: [\"https://example.com/*\"],\n  grant: [\"none\"], // Explicitly define grants if needed\n  main: () => {\n    console.log(\"Hello from Bundlemonkey!\");\n    document.body.innerHTML += '<h1>Bundlemonkey Quickstart!</h1>';\n  },\n});\n\n# Build the project (output will be in ./dist):\nnpx bundlemonkey","lang":"typescript","description":"Initializes a new Bundlemonkey project from a template, demonstrates how to define a basic userscript with `defineUserScript`, and then builds it using the CLI."},"warnings":[{"fix":"Update programmatic calls from `bundle()` to `build()` or `watch()`. Adjust code to handle the return value of `build()`.","message":"The `bundle` export was removed and replaced by `build` and `watch` functions. Additionally, the `build` function now returns the bundled outputs directly.","severity":"breaking","affected_versions":">=0.7.0"},{"fix":"Explicitly include the `grant` property in `defineUserScript` (e.g., `grant: []` for no grants, or `grant: ['GM_getValue']` for specific ones) to ensure the desired `@grant` headers are present.","message":"If the `grant` property is omitted from `defineUserScript`, no `@grant` header will be output in the bundled userscript. Previously, omitting it might have resulted in a default or different behavior.","severity":"breaking","affected_versions":">=0.5.0"},{"fix":"If using Bundlemonkey programmatically between v0.4.0 and v0.6.x, change `import { main } from 'bundlemonkey'` to `import { bundle } from 'bundlemonkey'`. Note that `bundle` itself was replaced in v0.7.0.","message":"The main programmatic export of the library was renamed from `main` to `bundle`.","severity":"breaking","affected_versions":">=0.4.0 <0.7.0"},{"fix":"Ensure your project is configured for ESM by adding `\"type\": \"module\"` to your `package.json`, or use dynamic `import()` for CommonJS environments.","message":"Bundlemonkey is designed for modern JavaScript environments and uses ESM (ECMAScript Modules) for its exports. Attempting to use `require()` in a CommonJS context without proper configuration can lead to import errors.","severity":"gotcha","affected_versions":">=0.4.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Replace calls to `bundle()` with `build()` or `watch()`. Example: `import { build } from 'bundlemonkey'; build(...)`.","cause":"Attempting to use the deprecated `bundle` API after upgrading to Bundlemonkey v0.7.0 or later.","error":"TypeError: bundlemonkey.bundle is not a function"},{"fix":"Add `import { defineUserScript } from 'bundlemonkey';` to the top of your userscript file.","cause":"`defineUserScript` was not imported from the `bundlemonkey` package.","error":"Error: 'defineUserScript' is not defined"},{"fix":"Ensure you specify the `grant` property in your `defineUserScript` call, e.g., `grant: ['GM_setValue', 'GM_getValue']` or `grant: ['none']`.","cause":"Since v0.5.0, `bundlemonkey` only outputs `@grant` headers if the `grant` property is explicitly provided in `defineUserScript`.","error":"Userscript does not include expected @grant headers in the output."},{"fix":"Ensure your `package.json` contains `\"type\": \"module\"` if you intend to use ESM syntax throughout your project, or convert `import` statements to dynamic `import()` if you must remain in a CommonJS context.","cause":"This error occurs when trying to use ESM `import` syntax (which Bundlemonkey uses) in a CommonJS (`require`) environment without proper configuration.","error":"SyntaxError: Cannot use import statement outside a module"}],"ecosystem":"npm"}