Another popular package manager is Yarn, which offers faster and more reliable dependency management while maintaining compatibility with the npm ecosystem.

In this article, we'll explore what npm libraries are, their benefits, and how they enhance the JavaScript and React ecosystem. We'll also go through a practical step-by-step guide on creating, publishing, and using your own npm library in a React project. We’ll also compare npm and Yarn, showing how you can use either of them effectively in your workflow.

By the end of this tutorial, you'll have a clear understanding of how to package and distribute your own code, making it reusable across multiple projects and even available to the wider developer community.

Table of Contents

1. What is npm?

   • How npm works

   • The role of the package.json file

   • Key npm Commands

2. Why Use npm Libraries?

   • Code reuse and modularization

   • Simplified dependency management

   • Community-driven ecosystem

3. Introducing Yarn: An Alternative to npm

   • What is Yarn?

   • Differences between npm and Yarn

   • When to use Yarn instead of npm

4. How to Create Your Own npm Library

   • Setting up a new package

   • Writing modular and reusable code

   • Adding dependencies and peer dependencies

5. How to Publish Your Library to npm

   • Creating an npm account

   • Configuring package.json for Publishing

   • Publishing the package

6. How to Use Your npm Library in a React Project

   • Installing your package

   • Importing and using the package in a React component

   • Handling package updates and versioning

7. Best Practices for npm and Yarn Libraries

   • Write Meaningful Documentation

   • Follow Semantic Versioning (SemVer)

   • Keep Dependencies Up to Date

   • Write Unit Tests for Your Library

   • Ensure Cross-Platform Compatibility

8. Conclusion & Next Steps

   • Recap of key points

   • Additional resources for npm and Yarn library development

   • Encouragement to contribute to open-source

What is npm?

npm (Node Package Manager) is the default package manager for JavaScript and Node.js. It allows developers to install, share, and manage libraries or dependencies that make building applications easier and more efficient.

npm provides access to a vast ecosystem of open-source packages hosted on the npm registry, making it one of the largest software repositories in the world.

npm comes bundled with Node.js, meaning that once you install Node.js, you automatically have access to npm. You can check if npm is installed by running the following command in your terminal:

npm -v

This command should return the version of npm installed on your system.

How npm Works

npm operates through three key components:

1. The npm Registry – A public repository that hosts open-source JavaScript packages.

2. The npm CLI (Command Line Interface) – A tool that allows developers to install, update, and manage packages from the command line.

3. The package.json File – A metadata file that keeps track of dependencies, scripts, and project configurations.

When you install a package using npm, it pulls the package from the registry and saves it in the node_modules folder within your project.

For example, to install Lodash, a popular utility library, you would run:

npm install lodash

This will:

• Download the latest version of lodash from the npm registry

• Add it to your node_modules folder

• Update the package.json and package-lock.json files to reflect the new dependency

The Role of package.json

The package.json file is the heart of any npm project. It serves as a blueprint, containing information about the project, including:

• Project metadata (name, version, description)

• Dependencies (external packages required for the project)

• Scripts (commands to automate tasks like starting a server or running tests)

• Versioning information (ensuring compatibility between different versions of dependencies)

A typical package.json file looks like this:

{
  "name": "my-awesome-project",
  "version": "1.0.0",
  "description": "A sample project demonstrating npm usage",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "test": "echo \"No tests specified\" && exit 0"
  },
  "dependencies": {
    "lodash": "^4.17.21"
  },
  "devDependencies": {
    "eslint": "^8.0.0"
  },
  "author": "Your Name",
  "license": "MIT"
}

• dependencies – Lists essential packages required for the application to function.

• devDependencies – Includes development-only dependencies (for example, testing and linting tools).

• scripts – Defines CLI commands for automating tasks.

To install all dependencies listed in package.json, simply run:

npm install

This ensures all required packages are downloaded and ready for use.

Key npm Commands

Here are some essential npm commands you’ll use frequently:

Why Use npm Libraries?

As modern web development grows in complexity, using npm libraries has become essential for building scalable and maintainable applications. Instead of writing everything from scratch, you can leverage pre-built, tested, and optimized libraries to speed up development and ensure reliability.

In this section, we’ll explore the key advantages of using npm libraries and why they are crucial in JavaScript and React development.

Code Reuse and Modularization

One of the biggest benefits of npm libraries is code reuse. Instead of repeatedly writing the same functions or utilities in different projects, developers can:

• ✅ Use existing open-source packages for common functionalities (for example, date formatting, HTTP requests, UI components).

• ✅ Create and publish their own reusable libraries to share across multiple projects.

For example, instead of manually implementing a function to format dates, you can install a well-maintained package like date-fns:

npm install date-fns

Then, you can use it in your project:

import { format } from "date-fns";

const formattedDate = format(new Date(), "yyyy-MM-dd");
console.log(formattedDate); // Outputs: 2024-02-04 (or the current date)

This modular approach saves time and ensures consistency across projects.

Simplified Dependency Management

npm makes it easy to manage dependencies in a project. Instead of manually downloading and maintaining different versions of external libraries, npm automates this process through the package.json and package-lock.json files.

Some key features include:

🔹 Automatic installation – Run npm install, and all dependencies are set up.
🔹 Version control – Specify package versions to avoid breaking changes.
🔹 Peer dependencies – Ensure compatibility between different libraries.

For example, here’s how npm helps manage dependency versions in package.json:

"dependencies": {
  "react": "^18.0.0",
  "axios": "^1.5.0"
}

• ^18.0.0 – Allows minor updates but prevents major breaking changes.

• axios – Ensures HTTP requests are handled consistently across different projects.

To update all dependencies safely, run:

npm update

This ensures your project is always running on the latest stable versions.

Community-Driven Ecosystem

npm has an active and growing community, meaning developers around the world contribute and maintain thousands of useful libraries. This results in:

🌎 Faster development – No need to reinvent the wheel.
🛠️ Well-tested solutions – Many libraries are battle-tested in production environments.
📚 Rich documentation – Most npm packages come with clear usage instructions and examples.

Popular npm libraries include:

For example, using Axios to make an API request:

import axios from "axios";

axios.get("https://jsonplaceholder.typicode.com/posts/1")
  .then(response => console.log(response.data))
  .catch(error => console.error(error));

This replaces the need for writing complex fetch requests with error handling manually.

Introducing Yarn: An Alternative to npm

While npm is the default package manager for Node.js, another powerful alternative exists: Yarn. Developed by Facebook in 2016, Yarn was created to improve speed, security, and reliability in dependency management.

In this section, we’ll explore what Yarn is, how it differs from npm, and when you might prefer using Yarn over npm.

What is Yarn?

Yarn (Yet Another Resource Negotiator) is a package manager that works similarly to npm but with a focus on performance, security, and consistency. It offers:

🚀 Faster dependency installation thanks to parallel downloads
🔐 More secure package management using checksum verification
📦 Reliable dependency resolution with an offline cache

To check if you have Yarn installed, run:

yarn -v

If you don’t have it yet, you can install it globally using npm:

npm install --global yarn

Once installed, you can use it just like npm to manage dependencies.

Differences Between npm and Yarn

Although npm and Yarn serve the same purpose, they have some key differences:

Performance Comparison

When installing dependencies, Yarn is often faster because it downloads packages in parallel, while npm installs them sequentially.

For example, to install all dependencies in a project:

# With npm
npm install

# With Yarn
yarn install

Yarn can also install packages from a local cache, meaning it doesn't always need to fetch dependencies from the internet.

Common Yarn Commands vs. npm

Many npm commands have an equivalent in Yarn:

For example, installing axios using Yarn:

yarn add axios

When to Use Yarn Instead of npm

Yarn is a great choice when:

• You want faster installations – Yarn installs multiple packages in parallel, making it faster than npm.

• You need better dependency consistency – The yarn.lock file ensures that all developers use the same dependency versions.

• You're working with monorepos – Yarn’s built-in workspaces make it easier to manage multiple projects within the same repository.

• You want improved security – Yarn’s checksum verification prevents corrupted packages from being installed.

Still, npm has improved significantly in recent years, especially with npm v7+, making it a viable choice for most projects.

Switching Between npm and Yarn

If your project was originally set up using npm but you want to switch to Yarn, you can:

1️⃣ Delete node_modules and package-lock.json

rm -rf node_modules package-lock.json

2️⃣ Run Yarn to install dependencies

yarn install

This will generate a yarn.lock file, ensuring all dependencies are managed by Yarn moving forward.

Both npm and Yarn are powerful tools for package management. Choosing between them depends on your project’s needs:

✔️ Use npm if you want the default, widely used package manager that works well with most projects.
✔️ Use Yarn if you need faster installs, better security, and monorepo support.

Ultimately, both tools allow you to install, manage, and publish JavaScript packages efficiently.

How to Create Your Own npm Library

Creating your own npm library is a great way to share reusable code, contribute to the open-source community, or even streamline development across multiple projects. In this section, we’ll walk through the step-by-step process of setting up, coding, and preparing a library for publishing on npm.

Setting Up a New Package

Before writing code, you need to set up an npm package. Follow these steps:

Step 1: Create a New Project Folder

mkdir my-awesome-library
cd my-awesome-library

Step 2: Initialize npm

Run the following command to create a package.json file:

npm init

You will be prompted to enter details such as:

• Package name

• Version

• Description

• Entry point (default: index.js)

• Author

• License

💡 To skip the prompts and create a default package.json, use:

npm init -y

Writing Modular and Reusable Code

Now, let’s create a simple utility library that provides a function to format dates.

Step 3: Create an index.js File

Inside the project folder, create a file named index.js and add the following code:

function formatDate(date) {
  if (!(date instanceof Date)) {
    throw new Error("Invalid date");
  }
  return date.toISOString().split("T")[0];
}

module.exports = { formatDate };

Adding Dependencies and Peer Dependencies

Your library might depend on external packages. For example, let’s use date-fns for better date formatting.

To install it as a dependency, run:

npm install date-fns

Then, modify index.js to use date-fns:

const { format } = require("date-fns");

function formatDate(date) {
  if (!(date instanceof Date)) {
    throw new Error("Invalid date");
  }
  return format(date, "yyyy-MM-dd");
}

module.exports = { formatDate };

If you're creating a React-specific library, you should add React as a peer dependency:

npm install react --save-peer

This ensures users of your library install React separately, preventing version conflicts.

Before publishing, you should test how your package works when installed as a dependency.

Step 4: Link the Package Locally

Run the following command in your package folder:

npm link

Then, in another project where you want to use your package, navigate to that project and run:

npm link my-awesome-library

Now, you can import and use your function:

const { formatDate } = require("my-awesome-library");

console.log(formatDate(new Date())); // Output: 2025-02-04 (or the current date)

Once you're happy with your package, it's time to publish it on npm.

How to Publish Your Library to npm

Now that we’ve created our npm package, the next step is publishing it to the npm registry so others can install and use it. In this section, we’ll cover how to publish the package step by step.

Creating an npm Account

Before publishing, you need an npm account.

Step 1: Sign Up for npm

1. Go to https://www.npmjs.com/signup and create an account.

2. Verify your email address.

Step 2: Log in to npm from the Terminal

Run the following command in your terminal:

npm login

You will be prompted to enter:

• Your npm username

• Your password

• Your email (associated with your npm account)

If the login is successful, you’ll see a message:

Logged in as your-username on https://registry.npmjs.org/

Configuring package.json for Publishing

Step 3: Ensure Your Package Name is Unique

Every npm package needs a unique name. Run the following command to check if your desired name is available:

npm search my-awesome-library

If the name is already taken, you’ll need to modify package.json and change the "name" field.

Step 4: Add Metadata and Keywords

Open package.json and ensure it includes useful metadata:

{
  "name": "my-awesome-library",
  "version": "1.0.0",
  "description": "A simple npm package for formatting dates",
  "main": "index.js",
  "repository": {
    "type": "git",
    "url": "https://github.com/yourusername/my-awesome-library.git"
  },
  "keywords": ["date", "formatter", "utility", "npm package"],
  "author": "Your Name <your-email@example.com>",
  "license": "MIT"
}

🔹 repository – Useful if you plan to host the project on GitHub.
🔹 keywords – Helps people discover your package on npm.
🔹 license – Specifies how others can use your package (for example, MIT, GPL, and so on).

Publishing the Package

Step 5: Publish Your Package to npm

Run the following command inside your project folder:

npm publish

If successful, you’ll see output similar to:

+ my-awesome-library@1.0.0

Your package is now available at:

📌 https://www.npmjs.com/package/my-awesome-library

Step 6: Making Changes and Updating the Package

If you want to release a new version, update the version field in package.json. npm follows Semantic Versioning (SemVer):

• Patch: Bug fixes (1.0.0 → 1.0.1)

• Minor: New features, backward-compatible (1.0.0 → 1.1.0)

• Major: Breaking changes (1.0.0 → 2.0.0)

Instead of manually updating package.json, use:

npm version patch   # 1.0.0 → 1.0.1
npm version minor   # 1.0.0 → 1.1.0
npm version major   # 1.0.0 → 2.0.0

Then, publish the new version:

npm publish

If you accidentally publish a package and need to remove it:

npm unpublish my-awesome-library --force

⚠️ Note: You can only unpublish packages within 72 hours of publishing.

🎯 You’ve successfully published your own npm library! Now, other developers can install it using:

npm install my-awesome-library

By following Semantic Versioning, writing clear documentation, and maintaining your package, you contribute to the open-source ecosystem and make your code reusable.

How to Use Your npm Library in a React Project

Now that we’ve published our npm package, let’s see how to install, import, and use it inside a React project created with Vite. This section will guide you through the process using both npm and Yarn.

Installing Your Package

Step 1: Create a New React Project with Vite (if needed)

If you don’t have an existing React project, create one using Vite:

Using npm

npm create vite@latest my-react-app --template react
cd my-react-app
npm install

Using Yarn

yarn create vite@latest my-react-app --template react
cd my-react-app
yarn install

Once the installation is complete, you can start the development server:

npm run dev

or

yarn dev

Step 2: Install Your npm Package

Now, install the npm library we created earlier (my-awesome-library).

Using npm

npm install my-awesome-library

Using Yarn

yarn add my-awesome-library

Importing and Using the Library in a React Component

Once installed, you can use the library inside a React component.

Open src/App.jsx and modify it as follows:

import React from "react";
import { formatDate } from "my-awesome-library";

function App() {
  const today = new Date();
  return (
    <div>
      <h1>Formatted Date</h1>
      <p>{formatDate(today)}</p>
    </div>
  );
}

export default App;

Now, run your Vite React app:

npm run dev

Or with Yarn:

yarn dev

This will display a formatted date on the webpage, confirming that our library is working!

Handling Package Updates and Versioning

To update your npm package in your project:

Using npm

npm update my-awesome-library

Using Yarn

yarn upgrade my-awesome-library

If you want to check outdated dependencies:

npm outdated

or

yarn outdated

Using a Local Version of Your Package in Development

If you’re still making changes to your npm package and want to test it in your React project before publishing, you can use npm link or yarn link.

Step 1: Link Your Package Locally

Go to your package’s project folder:

cd ~/path-to-my-awesome-library
npm link

or

yarn link

Step 2: Use It in Your React Project

Navigate to your React app and link the package:

cd ~/path-to-my-react-app
npm link my-awesome-library

or

yarn link my-awesome-library

Now, when you import and use my-awesome-library, it will use the local version instead of the published one.

Publishing an Update to Your Package

If you’ve made changes to your package and want to publish a new version:

1️⃣ Update the version number in package.json (use npm version patch for small updates).
2️⃣ Run npm publish to upload the new version.
3️⃣ Run npm update my-awesome-library in your React project to get the latest version.

Final Thoughts on Using npm Libraries in React (Vite Edition)

By now, you should have a fully functional npm package and know how to install, use, and update it in a React project using Vite.

✔️ Vite is faster than Create React App and provides better performance for development.
✔️ npm and Yarn make dependency management easy.
✔️ npm link allows local testing before publishing.
✔️ Keeping dependencies updated ensures stability.

This workflow is essential for developers looking to create, maintain, and distribute reusable React components or JavaScript utilities.

Best Practices for npm and Yarn Libraries

Now that you've created, published, and used your own npm package, it's essential to follow best practices to ensure your package is reliable, maintainable, and easy to use. This section will cover key principles and techniques to make your npm library as professional as possible.

Write Meaningful Documentation

A well-documented library helps other developers understand how to use it effectively.

What to Include in Your Documentation

📌 Installation instructions
📌 Usage examples
📌 API reference (functions, parameters, return values)
📌 Versioning and update history
📌 Contributions guide (if open-source)

For example, a simple README.md file for my-awesome-library:

# my-awesome-library

A simple npm package for formatting dates.

## Installation

### Using npm
```sh
npm install my-awesome-library

Using Yarn

yarn add my-awesome-library

Usage

import { formatDate } from "my-awesome-library";

console.log(formatDate(new Date())); // Outputs: 2025-02-04

Follow Semantic Versioning (SemVer)

Versioning helps maintain compatibility and informs users of changes. npm follows Semantic Versioning (SemVer):

MAJOR.MINOR.PATCH

💡 To bump versions automatically, use:

```sh
npm version patch   # Small bug fix
npm version minor   # New feature added
npm version major   # Breaking changes

Then, publish the new version:

npm publish

👉 Use proper versioning to prevent breaking projects that depend on your library.

Keep Dependencies Up to Date

Regularly updating dependencies improves security, performance, and compatibility.

Check for outdated dependencies:

npm outdated

or

yarn outdated

Update dependencies:

npm update

or

yarn upgrade

Write Unit Tests for Your Library

Testing ensures your package works correctly before publishing updates.

Install a Testing Framework (Jest)

npm install --save-dev jest

Create a Test File (index.test.js)

const { formatDate } = require("./index");

test("formats a date correctly", () => {
  expect(formatDate(new Date("2025-02-04"))).toBe("2025-02-04");
});

test("throws an error if input is not a date", () => {
  expect(() => formatDate("not a date")).toThrow("Invalid date");
});

Run Tests

shCopyEditnpm test

👉 You can use CI/CD (for example, GitHub Actions) to run tests automatically on every push.

Using CI/CD for Automated Publishing

Automate Publishing with GitHub Actions

Create a .github/workflows/publish.yml file:

ymlCopyEditname: Publish to npm
on:
  push:
    branches:
      - main

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
          registry-url: "https://registry.npmjs.org/"
      - run: npm install
      - run: npm test
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

1️⃣ Create an npm token:
Run:

shCopyEditnpm token create

Copy the token and add it to GitHub Secrets (NPM_TOKEN).

2️⃣ Push code to GitHub → Auto-publish on npm!

👉 Automating publishing prevents human errors and ensures quality control.

Ensure Cross-Platform Compatibility

• Use ES modules (import/export) for modern compatibility.

• Include CommonJS (require/module.exports) support for older environments.

• Test with different Node.js versions using CI/CD.

Example package.json for dual compatibility:

jsonCopyEdit"type": "module",
"main": "index.cjs",
"exports": {
  "import": "./index.mjs",
  "require": "./index.cjs"
}

👉 This ensures your package works everywhere (Node.js, React, Next.js, and so on).

Conclusion

Congratulations! 🎉 You’ve successfully learned how to create, publish, and use your own npm package, while also understanding the benefits of both npm and Yarn for package management.

Throughout this guide, we covered:

✔️ What npm is and why it’s important
✔️ How to use npm and Yarn to manage dependencies
✔️ How to create a reusable npm package
✔️ How to publish and update your package on npm
✔️ How to integrate your package into a React project with Vite
✔️ Best practices for writing, testing, and maintaining your library

By following these steps, you've taken an important step toward open-source development and modular programming, making your code reusable for both yourself and the developer community.

This article will show you all you need to get started with package managers like NPM and Yarn.

But why exactly do we need a package manager in our development workflow? Let's find out.

Why Do You Need a Package Manager?

Suppose there were no package managers. In that case, you would have to do the following manually:

• Find all the correct packages for your project
• Verify that the packages don't have any known vulnerabilities
• Download the packages
• Install them at the appropriate location
• Keep track of new updates for all your packages
• Upgrade each package whenever there is a new release
• Remove the packages you no longer need

Manually managing tens or hundreds of packages is a tiresome and time-consuming endeavor.

Therefore, package managers—such as NPM, pNPM, Bower, and Yarn—help automate and eliminate the tedious process of managing all your packages manually.

Keep in mind that a package manager is not the same as a package registry. So, let's find out the main difference.

Package Manager vs. Package Registry – What's the Difference?

A package manager is a tool developers use to automatically find, download, install, configure, upgrade, and uninstall a computer's packages.

NPM (Node Package Manager) and Yarn (Yet Another Resource Negotiator) are two popularly used package managers.

A package registry is a database (storage) for thousands of packages (libraries, plugins, frameworks, or tools).

In other words, a package registry is the place packages get published to and installed from.

NPM registry and GitHub Packages are two popularly used package registries.

So, now that we know what a package manager is and why it is needed, we can discuss how to use the two popular ones—NPM and Yarn.

Note that there are numerous NPM vs. Yarn debates out there – so we will avoid them here because the best package manager is the one that works best for you.

Therefore, this article will show you how NPM and Yarn work rather than tell you which package manager is best. It is then up to you to decide which you prefer.

Alternatively, you can choose to use NPM for a specific project and Yarn for another—depending on which manager you believe is best suited for the job.

So, without any further ado, let's begin by learning how to install the two managers.

How to Install Node Package Manager (NPM)

NPM gets installed automatically while installing Node.

Therefore, to get NPM installed on your system, go to the NodeJS website and get Node's latest LTS or the current version.

How to Install Yarn

It is best to install Yarn through NPM. So, first, install NPM from the Node.js website.

Once you've installed NPM, proceed to install Yarn like so:

npm install -g yarn

How to Check the Installed Node Version

To check the Node.js version installed on your system, run:

node -v

The -v flag in the snippet above is a shorthand for --version.

How to Check the Installed NPM Version

To check the NPM version installed on your system, run:

npm -v

How to Check the Installed Yarn Version

To check the Yarn version installed on your system, run:

yarn -v

How to Upgrade Node Package Manager

Update to the latest NPM version by running:

npm install npm@latest -g

How to Upgrade NodeJS

Suppose you wish to upgrade your Node.js installation. In that case, you have two options:

Option 1: Upgrade via the NodeJS website

One way to upgrade your NodeJS installation is to manually download and install the latest version from the Node.js website.

Option 2: Upgrade via a version management tool

Another way to upgrade your NodeJS installation is to use a version manager such as NVM, n, or nvs.

How to Upgrade Yarn

Update to the latest Yarn version by running:

yarn set version latest

So, now that we have NPM (or Yarn) on our computer, we can start using the installed manager to find, install, configure, and remove our project's packages.

But what exactly is a package? Let's find out.

What Exactly Is a Package?

A package is a directory (or project) that has a package.json file used to record information about it.

Note: You can only publish packages (a project described by a package.json file) to the NPM registry.

How to Install Packages

There are two ways to install a package: locally or globally.

Local package installation

A locally installed package is one that you can use only in the project in which you've installed it.

To install a package locally, do the following:

1. Navigate to the root directory of your project from the command line.
2. Install your package using the NPM or Yarn installation command below (depending on the package manager you've chosen to use for your project).

Note: You must have Node and NPM installed on your system for the NPM (and Yarn) installation commands below to work. You can get both by installing the latest LTS or the current version from the Node.js website.

NPM installation command

npm install package-name --save

Note that the --save command above instructs NPM to save package-name in the package.json file as one of the packages on which the project depends.

Suppose you wish to install an exact version of a package. In such a case, add a @[version-number] after the package's name like so:

npm install package-name@4.14.1 --save

Alternatively, if the package you are installing is for development and testing purposes, use:

npm install package-name --save-dev

The commands above will cause NPM to download three items into your project's root directory: a node_modules folder, a package.json file, and a package-lock.json file. We will discuss these items in detail later on in this article.

Yarn installation command

yarn add package-name

Suppose you wish to install an exact version of a package. In such a case, add a @[version-number] after the package's name like so:

yarn add package-name@4.14.1

Alternatively, if the package you are installing is for development and testing purposes, use:

yarn add package-name --dev

The commands above will cause Yarn to download three items into your project's root directory: a node_modules folder, a package.json file, and a yarn.lock file. We will discuss these items in detail later on in this article.

So, now that we know how to install a package locally, we can discuss the global package installation.

Global package installation

A globally installed package is a package that you can use anywhere on your system.

To install a package globally, run the code below on your terminal:

npm install package-name -g

Alternatively, you can use Yarn like so:

yarn global add package-name

Note that you can run the commands above from any location on your system.

Local vs. global package installation

Generally, it is better to install a package locally. Below are some of the differences between a local and global installation.

Difference 1: Installation location

A locally installed package gets installed in the directory where you executed the npm install package-name (or yarn add package-name) command.

Specifically, you will find a project's locally installed packages in its node_module directory.

In contrast, a globally installed package gets installed in a single location on your system. The exact location depends on your system's configuration.

Difference 2: Package versions

Suppose you installed your package locally. Then, you can use different versions of the same package for multiple app development.

However, you are forced to use the same package version for all your apps when you install globally.

Difference 3: Updates

A local installation allows you to choose the project's packages you wish to upgrade to the latest version. This makes it easier to manage upgrades that break compatibility with other packages.

However, upgrading a globally installed package updates the package for all projects—which can cause maintenance nightmares if the upgrade breaks compatibility with other packages.

Difference 4: Usage recommendation

Global installation is best for packages you intend to use only on your command line—especially when they provide executable commands reusable across projects.

However, local installation is best for packages you intend to use in your program—through the import statement or require() function.

Difference 5: Examples

NPM, React Native CLI, Gatsby CLI, Grunt CLI, and Vue CLI are well-known examples of global packages.

Common examples of local packages are Webpack, Lodash, Jest, and MomentJS.

Note:

• You can do both local and global installation of packages you intend to use both on the command line and in your project. Typical examples of such packages are ExpressJS and CoffeeScript.
• Your package manager does not execute an installed package. NPM (and Yarn) only install packages to the node_modules directory. And if you had specified the --save command, your manager would add details about the package to the package.json file.
• To execute (run) any executable package, you must explicitly do so yourself. We will discuss how in a later section of this article.

But what exactly are the node_modules folder, package.json file, package-lock.json file, and yarn.lock file? Let's find out.

What Is a node_modules Folder?

The node_modules directory is the folder where NPM places all the packages it downloads locally for your project.

What Is a package.json File?

A package.json file is a JSON document that package managers—like NPM and Yarn—use to store information about a specific project.

In other words, a package.json file is a project's metadata file.

Advantages of a package.json File

A package.json file:

• makes it possible to publish your project to the NPM registry
• makes it easy for others to manage and install your package
• helps NPM manage a module's dependencies easily
• makes your package reproducible and shareable with other developers

How to Create a package.json File

Go to your project's root directory and initialize the creation of a package.json file by running:

npm init

Or, if your package manager is Yarn, run:

yarn init

Once you've executed the initialization command above, your package manager will walk you through creating the package.json file by asking a few questions about your project.

If you wish to skip the questionnaire, you can create a default package.json file. Let's see how.

How to Create a Default package.json File

Suppose you prefer to skip the questionnaire prompted by the npm init (or yarn init) command. In such a case, go to your project's root directory and run:

npm init -y

Or, if your package manager is Yarn, run:

yarn init -y

The command above will use default values extracted from the current directory to create your project's package.json file.

Note: The -y flag is a shorthand for --yes.

Once your package manager finishes its initialization process, your project's package.json file will contain an object with a set of properties.

Here's an example:

{
  "name": "codesweetly-project",
  "version": "1.0.0",
  "main": "index.js"
}

You can see that the package.json file above contains the name, version, and main fields. Let's learn more about these properties below.

The package.json's Fields

The package.json's properties make your project usable to package managers and end-users.

Suppose you wish to publish your package to the NPM registry. In that case, your package.json file must have the "name" and "version" fields.

However, if you do not intend to publish your package, in that case, all fields—including the "name" and "version" properties—are optional.

Let's learn more about the commonly used fields in a package.json file.

name

The "name" field is a property used to record a project's name.

The "name" property's value must be:

• a single word
• lowercase lettering
• and less than or equal to 214 characters

Note that you can join words together with hyphens and underscores.

Here's an example:

{
  "name": "code_sweetly-project"
}

version

The "version" field indicates a project's current version number.

The "version" property must be in the form of a major.minor.patch format. It must also follow the semantic versioning guidelines.

Here's an example:

{
  "version": "1.0.0"
}

description

The "description" field is a property containing a brief description of a project's purpose.

NPM recommends having a "description" property to make your package easier to find on the NPM website.

Your description will be one of the things that's shown when people run the npm search command.

Here's an example:

{
  "description": "A brief description about this package (project)"
}

main

The "main" field indicates a project's entry point.

In other words, when someone runs the require() function, Node will resolve the invocation to require(<package.json:main>).

Here's an example:

{
  "main": "./src/index.js"
}

private

The "private" field lets package managers know whether they should publish your project to the NPM registry.

Here's an example:

{
  "private": true
}

If you set your package.json's "private" property to true, package managers will not publish your project.

Therefore, setting the property is an excellent way to prevent accidental publication of your package.

scripts

The "scripts" field defines the script commands you want to run at various times in your project's lifecycle.

Here's an example:

{
  "scripts": {
    "test": "jest",
    "dev": "webpack --mode development",
    "build": "webpack --mode production",
    "predeploy": "npm run build",
    "deploy": "gh-pages -d build" 
  }
}

The "scripts" field above contains five properties whose values are the commands we want our package manager to run whenever we invoke the property's key.

So, for instance, running npm run dev will execute the "webpack --mode development" command.

keywords

The "keywords" field specifies an array of keywords that can help people discover your package.

Here's an example:

{
  "keywords": [
    "drag",
    "drop",
    "drag and drop",
    "dragndrop",
    "draggable" 
  ]
}

The "keywords" property is part of the information shown when people run the npm search command.

author

The "author" field lists a project's author's details.

Here's an example:

{
  "author": "Oluwatobi Sofela <oluwatobiss@codesweetly.com> (https://www.codesweetly.com)"
}

You can also write the snippet above as:

{
  "author": {
    "name": "Oluwatobi Sofela",
    "email": "oluwatobiss@codesweetly.com",
    "url": "https://www.codesweetly.com"
  }
}

Note that the "email" and "url" properties are optional.

dependencies

The "dependencies" field lists all the packages a project depends on in production.

Here's an example:

{
  "dependencies": {
    "first-package": "^1.0.4",
    "second-package": "~2.1.3"
  }
}

So, whenever a user installs your project from the NPM registry, the dependencies property ensures package managers can automatically find and install the packages listed.

Note that you can add a package to the "dependencies" field through either of the following ways:

• Manually add the name and the semantic version of each package your project depends on in production.
• Run the npm install package-name --save-prod command on your terminal. Or yarn add package-name if Yarn is your package manager.

devDependencies

The "devDependencies" field lists all the packages a project does not need in production—but requires for its local development and testing purposes.

Here's an example:

{
  "devDependencies": {
    "first-dev-package": "^5.8.1",
    "second-dev-package": "3.2.2—4.0.0"
  }
}

Note that the packages listed in the "devDependencies" field will be available in the project's development environment but not on its production server.

Suppose a user installs the project through the npm install (or yarn add) command. In such a case, the package manager will find and download all the listed devDependencies to the project's node_modules directory.

Keep in mind that you can add a package to the "devDependencies" field through either of the following ways:

• Manually add the name and the semantic version of each package on which your project depends for its development and testing purposes.
• Run the npm install package-name --save-dev command on your terminal. Or yarn add package-name --dev if Yarn is your package manager.

homepage

The "homepage" field specifies the URL to your project's homepage.

Here's an example:

{
  "homepage": "https://codesweetly.com/package-json-file-explained"
}

So, now that we know what a package.json file is, we can discuss package-lock.json.

What Is a package-lock.json File?

The package-lock.json file is a document NPM uses to record the exact version of all the packages you've installed locally to your project's node_modules directory.

A package-lock.json file makes an app 100% reproducible in the exact way you published it to the NPM registry.

So, suppose a user clones your app and runs the npm install command. In such a case, package-lock.json ensures that the user downloads the exact version of the packages you used to develop the application.

For instance, let's say a user cloned your app containing no package-lock.json file, and a dependency used in the app has a newer version.

Suppose the dependency's version number in the package.json file has a caret sign (for example, ^2.6.2). In that case, NPM will install the latest minor version of the dependency—which might cause the app to produce erroneous results.

However, suppose the user cloned your app containing a package-lock.json file. In that case, NPM will install the exact version of the dependency as recorded in the package-lock.json file—regardless of whether a newer version exists.

Therefore, users will always get your app the precise way you published it to the NPM registry.

In other words, NPM uses the package-lock.json file to lock your package's dependencies to the specific version numbers you used for the project's development.

Note: NPM will update the packages recorded in the package-lock.json file whenever you run the npm update command.

What Is a yarn.lock File?

The yarn.lock file is a document Yarn uses to record the exact version of all the packages you've installed locally to your project's node_modules directory.

The yarn.lock file is comparable to NPM's package-lock.json lockfile.

We earlier mentioned that your package manager does not execute an installed package—you must explicitly do so yourself. Let's discuss how.

How to Run an Executable Package

There are several ways to run an executable package. Below are the standard techniques.

Manually locate and execute the package

One way to run an executable package is to type its local path on your command line like so:

./node_modules/.bin/package-name

Add the package to the package.json's scripts field

An alternate way to execute a package is to first add it to the "scripts" field of your project's package.json file like this:

{
  "name": "your_package",
  "version": "1.0.0",
  "scripts": {
    "desired-name": "name-of-package-to-execute"
  }
}

Afterward, you can run the package like so:

npm run desired-name

Note that the command above is shorthand for npm run-script desired-name.

Alternatively, you can execute the package with Yarn like so:

yarn run desired-name

Here's an example:

{
  "name": "codesweetly-app",
  "version": "1.0.0",
  "scripts": {
    "build": "webpack",
  }
}

The snippet above added webpack to your package.json's "scripts" field. So, we can now execute webpack on the command line like this:

npm run build

Or, if your package manager is Yarn, you can run webpack like this:

yarn run build

Use NPX

A faster way to run an executable package is to use NPX like so:

npx package-name

With NPX, you no longer need to add your package to the "scripts" field of your project's package.json file.

NPX (Node Package Execute) is a Node package runner that automatically finds and executes a specified package.

Here's an example:

npx webpack

The command above will automatically find and execute webpack. So, we do not need to add the "build": "webpack" property to the "scripts" field of our package.json file.

Note: NPX automatically gets installed when you install Node 8.2/NPM 5.2.0 or higher.

You can also run some code using your preferred Node.js version. Let's find out how.

How to Run Code Using Your Preferred Node.js Version

You can use the @ character and the node npm package to specify the Node.js version you wish to use to execute your code.

Here's an example:

npx node@7 index.js

The snippet above tells NPX to run index.js with the latest version of Node from version 7 major.

Using the node@ command is a helpful way to avoid using Node.js version management tools like nvm to switch between Node versions.

Suppose you wish to confirm the Node version NPX will use to run your code. In that case, run:

npx node@7 -v

The snippet above will display the latest Node version from version 7 major that NPX will use to run your code—for example, v7.10.1.

How to Check for Outdated Local Packages

To determine if any of your project's packages are outdated, run:

npm outdated

If the command outputs nothing, it means all your project's packages are up to date.

Otherwise, see this npm-outdated article for a detailed explanation of the command's output.

Alternatively, you can use Yarn like so:

yarn outdated

Note: To check a specific package's outdated status, add the package's name after the outdated keyword—for example, npm outdated lodash.

How to Check for Outdated Global Packages

To confirm which global package is outdated, run:

npm outdated -g --depth=0

How to Check for Locally Installed Packages

Here are three ways to check for locally installed packages:

Locally installed packages and their dependencies

npm list

Or use Yarn like so:

yarn list

Locally installed packages—without their dependencies

npm list --depth=0

Or,

yarn list --depth=0

Check if a specific package got installed locally

npm list package-name

How to Check for Globally Installed Packages

Here are three ways to check for globally installed packages:

Globally installed packages and their dependencies

npm list -g

Or use Yarn like so:

yarn list -g

Globally installed packages—without their dependencies

npm list -g --depth=0

Or,

yarn list -g --depth=0

Check if a specific package got installed globally

npm list -g package-name

How to Update Packages

Here's how to update packages with NPM and Yarn:

How to update a specific package to its latest version

npm update package-name

Or, for projects managed with Yarn, run:

yarn upgrade package-name

How to update all of a project's locally installed packages

npm update

Or,

yarn upgrade

How to update a specific globally installed package

You can update a globally installed package like this:

npm update package-name -g

How to update all your system's globally installed packages

npm update -g

How to Uninstall Packages

Here's how to uninstall packages with NPM and Yarn:

How to uninstall a package from a specific project

First, navigate to the project's root directory from the command line and run:

npm uninstall package-name

Note:

• Add the -S (or --save) flag to remove references to the package in the dependencies field of the project's package.json file.
• Add the -D (or --save-dev) flag to remove references to the package in the devDependencies field of the project's package.json file.

For projects managed with Yarn, run:

yarn remove package-name

Note: The yarn remove command will automatically update the project's package.json and yarn.lock files.

How to uninstall a global package

npm uninstall package-name -g

Note that it is best practice not to remove packages manually from the node_modules folder as such action can affect other modules depending on it.

But what exactly is a module in NodeJS? Let's find out below.

What Exactly Is a Module in NodeJS?

A module in NodeJS is any file in the node_modules folder that the computer can load through Node's require() function.

Here's an example:

const myModule = require("./codesweetly.js");

Suppose the computer successfully used the require() function to load the codesweetly.js file. In such a case, it means codesweetly.js is a module—assigned to the myModule variable.

Keep in mind that a module may also be a package—but not always.

A module is not a package if it does not have a package.json file used to record information about it.

Also, note that for a module to be loadable by the require() function, the module must be one of the following:

• A package—whose package.json file contains a "main" field.
• A JavaScript file.

How to Publish Your Project to the NPM Registry

NPM is a free registry for public package authors.

So, you can use it to publish any project (folder) from your computer that has a package.json file.

Below are the steps required to share your package with the world.

Step 1: Sign in or sign up

Go to the NPM website and sign in (or sign up if you do not yet have an account).

Note: make sure that you verify your email after creating a new account. Otherwise, you will get a 403 Forbidden error while publishing your package.

Step 2: Log in

Login to your NPM account from the command line like so:

npm login

Note: You can use the npm whoami command to check if you are currently logged in.

Step 3: Publish your package!

Go to your project's root directory and publish it like so:

npm publish

Make sure that your package's name does not currently exist on NPM. Otherwise, you will get an error while publishing.

You can use the npm search command (or the NPM website's search bar) to search if the name you wish to use already exists on NPM.

Suppose all the suitable names for your package are already taken. In that case, NPM allows you to publish your project as a scope.

In other words, you can publish your package as a sub-section of your username. Let's see how below.

How to publish your package as a scope of your username

Open your package.json file and prefix your package's name with your username.

Here's an example:

{
  "name": "@username/package-name",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT"
}

NPM's default setting assumes that a scoped name package is a private project. So, you will get an error if you use the npm publish command to share a scoped name package.

Therefore, to publish your package as a scope of your username, add the --access=public flag to the npm publish command:

npm publish --access=public

Note: You can make your project a scoped package during the initialization process by using the npm init --scope=username command instead of npm init.

Overview

This article discussed what a package manager is. We also looked at how two popular package managers (NPM and Yarn) work.

Thanks for reading!

And here's a useful ReactJS resource:

I wrote a book about React!

• It's beginners friendly ✔
• It has live code snippets ✔
• It contains scalable projects ✔
• It has plenty of easy-to-grasp examples ✔

The React Explained Clearly book is all you need to understand ReactJS.

In this short post, I’m going to show you how to prevent the usage of npm or yarn, depending on your needs.

This comes in handy when your team or organization has a preference for a specific package manager.

With this method, you make sure everyone will be using the same package manager.

Let’s get started!

Want to watch a video about how to do this? Check this one out:

Edit .npmrc

You might not have this file in your codebase. If this is the case, create this file in the root folder of your application.

It allows us to specify package manager configurations and it is used by both npm and yarn.

Your .npmrc file should have the engine-strict property marked as true.

//.npmrc file

engine-strict = true

This option tells the package manager to use the version of the engines we have specified in the package.json file.

Edit package.json

Inside your package.json file you should add the engines section if you don’t currently have it.

//package.json
{ 
  ...
  "engines": {
    "npm": "please-use-yarn",
    "yarn": ">= 1.19.1"
  },
  ...
}

In the above code, the package.json file uses a version of yarn 1.19.1 or greater.
But for npm we specify a version that doesn’t exist.

This way we make sure that when someone tries to use npm instead of yarn, they will receive an error that outputs ‘please-use-yarn‘.

Running npm install

Once you’ve done the above changes, try to run npm install.

You will receive an error that prevents you from using npm.

npm ERR! code ENOTSUP
npm ERR! notsup Unsupported engine for my-app@0.1.0: wanted: {"npm":"please-use-yarn","yarn":">= 1.19.1"} (current:
 {"node":"12.16.3","npm":"6.14.4"})
npm ERR! notsup Not compatible with your version of node/npm: my-app@0.1.0
npm ERR! notsup Not compatible with your version of node/npm: my-app@0.1.0
npm ERR! notsup Required: {"npm":"please-use-yarn","yarn":">= 1.19.1"}
npm ERR! notsup Actual:   {"npm":"6.14.4","node":"12.16.3"}

npm ERR! A complete log of this run can be found in:
npm ERR!     C:\Users\YourUser\AppData\Roaming\npm-cache\_logs\2020-05-21T10_21_04_676Z-debug.log

This, of course, can be done the other way around if you want to prevent the usage of yarn.

Conclusion

It is pretty straightforward and easy to ensure that only one package manager must be used inside your project.

This will reduce the chance of errors caused by developers that are using different package managers and it is a good practice to standardize the project’s coding rules and management.

You can reach out and ask me anything on Twitter, Facebook and my website.

• What are hooks?
• Why are custom hooks cool?
• What are we going to make?
• Step 0: Naming your hook
• Step 1: Setting up your project
• Step 2: Writing your new React Hook
• Step 3: Using your React hook in an example
• Step 4: Compiling your React hook and Example
• Step 5: Publishing your React hook to npm
• More resources about hooks

What are hooks?

React hooks in simple terms are functions. When you include them in your component or within another hook, they allow you to make use of React internals and parts of the React lifecycle with native hooks like useState and useEffect.

I don’t plan on doing a deep dive about hooks, but you can check out a quick introduction with an example of useState as well as the intro from the React team.

Why are custom hooks cool?

The great thing about creating custom hooks is they allow you to abstract logic for your components making it easier to reuse across multiple components in your app.

Hook diagram example for useCounter

For instance, if you wanted to create a simple counter where you use React’s state to manage the current count. Instead of having the same useState hook in each component file, you can create that logic once in a useCounter hook, making it easier to maintain, extend, and squash bugs if they come up.

What are we going to make?

For the purposes of this article, we’re going to keep it simple with a basic hook. Typically, you might use a hook because rather than a typical function, you use other native hooks that are required to be used within React function components. We’re going to stick with some basic input and output to keep things simple.

We’re going to recreate this custom Placecage hook I made, that allows you to easily generate image URLs that you can use as placeholder images.

Nic Cage excited

If you’re not familiar, Placecage is an API that allows you to generate pictures of Nic Cage as placeholder images for your website. Silly? Yes. Fun? Absolutely!

But if you’re not a fan of Nic's work, you can just as easily swap in the URL for Fill Murray which uses pictures of Bill Murray or placeholder.com which generates simple solid color background with text that shows the size of the image.

Step 0: Naming your hook

Before we jump in to our actual code, our ultimate goal is to publish this hook. If that’s not your goal, you can skip this step, but for publishing, we’ll want to create a name for our hook.

In our case, our hook name will be usePlaceCage. Now with that in mind, we have 2 formats of our name — one in camelCase format and one in snake-case format.

• camelCase: usePlaceCage
• snake-case: use-placecage

The camelCase format will be used for the actual hook function, where the snake-case name will be used for the package name and some of the folders. When creating the name, keep in mind that the package name must be unique. If a package with the same name exists on npmjs.com already, you won't be able to use it.

If you don’t already have a name, it's okay! You can just use your own name or something you can think of, it doesn’t really matter too much as really we're just trying to learn how to do this. If it were me for instance, I would use:

• camelCase: useColbysCoolHook
• snake-case: use-colbyscoolhook

But just to clarify, for the rest of our example, we’re going to stick with usePlaceCage and use-placecage.

Step 1: Setting up your project

Though you can set up your project however you’d like, we’re going to walk through building a new hook from this template I created.

The hope here, is that we can take out some of the painful bits of the process and immediately get productive with our custom hook. Don’t worry though, I’ll explain what’s going on along the way.

The requirements here are git and yarn as it helps provide tools that make it easy to scaffold this template, such as using the workspaces feature to allow easy npm scripts to manage the code from the root of the project. If either of those are a dealbreaker, you can try downloading the repo via the download link and update it as needed.

Cloning the hook template from git

To start, let’s clone the repository from Github. In the command below, you should replace use-my-custom-hook with the name of your hook, such as use-cookies or use-mooncake.

git clone https://github.com/colbyfayock/use-custom-hook use-my-custom-hook
cd use-my-custom-hook

Once you clone and navigate to that folder, you should now see 2 directories – an example directory and a use-custom-hook directory.

Cloning use-custom-hook

This will give you a few things to get started:

• A hook directory that will include the source for our hook
• Build scripts that compile our hook with babel
• An example page that imports our hook and creates a simple demo page with next.js

Running the hook setup scripts

After we successfully clone the repo, we want to run the setup scripts which install dependencies and update the hook to the name we want.

yarn install && yarn setup

Setting up a new hook from the use-custom-hook template

When the setup script runs, it will do a few things:

• It will ask you for your name – this is used to update the LICENSE and the package's author name
• It will ask you for your hook's name in 2 variations – camelCase and snake-case - this will be used to update the name of the hook throughout the template and move files with that name to the correct location
• It will reset git – it will first remove the local .git folder, which contains the history from my template and reinitialize git with a fresh commit to start your new history in
• Finally, it will remove the setup script directory and remove the package dependencies that were only being used by those scripts

Starting the development server

Once the setup scripts finish running, you'll want to run:

yarn develop

This runs a watch process on the hook source, building the hook locally each time a source file is changed, and running the example app server, where you can test the hook and make changes to the example pages.

Starting up the use-custom-hook development server

With this all ready, we can get started!

Follow along with the commit!

Step 2: Writing your new React Hook

At this point, you should now have a new custom hook where you can make it do whatever you'd like. But since we're going to walk through rebuilding the usePlaceCage hook, let's start there.

The usePlaceCage hook does 1 simple thing from a high level view – it takes in a configuration object and returns a number of image URLs that you can then use for your app.

Just as a reminder, any time I mention usePlaceCage or use-placecage, you should use the hook name that you set up before.

A little bit about placecage.com

Placecage.com is a placeholder image service that does 1 thing. It takes a URL with a simple configuration and returns an image... of Nic Cage.

placecage.com

From the simplest use, the service uses a URL pattern as follows:

https://www.placecage.com/200/300

This would return an image with a width of 200 and height of 300.

Optionally, you can pass an additional URL parameter that defines the type of image:

https://www.placecage.com/gif/200/300

In this particular instance, our type is gif, so we'll receive a gif.

The different types available to use are:

• Nothing: calm
• g: gray
• c: crazy
• gif: gif

We'll use this to define how we set up configuration for our hook.

Defining our core generator function

To get started, we're going to copy over a function at the bottom of our use-placecage/src/usePlaceCage.js file, which allows us to generate an image URL, as well as a few constant definitions that we'll use in that function.

First, let's copy over our constants to the top of our usePlaceCage.js file:

const PLACECAGE_HOST = 'https://www.placecage.com/';
const TYPES = {
  calm: null,
  gray: 'g',
  crazy: 'c',
  gif: 'gif'
};
const DEFAULT_TYPE = 'calm';
const ERROR_BASE = 'Failed to place Nick';

Here we:

• Define a host, which is the base URL of our image service.
• Define the available types, which we'll use in the configuration API. We set calm to null, because it's the default value which you get by not including it at all
• Our default type will be calm
• And we set an error base which is a consistent message when throwing an error

Then for our function, let's copy this at the bottom of our usePlaceCage.js file:

function generateCage(settings) {
  const { type = DEFAULT_TYPE, width = 200, height = 200, count = 1 } = settings;
  const config = [];

  if ( type !== DEFAULT_TYPE && TYPES[type] ) {
    config.push(TYPES[type]);
  }

  config.push(width, height);

  if ( isNaN(count) ) {
    throw new Error(`${ERROR_BASE}: Invalid count ${count}`);
  }

  return [...new Array(count)].map(() => `${PLACECAGE_HOST}${config.join('/')}`);
}

Walking through this code:

• We define a generateCage function which we'll use to generate our image URL
• We take in a settings object as an argument, which defines the configuration of our image URL. We'll be using the same parameters as we saw in our placecage.com URL
• We destructure those settings to make them available for us to use
• We have a few defaults here just to make it easier. Our default type will be defined by DEFAULT_TYPE along with a default width, height, and number of results we want to return
• We create a config array. We'll use this to append all of the different configuration objects in our URL and finally join them together with a / essentially making a URL
• Before we push our config to that array, we check if it's a valid argument, by using the TYPES object to check against it. If it's valid, we push it to our config array
• We then push our width and height
• We do some type checking, if we don't have a valid number as the count, we throw an error, otherwise we'll get incorrect results
• Finally, we return a new array with the number of results requested, mapped to a URL creator, which uses PLACECAGE_HOST as our defined base URL, and with our config array joined by /

And if we were to test this function, it would look like this:

const cage = generateCage({
  type: 'gif',
  width: 500,
  height: 500,
  count: 2
});

console.log(cage); // ['https://www.placecage.com/gif/500/500', 'https://www.placecage.com/gif/500/500']

Using our function in the hook

So now that we have our generator function, let's actually use it in our hook!

Inside of the usePlaceCage function in the use-placecage/src/usePlaceCage.js file, we can add:

export default function usePlaceCage (settings = {}) {
  return generateCage(settings);
}

What this does it uses our generator function, takes in the settings that were passed into the hook, and returns that value from the hook.

Similar to our previous use example, if we were to use our hook, it would look like this:

const cage = usePlaceCage({
  type: 'gif',
  width: 500,
  height: 500,
  count: 2
});

console.log(cage); // ['https://www.placecage.com/gif/500/500', 'https://www.placecage.com/gif/500/500']

At this point, it does the same thing!

So now we have our hook, it serves as a function to generate image URLs for the placecage.com service. How can we actually use it?

Follow along with the commit!

Step 3: Using your React hook in an example

The good news about our template, is it already includes an example app that we can update to easily make use of our hook to both test and provide documentation for those who want to use it.

Setting up the hook

To get started, let's open up our example/pages/index.js file. Inside of this file you'll see the following:

const hookSettings = {
  message: 'Hello, custom hook!'
}

const { message } = usePlaceCage(hookSettings);

This snippet is what was used by default in the template just for a proof of concept, so let's update that. We're going to use the same exact configuration as we did in Step 2:

const hookSettings = {
  type: 'gif',
  width: 500,
  height: 500,
  count: 2
}

const cage = usePlaceCage(hookSettings);

Again, we set up our settings object with the configuration for our hook and invoke our hook and set the value to the cage constant.

If we now console log that value our to our dev tools, we can see it working!

console.log('cage', cage);

Using console.log to show the cage value

Note: If you get an error here about message, you can comment that our or remove it under the Examples section.

Updating the example with our new hook configuration

If you scroll down to the Examples section, you'll notice that we have the same default hookSettings as above, so let's update that again to make sure our example is accurate.

{`const hookSettings = {
  type: 'gif',
  width: 500,
  height: 500,
  count: 2
}

const cage = usePlaceCage(hookSettings);`}

You'll also notice that we're no longer using the message variable. If you didn't remove it in the last step, we can now replace it under the Output heading with:

<p>
  { JSON.stringify(cage) }
</p>
<p>
  { cage.map((img, i) => <img key={`img-${i}`} width={200} src={img} />)}
</p>

We're doing 2 things here:

• Instead of showing the variable itself, we wrap it with JSON.stringify so that we can show the contents of the array
• We also use the map function to loop over our image URLs in the cage constant and create a new image element for each. This let's us preview the output instead of just seeing the values

And once you save and open your browser, you should now see your updated examples and output!

Custom hook example page

Other things you can do on that page

Before moving on, you can also update a few other things that will be important for your hooks page:

• Update the How to use section with instructions
• Add additional examples to make it easier for people to know what to do

A few things are also automatically pulled in from the use-placecage/package.json file. You can either update them there to make it easier to maintain or you can replace them in the example page:

• name: Is used at the <h1> of the page
• description: Is used at the description under the <h1>
• repository.url: Used to include a link to the repository
• author: The name and url are used to include a link at the bottom of the page

Follow along with the commit!

Step 4: Compiling your React hook and Example

The way we can make our hook work easily as an npm module is to compile it for others to use. We're using babel to do this.

Though the publish process already does this for us automatically with the prepublishOnly script in use-placecage/package.json, we can manually compile our hook using the yarn build command from the root of the project.

Along with compiling the hook, running yarn build will also compile the example page, allowing you to upload it wherever you'd like. After running that command, you should see an output of static HTML files in the example/out directory.

If you're looking for a recommendation, Netlify makes it easy to connect your Github account and deploy the static site.

Deployment setup in Netlify

See the demo site deployed to Netlify!

Step 5: Publishing your React hook to npm

Finally, if you're happy with your hook, it's time to publish!

npm makes this part really easy. The only prerequisite you need to have an npm account. With that account, let's log in:

npm login

Which will prompt you for your login credentials.

Next, let's navigate to our hook's directory, as our package configuration is there under use-placecage/package.json:

cd use-placecage

Then, we can simply publish!

npm publish

Keep in mind, that each package name needs to be unique. If you used use-placecage, it's already taken... by me. ?

But if you're successful, npm should build your hook and upload it to the package registry!

Publishing an npm package

It will then be available on npm with the following pattern:

https://www.npmjs.com/package/[package-name]

So for use-placeage, it's available here: https://www.npmjs.com/package/use-placecage

We now have a custom hook!

Yay ? if you followed along, you should now have created a custom hook and published it to npm.

Though this was a silly example using placecage.com, it gives us a good idea of how we can easily set this up.

You'll also notice that this specific example wasn't the best use case for a hooks, where we could have simply used a function. Typically, we'll want to use custom hooks to wrap functionality that can only live inside a React component, such as useState. To learn more about that, you can read one of my other articles about custom hooks.

However, this gave us a good basis to talk through the creation and configuration of our new hook!

More resources about hooks

• How to destructure the fundamentals of React Hooks (freecodecamp.org)
• Introducing Hooks (reactjs.org)
• Hooks API Reference (reactjs.org)

Reduce your install time up to 70%. Ask me how! ?

Anyone who knows me can confirm that I’m a long-standing lover of JavaScript and its entire ecosystem. As a Front-end engineer, Node-based package managers have been a crucial part of my toolset since 2013.

First, I used Bower, which was primarily focused on the front-end world. Then, in 2015, I sadly (ok, not really) realized that Bower was dying and NPM, the default package manager for Node, was the way to go for the front-end too. It was strange for me, at first, to use NPM for other things than Node modules, but I got used to the idea and migrated seamlessly.

Finally, just one year later, Facebook gave us Yarn, a modern and blazing fast alternative to NPM. I loved it at first sight! But some things were still problematic…

Inherited problems in Yarn

Besides the speed, Yarn brought a number of advantages when compared to the NPM version at the time, such as lock files, offline mode, network resilience, checksums and others. Nevertheless, Yarn borrowed some known problems from NPM:

node_modules here, there, everywhere

For each project on your machine that uses NPM or Yarn, a node_modules folder is created. It doesn't matter if 10 projects use the exact same version of a given module, it will be copied over and over into each node_modules folder of these projects.

Generating a new node_modules folder takes a really long time

Even taking a great leap forward in terms of installation speed, Yarn was constrained by node_modules limitations. Just creating the node_modules folder takes up to 70% of the time needed to run yarn install (with a warm cache). It's a huge amount of files to be created on every installation. So, don't blame it on Yarn.

Dependencies not added to package.json

Here’s a scenario for you: Your app works perfectly in development, but crashes in production. After hours of investigation, you finally realize that you forgot to add a dependency to your package.json. Yes, it can happen.

Slow module resolution at runtime

The boot time of your app is heavily impacted by the way Node resolves dependencies. It wastes time querying the file system to discover where a given dependency will be resolved from.

Yarn Plug’n’Play to the rescue!

All of the above problems were addressed by the Yarn team with the release of the Plug’n’Play feature last September.

When you enable PnP, instead of copying every needed file from the cache to the node_modules folder, here's what Yarn does:

1. It creates a single file with static resolution tables. These tables will contain a bunch of important info, such as: packages available in the dependency tree, how they relate between themselves and their location on the disk.
2. A special resolver is used in order to help Node discovering where each dependency has been installed (under the Yarn cache folder). It solely relies on the resolution tables which were created previously. As these tables contain information about the entire dependency tree, the node_modules resolution process won’t need to make a lot of stat and readdir calls at runtime anymore, significantly reducing your app boot time. And as Yarn knows all of your dependencies, it will complain if you try to import a module that's not present in your package.json:

Using Yarn Plug’n’Play

Converting a project to make use of PnP is easy as 1–2–3. You just need to add a installConfig section to your package.json, with a pnp key set to true, like this one:

{    "installConfig": {     "pnp": true   }}

Note: You need Yarn v1.12+ in order to use Plug’n’Play.

After that, just run yarn install and everything inside your node_modules folder will be deleted. From now on, every dependency will be resolved directly from Yarn's hot cache.

_“yarn install” clears your nodemodules folder when PnP is enable

Using PnP in a new React project with create-react-app

If you use create-react-app 2+, the good news is that it works great with Yarn Plug’n’Play! Just append the --use-pnp option to the create-react-app command and you're good to go:

npx create-react-app your-app-name --use-pnp

Possible issues

As nothing is perfect in the world, PnP may incur new issues when used in projects relying on a custom install logic. If you need more info about these potential new issues, you can find a detailed explanation in this paper.

Conclusion

Plug’n’Play solves some really annoying problems in Yarn. Besides, it dramatically improves dependency caching on CIs, saving installation time and allowing our builds to get right to the point: running the tests!

And that’s it! Have fun with Yarn PnP.