logseq/libs/development-notes/experiments_api_guide.md

Logseq Experiments API Guide

This guide covers the experimental APIs available in the Logseq Plugin SDK. These APIs provide advanced functionality for creating custom renderers, loading external scripts, and accessing internal utilities.

⚠️ WARNING: These are experimental features that may change at any time. Plugins using these APIs may not be supported on the Marketplace temporarily.

---

Overview

The Experiments API is accessed via logseq.Experiments and provides:

1. React Integration - Access to React and ReactDOM from the host
2. Custom Renderers - Register custom code block, route, and daemon renderers
3. Component Access - Access to internal Logseq components
4. Utilities - ClojureScript interop utilities (toClj, toJs, etc.)
5. Script Loading - Dynamic loading of external scripts
6. Extension Enhancers - Enhance libraries like KaTeX and CodeMirror

---

1. React Integration

Access React and ReactDOM from the Logseq host environment.

Properties

logseq.Experiments.React

Returns the React instance from the host scope.

const React = logseq.Experiments.React

logseq.Experiments.ReactDOM

Returns the ReactDOM instance from the host scope.

const ReactDOM = logseq.Experiments.ReactDOM

Example Usage

const React = logseq.Experiments.React
const ReactDOM = logseq.Experiments.ReactDOM

// Use React to create components
const MyComponent = React.createElement('div', null, 'Hello from plugin!')

---

2. Components

Access internal Logseq components for advanced UI integration.

logseq.Experiments.Components.Editor

A page editor component that can render Logseq page content.

Type: (props: { page: string } & any) => any

Parameters:

• page (string): The page name to render

const Editor = logseq.Experiments.Components.Editor

// Render a page editor
const editor = Editor({ page: 'My Page Name' })

---

3. Utilities

ClojureScript interop utilities for data conversion between JavaScript and ClojureScript.

logseq.Experiments.Utils

Provides conversion utilities:

toClj(input: any)

Convert JavaScript data to ClojureScript data structures.

const cljData = logseq.Experiments.Utils.toClj({ key: 'value' })

jsxToClj(input: any)

Convert JSX/JavaScript objects to ClojureScript, preserving JSX structures.

const cljData = logseq.Experiments.Utils.jsxToClj(<div>Content</div>)

toJs(input: any)

Convert ClojureScript data structures to JavaScript.

const jsData = logseq.Experiments.Utils.toJs(cljData)

toKeyword(input: any)

Convert a string to a ClojureScript keyword.

const keyword = logseq.Experiments.Utils.toKeyword('my-key')

toSymbol(input: any)

Convert a string to a ClojureScript symbol.

const symbol = logseq.Experiments.Utils.toSymbol('my-symbol')

---

4. Script Loading

logseq.Experiments.loadScripts(...scripts: string[])

Dynamically load external scripts into the Logseq environment.

Parameters:

• scripts (string[]): Array of script URLs or relative paths

Returns: Promise<void>

Behavior:

• Relative paths are resolved using the plugin's resource path
• HTTP/HTTPS URLs are loaded directly
• Scripts are loaded in order

// Load external library
await logseq.Experiments.loadScripts(
  'https://cdn.jsdelivr.net/npm/chart.js@3.9.1/dist/chart.min.js'
)

// Load local script from plugin resources
await logseq.Experiments.loadScripts('./my-script.js')

// Load multiple scripts
await logseq.Experiments.loadScripts(
  'https://cdn.example.com/lib1.js',
  'https://cdn.example.com/lib2.js',
  './local-script.js'
)

---

5. Custom Renderers

5.1 Fenced Code Renderer

Register a custom renderer for code blocks with specific language tags.

logseq.Experiments.registerFencedCodeRenderer(lang: string, opts: object)

Parameters:

• lang (string): The language identifier for the code block (e.g., 'mermaid', 'chart')
• opts (object):
  • render (function, required): Render function that receives props
  • edit (boolean, optional): Whether the block is editable
  • before (function, optional): Async function to run before rendering
  • subs (string[], optional): Subscriptions to state changes

Render Props:

• content (string): The content of the code block

// Register a custom code block renderer
logseq.Experiments.registerFencedCodeRenderer('my-chart', {
  edit: false,
  before: async () => {
    // Load dependencies before rendering
    await logseq.Experiments.loadScripts(
      'https://cdn.jsdelivr.net/npm/chart.js'
    )
  },
  render: (props) => {
    const React = logseq.Experiments.React
    
    return React.createElement('div', {
      ref: (el) => {
        if (el) {
          // Parse content and render chart
          const config = JSON.parse(props.content)
          new Chart(el, config)
        }
      }
    })
  }
})

Usage in Logseq:

```my-chart
{
  "type": "bar",
  "data": {
    "labels": ["A", "B", "C"],
    "datasets": [{"data": [10, 20, 30]}]
  }
}
```

5.2 Daemon Renderer

Register a renderer that runs continuously in the background (daemon).

logseq.Experiments.registerDaemonRenderer(key: string, opts: object)

Parameters:

• key (string): Unique identifier for the daemon renderer
• opts (object):
  • render (function, required): Render function
  • sub (string[], optional): Subscriptions to state changes

// Register a daemon renderer for persistent UI
logseq.Experiments.registerDaemonRenderer('my-status-bar', {
  sub: ['ui/theme', 'ui/sidebar-open'],
  render: (props) => {
    const React = logseq.Experiments.React
    
    return React.createElement('div', {
      style: {
        position: 'fixed',
        bottom: 0,
        right: 0,
        padding: '10px',
        background: '#333',
        color: '#fff'
      }
    }, 'Status: Active')
  }
})

5.3 Route Renderer

Register a custom renderer for specific routes in Logseq.

logseq.Experiments.registerRouteRenderer(key: string, opts: object)

Parameters:

• key (string): Unique identifier for the route renderer
• opts (object):
  • path (string, required): Route path (e.g., '/my-plugin-page')
  • render (function, required): Render function
  • name (string, optional): Display name for the route
  • subs (string[], optional): Subscriptions to state changes

// Register a custom route
logseq.Experiments.registerRouteRenderer('my-custom-page', {
  path: '/my-plugin-dashboard',
  name: 'Dashboard',
  subs: ['ui/theme'],
  render: (props) => {
    const React = logseq.Experiments.React
    
    return React.createElement('div', {
      className: 'my-plugin-dashboard'
    }, [
      React.createElement('h1', null, 'Plugin Dashboard'),
      React.createElement('p', null, 'Custom content here')
    ])
  }
})

// Navigate to the route
logseq.App.pushState('page', { name: 'my-plugin-dashboard' })

---

6. Extension Enhancers

Enhance external libraries that Logseq uses (like KaTeX for math rendering).

logseq.Experiments.registerExtensionsEnhancer(type: string, enhancer: function)

Parameters:

• type ('katex' | 'codemirror'): The extension type to enhance
• enhancer (function): Async function that receives the library instance and can modify it

Returns: Promise<void>

// Enhance KaTeX with custom macros
logseq.Experiments.registerExtensionsEnhancer('katex', async (katex) => {
  // Add custom KaTeX macros
  katex.macros = {
    ...katex.macros,
    '\\RR': '\\mathbb{R}',
    '\\NN': '\\mathbb{N}',
    '\\ZZ': '\\mathbb{Z}'
  }
  
  console.log('KaTeX enhanced with custom macros')
})

---

7. Plugin Local Access

logseq.Experiments.pluginLocal

Access the internal plugin instance (PluginLocal) for advanced operations.

Type: PluginLocal

const pluginLocal = logseq.Experiments.pluginLocal

// Access plugin-specific internal state
console.log('Plugin ID:', pluginLocal.id)

---

8. Advanced: Invoke Experimental Methods

logseq.Experiments.invokeExperMethod(type: string, ...args: any[])

Directly invoke experimental methods from the host scope.

Parameters:

• type (string): Method name (converted to snake_case)
• ...args: Arguments to pass to the method

Returns: any

// Invoke a custom experimental method
const result = logseq.Experiments.invokeExperMethod(
  'someExperimentalFeature',
  arg1,
  arg2
)

---

Complete Example: Custom Chart Renderer

Here's a complete example combining multiple APIs:

import '@logseq/libs'

async function main() {
  console.log('Chart Plugin Loaded')
  
  // Register fenced code renderer for charts
  logseq.Experiments.registerFencedCodeRenderer('chart', {
    edit: false,
    before: async () => {
      // Load Chart.js before rendering
      await logseq.Experiments.loadScripts(
        'https://cdn.jsdelivr.net/npm/chart.js@3.9.1/dist/chart.min.js'
      )
    },
    render: (props) => {
      const React = logseq.Experiments.React
      
      return React.createElement('div', null, [
        React.createElement('canvas', {
          ref: (canvas) => {
            if (canvas && window.Chart) {
              try {
                const config = JSON.parse(props.content)
                new window.Chart(canvas, config)
              } catch (e) {
                console.error('Chart rendering error:', e)
              }
            }
          }
        })
      ])
    }
  })
}

logseq.ready(main).catch(console.error)

Usage:

```chart
{
  "type": "line",
  "data": {
    "labels": ["Jan", "Feb", "Mar", "Apr"],
    "datasets": [{
      "label": "Sales",
      "data": [10, 20, 15, 30],
      "borderColor": "rgb(75, 192, 192)"
    }]
  }
}
```

---

Best Practices

1. Check Host Scope: Always ensure the host scope is accessible before using experimental APIs
2. Error Handling: Wrap experimental API calls in try-catch blocks
3. Dependencies: Load external scripts in before hooks to ensure they're ready
4. Memory Management: Clean up event listeners and subscriptions in daemon renderers
5. Compatibility: Test thoroughly as these APIs may change between Logseq versions
6. Documentation: Document which experimental APIs your plugin uses
7. Marketplace: Be aware that plugins using these APIs may not be accepted on the Marketplace

---

Limitations

• Experimental Status: These APIs are not stable and may change without notice
• Marketplace Support: Plugins using experimental APIs may not be approved for the Marketplace
• Security: Be cautious when loading external scripts or accessing host scope
• Performance: Custom renderers can impact performance if not optimized
• Compatibility: Limited backwards compatibility guarantees

---

See Also

• Starter Guide - Getting started with plugin development
• DB Properties Guide - Working with database properties
• DB Query Guide - Querying the Logseq database

---

Support

For questions and issues:

• Logseq Discord - #plugin-dev channel
• GitHub Discussions
• Plugin API Documentation

Remember: These are experimental features. Use at your own risk and always test thoroughly!