build-dist

Opinionated build tool for hybrid NPM modules.

Conventions (Input)

Source directory structure:

  package.json
  src/index.js

Optional directories for mock modules:

  webpack/
  webpack/cjs/
  webpack/esm/
  webpack/web/

where:

• cjs/, esm/, web/
  • only resolve for the corresponding build target

Package.json configuration:

  {
    "config": {
      "build-dist": {
        "window": "myApp",
        "export": "my-app"
      }
    }
  }

where:

• config["build-dist"]["window"]
  • is the name of the global variable used by browser builds
• config["build-dist"]["export"]
  • is the filename (without extension) used by all build targets

Conventions (Output)

Dist directory structure:

  dist
  +---es2020
  |   +---cjs
  |   |       my-app.js
  |   |       my-app.map
  |   |       package.json
  |   |
  |   +---esm
  |   |       my-app.js
  |   |       my-app.map
  |   |       package.json
  |   |
  |   \---web
  |           my-app.js
  |           my-app.map
  |
  \---es5
      \---web
              my-app.js
              my-app.map

Package.json injection:

  {
    "exports": {
      ".": {
        "browser": "./dist/es2020/web/my-app.js",
        "import": "./dist/es2020/esm/my-app.js",
        "require": "./dist/es2020/cjs/my-app.js"
      },
      "./es2020": {
        "browser": "./dist/es2020/web/my-app.js",
        "import": "./dist/es2020/esm/my-app.js",
        "require": "./dist/es2020/cjs/my-app.js"
      },
      "./es5": {
        "browser": "./dist/es5/web/my-app.js"
      }
    },
    "files": [
      "dist/"
    ]
  }

Installation

  npm install --global "@warren-bank/build-dist"

Usage

  cd /path/to/project

  build-dist [webpack_config_filepath]

where:

• webpack_config_filepath
  • is optional
  • must extend: @warren-bank/build-dist/webpack
    • hybrid module that supports both commonjs and esm
    • exports a function

for example:

  // webpack.config.js

  const base_config = require('@warren-bank/build-dist/webpack')

  module.exports = function(env, argv) {
    const options = base_config(env, argv)

    if (env.module === 'web') {
      options.externals = {
      }

      options.resolve.fallback = {
      }
    }

    return options
  }

Legal

• copyright: Warren Bank
• license: GPL-2.0