Prettier-plugin-elm NPM

Please note that the plugin ecosystem in Prettier is still beta, which may make prettier-plugin-elm not ready for production use yet.

This plugin integrates elm-format into Prettier, thus providing you with a universal interface to code formatting regardless of its language. In addition to dealing with .elm files via Prettier API, this plugin lets you format Elm code blocks inside markdown files. For example

#    Hello world in Elm
```elm
import  Html exposing     (text)

main = text      "Hello, World!"
```

becomes

# Hello world in Elm

```elm
import Html exposing (text)


main =
    text "Hello, World!"
```

You can disable code formatting for a particular code block by adding  before ```elm.

Elm code with custom formatting:

<!-- prettier-ignore -->
```elm
main = text      "Hello, World!"
```

Prettified code:

```elm
main =
    text "Hello, World!"
```

In order to successfully format Elm code in markdown blocks, prettier-plugin-elm assumes your Elm version is 0.19. If you use Elm 0.18, please install prettier-plugin-elm@0.3.

Getting started

Simply install prettier and prettier-plugin-elm as your project’s npm dependencies:

cd /path/to/project

## initialise an npm project if you haven’t done it yet
npm init
## or
yarn init

## add Prettier and its Elm plugin to project’s dev dependencies
npm install --dev prettier prettier-plugin-elm
## or
yarn add --dev prettier prettier-plugin-elm

Installing prettier-plugin-elm also installs a local copy of elm-format, so you do not need to manually obtain one yourself.

Usage

## format all elm files in your project
./node_modules/.bin/prettier --write "**/*.elm"
## or
yarn prettier --write "**/*.elm"

## format all markdown files including ```elm code blocks inside them
./node_modules/.bin/prettier --write "**/*.md"
## or
yarn prettier --write "**/*.md"

Integration with editors

Use of this plugin in Atom and VSCode seems to be blocked by prettier/prettier-atom#395 and prettier/prettier-vscode#395. Feel free to help!

If you are using a text editor that supports Prettier integration (e.g. Atom or VSCode), you can have all Prettier perks for your Elm code too!

In order to get prettier-plugin-elm working in projects that do not have local npm dependencies, you can install this plugin globally:

npm install --global prettier prettier-plugin-elm

In this case, you might need to check the settings of your editor’s Prettier extension to make sure that a globally installed Prettier is used when it is not found in project dependencies (i.e. package.json).

Nevertheless, it is recommended to always rely on local copies of prettier and prettier-plugin-elm as this reduces the chance of formatting conflicts between project collaborators. This may happen if different global versions of Prettier are used.

Installing prettier-plugin-elm either locally or globally may require you to restart the editor if formatting does not work right away.

Implementation details

Unlike other Prettier plugins, prettier-plugin-elm does not parse the code into a syntax tree to then print it; both of these tasks are delegated to elm-format and are executed in a single call to a sub-process. Thus, the result of formatting is compatible with what Elm community is used to see.

The only difference that prettier-plugin-elm introduces is related to handling fragments of Elm modules, which is not yet supported by elm-format. See src/parser.js for details on this.

Contributing

If you’re interested in contributing to the development of Prettier for Elm, you can follow the CONTRIBUTING guide from Prettier, as it all applies to this repository too.

To test it out on an Elm file:

Clone this repository.
Run yarn.
Create a file called prettier-test.elm or prettier-test.md.
Run yarn prettier prettier-test.elm or yarn prettier prettier-test.md to check the output.