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.
- 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
servant-elm (for Haskell servant)
- Keep yourself honest about solving problems by starting with an
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
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
- 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
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!