Context Mapper IntelliJ Plugin

NOTE: This plugin is a proof of concept. It does not support all Context Mapper features yet.

Context Mapper is an open source tool providing a Domain-specific Language based on Domain-Driven Design (DDD) patterns for context mapping and service decomposition.

System Requirements

To use the Context Mapper IntelliJ plugin you need the following tools (besides IntelliJ and our extension) installed locally:

• Oracle Java or OpenJDK (JRE 11 or newer)
• Node.js (v22)
• Maybe you want to install a PlantUML extension for the generated PlantUML diagrams.
• Graphviz if you want to render generated PlantUML diagrams in IntelliJ.
• LSP4IJ IntelliJ plugin (will be installed automatically when installing our plugin)

Getting Started

This plugin provides Context Mapper DSL support in IntelliJ. It recognizes .cml files, starts the bundled Context Mapper language server through LSP4IJ, provides semantic highlighting, and can ask the language server to generate PlantUML .puml diagrams.

1. Install the IntelliJ plugins

Install the Context Mapper plugin ZIP in IntelliJ:

1. Open Settings > Plugins.
2. Click the gear icon and choose Install Plugin from Disk....
3. Select the built plugin ZIP from build/distributions/context-mapper-intellij-plugin.zip.
4. Restart IntelliJ when prompted.

The Context Mapper plugin depends on LSP4IJ. IntelliJ should install LSP4IJ automatically with this plugin. If syntax highlighting or generation does not work, check that both plugins are enabled under Settings > Plugins.

2. Install local tools

The Context Mapper language server is a Node.js process. Make sure node is installed and visible to IntelliJ:

node --version
which node

On macOS with Homebrew, Node is commonly installed under /opt/homebrew/bin/node. If IntelliJ was launched from Finder and cannot find Node, restart IntelliJ after installing Node or set the CONTEXT_MAPPER_NODE environment variable to the full Node executable path before launching IntelliJ.

To preview generated PlantUML diagrams inside IntelliJ, install the PlantUML Integration plugin and Graphviz:

brew install graphviz
which dot
dot -V

Then configure the PlantUML plugin's Graphviz/Dot executable path to the result of which dot, for example /opt/homebrew/bin/dot. A common broken default is /opt/local/bin/dot, which is a MacPorts path and may not exist on Homebrew-based systems.

3. Create a simple CML file

Create a file such as architecture/context-maps/example.cml:

ContextMap ExampleMap {
  contains OrderingContext
  contains BillingContext

  OrderingContext [SK]<->[SK] BillingContext
}

BoundedContext OrderingContext {
  type = APPLICATION
  domainVisionStatement = "Handles customer order placement."
}

BoundedContext BillingContext {
  type = APPLICATION
  domainVisionStatement = "Handles invoicing and payment workflows."
}

Syntax highlighting should appear after the file opens. If the file icon appears but keywords are not colored, the file type is registered but the language server may not be running.

4. Generate a PlantUML diagram

Open the .cml file in the editor, then run:

1. Right-click inside the editor.
2. Choose Context Mapper > Generate PlantUML Diagrams.

You can also search for the action with Cmd+Shift+A and run Generate PlantUML Diagrams.

The generated file is written to:

<project-root>/src-gen/<source-file-name>.puml

For example:

src-gen/example.puml

Open that .puml file to preview it with the PlantUML plugin.

Troubleshooting

If .cml files have the Context Mapper icon but no syntax highlighting, verify that LSP4IJ is enabled and that IntelliJ can start Node. Search the IntelliJ log for cml-language-server, contextmapper, LSP4IJ, or node.

If generation reports that no PlantUML diagrams were created, make sure the .cml file contains a ContextMap. Standalone BoundedContext declarations are valid CML, but the current generator creates a component diagram from the first ContextMap in the file.

If the PlantUML preview shows Cannot find Graphviz, the generated .puml file is usually fine. Configure the PlantUML plugin's Dot executable to the path returned by which dot.

Build and/or Run Extension Locally

This project uses Gradle to build the IntelliJ plugin.

Requirements

To be able to work on the plugin in IntelliJ, you need to have the Plugin DevKit plugin installed.

The language server package is downloaded from the GitHub NPM registry, which requires you to provide an authentication token. You can get a token by creating a personal access token in your GitHub account. Make sure that the token includes the package:read permission.

To configure the registry and authentication, add this configuration to the .npmrc file in your home directory.

@contextmapper:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=<TOKEN>

Commands

After cloning this repository, you can build the project with the following command:

./gradlew clean buildPlugin

Before installing a built plugin ZIP into a newer IntelliJ IDEA version, verify plugin compatibility:

./gradlew verifyPlugin

The verifier target defaults to IntelliJ IDEA Ultimate 2026.1.3. Override it when needed:

./gradlew verifyPlugin -PintellijVerifierIdeVersion=<IDE_VERSION>

Use the following command to build and run the plugin:

./gradlew runIde

Contributing

Contribution is always welcome! Here are some ways how you can contribute:

• Create Github issues if you find bugs or just want to give suggestions for improvements.
• This is an open source project: if you want to code, create pull requests from forks of this repository. Please refer to a Github issue if you contribute this way.
• If you want to contribute to our documentation and user guides on our website https://contextmapper.org/, create pull requests from forks of the corresponding page repo https://github.com/ContextMapper/contextmapper.github.io or create issues there.

Licence

ContextMapper is released under the Apache License, Version 2.0.