Skip to content
Skills Library
Programming · Building & coding

univer-plugin-dev

/univer-plugin-dev

Develop custom plugins for Univer sheets, docs, slides, bases, boards, and PDFs. Use when implementing a Plugin lifecycle, dependency injection, commands/mutations/operations, undo/redo, Facade extensions or custom events, toolbar/context-menu items, shortcuts, icons, popups, or when diagnosing plugin API and registration errors.

Repository
skills ↗
Licence
Apache-2.0
Last repository change
14.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
8
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 14.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/scaffold-plugin.ts

What it does and when to use it

Develop custom plugins for Univer sheets, docs, slides, bases, boards, and PDFs. Use when implementing a Plugin lifecycle, dependency injection, commands/mutations/operations, undo/redo, Facade extensions or custom events, toolbar/context-menu items, shortcuts, icons, popups, or when diagnosing plugin API and registration errors.

Original author description

Develop custom plugins for Univer sheets, docs, slides, bases, boards, and PDFs. Use when implementing a Plugin lifecycle, dependency injection, commands/mutations/operations, undo/redo, Facade extensions or custom events, toolbar/context-menu items, shortcuts, icons, popups, or when diagnosing plugin API and registration errors.

How it works

  1. Scaffold a Sheet UI plugin
  2. Core rules
  3. Validation
Original SKILL.md headings · 143 lines, 783 words
SKILL.md preview
---
name: univer-plugin-dev
description: Develop custom plugins for Univer sheets, docs, slides, bases, boards, and PDFs. Use when implementing a Plugin lifecycle, dependency injection, commands/mutations/operations, undo/redo, Facade extensions or custom events, toolbar/context-menu items, shortcuts, icons, popups, or when diagnosing plugin API and registration errors.
---

# Univer Plugin Development

Build plugins against the APIs exported by the target application's installed Univer packages.

> **Compatibility**: The checked source baseline is Univer and Univer Pro `1.0.0-beta.0`. Keep release-train packages such as `@univerjs/core`, `@univerjs/sheets`, `@univerjs/ui`, and `@univerjs-pro/*` on that same exact version. Independently versioned packages such as `@univerjs/icons` must follow the target manifest instead. If the target project differs, inspect its manifests and source exports before copying an example.

## Scaffold a Sheet UI plugin

Run the bundled generator:

```bash
npx tsx <skills-repo>/skills/univer-plugin-dev/scripts/scaffold-plugin.ts my-plugin --path ./packages
```

It creates a buildable Sheet UI plugin package. For docs, slides, bases, boards, or PDFs, first choose the product type and official core/UI plugin family in [plugin-architecture.md](references/plugin-architecture.md), then adapt the generated dependencies and `UniverInstanceType`.

```text
my-plugin/
├── src/
│   ├── commands/my-command.ts
│   ├── controllers/menu.controller.ts
│   ├── facade/f-univer.ts
│   ├── index.ts
│   └── plugin.ts
├── package.json
└── tsconfig.json
```

Register the plugin and explicitly load its Facade extension:

```ts
import { UniverMyPlugin } from './packages/my-plugin/src';
import './packages/my-plugin/src/facade/f-univer';

univer.registerPlugin(UniverMyPlugin);
```

When consuming a built package, import its public subpath instead:

```ts
import { UniverMyPlugin } from 'my-plugin';
import 'my-plugin/facade';
```

The scaffold has no stylesheet. Product/preset styles belong to the host; if the plugin adds CSS, publish a CSS entry with a CSS-aware build and require the host to import it. See [ui-customization.md](references/ui-customization.md) for the 1.0 preset/plugin-mode CSS boundary.

## Core rules

### Plugin lifecycle

Extend `Plugin`, provide a unique `pluginName`, choose a `UniverInstanceType`, and inject `Injector` as the protected `_injector` required by the base class. The 1.0 product matrix is sheets, docs, slides, bases, boards, and PDFs; do not copy the Sheet scaffold unchanged for another product.

| Hook | Use it for |
| --- | --- |
| `onStarting()` | Register DI dependencies, commands, menus, shortcuts, icons, and components. Do not read a workbook or the DOM. |
| `onReady()` | Initialize logic that requires a created unit of the plugin's product type. |
| `onRendered()` | Register render modules or other renderer/DOM-dependent logic. |
| `onSteady()` | Start non-critical work after all plugins have rendered. |

Own every disposable subscription, listener, shortcut, command, component, icon, render module, timer, and worker with `disposeWithMe()`. `IMenuManagerService.mergeMenu()` is the notable exception: it currently returns `void`.

Read [plugin-architecture.md](references/plugin-architecture.md) when adding lifecycle logic, DI services, configuration, dependencies, or controllers.

### Command model

- `COMMAND` orchestrates validation and business flow.
- `MUTATION` deterministically changes persisted model state and is the collaboration changeset unit.
- `OPERATION` changes transient UI state.

A mutation is not automatically undoable. Capture undo parameters before executing redo mutations, then push symmetric `undoMutations` and `redoMutations` through `IUndoRedoService` from the command.

Use `executeCommand()` for async execution and `syncExecuteCommand()` only when the full handler chain is synchronous. Both return the handler result directly; there is no `.result` wrapper.

Read [command-system.md](references/command-system.md) before changing persisted data, implementing undo/redo, invoking built-in commands, or listening to command execution.

### Facade extensions

When the target Facade class explicitly exposes static `extend()`, subclass it, call `extend()`, and augment the module that owns the class. Not every public Facade class is a mixin target; check [facade-extension.md](references/facade-extension.md) first.

```ts
import { FWorksheet } from '@univerjs/sheets/facade';

export interface IFWorksheetMyMixin {
    markHeader(color: string): this;
}

export class FWorksheetMyMixin extends FWorksheet implements IFWorksheetMyMixin {
    override markHeader(color: string): this {
        this.getRange(0, 0, 1, this.getMaxColumns()).setBackground(color).setFontWeight('bold');
        return this;
    }
}

FWorksheet.extend(FWorksheetMyMixin);

declare module '@univerjs/sheets/facade' {
    interface FWorksheet extends IFWorksheetMyMixin {}
}
```

Consumers must side-effect import the extension module. Read [facade-extension.md](references/facade-extension.md) when extending `FUniver`, `FWorkbook`, `FWorksheet`, `FRange`, `FDocument`, Pro product Facades such as `FPresentation`, or Facade events.

### UI extensions

Register toolbar and context-menu items by merging a menu schema. A menu item's `id` (or `commandId`) selects the registered command. A shortcut also executes the command whose ID it carries; `IShortcutItem` has no custom handler.

```ts
this._menuManagerService.mergeMenu({
    [RibbonOthersGroup.OTHERS]: {
        [MyCommand.id]: {
            order: 10,
            menuItemFactory: () => ({
                id: MyCommand.id,
                title: 'my-plugin.menu.run',
                type: MenuItemType.BUTTON,
            }),
        },
    },
});
```

Use `IconManager` for icons and `ComponentManager` for React/Vue/custom components. Keep their returned disposables. Read [ui-customization.md](references/ui-customization.md) for current menu nesting, context-menu positions, shortcuts, components, and range popups.

### Events

Prefer typed Facade events through `univerAPI.addEvent()`. Load the owning Facade side-effect module so its event names and parameter types are installed. Filter `ICommandService` listeners by exported command constants when no semantic Facade event exists.

Read [event-system.md](references/event-system.md) for current event names, cancellation, custom events, and cleanup.

## Validation

After generating or editing a plugin:

1. Build or typecheck it against the target project's exact Univer versions.
2. Register it in a minimal app and exercise the command, menu/shortcut, Facade side-effect import, and disposal path.
3. Verify persisted changes round-trip and undo/redo when applicable.
4. Run the skill validator after editing this skill:

```bash
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/univer-plugin-dev
```
Files in this package (8)
  • SKILL.md 7 KB
  • agents/openai.yaml 1 KB
  • references/command-system.md 9 KB
  • references/event-system.md 5 KB
  • references/facade-extension.md 8 KB
  • references/plugin-architecture.md 10 KB
  • references/ui-customization.md 9 KB
  • scripts/scaffold-plugin.ts 7 KB

Versions

The database has no other skills named univer-plugin-dev.

Database snapshot: 13.11.2026 · package version 1e03ba2e312d (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100univer-integrate
    Integrate Univer Sheets, Docs, or Slides into React, Vue 3, HTML, or Node.js projects. Use when embedding Univer, choosing preset or plugin mode, initializing instances, configuring themes/locales/workers, or manipulating workbooks, worksheets, ranges, formulas, permissions, and…
  • 100univer-node-backend
    Run Univer Sheets, Docs, Slides, Bases, Boards, or PDFs in Node.js without browser UI. Use for server-side or backend Univer, OSS Sheets or Docs Node presets, Pro product Facades and collaboration, JSON snapshot processing, formula or Base child-process workers, or automated…
  • 100woo-plugin-dev
    Create WooCommerce extensions/plugins — file structure, main plugin file, activation/deactivation hooks, custom database tables, autoloading, and WordPress plugin API. Use when building new WooCommerce extensions or structuring plugin code.
  • 100strapi-plugin-dev
    Strapi v5 plugin development expert. Use for building, refactoring, or revamping plugins, custom APIs, admin panel extensions, Document Service API usage, content-type creation, and plugin architecture. Invoke when working with Strapi v5 plugin development, troubleshooting…
  • 84handling-wpf-input-commands
    Implements WPF input handling with RoutedCommand, ICommand, CommandBinding, and InputBinding patterns. Use when creating keyboard shortcuts, menu commands, or custom command implementations.
  • 100plugin-development
    Create and run NetAlertX plugins. Use this when asked to create a plugin, run a plugin, test a plugin, or develop plugin functionality.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.