Documentation for the Elm Land VS code plugin
With the Elm Land plugin, every feature (except "Syntax highlighting") is fully optional. By default, all features are enabled. If you prefer a more minimal editing experience, you can disable any feature in your VS Code "User Settings".
This section breaks down what each feature does, and the VS code configuration setting that enable/disable it.
Setting: None
Provides basic syntax highlighting to help you visually scan your Elm code, increase readability, and provide context. This feature is the only one that cannot be disabled.
Setting: formatOnSave
Uses elm-format to automatically format your code on save. This requires the elm-format command to be installed on your computer, and the VS code plugin can take care of that for you if you already have Node.js installed.
Setting: elmLand.feature.errorHighlighting
If your Elm code doesn't compile, this feature will underline the relevant problems in your editor. It depends on a local installation of elm on your computer.
When you open an Elm file, or save one, you'll see a red underline under each compiler error.
Note: The Elm Land plugin will also check the elmLand.entrypointFilepaths setting to compile the top-level Elm program. This allows the editor to report errors in other files. If your project doesn't use src/Main.elm as the program's entrypoint, change the elmLand.entrypointFilepaths settings in that workspace's .vscode/settings.json file.
Setting: elmLand.feature.jumpToDefinition
You can jump to the definition of any function or value, even if it's defined in another module. This is helpful for quickly navigating around.
Setting: elmLand.feature.offlinePackageDocs
Every Elm package in the ecosystem comes with built-in documentation. With this feature, even if you're offline, you can access this documentation from within your editor.
Setting: elmLand.feature.autocomplete
Every Elm module in your project, and any Elm package you installed will provide autocomplete information for the exposed types, functions, and values. To see more detailed documentation, you can even toggle details panel for each autocomplete suggestion.
Setting: elmLand.feature.htmlToElm
To help you convert HTML snippets to Elm code and help newcomers learn the syntax of Elm, this plugin comes with a built-in "HTML to Elm" action whenever you highlight over a snippet of HTML code.
Elm's editor plugins repo recommends doing performance profiling to help others learn how different editors implement features, and also to help try to think of ways to bring down costs.
This VS code plugin was specifically designed to have near-zero memory overhead ¹, and to avoid in-memory indexing that cache your codebase before invoking features. For this reason, it's been very effective at Vendr, even though the frontend codebase is over 400k lines of Elm code.
These benchmarks were taken on a MacBook Pro (2020) ² testing this editor plugin against Vendr's codebase, which has 578k lines of Elm code across 3,384 Elm files.
| Feature | Average Speed | Constant RAM Overhead | Cumulative CPU Costs |
|---|---|---|---|
| Format on save | <200ms | None | On command |
| Error highlighting | <500ms | None | On file open and save |
| Jump-to-definition | <600ms | None | On file open and save |
| Offline package docs | <400ms | None | On command |
| Module import autocomplete | <100ms | None | On key stroke |
| Convert HTML to Elm | <100ms | None | On command |
These benchmarks were taken on a Windows PC ³ testing this editor plugin against rtfeldman/elm-spa-example repository, which has 3.8k lines of Elm code across 34 files.
| Feature | Average Speed | Constant RAM Overhead | Cumulative CPU Costs |
|---|---|---|---|
| Format on save | <300ms | None | On command |
| Error highlighting | <500ms | None | On file open and save |
| Jump-to-definition | <150ms | None | On file open and save |
| Offline package docs | <100ms | None | On command |
| Module import autocomplete | <100ms | None | On key stroke |
| Convert HTML to Elm | <100ms | None | On command |
The only in-memory overhead from this plugin comes from caching the contents of your elm.json files within the current workspace, and any docs.json files for packages that you are using.
This means a tiny project with 10 lines of Elm code and a huge project with 500k+ lines of Elm code would have the same RAM overhead– assuming they both had the same Elm package dependencies.
The MacBook Pro used for benchmarking had the following specifications:
- Model: MacBook Pro (13-inch 2020)
- OS: macOS Ventura 13.2.1
- Processor: 1.7 GHz Quad-Core Intel Core i7
- Memory: 16GB
The Windows PC used for benchmarking has the following specifications:
- OS: Windows 11 Home 64-bit
- Processor: Intel(R) Core(TM) i9-9980HK CPU @ 2.40GHz (16 CPUs), ~2.4GHz
- Memory: 16GB
This VS Code plugin was made possible by the following open-source projects. Thank you to everyone for doing the hard work of making compilation, formatting, syntax highlighting, and AST parsing a solved problem:
Evan Czaplicki (@evancz)
Evan laid an incredible foundation for this plugin project. This includes everything from helpful READMEs like the ones in elm/editor-plugins to the design choices like storing documentation offline in the ELM_HOME directory.
I couldn't have done Error highlighting without the elm/compiler, nor implemented the Offline package docs UI without helpful packages like elm/project-metadata-utils.
Thanks so much, Evan- you made the plugin authoring experience a breeze!
Mats Stijlaart (@stil4m)
The stil4m/elm-syntax package made it possible for me to include Jump to definition, Module import autocomplete, and the Offline Package Docs features. Creating a reliable Elm parser that I could run within my VS code extension would have been a difficult hurdle for me.
Thank you, Mats! This AST parser was a huge part of the plugin work.
Aaron VonderHaar (@avh4)
Aaron's work on avh4/elm-format made it possible for me to quickly provide the Format on save feature by running your CLI tool directly. The performance is great, and the NPM installer makes it easy for folks to install it on their machines.
Thank you, Aaron, elm-format is awesome!
Kolja Lampe (@razzeee)
Kolja's work on the elm-tooling/elm-language-client-vscode made Syntax highlighting possible. The elm-syntax.json and codeblock.json were already battle-tested and reliable from the existing Elm LS plugin.
Thank you Kolja, and the folks in elm-community, for providing this open-source project for tooling authors like me to learn from and build!
Rupert Smith (@the-sett)
When adding the HTML to Elm feature, both the the-sett/elm-pretty-printer and the-sett/elm-syntax-dsl allowed me to turn an Elm AST into an elm-format compatible string.
Thank you Rupert and pwentz for your contributions to these repos!
Jim Sagevid (@jims)
Jim provided the HTML parser that powers the HTML to Elm feature. The jims/html-parser package made it easy for to add the feature to help lower the learning curve for newcomers to Elm.
Thank you, Jim! Your Elm package rocks!
Great! This project is focused on the following high-level goals:
-
Every feature should work reliably.
Any developer using Mac, Windows, or Linux should be able to download this plugin, and have it reliably work for any valid Elm project.
-
Create a fully configurable experience
Many users prefer less visual noise when coding, or only want the Syntax Highlighting feature. We should support those folks by providing an easy way to opt-out of undesired editor features.
-
Minimize performance overhead
Some features have been omitted because they had undesirable performance implications. When a company scales their Elm project, this plugin should scale with them!
The goal of this plugin is to ensure every feature works reliably and scales with large Elm codebases. The tradeoff is that it doesn't have as many features as more robust plugins like the Elm Language Server plugin.
The features below have been left out for now, but you might be able to help add them to the official Elm Land plugin:
Something that would make this plugin even better would be a "Find usages" feature. This would enable folks to quickly scan their Elm codebase for all occurences of any type or value.
Back in 2019, Evan outlined a cool project for the community, called elm-find. Just like elm-format or elm itself, it would have the following characteristics:
- No constant RAM overhead
- Fast as possible
If you are interested in creating a super fast tool to help improve the Elm ecosystem, we would love to benefit from your implementation of elm-find!
Once that project is available, I can update this plugin to have features like Find usages or Bulk rename.
Hoping to add another feature?
Come join the Elm Land Discord and start a conversation in #vscode!