2.10

The Elm Platform includes all the tools necessary to work with Elm, but it doesn’t come with every package available in the online catalog. If all those packages were to be included in the platform itself, its download size would be huge. Even then we would still need to download packages from the catalog because new packages are being published frequently.

Installing a Package

Earlier, when we ran the elm init command in the Building a Simple Web Page section, the elm.json file was created inside the beginning-elm directory. If you look inside that file, you’ll see the packages our project depends on.

{
    .
    .
    "dependencies": {
        "direct": {
            "elm/browser": "1.0.1",
            "elm/core": "1.0.2",
            "elm/html": "1.0.0"
        },
        "indirect": {
            "elm/json": "1.1.3",
            "elm/time": "1.0.0",
            "elm/url": "1.0.0",
            "elm/virtual-dom": "1.0.2"
        }
    },
    .
    .
}

Note: Our project uses packages listed in direct. Some of those direct packages depend on other packages which are listed in indirect.

We then ran the elm make command to compile our Elm code to JavaScript.

$ elm make src/HomePage.elm --output elm.js

elm make looks inside the elm.json file and automatically installs all packages listed as dependencies. Once the initial project is setup, we shouldn’t modify elm.json by hand. Instead, we should use the elm install command to download packages from the online catalog.

Let’s install a new package called elm/http to get a feel for how elm install works. Later in the book, we will be making multiple HTTP requests to a server to retrieve data. To do that we will need the elm/http package. Run the following command from the beginning-elm directory in terminal.

$ elm install elm/http

Before downloading the package, elm install politely asks for our permission to add this package as a dependency to elm.json.

Here is my plan:

  Add:
    elm/bytes    1.0.8
    elm/file     1.0.5
    elm/http     2.0.0

Would you like me to update your elm.json accordingly? [Y/n]:

Answer Y and you should see the following message.

Starting downloads...

  ● elm/bytes 1.0.8
  ● elm/file 1.0.5
  ● elm/http 2.0.0

Dependencies ready!

Once the package has been downloaded, elm install saves it in a local cache which is located in your home directory (~/.elm). Whenever we ask elm install to install a package, it first checks to see if that package is already in local cache. If yes, it’ll install from there. If not, it will download the package from online catalog. This speeds up the installation process quite a bit.

Note: A package name is prefixed by the username of the person or organization who publishes the package. All packages we have installed so far are published by elm — official organization for developing Elm’s compiler and core tools.

elm install also adds the elm/http package as a direct dependency to the elm.json file.

{
    .
    .
    "dependencies": {
        "direct": {
            "elm/browser": "1.0.1",
            "elm/core": "1.0.2",
            "elm/html": "1.0.0",
            "elm/http": "2.0.0"
        }
    .
    .
}

By listing all of our dependencies in one place (elm.json), Elm has made it easy for us to share our project with others. All our co-workers need to do is run elm make and the required packages will be installed automatically.

What is a package anyway?

The term package has been used throughout this chapter without being formally introduced. A package in Elm is a collection of modules. A module is a collection of functions and other values. Don’t worry if you don’t know what functions and values are in Elm. We’ll get properly introduced to them in chapter 3.

For now, think of functions as the smallest utilities you can write in Elm. Some of these utilities can be reused in multiple contexts. You can combine these reusable utilities that perform similar tasks into a module. You might even want to combine multiple modules that solve similar problems into a package. You can then share that package with other programmers by publishing it on the online catalog.

A package doesn’t have to have multiple modules in it. For example, as of this writing the elm/random package has only one module called Random. elm install is designed to work with packages. Therefore, putting a module in a package makes it easier to share with others through the online catalog.