Bundlemonkey Userscript Bundler

Common errors

• TypeError: bundlemonkey.bundle is not a function

  cause Attempting to use the deprecated `bundle` API after upgrading to Bundlemonkey v0.7.0 or later.
  fix Replace calls to `bundle()` with `build()` or `watch()`. Example: `import { build } from 'bundlemonkey'; build(...)`.

• Error: 'defineUserScript' is not defined

  cause `defineUserScript` was not imported from the `bundlemonkey` package.
  fix Add `import { defineUserScript } from 'bundlemonkey';` to the top of your userscript file.

• Userscript does not include expected @grant headers in the output.

  cause Since v0.5.0, `bundlemonkey` only outputs `@grant` headers if the `grant` property is explicitly provided in `defineUserScript`.
  fix Ensure you specify the `grant` property in your `defineUserScript` call, e.g., `grant: ['GM_setValue', 'GM_getValue']` or `grant: ['none']`.

• SyntaxError: Cannot use import statement outside a module

  cause This error occurs when trying to use ESM `import` syntax (which Bundlemonkey uses) in a CommonJS (`require`) environment without proper configuration.
  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.

Warnings

• breaking The `bundle` export was removed and replaced by `build` and `watch` functions. Additionally, the `build` function now returns the bundled outputs directly.
  Fix: Update programmatic calls from `bundle()` to `build()` or `watch()`. Adjust code to handle the return value of `build()`.
• breaking 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.
  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.
• breaking The main programmatic export of the library was renamed from `main` to `bundle`.
  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.
• gotcha 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.
  Fix: Ensure your project is configured for ESM by adding `"type": "module"` to your `package.json`, or use dynamic `import()` for CommonJS environments.

Install

• npm install bundlemonkey npm
• yarn add bundlemonkey yarn
• pnpm add bundlemonkey pnpm

Imports

• defineUserScript
  wrong:

  const { defineUserScript } = require('bundlemonkey');

  correct:

  import { defineUserScript } from 'bundlemonkey';

  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.
• build
  wrong:

  import { bundle } from 'bundlemonkey';

  correct:

  import { build } from 'bundlemonkey';

  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.
• watch
  wrong:

  import { bundle } from 'bundlemonkey';

  correct:

  import { watch } from 'bundlemonkey';

  Enables programmatic watch mode, rebuilding userscripts automatically on changes. Introduced in v0.7.0 alongside the 'build' function.

Quickstart

Initializes a new Bundlemonkey project from a template, demonstrates how to define a basic userscript with `defineUserScript`, and then builds it using the CLI.

npx bundlemonkey --create
# Follow prompts to initialize your project

# Then, open src/your-script-name/index.user.ts and modify it:
// src/your-script-name/index.user.ts
import { defineUserScript } from "bundlemonkey";

export default defineUserScript({
  name: "My New Userscript",
  version: "1.0.0",
  description: "A quickstart script.",
  match: ["https://example.com/*"],
  grant: ["none"], // Explicitly define grants if needed
  main: () => {
    console.log("Hello from Bundlemonkey!");
    document.body.innerHTML += '<h1>Bundlemonkey Quickstart!</h1>';
  },
});

# Build the project (output will be in ./dist):
npx bundlemonkey