Skip to main content

Creating an NPM library

Few notes on this and best-practices:

  • Never commit dist / lib files to GitHub repo in addition to the src (source) code. Its just not needed and is a clunky way to manage the codebase. Github is used to manage and version source code, not store our files
  • Your libraries should never include source code (src file) when you npm install it.
  • You should use webpack or rollup t

Entry point​

This gives the entry-point and tells npm to look at this file when the package is required or imported. You should have all your exports in this one file.

  "main": "lib/index.js",

Scripts​

  • prepare script is the script that will be run when you npm install in another repo. This MUST include the build script.
  • clean, used to delete the dist directories before building
  • build:commonjs
  • build:umd
  • build:umd:min
  • build
 "scripts": {
    "clean": "rimraf lib dist",
    "test": "mocha test.js",
    "build:commonjs": "babel src --out-dir lib",
    "build:umd": "cross-env FILE_NAME=spongepoop webpack",
    "build:umd:min": "cross-env NODE_ENV=production npm run build:umd",
    "build": "npm run clean && npm run build:commonjs && npm run build:umd && npm run build:umd:min",
    "prepare": "npm run build"
  },

Files​

When your package is installed in another project or app, files will list all of the files that should be included in the node_module directory of your package. Here, only dist should be included.

  "files": [
    "dist"
  ],

.gitignore​

To prevent your source code repository on GitHub from including your build, add it to the .gitignore file.

# .gitignore
...


dist/

Transpile the code​

Inside the package directory, install the following dependencies:

npm i -D @babel/core @babel/cli @babel/preset-env
  • @babel/core Contains the core functionality of Babel.
  • @babel/cli Allows using Babel from the terminal.
  • @babel/preset-env A preset that includes all plugins to support modern JS.

You can configure Babel in many different ways, one of them is using a .babelrc file.

Create the .babelrc file in the root of the package and modify its content to match the following:

{
  "presets": [
    "@babel/preset-env"
  ]
}

Next, create a script to transpile the code to normal ES5 syntax using Babel CLI. Add a build script to package.json file:

{
  ...
  "scripts": {
    ...
   "build:commonjs": "babel src --out-dir lib",
    ...
  },
  ...
}

Running this script npm run build:commonjs will create a lib directory with the transpiled code inside. Commonjs is the standard module specification that Node.js uses.

Publish to npm​

Login to npm on your local to be able to publish to their servers.

npm login

Do a dry-run to see if everything is good and your tarball size (package size)

npm dryrun

Build if you need to:

npm run build

Then publish your public package

npm publish --access public

Do you want your library to run on front-end as well?

If so, you will need to create a Universal Module Definition (UMD) version.

Create a UMD version​

This means bundling all your code and all of its dependencies into a single file. You can achieve this using Webpack.

Add the following development dependencies to your package:

npm i -D webpack webpack-cli cross-env

Cross-env is a package that allows setting environment variables properly across different platforms.

Create the configuration file webpack.config.js for Webpack in the root of the package. Contents of webpack.config.js should be:

const path = require('path');
const { NODE_ENV, FILE_NAME } = process.env;
const filename = `${FILE_NAME}${NODE_ENV === 'production' ? '.min' : ''}.js`;
module.exports = {
  mode: NODE_ENV || 'development',
  entry: [
    './src/index.js',
  ],
  output: {
    path: path.join(__dirname, 'dist'),
    filename,
    libraryTarget: 'umd',
  },
};

Running commands npm run build:umd and npm run build:umd:min inside the package directory will create a new folder named dist that contains two files: lt-utils.js and lt-utils.min.js, respectively.

Resources:

Publishing to Chaine

1. Create a NPM Account using your Chaine email​

2. Send your username or NPM email to Param, Anurag or Annalise​

3. Pull the repo package you want to publish​

Pull the repo package you are working on. When you want to publish, you have to login with your npm login in that repo's directory.

4. Login on your local​

When you want to publish, you have to login with your npm login in that repo's directory.

Once you are added to the organization, login on your local:

npm login

5. Follow the workflow for the repo​

That's it. The repo's documentation should have instructions on remaining steps.

See an example here for Keychaine