Changes on SonarJS public API

[vdiez]

SonarJS developer here. Just a heads up that we are deprecating the current public API of our analyzer. You can check the new APIs here, compared to the deprecated one .

Not many changes needed, we just needed to clean up a little bit as there were too many classes to define Rules. Deprecated Check, EslintBasedCheck, JavaScriptCheck and TestFileCheck. Left EslintHook as only way to register rules. All the former will be removed in SonarJS 12

[utarwyn]

Hello @vdiez! Thank you for this discussion post.

I am working on a new major version of the plugin to update minimal requirements. I have also taken note of the need to switch to the class EslintHook to define our rules. It works well on the latest community and developer versions of SonarQube.

But I'm having trouble defining the minimum SonarQube versions that our plugin can support. It must be based on SonarJS v11, which does not seem to be used by the latest LTA version of SonarQube. So should I give up on supporting the latest LTA?

---

SonarQube Developer 2025.4 LTA

Caused by: java.lang.NoClassDefFoundError: org/sonar/plugins/javascript/api/EslintHook

SonarQube Community Edition 25.9 (first version using SonarJS 11)

Caused by: java.lang.ClassCastException: class org.greencodeinitiative.creedengo.javascript.checks.PreferLighterFormatsForImageFiles 
    cannot be cast to class org.sonar.plugins.javascript.api.JavaScriptCheck 
    (org.greencodeinitiative.creedengo.javascript.checks.PreferLighterFormatsForImageFiles is in unnamed module of loader 
    org.sonar.classloader.ClassRealm @2459319c; org.sonar.plugins.javascript.api.JavaScriptCheck is in unnamed module of loader 
    org.sonar.classloader.ClassRealm @ffaaaf0)

happens during the project scan

---

Looking forward to your valuable feedback, thank you 🙏

[vdiez]

Hi @utarwyn,

Thank you for your detailed feedback! Let me help clarify the compatibility situation and offer a path forward. I checked and SonarQube Server 2025.4.0 LTA bundles SonarJS 10.25.0, which includes the EslintHook interface (introduced in 10.23.0). The latest patch 2025.4.4 has SonarJS 10.26.0.

The Root Cause of Your Issues

Problem 1 (NoClassDefFoundError: EslintHook):
If you're seeing this error on SonarQube Server 2025.4.x, something else may be wrong since the LTA does include EslintHook. Can you confirm which exact version you tested with?

Problem 2 (ClassCastException):
This is caused by classloader isolation due to the API module split in SonarJS 10.15.0. Your plugin was compiled against the old javascript-checks JAR (SonarJS 9.x), but newer SonarQube loads classes from the new API JAR. Even though the class names are identical, the JVM treats them as different types.

The Solution

You need to recompile against the new API artifact:

<!-- Replace this -->
<dependency>
  <groupId>org.sonarsource.javascript</groupId>
  <artifactId>javascript-checks</artifactId>
  <version>9.13.0.20537</version>
</dependency>

<!-- With this -->
<dependency>
  <groupId>org.sonarsource.javascript</groupId>
  <artifactId>api</artifactId>
  <version>10.23.0.32711</version>
  <scope>provided</scope>
</dependency>

Also update your CustomRuleRepository:

// Replace languages() with compatibleLanguages()
@Override
public Set<org.sonar.plugins.javascript.api.Language> compatibleLanguages() {
    return EnumSet.of(Language.JAVASCRIPT, Language.TYPESCRIPT);
}

Two Options for Implementation

Option 1: Maximum Compatibility (SonarJS 10.23 - 11.5)

Use EslintBasedCheck which extends both EslintHook and JavaScriptCheck:

@Rule(key = "EC4")
@JavaScriptRule
@TypeScriptRule
public class PreferLighterFormatsForImageFiles implements EslintBasedCheck {

    @Override
    public String eslintKey() {
        return "prefer-lighter-formats-for-image-files";
    }
}

Covers:

• SonarQube Server 2025.4.x LTA (SonarJS 10.25-10.26)
• SonarQube Community 25.6 - 25.11 (SonarJS 10.23 - 11.5)

Note: EslintBasedCheck is deprecated in SonarJS 11.6+ but still works.

---

Option 2: Future-Proof (SonarJS 11.6+)

Use EslintHook directly:

@Rule(key = "EC4")
@JavaScriptRule
@TypeScriptRule
public class PreferLighterFormatsForImageFiles implements EslintHook {

    @Override
    public String eslintKey() {
        return "prefer-lighter-formats-for-image-files";
    }
}

Covers:

• SonarQube Community 25.12+ (SonarJS 11.6+)
• Upcoming LTA (expected to bundle SonarJS 11.7)

Does NOT work with:

• SonarQube Server 2025.4.x LTA (SonarJS 10.25-10.26)
• SonarQube Community 25.6 - 25.11 (SonarJS 10.23 - 11.5)

---

Summary

Option	Interface	Current LTA (2025.4)	Community 25.6-25.11	Community 25.12+	Upcoming LTA
1	EslintBasedCheck	✅	✅	✅ (deprecated)	✅ (deprecated)
2	EslintHook	❌	❌	✅	✅

Recommendation:

• If you need to support the current LTA (2025.4): Use Option 1 (EslintBasedCheck)
• If you only need to support the upcoming LTA and newer: Use Option 2 (EslintHook)

Since the upcoming LTA will have SonarJS 11.7+, you could also choose to:

1. Release now with Option 1 to support current LTA
2. Switch to Option 2 when the new LTA is released

Let me know if you have any questions!

[utarwyn]

Thank you @vdiez for the detailed explanations! It's really appreciated 🙌

I followed your recommendations, so I chose option 1 for now in order to optimize compatibility. I can confirm that the plugin works well up to SonarQube 25.11, but starting with SonarQube 25.12, we're encountering the ClassNotFoundException for EslintBasedCheck class.

Caused by: java.lang.ClassNotFoundException: org.sonar.plugins.javascript.api.EslintBasedCheck

I analyzed the SonarJS plugin JAR (version 11.7.1.36988) bundled with SonarQube Community 26.1, and indeed, the EslintBasedCheck class seems to be completely removed:

▶ jar tvf sonar-javascript-plugin-11.7.1.36988-multi.jar | grep Eslint
   820 Fri Dec 05 17:19:34 CET 2025 org/sonar/plugins/javascript/external/EslintReportImporter$EslintError.class
   761 Fri Dec 05 17:19:34 CET 2025 org/sonar/plugins/javascript/external/EslintReportImporter$FileWithMessages.class
  9365 Fri Dec 05 17:19:34 CET 2025 org/sonar/plugins/javascript/external/EslintReportImporter.class
  3962 Fri Dec 05 17:19:34 CET 2025 org/sonar/plugins/javascript/rules/EslintRulesDefinition.class
   475 Fri Dec 05 17:18:26 CET 2025 org/sonar/plugins/javascript/api/EslintHookRegistrar.class
  1368 Fri Dec 05 17:19:26 CET 2025 org/sonar/plugins/javascript/api/EslintHook.class
   419 Fri Dec 05 17:18:26 CET 2025 org/sonar/plugins/javascript/api/EslintHookRegistrar$RegistrarContext.class
  5263 Fri Dec 05 17:18:52 CET 2025 org/sonar/plugins/javascript/bridge/EslintRule.class

As you mentioned, EslintBasedCheck was deprecated in SonarJS 11.6+ but I don't understand why it is not present in the final build. Perhaps this is the result of a minification process if you don't use it? Do you have any more information on this?

I think I'll have to migrate to EslintHook and therefore go straight to option 2.

Thank you again for the guidance!

[vdiez]

Hi @utarwyn,

you are absolutely right. This is due to minification, just tested locally adding an include filter in the minimizer and it's now there:

<filters>
  <filter>
   <artifact>org.sonarsource.javascript:api</artifact>
   <includes>
     <include>org/sonar/plugins/javascript/api/**</include>
   </includes>
 </filter>
/filters>

Sorry, we totally missed that, and thanks for reporting it. We should keep that filter to make sure our public APIs are always published.

We prepared some docs about the custom rules APIs, I hope this helps!

[utarwyn]

Thank you for quickly taking my feedback into account!

Given that this class was not included in previous builds of SonarJS, I confirm that I will go with the second option you suggested. Your fix will be useful for future depreciation 👍 Also, thank you for the detailed documentation. II will be able to check whether the plugin complies with the standards you propose with SonarJS.

Thank you for opening up the SonarJS API to the community, it's a really great initiative.