NPM Cheat Sheet.md

NPM Cheat Sheet

Table of Contents

• Modules
• Scripts

Modules

Defaults

⚠️ ECMAScript modules is still experimental but enabled by default in Node.js 12.

Node.js treats as ES modules:

• Files ending in .mjs
• Files ending in .js if package.json's type field is set to module

Node.js treats as CommonJS modules:

• Files ending in .cjs
• Files ending in .js if package.json's type field is set to commonjs or is missing (current default, always specify type for future-proofing)

TypeScript

Code in TypeScript and transpile to a package supporting both ES & CJS using Rollup.

NPM Package

Support both ES & CJS in package.json:

{
  "type": "commonjs",
  "files": [
    "dist"
  ],
  "types": "./dist/index.d.ts",
  "main": "./dist/index.js",
  "module": "./dist/index.mjs",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.js",
      "default": "./dist/index.mjs"
    }
  }
}

Package properties:

• .js files are treated as CommonJS modules with the type field set to commonjs
• .mjs files are treated as ECMAScript modules (Node.js 12+ require no runtime flag)
• dist folder is distributed on install with the files field set to [ "dist" ] (other files are distributed by default: package.json, README, LICENSE...)
• ./dist/index.d.ts is used by IDEs for autocompletion via the types field
• ./dist/index.js is the entry point for the package run in Node.js 11- via the main field
• exports overrides main and defines multiple conditional entry points for the package run in Node.js 12+
  • ./dist/index.mjs is the entry point for the package run in Node.js 12+ and loaded using an import statement via the import conditional field
  • ./dist/index.js is the entry point for the package run in Node.js 12+ and loaded using a require statement via the require conditional field
  • ./dist/index.js is the fallback entry point for the package run in Node.js 12+ via the default conditional field

Rollup configuration

Support ES & CJS transpilation in rollup.config.js:

import pkg from "./package.json";
import typescript from "rollup-plugin-typescript2";

export default [
  {
    input: "./src/index.ts",
    output: [
      {
        file: pkg.main,
        format: "cjs",
        exports: "named",
        sourcemap: true
      },
      {
        file: pkg.module,
        format: "esm",
        exports: "named"
      }
    ],
    plugins: [
      typescript({
        tsconfigOverride: {
          compilerOptions: {
            declaration: true,
            module: "ES2015",
            strict: true,
            target: "ES2015"
          }
        },
        typescript: require("typescript")
      })
    ]
  }
]

Transpile package:

rollup --config rollup.config.js

Scripts

# List scripts in package.json
npm run
# Run a script
npm run <scriptname>