DEV Community: Ilias Van Peer

Elm tools

Ilias Van Peer — Sun, 03 Feb 2019 10:52:40 +0000

Elm, besides being an awesome language with a nice ecosystem of packages, also has an incredible ecosystem of tools. In this post, I list a few of my favourite ones and quite shamelessly plug a few of my own.

`elm-format`

npm i elm-format

One of the best known tools in the Elm ecosystem, this one needs no introduction.

A quick overview:

zero-config formatting of all your Elm code
integrations with popular editors
can be used in CI using the --validate flag

`elm-test`

npm i elm-test

elm-test is your one-stop shop for testing Elm code. Useful for plain old unit tests, property-based tests using fuzz tests, as well as inspecting generated HTML using Test.Html.Query in combination with some selectors, it enables some really powerful testing scenario's.

The de-facto way of using elm-test is through the node-based test-runner.

Noteworthy: it's supported on travis, too!

`elm-verify-examples`

npm i elm-verify-examples

Incredibly useful when writing documentation for your packages, elm-verify-examples allows running your examples and verifying their correctness.

If you're publishing packages, this should be part of your CI setup!

`elm-doc-preview`

npm i elm-doc-preview

Writing documentation for a package is so much easier when there is a nice way to preview what it will actually look like. And that's where elm-doc-preview comes in!

elm-doc-preview can be used locally, but also exists as a hosted version that can preview docs for GitHub repositories, as long as a README.md and docs.json are committed.

`elm-doc`

npm i elm-doc

Along the same lines, but geared towards writing applications, elm-doc allows viewing the docs of all of your dependencies in one single location, fully offline.

Disclaimer: I made this

`elm-analyse`

npm i elm-analyse

elm-analyse analyses your Elm code and can help identify a bunch of (potential) issues, while also allowing quick-fixes for a bunch of best practices. Very cool tool!

`elm-xref`

npm i elm-xref

Inspired by Erlang/OTP's http://erlang.org/doc/apps/tools/xref_chapter.html, elm-xref is a cross-referencing tool.

This essentially means that it can do static analysis of your codebase and identify unused functions (both private and exposed), or look for all the places a given function is used.

Disclaimer: I also made this

`elm-dependencies-analyzer`

An online tool that analyses your elm.json, and can tell you which of your dependencies have updates available, shows your potential incompatibilities between the available versions of your dependencies, and so on.

If you've ever wondered why you can't update elm/http, this tool can tell you why!

`@dillonkearns/elm-graphql`

If you're using GraphQL with Elm (or want to use GraphQL with Elm), this package/tool combination allows generating a type-safe interface to your GraphQL backend based on the schema.

Great docs, very well thought-out API, and overall an absolute joy to work with!

Did I miss any of the tools you love to use? Feel free to point out in comments!

The `elm-package.json` file

Ilias Van Peer — Thu, 28 Dec 2017 09:20:45 +0000

The elm-package.json file contains metadata about your application or package. The Elm platform uses it to compile your code and distribute it as a package.

To create a basic elm-package.json file, you can execute elm-package install or elm-make. This will set up a simple project and download the default dependencies.

{
    "version": "1.0.0",
    "summary": "helpful summary of your project, less than 80 characters",
    "repository": "https://github.com/user/project.git",
    "license": "BSD3",
    "source-directories": [
        "."
    ],
    "exposed-modules": [],
    "dependencies": {
        "elm-lang/core": "5.1.1 <= v < 6.0.0",
        "elm-lang/html": "2.0.0 <= v < 3.0.0"
    },
    "elm-version": "0.18.0 <= v < 0.19.0"
}

Overview

Property	Relevant for applications	Relevant for packages
`version`		x
`summary`		x
`repository`		x
`license`		x
`source-directories`	x	x
`exposed-modules`		x
`dependencies`	x	x
`elm-version`	x	x

Note: All properties are required, even if not marked above as relevant. Properties not relevant to your project are best left with their default values intact.

`version`

There is no need to ever touch this for applications.

The version property defines the semantic version of the public API of your package.

Only stable packages can be published to http://package.elm-lang.org/. As such, version numbers start at 1.0.0.

There is generally no need to manually modify this value. Instead, when you are ready to publish a new version, use elm-package bump which will compare your API to the previously uploaded version and decide on the correct new version number to apply.

Before a version can be published with elm-package publish, it need to be tagged and the tag must be published. Using elm-package publish before doing so will give you specific instructions on how to tag and push that tag.

`summary`

There is no need to ever touch this for applications.

80 character (max) description of your package.

This is the description that shows up on the package listing at http://package.elm-lang.org. In order for people to be able to find your package, it's a good idea to use relevant keywords in here.

`repository`

There is no need to ever touch this for applications.

For packages, this should be the git repository, accessible over https, as hosted on GitHub. You will only want to change the user/project part of the URL, and leave the https://github.com/ prefix and .git suffix intact.

Note that this entry is case sensitive. If you do not use the exact same casing here as your actual GitHub username or GitHub repository, installation will not function correctly.

You'll generally want to refrain from using any "special" characters here. Using dots in the username or project, for example, will break the compiled code.

Unless your GitHub username is Elm-specific (for example elm-lang), it's generally a good idea to prefix the package name with elm-. This makes it easier for people to discover your package on GitHub.

`license`

There is no need to ever touch this for applications.

License under which you release this code. Note that most licenses also require a LICENSE file to be included in your repository as well as a copyright notice in your README in order to actually be valid.

Using the license generator on GitHub makes this a fairly painless process.

At the moment, this field is not restricted. However, it is recommended to use a proper SPDX license identifier.

`source-directories`

The source-directories property gives a list of (relative) paths where the Elm compiler will look for modules referenced in your code.

Typically, this will look like ["src"] if your sources live in the src directory, relative to the location of elm-package.json. In the case of the elm-package.json for elm-test, there would typically be a corresponding [".", "../src"] entry (the first is where you tests are, the second is where the code under test is).

Note that there is a direct mapping of filepaths to module names in Elm. For example, given a "source-directories": ["src"], the module Foo.Bar.Baz should live at src/Foo/Bar/Baz.elm.

On Mac OS X, the filesystem is case aware, but not case sensitive. What this means is that during development, you can probably get away with naming the above file src/fOO/bAR/bAZ.elm. However, people using your packages may be using case sensitive filesystems, so your package will not work for them.

As such, please use the exact same case for the path as for the module names.

`exposed-modules`

There is no need to ever touch this for applications.

The exposed-modules property indicates which modules from your package are exposed. Modules added to this list will be shown on http://package.elm-lang.org and, when a user installs your package as a dependency, the exposed modules will be available to import.

When a module is added to the exposed-modules property, elm-make will enable an extra set of checks for those modules to ensure that all exposed variables are properly documented. You can read a bit more on the exact format for documentation on package.elm-lang.org/help/documentation-format.

`dependencies`

This is probably the most important property for applications. It consists of a map of each dependency's name (identified by its author's name combined with a package name) to a range of semantic versions. The general syntax is <minimal> <= v < <maximal>.

For applications, it's generally a good idea to limit ranges or even pin them to specific versions (1.2.3 <= v < 1.2.4 would only allow version 1.2.3, for example). This prevents you from accidentally relying on behaviour that may change. To be extra-safe, one can also add transient dependencies here and pin those, too. That way, elm-package.json can double as a lock-file.

For libraries, it's recommended to use broad ranges (to minimize the risk of running into dependency conflicts) while also limiting the number of dependencies. For example, if you only need a single function from some package, it may be better to replicate that function rather than pull that package in as a dependency, and making consumers of your package depend upon it as well.

`elm-version`

This is a semantic version range specifying the version(s) of Elm your package is compatible with. You'll probably want to leave it set to its default value, unless upgrading a package from an older version of Elm to 0.18.