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]
.
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.
## 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"
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.
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.
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 runyarn prettier --plugin=. prettier-test.elm
(or.md
) and check the output.
This project was inspired by https://github.com/prettier/plugin-python.
Big thanks to Aaron VonderHaar (@avh4) and contributors for creating elm-format
!