CustomJS for Obsidian

The window.customJS object is available globally and holds instances of your loaded classes. It also contains special properties:

• customJS.state: An object used to persist data. Since window.customJS is overwritten whenever JS files are modified, you should store any data you want to keep in customJS.state.
• customJS.obsidian: Access to the Obsidian API.
• customJS.app: The Obsidian App instance.

Class Properties: For every class MyModule you define, CustomJS adds:

• customJS.MyModule: The singleton instance of your class.
• customJS.createMyModuleInstance: A function to create a new instance (cannot pass arguments to the constructor).

CustomJS only works with JavaScript classes. Each file must contain exactly one class and no other top-level code.

Rules for valid files:

• Must contain a single class Name { ... } definition.
• Do NOT use module.exports.
• Do NOT use bare functions (e.g., function myFunc() {}).
• Do NOT use variable exports (e.g., export const x = 1).
• Do NOT define any code (imports, constants, etc.) outside of the class definition.

Note on Instances: By default, CustomJS initializes every class as a singleton. To create a new, isolated instance, use the naming convention create${ClassName}Instance (e.g., createMyClassInstance()).

// Valid: scripts/MyClass.js
class MyClass {
    doSomething() {
        return "Hello";
    }
}

Because window.customJS is overwritten every time a JS file is modified in your vault, you can define a deconstructor() method in your class to perform cleanup work (like removing event listeners) before the reload occurs.

Example: Implementing a Context Menu entry safely

class AddCustomMenuEntry {
  constructor() {
    this.eventHandler = this.eventHandler.bind(this);
  }

  async invoke() {
    // Register the event when the script is run/loaded
    this.app.workspace.on('file-menu', this.eventHandler);
  }

  deconstructor() {
    // Remove the event listener when the file is reloaded to prevent duplicates
    this.app.workspace.off('file-menu', this.eventHandler);
  }

  eventHandler(menu, file) {
    menu.addItem((item) => {
      item.setTitle('Custom menu entry').onClick(() => { /* logic */ });
    });
  }
}

You can install CustomJS using two methods:

1. Recommended: Search for and install

# Manual installation steps:
# 1. Download latest main.js and manifest.json from releases
# 2. Create folder .obsidian/plugins/customjs
# 3. Place files in that folder

CustomJS allows you to specify which scripts to load via the plugin settings. Use forward slashes (/) for all paths to ensure cross-platform compatibility.

• Individual files: A comma-separated list of specific file paths.
• Folder: A path to a folder. CustomJS will load all *.js files in that folder recursively. Files are loaded in alphabetical order by filename to support dependencies.
• Registered invocable scripts: Bind an Invocable Script to a hotkey.
• Startup scripts: Execute Invocable Scripts when the plugin loads (e.g., for initialization).

To turn a class into a callable command in Obsidian:

1. Ensure your class has an async invoke() method.
2. Open the CustomJS settings.
3. Click "Register invocable script" and select your class from the list.
4. Once registered, the script appears in the Obsidian Command Palette. You can also assign a Hotkey to it via the standard Obsidian Hotkeys settings (search for CustomJS: [YourScriptName]).

An Invocable Script is a class that defines an async invoke() method. These scripts can be triggered via the CustomJS: Invoke Script command, or registered in settings to be bound to specific hotkeys and commands (e.g., CustomJS: MyScriptName).

Example structure:

class MyScript {
    async invoke() {
        // Your logic here
    }
}

You can control which JavaScript files are loaded by the plugin through the CustomJS settings tab. There are two primary ways to specify files:

1. Individual files: Provide a comma-separated list of absolute or relative paths to specific .js files (e.g., scripts/util.js, scripts/math.js).
2. Folder: Provide a folder path. The plugin will automatically load all .js files found within that folder.

If you enable "Re-execute the start scripts when reloading", any scripts listed in your Startup scripts configuration will run again whenever a .js file in your configured paths is modified.

The cJS function is the primary way to interact with loaded CustomJS classes from within Obsidian (e.g., from DataviewJS or other scripts). It ensures that the CustomJS environment is initialized before returning the requested module or the full customJS object.

Usage Patterns:

• Get the full customJS object: Call cJS() without arguments.
• Get a specific class/module: Call cJS('ClassName') to return the class directly.
• Execute a callback with the customJS object: Pass a function to cJS((customJS) => { ... }) to perform operations once the environment is ready.

// Get the entire customJS object
const customJS = await cJS();

// Get a specific class by its name
const MyClass = await cJS('MyClass');

// Use a callback to ensure readiness
await cJS((customJS) => {
  const instance = new customJS.MyClass();
  // ...
});

The window.customJS object is the central registry for all loaded scripts. It contains:

• obsidian: The full Obsidian API object.
• app: The Obsidian App instance.
• state: An object containing internal state, including state._ready (boolean indicating if loading is complete).
• [ClassName]: The class constructor itself.
• create[ClassName]Instance: A function that returns a new instance of [ClassName].