« Previous Tutorial Next Tutorial »

For number four in our Five Minute React series, we’re going to talk about package managers, specifically two of them: NPM and Yarn. NPM comes bundled with Node, so assuming you followed tutorial three or already had Node installed, you’ve got NPM. Yarn is a separate download, which means another Mac/Windows split here, but this one’s much shorter than the previous tutorial, because both versions are basically just “download and install it” – but we’ll get to that.

NPM’s a great package manager and for simple Node apps, it’s more than up to the task of managing your dependencies and keeping your application in line. When you get to building production-ready code, though, Yarn comes in handy for really locking things down and making sure that your app is identical on every possible platform to which you want to deploy it, be they production servers or other engineers’ personal workstations.

But we’re getting ahead of ourselves, because first we should talk a little bit about what package management is. In the Node world (as in many application development platforms), applications are made up of a variety of pieces, including custom JavaScript that you write, various modules that others have written and that you can choose to leverage, and possibly other assets like HTML and CSS files, configuration files, maybe a few adorable kitten gifs, and so forth.

adorable kittens (pictured: adorable kittens)

NPM allows you to install dependencies, bundle up your own packages, and other cool features. Yarn performs many of the same tasks, and—good news!—is compatible with NPM, so you can start there and then move to Yarn, if you want.

We don’t want. Yarn’s really good, and it’s easy to use, so there’s not a lot of reason to start with NPM when building our project. There are some minor differences between the two package managers, but if you learn one, you’re basically learning how the other one works, too, other than syntax. So I’m going to show you how to use Yarn right from the get-go. But first, let’s get it installed.

Installing Yarn on OSX

In our last tutorial, we installed Homebrew, so you’ve already got everything you need to install Yarn. Just open a terminal window and type:

brew update && brew install yarn

and hit enter. That’ll both make sure you have the latest list of Homebrew apps and get yarn installed on your Mac. Like with NVM from the last tutorial, we’ll need to edit our shell configuration file (for example, mine’s .zshrc in my home directory - if you're on a default Mac install, yours is probably .bash_profile) and append the following line to the end:

export PATH="$PATH:`yarn global bin`"

save the file, exit out, and restart your terminal session. Don’t worry if you have other export statements in your configuration file; it appends new directories to the path, rather than overwriting.

That’s it. If you’re on OSX, you can skip to “Using Yarn” below.

Installing Yarn on Windows

This is so straightforward that I’m not going to spend much time on it, since I assume you’ve installed at least one Windows program before in your life. Just go to the install page, click on the Download Installer button, and run the MSI that gets downloaded. That’s it … you’re done! Note that you’ll need to close and re-open any Command Prompts you already had open if you want to use Yarn in them.

Using Yarn

For this step, we’re going to use Yarn to initialize a new package and add a dependency to that package. Then in the next tutorial, we’re going to write some code that uses that dependency, and we’re going run our code with Node.JS to show it working.

First, pick a place to store your new package. I’m going with my home directory/tutorials/ yarntest. You can literally store this anywhere you want. It’s entirely self-contained. Open a terminal window or command prompt, if you haven’t already, and CD to the directory in which you’re going to store this test (if it doesn’t already exist, you’ll have to create it, which I’m doing here).

All good? Type:

yarn init

and press enter. You’ll be asked to name your project. I’m going with “YarnTest” for this one. I know … both original and evocative. You can’t use spaces here, so don’t try, or it’ll just yell at you. For version let’s go with 0.0.1, for description we’ll type “a test yarn package” and for entry point we’ll just hit enter to use the default index.js. We don’t have a repo URL—well, actually, I do (see tutorial info above), but you don’t, so leave it blank—and hit enter. For author, you can put your name, or anything else you’d like … Code Machine or Starlord or Hotpants6969 … whatever you like to call yourself. Spaces are OK, here.

Licensing is outside the scope of this tutorial, but you’re unlikely to be distributing this slightly-more-than-hello-world application to anyone, so I’d just hit enter and accept the default MIT license. This just governs the permissions you’re giving, telling whether people can or cannot modify and distribute your code. Again, you’re not likely to ever be distributing this, so it doesn’t really matter. "Private" adds a private: true flag to your package.json, which keeps NPM from publishing it on their site should you register your application in their database, which you won't be doing. Doesn't really matter what you choose.

That’s it. Assuming you got “success Saved package.json,” you’re good to … if you got something else, that’s problematic. Try running yarn init again.

If you look at what’s in your directory now, you’ll see a file called package.json. This is the central organization structure of your package. Open it up and take a look at it in your text editor of choice, and you’ll see that it contains all of the information we just entered in JSON format.

{
  "name": "YarnTest",
  "version": "0.0.1",
  "description": "index.js",
  "author": "Christopher Buecheler",
  "license": "MIT"
}

We’re going to be adding to this file, but not manually (though you can certainly do that). Instead, we’re going to use Yarn itself to do it.

Back in your terminal window or command prompt, type:

yarn add map-reverse

and hit enter. You’ll see it quickly run through an installation. Congratulations, you’ve just added a 3rd party module to your package. If you check out what’s in your directory now, you’ll see a node_modules folder and a yarn.lock file. Don’t worry about the latter for now, we’ll talk about it when we get much closer to deploying projects. CD to your node_modules directory and list its contents, and you’ll see that, yep, the map-reverse package is in there. Sweet. CD back up to your yarntest directory (or whatever you named it). It’s time to create index.js.

You can do this however you like … right clicking in windows, using touch in the terminal, or just starting in your text editor and saving the file. Sublime lets me just type

subl index.js

and hit enter, which will launch Sublime with a file named index.js opened, though it won’t actually create the file until I hit ctrl-s, which I’m doing now.

If you check out package.json again, you’ll see that it’s added a dependency to your app.

{
  "name": "YarnTest",
  "version": "0.0.1",
  "description": "index.js",
  "author": "Christopher Buecheler",
  "license": "MIT",
  "dependencies": {
    "map-reverse": "^1.0.1"
  }
}

This means when anyone else downloads your app and runs yarn install, they’ll get map-reverse installed into their node_modules folder. This is handy when you have an app that uses several third party modules, and you don’t want people to have to yarn add each of them individually.

We’re ready to write some code. Hop on over to the next tutorial, and let’s get started!

« Previous Tutorial Next Tutorial »


Kitten image copyright: tobkatrina / 123RF Stock Photo