Bakery is an opinionated utility for building and releasing projects with Bun. It’s intended for tools and executables, not libraries.

In particular, it supports:

  1. Versioning project changes with a CHANGELOG.md file.
  2. Creating Github releases for new versions.
  3. Publishing new versions to NPM.
  4. Publishing new versions as single-file executables for all available targets.

By design, most bakery commands are intended to be run in a Github Action when a new version is created:

The user kicks off a version release with the bakery version command, then build, publish, and release commands are run in Github Actions.

For each new version, you’ll get a Github release that looks something like this:

Screenshot of a Github release for the bakery project.

Read on for how to start using bakery in your own projects.

Getting Started

Dependencies:

  • Bun
  • Git

The simplest way to start with bakery is to use bunx to automatically configure an existing Bun project:

bunx @luketurner/bakery init

This will:

  1. Install @luketurner/bakery as a dev dependency.
  2. Create a Github action to handle creating releases etc.
  3. Create a CHANGELOG.md if it doesn’t already exist.

Then you just need to publish your first version (replace 0.0.1 with the version you want to create):

bun run bakery version 0.0.1 --push

The --push flag automatically pushes the created tag/commit to the origin remote.

bakery version

The version command is perhaps the most opinionated part of bakery, because it codifies a standard workflow for creating new versions:

  1. Adds the new version to CHANGELOG.md and opens it for you to write your changes.
  2. Updates the version and creates a tag for it using the bun pm suite of commands.
  3. If --push is specified, push the tag and current branch to the remote.

You should run bakery version once you’re ready to cut a new release and all code changes for it have been committed.

Instead of specifying an explicit version to create, you can specify major, minor, or patch to bump the existing version. For example:

bun run bakery version minor --push

bakery commands are idempotent for the same version (it won’t attempt to update existing releases, etc.), so bakery version is an essential tool for easily flagging some code as “this should be published”.

bakery build

The build command just calls bun build to create an executable, then wraps it in either a .zip (for Windows) or .tar.gz (for everything else) archive. It does this for every available build target by default.

Builds created by bakery have two special characteristics that your app can use to conditionally adjust behavior:

  1. The NODE_ENV variable is inlined (hardcoded) to "production".
  2. The RELEASE variable is inlined (hardcoded) to true.

Usually, you won’t need to run bakery build yourself, but you can create builds locally for testing by adding the --target flag:

bun run bakery build --target bun-linux-x64

bakery release

This parses the latest release from the CHANGELOG.md and creates a new release in Github based on it.

bakery release depends on the gh CLI being set up and generally is assumed to be run in a Github Action where all that is taken care of already.