Prettier Elm plugin

This plugin integrates elm-format into Prettier. In addition to dealing with .elm files via Prettier API, this plugin lets you format Elm code blocks inside markdown documents.

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!"
```

The latest version of prettier-plugin-elm assumes that you are using Elm 0.19. For compatibility with Elm 0.18, please install prettier-plugin-elm@0.3.

Getting started

The instructions assume that you have already installed Node.js on your machine. To check its presence, open the terminal and type these two commands:

node --version
## ≥ 12.15

npm --version
## ≥ 6.14

If you see errors or if the displayed versions are too old, follow the instructions on nodejs.org to download this software. By installing Node.js you also get NPM, so there is no need to obtain it separately. You might need to restart the terminal or the whole machine to see the new versions.

Global install

The easiest way to get started with Prettier and its Elm plugin is to globally install two NPM packages:

npm install --global prettier@2 prettier-plugin-elm

Global install is preferred in simple scenarios, especially when you are working alone on small projects.

Prettier v3 does has dropped support for automatic plugin search so we need to install prettier@2 globally. If you want to use Prettier v3, you need to install it locally and mention prettier-plugin-elm in the config file.

Local install

When collaborating on a group project, it is useful to keep versions of Prettier and its Elm plugin in sync within the team. This avoids frequent unwanted changes in source files, which can be caused by formatting differences between tool versions.

1. Open a terminal and ensure you are located at the root of your project:

   pwd
   ## prints something like /path/to/my/project

2. If there is no package.json file in your project directory, initialize it:

   npm init --yes

   ## if you use yarn instead of npm
   yarn init --yes

3. Run the install command:

   npm install --only=dev prettier prettier-plugin-elm

   ## if you use yarn instead of npm
   yarn add --dev prettier prettier-plugin-elm

   Versions of Prettier and its Elm plugin will be written to package.json and package-lock.json / yarn.lock. If you share these files with the rest of your source code, others will be able to get the exact same versions of the tools by running:

   npm install

   ## if you use yarn instead of npm
   yarn install

4. Mention the plugin in the config file:

   1. Create a file named .prettierrc.json in the root of your project. If you already have this file, open it instead. Note that it can be called differently because Prettier supports several config file names.

   2. Add the following content to the file:

      {
        "plugins": ["prettier-plugin-elm"]
      }

      This tells Prettier to use the Elm plugin when formatting files.

   3. Save the file.

Note that you need to repeat the local install steps for every project.

---

ℹ️ Combining global and local setup is allowed. If two copies of Prettier are available for a given folder, a local one is used.

---

ℹ️ To upgrade Prettier and its Elm plugin, run the same command as you used to install them.

---

ℹ️ Installing prettier-plugin-elm also downloads a compatible version of elm-format, so you do not need to manually obtain it yourself.

Usage

Please complete the the Getting started section first.

Via editor

Follow the instructions on prettier.io to download Prettier extension for your editor. As the second step, you might need to open editor preferences and select Prettier as your preferred file formatter. Most editors can format files on save and you are encouraged to enable this option.

---

ℹ️ You might need to restart the editor if formatting does not work for Elm or Markdown files right away.

Via terminal

If you have a locally installed copy of Prettier, you can configure a script to lint (i.e. check) all your project files and even automatically fix their formatting.

For inspiration, see the scripts section in this project’s package.json. You will also need to create a file named .prettierignore, similar to the one in this project.

## Lint (i.e. check) if all source files are formatted
npm run lint:prettier

## Fix formatting in all files
npm run fix:prettier

## if you use yarn instead of npm

## Lint (i.e. check) if all source files are formatted
yarn lint:prettier

## Fix formatting in all files
yarn fix:prettier

Implementation details

This plugin is written in TypeScript. The quality of the codebase is checked using Prettier, Jest and ESLint via Github Actions. Tests run on Linux, macOS and Windows.

Unlike most other Prettier plugins, prettier-plugin-elm does not contain logic to parse code blocks into syntax trees to then stringify them. Both of these tasks are delegated to elm-format by making a call to a sub-process. Thus, the result of formatting is compatible with what Elm community is used to see.

The only difference to elm-format introduced by prettier-plugin-elm is related to handling fragments of Elm modules, which is not supported upstream yet. See src/parser.ts for details on the workaround.

Contributing

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

To run the development version of prettier-plugin-elm:

• Clone this repository
• Run yarn install
• Run yarn lint to make sure that the codebase passes linting
• Run 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 named 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!