elm-format

elm-format formats Elm source code according to a standard set of rules based on the official Elm Style Guide. It is inspired by the popular gofmt.

The benefits of elm-format:

• It makes code easier to write, because you never have to worry about minor formatting concerns while powering out new code.
• It makes code easier to read, because there are no longer distracting minor stylistic differences between different code bases. As such, your brain can map more efficiently from source to mental model.
• It makes code easier to maintain, because you can no longer have diffs related only to formatting; every diff necessarily involves a material change.
• It saves your team time debating how to format things, because there is a standard tool that formats everything the same way.
• It saves you time because you don't have to nitpick over formatting details of your code.

Usage

elm-format .  # Format all *.elm files in the current directory
elm-format Main.elm  # Format a single file
elm-format Main.elm --yes  # Overwrite the file without prompting
elm-format src/ Main.elm  # Format the listed files and directories
elm-format --help  # See other command line options

Installation

To install elm-format:

npm install -g elm-format

or download the version appropriate for your OS from the release page, unzip it, and place elm-format or elm-format.exe (windows) on your PATH.

You must run elm-format from the directory that contains your elm.json (for Elm 0.19) or elm-package.json (for Elm 0.18), or else you must pass the appropriate --elm-version=0.19/--elm-version=0.18 command line argument.

Editor integration

Find your editor in the table below. The recommended plugin for each editor is indicated with 🏆 (trophy emoji).

Editor	Plugin	Installation	Formatting	Format on save	Configuration	Error handling
Atom	🏆 atom-elm-format	✅ 2 steps	✅	✅	✅	⚠️ no installation instructions
	atom-beautify	⚠️ 3 steps	✅	⚠️ requires configuration	✅	✅
Light Table	🏆 elm-light	⚠️ 3 steps	✅	⚠️ requires configuration	✅	⚠️ no installation instructions
Vim	🏆 elm-vim	❌ 6 steps	✅	⚠️ requires configuration	✅	❌ no error message
Emacs	🏆 elm-mode	❌ 4 steps	✅	⚠️ requires configuration	✅	⚠️ no installation instructions
Visual Studio Code	🏆 Elm Tooling	⚠️ 3 steps	✅	⚠️ requires configuration	✅	❌ uninformative error message
Sublime Text	🏆 Elm Language Support	✅ 2 steps	❔ TBD	✅	❔ TBD	❔ TBD
JetBrains (WebStorm, etc)	🏆 intellij-elm	⚠️ 4 steps	✅	⚠️ requires configuration	⚠️ requires configuration	❔ TBD
TextMate	🏆 Elm.tmbundle	✅ 2 steps	❔ TBD	❔ TBD	❔ TBD	❔ TBD

Detailed instructions

If you can simplify or improve the installation instructions or add instructions for another editor, please make a pull request. The default behavior of elm-format-approved plugins is to format Elm files on save.

atom-elm-format installation

1. Install elm-format

2. Install atom-elm-format

   apm install elm-format
   

or use the Atom package manager in Atom's settings

atom-beautify installation

1. Install elm-format

2. Install atom-beautify

   apm install atom-beautify
   

or use the Atom package manager in Atom's settings

1. Use ^⌥B (CTRL-ALT-B) to format a file

elm-light installation

1. Install elm-format
2. Install the elm-light plugin using the Light Table plugin manager
3. To format on save, edit your user keymap by performing the following:

• Click File -> Settings -> User Keymap to open the user keymap.
• Copy the following line and paste it into your keymap. Anywhere is fine as long as it is whithin the outer brackets. Ensure to save the file.

[:editor.elm "ctrl-s" :save :elm-format :elm.lint]

• Search for "App: Reload keymaps" in the Commands Window to apply the changes (or restart LightTable).

elm-mode installation

1. Install elm-format

2. If your Emacs has package.el (which is automatically the case for Emacs >= 24), you can install elm-mode from the package in MELPA:

   1. Ensure that you have added the MELPA source in your ~/.emacs.d/init.el:

      (require 'package)
      (add-to-list 'package-archives '("melpa" . "http://melpa.org/packages/"))

   2. Install elm-mode (official instructions): Use M-x list-packages and choose elm-mode.

3. Add the following to your ~/.emacs.d/init.el:

   (add-hook 'elm-mode-hook 'elm-format-on-save-mode)

elm-vim installation

If you are an advanced vim user and already have a preferred vim plugin installation method, you may prefer to refer to the official elm-vim installation instructions. The instructions below are for those who need a step-by-step walkthrough of how to get the plugin set up.

1. Install elm-format

2. Install vim-plug (official instructions) NOTE: if you are using neovim, you will need to refer to the official instructions.

   1. Download vim-plug:

      curl -fLo ~/.vim/autoload/plug.vim --create-dirs \
          https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim

   2. Make sure ~/.vimrc exists and has a section like this:

      call plug#begin('~/.vim/plugged')
      " ... any active plugins
      call plug#end()

3. Install elm-vim (official instructions)

   1. Add Plug 'elmcast/elm-vim' to the plug#begin plugin section in your ~/.vimrc
   2. Start vim and run :PlugInstall

4. Add the following to your ~/.vimrc:

let g:elm_format_autosave = 1

Visual Studio Code installation

1. Install elm-format

2. Install the extension Elm Plugin for Visual Studio Code.

3. Configure the extension to format on save:

   1. Find your settings.json file (instructions).
   2. Add the following key-value pair to your settings.json:

   "[elm]": {
       "editor.formatOnSave": true
   },

Sublime Text installation

1. Install elm-format
2. Install the Elm Language Support package.

JetBrains installation

This is for WebStorm and other JetBrains IDEs like IntelliJ and PyCharm.

1. Install elm-format

2. Install the intellij-elm plugin

3. In IntelliJ, open Settings -> Languages & Frameworks -> Elm

   1. Specify the path to elm-format (try the "Auto Discover" button first)
   2. Check the "Run when file saved?" checkbox

Development info

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Building from source

1. Install Haskell ghcup following the instructions for your operating system: https://www.haskell.org/ghcup/

# check out the repo
git clone https://github.com/avh4/elm-format.git
cd elm-format

# initial setup
ghcup install ghc 8.10.4
ghcup set ghc 8.10.4

# build
./build.sh -- build

# run the built elm-format
./_build/elm-format

Running tests

./build.sh