Learn the JavaScript ecosystem one package at a time

May 30th, 2016

Modern JavaScript is a land of many moving pieces. When you look at it from a high level: it looks like chaos. A single project might incorporate all of these packages:

es6 webpack autoprefixer axios babel-cli babel-core babel-eslint babel-loader babel-preset-es2015 babel-preset-react bluebird body-parser classnames connect-pg-simple cross-env css-loader deep-equal es6-promise express express-flash express-session extract-text-webpack-plugin file-loader helmet immutable inline-environment-variables-webpack-plugin invariant isomorphic-fetch json-loader kerberos lodash method-override node-libs-browser passport passport-google-oauth passport-local pg pg-hstore postcss-import postcss-loader postcss-mixins postcss-nested postcss-reporter postcss-simple-vars react react-dom react-redux react-router react-router-redux react-transform-hmr redux redux-logger redux-thunk rimraf sequelize sequelize-cli spark-md5 style-loader url-loader warning webpack-dev-middleware webpack-hot-middleware eslint eslint-config-airbnb eslint-plugin-import eslint-plugin-jsx-a11y eslint-plugin-react expect karma karma-jsdom-launcher karma-mocha karma-mocha-reporter karma-sinon karma-sourcemap-loader karma-webpack mocha nock nodemon null-loader react-addons-test-utils react-stateless-wrapper react-transform-catch-errors redux-mock-store sinon

If you start learning with a starter project, you will just be thrown into the chaos. It can be sooo overwhelming.

Imagine for a moment, that you knew absolutely no math. And then someone gave you a starter equation like this:

x3 - 8 = 36√4 / 12 + 13

It's too much at once! Addition, subtraction, multiplication, division, square roots, exponents....

The equation might bring you closer to your goal, but if you don't understand it, you won't be able to modify it. You'll never finish. It brings a false sense of early progress - and then you hit a wall.

There's a better way. You can relax while you learn one small and simple piece at a time. First counting, then arithmetic, then subtraction, and so on.

The learning pieces in modern JavaScript are often npm packages. So let's learn one npm package at a time.

And instead of teaching you one specific packages, I'd rather give you a technique to learn a package on your own. This strategy will work for ANY package - even if it has no documentation or tutorials.

The Technique: Sandboxing

You can quickly understand any npm package with sandboxing. By 'sandboxing', I just mean: creating a directory of files that you use to experiment with a package.

Sandboxing begins with four simple lines of shell script:

mkdir sandbox
cd sandbox
npm init -y       # create an npm project. -y means use defaults
npm install --save <package name>

The above lines create a directory with a package.json file and a node_modules folder.

This newly created directory is an isolated environment where you can test out an npm package and see how it works.

As you add code to the sandbox, you'll gain intuitive, experiental knowledge that you can directly apply when you add the same package to your real project.

This approach is ideal for those who, like me, prefer to learn by doing instead of learning by reading.

To make this approach more concrete, I'll walk you through an example. But first let's get source control set up.

Setup: Where to Save Your Work

Before we get into the first example, I'd like to ask: Do you have a place to save sample projects and code snippets?

I learned the hard way that if I don't save my learning projects, I'll regret it later. I'll forget the information, or want to revisit it or add to it.

Don't make the mistake of not backing up your work. Even your learning work.

I keep all my sandboxes in a single git repository that I call workshop-2016. I recommend making a separate repository for each year because if you use this technique as often as I do, a single repository would become bloated.

Here's how to make your workshop repository if you use git. Just type this into your terminal:

mkdir workshop-2016
cd workshop-2016
echo 'node_modules' > .gitignore
echo 'My Workshop' > README.md
git init
git add .
git commit -m 'initial commit'

Don't forget to push it up to your favorite git host like bitbucket or github.

Example Sandbox: twemoji

Now that you've got a place to keep your code samples, let's go through an example.

I recently found a fun npm package called twemoji that converts emoji strings into images (😺🍾πŸͺ Β  => Β  😺🍾πŸͺ).

In this example we'll learn exactly what twemoji does and how to use it. We won't just learn academically how it works via the docs, we'll get a feel for how it works.

To start, type these steps out into your terminal.

cd workshop-2016            # whichever folder you keep your sandboxes & snippets in
mkdir twemoji-sandbox
cd twemoji-sandbox
npm init -y                 # creates a package.json file with default values
npm install --save twemoji

That's all the project setup. Now you can create a .js file to start experimenting!

Create a file called experiment.js within your new twemoji-sandbox folder. A quick glance at the twemoji docs tells us that they provide a parse() method, so let's type in this text:

var twemoji = require("twemoji");

Run your file with this command:

node experiment.js

You should see this output:

<img class="emoji" alt="😺" src="https://twemoji.maxcdn.com/2/72x72/1f63a.png">

This shows us how twemoji really works: you give it a plain text string, and it returns HTML full if <img> tags.

Homework 1: Experiment on your own

If you've been following along, so far you've copy/pasted or retyped existing commands. To really learn the package, mess around!

βš‘οΈπŸ˜‰πŸͺ THIS IS THE FUN PART! πŸ­πŸŽ‰πŸ‘

What happens if you:

  • ...pass twemoji.parse() multiple emoji at once?
  • ...pass twemoji.parse() a mix of regular text and emoji?

Don't skimp on this step. When you come up with your own experiments and try them out, the information really sticks to your brain.

Homework 2: Add a Readme

Put a README.md file in every sandbox you make so that if you revisit it later you can remember what you were doing and what you learned.

Here's my README.md:

## twemoji sandbox

Tested out twemoji, Twitter's npm package for converting emoji strings into
Twitter emoji.

The `parse()` method takes a string and converts it to HTML, with `<img>` tags
for all the emoji images.

Treasure this forever

Now you have a record of how to use twemoji in your own words.

You are not likely to forget how to use this package, but if you do, you now basically have your own documentation.

Browser Packages

npm packages that run in the browser or work with React will require a little more work to test, but the principle is the same. Instead of starting with an empty directory, start with an extremely simple starter project.

Ideally you'll write your own starter project so you understand all the pieces.

Alternatively, you can use my minimal-react-starter or pick one with my starter project search tool.

Take Action: Create Your Own Sandbox

To really solidify this new skill, go make a sandbox for an npm package that you have been meaning to try, or one of these awesome npm packages:

  • marked: A markdown parser and compiler.
  • webpack: JavaScript bundler.
  • mocha: JavaScript test framework.
  • mobx: Simple, scalable state management.
  • express: Minimalist web framework for node.
  • babel: Compiler for next generation JavaScript.

Once you do this a few times you'll be surprised out how quickly you can learn new packages. You could easily learn 10 in a day!

More Examples

Here are some example sandboxes that I've created for my own work:

twemoji sandbox: The twemoji example covered above.
autoprefixer sandbox: A test I ran to figure out how the browsers config option works in autoprefixer.
yargs sandbox: A test of how boolean arguments work with yargs.


Next time you're stuck trying to understand a project, or you have encountered a bug that seems odd: try this approach. Take one of the packages out into a sandbox and make sure you really understand how it works.

You'll be surprised at how much clearer the big picture gets after looking at a couple pieces in isolation.

There are ~300,000 npm packages out there and new ones added each day. Depending on how you handle it, this can either be incredibly overwhelming or exciting and fun.