There have been a handful of times when I thought it would be nice to publish a JavaScript library on NPM. It was either a small library I kept using in different projects or a command-line tool I thought was useful enough to share with coworkers. But every time I started researching the process of building and publishing packages to NPM, I would invariably become overwhelmed.
After going down the rabbit holes of best practices and support I realized that my afternoon project just cascaded into the evening, and then into the night. If I did make any headway, I was never sure of it. I was constantly asking myself, “Am I really doing this right?”
When a former coworker asked if I had ever used @pika/pack, a new tool designed to do all of the heavy lifting for building and publishing NPM packages, I jumped at the opportunity. This past week I took @pika/pack for a test run by creating and publishing a simple CLI tool.
What is @pika/pack?
The NPM ecosystem is gigantic, and the quality of packages you can find runs the full gamut of quality and usability. Packages that look well-used can give you headaches if you don’t use modern language features or vice-versa, and working with NPM packages within languages like TypeScript can be a world of hurt if the typings aren’t present. @pika/pack is a tool that helps package developers build and publish optimized builds for the web, Node.js, TypeScript, WebAssembly, and more, using pluggable pipelines and simple configuration. You can read the project developers’ full introduction and see code samples here.
Putting @pika/pack to the test
The CLI tool I wrote to try out @pika/pack is a simple search for images on Docker Hub. Unlike the docker search utility, this tool restricts results to official images only and provides terminal links to their respective pages on Docker Hub. Here’s what the finished product looks like:
IDGI wrote the lookup tool using some modern JavaScript syntax like import statements, arrow functions, and template literals and I used babel-node to run it locally while I was developing. Once I got it to where I wanted it, I was ready to incorporate @pika/pack, build, and publish.
@pika/pack installation and setup
The first step to incorporate @pika/pack is installing a few dependencies and modifying your package.json to include an extra configuration setting. I chose to install the standard package plug-in, the Node.js plug-in, and the simple-bin plug-in in order to deploy this tool as an executable CLI.
npm install --save-dev @pika/pack @pika/plugin-standard-pkg @pika/plugin-build-node @pike/plugin-simple-bin
The only configuration needed is to choose the order of plug-ins you want to use in your pipeline build, as shown in this excerpt from package.json:
"name": "dlook-cli",
"version": "0.1.1",
"description": "A cli tool to search official docker containers",
...
"@pika/pack": {
"pipeline": [
[
"@pika/plugin-standard-pkg"
],
[
"@pika/plugin-build-node"
],
[
"@pika/plugin-simple-bin",
{
"bin": "dlook"
}
]
]
}
Building a package with @pika/pack
Building then becomes as simple as running pack build, if you have @pika/pack installed globally:
IDGThe first time I tried this I ran into issues, however. That’s because I didn’t adhere to an undocumented requirement that all of your source code be in a src directory. I had set up a flat repository because the project was so simple. You also have to ensure that your main script is named index.js regardless of what the entry point in your package.json specifies. Both of these expectations were undocumented, but the error messages were clear and I was past these bumps in a flash.
From here, you can take a look at each of the directories within the newly created pkg directory to see what the pack command actually generated. I’m only interested in the executable binary, so a quick test running the command locally was all I needed to give me some confidence:
IDG
Less descriptive error messages aren’t quite as helpful.
Referencing the @pika/plugin-simple-bin repository led me to the answer quite quickly: In order to use the plug-in, you have to expose a run function from your index.js file. The plug-in wraps and executes this function in a relatively simple way, so while the error message wasn’t very descriptive, the fix was straightforward. Another round of building and testing led to the output I was expecting:
IDGPublishing a package with @pika/pack
Happy with the build, it was time to publish. @pika/pack borrowed heavily from np, a great tool for publishing to NPM, so the interface for publishing may be familiar to you:
IDG
Helpful verifications and options smooth the process quite a bit.
After reviewing commits and choosing a new version, the tool tests and publishes your package in addition to updating your package.json to include the bumped version.
IDGAll in all, my first experience with @pika/pack was great, despite some minor confusion due to lack of documentation. @pika/pack is a brand new project, though, so expect those little bumps to smooth out as the community adopts, uses, and contributes back to the project.
As always, the code in this column is available on GitHub. If you want to try out the utility I built and published, simply run:
npm install -g dlook-cli
dlook --help
Any questions or comments? Please continue the conversation on Twitter: @freethejazz