How to publish a library to NPM with Rollup & TypeScript

TypeScript continues to be a big player in the JavaScript scene. With over 5 million weekly downloads, the backing of Microsoft and the increasing adoption by many developers (e.g. Angular, Vue.js), TypeScript has become a popular choice for web & node developers. NPM is the central registry for publishing JavaScript libraries to be used both internally (paid version) and externally (free version).

TypeScript can be used to create high quality libraries which can be used in plain JavaScript as well as in TypeScript projects. To create a library, we need a module bundler which will generate our production-ready and deliverable library code. Rollup is a popular module bundler which will be used in this tutorial.

A real-life example can be found in this GitHub project.

Create & publish a library on NPM

1. Create a project using npm init if you do have one yet. NPM needs the Node.js runtime so you need to install Node.js first if necessary.
2. Install the necessary dev-dependencies: we need Rollup, TypeScript and two helpful Rollup plugins. Run the command: npm install rollup rollup-plugin-terser rollup-plugin-typescript2 typescript --only=dev.
3. Create a rollup.config.js file which will be picked up by Rollup when we want to build the library. The file should be at the root of your project like your package.json file.
4. Write your library code.
5. In package.json, create a script to build the library:"build": "rollup -c && tsc". Hence, to build the library, we need to call npm run build. Our bundle should at least contain a ES module and a TypeScript definition file.
6. (Optional) Create unit tests and/or end-to-end tests to verify your library code is working fine. These tests can be executed automatically (e.g. using GitLab or Travis CI) to ensure we do not introduce new bugs after making changes. This step is optional but highly recommended.
7. Publish the library on NPM with the following CLI command: npm publish. If you want to test whether your package would work fine without publishing, you can use npm pack to build your library.

Example rollup.config.js file:

import typescript from 'rollup-plugin-typescript2';
import pkg from './package.json';
import {terser} from "rollup-plugin-terser";
export default {
 input: 'src/index.ts', // our source file
 output: [
  {
   file: pkg.main,
   format: 'cjs'
  },
  {
   file: pkg.module,
   format: 'es' // the preferred format
  },
  {
   file: pkg.browser,
   format: 'iife',
   name: 'MyPackage' // the global which can be used in a browser
  }
 ],
 external: [
  ...Object.keys(pkg.dependencies || {})
 ],
 plugins: [
  typescript({
   typescript: require('typescript'),
  }),
  terser() // minifies generated bundles
 ]
};

A few tips for publishing

• Make sure beforehand that your package name is unique to avoid renaming it later.
• If you do not need TypeScript, you can omit the TypeScript related steps to generate a pure JavaScript library. Personally, I think TypeScript is a great help in modern web development projects, though.
• For unit tests, Jest is a good choice as it is fast and does not need a browser to run. For end-to-end tests, TestCafe is a solid choice since it is fast, reliable and working in CI.
• rollup-plugin-terser is a plugin which minifies the generated bundles. While minification will not affect bundle size when you have only a few exported functions, minification will drastically reduce bundle size the larger your library becomes.
• TypeScript can generate definition files (*.d.ts) automatically by specifying declaration: "true" in the tsconfig.json file. Now, whenever we build our library, we have up-to-date typings of our library.
• Ideally, we want our library to contain only the required files (the generated bundles, the README.md etc.). NPM respects a .gitignore file which most projects use. If you want to be more restrictive, you can either create a .npmignore file or you can specify what you want to include in your package.json.
• To make your package compatible with most browsers, you can also create a browser-compatible version using an IIFE (like in the example file) since not every web browser supports ES modules yet.

Conclusion

Thanks for reading this article about how to create and publish a library on NPM with TypeScript and Rollup. As you can see, creating and publishing a simple library is a matter of minutes thanks to the ease of use of NPM and great tools like Rollup. Have any other tips how to publish a JavaScript library? Let me know in the comments.