Plugin Verifier and API Compatibility Maintenance: Livestream Recording & Key Takeaways

In a recent session, IntelliJ Platform Developer Advocate Róbert Novotný walked through the Plugin Verifier—one of the most important tools for maintaining plugin compatibility across JetBrains IDEs. The session focused on spotting breaking API changes, avoiding internal APIs, and verifying plugin behavior across IDE versions. If you couldn’t join us live, the full recording is […]

May 30, 2025 - 16:30

Plugin Verifier and API Compatibility Maintenance: Livestream Recording & Key Takeaways

In a recent session, IntelliJ Platform Developer Advocate Róbert Novotný walked through the Plugin Verifier—one of the most important tools for maintaining plugin compatibility across JetBrains IDEs. The session focused on spotting breaking API changes, avoiding internal APIs, and verifying plugin behavior across IDE versions.

If you couldn’t join us live, the full recording is now available on JetBrains TV.

And if you prefer reading over watching, this blog post sums up the key takeaways from the session.

What is the IntelliJ Plugin Verifier?

The IntelliJ Plugin Verifier is a tool that ensures a plugin behaves correctly across JetBrains IDE versions. It checks for compatibility issues with the evolving IntelliJ Platform APIs, and validates that a plugin:

Contains a complete and correct plugin descriptor (plugin.xml)
Uses APIs that are available and compatible with target IDE versions
Avoids deprecated, internal, or experimental APIs

JetBrains Marketplace relies on the Plugin Verifier to assess plugins upon upload, acting as a quality gate for all listed plugins.

Why Compatibility Matters

Publishing a plugin to JetBrains Marketplace is about more than just passing basic validation. End users expect plugins to work reliably, without errors or unexpected behavior. The Plugin Verifier helps plugin authors ensure their plugins will run smoothly across IDE versions, minimizing user disruption.

Typical Compatibility Challenges

The session covered several types of issues that the Plugin Verifier can detect:

Deprecated APIs: These may work now but are scheduled for removal in future platform versions.
Internal APIs: Not intended for external use, these may change without notice and break plugins.
Experimental APIs: Unstable and subject to change, their use is discouraged.
Override-only APIs: These should only be overridden, not invoked directly.
Visibility changes: Classes, methods and fields may become protected or public.
Structural changes: Classes may become interfaces or vice versa, breaking assumptions in plugin code.

Example: Plugin verification results

Running the Plugin Verifier Locally

To avoid the delay of uploading a plugin just to see it fail verification, developers can and should run the Plugin Verifier locally. There are two main ways to do this:

With IntelliJ Platform Gradle Plugin: This is the recommended approach. The Gradle plugin provides tasks like verifyPlugin and verifyPluginStructure for integrated verification.
Standalone Tool: Developers can download the Plugin Verifier JAR from GitHub or Maven Central and run it via the command line.

The session also walked through how to set up both methods, showing how developers can validate plugins against multiple IDE versions, identify API compatibility problems, and fix issues before publication.

Integrating with CI/CD

Integrating the Plugin Verifier into a continuous integration pipeline saves time and prevents issues from reaching production. The verifier can be run against new plugin versions and upcoming IDE releases to catch problems proactively.

Handling Warnings and Errors

While the Plugin Verifier highlights potential problems, not all warnings are show-stoppers. Some rules (like those about naming or older plugin IDs) can be muted locally using CLI flags (e.g., --mute). However, JetBrains Marketplace may enforce stricter rules, and muted issues locally do not affect Marketplace verification.

Best Practices

To get the most out of the Plugin Verifier and to avoid common pitfalls later on, keep these practical tips in mind:

Avoid internal and deprecated APIs whenever possible.
Use stable and documented APIs that are part of the official SDK.
Run verification locally before every release.
Regularly check compatibility against newer IDE versions.

Resources and Further Reading

Find more details and documentation in the IntelliJ Platform SDK docs
Ask questions or explore existing discussions on the JetBrains Platform Forum
Contribute to development on the Plugin Verifier GitHub Repository

Conclusion

The Plugin Verifier is a crucial tool in the JetBrains plugin development workflow. Whether integrated via Gradle or run standalone, it empowers developers to ship robust, future-proof plugins. By embracing it early in the development process, plugin authors can ensure a smoother path to publication and better experiences for their users.