In deciding to support npm and pnpm as package managers as well, bun-workspaces's name became obviously inappropriate if I were to continue development.

With that, I'm introducing pacwich! This is the official continuation of bun-workspaces with multi-package-manager support.

pacwich is built from bun-workspaces's core and is mostly backwards compatible. If you're an existing user, you can use the official migration guide and explore the docs, which have enhanced LLM integrations as well.

Read on to learn more about my motivations and strategy for the pivot.

# Global install with your preferred package manager
# The pacwich command will use a local install if available
bun add -g pacwich
pnpm add -g pacwich
npm install -g pacwich

# Local install in your project
bun add -d pacwich
pnpm add -D pacwich
npm install -D pacwich

The CLI is essentially backwards compatible, save for the fact that the system shell (sh/cmd.exe) is now the default for inline scripts over the Bun shell, since Bun is no longer guaranteed to be available due to Node and npm/pnpm support.

# Before (bun-workspaces):
alias bw="bunx bun-workspaces"
bw ls
bw run lint my-workspace "path:my-packages/**/*" --parallel=2
# Bun shell default for inline scripts:
bw run --inline "echo <workspaceName>" --shell=bun

# After (pacwich):
# You could alias "pw", but demonstrating the vanilla global install
pacwich ls
pacwich run lint my-workspace "path:my-packages/**/*" --parallel=2

# "system" now the default shell for inline scripts
# Pass --shell=bun to use Bun shell instead if Bun is available:
pacwich run --inline "echo <workspaceName>" --shell=bun

Some History​

Since early in my career, I have found monorepos to be very satisfying to work with.

npm's workspaces feature was the first tooling I used for monorepos, but it felt very bare-bones.

For many years, I had an itch I wanted to scratch by making my own monorepo tooling that worked as directly with native tooling like as possible. I wanted it to be both lightweight and my own.

At some point after Bun's release, I started using it more and more until it became my package manager of choice for TypeScript projects.

I created bun-workspaces on a whim to get around a now irrelevant limitation of Bun's --filter feature. It gave me an excuse to start building the monorepo toolset I had wanted for years, and I noticed that I was getting more positive reactions from other devs than I expected as a no-name, but I didn't take the project very seriously until about a year later.

Why Change?​

A Revelation of Abstraction​

After months of building upon bun-workspaces, it went from only the CLI that gave you metadata about workspaces and ran scripts in series or parallel to a CLI and TS library with more powerful configuration and a rapidly solidifying set of concepts.

As bun-workspaces became more advanced, I noticed that its mental model was increasingly less specific to Bun as it started to grow as its own set of abstractions, such as "workspace patterns," its model for the affected graph, and more.

Workspace patterns used to select subsets of workspaces in various features and config:

"my-name-or-alias" # matches workspace name or alias
"my-name-pattern-*" # matches workspace names only by wildcard
"alias:my-alias-pattern-*" # matches workspace aliases by wildcard
"path:packages/**/*" # matches workspace paths by glob
"tag:my-tag" # matches workspaces with tag in config
"not:my-name-or-alias" # excludes workspace name or alias
"not:tag:my-tag-pattern-*" # excludes workspace tag matching wildcard
"re:^my-regex-pattern$" # matches workspace name or alias by regex
"not:tag:re:^my-tag-regex-pattern$" # excludes workspace tag by regex
"@root" # matches the root workspace

An Anti-Lockin Philosophy​

Part of my philosophy for bun-workspaces was to make it relatively unopinionated and anti-lockin. However, its own namesake and description made it locked into one package manager.

Reflecting upon this, I dug deeper into whether bun-workspaces could retain all its present functionality while working with npm or pnpm workspaces instead.

No Time Like The Present​

After confirming that this was a reasonable goal, I couldn't ignore the fact that if I wanted this, putting it off and continuing development of bun-workspaces would mean accruing technical debt and unknowns for this pivot.

On top of this, more feature additions to bun-workspaces would mean more potential migration pain for users, so I didn't want to waste any time. My bun-workspaces releases halted, where almost a month went by without a release instead of my usual weekly cadence.

I am still a fan of Bun's design as a package manager and think it handles workspaces and dependency catalogs very elegantly, and I still plan to use it personally.

However, I realized that decoupling my monorepo tooling from my package manager and runtime would provide greater freedom in development, and I could not ignore this realization.

Development Strategy​

AI Assistance​

I will get the elephant out of the room early here.

In a page on pacwich's security practices, I wrote at length about my approach to using AI tools for development of open source like this.

The quick summary is that I greatly value knowing my codebase and performing real manual review of code I'm releasing, and I want to make it clear that I have no desire to release risky vibe code in a package that deals with monorepo shell script orchestration and DevOps.

For this pivot, tools like Claude Code and the Windsurf IDE did assist my effort.

However, I refused to perform this launch until I had re-reviewed the entire source code, documentation, and tests myself. I can't stand to feel like I don't know a codebase of this importance inside and out.

I also want to clarify that I write the documentation found at https://pacwich.dev myself. I only use agents like Claude to review what I wrote to flag potential mistakes rather than write it for me. I personally would feel embarrassed if I couldn't describe my own spec, and this is a way to keep myself feeling like I am the one who truly leads the project, not one of my tools.

If I was trying to show off how fast I could pump this pivot out, I could have easily gotten it done in a week or less. I'm extremely glad that I didn't do this and instead spent a month ensuring it was ready enough.

Luckily, while this was a lot of work, the changes to source code aren't as dramatic as they might seem, meaning that my knowledge of bun-workspaces's source code, which I developed largely manually, carried over.

Things That Stayed​

pacwich's own source monorepo retains almost exactly the same structure as bun-workspaces. Similarly, pacwich's package source code also retains the same general shape, with a large majority of modules carrying over.

In addition to this, almost all exisitng bun-workspaces tests remained. The overwhelming majority of test changes other than minor Bun specifics ended up being additions of coverage.

Given that pacwich is mostly backwards compatible with bun-workspaces, the similarities should only be natural, so despite its newness, it is far from brand new to me as its maintainer.

Actual Stages of Development​

I'll describe my actual strategy that I took in performing this pivot, and you'll see this was by no means anything close to a one-shot.

Stage 1: Make source code compatible with NodeJS​

One tradeoff of this pivot was that I could no longer rely on Bun builtins without introducing a layer of complexity to swap out builtins based on the runtime.

I decided the most straightforward path would be to simply make existing source code equally compatible in both Bun and Node without this split.

My goal here was to replace all Bun builtins with Node builtins that Bun also supported, until existing tests passed with almost no modificiations and the package seemed to function normally locally.

Bun.spawn -> child_process.spawn

Stage 2: Migrate the test runner​

This is related to the last stage, since at this point, I was using Bun's test runner and therefore could not confirm tests passed when Node was actually used at the runtime.

I migrated tests to vitest and added scripts to run tests through Bun or Node. Actual test code generally did not meaningfully change besides Node support changes in utilities.

# before
bun test

# after
npx vitest # use Node.js runtime
bunx --bun vitest # force Bun runtime

Stage 3: Design an adapter layer to hide Bun details​

Before jumping to npm and pnpm support, it made sense to first extract all behavior specific to Bun integration into a new layer that would abstract away the package manager.

This way I could prepare the multi-package support while confirming that the existing tests passed for what was still essentially bun-workspaces at this point.

parseBunLock() -> createAdapter("bun").parseLockfile()

Stage 4: Create a testing layer for the adapter layer​

To further prepare for npm and pnpm support, it made sense to go ahead and add tests that would iterate over each supported pm to confrim conformancy of behavior, ensuring that behavior was the same across the CLI and API for the same set of test projects.

Stage 5: Add support for npm workspaces​

Now that an adapter existed with conformancy tests, adding pm support just meant making a new adapter implementation.

This was the natural first choice due to npm's simplicity and the fact that its workspace configuration is very similar to Bun's, using package.json["workspaces"].

However, this addition inspired the verify feature used to help ensure workspace-to-workspace dependencies are explicitly defined in workspace package.json files, something npm does not require, unlike Bun and pnpm.

Stage 6: Add support for pnpm workspaces​

This was the obvious next step, which mainly involved adding in the YAML parsing and logic needed to read pnpm-workspace.yaml and pnpm-lock.yaml.

// Hooray!
export const PACKAGE_MANAGER_NAMES = ["bun", "pnpm", "npm"] as const;
export type PackageManagerName = (typeof PACKAGE_MANAGER_NAMES)[number];

Stage 7: Desired deprecations and small breaking changes from bun-workspaces​

Since this is the launch of a brand new package, I took the opportunity for some minor breaking cleanup items described in the migration guide.

Stage 8: Feature additions​

Mainly due to npm's lack of requirement for explicit workspace dependencies, the verify feature was designed to help detect workspaces that imported/exported from workspaces not declared as dependencies in package.json.

AI integrations had some improvements, while most MCP tools were removed, since they were too redundant and limited compared to CLI, placing emphasis on using MCP resources to read the package overview and CLI docs.

A CLI feature to add skill files was added as a quick win for another means of providing docs to an agent.

Stage 9: Documentation and Final Manual Reviews​

This was actually the longest of all these stages. As I described earlier, I rewrote the old bun-workspaces documentation website into pacwich.dev, myself, which was worth it.

In addition to multiple agent passes to help with review, I also conducted a full unassisted manual review of the codebase myself to regain confidence in my source code knowledge, since a lot of details had changed.

Even though I already reviewed as I went through each stage, this was one last deep dive where I caught code smells, adjusted code to match style and naming consistency, found concerns to refactor for DRYness and the like, polished tests, removed long comments where better naming would suffice, and more.

I also had a lot of other preparations to do, like writing this very blog post.

/** @todo plan changes for every single thing bun-workspaces ever touched */

Conclusion​

If you have read this as someone who was already a fan of bun-workspaces, I hope that you feel as optimistic as I do that this is a net win for the project, as almost nothing has been lost from bun-workspaces while several new advantages not possible before have been gained thanks to runtime and package manager portability.

While pacwich is at 0.x at launch, I plan to guard stability as much as I can., treating it more like a 1.x or higher version without a very compelling reason for any breakage.

bun-workspaces 1.9 is a major milestone for the project, thanks to the new debuggable affected graph!

Read on for more details, or get straight into the documentation.

More documentation resources:

• Affected Overview
• CLI:
  • bw list-affected
  • bw run-affected
• TS/JS API:
  • FileSystemProject.determineAffectedWorkspaces()
  • FileSystemProject.runAffectedWorkspaceScript()
• Configuration
  • Project Root Configuration (sets default base git ref for comparison)
  • Workspace Configuration (sets inputs for affected detection)
  • Workspace Inputs (configuring affected detection inputs)
• Workspace Dependencies (how workspaces depend on each other)

Graphs?​

The "graph" term hasn't been explicitly used with bun-workspaces primitives and features very much, but it's a useful concept that still applies.

The Project Graph​

In bun-workspaces, you could say that the project graph is simply the structure of your workspaces and how they depend on each other, each workspace being a node and each dependency being an edge.

bun-workspaces does not perform source code analysis to determine the graph, since with Bun, workspaces must be explicitly declared in package.json dependencies like "my-workspace-name": "workspace:*" for imports/exports to work between them.

This makes determining the project graph fast and computationally cheap.

The Affected Graph​

The affected graph is simply only the part of the project graph that has been meaningfully changed.

If one can determine which workspaces are affected by some code change, that can be very helpful for orchestrating DevOps tasks, such as running builds for only those changed workspaces.

What is a Meaningful Change?​

Inputs: The Source of Changes​

By default, a workspace is considered to have a set of inputs.

When not configured, the default inputs are:

• All git-trackable files in the workspace's directory
• All workspace dependencies. If a workspace dependency is affected for any reason, its dependents are also considered affected.
• The version resolved in bun.lock for all other dependencies in a workspace's package.json.

Inputs can be configured per script as well.

Here's an example of a workspace config that configures its inputs:

// path/to/your/workspace/bw.workspace.ts

import { defineWorkspaceConfig } from "bun-workspaces/config";

export default defineWorkspaceConfig({
  alias: "my-web-app",
  tags: ["frontend"],
  // All input config is optional
  defaultInputs: {
    // default: all git-trackable files in the workspace directory
    files: [
      "src/**/*.{ts,tsx}",
      "!src/**/*.test.{ts,tsx}",
      "/tsconfig.json", // relative to project root
    ],
    // treat all tagged libs like dependencies
    workspacePatterns: ["tag:lib"],
    // treat only the "react" package as affect-able
    externalDependencies: ["react"],
  },
  scripts: {
    // configure inputs per script
    test: {
      inputs: {
        files: ["src/**/*.{ts,tsx}"],
      },
    },
  },
});

Detecting Changes​

There are two main ways to determine affected workspaces:

Using git diff (default)​

The default behavior of affected features is to use the git diff between the current HEAD and the default base ref in git.

The default base ref is main except when overridden via the project root config or a environment variable BW_AFFECTED_BASE_REF_DEFAULT.

Uncommitted changes (staged, unstaged, untracked) are considered a part of the diff by default. Files that are gitignored are never considered a part of the diff.

# Uses diff of current HEAD against the default base ref
bw ls-affected

# Compare specific refs (can also pass commit SHA, tag, etc.)
bw ls-affected --base=my-branch-a --head=my-branch-b

# Ignore uncommitted changes
bw ls-affected --ignore-uncommitted # (staged, unstaged and untracked)
bw ls-affected --ignore-untracked
bw ls-affected --ignore-unstaged
bw ls-affected --ignore-staged

# Ignore changes to workspace dependencies derived from package.json files
bw ls-affected --ignore-workspace-deps

# Ignore changes to external dependencies (e.g. npm packages)
bw ls-affected --ignore-external-deps

Using a list of changed files​

You can bypass using git entirely and simply pass a list of changed files that match workspace inputs.

bw ls-affected --files="packages/example/**/*.ts packages/example/my-file.js"

Debuggability​

You can use the --explain flag to get detailed reasoning for the affected workspaces.

# Detailed output about every changed file and dependency
bw ls-affected --explain --detailed

This can give you output such as this when workspace-b depends on workspace-a, whose my-script.ts file is changed:

Workspace: workspace-a
Path: packages/workspace-a
Changed input files:
 - my-script.ts (input: "my-script.ts")
Affected dependencies: (none)
Changed external dependencies: (none)

Workspace: workspace-b
Path: packages/workspace-b
Changed input files: (none)
Affected dependencies:
- workspace-a
  chain: workspace-b --[package]-> workspace-a
  Changed external dependencies: (none)

Running Affected Scripts​

You can run a script across all affected workspaces with the bw run-affected command.

It essentially marries the options of bw ls-affected and bw run.

bw run-affected my-script --base=my-branch --ignore-uncommitted

API Parity​

As usual, the TypeScript API is in parity with the CLI.

Determine affected workspaces via git:​

import { createFileSystemProject } from "bun-workspaces";

// Initialize Project, by default at process.cwd()
const myProject = createFileSystemProject();

// Workspace results contain details about each workspace,
// including whether it is affected and why
const { workspaceResults } = await project.determineAffectedWorkspaces({
  // Optional, the script to run to determine affected workspaces
  // When not provided, based on workspaces' default inputs
  script: "my-script",
  diffSource: "git",
  diffOptions: {
    // Optional, defaults to main if default base ref not configured
    baseRef: "my-branch-a",
    // Optional, defaults to current HEAD if not provided
    headRef: "my-branch-b",

    // Optional means of ignoring uncommitted changes
    // gitignored files are never included in a diff
    ignoreUntracked: false, // files that may be tracked but aren't
    ignoreStaged: false,
    ignoreUnstaged: false,
    // Ignores untracked, staged, and unstaged
    ignoreUncommitted: false,
  },
  // Ignore workspace dependencies when determining affected workspaces
  ignoreWorkspaceDependencies: false,
  // Ignore changes external dependencies (e.g. react, lodash) lock versions
  ignoreExternalDependencies: false,
});

Determine affected workspaces via list of files:​

import { createFileSystemProject } from "bun-workspaces";

const myProject = createFileSystemProject();

const { workspaceResults } = await project.determineAffectedWorkspaces({
  // Bypass git and pass a list of changed files that match workspace inputs
  diffSource: "fileList",
  changedFiles: ["src/**/*.ts", "something.txt"],
});

Run a script across affected workspaces:​

import { createFileSystemProject } from "bun-workspaces";

const myProject = createFileSystemProject();

// Returns the same output and summary as project.runScriptAcrossWorkspaces
const { output, summary } = await project.runAffectedWorkspaceScript({
  // About the same options as project.determineAffectedWorkspaces
  affectedOptions: {
    diffSource: "git",
    diffOptions: {
      baseRef: "my-branch-a",
      headRef: "my-branch-b",
    },
  },
  // About the same options as project.runScriptAcrossWorkspaces
  scriptOptions: {
    script: "my-script",
  },
});

Conclusion​

This is an exciting and big improvement to bun-workspaces I've wanted since day one, but I wanted to ensure that the right foundation was in place for it first.

This is just one of several features to come that add advanced monorepo management capabilities to bun-workspaces without changing the fact that you can use the package right away without any configuration.

This continues to reinforce my hypothesis that powerful monorepos can be achieved with more lightweight tooling that works with, rather than against, native tooling.

bun-workspaces 1.5 is here! Let's cover some noteworthy feature additions since version 1's release.

Jump to: TypeScript Configs | Workspace Tags | Dependency Rules | MCP Server

TypeScript/JavaScript Config Files​

bun-workspaces's optional config files were only able to be written in JSON/JSONC previously.

Now, config files can be written in TypeScript or JavaScript, such as in bw.workspace.ts:

import { defineWorkspaceConfig } from "bun-workspaces/config";

export default defineWorkspaceConfig({
  alias: "my-web-app",
  tags: ["frontend"],
  rules: {
    workspaceDependencies: {
      denyPatterns: [
        "tag:backend", 
        "path:packages/internal/**/*",
        "some-specific-workspace",
        "not:name:my-negated-name-pattern-*"
      ]
    }
  }
});

What makes this powerful beyond having TypeScript autofill for config properties is the ability to share code between config files via import/export, so you can more easily set up similar config files between workspaces, using whatever pattern you want in TypeScript.

The above config has some of the newest features showcased. Read on to learn more about them.

Workspace Tags​

This is a simple concept but potentially very powerful for a project.

Prior, workspaces had several identifying traits: their name (from their respective package.json), any aliases configured in their bun-workspaces workspace configuration, and their path. It has been possible to match workspaces by any of these traits via workspace patterns.

Workspace tags are simply strings that can be added to a workspace's configuration that can be shared between workspaces.

Where these really come in handy is workspace patterns, which can be used when listing scripts and running scripts.

For example, workspace patterns could be workspace-name, path:my-glob/**/*, or now tag:my-tag/tag:my-tag-pattern-*, the latter matching all workspaces matching the given tag or tag wildcard pattern. In the CLI, bw run lint tag:my-tag will run the lint script from package.json for all workspaces that have "my-tag" in their configured tags.

These can be a useful pattern to use in workspace dependency rules, a new feature, covered next:

Workspace Dependency Rules​

Monorepos are powerful for code sharing. The bun-workspaces documentation covers some of the basics behind workspace dependencies, which are declared in package.json dependencies like "my-workspace-name": "workspace:*".

Oftentimes, one of the main reservations people have about making code sharing simpler is leaking code that shouldn't be exposed in the wrong package.

Monorepos are great for developing a full stack application using TypeScript for both the frontend and backend, but people don't want their backend code being included in their frontend, especially for a web app where it's very easy to inspect and get code that was accidentally bundled.

Dependency rules let you use workspace patterns in your workspace configuration in order to allow or deny dependencies, so that bun-workspaces will exit with an error if any workspaces violate their rules.

For example, you could use the new tags to tag all your backend workspaces, so that your frontend workspaces can then deny backend code.

This does take into account the whole dependency tree, such as when a workspace that violates a rule is a dependency of a dependency.

With the new TypeScript configs as we have seen earlier, we could set up something like this for frontend workspaces:

// configHelpers.ts

import { type WorkspaceConfig } from "bun-workspaces/config";
  
export const FRONTEND_WORKSPACE_CONFIG: WorkspaceConfig = {
  tags: ["frontend"],
  rules: {
    workspaceDependencies: {
      denyPatterns: ["tag:backend"]
    }
  }
};

export const BACKEND_WORKSPACE_CONFIG: WorkspaceConfig = {
  tags: ["backend"]
};

// packages/my-frontend/bw.workspace.ts

import { defineWorkspaceConfig } from "bun-workspaces/config";
import { FRONTEND_WORKSPACE_CONFIG } from "../../configHelpers";

export default defineWorkspaceConfig({
  alias: ["my-fe"],
  ...FRONTEND_WORKSPACE_CONFIG
});

// packages/my-backend/bw.workspace.ts

import { defineWorkspaceConfig } from "bun-workspaces/config";
import { BACKEND_WORKSPACE_CONFIG } from "../../configHelpers";

export default defineWorkspaceConfig({
  alias: ["my-be"],
  ...BACKEND_WORKSPACE_CONFIG
});

Now you can reuse the configHelpers.ts utilities in any frontend-related or backend-related workspace, and if a frontend workspace declares a backend workspace as a dependency (or any workspace with a backend dependency itself, etc.), you will get an error.

Update​

Version 1.6 introduced workspace pattern configs that can be used in the project root config for bulk DRY workspace configs.

MCP Server​

See the Documentation for information about setup.

bun-workspaces is a newer, growing open source tool. That means that AI doesn't generally know about it by default. This is an issue with new open source, but that doesn't mean modern development is now stuck with only pre-existing open source tooling.

Now the CLI ships with an mcp-server command that you can use to set up in your tooling that supports MCP, like Cursor or Claude Code.

The server provides instructions outlining the overall use of the bun-workspaces CLI and TypeScript API to your AI, and it includes tools for using some of its functionality to get project metadata and resources that allow it to read more complete docs about all of its features if necessary.

Now your tooling doesn't have to guess how bun-workspaces works!

1978: The VT100 is released, the first terminal with a video display to support the ANSI codes used today. There are control codes for the keyboard's lights, reminding me of the the RGBs on my mechanical keyboard that have been a great way to impress women.

1989: The bash terminal shell is released under one of the first open source licenses, combining many of the best features of existing shells that could control the Unix operating system. Two years later, Linus Torvalds ports it to Linux.

2005: Linus Torvalds releases git, an improved system of version control and collaboration for developing a directory of files, though Linus's first commit to its own source code calls it "the information manager from hell."

2011: The idea of a "coding bootcamp" is first seen. The current barrier of entry for code self-education is lower than most people realize. Years later, I eventually attend one of these bootcamps, where I am first taught to use bash and git in macOS's terminal emulator.

2025: Claude Code is released, including the fully terminal-based AI coding interface used popularly by developers of all experience levels. A year later, I attend a vibe coding hype presentation of Claude targeting a non-technical audience that inevitably ends up emphasizing having some familiarity with bash and git.

What even are the fundamentals of software engineering?​

A pattern we see in software development is the stark contrast in the increasingly rapid and dramatic changes to how we work, while some aspects don't seem to ever die.

People hardly seem to agree on which aspects are dead, which are about to die, which are worth spending time on, and so on.

It doesn't help that platforms where general tech discourse is held, like LinkedIn and other social media, reward hot takes and bold predictions more than patient, measured discussion.

When this is the case, it's hard to find agreement on what fundamental skills even are.

To JavaScript, or not to JavaScript​

10 years ago, it was very valuable to just be very strong at JavaScript. However, even then, saying that knowing JavaScript is a truly fundamental skill was arguably too superficial.

Now, even the idea that knowing JavaScript is important to write JavaScript is being challenged.

To say that specifically operating the 1978 VT100 terminal is a fundamental skill now is at least obviously ridiculous.

What are we doing today, though? Many of us still decide to emulate the same experience and even use the latest AI in similarly ANSI-compatible terminal software.

Apparently, something stuck there, and there is something to this beyond just receiving software hand-me-downs.

The Practice of Coding: A 7-Foot Toddler​

Part of what I believe is difficult about these discussions is the fact that computer science and coding are very young practices in terms of human history.

While we advance technology at never-before-seen rates, we barely have time to process what we've really been doing.

It seems like just as we start to really define development, something comes along that shakes up the details of that narrative, and we're left picking up the pieces to see which are still useful to us, some wanting to throw all those pieces straight into the trash, as if due to personal vendetta.

An Understood Domain of Code: Music​

Something many academic musicians are well aware of is the fact that our primary means of communicating about music in great detail (sheet music, musical theory concepts, acoustic science, etc.) is a form of musical code.

One could argue that sheet music is one of the oldest and most sophisticated forms of written code, early forms going back to 2000 B.C.

An Efficient Code​

Sheet music is extremely efficient at representing a large amount of music.

One page potentially equates to several minutes worth of music, providing a large variety of instructions for the performer: pitch, duration, key, tempo, volume, harmonic context, rhythmic meter, technique, emotion, free-form comments, and more.

These aspects are all able to be compressed to a relatively short line that's still readable enough for a skilled reader to digest it at sight. Is any of this sounding familiar?

Known Musical Fundamentals​

People have been practicing and teaching music for millennia. Thanks to this, a lot is known about the mental and physical development of musical skills. There are exercises and whole thought systems passed down for generations broadly.

That being said, on some level, musical traditions still haven't escaped the bulldozer of tech.

A guitarist can use an electronic tuner instead of their ear. However, most musicians still would agree that this in no way makes hearing when something is out-of-tune obsolete, even for guitarists.

An electronic musician can fully automate rhythm. However, again, most musicians agree that this does not make understanding rhythm obsolete. Many electronic musicians eventually come to value having physical electronic instruments like beat pads so they can capture rhythm and emphasis from their head naturally, using old school tools: their minds and their hands.

The Nature of Fundamentals, in a Sense​

The two examples I provided hit two major fundamentals for a musician: A sense of pitch, and a sense of rhythm.

Fundamental skills are often related to some underlying human sense that is applicable regardless of how advanced the technology used on top of it is.

Engineering Senses​

It's difficult to truly capture the internal senses we're using as software engineers. Many that can feel it have been trying to express it in a variety of ways despite the difficulty, including myself.

I'm going to attempt here to describe some of the "senses" that engineers use that are still fundamental today. I won't pretend that it's an exhaustive list.

Eye-Rolling Acronyms​

DRY. SOLID. YAGNI. Some of these acronyms for engineering practices and principles are practiced dogmatically or dismissed entirely. Dismissal is becoming more prevalent these days.

I think many of these principles are still relevant and beneficial, even if one is heavily relying on AI generation, and these spur from our fundamental engineering senses.

A Sense of Organization​

Even if you aren't experienced as a coder, you have some sense of when you are poorly organized, physically or digitally. We learn to organize a room earlier in life on some level, and we also tend to learn lessons with digital organization when we lose or confuse important files for school or work.

Many of the classical engineering principles could be said to be practices of organization.

DRY (Don't Repeat Yourself) and the S in SOLID (Single Responsibility) are a couple of these, and they're closely related.

The DRY idea isn't and has never meant be "Any repetition is automatically bad," and Single Responsibility doesn't mean "Nothing can ever do more than one thing."

The real spirit of DRY is "Code becomes hard to keep track of when too many parts do the same thing," and an aspect of Single Responsibility is "When something has too different of jobs, it's hard to organize it properly."

If you have three copies of an essay for school in different folders on your computer, and you edit one on your USB drive, unplug it, forget you edited it there, then edit the copy in your Documents folder, save it, and then turn in a different copy in your Downloads that appeared when it was time to upload it, you already suffered from a lack of DRY.

Organization and AI​

When I engage with AI, I keep these principles in mind. I don't let it repeat code too much, because I see there's a good chance that it misses the fact there's repetition later. That chance grows as the code grows. This coincidentally is the same thing that happens to people who are working with code. I tend to refactor repeated code at the same timing that I would want if I was writing without any AI.

YAGNI (you aren't gonna need it) is a principle that counterbalances over-engineering by discouraging adding unnecessary features or designing features for complexity beyond what is practical. When one can't define a clear scope or purpose for AI's work, it can generate a lot of unnecessary code. That code then will get in its own way later, the same way it does for people. Having precise intent comes from engineering experience that can recognize when a feature is overkill.

An AI tool only works with so much context, just like us, and it never has a perfect memory or history of every engineering decision that you or it made. To me, it has appeared that no matter how smart any AI tool I've used gets, it benefits from the same things humans benefit from when it comes to code organization, and I have not yet experienced a lack of need for this organization to be driven by my own senses and am skeptical about that fundamentally changing.

A Sense of Clarity in Naming​

Naming has long been said to be one of the most difficult problems in coding.

This is because a good name succinctly describes what something is, but it strips away a massive amount of detail, only allowing a relatively short sequence of text characters.

If it's too vague, every time you see it, there are too many different things it could be. If it's more specific than what it really is, then it subtly hides aspects of itself. If it's inaccurate, it's inherently confusing.

You've probably experienced issues with naming in other areas of life. I once lived in a city where the electric company was called CPS, who show up on your doorstep with hats and name tags bearing this. It's not the best practice to use a name that is very easily confused with something of the same name without anything extra to qualify it. (Ever deal with the word "client" on its own in a coding context?)

Naming and AI​

This matters whether an AI or a human is reading code. This applies when prompting an AI as well, the same as it would confuse someone if you said "I want you to work on my project called My Cool API" that is actually a desktop GUI.

We are not at a point where 100% of code can be trusted blindly to AI, and I'm not going to try to predict a day where that becomes true. I also find it hard to believe that's coming as soon as some people say and in the form they describe it, and there's always the chance we're not really going to get there, just like how ANSI terminals still have not died for around 50 years. Regardless, right now and for probably longer than the biggest hype-drivers say, we're not there.

I had to code and debug bun-workspaces's fancy terminal output when running scripts in parallel mostly myself, because AI is not well-trained on making fancy terminal interfaces, and I found that any model I used was pretty terrible at debugging it, leaving most the real work to me.

This is an extreme example, but I often find that there are important features to write where I at least start them myself or work in hybrid with AI. That means that the names I decide really matter, because they signal intent to the AI like prompts themselves, again in the same way good names help humans understand and build on top of existing code, and the human element is far from irrelevant.

AI also uses a mix of the conventions it's been trained on. Without guiding it with naming conventions of my own, it will use a mix of them. That makes it difficult for me to debug and difficult for it to decide on its own patterns going forward. Naming consistency means that it has less friction on deciding names for itself and understanding existing names based on a pattern, which are, again, the same benefits people get.

A Sense of Fluency​

Coding, music, writing: All of these are essentially language skills.

After all, you could say language is a code rather than code is language, when talking about the general idea of code being simply a system of symbolic representation.

There have been studies like this one that have shown that language skills predict coding skills better than math skills.

If you've studied another language at all, you know you can feel a visceral difference between reading your main language and one you aren't as fluent in.

Fluency and AI​

At the moment, we're seeing that experienced engineers are the ones often benefitting from new AI development workflows the most.

If this is true, then the argument that fluency in code is no longer needed is backwards. The implication is that having what is sometimes being posited as "traditional" coding fluency is still a valuable thing to learn.

Before AI, I had already been engaging in code reviews and managing several growing projects at a time. Fluency was imperative because no one has time to deeply study the code they've already written or others wrote from the ground up constantly.

Now, I still need this fluency, maybe more than ever. Sometimes I focus it on tests. If AI creates a helper module for me, I want to be able to skim it and understand how it's working. If that module is too complex to fully process in my head, then that's where having tests, code comprised mostly of obvious "when this happens, then this should happen" statements using straightforward syntax becomes even more valuable. This then gives me a place in the code that is easier to read quickly with confidence to know that my project is still in good shape.

Conclusion​

I'm in no way trying to gatekeep people from coding with AI. I'm not saying you need to stop everything you're doing just to work on these fundamentals before you "earn" it. But I am saying that I strongly do not believe we're at a point where you can ignore them entirely, and because of the nature of fundamentals themselves, I find it hard to believe that they will actually ever truly go away without just taking some new form.

Fundamentally, git isn't complex because of the complexity of code but due to the complexity of versioning and collaborating with text-based projects. Text doesn't die because it's an extremely efficient, established means of communication that works well for both machines and people, which is part of why modern engineers are still are using software that looks and acts something like a virtualized 1978 computer console, because text input and text output have been and still remain king, whether it's terminal stdio, AI prompting, or sending stupid messages to your loved ones.

Historical Sources​

• Computer History Timeline
• The Whirlwind I
• The Flexowriter
• The VT100
• Bash's history
• Sheet music's history

bun-workspaces was in alpha for several months, and now version 1 is here! The package is officially at 1.1.2 at the time of writing.

Along with this first stable version is the first blog post! Let's take a walk through some of the core features of bun-workspaces, both its CLI and its TypeScript API.

Background​

Before diving directly into features, I'd like to give some background to the package first. You can skip forward to get right to how bun-workspaces works.

Fundamentals​

It's good to familiarize yourself with the basics of Bun's workspaces features. If you're coming from Node, Bun workspaces are extremely similar to npm workspaces.

The general idea is not very complicated: Normally you have one package in a git repo, defined by a package.json at the root. When using workspaces, you can nest any number of package.jsons in subdirectories in your project, with configuration for this in your root package.json.

These workspaces can import and export code between each other like local modules that are named by their package.json, acting like local node_modules. I have more about this in the documentation.

History​

Inspiration​

The inspiration for bun-workspaces comes from my experience working with TypeScript and monorepos in general. I've worked in setups where I was publishing private npm packages when I wished I had a monorepo, and I've worked in complex monorepo setups, such as managing microfrontends with Nx.

The bare-bones monorepo features of Node and Bun don't offer a lot in terms of features, but the alternatives are generally heavyweight frameworks that require a steep learning curve and complex configuration, like Nx.

For years, I've wanted to meet in the middle and have a monorepo power user layer that works in tandem with native workspaces, but I didn't get around to it while working previous jobs.

How It Started​

I originally created bun-workspaces to finally start a project that works with native workspaces, but it wasn't very serious and was mostly a workaround for a now irrelevant limitation of Bun's --filter feature at first.

But, I noticed that several developers liked the idea. The positive reactions I've received and the usefulness I've found for myself have now propelled the project forward from a tiny, slapped-together package with a basic CLI and README to the project you see now that has a well-tested CLI and TypeScript library, a full documentation website with an in-browser demo of the CLI, this blog, and more.

Going Forward​

I am just as much of a user or more than any of my current users, so I'm driven to keep adding functionality, with the hypothesis that a lot of monorepo frameworks' features can be achieved in a more lightweight package that works with, rather than against, native tooling.

I don't think well-automated monorepos are just for large enterprise projects, so I want there to be tooling that gives more accessible power to users that are solo, in smaller teams, or simply have projects that aren't worth a heavy framework.

You can see a more detailed roadmap here.

The Features​

The main documentation intends to provide the true exhaustive description of bun-workspaces's features, so I won't repeat everything here, but I would like to highlight some core features.

In general, you can say bun-workspaces has two main jobs:

• Getting metadata about a monorepo's workspace structure
• Running scripts across workspaces with advanced control, in parallel (by default) or sequentially

A CLI and API in Parity​

This package started out as only a CLI. The idea of shipping a TypeScript library (the API) along with the CLI sounded like a lot of extra work at first.

However, I had already designed CLI features to have strong CLI-agnostic code behind them, a good practice for any kind of interface, so I already almost had a TypeScript library. Making it public just meant taking extra care to its design and ensuring that it's documented.

Benefits​

This has become a great boon to the project, as it forces the core features to be designed strongly before thinking about the CLI, encourages another strong layer of testing to diagnose core logic issues separately from CLI issues, and allows users to choose either shell scripting or JavaScript/TypeScript scripting with first-class support to accomplish the same thing.

Comparison​

We can directly look at a shell script and a TypeScript script that perform essentially the same functions below:

CLI​

# A shell alias for simplicity
alias bw="bunx bun-workspaces"

# List workspaces
bw ls

# Get info about my-workspace in JSON format
bw info my-workspace --json --pretty

# Get same info using a configured alias (optional bw.workspace.json)
bw info my-alias --json --pretty

# Run the "lint" script in parallel across all workspaces
# and write a report to results.json
bw run lint --json-outfile=results.json

API​

import { createFileSystemProject } from "bun-workspaces";

// Initialize Project, by default at process.cwd()
const myProject = createFileSystemProject();

// List of Workspaces
const myWorkspaces = myProject.workspaces;

// Workspace aliases are validated to be unique from workspace names,
// so this is unambiguous
const myWorkspace = myProject.findWorkspaceByNameOrAlias("my-alias");

// Run the lint script in parallel across workspaces
const { output, summary } = myProject.runScriptAcrossWorkspaces({
  script: "lint",
});

for await(const { chunk, metadata } of output.text()){
  // console.log(chunk); // the output chunk's content (string)
  // console.log(metadata.streamName); // "stdout" or "stderr"
  // console.log(metadata.workspace); // the Workspace the output is from
}

// Object with details about exit results etc.
// This is the same data as the CLI's --json-outfile
const results = await summary;

See the full CLI docs and full API docs for more.

Aliases and Configuration Files​

Part of bun-workspaces's philosophy is to never require special configuration, since it can determine a project's structure simply from metadata available from Bun.

That being said, optional config can be used, such as to define aliases for workspaces, which can make it easier to reference a workspace with a long package.json name such as @my-organization/my-long-package-name.

These aliases can't clash with workspace names so that they can also unambiguously represent a workspace.

An example configuration file that might be at my-project/my-workspaces/bw.workspace.json:

{
  "alias": "my-alias"
}

You can read more about configuration here.

Workspace Patterns​

Workspaces can be filtered or selected for certain features using workspace patterns. You can read more about these here.

CLI​

# Filter the workspace list by patterns.
# This could be used to test patterns
# before using the run command.
#
# my-workspace may match a name or alias,
# while "my-pattern-*" matches by name pattern only.
#
# The "path:" specifier matches workspace directories
# relative to the project root via glob 
bw ls my-workspace "my-pattern-*" "path:my-glob/**/*"

# Run for workspaces that have my-script and match the patterns.
# You can see that it's still possible to match aliases by wildcard
bw run my-script "alias:my-alias-*" "path:my-glob/**/*"

# In general, any positional arguments for commands have 
# alternative flag options
bw run \
  --workspace-patterns="my-workspace path:my-glob/**/*" \
  --script="my-script"

API​

// Similar to listing by pattern via the CLI
const myWorkspaces = myProject.findWorkspacesByPattern(
  "my-workspace",
  "my-pattern-*",
  "path:my-glob/**/*"
);

// Same as the above CLI run command
const { output, summary } = myProject.runScriptAcrossWorkspaces({
  workspacePatterns: [
    "alias:my-alias-*",
    "path:my-glob/**/*"
  ],
  script: "my-script",
});

Inline Scripts via the Bun Shell​

Running scripts in bun-workspaces usually means running a command from the "scripts" in workspaces' respective package.jsons.

However, it's possible to also write "inline scripts," which are simply plain shell commands.

Bun created the Bun Shell as a cross-platform bash-like shell, and this turned about to be perfect for this feature.

The following code uses the Bun Shell to run the inline command in all workspaces, so its behavior should be consistent across all major operating systems:

CLI​

bw run "echo 'This is my inline script'" --inline

API​

myProject.runScriptAcrossWorkspaces({
  script: "echo 'This is my inline script'",
  inline: true
});

You aren't limited to only the Bun Shell but can also force the system shell, which is sh for Linux/macOS/WSL and cmd for Windows. You can read more on inline scripts here.

In Conclusion & The Future​

Above doesn't cover everything that bun-workspaces can currently do.

However, I realize that still many features should be added to satiate those users that are used to the heavier monorepo frameworks.

I'm one of those users myself, so I will be working continuously towards a more and more advanced feature set, without sacrificing the no-config easy entry that only requires a valid Bun monorepo.

Now that version 1 has solidified, I'm free to build on top of this foundation that has proven itself for the features thus far with little technical debt, and I will strive to keep about the same weekly release cadence that I've kept up for many months already.

Keep an eye out for new releases as I work on the roadmap, and consider subscribing to the blog at the top right of the page, as I will write new posts for big releases!