I recently decided to publish an NPM module. I wrote it in TypeScript and went with Rollup for bundling. It was my first time publishing a module and my first experience with Rollup, so I’d like to write a tutorial on how to do it, both as a reference for myself and for anyone who may find this useful. Let’s get started!

Why TypeScript and Rollup

I went with TypeScript for several reasons. It’s what I use at work, so I’m not only familiar with it, but it’s always good to hone my skills, especially since I’m not necessarily a TypeScript expert (yet). I’m also a fan of types for a number of reasons, and compile-time errors are invaluable. I also believe all JS libraries should be authored in TypeScript.

As for Rollup, I mostly went with it because I had never used it and have heard good things about it. Not only that, but I know that a number of open-source projects use it over Webpack. I also read this great post about the differences between the two and why Rollup is better for building libraries.

Prerequisites

I’m going to be using yarn, but you can use npm if you wish!

First, let’s create our package.json inside the project directory. Fill out everything as you wish, or just hit Enter at every step if you don’t care yet. You can always edit these later.

$ yarn init

First, let’s install TypeScript and Rollup inside the project directory, as well as a plugin to allow Rollup to compile TypeScript as part of its bundling process.

$ yarn --dev add typescript rollup rollup-plugin-typescript2

Note: The original rollup-plugin-typescript appears to be unmaintained, which is why we’re using this one instead.

At this point, your package.json should look something like this:

{"name": "some-project","version": "1.0.0","main": "index.js","author": "John Doe <jdoe@example.com>","license": "MIT","devDependencies": {"rollup": "^0.62.0","rollup-plugin-typescript2": "^0.15.1","typescript": "^2.9.2"}}

Let’s add a few extra lines to the file and replace the default for main:

{"name": "some-project","version": "1.0.0",

"main": "dist/index.js","module": "dist/index.es.js","files": ["dist"],"types": "dist/index.d.ts","scripts": {"build": "rollup -c","watch": "rollup -cw"},

"author": "John Doe <jdoe@example.com>","license": "MIT","devDependencies": {"rollup": "^0.62.0","rollup-plugin-typescript2": "^0.15.1","typescript": "^2.9.2"}}

Here’s what’s going on:

Now we’re ready for some configuration!

TypeScript configuration

In order to configure TypeScript, we need to create a tsconfig.json file. There are more options than we can go over, but the following ones will be good enough for now. I encourage you to dive deeper into the options if you find yourself unsatisfied with how something is working!

Copy the following into tsconfig.json in the root directory of your project.

{"compilerOptions": {"declaration": true,"declarationDir": "./dist","module": "es6","noImplicitAny": true,"outDir": "./dist","target": "es5"},"include": ["src/**/*"],"exclude": ["node_modules"]}

What’s going on:

Rollup configuration

Next, we’ll configure Rollup.

In the root directory of your project, create a file called rollup.config.js. Next, copy this into there:

import typescript from 'rollup-plugin-typescript2'

import pkg from './package.json'

export default {input: 'src/index.ts',output: [{file: pkg.main,format: 'cjs',},{file: pkg.module,format: 'es',},],external: [...Object.keys(pkg.dependencies || {}),...Object.keys(pkg.peerDependencies || {}),],

plugins: [typescript({typescript: require('typescript'),}),],}

The first thing to note is that we’re importing package.json. This isn’t necessary, but it’s a handy way to make sure you aren’t duplicating certain information, such as the filename of your bundle. Here’s a breakdown of what’s going on:

Publishing to NPM

In order to publish the module, we first need to log into NPM. If you don’t have an account, go create one now. You’ll only need to do this once on your machine. For some reason, yarn login didn’t work for me, so I’m going to use npm login for this:

$ npm login

Username: yourusernamePassword:Email: (this IS public) [email protected]Logged in as yourusername on https://registry.npmjs.org/.

Next, let’s create a tiny module to publish. Create a src directory, and inside there, an index.ts file:

// src/index.ts

export const greet = () => console.log('Hello, world!')

After that, run the build command to compile the TypeScript:

$ yarn run build

yarn run v1.3.2$ rollup -c

src/index.ts → dist/index.js, dist/index.es.js...created dist/index.js, dist/index.es.js in 522ms✨ Done in 0.91s.

You’ll notice a dist folder was created with three files in it. Feel free to check those out!

Finally, we can publish the module to NPM:

$ yarn publish

yarn publish v1.3.2[1/4] Bumping version...info Current version: 0.0.1question New version:[2/4] Logging in...[3/4] Publishing...success Published.[4/4] Revoking token...info Not revoking login token, specified via config file.✨ Done in 1.85s.

And that’s it! You’ve successfully published a module to NPM using TypeScript and Rollup.

To verify that everything looks good, create another directory somewhere else on your computer and run yarn init, then yarn add your-package-name. If you navigate to node_modules/your-package-name, you should see the dist folder with all the compiled files in there! You can then import your module like so:

import { greet } from 'your-package-name'

Developing locally

As you can imagine, it would be pretty annoying and hacky to publish your package every time you wanted to test it out. While writing automated tests helps a lot in this regard, sometimes you’ll need to actually use your module to make sure that it works properly before publishing it.

For this, we can use yarn link (or npm link, of course).

First, navigate to your module’s project directory and run the following:

$ yarn link

Next, navigate to the project where you’d like to consume this module. Make sure that the module is not installed via yarn or npm, then run:

$ yarn link your-package-name

This will create a symbolic link to your package folder inside your project’s node_modules directory. Essentially, you’ll be able to use the local version of your package the same way you’d be able to use it if you had it published and downloaded/installed via yarn add or npm install!

Thanks for reading

If you’ve made it this far, congratulations on publishing something to NPM! I hope you enjoyed this tutorial. If I made any mistakes or if anything needs clarification, please don’t hesitate to reach out. I’d like to contribute more to NPM going forward, so I’ll try to keep this tutorial as up-to-date as I can.