Create Plugin OnlyOffice Docs: Full Guide

Yes, you can create a plugin for ONLYOFFICE Docs, and this article explains exactly how to build, debug, and deploy one. An ONLYOFFICE plugin is a small web app (HTML, CSS, JavaScript) that runs inside the editor and adds custom buttons, panels, or automation. You’ll need basic JavaScript knowledge and a code editor; the rest is configuration and testing.

What Exactly Is an ONLYOFFICE Plugin?

ONLYOFFICE Docs (formerly ONLYOFFICE Online Editors) is a suite of office applications—document, spreadsheet, presentation, and form editors—that run in a browser. Plugins extend these editors with custom functionality. For example, a plugin might insert a QR code, translate selected text, or pull data from an external API. Plugins are written in standard web technologies (HTML, CSS, JavaScript) and are loaded by the editor at runtime. They are not compiled binaries; they are just files served from a URL or a local folder.

Every plugin has a config.json file that tells the editor what the plugin is called, what buttons it adds, and which files it needs. The actual logic lives in an index.html file (or a JavaScript file referenced by it). The editor provides a JavaScript API (the Asc.plugin object) that lets your plugin interact with the document—get selected text, insert content, open dialogs, etc.

Prerequisites: What You Need Before You Start

Before writing your first plugin, make sure you have:

An ONLYOFFICE Docs instance (self-hosted or a cloud version) where you can test. The free Community Edition works for development.
A text editor or IDE (VS Code, Sublime, Notepad++).
Basic knowledge of JavaScript, HTML, and CSS.
If you plan to test locally, a way to serve your plugin folder over HTTP (e.g., a simple static server). The editor loads plugins via URL, so file:// won’t work.

You don’t need a build tool or a package manager. A simple folder with two files is enough to start.

Step-by-Step: Building a Minimal Plugin

Here’s how to create a plugin that inserts the current date into the document.

Create a folder for your plugin, e.g., insert-date-plugin.
Create config.json with the following content:

{
  "name": "Insert Date",
  "guid": "asc.{12345678-1234-1234-1234-123456789012}",
  "variations": [
    {
      "description": "Inserts the current date",
      "url": "index.html",
      "icons": ["resources/icon.png"],
      "buttons": [
        {
          "text": "Insert Date",
          "type": "button",
          "hint": "Insert current date"
        }
      ]
    }
  ]
}

The guid must be a unique identifier—you can generate one online. The url points to your HTML file. The icons array expects an image (you can skip it for a first test, but the editor may show a default icon).

Create index.html with the plugin logic:

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <script src="https://onlyoffice.github.io/sdkjs-plugins/v1/plugins.js"></script>
</head>
<body>
  <script>
    window.Asc.plugin.init = function() {
      this.executeCommand("command", function() {
        var today = new Date().toLocaleDateString();
        this.callCommand(function() {
          this.
            GetDocument().
            InsertText(today);
        });
      });
    };
  </script>
</body>
</html>

This script loads the plugin API, then when the plugin is initialized, it inserts the current date at the cursor position. The callCommand method runs the operation on the document.

Serve the folder over HTTP. For example, with Python: python -m http.server 8080 in the plugin folder.
Add the plugin to ONLYOFFICE Docs. In the editor, go to the Plugins tab (or Settings → Plugins), click “Add plugin”, and enter the URL to your config.json (e.g., http://localhost:8080/config.json).
Reload the editor and you should see your button. Click it to insert the date.

How the Plugin API Works

The core object is window.Asc.plugin. It provides methods like init, executeCommand, and callCommand. Here’s what they do:

init – called when the plugin is loaded. You set up UI and event listeners here.
executeCommand – runs code in the plugin’s own context, useful for preparing data.
callCommand – sends a command to the editor’s core, where you can manipulate the document using the Api object (e.g., GetDocument(), InsertText()).
attachEvent – lets you listen to editor events (like selection changes).

You can also create custom panels, dialogs, and buttons. For example, to add a button that opens a dialog, you would use this.createWindow or this.attachEvent to show a modal. The official documentation (available on the ONLYOFFICE GitHub) lists all API methods and examples.

Testing and Debugging Your Plugin

Debugging is straightforward because plugins run in the browser. Open the developer console (F12) to see errors and use console.log statements. The editor’s console will show any JavaScript errors from your plugin. A common issue is that the plugin API script (plugins.js) fails to load—make sure you’re using the correct URL for your ONLYOFFICE version. For self-hosted instances, the API script is usually served from the same domain as the editor, so you can use a relative path like /sdkjs-plugins/v1/plugins.js instead of the GitHub URL.

Another debugging tip: you can add a temporary button that logs the current selection or document state to see if your commands are reaching the document. Also, test in different browsers (Chrome, Firefox, Edge) because some APIs behave differently.

Common Problems and How to Fix Them

Plugin doesn’t appear in the editor – Check that the URL to config.json is correct and accessible from the editor’s server. If you’re testing locally, make sure your server is running and the port is open.
Button does nothing – Look at the console for errors. Make sure window.Asc.plugin is defined (the API script loaded). Also check that you’re using this.callCommand inside the correct context—often you need to bind this or use an arrow function.
Plugin works in one editor but not another – Different editor types (document, spreadsheet, presentation) have different APIs. For example, InsertText works in the document editor, but in the spreadsheet editor you might need SetCellText. Check the API reference for each editor type.
“Cannot read property ‘GetDocument’ of undefined” – This usually means the callCommand function isn’t receiving the correct context. Ensure you’re calling it as a method of the plugin object, not as a standalone function.

Alternatives to Writing Plugins from Scratch

If you don’t want to build a plugin from zero, you can:

Use the official plugin repository (on GitHub) to copy and modify existing plugins. The repository contains many ready-made plugins like a translator, a thesaurus, and a photo editor.
Use ONLYOFFICE’s built-in macros (for documents) or scripts (for spreadsheets) for simple automation. Macros are lighter than plugins and don’t require a separate UI.
If you need to integrate with an external service, consider using the ONLYOFFICE API directly from your own web application instead of a plugin—the editor can be embedded and controlled via its JavaScript API.

Frequently Asked Questions

Do I need a server to run a plugin?

Yes, the editor loads plugins via HTTP(S). You can run a local server during development, but for production you need a publicly accessible URL (or a server on the same network as the editor).

Can I sell my ONLYOFFICE plugin?

Yes, you can distribute your plugin commercially, but you must follow the ONLYOFFICE license terms. The plugin SDK is open source, but if you use the ONLYOFFICE Docs software, check the license of the edition you’re using (Community Edition is AGPL, while commercial editions have different terms).

What programming languages can I use?

Plugins are written in JavaScript (or TypeScript that compiles to JS). You can also use HTML and CSS for the UI. There’s no support for Python or other languages inside the plugin runtime, but you can call external APIs from your plugin using AJAX.

How do I add a plugin to ONLYOFFICE Desktop Editors?

The process is similar: in the desktop app, go to the Plugins tab, click “Settings” (gear icon), then “Add plugin” and select the config.json file from your local disk. The desktop app can load plugins from local paths, unlike the web version.

Can I create a plugin that works across all editor types?

Yes, you can define multiple variations in config.json, each with its own url and buttons. You can also check the current editor type at runtime using this.getType() and adapt your code accordingly.

Where can I find the official documentation?

The official plugin documentation is on the ONLYOFFICE GitHub repository under sdkjs-plugins. It includes a detailed API reference, code samples, and a guide on publishing plugins to the marketplace.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →