Prettier Elm plugin

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 cross-language interface to code formatting. 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 <!-- prettier-ignore --> 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 [email protected].

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

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

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

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 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 or its Elm plugin 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

This plugin is written in TypeScript and its quality is maintained using Prettier, TSLint and Jest. Azure Pipelines continuously run checks on Linux, macOS and Windows.

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.ts 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 run prettier-plugin-elm locally:

• Clone this repository.
• Execute yarn install.
• Execute yarn lint to make sure that the code passes formatting and linting.
• Execute yarn test to make sure that TypeScript successfully compiles into JavaScript and and all unit tests pass.
• To test the plugin manually, create a file called prettier-test.elm (or .md), then run yarn prettier --plugin=. prettier-test.elm (or .md) and check the output.

Credits

This project was inspired by https://github.com/prettier/plugin-python.

Big thanks to Aaron VonderHaar (@avh4) and contributors for creating elm-format!