preppy

Preppy

Preppy - A Simple and lightweight tool for preparing the publish of NPM packages.

To keep things simple and reduce to number of dependencies, Preppy uses your local Babel configuration to transpile your code. You have to make sure that all required Babel mechanics, presets and plugins are installed locally to your project.

Preppy also support extracting TypeScript types into .d.ts files to make them usable by users of your libraries. The generated code is still transpiled by Babel. The standard typescript CLI is used for extracting the types.

Input Files

These are the typical entry points looked up for by Preppy:

• src/index.js
• src/index.jsx
• src/index.ts
• src/index.tsx

We made the experience that this works pretty fine for most projects. If you have the need for more input files, please report back to us.

Output Targets

Preppy produces exports of your sources depending on the entries of your packages package.json. It supports building for ESM, CommonJS and UMD. Just add the relevant entries to the package configuration.

• CommonJS: main
• EcmaScript Modules (ESM): module: New module standard for optimal tree shaking of bundlers.
• Universal Module Definition (UMD): umd + unpkg for delivering a minified bundle to the CDN.

Basic Example:

{
  "name": "mypackage",
  "main": "lib/index.cjs.js",
  "module": "lib/index.esm.js",
  "unpkg": "lib/index.umd.min.js",
}

For exporting types with TypeScript you should add a types entry to your package.json as well:

{
  "name": "mypackage",
  "main": "lib/index.cjs.js",
  "module": "lib/index.esm.js",
  "unpkg": "lib/index.umd.min.js",
  "types": "lib/index.d.ts"
}

Binary Output

Additionally *Preppy is capable in generating for binary targets e.g. CLI tools.

This generates a mypackage binary which is generated from the matching source file.

Binaries are generally generated from one of these source files:

• src/cli.js
• src/binary.js
• src/script.js

Example Configuration:

{
  "name": "mycli",
  "bin": {
    "mycli": "bin/mycli"
  }
}

Installation

$ npm install --save-dev preppy

Configure Babel

As transpiling happens via Babel you have to install the Babel Core, Plugins and Presets on your own. You also need to use a standard Babel Configuration inside your package.

Example babel.config.js (has to be CommonJS unfortunately):

module.exports = (api) => {
  const env = api.env()
  const caller = api.caller((inst) => (inst && inst.name) || "any")

  const isBundler = caller === "rollup-plugin-babel"
  const isCli = caller === "@babel/node"
  const modules = (env === "test" && !isBundler) || isCli ? "commonjs" : false

  return {
    sourceMaps: true,
    plugins: [
      [
        "@babel/transform-runtime"
      ]
    ],
    presets: [
      [
        "@babel/env",
        {
          useBuiltIns: "usage",
          loose: true,
          modules
        }
      ],
      [
        "@babel/typescript",
        {
          allExtensions: true,
          isTSX: true
        }
      ]
    ]
  }
}

Note: Leave out the "@babel/typescript" when you do not need TypeScript transpiling.

Installing Babel Dependencies

$ npm install --save-dev @babel/plugin-transform-runtime @babel/preset-env @babel/preset-typescript @babel/core
$ npm install --save @babel/runtime corejs

Usage

Preppy comes with a binary which can be called from within your scripts section in the package.json file.

"scripts": {
  "prepare": "preppy"
}

There is also some amount of parameters you can use if the auto detection of your library does not work out correctly.

Usage
  $ preppy

Options
  --input-lib        Input file for Library target [default = auto]
  --input-cli        Input file for Binary target [default = auto]
  --output-folder    Configure the output folder [default = auto]

  -m, --sourcemap    Create a source map file during processing
  -v, --verbose      Verbose output mode [default = false]
  -q, --quiet        Quiet output mode [default = false]

License

Apache License; Version 2.0, January 2004

Copyright

Copyright 2016-2018
Sebastian Software GmbH