@americanexpress/one-app-bundler

@americanexpress/one-app-bundler

A command line interface(CLI) tool for bundling One App and One App modules.

🤹‍ Usage

To bundle a One App module

To build a React component for usage as a One App module:

Install:

npm i -D @americanexpress/one-app-bundler

Run the bundle-module script as part of your build. This script is provided by one-app-bundler:

{
  "scripts": {
    "build": "bundle-module",
    "prepare": "npm run build"
  }
}

When bundling a One App module, some options can be applied by adding a bundler config object to a one-amex section within package.json:

{
 "one-amex": {
   "bundler": {
   }
 }
}

providedExternals & requiredExternals

In order to avoid duplicate code in your One App instance, you may want to share a dependency across all your modules that is not already provided by One App. These dependencies can be provided to your modules by your root module. The root module should include in its configuration providedExternals, which is an array of external dependencies to be bundled with it and provided to other modules.

First make sure to add your dependency to your module's package.json:

npm install some-dependency

Then configure one-app-bundler to provide that dependency (and any others) as an external to your other modules:

{
  "one-amex": {
    "bundler": {
      "providedExternals": ["some-dependency", "another-dependency"]
    }
  }
}

Modules consuming these external dependencies must declare what they expect the root module to provide by setting the requiredExternals option. Any dependency listed there will not be bundled with the module, but will be replaced with a reference to the external dependency as provided by the root module.

Before doing so make sure to add said dependency to your package.json:

npm install some-dependency

{
  "one-amex": {
    "bundler": {
      "requiredExternals": ["some-dependency"]
    }
  }
}

Modules shouldn't configure both providedExternals and requiredExternals.

Any module with requiredExternals configured will be validate at runtime to ensure that the root module is in fact providing those requiredExternals, and will fail to load if it is not.

If you attempt to include in providedExternals or requiredExternals and dependencies already provided by One App, your build will fail.

performanceBudget

Set a custom performance budget for your client module build. The default value is 200e3.

{
  "one-amex": {
    "bundler": {
      "performanceBudget": 500e3
    }
  }
}

webpackConfigPath, webpackClientConfigPath, & webpackServerConfigPath

You may extend the webpack configuration by providing paths to custom webpack config files in this option. Use of this option is at your own risk.

There are two options when customizing your webpack build.

1. Add webpackConfigPath to apply a custom config to both your client and server builds.

{
  "one-amex": {
    "bundler": {
      "webpackConfigPath": "webpack.config.js"
    }
  }
}

1. Add webpackClientConfigPath and/or webpackServerConfigPath to apply different configs to your client and server builds. You don't need to add both of these options. You can pass only one if you wish to customize a single build target.

{
  "one-amex": {
    "bundler": {
      "webpackClientConfigPath": "webpack.client.config.js",
      "webpackServerConfigPath": "webpack.server.config.js"
    }
  }
}

purgecss Options

You may add additional paths for purgecss to consider before stripping out unused CSS by adding an array of glob patterns to bundler.purgecss.paths under bundler.purgecss.paths. The example below illustrates how we would add some-lib if we were applying custom styles to it in our module.

{
  "one-amex": {
    "bundler": {
      "purgecss": {
        "paths": ["node_modules/some-lib/src/**/*.{js,jsx}"]
      }
    }
  }
}

Additional purgecss options. Please refer to the purgecss Options Documentation before enabling any of the following:

{
  "one-amex": {
    "bundler": {
      "purgecss": {
        "paths": ["node_modules/some-lib/src/**/*.{js,jsx}"],
        "extractors": [{
          "extractor": "purgeJs",
          "extensions": [
            "js"
          ]
        }],
        "fontFace": false,
        "keyframes": false,
        "variables": false,
        "whitelist": [
          "random",
          "yep",
          "button"
        ],
        "whitelistPatterns": ["red"],
        "whitelistPatternsChildren": ["blue"]
      }
    }
  }
}

purgecss can be disabled for your module by adding bundler.purgecss.disabled as true. This option is only to be used in rare instances and as a last resort, the effect of disabling will have a negative impact on performance.

{
  "one-amex": {
    "bundler": {
      "purgecss": {
        "disabled": true
      }
    }
  }
}

Other Available Scripts

The following scripts are provided by one-app-bundler and used by one-app.

npm run build:bundle

This would bundle one app.

npm run serve-module ../path-to-your-one-app-module

This would serve your module locally.

npm run drop-module ../path-to-your-one-app-module

This would stop serving your module locally.

Changelog

6.6.0 (2020-05-22)

Bug Fixes

• css-loader: upgraded to latest css-loader api as of 3.4.2 (74cad69)
• externals: resolver did not recognize complex browser fields (#66) (d35d03c)
• generator: remove deprecated holocron api (#65) (8d8564a)
• one-app-cli: drop-module command now works (#35) (99a5da1)
• one-app-runner: fix runner not reading package.json correctly (766a99e)
• url-loader: add missing dep of url-loader (5f4a70b)
• webpack: hash collisions between chunks broke dynamic imports (#30) (2cb92d2)

Features

• babel-loader: cache transpilation (#69) (64e0599)
• bundler: custom client and server webpack configs (#22) (c5a3e82)
• deps: add create-shared-react-context (#59) (16de0a4)
• deps: update generator deps for react-intl and parrot-generator (ac24226)
• generator: csp report-uri to ONE_CLIENT_CSP_REPORTING_URL (#50) (9ae5dc9)
• generator: update base-module template (#25) (1a0af74)
• one-app: removed instances of tenancy or tenant (#36) (9c834f1)
• one-app-bundler: use cross-fetch instead of isomorphic-fetch (#49) (e5232cb)
• one-app-runner: add (#34) (f3c6755)
• purgecss: additional options for purgecss (#61) (37f6817)
• runner: configuration for browser tests (#67) (4ae5eab)
• runner: require modules if moduleMapUrl is missing (#48) (992af08)

Reverts

• Revert "chore(release): bump to v6.5.0 (#62)" (5f708de), closes #62