Create an npm Package

Creating an npm package is not just about publishing source code to the npm registry. It's way more than that and can become very tricky, but this article will explain the basics of the process.

The npm Registry

When we start learning development with JavaScript, we rapidly learn about using external libraries, also called dependencies. We install them using npm install command.

They are extremely powerful because they allow us to use and reuse code written by other developers or in multiple projects. Nobody wants to reinvent the wheel, right?

So the npm registry is a place, like a store, where developers can publish their packages and share them with everyone. Some other developers can then install these packages in their projects to use them.

Today's Problems

CJS and ESM

At the beginning of JavaScript, there was no standard module system. In other words, there was no way to split your code into multiple files. In 2009, Node.js was introduced, and with it comes the possibility to use JavaScript on the server side. Because of that, the need to split code into multiple files becomes more and more important, and some people start working on a standard named CommonJS, also known as CJS.

const app = require('packageName')

The problem with CommonJS is that it's not part of the language itself and suffers from some limitations. In 2015, the ECMAScript 6 specification was released, introducing a new module system called ECMAScript Modules (also known as ESM).

import app from 'packageName'

This new standard enables named exports, better static analysis, tree-shaking, browser native support, and because it's part of the language, it's the future of JavaScript.

The nice part is that ESM supports CJS imports, but the opposite is not true. This means that if we want to publish a package, for compatibility reasons, we must publish it in both formats.

This is made possible by the package.json file and the exports field that allows us to specify the entry point for both formats.

{
  "name": "packageName",
  "exports": {
    ".": {
      "import": "./esm/index.js", // ESM
      "require": "./cjs/index.js" // CJS
    }
  }
}

Types

Even if the project we do is not written with TypeScript, having types for code completion and parameter info is very useful. In order to have this, packages must be published with special files called type definitions.

TypeScript

Developers also use tools like TypeScript to write their source code for convenience. This must be transpiled to JavaScript before publishing the package to the npm registry to allow every developer to use it. We'll see in another article how to do that.

Unbuild

That's a lot of things to think about when we want to create a package for npm. The good news is that UnJS have a tool for us called unbuild.

Unbuild is a unified JavaScript build system that will simplify the process and avoid thinking about all these problems.

The nice part about unbuild is that it does not need to write a complex configuration file. It infers the configuration from the package.json file.

To get started, create a new project:

mkdir create-a-npm-package
cd create-a-npm-package
npm init -y

Then install unbuild:

npm install -D unbuild

Our code source will live in a src directory. That's a convention from unbuild. Create a src/index.js file with the following content:

export function app() {
  return 'Hello, World!'
}

Then, add a build script in the package.json file:

{
  "scripts": {
    "build": "unbuild"
  }
}

We are nearly ready to build our package. We just need to add many fields in the package.json file to explain to the runtime how to use our package.

{
  "name": "create-a-npm-package",
  "type": "module",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    }
  },
  "main": "./dist/index.cjs",
  "types": "./dist/index.d.ts",
  "files": ["dist"]
}

Some explanations about these fields:

• type is used to specify that we are using ESM.
• exports is used to specify the entry point for both formats.
• main is used to specify the default entry point. We use the CJS format since it's the most compatible.
• types is used to specify the type definitions file that is used by editors to provide code completion and parameter info.
• files is used to specify the files that will be included when the package is published.

Finally, run the build script:

npm run build

Take a quick look at the terminal. We can see Automatically detected entries: src/index [esm] [cjs] [dts] which means that unbuild has detected the entry points and the type definitions file.

We can open the dist directory and see that unbuild has created 5 files including 3 that we need: index.mjs, index.cjs, and index.d.ts.

Perfect! You can play with the inference by editing the package.json file. Try to remove the types field and run the build script again. You will see that unbuild will not create the type definitions file.

Finally

During this article, we first learn about the actual problems when we want to create an npm package. This gives us a first answer to why we need to use a bundler like unbuild to create a package for the npm registry.

We then see how to create an npm package with the help of a powerful tool called unbuild. This was quite simple and manual. We only scratched the surface of what unbuild can do and how UnJS can help create a package.

In future articles, we will see how to add a playground to play with the package locally, how to publish the package on npm, how to create a package with TypeScript and how to automate the process with unjs/changelogen.