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.
- Author
- dream-num ↗
- Repository
- skills ↗
- Licence
- Apache-2.0
- Last repository change
- 14.10.2026
Assessment and security
- Files in this package
- 8
- Scripts
- 1
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 14.10.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
- 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
- Scaffold a Sheet UI plugin
- Core rules
- Validation
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.