📦⚡️ npm package building, reimagined. https://www.pikapkg.com/blog/introducing-pika-pack/
Branch: master
Clone or download
Latest commit 554d843 Feb 15, 2019

README.md

Logo

@pika/pack • npm package building, reimagined.

Demo

@pika/pack helps you build amazing packages without the hassle:

  • Simple  ⚡️  Use pre-configured plugins to build your package for you.
  • Flexible  🏋️‍♀️  Choose plugins and optimizations to match your needs.
  • Holistic  ⚛️  Let us build the entire package... including package.json.

Quickstart

Getting started is easy:

// 1. Install it!
$ npm install -g @pika/pack
// 2. Add this to your package.json manifest:
"@pika/pack": {
  "pipeline": []
}
// 3. Run it!
$ pack build

😎 🆒

So now what? If you run pack build with an empty pipeline, you'll get an empty package build. @pika/pack lets you connect pre-configured plugins to build and optimize your package for you. Plugins wrap already-popular tools like Babel and Rollup with npm-optimized config options, removing the need to fiddle with much (if any) configuration yourself. You even get a generated package.json manifest configured for you automatically.

1. Create a project pipeline out of simple, pluggable builders.

// Before: Your top-level package.json manifest:
{
  "name": "simple-package",
  "version": "1.0.0",
  "@pika/pack": {
    "pipeline": [
      ["@pika/plugin-standard-pkg", {"exclude": ["__tests__/*"]}],
      ["@pika/plugin-build-node"],
      ["@pika/plugin-build-web"],
      ["@pika/plugin-build-types"]
    ]
  }
}

Builders are simple, single-purpose build plugins defined in your package.json. For example, @pika/plugin-build-node & @pika/plugin-build-web build your package for those different environments. Other, more interesting builders can bundle your web build for unpkg, generate TypeScript definitions from your JavaScript, addon a standard CLI wrapper for Node.js builds, and even compile non-JS languages to WASM (with JS bindings added).

2. Builders handle everything, including package configuration.

// After: your built "pkg/" package.json manifest:
{
  "name": "simple-package",
  "version": "1.0.0",
  // Multiple distributions, built & configured automatically:
  "esnext": "dist-src/index.js",
  "main": "dist-node/index.js",
  "module": "dist-web/index.js",
  "types": "dist-types/index.d.ts",
  // With sensible package defaults:
  "sideEffects": false,
  "files": ["dist-*/", "assets/", "bin/"]
}

This is all possible because @pika/pack builds your entire package: code, assets, and even package.json manifest. By building the entire package, you end up with a fully-built pkg/ directory, ready to publish. Entry points like "main", "module", "umd:main", "types", "unpkg", "files", and even advanced options like "sideEffects" are all handled by your build pipeline.

Available Builders

Source Builders:

NOTE: Include a source builder early in your pipeline. Source builders take your modern source code (ESNext, TS, etc.) and compile it to standard, ES2018 JavaScript. Other builders will then use this standardized build to base their own work off of.

Distribution Builders:

WASM Builders:

Advanced Builders:

  • @pika/plugin-bundle-node: Creates a Node.js build with all code (including dependencies) bundled into a single file. Useful for CLIs.
  • @pika/plugin-bundle-web: Creates a ESM build with all code (including dependencies) bundled. Useful for unpkg & serving code directly to browsers.
  • @pika/plugin-simple-bin: Generates & configures a CLI wrapper to run your library from the command line.
  • Write your own! @pika/pack can load local builders by relative path directly from your repo.
  • Publish & Share your own! These official builders are just the start. Create a PR to add your community plugin to this list.

See a full list of official builders here →

Community Builders

Bonus Command: publish

Demo

We've brought our favorite parts of np (a self-described "better npm publish") into @pika/pack. With the publish command there's no need to worry about how to publish your package once you've built it.

Run pack publish in your project and @pika/pack will walk you through version bumping, tagging your release, generating a fresh build, and finally publishing your package.