Wheelhouse-packager NPM

Packager

Packager is Wheelhouse's solution for creating a simple way to pre-publish all of your packages, libraries, and projects before they end up on GitHub or NPM.

Installation

NPM

$ npm install -D wheelhouse-packager

Yarn

$ yarn add -D wheelhouse-packager

Usage

Packager is shipped with a binary which can be called from the 'scripts' section of your 'package.json' file.

"scripts": {
    "prepare": "packager"
}

There are also some CLI parameters you can pass directly if the auto-detection of your library does not work out the way that we had intended.

Usage
  $ packager

Options
  --entry-node       Entry file for Node target [ default = auto ]
  --entry-web        Entry file for browser target [ default = auto ]
  --entry-binary     Entry file for binary target [ default = auto ]

  --output-folder    Configure the output destination [ default = auto ]

  -t, --transpiler   Chose which transpiler to use. "babel" or "buble" [ default = babel ]
  -x, --minified     Enables the minification of the output
  -m, --sourcemap,   Creates a sourcemap during build
  --target-unstable  Binaries should target the upcoming version of NodeJS instead of LTS

  -v, --verbose
  -q, --quiet
## Transpilers

*Packager* includes two different transpiler configurations for your projects:

- **[Buble](https://buble.surge.sh/guide/)**: An insanely fast ES2015+ transpiler which gives up a large plugin ecosystem in favor of having a lightweight, optimized runtime.
- **[Babel](https://babel.js.io/docs/plugins/preset-latest/)**: The de-facto standard when it comes to Javascript transpiling. The configuration currently provides support for almost all of modern Javascript dependending on your environment. If you do not specify any configuration, it will try to auto-determine what features you need based on your environment and only include the features you need by checking the features availability. It also contains support for a lot of proposed features such as [Object-Rest-Spread](https://babeljs.io/docs/plugins/transform-object-rest-spread/) and [Class-Properties](https://babeljs.io/docs/plugins/transform-class-properties/), as well as support for generators and async/await powered by [fast-async](https://github.com/MatAtBread/fast-async).

> Note: The Babel configuration uses [Transform-Runtime](https://github.com/babel/babel/tree/master/packages/babel-plugin-transform-runtime) to externalize requirements to Polyfills. This means that the resulting code needs all Polyfills for each library published with this tool. This would typically be done with a service such as [polyfill.io](https://qa.polyfill.io/v2/docs/) or [Babel-Runtime](https://github.com/babel/babel/tree/master/packages/babel-runtime).

## Output Targets

*Packager* produces several different exports of your source depending on the entries found in your packages 'package.json'. It supports building for targets that support *CommonJS* as well as ES Modules (ESM). Just add the relevant entries to the configuration.

- CommonJS Output: 'main'
- ES Module Output: 'module'

A Basic Example:

```json
{
    "name": "my-cool-package",
    "main": "lib/main-cjs.js",
    "module": "lib/main-esm.js"
}

You can also choose to separate your build and create one for both NodeJS and browsers using one of the following keys for the browser bundle: 'browser' or 'web'. These bundles are always exported as ES Modules (ESM) as we can assume that they are going to be bundled with another tool such as Rollup or Webpack before usage.

Example:

{
    "name": "my-cool-package",
    "main": "lib/main-cjs.js",
    "module": "lib/main-esm.js",
    "browser": "lib/main-browser.js"
}

Entries

You might be wondering how to produce a browser bundle from a completely different input? Well, this is actually pretty easy if you follow some conventions within your package.

The files are looked up in a list of possible entries with the first match being used.

Entries for NodeJS Targets

src/index.js
src/server.js
src/exports.js
src/main.js
lib/index.js
lib/server.js
lib/main.js
lib/exports.js
server/index.js
server/exports.js
server/main.js
server/server.js

Sources for Browser Targets

public/index.js
public/main.js
public/app.js
public/exports.js
client/index.js
client/main.js
client/app.js
client/exports.js
src/client/index.js
src/client/main.js
src/client/app.js
src/client/exports.js

Targeting Modern Sources

You are able to export modules for standard ES6 complant environments or for more modern platforms as well.

Note: To use these 'non-standard' bundle outputs might require you to make some tweaks to the bundling phase of your application if it will be going through a second build process (e.g. with Webpack). This is because we are using non-standardized configuration keys in the package.json. This shouldn't cause too many problems as we are only appending either: ':es2015' or ':modern', but it should be known.

While 'es2015' is an exact requirement full the client to have full ES2015 support (excluding natively supported features), 'modern' is more layers on top of this adding in ES2017, async/await, etc. This is a frequently changing and updated target.

An Example Configuration:

{
    "name": "my-cool-package",
    "main": "lib/main-cjs.js",
    "module": "lib/main-esm.js",
    "browser": "lib/main-browser.js",
    "main:es2015": "lib/main-esm-es2015.js",
    "module:es2015": "lib/main-esm-es2015.js",
    "browser:es2015": "lib/main-browser-es2015.js"
}

This can be a bit overwhelming. To make sense of all of these new modules it might be helpful to produce two different groups of autoputs. One for classic browsers, another for modern browsers, and then use feature detection to serve up the script that best suites the environment. This feature is beyond the scope of the library, but the client detection required is very basic.

Binary Output

Additionally, Packager is capable of generating outputs for binary targets as well.

Binaries are generally generated from one of the following source files:

src/binary.js
src/script.js

Example Configuration:

{
    "name": "my-cool-package",
    "bin": {
        "my-cool-package": "bin/my-cool-package"
    }
}

Using NodeJS v8 for Binaries

You can also explicitly target Node8 when generating binaries by passing the --target-unstable command line options together with the "bin" entry seen above