Introducing: @pika/pack

npm package building, reimagined.

Star on Github

If you've recently published a package to npm, you know how much work goes into a modern build process. Transpile JavaScript, compile TypeScript, convert ES Module syntax (ESM) to Common.js, configure your package.json manifest... and that's just the basics.

What about web browsers and bundlers? Is your package optimized for them? Can users load your package from UNPKG? Does it include type definitions for VSCode & TypeScript users? Has it been stripped of all unnecessary files to be as small as possible? Your users care about these optimizations, but they all require even more knowledge, configuration, tooling, time and effort to get right.

@pika/pack builds amazing packages without the hassle:
  • Simple ⚡️ Use pre-configured plugins to build your entire package.
  • Flexible 🏋️‍♀️ Choose plugins and optimizations that match your needs.
  • Holistic ⚛️ Let us handle your code, assets, and package.json config.

The Package Build Pipeline #

@pika/pack connects pre-configured plugins to build and optimize your package for you. Plugins wrap already-popular tools like Babel and Rollup with options already optimized for npm. This lets @pika/pack build your package without much (if any) configuration required on your part.

@pika/pack even creates and configures a package.json manifest for your package, automatically.

This works 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", and even advanced options like "sideEffects" and "files" are all handled by your build plugins.

Getting started is easy:

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

😎 🆒

So now what? If you run pack build with an empty pipeline, you'll get an empty package. That's not very useful.

To get you started, here are our five favorite things to do with @pika/pack:

1. Publish Modern, ES2018 JavaScript By Default (1 Line) #
"@pika/pack": {
    "pipeline": [
        ["@pika/plugin-standard-pkg", {"exclude": ["__tests__/**/*"]}]
    ]
}

The first plugin that most packages will use is @pika/plugin-standard-pkg. This is our standard "source" builder that builds any JavaScript & TypeScript source code to the latest ES2018 language spec. TypeScript is supported by default, and any custom Babel plugins in your local .babelrc will be used automatically (the plugin is powered by Babel internally).

This gives the rest of our pipeline a standard ES2018 target to build from. BONUS: some of your users may support modern JavaScript, and can leverage this ES2018 distribution directly for a smaller, faster, less-bloated package.

2. Publish Node.js & Web-Optimized Builds (1 Line Each) #
"@pika/pack": {
    "pipeline": [
        ["@pika/plugin-standard-pkg"],
        ["@pika/plugin-build-node"],
        ["@pika/plugin-build-web"]
    ]
}

After creating your modern ES2018 build, it becomes trivial to add Node.js- and web-optimized distributions to your package. @pika/plugin-build-node will transpile a Node.js-ready distribution to run on any supported Node.js version. @pika/plugin-build-web will build a more modern, ES module (ESM) distribution: optimized for bundlers and compiled to run on all browsers that support ESM syntax natively.

Both plugins use Rollup internally, but you don't have to configure any bundler logic yourself. With just three lines of JSON you get a package that is fully optimized for the two most popular JS platforms. And because @pika/pack builds your entire package, your package.json manifest is automatically configured for you with "main", "module", and "esnext" entry points.

3. Automatically Generate TypeScript Definitions (1 Line) #
"@pika/pack": {
    "pipeline": [
        ["@pika/plugin-standard-pkg"],
        ["@pika/plugin-build-node"],
        ["@pika/plugin-build-web"],
        ["@pika/plugin-build-types"]
    ]
},

With @pika/pack, every package automatically gets .d.ts TypeScript definition files thanks to the @pika/plugin-build-types plugin. Even if you're writing JavaScript, this plugin will use TypeScript to automatically generate type definitions from your JavaScript & JSDoc!

4. Publish WASM! Or Reason, or Rust, or C++, or... (1-2 Lines) #
"@pika/pack": {
    "pipeline": [
        ["@pika/plugin-wasm-assemblyscript"],
        ["@pika/plugin-wasm-bindings"]
    ]
},

The pipeline concept is simple AND flexible. So flexible that your package source doesn't even need to be JavaScript:

5. Automatically Enhance Your Package (1 Line) #
"@pika/pack": {
    "pipeline": [
        ["@pika/plugin-standard-pkg"],
        ["@pika/plugin-build-node"],
        ["@pika/plugin-simple-bin", {"bin": "my-cli"}]
    ]
}

Build plugins can also enhance existing builds in some really exciting ways. Our favorite enhancement right now is @pika/plugin-simple-bin, which injects a simple CLI wrapper into any package and configures your package.json to point to it automatically.

We use @pika/pack to build @pika/pack, and we use this plugin specifically to add a command-line interface with none of the package.json configuration and setup hassle.

We can't wait to see what's possible with this wrapping concept, especially for CLIs: Automatically restart your program on failure, check for package updates after running, log usage statistics... the possibilities are endless!

Publishing Your Package #

Publishing your package should be as easy as building it. So we 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 built package. Just run pack publish in your top-level project and @pika/pack will walk you through cutting a new version and publishing your package.

It even includes a handy unpkg.com at the end so that you can immediately view your new package.

Try @pika/pack Today! #

npm install -g @pika/pack

Don't wait, try @pika/pack in your next package (or any old ones that could a 2019 upgrade). And when you do, please let us know how it went!

Pika is a project to move the JavaScript ecosystem forward. Pika's mission is to make modern JavaScript more approachable by making it easier to find, publish, install, and use modern packages on npm. Hopefully @pika/pack moves us one step closer towards that goal.

Projects Already Using @pika/pack #

Have you used @pika/pack in a package? Let us know and we'll add your package to the list!