elm-format formats Elm source code according to a standard set of rules based on the official Elm Style Guide
Haskell Elm JavaScript HTML Shell Python Other
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
Release Notes Update 0.7.0-exp release notes May 14, 2017
Style Guide Add CI info to the guide May 14, 2017
ci Add Concourse CI scripts for windows and linux Apr 16, 2016
img Update JetBrains setup screenshot to reflect new layout Apr 16, 2017
markdown explicit PatternGuards extension Jan 26, 2018
package Bump version to 0.8.0-alpha-elm019rc1-rc2 May 17, 2018
parser Disentangle module alias lookup from the JSON AST serialization Aug 18, 2018
src-cli Add elm-format-0.19 binaries and remove 0.17 Apr 14, 2018
src Merge pull request #505 from harrysarson/patch-1 Aug 18, 2018
tests Fix CI on Windows (attempt #1) Aug 18, 2018
.dockerignore Update publishing instructions Mar 25, 2017
.gitignore Add --json option and JSON output of variable references Mar 16, 2018
.travis.yml Remove test dependency on ajv Mar 26, 2017
BuildFromSource.hs Don't needlessly install elm-reactor Sep 13, 2015
CHANGELOG.md Use System.FilePath functions to check filenames and extensions Jun 12, 2018
CODE_OF_CONDUCT.md Add Contributor Code of Conduct May 5, 2017
Dockerfile Upgrade to latest stack version to avoid commercialhaskell/stack#3634 May 6, 2018
HLint.hs Fix warnings Oct 3, 2015
LICENSE Inline usage of Text.Parsec.Token Apr 11, 2018
PUBLISHING.md Update publishing instructions May 18, 2017
README.md Update vscode table in readme Jun 29, 2018
Setup.hs Fix Travis-CI Mar 26, 2017
appveyor.yml Use 32-bit stack on appveyor builds Mar 26, 2017
cabal.config Enable ghc --split-objs to reduce build size Jun 9, 2016
elm-format.cabal Disentangle module alias lookup from the JSON AST serialization Aug 18, 2018
install_system.sh Add elm-format-0.19 binaries and remove 0.17 Apr 14, 2018
stack.yaml Upgrade to latest stack version to avoid commercialhaskell/stack#3634 May 6, 2018

README.md

Build Status latest version: 0.7.0-exp

elm-format

elm-format is still in alpha. If you run into any problems, please report them.

The format produced by elm-format may change significantly before the 1.0.0 release. If this will cause problems for you, please refrain from using elm-format during the alpha- and beta-test periods.

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 Main.elm  # Format a single file
elm-format Main.elm --yes  # Overwrite the file without prompting
elm-format src/  # Format all *.elm files in a directory
elm-format --stdin  # Format input from stdin and write to stdout
elm-format --stdin --output Main.elm  # Format input from stdin and write to file
elm-format --help  # See other command line options

Installation (latest version: 0.7.0-exp)

elm-format is still in alpha. If you run into any problems, please report them.

The format produced by elm-format may change significantly before the 1.0.0 release. If this will cause problems for you, please refrain from using elm-format during the alpha- and beta-test periods.

Experimental version

The latest version of elm-format contains experimental features that may or may not appear in future releases. If you are able to tolerate some amount of instability on your Elm projects, you can help with the development of elm-format by using the experimental version and providing feedback. You can give feedback about the latest experimental version here.

To install the experimental version:

npm install -g elm-format@exp

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.

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 Language Support ⚠️ 3 steps βœ… ⚠️ requires configuration ❔ TBD ❔ TBD
Sublime Text πŸ† Elm Language Support βœ… 2 steps ❔ TBD βœ… ❔ TBD ❔ TBD
JetBrains (WebStorm, etc) πŸ† Elm Language Plugin ⚠️ 4 steps ❔ TBD βœ… ❔ TBD ❔ 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. Set elm-format-on-save to t to apply elm-format on the current buffer on every save. (The setting can be changed via M-x customize-variable elm-format-on-save. Click button Toggle to change the setting and button State to activate the setting.)

elm-vim installation

  1. Install elm-format

  2. Install vim-plug (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 there is a section like this in your ~/.vimrc:

      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

Note: If you previously installed a VSCode extension called "elm-format", uninstall it (it is deprecated, and the "elm" extension now provides elm-format integration).

  1. Install elm-format

  2. Install Elm Language Support for VSCode

    ext install elm
  3. Configure the extension to format on save:

    1. Go to Preferences -> Settings in the menu
    2. In your User Settings, update the following value:
    "[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.

  1. Install elm-format
  2. Install the Elm Language Plugin package.
  3. Install the File Watchers plugin (available in the plugin repository)
  4. Add a file watcher for .elm files with the settings as shown here.

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

brew install haskell-stack
git clone https://github.com/avh4/elm-format.git
cd elm-format
stack setup
stack build
stack install
~/.local/bin/elm-format-0.18 --help

Running tests

brew install shellcheck
./tests/run-tests.sh