Guide for developing Zotero 8 plugins. Use this skill whenever working on Zotero plugins, adding features like UI elements (item tree columns, pane sections, menus, dialogs), handling Zotero data (items, collections, metadata), integrating with Zotero lifecycle events, creating new plugin modules, or debugging plugin functionality. Also use when modifying existing features, working with the zotero-plugin-toolkit, or implementing preferences and localization.
Guide for building Zotero 8 plugins.
src/
├── index.ts # Entry point - usually leave unchanged unless changing bootstrap wiring
├── addon.ts # Addon class - data store, API container
├── hooks.ts # Lifecycle handlers - wire up features here
├── modules/ # Your feature modules
└── utils/ # Utilities (ztoolkit, locale, prefs)
src/modules/hooks.ts lifecycle hooksonShutdown()See Adding Features for the complete workflow.
| Task | Reference |
|---|---|
| Create a new feature module | adding-features.md |
| Understand project structure | architecture.md |
| Add UI (columns, menus, sections, dialogs) | ui-patterns.md |
| Work with items, Extra field, notifiers | data-access.md |
| Add translations | localization.md |
| Cleanup resources, debug issues | cleanup-debugging.md |
The zotero-plugin-toolkit provides these utilities:
| Tool | Purpose | Reference |
|---|---|---|
ztoolkit.ExtraField | Get/set Extra field values | data-access.md |
ztoolkit.Dialog | Create dialog windows | ui-patterns.md |
ztoolkit.FilePicker | File/folder selection | ui-patterns.md |
ztoolkit.Clipboard | Copy text/HTML | ui-patterns.md |
ztoolkit.ProgressWindow | User notifications | ui-patterns.md |
ztoolkit.VirtualizedTable | Tables in preferences | ui-patterns.md |
ztoolkit.Reader | Access the Zotero reader | data-access.md |
ztoolkit.Keyboard | Global shortcuts | ui-patterns.md |
ztoolkit.UI.createElement | Create DOM elements | architecture.md |
Rule: Always check if ztoolkit provides an API before writing custom implementations.
Best practice: Treat scaffold examples as a starting point, not as the final architecture. Prefer current non-deprecated APIs, remove demo code early, and keep cleanup ownership inside feature modules.
See adding-features.md for:
hooks.tsSee ui-patterns.md for:
See data-access.md for:
See localization.md for:
See cleanup-debugging.md for:
ztoolkit.unregisterAll() usageWhen starting from the zotero-plugin-template, delete:
src/modules/examples.tssrc/modules/preferenceScript.ts (unless using prefs)Then clean up hooks.ts:
*ExampleFactory importsKeep these utilities:
src/utils/ztoolkit.tssrc/utils/locale.tssrc/utils/prefs.ts (optional)