BetterCurseForge/docs/guide/plugins.md

# Writing Plugins

Plugins are small JavaScript modules that run inside CurseForge. They can change the DOM, patch methods at runtime, and save settings between sessions.

---

## Plugin folder

Plugins live in the BetterCurseForge user directory:

```text
%APPDATA%\CurseForge\BetterCurseForge\plugins\
```

Each plugin gets its own subfolder:

```text
plugins/
└── compact-mode/
    ├── manifest.json       # Required: Plugin metadata
    ├── index.js            # Required: Entry script
    └── styles.css          # Optional: Companion stylesheet
```

The **Open Plugins Folder** button in the desktop app opens it.

---

## Manifest (`manifest.json`)

`manifest.json` describes the plugin:

```json
{
  "id": "compact-mode",
  "name": "Compact Mode",
  "version": "1.0.0",
  "description": "Reduces padding across mod lists, sidebar items, and modpack details for high-density browsing.",
  "author": "ModderDev",
  "main": "index.js",
  "styles": "styles.css"
}
```

### Fields

| Field | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `name` | `string` | **Yes** | Name shown in the management UI. |
| `version` | `string` | **Yes** | Semantic version (e.g. `1.0.0`). |
| `description` | `string` | No | Short summary of what the plugin does. |
| `author` | `string` | No | Author name or handle. |
| `main` | `string` | No | Entry script. Defaults to `index.js`. |
| `styles` | `string` | No | Stylesheet that's injected automatically when the plugin is enabled. Defaults to `styles.css`. |

---

## Lifecycle

A plugin's script runs when the plugin is enabled. It gets the `BetterCurseForge` API and a `plugin` context object:

```javascript
// index.js
// BetterCurseForge passes (BetterCurseForge, plugin)
const { injectCSS, patcher, settings, on, off } = BetterCurseForge;

console.log('[MyPlugin] Plugin initialized!');

// Attach an onDisable cleanup handler:
plugin.onDisable = () => {
  console.log('[MyPlugin] Plugin disabled! Cleaning up...');
  // Remove any custom DOM elements, event listeners, or intervals here
};
```

::: tip STYLESHEETS
If your plugin folder has a `styles.css` (or the file named in `"styles"` in `manifest.json`), BetterCurseForge injects it into `<head>` when the plugin is enabled and removes it when the plugin is disabled. You don't need to inject or clean it up yourself.
:::

---

## Plugin API

### 1. `BetterCurseForge.injectCSS(css)`
Injects CSS into `<head>`. Returns a function that removes the style tag:

```javascript
const removeStyles = BetterCurseForge.injectCSS(`
  .addon-row { padding: 4px 8px !important; }
`);

// Later in cleanup:
plugin.onDisable = () => {
  removeStyles();
};
```

---

### 2. `BetterCurseForge.settings`
Reads and writes settings that are saved to disk (`settings.json`):

```javascript
// Retrieve a stored setting (or null if not set)
const isCustomFont = await BetterCurseForge.settings.get('compactMode.customFont');

// Store a setting
await BetterCurseForge.settings.set('compactMode.density', 'ultra');
```

---

### 3. `BetterCurseForge.patcher`
Helpers for monkey-patching methods on objects. Each call returns a function that undoes the patch:

#### `patcher.before(object, methodName, callback)`
Runs your callback before the original method. The callback gets `(args)`:

```javascript
const unpatch = BetterCurseForge.patcher.before(console, 'error', (args) => {
  console.warn('[Intercepted Console Error]', ...args);
});

plugin.onDisable = () => unpatch();
```

#### `patcher.after(object, methodName, callback)`
Runs after the original method. The callback gets `(args, result)` and can return a new value to replace the result:

```javascript
const unpatch = BetterCurseForge.patcher.after(targetObj, 'getItemTitle', (args, result) => {
  return `⚡ ${result}`;
});

plugin.onDisable = () => unpatch();
```

#### `patcher.instead(object, methodName, callback)`
Replaces the original method. The callback gets `(args, originalMethod)`:

```javascript
const unpatch = BetterCurseForge.patcher.instead(targetObj, 'fetchData', (args, originalFn) => {
  console.log('Intercepting fetchData call...');
  return originalFn(...args);
});

plugin.onDisable = () => unpatch();
```

---

### 4. `BetterCurseForge.on(event, callback)` / `.off()` / `.emit()`
An event emitter shared across the app:

```javascript
const onReady = () => console.log('CurseForge UI is fully loaded!');

BetterCurseForge.on('ready', onReady);

plugin.onDisable = () => {
  BetterCurseForge.off('ready', onReady);
};
```

---

## Example: Compact Mode

This plugin makes CurseForge's layout denser.

::: code-group

```json [manifest.json]
{
  "id": "compact-mode",
  "name": "Compact Mode",
  "version": "1.0.0",
  "description": "Reduces margins and padding for high-density modpack browsing.",
  "author": "BetterCurseForge Team",
  "main": "index.js",
  "styles": "styles.css"
}
```

```javascript [index.js]
// Add compact layout class to the document root
document.documentElement.classList.add('bcf-compact-layout');

console.log('[Compact Mode] Activated');

// Clean up when toggled off
plugin.onDisable = () => {
  document.documentElement.classList.remove('bcf-compact-layout');
  console.log('[Compact Mode] Deactivated');
};
```

```css [styles.css]
/* Automatically injected when plugin is enabled */
.bcf-compact-layout .tile-view-item {
  width: 150px !important;
  height: 240px !important;
}

.bcf-compact-layout .action-button-container {
  height: 48px !important;
  margin: 6px 0 !important;
}

.bcf-compact-layout .details-title {
  font-size: 13px !important;
}
```

:::