### BundleMonkey Configuration Example

Source: https://github.com/mkobayashime/bundlemonkey/blob/main/README.md

An example configuration file (`bundlemonkey.config.ts`) demonstrating how to set up `srcDir`, `dist`, and `defaultMeta`.

```APIDOC
## Configuration File Example

### Description
This example shows a typical `bundlemonkey.config.ts` file, illustrating the structure and available options for configuring BundleMonkey.

### Method
N/A (Configuration File)

### Endpoint
N/A (Configuration File)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```typescript
import type { Config } from "bundlemonkey";

const config: Config = {
  srcDir: "src", // default value
  dist: {
    dev: ".dev", // default value
    production: "dist", // default value
  },
  defaultMeta: {
    author: "John Doe",
    namespace: "johndoe",
    homepage: "https://github.com/johndoe/userscripts",
    updateURL: ({ scriptName }) =>
      `https://github.com/johndoe/userscripts/raw/main/dist/${scriptName}.user.js`,
    downloadURL: ({ scriptName }) =>
      `https://github.com/johndoe/userscripts/raw/main/dist/${scriptName}.user.js`,
  },
};

export default config;
```

### Response
N/A (Configuration File)

#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Start Watch Mode

Source: https://github.com/mkobayashime/bundlemonkey/blob/main/templates/template-typescript/README.md

Enables development mode to automatically rebuild on file changes.

```bash
npm run watch
# or
npm run watch:remote
```

--------------------------------

### Define Basic User Script with Bundlemonkey

Source: https://context7.com/mkobayashime/bundlemonkey/llms.txt

Example of a basic userscript entry point using defineUserScript. Ensure the 'name', 'version', and 'match' properties are set.

```typescript
import { defineUserScript } from "bundlemonkey";
import { message } from "./message.js";

export default defineUserScript({
  name: "Hello world",
  version: "0.1.0",
  description: "Hello from Bundlemonkey!",
  match: ["https://example.com/*"],
  main: () => {
    window.alert(message);
  },
});
```

--------------------------------

### Define User Script with Run-At and Injection Options

Source: https://context7.com/mkobayashime/bundlemonkey/llms.txt

Configures when and how a userscript executes using 'runAt', 'sandbox', 'injectInto', 'noframes', and 'topLevelAwait' properties. This example sets the script to run at 'document-start' in the page context and enables top-level await.

```typescript
import { defineUserScript } from "bundlemonkey";

export default defineUserScript({
  name: "Injection Example",
  version: "1.0.0",
  match: ["https://example.com/*"],

  // When to run: "document-start", "document-end", "document-idle", "document-body", "context-menu"
  runAt: "document-start",

  // Sandbox mode: "raw", "JavaScript", "DOM"
  sandbox: "JavaScript",

  // Injection context: "page", "content", "auto"
  injectInto: "page",

  // Don't run in iframes
  noframes: true,

  // Enable top-level await
  topLevelAwait: true,

  main: async () => {
    // Script runs at document-start in page context
    await someAsyncSetup();
  },
});
```

--------------------------------

### Install Bundlemonkey Manually

Source: https://github.com/mkobayashime/bundlemonkey/blob/main/README.md

Add the package to your project dependencies using your preferred package manager.

```bash
npm install --save bundlemonkey

# or like
pnpm add bundlemonkey
bun add bundlemonkey
```

--------------------------------

### Define User Script with Type-Safe Grants

Source: https://context7.com/mkobayashime/bundlemonkey/llms.txt

Example of defining userscript grants using the 'grant' property for type-safe access to Tampermonkey, Violentmonkey, and Greasemonkey APIs. The 'connect' property specifies allowed hostnames for cross-origin requests.

```typescript
import { defineUserScript } from "bundlemonkey";

export default defineUserScript({
  name: "API Example",
  version: "1.0.0",
  match: ["https://example.com/*"],
  // Type-safe grant array with autocomplete
  grant: [
    "GM_setValue",
    "GM_getValue",
    "GM_xmlhttpRequest",
    "GM_notification",
    "GM_setClipboard",
    "GM_addStyle",
    "unsafeWindow",
  ],
  // Or disable all grants
  // grant: "none",
  connect: ["api.example.com", "cdn.example.com"],
  main: () => {
    // Use granted APIs
    GM_setValue("key", "value");
    const stored = GM_getValue("key", "default");

    GM_xmlhttpRequest({
      method: "GET",
      url: "https://api.example.com/data",
      onload: (response) => {
        console.log(response.responseText);
      },
    });
  },
});
```

--------------------------------

### Initialize a New Project

Source: https://github.com/mkobayashime/bundlemonkey/blob/main/README.md

Create a new project using the interactive template command.

```bash
npx bundlemonkey --create

# or like
pnpx bundlemonkey --create
bunx bundlemonkey --create
```

--------------------------------

### Build Project

Source: https://github.com/mkobayashime/bundlemonkey/blob/main/README.md

Compile your source scripts into the distribution directory.

```bash
npx bundlemonkey

# or like
pnpx bundlemonkey
bunx bundlemonkey
```

--------------------------------

### Project Directory Structure

Source: https://github.com/mkobayashime/bundlemonkey/blob/main/README.md

Recommended file layout for organizing source scripts and build outputs.

```bash
├── src/ # configurable
│   ├── script-a/
│   │   ├── index.user.ts
│   │   └── some-module.ts
│   └── script-b/
│       └── index.user.ts
├── dist/ # configurable
│   └── # bundled code goes here
├── bundlemonkey.config.ts # optional
└── package.json
```

--------------------------------

### Configuration Options

Source: https://github.com/mkobayashime/bundlemonkey/blob/main/README.md

Detailed explanation of the configuration options available for BundleMonkey.

```APIDOC
## Configuration Options

### srcDir

- **type**: `string`
- **Default**: `"src"`

Directory where your source scripts are located.

> [!NOTE]
> The glob for collecting the source files is like: `<cwd>/<srcDir>/*/index.user.{ts,js}`

### dist

- **type**: `object`

#### dist.dev

- **type**: `string`
- **Default**: `".dev"`

Dist directory in watch mode.

#### dist.production

- **type**: `string`
- **Default**: `"dist"`

### defaultMeta

- **type**: `object`
- **Default**: `undefined`

Default meta used for all userscripts. Metadata defined in [`defineUserScript`](#props-of-defineuserscript) overrides this.

All meta properties in [`defineUserScript`](#props-of-defineuserscript) can be used here as well, while `updateURL`/`downloadURL` have different signatures like below.

#### defaultMeta.updateURL

- **type**: `(args: { scriptName: string; version: string }) => string`
- **Default**: `undefined`

#### defaultMeta.downloadURL

- **type**: `(args: { scriptName: string; version: string }) => string`
- **Default**: `undefined`
```

--------------------------------

### Build Userscripts

Source: https://github.com/mkobayashime/bundlemonkey/blob/main/templates/template-typescript/README.md

Compiles the project into a distributable bundle.

```bash
npm run build
```

--------------------------------

### Bundlemonkey CLI usage

Source: https://github.com/mkobayashime/bundlemonkey/blob/main/README.md

Run the bundlemonkey command with optional flags for development modes.

```bash
bundlemonkey [--watch [--remote]] [--create]
```

--------------------------------

### CLI Usage Commands

Source: https://context7.com/mkobayashime/bundlemonkey/llms.txt

Common command-line interface operations for building, watching, and scaffolding projects.

```bash
# Production build - compiles all scripts to dist/
npx bundlemonkey

# Watch mode - rebuilds on change, copies to clipboard
npx bundlemonkey --watch

# Remote watch mode - uses file:// require for auto-reload
npx bundlemonkey --watch --remote

# Create new project from template
npx bundlemonkey --create
```

--------------------------------

### build

Source: https://context7.com/mkobayashime/bundlemonkey/llms.txt

Programmatic API for building userscripts in production mode.

```APIDOC
## build

### Description
Compiles all source scripts and writes them to the output directory.

### Parameters
#### Request Body
- **config** (object) - Optional - Configuration object containing srcDir, dist paths, and defaultMeta
```

--------------------------------

### Compiled Output of Hello World Userscript

Source: https://context7.com/mkobayashime/bundlemonkey/llms.txt

This is the JavaScript output generated by Bundlemonkey for the 'Hello world' userscript. It includes the userscript metadata header and the main function execution.

```javascript
// ==UserScript==
// @name         Hello world
// @version      0.1.0
// @description  Hello from Bundlemonkey!
// @match        https://example.com/*
// ==/UserScript==

var message = "Hello from bundlemonkey!";
void (() => {
  window.alert(message);
})();
```

--------------------------------

### BundleMonkey Configuration

Source: https://github.com/mkobayashime/bundlemonkey/blob/main/README.md

Configure source and distribution directories, and default metadata for userscripts. The updateURL and downloadURL functions allow dynamic generation of URLs based on script name and version.

```typescript
import type { Config } from "bundlemonkey";

const config: Config = {
  srcDir: "src", // default value
  dist: {
    dev: ".dev", // default value
    production: "dist", // default value
  },
  defaultMeta: {
    author: "John Doe",
    namespace: "johndoe",
    homepage: "https://github.com/johndoe/userscripts",
    updateURL: ({ scriptName }) =>
      `https://github.com/johndoe/userscripts/raw/main/dist/${scriptName}.user.js`,
    downloadURL: ({ scriptName }) =>
      `https://github.com/johndoe/userscripts/raw/main/dist/${scriptName}.user.js`,
  },
};

export default config;
```

--------------------------------

### Define Userscript with Configuration

Source: https://github.com/mkobayashime/bundlemonkey/blob/main/README.md

Pass a configuration object to the main function to manage script-specific settings.

```typescript
import { defineUserScript } from "bundlemonkey";

export default defineUserScript({
  name: "Sample userscript",
  version: "1.0.0",
  description: "Write userscripts with ease using bundlemonkey!",
  match: ["https://example.com/*"],
  config: {
    message: "hello!",
  },
  main: (config) => {
    // your main code here!
    console.log(config.message)
  },
});
```

--------------------------------

### Configure Bundlemonkey

Source: https://context7.com/mkobayashime/bundlemonkey/llms.txt

Define project-wide settings using the Config interface in bundlemonkey.config.ts.

```typescript
import type { Config } from "bundlemonkey";

const config: Config = {
  // Source directory containing userscript folders
  srcDir: "src",

  // Output directories
  dist: {
    production: "dist",  // Production builds
    dev: ".dev",         // Watch mode builds
  },

  // Default metadata applied to all scripts
  defaultMeta: {
    author: "John Doe",
    namespace: "johndoe",
    homepage: "https://github.com/johndoe/userscripts",

    // Dynamic URL generation based on script name and version
    updateURL: ({ scriptName, version }) =>
      `https://github.com/johndoe/userscripts/raw/main/dist/${scriptName}.user.js`,
    downloadURL: ({ scriptName, version }) =>
      `https://github.com/johndoe/userscripts/raw/main/dist/${scriptName}.user.js`,
  },
};

export default config;
```

--------------------------------

### Define User Script with Configurable Properties

Source: https://context7.com/mkobayashime/bundlemonkey/llms.txt

Demonstrates using the 'config' property to define user-configurable values. These values are hoisted to the top of the compiled script for easy access and modification by end-users. Configuration values are fully typed.

```typescript
import { defineUserScript } from "bundlemonkey";

export default defineUserScript({
  name: "Configurable Script",
  version: "1.0.0",
  match: ["https://example.com/*"],
  config: {
    /**
     * Whether to enable feature X
     * @type boolean
     */
    FEATURE_X_ENABLED: true,
    /**
     * Maximum number of retries
     * @type number
     */
    MAX_RETRIES: 3,
    /**
     * Custom selector for target element
     * @type string
     */
    TARGET_SELECTOR: ".main-content",
  },
  main: ({ FEATURE_X_ENABLED, MAX_RETRIES, TARGET_SELECTOR }) => {
    if (FEATURE_X_ENABLED) {
      const element = document.querySelector(TARGET_SELECTOR);
      // Config values are fully typed!
    }
  },
});
```

--------------------------------

### Define a userscript with configuration

Source: https://github.com/mkobayashime/bundlemonkey/blob/main/README.md

Use defineUserScript to structure your userscript. The config object is automatically exposed as a global variable for user modification.

```typescript
export default defineUserScript({
  // ...
  config: {
    /**
     * Edit this to change the message
     * @type string
     */
    message: "hello!"
  },
  main: (config) => {
    window.alert(config.message);
  },
});
```

```typescript
// ==UserScript==
// ...
// ==/UserScript==

var userscriptConfig = {
  /**
   * Edit this to change the message
   * @type string
   */
  message: "hello!"
};

void ((config) => {
  window.alert(config.message);
})(userscriptConfig);
```

--------------------------------

### Watch Mode Development

Source: https://context7.com/mkobayashime/bundlemonkey/llms.txt

Use the watch function to monitor source files and trigger rebuilds automatically.

```typescript
import { watch } from "bundlemonkey";

// Standard watch mode - copies bundled script to clipboard on change
await watch({
  remote: false,
});

// Remote watch mode - uses @require for automatic browser reloading
await watch({
  remote: true,
  config: {
    srcDir: "src",
    dist: {
      dev: ".dev",
    },
  },
});
```

--------------------------------

### watch

Source: https://context7.com/mkobayashime/bundlemonkey/llms.txt

Programmatic API for watch mode development.

```APIDOC
## watch

### Description
Monitors source files and automatically rebuilds on changes.

### Parameters
#### Request Body
- **remote** (boolean) - Optional - If true, uses @require for automatic browser reloading
- **config** (object) - Optional - Configuration object
```

--------------------------------

### Build Userscripts Programmatically

Source: https://context7.com/mkobayashime/bundlemonkey/llms.txt

Use the build function to compile userscripts for production or with custom configurations.

```typescript
import { build } from "bundlemonkey";

// Build all userscripts in src/ directory
const results = await build({});

// Build with custom configuration
const results = await build({
  config: {
    srcDir: "scripts",
    dist: {
      production: "output",
      dev: ".dev",
    },
    defaultMeta: {
      author: "John Doe",
      namespace: "johndoe",
    },
  },
});

// Process build results
for (const result of results) {
  if (result) {
    console.log(`Built: ${result.path}`);
    console.log(`Content length: ${result.content.length}`);
  }
}
```

--------------------------------

### Define a Userscript with TypeScript

Source: https://github.com/mkobayashime/bundlemonkey/blob/main/README.md

Use defineUserScript to export your userscript configuration and main logic as the default export.

```typescript
// src/sample/message.ts

export const message = "Hello from sample script and bundlemonkey!";
```

```typescript
// src/sample/index.user.ts

import { defineUserScript } from "bundlemonkey";
import { message } from "./message";

export default defineUserScript({
  name: "Sample userscript",
  version: "1.0.0",
  description: "Write userscripts with ease using bundlemonkey!",
  match: ["https://example.com/*"],
  main: () => {
    console.log(message);
  },
});
```

--------------------------------

### defineUserScript Configuration

Source: https://github.com/mkobayashime/bundlemonkey/blob/main/README.md

Defines the structure and required properties for the defineUserScript function used to create userscripts.

```APIDOC
## defineUserScript Configuration

### Description
The defineUserScript function is the primary entry point for creating userscripts. It accepts a configuration object containing metadata and the main execution logic.

### Parameters
#### Request Body
- **name** (string) - Required - The name of the userscript.
- **version** (string) - Required - The version of the userscript.
- **main** ((config: T) => unknown) - Required - The main function containing the script logic.
- **config** (T) - Optional - Configuration object modifiable by users.
- **namespace** (string) - Optional - The namespace of the script.
- **copyright** (string) - Optional - Copyright information.
- **description** (string) - Optional - Description of the script.
- **icon** (string) - Optional - URL to the script icon.
- **grant** (Grant[] | "none") - Optional - Permissions granted to the script.
- **author** (string) - Optional - Author name.
- **homepage** (string) - Optional - Homepage URL.
- **antiFeature** (AntiFeature[]) - Optional - Anti-feature declarations.
- **require** (string[]) - Optional - External scripts to require.
- **resource** ({ name: string; url: string; }[]) - Optional - External resources.
- **match** (string[]) - Optional - URL patterns to match.
- **excludeMatch** (string[]) - Optional - URL patterns to exclude.
- **include** (string[]) - Optional - URL patterns to include.
- **exclude** (string[]) - Optional - URL patterns to exclude.
- **runAt** (RunAt) - Optional - When the script should run.
- **runIn** (string[]) - Optional - Contexts where the script runs.
- **sandbox** ("raw" | "JavaScript" | "DOM") - Optional - Sandbox mode.
- **injectInto** ("page" | "content" | "auto") - Optional - Injection mode.
- **tag** (string[]) - Optional - Tags for the script.
- **connect** (string[]) - Optional - Domains allowed for GM_xmlhttpRequest.
- **noframes** (boolean) - Optional - Whether to run in frames.
- **updateURL** (string) - Optional - URL for updates.
- **downloadURL** (string) - Optional - URL for downloads.
- **supportURL** (string) - Optional - URL for support.
- **unwrap** (boolean) - Optional - Whether to unwrap the script.
- **topLevelAwait** (boolean) - Optional - Whether to enable top-level await.
```

--------------------------------

### Compiled Output with Hoisted Config

Source: https://context7.com/mkobayashime/bundlemonkey/llms.txt

Shows how the 'config' properties defined in the userscript are hoisted to the top of the compiled JavaScript file as a 'userscriptConfig' object.

```javascript
// var userscriptConfig = {
//   FEATURE_X_ENABLED: true,
//   MAX_RETRIES: 3,
//   TARGET_SELECTOR: ".main-content"
// };
```

--------------------------------

### Define a Userscript with defineUserScript

Source: https://context7.com/mkobayashime/bundlemonkey/llms.txt

Use defineUserScript to configure metadata and the main execution logic for a userscript.

```typescript
import { defineUserScript } from "bundlemonkey";

export default defineUserScript({
  name: "My Userscript",
  version: "1.0.0",
  description: "A sample userscript with full configuration",
  match: ["https://example.com/*", "https://example.org/*"],
  excludeMatch: ["https://example.com/admin/*"],
  icon: "https://example.com/favicon.ico",
  author: "Your Name",
  namespace: "your-namespace",
  runAt: "document-end",
  grant: ["GM_setValue", "GM_getValue", "GM_xmlhttpRequest"],
  connect: ["api.example.com"],
  config: {
    /**
     * Enable debug logging
     * @type boolean
     */
    DEBUG: false,
    /**
     * API endpoint URL
     * @type string
     */
    API_URL: "https://api.example.com",
  },
  main: ({ DEBUG, API_URL }) => {
    if (DEBUG) console.log("Script loaded!");

    // Your userscript code here
    document.addEventListener("DOMContentLoaded", () => {
      console.log(`Using API: ${API_URL}`);
    });
  },
});
```

--------------------------------

### Define RunAt types

Source: https://github.com/mkobayashime/bundlemonkey/blob/main/README.md

Specify the injection timing for the userscript.

```typescript
type RunAt =
  | "document-end"
  | "document-start"
  | "document-body"
  | "document-idle"
  | "context-menu";
```

--------------------------------

### Compiled Userscript Output

Source: https://github.com/mkobayashime/bundlemonkey/blob/main/README.md

The resulting bundle generated by Bundlemonkey, including the header metadata and bundled source code.

```typescript
// ==UserScript==
// @name         Sample userscript
// @version      1.0.0
// @description  Write userscripts with ease using bundlemonkey!
// @match        https://example.com/*
// ==/UserScript==

// src/sample/message.ts
var message = "Hello from sample script and bundlemonkey!";

// src/sample/index.user.ts
void (() => {
  console.log(message);
})();
```

--------------------------------

### Define Grant types

Source: https://github.com/mkobayashime/bundlemonkey/blob/main/README.md

Specify required GM APIs or window methods in the Grant type definition.

```typescript
type Grant =
  | "unsafeWindow"
  | "GM_addElement"
  | "GM_addStyle"
  // ...
  | "GM.addStyle"
  | "GM.setValue"
  // ...
  | "window.onurlchange"
  | "window.close"
  | "window.focus";
```

--------------------------------

### defineUserScript

Source: https://context7.com/mkobayashime/bundlemonkey/llms.txt

The main function for defining a userscript with type-safe metadata and entry point.

```APIDOC
## defineUserScript

### Description
Defines a userscript with metadata and a main entry point function.

### Parameters
#### Request Body
- **name** (string) - Required - Userscript name
- **version** (string) - Required - Version string
- **description** (string) - Optional - Script description
- **match** (string[]) - Optional - URL patterns to match
- **excludeMatch** (string[]) - Optional - URL patterns to exclude
- **icon** (string) - Optional - Icon URL
- **author** (string) - Optional - Author name
- **namespace** (string) - Optional - Namespace
- **runAt** (string) - Optional - Execution timing
- **grant** (string[]) - Optional - GM functions to grant
- **connect** (string[]) - Optional - Allowed domains for GM_xmlhttpRequest
- **config** (object) - Optional - Custom configuration object
- **main** (function) - Required - The entry point function executed when the script runs
```

--------------------------------

### Define AntiFeature types

Source: https://github.com/mkobayashime/bundlemonkey/blob/main/README.md

Define anti-feature metadata for the userscript.

```typescript
type AntiFeature = {
  type: "ads" | "tracking" | "miner";
  description: string;
};
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.