Skip to content

This guide and website are in beta! Help us make them awesome with your feedback!

Learn@FujoWeb.Dev

Learn (and Practice) NPM

In our last article, we learned what the NPM package registry and manager are, and why they’re so helpful. Now, it’s time to get our hands dirty, and learn how to use the by jumping in and trying out a few basic commands.

After following this guide, you’ll know how to:

This article will show how you can use NPM to:

  1. Create your own project from scratch, leveraging functionality from existing libraries
  2. Work on an existing project or create one with a starter script, installing the packages that code needs on your own machine

From Scratch

Section titled “From Scratch”

Let’s create an extremely simple NPM project! You’ll start most (if not all) projects this way. At the end, you’ll have created a program that can generate a random rainbow ASCII cat! V(=^･ω･^=)v

Step 1: Initialize Your Project

Section titled “Step 1: Initialize Your Project”

  1. Create a folder for your project.

    Terminal window
    mkdir npm-shenanigans
    cd npm-shenanigans

    Create a folder on your computer for your project. Navigate into it with cd.

  2. Run npm init to initialize your project.

    After running this command, you will be prompted to fill-in some details about your project. NPM will set the text between parentheses () as your default values if a field is left empty.

    Terminal window
    npm init
    This utility will walk you through creating a package.json file.
    It only covers the most common items, and tries to guess sensible defaults.
    See `npm help init` for definitive documentation on these fields
    and exactly what they do.
    Use `npm install <pkg>` afterwards to install a package and
    save it as a dependency in the package.json file.
    Press ^C at any time to quit.
    package name: (npm-shenanigans) █

    Press enter as new prompts show up or type your own answers until you reach a final confirmation for the package.json file we’re about to create. Don’t worry too much about your answers at this stage, you can always edit them later!

  3. Confirm the creation of your package.json file.

    Terminal window
    npm init
    This utility will walk you through creating a package.json file.
    It only covers the most common items, and tries to guess sensible defaults.
    See `npm help init` for definitive documentation on these fields
    and exactly what they do.
    Use `npm install <pkg>` afterwards to install a package and
    save it as a dependency in the package.json file.
    Press ^C at any time to quit.
    package name: (npm-shenanigans)
    version: (1.0.0)
    description: A project to practice our NPM skills!
    entry point: (index.js)
    test command:
    git repository:
    keywords:
    author: boba-tan
    license: (ISC)
    About to write to /Users/boba-tan/npm-shenanigans/package.json:
    {
      "name": "npm-shenanigans",
      "version": "1.0.0",
      "description": "A project to practice our NPM skills!",
      "main": "index.js",
      "scripts": {
        "test": "echo \"Error: no test specified\" && exit 1"
      },
      "author": "boba-tan",
      "license": "ISC"
    }
    Is this OK? (yes) █

    Type yes or press enter to confirm! Now that we’re done with our npm init command, a new file called package.json has been created.

    This command might also create a package-lock.json (which in practice you will never need to look at), and the node_modules/ folder, which stores the downloaded and installed code for this project. Even if these two things aren’t created already, installing a library later will still automatically add these files and folders, so don’t worry if you’re only seeing package.json for now.

    • Directory/
      • DirectoryUsers/
        • Directoryboba-tan/
          • Directorynpm-shenanigans/
            • package.json

  4. Run npm pkg set type=module

    This will turn on modern JavaScript features that NPM doesn’t set up by default. Since many modern libraries rely on these newer features, you might run into errors if you forget this step.

    If you don’t set the type now, NPM will error when it run and tell you to set "type": "module" in the package.json.

    Now, take a look, a new line has been automatically added to your packacge.json.

    package.json
    {
      "name": "npm-shenanigans",
      "version": "1.0.0",
      "description": "A project to practice our NPM skills!",
      "main": "index.js",
      "scripts": {
        "test": "echo \"Error: no test specified\" && exit 1"
      },
      "author": "boba-tan",
      "license": "ISC",
      "type": "module"
    }

  5. (Optional) Ignore the node_modules/ folder when using git.

    If you use, or plan to use, git in your project, add a line for node_modules/ to your .gitignore file to keep your repository clean.

    The node_modules/ folder is filled up using the information in the package.json and package-lock.json files, so you shouldn’t keep track of it in git.

Step 2: Write and Run Your Code

Section titled “Step 2: Write and Run Your Code”

  1. Create a new file called index.js inside your project folder.

    • Directory/
      • DirectoryUsers/
        • Directoryboba-tan/
          • Directorynpm-shenanigans/
            • package.json
            • index.js

    Once you’ve created the file, open it in your text editor and add the following code to your file:

    index.js
    console.log(":3c ~nyaa");

    Save the changes in your index.js file.

  2. Run your code with node.

    In the command line, run node index.js.

    Terminal window
    node index.js
    :3c ~nyaa

  3. Run your code with an npm script.

    Open you project’s package.json file in your text editor. Let’s take the command we used in the previous step and turn it into a script instead.

    In your package.json, look for the line that says "scripts":{}. If you’ve been following closely, there’s probably a “test” script in there already with some messy code - feel free to ignore it. Let’s add a new script called “start” inside the curly brackets with our command from the previous step. Don’t forget to add commas between scripts!

    Your file should now look something like this:

    package.json
    {
      "name": "npm-shenanigans",
      "version": "1.0.0",
      "description": "A project to practice our NPM skills!",
      "main": "index.js",
      "scripts": {
        "test": "echo \"Error: no test specified\" && exit 1"
        "test": "echo \"Error: no test specified\" && exit 1",
        "start": "node index.js"
      },
      "author": "boba-tan",
      "license": "ISC",
      "type": "module",
      "dependencies": {}
    }

    Save the changes to your package.json file and run the start script we just defined.

    Terminal window
    npm run start
    test-project@1.0.0 start
    node index.js
    :3c ~nyaa

    Adding script commands in package.json will make your life much easier: you don’t need to remember the specific file names of every different file you want to run and it actually allows you to run multiple scripts at once as a single program. Script commands tend to have standard names like npm run start or npm run dev so they’re much easier to remember than individual file names.

Step 3: Add Your Libraries

Section titled “Step 3: Add Your Libraries”

For this exercise, we’re going to practice with Cat ASCII faces.

  1. In the command line, run npm install cat-ascii-faces.

    Terminal window
    npm install cat-ascii-faces
    added 8 packages, and audited 9 packages in 5s
    found 0 vulnerabilities

    The npm install [package-name] command adds a new package from npmjs.com to your project. To find the online home of a package you can type the name into the search or create the url yourself by adding /package/ and the package’s name, e.g. npmjs.com/package/cat-ascii-faces.

    If it didn’t happen during the initialization step, then your node_modules/ folder and package-lock.json file should have been created.

    • Directory/
      • DirectoryUsers/
        • Directoryboba-tan/
          • Directorynpm-shenanigans/
            • Directorynode_modules/
              • cat-ascii-faces
              • …
            • package.json
            • package-lock.json
            • index.js

    If you look at your package.json file, you’ll notice your new dependency has been added!

    package.json
    {
      "name": "npm-shenanigans",
      "version": "1.0.0",
      "description": "A project to practice our NPM skills!",
      "main": "index.js",
      "scripts": {
        "test": "echo \"Error: no test specified\" && exit 1",
        "start": "node index.js"
      },
      "author": "boba-tan",
      "license": "ISC",
      "type": "module",
      "dependencies": {
        "cat-ascii-faces": "^2.0.0"
      }
    }

  2. Edit your code to use our new dependency

    In your index.js file, edit your code like this:

    index.js
     import getRandomCatFace from "cat-ascii-faces";
    

     console.log(":3c ~nyaa")
     console.log(getRandomCatFace());

    The first line in the code imports a specific function (getRandomCatFace()) from the cat-ascii-faces npm package.

    In the other line we added, we’re calling the function we imported inside a console.log() to display a random ASCII cat face in our console.

    Save the changes in your index.js file.

  3. Run the start script

    Because of the code we added to index.js in the previous step, using node to run this file will now output a random ASCII cat face to our console.

    Terminal window
    npm run start
    (.=^・ェ・^=)

Packages Managed! …now What?

Section titled “Packages Managed! …now What?”

You’ve successfully used the most important NPM commands and seen how they work in practice: you know how to start a new project, add code packages to it, and run your code using scripts; you also know how to get an existing project up and running by installing its dependencies; and, if you need a refresher on how to do either, you know where to go for answer!

Now, it’s tiem to use what you learned in your own web projects (past and future), or find some NodeJS projects to contribute to.

We suggest to: