# Debugging ONLYOFFICE plugins: practical guide

**URL:** <https://community.onlyoffice.com/t/debugging-onlyoffice-plugins-practical-guide/17192>\
**Category:** News\
**Created:** [19 November 2025 09:40 UTC](https://community.onlyoffice.com/t/debugging-onlyoffice-plugins-practical-guide/17192 "2025-11-19T09:40:31Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![ONLYOFFICE\_team](https://community.onlyoffice.com/user_avatar/community.onlyoffice.com/onlyoffice_team/32/431_2.png) [@ONLYOFFICE\_team](https://community.onlyoffice.com/u/ONLYOFFICE_team)\
**Post date:** [19 November 2025 09:40 UTC](https://community.onlyoffice.com/t/debugging-onlyoffice-plugins-practical-guide/17192/1 "2025-11-19T09:40:31Z")

</div>

Originally published at: [Debugging ONLYOFFICE plugins: practical guide | ONLYOFFICE Blog](https://www.onlyoffice.com/blog/2025/11/debugging-onlyoffice-plugins-practical-guide/)

Developing and debugging ONLYOFFICE plugins can be challenging, but with the right tools and techniques, the process can be made much easier. This guide will walk you through the steps needed to effectively debug plugins in different environments.

![Debugging ONLYOFFICE Plugins: practical guide](https://static-blog.onlyoffice.com/wp-content/uploads/2025/11/18141308/plugin_debugging_post.png)

### About ONLYOFFICE plugins

ONLYOFFICE allows you to extend the functionality of its editors through plugins. These plugins are HTML pages that are embedded in the editor and use an API to interact with it. Understanding the plugin structure and debugging methods is key to successful development.

### Plugin structure

A typical ONLYOFFICE plugin consists of the following files:

- **config.json** : A configuration file that defines basic information about the plugin.
- **index.html** : The main HTML page of the plugin.
- **scripts** : A directory containing the JavaScript files required for the plugin’s functionality.

A detailed structure and examples are available [here.](https://api.onlyoffice.com/docs/plugin-and-macros/structure/getting-started?utm_source=blog&utm_medium=article&utm_id=plugin_debuging_guide_article)

### Debugging plugins in web editors

To debug plugins in the web version of the ONLYOFFICE editor, follow these steps:

- Add the **debugger** command to your script.

```
(function (window, undefined) {
    window.Asc.plugin.init = function () {
        this.callCommand(function () {
            debugger;
            let oDocument = Api.GetDocument();
            let oParagraph = Api.CreateParagraph();
            oParagraph.AddText("Hello from the plugin!");
            oDocument.InsertContent([oParagraph]);
        }, true);
    };
})(window, undefined);
```

- Press **F12** to open the console in your browser.
- In the ONLYOFFICE editor, go to the **Plugins** tab and run your plugin.

Note: The **debugger** command will only work if the developer tools are **open** ; otherwise, it will be ignored. You can read more about that, on this [page](https://api.onlyoffice.com/docs/plugin-and-macros/tutorials/developing/for-web-editors/?utm_source=blog&utm_medium=article&utm_id=plugin_debuging_guide_article).

### Debugging plugins in desktop editors

To debug plugins in the desktop version of the ONLYOFFICE editor, use the following approach:

- Run the editor with the **–ascdesktop-support-debug-info** flag.

![Debugging ONLYOFFICE Plugins: practical guide](https://static-blog.onlyoffice.com/wp-content/uploads/2025/10/31140653/asc-desktop-support.png)

- This flag enables the display of additional information useful for debugging.
- Similar to the web editors, insert **debugger;** at the desired location in your code.

```
(function (window, undefined) {
    window.Asc.plugin.init = function () {
        this.callCommand(function () {
            debugger;
            let oDocument = Api.GetDocument();
            let oParagraph = Api.CreateParagraph();
            oParagraph.AddText("Hello from the plugin!");
            oDocument.InsertContent([oParagraph]);
        }, true);
    };
})(window, undefined);
```

- Press **F1** to open the console and run the plugin.

After starting the editor with the specified flag, open the plugin and trace the code execution.

![Debugging ONLYOFFICE Plugins: practical guide](https://static-blog.onlyoffice.com/wp-content/uploads/2025/10/31141448/cors-img-1_mod.png)

Detailed instructions for different operating systems are available [here.](https://api.onlyoffice.com/docs/plugin-and-macros/tutorials/developing/for-desktop-editors/?utm_source=blog&utm_medium=article&utm_id=plugin_debuging_guide_article)

### Managing scopes

When developing an ONLYOFFICE plugin, it’s important to understand how to pass data between your plugin’s user interface (the HTML page) and the editor’s execution environment where the Document Builder API commands are run. These are different context or **scopes**.

A common source of bugs is improper handling of data between these scopes. ONLYOFFICE provides the **Asc.scope** object to facilitate this. You can attach variables to **Asc.scope** in your plugin’s main script, and they will be accessible within the function passed to **this.callCommand()**.

Here is an example of how to pass a text variable to your plugin to the editor:

```
(function (window, undefined) {
    window.Asc.plugin.init = function () {
    // In your main script (e.g., scripts/plugin.js)
    let text = "Hello from the plugin!";
    Asc.scope.dataForEditor = text; // Export variable to the shared plugin scope
    // In the command executed in the editor's scope
    this.callCommand(function () {
         debugger;
         let oDocument = Api.GetDocument();
         let Paragraph = Api.CreateParagraph();
         oParagraph.AddText(Asc.scope.dataForEditor);// Access the variable via Asc.scope
         oDocument.InsertContent([oParagraph]);
    }, true);
  };
})(window, undefined);
```

Properly using **Asc.scope** ensures that data is passed correctly between different contexts,which is critical for building complex plugins.

### Common issues and troubleshooting

While debugging you may encounter several common issues. Here are some of the most frequent problems and their solutions:

#### Debugger statement is not working

The **debugger;** statement is ignored and execution doesn’t pause.

- Make sure the browser’s developer tools ( **F12** ) are open before running the plugin.
- The **debugger;** statement only works when DevTools are active.

#### Plugin not loading or not visible

- Check that your **config.json** file is properly formatted (valid JSON).
- Verify that all required fields in config.json are present (name, guid, baseUrl).
- Check the browser console for any loading errors.
- Ensure the plugin is properly installed in the ONLYOFFICE plugins tab.
- Manual installation with zipped .plugin file or Asc.editor.installDeveloperPlugin() method.

#### Cors (cross-origin resource sharing) errors

- Install [ONLYOFFICE Docs](https://www.onlyoffice.com/download-docs?utm_source=blog&utm_medium=article&utm_id=plugin_debuging_guide_article).
- For web editors in ONLYOFFICE Docs, make sure you run http-server inside of your plugin folder.
- Or adjust path to your config.json file in **installDeveloperPlugin()**.

```
Asc.editor.installDeveloperPlugin("https://<documentserver>:<port>/<folder-name>/config.json")
```

![Debugging ONLYOFFICE Plugins: practical guide](https://static-blog.onlyoffice.com/wp-content/uploads/2025/10/31141448/cors-img-1_mod.png)

![Debugging ONLYOFFICE Plugins: practical guide](https://static-blog.onlyoffice.com/wp-content/uploads/2025/10/31140835/cors-img-2.png)

#### Files changed, old code is still running – Web Editors

- If you changed local files of your plugin, you’ll need to refresh your page and cache.
- Right click on the refresh button of your browser and select “Empty Cache and Hard Reload”, then run your plugin again.

![Debugging ONLYOFFICE Plugins: practical guide](https://static-blog.onlyoffice.com/wp-content/uploads/2025/10/31140935/refresh.png)

Effective debugging is crucial for developing stable and functional ONLYOFFICE plugins. By using the techniques and tools mentioned, you can quickly identify and resolve issues in your code, thereby improving the quality and performance of your plugins.

We welcome your questions, suggestions, and plugin ideas. If you’d like to share your work with us, please don’t hesitate to get in touch. We’re open to collaboration and happy to connect.

### Useful Links

[Interacting with ONLYOFFICE editors](https://api.onlyoffice.com/docs/plugin-and-macros/interacting-with-editors/overview/?utm_source=blog&utm_medium=article&utm_id=plugin_debuging_guide_article)

[Latest updates for ONLYOFFICE API](https://www.onlyoffice.com/blog/2025/09/api-roundup-aug-sept?utm_source=blog&utm_medium=article&utm_id=plugin_debuging_guide_article)

[Plugin examples on GitHub](https://github.com/ONLYOFFICE/sdkjs-plugins?utm_source=blog&utm_medium=article&utm_id=plugin_debuging_guide_article)

[Get ONLYOFFICE Docs](https://www.onlyoffice.com/download-docs?utm_source=blog&utm_medium=article&utm_id=plugin_debuging_guide_article)
