BetterCurseForge/docs/api/index.md

API Reference

BetterCurseForge adds a global object, window.BetterCurseForge, to CurseForge's Electron renderer process. Themes, plugins and your own scripts can use it to inject styles, patch methods, read and write settings, and listen for events.

---

TypeScript definitions

If you're using TypeScript, this gives you types and autocompletion:

declare global {
  interface Window {
    BetterCurseForge: BetterCurseForgeAPI;
  }
}

export interface BetterCurseForgeAPI {
  /** Active BetterCurseForge runtime version */
  readonly version: string;

  /** Injects CSS dynamically into <head>. Returns an unmount callback. */
  injectCSS(css: string): () => void;

  /** Persistent settings storage */
  settings: {
    get(key?: string): Promise<any>;
    set(key: string, value: any): Promise<boolean>;
  };

  /** Runtime method interception and monkey-patching */
  patcher: {
    before(obj: any, method: string, callback: (args: any[]) => void): () => void;
    after(obj: any, method: string, callback: (args: any[], result: any) => any): () => void;
    instead(obj: any, method: string, callback: (args: any[], original: Function) => any): () => void;
  };

  /** Event bus */
  on(event: string, callback: (...args: any[]) => void): void;
  off(event: string, callback: (...args: any[]) => void): void;
  emit(event: string, ...args: any[]): void;

  /** Internal subsystem managers */
  themes: ThemeManager;
  plugins: PluginManager;
  ads: AdBlocker;
}

---

Core API

BetterCurseForge.version

• Type: string
• Description: Version of the BetterCurseForge runtime that's currently running.

console.log(BetterCurseForge.version); // "1.0.0"

---

BetterCurseForge.injectCSS(css)

Adds CSS rules to the document <head>.

• Parameters:
  • css (string): The CSS to inject.
• Returns: () => void. Call it to remove the injected <style> tag.

// Inject styles
const uninject = BetterCurseForge.injectCSS(`
  .some-container {
    background-color: #1a102f !important;
  }
`);

// Later, remove the styles
uninject();

---

Settings API (BetterCurseForge.settings)

Persistent configuration, stored in %APPDATA%\CurseForge\BetterCurseForge\settings.json.

settings.get(key?)

Returns the setting for key, or the whole settings object if you don't pass a key.

• Parameters:
  • key (string, optional): Name of the setting.
• Returns: Promise<any>. The value, or null if it isn't set.

// Retrieve a specific value
const activeTheme = await BetterCurseForge.settings.get('activeCustomTheme');

// Retrieve all settings
const allSettings = await BetterCurseForge.settings.get();

settings.set(key, value)

Saves a value and writes it to disk asynchronously.

• Parameters:
  • key (string): Name of the setting.
  • value (any): Any JSON-serializable value.
• Returns: Promise<boolean>. true if the save worked.

await BetterCurseForge.settings.set('myPlugin.fontSize', 14);

---

Patcher API (BetterCurseForge.patcher)

Utilities for inspecting, modifying or replacing methods on JavaScript objects and modules. Every function returns an unpatch function.

patcher.before(obj, method, callback)

Runs callback(args) before the target method is called.

• Parameters:
  • obj (object): Target object.
  • method (string): Method name on obj.
  • callback (Function): (args) => void.
• Returns: () => void. Call it to restore the original method.

const unpatch = BetterCurseForge.patcher.before(console, 'warn', (args) => {
  console.log('[Warn Interceptor]', ...args);
});

// Revert patch:
unpatch();

---

patcher.after(obj, method, callback)

Runs callback(args, result) after the target method. Return a value to replace the method's return value.

• Parameters:
  • obj (object): Target object.
  • method (string): Method name on obj.
  • callback (Function): (args, result) => any.
• Returns: () => void. Unpatch function.

const unpatch = BetterCurseForge.patcher.after(service, 'getTitle', (args, result) => {
  return `Prefix: ${result}`;
});

unpatch();

---

patcher.instead(obj, method, callback)

Replaces the target method. The callback gets the arguments and a reference to the original method.

• Parameters:
  • obj (object): Target object.
  • method (string): Method name on obj.
  • callback (Function): (args, originalFn) => any.
• Returns: () => void. Unpatch function.

const unpatch = BetterCurseForge.patcher.instead(target, 'openExternalUrl', (args, originalFn) => {
  const url = args[0];
  if (url.startsWith('https://safe-domain.com')) {
    return originalFn(...args);
  }
  console.warn('Blocked external URL navigation:', url);
});

unpatch();

---

Event system (BetterCurseForge.on / off / emit)

BetterCurseForge has an event bus that plugins can use to talk to each other and to react to lifecycle events.

BetterCurseForge.on(event, callback)

Adds a listener for an event.

const onReady = () => console.log('BetterCurseForge is ready!');
BetterCurseForge.on('ready', onReady);

BetterCurseForge.off(event, callback)

Removes a listener.

BetterCurseForge.off('ready', onReady);

BetterCurseForge.emit(event, ...args)

Calls every listener registered for the event.

BetterCurseForge.emit('custom-event', { detail: 123 });

---

Subsystem managers

BetterCurseForge.themes (ThemeManager)

Control custom themes from code:

// Get all discovered themes
const themes = BetterCurseForge.themes.getThemes();

// Get active theme filename (or null)
const currentTheme = BetterCurseForge.themes.getActiveThemeName();

// Preview a theme temporarily on screen
BetterCurseForge.themes.previewTheme(themes[0]);

// Revert preview back to active theme
BetterCurseForge.themes.cancelPreview();

// Apply and save a theme permanently
BetterCurseForge.themes.applyTheme(themes[0], true);

// Remove custom theme and revert to native CurseForge skin
BetterCurseForge.themes.removeTheme(true);

BetterCurseForge.plugins (PluginManager)

Control plugins from code:

// Get all installed plugins
const plugins = BetterCurseForge.plugins.getPlugins();

// Toggle a plugin by folder name
await BetterCurseForge.plugins.togglePlugin('compact-mode');

BetterCurseForge.ads (AdBlocker)

The internal ad blocker runtime:

// Contains zero-ad CSS rules and ad container cleanup handlers
console.log(BetterCurseForge.ads);