Joplin Plugin Writer

Overview

Workflow

1. Clarify plugin type and target. Gather target platform (

   desktop

   or

   desktop+mobile

   ), core user action, UI surface (command, panel, toolbar, editor content script), and expected trigger.
2. Bootstrap or inspect the project. For a new plugin, scaffold with:

npm install -g yo generator-joplin
yo joplin

src/index.ts

src/manifest.json

plugin.config.json

webpack.config.js

1. Implement with the official plugin lifecycle. Always register through

   joplin.plugins.register({ onStart: async () => {} })

   . Place command/view/content-script wiring in

   onStart

   . Treat handlers and API calls as async.
2. Choose the integration pattern. If the feature targets note/workspace behavior, use

   joplin.workspace

   ,

   joplin.commands

   ,

   joplin.views

   . If the feature targets editor behavior, use content scripts and choose CodeMirror strategy:

• Prefer CodeMirror 6 plugin flow for modern Joplin.
• Add dual CM5+CM6 scripts only when explicit backward compatibility is required.
• Keep CM packages externalized to avoid duplicate-instance runtime issues.

1. Keep manifest and packaging correct. Update

   src/manifest.json

   with accurate

   app_min_version

   ,

   platforms

   , metadata, and assets. Build with

   npm run dist

   so runtime artifacts are available under

   dist/

   and publish output under

   publish/

   .
2. Run and verify in Development Mode. Launch Joplin in Development Mode, point "Development plugins" to plugin root, restart fully, and validate:

• Plugin loads without errors
• Core command/view behavior works
• Console/log output is clean

1. Debug with directed checks. For loading failures, check compiled entry and load paths (

   dist/index.js

   and plugin directory selection). For editor issues, verify CM6/CM5 compatibility branch and content script registration IDs. For mobile/web behavior, follow mobile debugging flow and ensure

   platforms

   contains

   mobile

   when needed.

Implementation Rules

• Read

  references/official-docs-index.md

  first and load only the minimum relevant section.
• Keep generated code TypeScript-first unless the repository is clearly JavaScript-only.
• Modify existing plugin structure instead of rewriting whole files when possible.
• Preserve user/plugin IDs and public command names unless migration is explicitly requested.
• Explain manifest-impacting changes (ID/version/platforms/min-version) before finalizing.
• Prefer incremental commits: scaffold, core feature, polish/fix, docs update.

Task Playbooks

New Plugin From Requirement

1. Convert requirement into one primary user interaction.
2. Scaffold with

   yo joplin

   .
3. Implement minimum viable command/panel/content script.
4. Update manifest metadata.
5. Build and run in Development Mode.
6. Return install/run steps and known limitations.

Feature Upgrade In Existing Plugin

1. Identify extension points in existing

   onStart

   registration.
2. Add feature with minimal API surface change.
3. Keep compatibility with existing settings and data where possible.
4. Validate build and runtime regressions.

Debugging and Fixes

1. Reproduce in Development Mode.
2. Triage by category: load-time, API/runtime, editor-content-script, packaging.
3. Apply smallest fix with clear reason.
4. Rebuild and re-test.

References

references/official-docs-index.md