How to publish an Elm package guide
Intro
This guide is focused on the mechanics on how to publish a new Elm package at https://package.elm-lang.org/, for more in-depth details please check the Real Life section.
Step 1 - Preparation
For publishing a new Elm package we need to ensure we have an elm.json
file configuration similar to this:
{
"type": "package",
"name": "TheBestDeveloper/my-first-elm-package",
"summary": "A sample Elm package reference",
"license": "BSD-3-Clause",
"version": "1.0.0",
"exposed-modules": [
"MyMath.FourierCalc",
"MyMath.FrontierCalc"
],
"elm-version": "0.19.0 <= v < 0.20.0",
"dependencies": {
"elm/core": "1.0.0 <= v < 2.0.0",
"elm/html": "1.0.0 <= v < 2.0.0"
},
"test-dependencies": {}
}
The type
of the project should be package
since normal application
projects are not allows as libraries at https://package.elm-lang.org/.
The field name
contains the full Elm package name including the owner separated by an slash /
, the owner should be a valid GitHub account you own.
Decide which license to use and add its code to the field license
and its content to the file LICENSE
including the fullname of the project owners.
The recommended license to use is BSD3, but of course you can use any license you want, a non-exhaustive list of possible licenses to use can be found at https://opensource.org/license.
For the initial version use 1.0.0
and the next versions will be calculated automatically by the system based and how deep are the evolution of the changes of your package along time.
Add a good summary
using less than 80 characters.
Ensure the Elm version and dependencies version is under a valid range your packge library supports, here we are using Elm 0.19.x
and elm/core
and elm/html
as a reference.
Then decide which modules you want to expose as part of the public API of your new package with entries at exposed-modules
, you do not need to make all your modules public, try to expose as little as possible.
Include a README.md
file at the root of your project with good documentation and useful examples.
Finally, you should document all of the publicly exposed modules and functions, here a guide about the documentation format to use -> http://package.elm-lang.org/help/documentation-format.
Step 2 - Clean, Compile and Test
With the new package configuration and README.md
file in place then clean and compile your project from scratch ensuring the tests run successfully.
Step 3 - Publish the first version
Ensure all your code, documentation and configuration files are commited at GitHub and then tag it with the first version 1.0.0
using the commands:
git tag -a 1.0.0 -m "Initial release"
git push --tags
Now using this new tag, let's publish your new Elm package with the command:
elm publish
And that's it !! ... if you have all the requisites fullfiled, your new package will be published at https://package.elm-lang.org/.
If a requisite is not met of you found an error please double check the prepartion and compilation step and tune your package and try again.
Publish new versions
Once you have your first version published, a long the time you may require to add new features or fix possible bugs, for that just create new commits with the changes and then checking all the requisites as before, run the command:
elm bump
This will check your code and decide the new version following the rules of semantic versioning which normally creates a patch version on small changes and minor or even mayor version for more involved changes, but once again, all of this is calculated automatically and saved at your elm.json
file.
If you want to inspect what are the changes and try to keep the versioning more fine grained run the command
elm-package diff
for getting more information about the new version automatic calculation process
With a new version calulated automatically, just clean, compile and test your project as before and then create a new tag at your repo using the new version with a command like:
git tag -a 1.0.1 -m "Adding a new feature"
git push --tags
Replace
1.0.1
with your previously automatic calculated version and give a more using tag comment
Then publish your new updated version with the command:
elm publish
Real life
Creating good packages requires more than just these mechanical steps, please visit Dillon Kearns in-depth publish tips at the Idiomatic Elm Package Guide
Some tips about new packages design can also be found at https://package.elm-lang.org/help/design-guidelines by Evan Czaplicki.
The original guide can be found at the history commits of the old
elm-package
repo found at https://github.com/elm-lang/elm-package created by Evan Czaplicki