Hex.pm is the main package repository of the Elixir eco system, the same goes for rubygems for the Ruby language.

When you do more than hobby development or want to give back to the eco system, you find yourself publishing a package.

So how to do just that? I’ll describe the steps I took for publishing the hello_elixir package.

The code

I start by creating a new github repository, clone it and create a new elixir project with:

mix new hello-elixir --app hello_elixir

Mix will prompt me if I want to use a directory which already exists.

Hex.pm

Now on to the next part - getting registered on Hex.pm. There’s a nice signup which takes you through the process. Or you can do it through the shell.

mix hex.user register

Next you need to authenticate to hex. This is done by

mix hex.user auth

Adding metadata to the package

Before the package can be published, I need to add some metadata to the mix.exs file.

def project do
[
  ...
  description: description(), # This is added for the description
  package: package(),         # Package info is added here
  source_url: "https://github.com/iamkristian/hello-elixir", # Github
  ...
]
end

# The description used on hex.pm
defp description() do 
~s"""
This is a nice description for the hello elixir project, which sole purpose
is to explore the possibility of publishing a package on hex.pm.
"""
end

# Run "mix help deps" to learn about dependencies.
defp deps do
[
  {:ex_doc, "~> 0.0"} # Hex requires ex_doc because it uses that package to generate documentation.
]
end

# Hex requires package metadata on licenses and links
defp package() do
[
  licenses: ["MIT"],
  links: %{"Github" => "https://github.com/iamkristian/hello-elixir"}
]
end

For the full mix.exs file check out github.

Publish the package

Now for the exiting part - publishing the package. That’s done by

mix hex.publish

The command will prompt you to verify everything is alright and correct. Once I had published the package I realised my first hex username (krx) didn’t really mix into the blend. It needed to be recognisable.

So I created my current username (kristianras), and transfered the package to the new user, I’m really amazed at how well thought the system is.

The transfer was done easily with

mix hex.owner transfer hello_elixir kristianras

Validating the package

Going over the package on hexdocs.pm/hello_elixir I found out the links from the modules to github wasn’t working properly. I deliberately used the master branch and not main.

So the link is wrong. The way to fix that is diving into the ex_doc documentation, and updating the mix.exs file.

  def project do
    [
      ...
      description: description(), # This is added for the description
      package: package(),         # Package info is added here
      deps: deps(),

      source_url: "https://github.com/iamkristian/hello-elixir", # Github
      docs: [
        source_ref: "master"
      ]
      ...
    ]
  end

This will tell ex_doc to use master as the default branch, and since one hour didn’t pass I could use the --replace flag of the mix hex.publish command. I didn’t fancy a version with a broken link. So I retired the broken version.

The version with the broken repository link is retired with

mix hex.retire hello_elixir 0.1.0 invalid --message "Broken documentation"

After a while I found out hexdocs takes a while for changes to come through. So the broken package did get replaced. But as a bonus, I got to play around some more with mix hex.retire.

Hope you enjoyed this little trip into hex.pm land.