intellij-scala: the Scala plugin for IntelliJ IDEA, built in the open

A language plugin that has to work on every IntelliJ release

The plugin adds support for the Scala language to IntelliJ IDEA, and the feature list in the README is short enough to summarise: coding assistance with highlighting, completion, formatting, refactorings and code inspection, navigation and search with information about types and implicits, integration with the build tools SBT, Maven, Gradle and BSP, support for the ScalaTest, MUnit, Specs2 and uTest testing frameworks, a Scala debugger and worksheets, and more.

What makes this repository interesting is not the feature list, which any language plugin will have, but the second job it has to do. The default branch is named idea263.x, which is an IntelliJ platform release branch, and the repository is a mirror of a larger JetBrains setup. The GitHub Actions section explains that the test tier not available in the Community repository mirrored to GitHub is part of the Ultimate repository's regular test suite, which tells you the public repository is a subset of the development reality.

There is also the user-facing split that the README mentions in one line: HOCON support was moved to a separate plugin. A language plugin that accumulates every adjacent format ends up large and slow to build, and moving HOCON out is the kind of decision that keeps a core plugin maintainable.

Everything user-facing lives elsewhere. The landing page is on the JetBrains site, the plugin is on the JetBrains Marketplace, release notes and feature articles are on the Scala blog, detailed usage is in the IntelliJ IDEA online help, and bugs go to YouTrack with the SCL project prefix. The repository is for people who want to work on the plugin rather than use it.

Clone, open in IDEA, pick JDK 25, run scalaCommunity

The setup instructions assume you are going to develop the plugin inside the IDE it extends, which is unusual but sensible here.

The prerequisites are IntelliJ IDEA 2022.3 or higher with a compatible version of the Scala plugin, JDK 25, which can be downloaded through IntelliJ IDEA itself, and, optionally but recommended, internal mode enabled, which gives access to helpful internal actions and debug information.

Then four steps. Clone the repository:

git clone https://github.com/JetBrains/intellij-scala.git

Open IntelliJ IDEA and point it at the cloned directory, from the Welcome screen or the File menu, and it will be imported automatically as an sbt project. Select JDK 25 as the project JDK, creating it from an installed JDK if necessary. Then select the scalaCommunity run configuration and press Run or Debug, which builds and starts a development version of IDEA with the Scala plugin inside it.

The reasoning behind the last step is what makes the workflow work. The plugin is not a separate program that talks to IDEA, it is code that is compiled into the IDE, so the only way to see a change is to build the plugin and launch an IDE that has it. Under the hood that run configuration launches IntelliJ IDEA with the pre-installed Scala plugin built from sources, so the debugging experience is the real one, with breakpoints in the plugin's own code and the IDE under it.

Packaging the plugin so a normal IDE can load it

The development loop above is for working on the plugin. Running a modified version in a regular IntelliJ instance needs the plugin packaged, and the README gives three steps.

On the sbt shell you run packageArtifactZip, which outputs the location of the generated plugin zip, typically into the project directory as target/scala-plugin.zip. In IntelliJ you open Preferences, go to the Plugins section, choose Install plugin from disk and navigate to that zip. Then you restart IntelliJ.

The restart is not a quirk, it is how the platform works, since plugins are loaded at startup and a changed plugin needs a new process to pick it up. The zip is a self-contained artefact, which also means the same file can be handed to someone else for testing or distributed to a small team without going through the Marketplace.

The repository layout supports this workflow. There is build.sbt at the root with the sbt/ directory for the build definitions and project/ for the project-level configuration, the scala/ directory for the plugin sources, pluginXml/ for the plugin descriptor, tools/ for helper code, scala-cli/ and bsp-builtin/ for the two build tool integrations, a .devcontainer/ for a reproducible development environment, .jvmopts for the JVM options the build needs, and crowdin.yml for the translation workflow.

Test tiers, and a fast suite that takes over an hour

Running the tests needs the plugin packaged, and the README is explicit about the order: on the sbt shell, packageArtifact and then runFastTests.

The warning is the important part. The fast tests can take over an hour. For a quick feedback on project health, the README points at a narrower target, runTypeInferenceTests, which runs only the type inference tests.

That number is a good indicator of the shape of this project. Type inference is the hard part of a Scala plugin, the typechecker has its own test corpus, and the type inference tests are the closest thing to a fast smoke test of whether the plugin's reasoning still works. Everything else about the plugin, highlighting, completion, refactorings, inspections, has a much larger surface and a much slower test.

Running a single test has a quirk that the README calls out, because the Scala plugin project configuration is different from a standard sbt project: you do not need to add the sbt project name before the test name. The command is just testOnly with the test name:

testOnly org.jetbrains.plugins.scala.annotator.Scala3HighlightingTestsMix

The example is a Scala 3 highlighting test, which is a good illustration of the two things a contributor is usually chasing at once, a specific behaviour and a specific Scala version.

What continuous integration actually runs

The CI section is the most useful part of the README for a contributor, because it tells you what will happen to your pull request.

The pull-request workflow runs for changes targeting supported release branches. It builds the Community sources and runs the JUnit 5 bundle, the typechecker and the fast-test tiers. The full test suite is not run, to avoid really long build times. Maintainers can also dispatch those checks manually for a selected branch, and they are not triggered by direct pushes.

The nightly inspection-sanity workflow runs daily, but only after a recent default-branch change, or when started manually. It builds the Community sources and runs GeneralInspectionSanityTest, and it does not repeat the pull-request or full test suite.

The JDK matrix is spelled out as well. The pull-request workflow installs JDKs 8, 11, 17, 21 and 25 so that tests can launch the compatible runtime they need, and the final entry, 25, is the JAVA_HOME used to run sbt itself. The nightly workflow also runs sbt on JDK 25. A test called GitHubWorkflowPolicyTest in ultimate-meta-tests-standalone keeps these defaults aligned with the project's JDK requirement, and that test is not available in the Community repository mirrored to GitHub.

The picture that emerges is sensible for a plugin that has to support an IDE across many runtime versions: fast tiers on every change, an inspection sanity check nightly, and the exhaustive suite reserved for maintainers who can afford to dispatch it.

Three common problems, and why internal mode keeps coming up

The README closes with a troubleshooting section, and it is worth reading because each entry describes a real class of problem in a large sbt and IntelliJ project.

The first is an error saying object BuildInfo is already defined during compilation. BuildInfo is an sbt plugin that exposes some of the build metadata to the main project, used here to forward dependency versions from the build sources to the main project sources. Sometimes during import this generated source root gets added to the bsp and sbt-impl modules more than once, and the fix is to remove the duplicates in File and Project Structure.

The second is not being able to browse IntelliJ Platform sources, which shows up as decompiled code when you open a Platform API class. The platform is downloaded during an sbt load to a directory under the home directory, and the sources should attach automatically after the project is imported and indices are built. When they do not, the fix is the Attach Intellij Sources action, which requires internal mode.

The third is seeing local git changes in files like ImportsPanel.java after a build, where all instances of one border factory call are replaced with another. The stated solution is again to enable internal mode.

So the advice that appears in the prerequisites, enable internal mode, is not optional politeness. It is what makes two of the three documented fixes possible, and any contributor who skips it will hit the third problem and have no documented way out.

Apache-2.0, a moving branch name, and where a newcomer should start

The plugin is licensed under Apache-2.0, with LICENSE.txt at the repository root, and it carries the official JetBrains project badge, which is the marker that the project is maintained by JetBrains rather than by a community around a plugin.

The repository is not archived and the last push was on 2026-10-19, so the work is current. The branch naming is the detail to plan around: the default branch is idea263.x, named after the IntelliJ platform release it targets, and the pull-request workflow runs for changes targeting supported release branches, which means a contribution is expected to be made against a specific release line rather than against a single trunk.

For a newcomer, the practical entry points are the Scala blog for what the team is working on, the YouTrack SCL project for what is broken, and the Discord channel for questions. The README keeps the repository's role narrow on purpose. It is where the code is, and the code is where a contributor with a specific problem in mind should go.

One more piece of context is worth having before you start. The repository is mirrored from the internal JetBrains development setup, so the Community edition sources you see here are the open part of a larger codebase, and the GitHubWorkflowPolicyTest that keeps the JDK defaults aligned runs only in the Ultimate repository's test suite.

Editorial conclusion

Adopt the plugin as a developer tool if you write Scala in IntelliJ IDEA, and note that one CI guard test, GitHubWorkflowPolicyTest, lives in the Ultimate repository's test suite. Do not adopt it as a build system for a team that wants reproducible plugin builds without JetBrains infrastructure, since the workflow assumes IDEA and a local sbt setup. Before you contribute, read CONTRIBUTING.md, enable internal mode as the README recommends, and plan around the test tiers, because the fast tests alone can take over an hour and the full suite does not run on pull requests at all.

Frequently asked questions

Official sources

1. Issues
2. JetBrains/intellij-scala on GitHub
3. License: Apache-2.0
4. Project website
5. README