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

  • Early elm-graphql commits started with examples before anything else

  • Write meaningful test cases with elm-test

  • elm-verify-examples

  • Have a clear vision

  • Ask people for feedback

  • Let ease of explanation guide you to refine core concepts

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!