What is an Elm Package?

  • Elm package repository
  • Elm packages enforce SemVer for the public package API
  • The SemVer (Semantic Versioning) Spec
  • Interesting note: the SemVer spec says breaking changes only refers to the public API. But a core contributor clarifies that breaking changes can come from changes to the public contract that you intend users to depend on. See this GitHub thread.
  • list-extra package
  • dict-extra package
  • Minimize dependencies in your package to make it easier for users to manage their dependencies
  • "Vendoring" elm packages (using a local copy instead of doing elm install author/package-name) can be useful in some cases to remove a dependency from your package

Should you publish a package?

  • The Elm package ecosystem has a high signal to noise ratio
  • Elm packages always start at version 1.0.0
  • SemVer has different semantics before 1.0.0 (patch releases can be breaking before 1) - see SemVer spec item 4

Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.

  • Elm package philosophy is to do an alpha phase before publishing package

Keep yourself honest about solving meaningful problems

  • Start by asking "What problem are you solving? Who are you solving it for?"
  • Scratch your own itch
  • elm-graphql
  • servant-elm (for Haskell servant)
  • Keep yourself honest about solving problems by starting with an examples/ folder

Make it easy for people to understand your package goals and philosophy

Porting libraries vs. Coming Up With an Idiomatic Solution for Elm

  • Instead of moment js ported to Elm, have an API built for a typed context
  • Ryan's date-format package

How to design an Elm package API

Pay attention to how other packages solve problems

Pick your constraints instead of trying to solve every problem

  • Helps you choose between tradeoffs
  • Having clear project goals explicitly in your Readme makes it easier to discuss tradeoffs with users and set expectations
  • Idiomatic elm package guide has lots of info on basic mechanics and best practices for publishing Elm packages

The mechanics of publishing an elm package

  • elm make --docs docs.json will tell you if you're missing docs or if there are documentation validation errors
  • elm-doc-preview
  • Can use elm-doc-preview site to share documentation of branches, or packages that haven't been published yet
  • Set up a CI
  • Dillon's CI script for dillonkearns/elm-markdown package
  • Dillon's elm-publish-action GitHub Action will publish package versions when you increment the version in your elm.json - nice because it runs CI checks before finalizing a new package release
  • elm publish will walk you through the steps you need before publishing the first version of your Elm package
  • #packages channel on the Elm slack shows a feed of packages as they're published
  • #api-design channel on the Elm slack is a good place to ask for feedback on your API design and package idea

Continue the Conversation

Share your package ideas with us @elmradiopodcast on Twitter!