BetterCurseForge/docs/api/index.md

API Reference

BetterCurseForge exposes a global runtime object on window.BetterCurseForge within the CurseForge Electron renderer process. This API allows themes, plugins, and developer scripts to inject styles, monkey-patch methods, manage settings, and listen to application events.

---

TypeScript Definition

For TypeScript development 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: The currently running BetterCurseForge runtime version.

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

---

BetterCurseForge.injectCSS(css)

Dynamically injects CSS rules into the document <head>.

• Parameters:
  • css (string): Raw CSS string to inject.
• Returns: () => void — Function that removes the injected <style> tag when called.

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

// Later, remove the styles
uninject();

---

Settings API (BetterCurseForge.settings)

Manages persistent configuration stored in %APPDATA%\CurseForge\BetterCurseForge\settings.json.

settings.get(key?)

Retrieves a setting by key, or returns the entire settings object if no key is specified.

• Parameters:
  • key (string, optional): Setting key name.
• Returns: Promise<any> — Value of the setting, or null.

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

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

settings.set(key, value)

Stores a setting value and writes it asynchronously to disk.

• Parameters:
  • key (string): Setting key name.
  • value (any): JSON-serializable value.
• Returns: Promise<boolean> — true if saved successfully.

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

---

Patcher API (BetterCurseForge.patcher)

Provides monkey-patching utilities to inspect, modify, or replace methods on JavaScript objects and modules safely.

patcher.before(obj, method, callback)

Executes callback(args) before the target method is invoked.

• Parameters:
  • obj (object): Target object.
  • method (string): Method name on obj.
  • callback (Function): Function receiving arguments: (args) => void.
• Returns: () => void — Unpatch function that restores the original method.

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

// Revert patch:
unpatch();

---

patcher.after(obj, method, callback)

Executes callback(args, result) after the target method runs. You can return a new 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)

Completely overrides the target method. Receives both the incoming 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 includes an event bus for inter-plugin and lifecycle communication.

BetterCurseForge.on(event, callback)

Subscribes a listener to an event.

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

BetterCurseForge.off(event, callback)

Unsubscribes a listener.

BetterCurseForge.off('ready', onReady);

BetterCurseForge.emit(event, ...args)

Emits an event to all registered listeners.

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

---

Subsystem Managers

BetterCurseForge.themes (ThemeManager)

Provides programmatic control over custom themes:

// 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)

Provides programmatic control over plugins:

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

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

BetterCurseForge.ads (AdBlocker)

Internal ad blocker runtime:

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