elm radio Tune in to the tools and techniques in the Elm ecosystem. 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
(for Haskell servant)
Keep yourself honest about solving problems by starting with an
Early started with examples before anything else
Write meaningful test cases with
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
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
Dillon's will publish package versions when you increment the version in your
elm-publish-action GitHub Action
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!