GIGABYTE Radeon RX 7700 XT GAMING OC 12GB GDDR6 Graphics Card

I ended up upgrading to a 9070xt for better 4k performance on the large TV, will post more details later, but in the meantime, you can buy the card on ebay!

About 3 days after writing this, Tanstack realeased a native preact tanstack query adapter! Just use that and ignore the rest. Thanks to everyone invovled in that.

• (@tanstack/preact-query)

Here is a simple approach to getting @tanstack/react-query working in a preact project. I’m certain I’m not the only person to arrive at this, but I also didn’t manage to find anyone suggesting this under the noise of your usual bundlerslop tutorials.

I’m intentionally trying to write this at more of a beginner’s level, so if anything is confusing, feel free to ask questions.

@tanstack/react-query internally imports and defines as a peerDependency react (meaning they need to be installed together in your project). When running a preact project, react generally shouldn’t be installed, so it will be missing, or auto-installed alongside @tanstack/react-query in newer versions of npm (we don’t want this!).

Package alias to the rescue

So the simplest solution here is to define react as a project dependency, next to @tanstack/react-query, and specify its version to a dependency override “package alias” pointing at @preact/compat:

# package.json
{
  "dependencies": {
    "@tanstack/react-query": "^5.90.20",
    "preact": "^10.27.0",
    # This swaps react for @preact/compat in node_modules!
    "react": "npm:@preact/compat@^18.3.1"
  } 
}

This tells npm, pnpm, etc to install @preact/compat inside the react directory in node_modules. Anything resolving react out of node_modules will instead import @preact/compat. Simple!

The advantage to this approach is ALL tools get the override, not just the frontend bundle.

If you do any kind of preact-render-to-string for SSR, or skeleton page generation or lightweight component testing inside of a Node.js process, things just work. The code you run through a bundler which sits on top of node_modules will inject the correct dependency, without any additional bundler config.

You don’t need to alias react-dom, unless something else is trying to import that. Typically, your DOM render function comes out of this package, but you are likely already using preact directly for this.

TanStack Getting Started (Preact edition)

After performing the above alias, the getting started TanStack example becomes:

// client.ts
import {
  useQuery,
  useMutation,
  useQueryClient,
  QueryClient,
  QueryClientProvider,
} from '@tanstack/react-query'
import { html } from 'htm/preact'
import { render } from 'preact'
import { getTodos, postTodo } from '../my-api'

// Create a client
const queryClient = new QueryClient()

export function App() {
  return html`
    <${QueryClientProvider} client=${queryClient}>
      <${Todos} />
    <//>
  `
}

function Todos() {
  // Access the client
  const queryClient = useQueryClient()

  // Queries
  const query = useQuery({ queryKey: ['todos'], queryFn: getTodos })

  // Mutations
  const mutation = useMutation({
    mutationFn: postTodo,
    onSuccess: () => {
      // Invalidate and refetch
      queryClient.invalidateQueries({ queryKey: ['todos'] })
    },
  })

  return html`
    <div>
      <ul>
        ${query.data?.map((todo) => html`
          <li key=${todo.id}>${todo.title}</li>
        `)}
      </ul>

      <button
        onClick=${() => {
          mutation.mutate({
            id: Date.now(),
            title: 'Do Laundry',
          })
        }}
      >
        Add Todo
      </button>
    </div>
  `
}

if (typeof window !== 'undefined') {
  const container = document.getElementById('root')
  if (container) {
    render(html`<${App} />`, container)
  }
}

If you wanted a separate Node.js entrypoint that ran preact-render-to-string you could then do:

// ssr
import { html } from 'htm/preact'
import { App } from './client.js'
import { render } from 'preact-render-to-string'

const out = render(html`<${App} />`)

Where this might not work

If you are importing a wide array of react components from npm, and any of them erroneously define a direct dependency on react, something else may download a second copy of react. react hates it when there is more than one copy of react in your bundle, so if you find yourself in this case, you may need to introduce bundler config to solve that. The more general package manager override directives might also work if you have transitive copies of react you want to hammer out, however these are specific to the package manager you use (npm, pnpm etc).

If you rely heavily on jsx but still hope to directly run your .tsx/.jsx through node, you will also need to find a solution to do that, or use something like htm if you want to avoid that problem altogether.

I’m running the latest Steam OS 3.7 (the OS running on the Steam Deck) on conventional AMD desktop hardware, running at equal or improved performance over Windows.

We’re here! You can just build a Steam Machine now, and get a console-like experience running PC games in your living room, on Linux, with great controllers, on your 4K OLED TV (and surround sound if you have it), running in parity with your Steam Deck.

The OS (SteamOS 3.7)

The OS to install is SteamOS 3.7. It’s available in Valve’s “preview” update channel for the Steam Deck, but you can download the recovery image and try installing it on anything.

There isn’t much more to say about this, other than yes, the rumors that Valve is expanding hardware support are true. It works on a lot more devices now, including conventional AMD desktop hardware.

If you are interested in the details on installing not-quite-released software, read:

• It’s time to install SteamOS 3.7

Prior to updating to SteamOS 3.7, I ran SteamFork, and before that, Chimera OS. SteamFork (the project) has thrown in the towel, and Chimera OS remains a great option. If SteamOS 3.7 isn’t quite working for your hardware yet, read about other similar projects that are helping bridge the compatibility gaps:

• “Bazzite isn’t SteamOS (and that’s okay!)”

The Hardware

I targeted a budget of $1500 for the core hardware. Final cost came to $1799.71. Part lists go stale REALLY quickly, but if you want to build exactly what I have, here is the list. I wrote up the build on PCPartPicker too, but hey—feel free to use my referral links if you found this useful:

• CPU: AMD Ryzen 7 7800X3D
• Cooler: Noctua NH-L12S (Run this CPU fan in this case unless you have a good reason not to)
• Motherboard: ASUS ROG Strix B650E-I
• RAM: G.SKILL Flare X5 Series (AMD Expo) DDR5 32GB (Use RAM matching tools)
• NVMe: WD_BLACK 2TB SN850X (Avoid low-end Samsung Gen5s)
• GPU: GIGABYTE Radeon RX 7700 XT (Go better here if you increase on anything)
• Case: Fractal Design Ridge
• PSU: CORSAIR SF750 (Avoid bulky, cheaper SFX-L PSUs in this case)
• Case Fans: 4 × Noctua NF-A6x25
• Top Fans: 3 × ARCTIC P8 Slim PWM
• Fan Hub: Noctua NA-FH1, 8 Channel Fan Hub
• WiFi Antennas (I don’t have Ethernet near my TV)
• Left Angle IEC C14 to C13 Power Adapter (Helpful to turn the power cable on the Ridge case)

The controllers

Finding good controllers has been a challenge. It needs to be on par with the Steam Deck controller, but unfortunately, nothing on the market matches that. Skipping a lot of nuance and details, the Steam Controller, DualSense Edge, and an HTPC keyboard have covered all my needs. Finding decent controllers that work well enough for PC games on the couch has been difficult, and I intend to write more about each one I’ve tried.

It’s surprising and hard to explain to people unfamiliar with the issue just how important of a development Gyro Aim is. This thesis is required watching if you haven’t had hands-on time with a Gyro input:

The only controller that comes close to what is offered by the Steam Deck controls is the DualSense Edge (unfortunately!). It’s a great controller, with Gyro, paddles, and a trackpad, and has high-end OEM quality, but it’s the most expensive controller on the market—and Bluetooth only (among other flaws).

Speaking of Bluetooth, I recommend getting an extended range dongle and ensuring your controller has line of sight to it. Latency-sensitive controls like Gyro need a solid connection, and I found that without line of sight, signal drops off around 6 feet. With line of sight, controllers work great—even at 10 feet.

The Steam Controller is nice to have. Probably not worth paying scalper prices for it these days, but if you still have yours lying around, get that thing going again. They work better than you remember and have a 2.4GHz dongle!

Any HTPC keyboard-mouse combo works. You mainly use it for one-off tasks where the on-screen keyboard is too cumbersome, and it mostly lives in the closet. I recommend the Logitech K400 Plus over the no-name Chinese Amazon ones, having tried both.

• PlayStation DualSense Edge Wireless Controller
• PlayStation DualSense Charging Station
• PlayStation DualSense Edge Stick Module – Pick some up before they go dead-stock pricing.
• TP-Link USB Bluetooth Adapter for PC, Bluetooth 5.3 Long Range Receiver
• Logitech K400 Plus Wireless Touch TV Keyboard
• Steam Controller (RIP)

The Screen

Whatever TV you have will work. Playing on a large 4K HDR OLED TV has been a real joy, and it’s easy to forget how many pixels are in these things. Just don’t forget to put it into game mode. I would also note—if you can, avoid Android TV, and definitely disconnect the smart features from any network connection.

The Audio

I can’t run surround in my current living room, so in the meantime, I run AirPods Max—mainly because they have the best audio sharing feature on the Apple TV. They work well with the Steam Machine though.

Build notes

Building in the Fractal Ridge was super easy, but seeing how other builds tackled little issues in the small case was helpful. Here are the builds I found most useful as a reference:

• Fractal Design Ridge full of Noctua fans feat. delidded 7800X3D and deshrouded RTX 4080
• ITX laptop destroyer
• All Fractal Ridge Completed Builds

Other notes

If you are familiar with the Steam Deck, you will feel comfortable with a Steam Machine. They are basically the same!

The following are helpful resources when trying to run games on it:

• ProtonDB – Compatibility reports for games running on Linux in Proton. Any Deck Verified game will also run great.
• Are We Anti-Cheat Yet? – If you must play multiplayer with cheating competitors who require kernel modules to stop them, you will run into some compatibility issues versus Windows. This site tracks those.
• GamingOnLinux – This has consistently been the best news site focusing on gaming on Linux.
  • GoL AntiCheat Tracker - GoL also has it’s own excellet data on Linux anti-cheat stats.
• SteamDB – General player and game price tracking on Steam.
• /r/GyroGaming/ – The GyroGaming subreddit can often be helpful when figuring out gyro on games with poor mouse and controller inputs.
• /r/SteamDeck/ - The SteamDeck subreddit is also a decent source of news fore SteamOS related info.

If you end up building a Steam Machine or something similar, please share your results! If you want to chat or ask more questions about the process, you can join the former SteamFork Discord, where there are still a bunch of users of SteamFork migrating to SteamOS and facing similar issues and questions.

Updates

• Josh Nichols wrote up his Steam Machine build with great photos and information. Check it out!

Syndications

• /r/SteamDeck
• X
• fosstodon
• https://bsky.app/profile/bret.io/post/3lopj5jivd22a

Installing SteamOS 3.7

(This will go stale quickly, but as of this writing, it works.)

• EDIT 3: A New SteamOS Home Page has been released echoing most of the information written here.
• EDIT 2: 3.7 Has been released to the stable channel. Running updates on the stable channel will get you to a working state.
• EDIT 1: As of writing this, 3.7 has been promoted to BETA, so check the system version you get on the hop to Beta. If you get to 3.7, you are good to go!

Prep Tips

• The recovery image installs SteamOS 3.5 3.7 or later. Descrete GPUs just work now.
• SteamOS 3.5 has limited hardware support. On desktop systems, enable integrated graphics and plug your monitor directly into the integrated HDMI or DisplayPort during installation.
• Some discrete GPUs I tested failed to boot SteamOS 3.5. I don’t recommend trying them. Use iGPUs for the initial install, then switch back to a discrete GPU once you’re on 3.7.

Procedure

• Download the Steam Deck Recovery Image from: https://help.steampowered.com/en/faqs/view/1b71-edf2-eb6d-2bb3
• Flash the recovery image to a USB drive.
• Boot the USB drive on your “Steam Machine” and “re-flash” your “Deck”—i.e., whatever hardware manages to boot the recovery image.
• It flashes the primary NVMe drive, deleting everything on it. Be careful!
• After flashing, reboot, remove the USB drive, and sign in.
• In system settings, run updates on the stable channel to update to SteamOS 3.7 or later. You can also test the Beta and Preview channels if you wish.
• Congrats! You’re now running SteamOS 3.7.
• Head back into your BIOS, disable integrated graphics, and test your discrete GPU. It will probably work now!
• SteamOS 3.7 should now be running on your hardware of choice!

Why SteamOS Now?

It’s been rumored for a while that SteamOS—the Arch-based Linux distro powering the Steam Deck—is moving toward becoming a general-purpose Linux OS for any device.

I tried installing SteamOS on conventional hardware a few months ago without much success:

• It wouldn’t boot without integrated graphics.
• There was lots of Steam Deck jank—rotated console output, ugly boot logs, etc.
• Performance was bad, and games didn’t launch correctly.

But recent announcements have focused on handhelds like the Lenovo Legion Go S. Still, it’s clear that the preview channel for SteamOS now supports conventional hardware much better than before.

From testing in the SteamFork community, it’s clear that running “vanilla” SteamOS is now viable for a lot of hardware—especially AMD desktop builds. You should definitely give it a shot.

What If I Can’t Boot the Repair Image?

If the repair image won’t boot, you could try flashing one of the other SteamOS images directly to your boot disk, or experiment with one of the newer, unreleased repair images. If you do, please share your notes on what worked or didn’t!

• All SteamOS ISO Images
• Steam Repair Image (Current)
• Unstable Repair Image - steamdeck-repair-20250320.1000-3.8.0.img.zip

Come Chat

If you’re running SteamOS on non–Steam Deck hardware, join the SteamFork (RIP) Discord to chat about your setup and share notes!

SteamOS, being a Linux distro, is no different. There are quite a few things being called “SteamOS” these days in YouTube tutorials, so I figured I could help clear things up.

graph TD
  SteamOSDebian["🎮 SteamOS (Debian)"]
  SteamOSArch["🎮 SteamOS (Arch)"]

  SteamFork["🛠️ SteamFork"]
  HoloISO["🌈 HoloISO"]
  ChimeraOS["🔥 ChimeraOS"]
  Bazzite["🔧 Bazzite"]

  SteamOSDebian
  SteamOSArch <-->|derived from| SteamFork
  SteamOSArch <-->|derived from| HoloISO

  ChimeraOS <-.->|pulls from| SteamOSArch
  Bazzite <-.->|pulls from| SteamOSArch

Valve’s Recovery Image is “SteamOS”

SteamOS has been around for a while—so much so that there are two distinct versions of it.

• Valve’s original Debian-based “SteamOS” that shipped with the Alienware Steam Machines.

• The Arch-based “Steam Deck Recovery image” that ships Gamescope and Valve’s latest 10-foot UI.

The modern Deck Recovery Image isn’t quite ready for prime time, but it’s totally usable on a lot of hardware (in the preview 3.7 branch).

If you aren’t running one of these, you aren’t “running SteamOS”!

SteamOS Derivatives

There have been two known SteamOS derivative distributions: HoloISO and SteamFork.

A derivative distribution directly takes Valve’s SteamOS and other sources as a base and builds from there. This guarantees they track SteamOS as closely as possible while layering on their own fixes or hardware compatibility support.

Both HoloISO and SteamFork are now discontinued (though you can still run them):

• HoloISO was run out of a Russian Telegram channel and had questionable build/distribution practices. It was hard to verify that it wasn’t distributing malware. While I don’t think it ever did, the project wasn’t transparent or easy to contribute to, and the maintainer was a college student who would disappear regularly.

• SteamFork was a US-based project that was fully open source on GitHub. It had a reproducible toolchain, real build infrastructure, and was run much more professionally. It produced a very high-quality SteamOS derivative that supported both desktop hardware and a wide variety of handhelds.

In the end, I agree with the SteamFork maintainers: the Chinese handheld vendors should be the ones footing the bill for SteamOS support—not the community. The decision to shut down, while disappointing, makes complete sense. SteamOS 3.7 is basically here—let’s use it.

Credit to the SteamFork team (@uejji and @fewtarius) for their beautiful build pipeline and for sharing their discoveries around SteamOS 3.7.

If you are running a SteamOS derivative, you’re nearly running SteamOS that differs only to the extent the patches change it.

Gamescope Distros

The two other notable distros I see frequently labeled as “SteamOS” in the ecosystem are: ChimeraOS and Bazzite.

ChimeraOS and Bazzite are not SteamOS.

They’re both excellent choices if SteamOS doesn’t run on your hardware, or if you prefer their broader project goals. They boot into Gamescope and use Proton for game compatibility.

Gamescope: the micro-compositor formerly known as steamcompmgr

Gamescope is the layer that the Steam 10-foot UI and games run inside on Linux. It handles resolution scaling, performance overlays, FSR upscaling, and other key features made popular by the Steam Deck.

We’ll call non-SteamOS-derivative distros that boot into Gamescope “Gamescope distros.”

ChimeraOS

Chimera is a great project that predates modern SteamOS. It’s an immutable Linux distribution built to provide a console-like experience across many devices.

It’s Arch-based like SteamOS, but it uses GNOME for desktop mode instead of KDE. It also runs its own update schedule, separate from Valve or the broader SteamOS ecosystem. It ships its own 10-foot UI, emulation support, and web-based management tools.

If SteamOS 3.7 or SteamFork doesn’t work for your device—or if you prefer Chimera’s vision and community—this is a solid choice.

Bazzite

I haven’t used Bazzite personally, but like Chimera, it’s not a SteamOS derivative. It boots into Gamescope and feels a lot like SteamOS.

Bazzite is based on Fedora and makes heavy use of process containers, which makes it even more distinct from SteamOS.

It’s very popular on Reddit, has strong community support, and offers good hardware compatibility. However, because it’s Fedora-based, you’ll encounter many differences when tinkering under the hood. If you like Arch Linux (or want to learn more about it), you may find Fedora-specific quirks frustrating.

If you’re using a Gamescope distro, you are not running SteamOS. You’re running a separate Linux distro with its own lineage that borrows components from SteamOS to work similarly.

“This doesn’t matter—the outcome is the same!”

Yes and no. While the direction is similar, details matter in open source. Different starting points create different outcomes, even if the UX looks the same. I’m not here to say x is better than y—just that x is not y. Saying you run x when you actually run y is misleading or mistaken.

Welcome to open source!

The point here is to highlight the differences and help you understand when those details might matter. In many cases, they won’t.

“Which one are you saying I should run?”

Try them all! See what works best for your goals and your hardware.

Conclusion

If you enjoyed this post, you might also like:

• You can just build a Steam Machine — A look at building a “Steam Machine” with SteamOS
• It’s time to install SteamOS 3.7 — My notes on installing SteamOS on non–Steam Deck hardware

I’m primarily talking about JS-based “monorepos,” a.k.a. workspaces when used in open source packages, but the whole space is confused enough that I might stray a bit.

Historical Context

JS monorepos (or “workspaces”) emerged with tools like lerna, later influencing similar features in npm, yarn and pnpm. At their core, they allow developers to:

• Develop and publish multiple npm packages from a single git repository
• Streamline dependency management with automatic linking and consolidated lockfiles
• Allow for varying direct dependency versions in a single repo

This approach gained popularity largely as a response to:

• The frustrating fragility of npm link
• React’s “unique” constraints that caused errors when linked across packages
• The exponential growth of tooling complexity costs (Babel, Webpack, CSS-in-JS, TS)
• The promise of O(1) tooling changes instead of O(n²) updates across multiple repositories

What I Love About Monorepos

Monorepos have utility in some circumstances.

Monorepos are ideal for scenarios like this: a project with a series of APIs, a website, and background worker processes where a team of developers works on the codebase together Each process has its own set of unique and shared dependencies, and also has a set of common queries and types shared between two or more services. The primary trade-off of course is that any changes to shared code has to be reflected in all dependents at the time of introduction.

Outside of this context, it’s mostly just misery for dependents and contributors.

All the Ways Monorepos (and Adjacent Hypertooling) Are Annoying

Most of the issues stem from “hypertooling”, a generally bigger issue in all development ecosystems, but they manifest at scale in the monorepo arrangement, so it’s a useful vehicle to point out these issues.

“Let Me Just Fix This Little Bug”

You’re using a dependency in your project. That dependency has a bug, and you need to fix it. Node.js was designed with the intention that you could just open up node_modules and edit the code to generate patches.

With packages sourced from monorepos, this is not the case!

You open up the code in node_modules now, and it’s some franken-compile-to-es-1-ts-rollupviteparcel-webpack-babeldegook-lerna-pnpm-berry-workzone-playplace that has also been pre-minified for some reason. Also the sourcemaps and ESM type exports are broken for some reason.

Packages Published from Monorepos Have More Bugs

This is completely anecdotal but also completely true. Packages published from monorepos have more defects, and finding and fixing the defects is more challenging for dependents. I believe this is due to two factors:

• The development environment (the monorepo) varies more from the deployment environment (node_modules/foo) than single repo = single package project organization.
• The developer who is prioritizing the monorepo DX over the consumption DX, has gone out of their way to avoid working in the deployment environment, and therefore fails to test things in realistic deployments.

These two factors, plus the inherent complexity of all the tools required to make monorepos work, lead to encountering more defects in monorepo-published packages.

Also, trying to fix or upstream work to monorepo packages is memorably more miserable and painful.

This really comes down to thermodynamics—more entropy, more problems—and it’s true!

Finding the Source Code to Fix Is a Lot Harder

Noodling around on your machine-generated direct runtime dependencies in node_modules may still be possible, and you may even identify a quick fix you want to upstream, but now you’re tasked with actually finding the source code. This leads to many additional challenges in monorepos!

Package Metadata Is Often Stripped from package.json

Because you can’t simply publish packages from a monorepo without a mountain of scripts and tooling, monorepo-sourced packages often rewrite package.json (we have to differentiate which package.json we’re talking about in a monorepo!) in a way that accidentally (or intentionally, for devs who prefer to move a bespoke minification step into the npm publish lifecycle for no stated reason) strips useful and important metadata.

Package Metadata Is Often Wrong or Incomplete

Okay, so we’re lucky—this monorepo-published package has some metadata about the repo that created it. But it only takes us to the repo homepage. Now we have to find out if the package name matches the directory name used in the monorepo or how this thing is put together at all to hunt down the source code of the package.

They probably don’t have a README.md

The package probably has a super sub-par README.md or something that points to some random permutation of a (probably incomplete) docs website (that will go offline when the maintainer gets busy and forgets to renew the domain). If you are lucky you might get a generated typedoc website (good), but with zero JSDoc description annotations (the part that describes things for humans) (bad).

Obviously, nothing in monorepos requires this to be the case, but the tools seem to facilitate this outcome.

Each Monorepo Is a Unique Permutation of Opinion and Entropy

Because there are always weird variations on which tool is used and how, finding the package entry point becomes a chore. It’s hard to do on GitHub, and you basically have to clone the package and grep around, comparing the source code to try and find where the contents of the package tarball match up.

Which Package Manager Are They Using for the Monorepo?

Okay, so the package itself has no hard requirements on which package manager you use, but the monorepo only works with pnpm. No, wait, it requires yarn. Oh, wait, not Yarn 1—why is that still the default? It needs Berry. Why does this repo have more than one lockfile?!? Oh crap, what is corepack, do I need that?

Now You Have to Install More Tools

corepack, yarn, berry, pnpm, lerna, volta, turborepo, nx, etc., etc., etc…

By the way, Node.js ships with npm. It literally could be that easy—this is all opt-in hypertooling.

No One Uses the Standard Node.js Tooling (npm Workspaces)

npm ships workspaces. Nothing uses them. To their credit, npm workspaces leave a lot to be desired. Tools that support workspaces will often only work with lerna 1 workspaces or something like that, not npm workspaces for some reason. Sad situation.

The Monorepo Install Step Will Probably Fail

Because you have to install dependencies for N packages instead of 1 in a monorepo, and the chances of a monorepo dev running Gentoo or nix or something elite and weird are much higher than normal, don’t expect this to work on your machine. The external native dependencies are probably not documented anywhere, or buried in a README in one of the packages.!

Remember, at scale, rare events become common! More dependencies, more places to break.

The Tests Aren’t Passing Locally

We got through the install step. We had to switch Node versions or install pkgconfig or something. We go to land our patch, but before we do, we run yarn test. The tests fail! Not on the package we want to work on, but somewhere else.

Now we get to look into how to narrow the test harness and see if the relevant suite works or not, or just submit the patch and hope it works in CI.

The Tests Aren’t Passing in CI

We submit the PR upstream, and CI fails—again, for the same unrelated package that we saw locally. I’m not here for that, and fixing it looks hairy. The maintainer merges your changes anyway. Oof. Let’s hope they have it under control despite appearances.

Isolated changes aren’t actually isolated at all in monorepos. They end up requiring the whole suite to pass. Depending on the nature of your contribution, it may come down to you to look into why something stopped working, unrelated to the task at hand.

All of the Devtools Fall Over

The scale of monorepos will often far exceed the performance envelope that the devtools were targeting (small to medium-sized repos). JS and TS require dev tooling. JS requires a parsing linter to catch well-known but easy-to-miss language hazards. TS requires tools to type-check and build.

These tools operate fine at a specific range of scale and get extremely slow and crappy beyond that scale. Monorepos are an excellent pattern to follow if you want to exceed that scale quickly.

Needs Everything Rewritten in Rust

A big part of the effort to rewrite everything in Rust is because the JS-based tooling isn’t fast enough for the size of the monorepos people throw them at. But also, people are just sick of the mess they’ve been a part of and want to hop ecosystems. Many monorepos are quick to adopt Rust-based tools, along with all of their fresh bugs and defects.

It’s a good time to remind people that tools like the SASS compiler used to be written in C++ to be fast. We’ve been here before!

They Need VSCode Plugins

Many monorepos assume and encourage people to not only install devDependencies but also VSCode plugins to work effectively in them. No, it’s not available in Vim or Sublime or any other editors. What, you don’t use VSCode?!

Monorepo Tooling Falls Out of Date Quickly

Maybe this is getting better these days, but why do I keep running into Yarn 1 and Lerna everywhere still?

Because any singular tooling change in a monorepo has to cover the workflow for N packages, it forces you to address any changes in ALL packages when making tooling updates. This often leads to it never happening.

Remember the argument that monorepos promised O(1) tooling changes? Well, that one change can’t go in until N packages (* N times you have to make updates) are modified to work with that change. This distinction is always overlooked. Centralizing tooling means every change requires mass coordination. If each package were in its own repo, you could selectively apply the tooling changes to the 2-3 you are actively working on and get around to the rest when it matters.

They Ship Hoisting Bugs

Hoisting bugs are more common in monorepos and are easily captured in lockfiles, where they can’t be reproduced by dependents. Why install any dependencies when you can assume your peers have them?!?

pnpm forces you to fix these—great—but pnpm doesn’t ship with Node, so only a fraction of monorepos address this.

Versioning and Publishing Hazards

Monorepos inadvertently create several versioning challenges that single-package repos typically don’t encounter:

• Overactive Versioning: Tooling automatically bumps multiple packages simultaneously, leading to unnecessary version noise for downstream dependents.

• Hazardous Permutations: When packages are published in groups but updated selectively by dependents, untested version permutations emerge—especially problematic with peer dependencies.

• Partial Publishes: Complex automations sometimes only publish a portion of interdependent changes, creating temporarily broken package states.

• Cross-Module Side Effects: Changes in unrelated modules in monorepos can introduce defects in the modules you depend on, something far less likely with separate repositories.

Overmodularized internals

Overmodularizing (adding versioned module boundaries between code where just a separate file or export in the same module would do) is a hazard in general, but it seems to often be worse in monorepos. This tends to be a mistake you see less experienced developers make, but monorepos deserve unique recognition here: by lowering the spin-up cost of modules, monorepos make this mistake easier and more common.

Probably overusing peerDependencies

I actually don’t understand this one, but modules out of monorepos tend to heavily utilize peer dependencies, where regular dependencies would actually be preferable. I suspect its some frontend bundler need that somehow has leaked into the Node.js module graph but I haven’t ever gotten an answer that makes sense on this one.

Monorepos Break GitHub and Tooling

Because N projects run out of one repo, the entire GitHub resource model (One project = one repo) is made largely useless. Issues, CI, and permissions now have to scale down to the folder level instead of hanging off the repo resource boundary. This has incredible implementation costs for the entire tooling ecosystem as they attempt to accommodate large monorepos.

Most tools just simply fail to work by default in the monorepo arrangement because your monorepo is unique and bespoke compared to all the others. Because of its sheer size, tools have to implement complex scaling solutions just to listen to webhooks off monorepos. It really sucks.

“But Google Does It!”

This comparison fundamentally misunderstands Google’s approach. Google doesn’t use JS-based workspaces or monorepos in their organization (at least in the example everyone’s reaching for)—they’ve built custom tooling with dedicated engineering teams specifically to make their monorepo approach viable at their scale.

Google has invested millions in proprietary build systems and infrastructure that most teams simply don’t have access to. The contexts are so different that the comparison provides little practical value for most JavaScript projects.

Your startup or open-source project operates under completely different constraints and with different goals than Google’s engineering organization, on top of the fact Google isn’t really a great company to emulate these days.

“But npm link Sucks”

“I don’t want to link 2+ repos together locally.”

This is a legitimate pain point—npm link becomes tedious and fragile beyond a single layer of linking. However, this limitation actually encourages better architectural decisions about module boundaries and dependencies.

The core issue isn’t that npm link is flawed; it’s that we’re often creating unnecessary dependencies between packages that could be designed with cleaner separation. When packages are truly independent enough to warrant separate publishing, they should rarely need simultaneous development.

For general-purpose libraries especially, isolating code into separate repositories with well-defined boundaries often leads to better design decisions and more maintainable code over time. Reaching for monorepos to avoid these challenges can sometimes mask architectural problems rather than solve them.

That said, every project has unique requirements—if yours genuinely benefits from the tight coupling a monorepo enables, that’s a valid choice. The key is making that decision deliberately rather than defaulting to it out of convenience.

“But Small Modules Are Annoying”

Monorepos and many/deep module graphs are pretty orthogonal, but I have heard this argument a few times. The idea is that it’s okay to have many dependencies sourced from the same repo—this is better than having them sourced from many repos. Okay, sure, as long as you can live with the above issues!

If all those repos are owned by the same person, I don’t really see the issue.

Generally though, small modules aren’t annoying because they live in a singularly scoped repo, (they are annoying because their they lack API depth). Annoying modules are annoying Get rid of your annoying dependencies, and cross your fingers the replacement is less annoying.

“All of These Problems Apply to Single-Package Repos Too!”

A lot of the above problems are just hazards with the Node module system. Yes, you can run into a lot of the same issues with single-package repos. But in practice, you don’t. Monorepos act as a multiplier on these hazards on top of their own set of issues.

“[Insert New Runtime] Fixes This!”

Give any JS ecosystem incumbent some time in the spotlight, and you will be surprised at the “wild” ideas people will come up with to make peoples lives more complicated!

“I’m an overworked, underpaid maintainer, I need this”

This is probably true. Do whatever you need. Just enumerating a few common hazards to avoid.

“You or someone should write up single package repo hazards”

Yeah Agreed. Single module repo strategies are sadly very underdeveloped and misunderstood.

Conclusion

Monorepos have legitimate uses in specific contexts—particularly when sharing code between multiple processes in a single project or coordinating work across closely related sub-projects and teams. In these situations, they can remove barriers to a developer workflow that would otherwise be necessary in open source.

But for open-source modules, the costs often outweigh the benefits and are actually creating a reputational hazard for an otherwise completely functional and scalable module system. Instead of defaulting to monorepos, consider these alternatives:

• Focused Single-Package Repos: For libraries with a clear, cohesive purpose, maintaining separate repositories provides cleaner boundaries and more reliable publishing workflows.

• Minimal Dependencies: Rather than splitting functionality across numerous tiny packages that require a monorepo to manage, consider whether your design truly benefits from such granular separation.

• Strategic Module Boundaries: Create module boundaries only where they provide genuine benefits—at natural seams in your architecture rather than arbitrary divisions. Frequent cross boundary linking indicates unnecessary boundaries.

The JavaScript ecosystem moves quickly, but we should be careful not to adopt complex solutions for problems that could be solved more elegantly with simpler approaches. Sometimes the answer isn’t more tooling or more packages—it’s thoughtful design and careful consideration of the downstream experience.

Monorepos aren’t inherently bad, but they’re also not a silver bullet. Understanding when they help and when they hinder is key to using them effectively.

Syndications

• Hacker News
• Bsky:bret.io
• Bsky:ECMASCript.news
• X:@bcomnes
• Mastodon:@bcomnes
• Mastodon:@ecmascript_news
• reddit.com/r/node
• ecmascript.news 2025-03-12

“Don’t be evil” paired with the companies premise: lets build products in a way that allows for immeasurable corporate access into people’s private lives for fun and profit, unlocking all the positive potential this data can provide. We’ll only use it for good, the Evil™️ things will just be off limits.

Of course the motto changes to “Do the right thing” in 2015 when it’s very obvious it’s impossible Google to not indulge in the Evil with the potential for it sitting right there. By loosening up the motto to allow for at least some Evil, so long as its the “right thing”, Google can at least be honest with the public that “Evil” is definitely on the table.

Maybe its time to demand “Can’t be evil”? Build in a way where the evil just isn’t possible. Reject the possibility of evil in what software you choose to use.

Richard Hamming’s “The Art of Doing Science and Engineering” is a book capturing the lessons he taught in a course he gave at the U.S. Navy Postgraduate School in Monterey, CA. He characterizes what he was trying to teach was “style” of thinking in science and engineering.

Having a physics degree myself, and also finding myself periodically ruminating on the agony of professional software development and hoping to find some overlap between my professional field and Hamming’s life experience, I gave it a read.

The book is filled with nuggets of wisdom and illustrates a career of move-the-needle science and engineering at Bell Labs. I didn’t personally find much value in many of the algebraic walk-through’s of various topics like information theory, but learning about how Hamming discovered error correcting codes definitely was interesting and worth a read.

The highlight of book comes in the second half where he includes interesting stories, analogies and observations on nearly every page. Below are my highlights I pulled while reading.

On What Makes Good Design

That brings up another point, which is now well recognized in software for computers but which applies to hardware too. Things change so fast that part of the system design problem is that the system will be constantly upgraded in ways you do not now know in any detail! Flexibility must be part of the modern design of things and processes. Flexibility built into the design means not only will you be better able to handle the changes which will come after installation, but it also contributes to your own work as the small changes which inevitably arise both in the later stages of design and in the field installation of the system…

Thus rule two:

Part of systems engineering design is to prepare for changes so they can be gracefully made and still not degrade the other parts.

– p.367

This quote is my favorite out of the entire book. It feels like a constant fight in software engineering between the impulse to lock down runtime versions, specific dependency versions, and other environmental factors versus developing software in such a way that accommodates wide variance in all of these different component factors. Both approaches argue reliability and flexibility, however which approach actually tests for it?

In my experience, the tighter the runtime dependency specifications, the faster fragility spreads, and it’s satisfying to hear Hamming’s experience echo this observation. Sadly though, his observation that those writing software will universally understand this simply hasn’t held up.

Good design protects you from the need for too many highly accurate components in the system. But such design principals are still, to this date, ill understood and need to be researched extensively. Not that good designers do not understand this intuitively, merely it is not easily incorporated into the design methods you were thought in school.

Good minds are still needed in spite of all the computing tools we have developed. The best mind will be the one who gets the principle into the design methods taught so it will be automatically available for lesser minds!.

– p.268

Here Hamming is describing H.S. Black’s feedback circuit’s tolerance for low accuracy components as what constitutes good design. I agree! Technology that works at any scale, made out of commodity parts with minimal runtime requirements tends to be what is most useful across the longest amount of time.

On Committees

Committee decisions, which tend to diffuse responsibility, are seldom the best in practice—most of the time they represent a compromise which has none of the virtues of any path and tends to end in mediocrity.

– p.274

I appreciated his observations on committees, and their tendency to launder responsibility. They serve a purpose, but its important to understand their nature.

On Data and Observation

The Hawthorne effect strongly suggests the proper teaching method will always to be in a state of experimental change, and it hardly matters just what is done; all that matters is both the professor and the students believe in the change.

– p.288

It has been my experience, as well as the experience of many others who have looked, that data is generally much less accurate than it is advertised to be. This is not a trivial point—we depend on initial data for many decisions, as well as for the input data for simulations which result in decisions.

– p.345

Averages are meaningful for homogeneous groups (homogeneous with respect to the actions that may later be taken), but for diverse groups averages are often meaningless. As earlier remarked, the average adult has one breast and one testicle, but that does not represent the average person in our society.

– p.356

You may think the title means that if you measure accurately you will get an accurate measurement, and if not then not, but it refers to a much more subtle thing—the way you choose to measure things controls to a large extent what happens. I repeat the story Eddington told about the fishermen who went fishing with a net. They examined the size of the fish they caught and concluded there was a minimum size to the fish in the sea. The instrument you use clearly affects what you see.

– p.373

Intuitively I think many people who attempt to measure anything understand that their approach reflects in the results to some degree. I hadn’t heard of the Hawthorne effect before, but intuitively it makes sense.

People with an idea on how to improve something implement their idea and it works, because they want it to work and allow the effects to be fully effective. Someone else is prescribed this idea or brought into the fold where the idea is implemented and the benefits of the idea evaporate.

I’ve long suspected that in the context of professional software development, where highly unscrutinized benchmarks and soft data are the norm, people start with an opinion or theory and work back to data that supports it. Could it just be that people need to believe that working in a certain way is necessary for them to work optimally? Could it be “data” is often just a work function used to out maneuver competing ideas?

Anyway, just another thing to factor for when data is plopped in your lap.

On Theory

Moral: there need not be a unique form of a theory to account for a body of observations; instead, two rather different-looking theories can agree on all the predicted details. You cannot go from a body of data to a unique theory! I noted this in the last chapter.

–p.314

Heisenberg derived the uncertainty principle that conjugate variables, meaning Fourier transforms, obeyed a condition in which the product of the uncertainties of the two had to exceed a fixed number, involving Planck’s constant. I earlier commented, Chapter 17, this is a theorem in Fourier transforms-any linear theory must have a corresponding uncertainty principle, but among physicists it is still widely regarded as a physical effect from nature rather than a mathematical effect of the model.

–p.316

I appreciate Hamming suggesting that some of our understanding of physical reality could be a byproduct of the model being used to describe it. It’s not exactly examined closely in undergraduate or graduate quantum mechanics, and I find it interesting Hamming, who’s clearly highly intuitive with modeling, also raises this question.

Predictions

Let me now turn to predictions of the immediate future. It is fairly clear that in time “drop lines” from the street to the house (they may actually be buried, but will probably still be called “drop lines”) will be fiber optics. Once a fiber-optic wire is installed, then potentially you have available almost all the information you could possibly want, including TV and radio, and possibly newspaper articles selected according to your interest profile (you pay the printing bill which occurs in your own house). There would be no need for separate information channels most of the time. At your end of the fiber there are one or more digital filters. Which channel you want, the phone, radio, or TV, can be selected by you much as you do now, and the channel is determined by the numbers put into the digital filter-thus the same filter can be multipurpose, if you wish. You will need one filter for each channel you wish to use at the same time (though it is possible a single time-sharing filter would be available) and each filter would be of the same standard design. Alternately, the filters may come with the particular equipment you buy.

– p.284-285

Here Hamming is predicting the internet. He got very close, and it’s interesting to think that these signals would all just be piped to your house in a bundle you you pay for a filter to unlock access to the ones you want. Hey Cable TV worked that for a long time!

On Leadership

But a lot of evidence on what enabled people to make big contributions points to the conclusion that a famous prof was a terrible lecturer and the students had to work hard to learn it for themselves! I again suggest a rule:

What you learn from others you can use to follow;

What you learn for yourself you can use to lead.

– p.292

Learn by doing, not by following.

What you did to become successful is likely to be counterproductive when applied at a later date.

– p.342

It’s easy to blame changing trends in software development for the disgustingly short half-life of knowledge regarding development patterns and tools, but I think it’s probably just the nature of knowledge based work. Operating by yourself may be effective and work well, but its not a recipe for success at any given moment in time.

A man was examining the construction of a cathedral. He asked a stonemason what he was doing chipping the stones, and the mason replied, “I am making stones.” He asked a stone carver what he was doing; “I am carving a gargoyle.” And so it went; each person said in detail what they were doing. Finally he came to an old woman who was sweeping the ground. She said, “I am helping build a cathedral.” If, on the average campus, you asked a sample of professors what they were going to do in the next class hour, you would hear they were going to “teach partial fractions,” “show how to find the moments of a normal distribution,” “explain Young’s modulus and how to measure it,” etc. I doubt you would often hear a professor say, “I am going to educate the students and prepare them for their future careers.” This myopic view is the chief characteristic of a bureaucrat. To rise to the top you should have the larger view—at least when you get there.

– p.360

Software bureaucrats aplenty. Really easy to fall into this role.

I must come to the topic of “selling” new ideas. You must master three things to do this (Chapter 5):

1. Giving formal presentations,
2. Producing written reports, and
3. Mastering the art of informal presentations as they happen to occur.

All three are essential—you must learn to sell your ideas, not by propaganda, but by force of clear presentation. I am sorry to have to point this out; many scientists and others think good ideas will win out automatically and need not be carefully presented. They are wrong;

– p.396

One thing I regret over the last 10 years of my career is not writing down more insights I have learned through experience. Ideas simply don’t transmit if they aren’t written down or put into some consumable format like video or audio. Nearly every annoying tool or developer trend you are forced to use is in play because it communicated the idea through blogs, videos and conference talks. And those who watched echoed these messages.

On Experts

An expert is one who knows everything about nothing; a generalist knows nothing about everything.

In an argument between a specialist and a generalist, the expert usually wins by simply (1) using unintelligible jargon, and (2) citing their specialist results, which are often completely irrelevant to the discussion. The expert is, therefore, a potent factor to be reckoned with in our society. Since experts both are necessary and also at times do great harm in blocking significant progress, they need to be examined closely. All too often the expert misunderstands the problem at hand, but the generalist cannot carry though their side to completion. The person who thinks they understand the problem and does not is usually more of a curse (blockage) than the person who knows they do not understand the problem.

– p.333

Understand when you are generalist and a specialist.

Experts, in looking at something new, always bring their expertise with them, as well as their particular way of looking at things. Whatever does not fit into their frame of reference is dismissed, not seen, or forced to fit into their beliefs. Thus really new ideas seldom arise from the experts in the field. You cannot blame them too much, since it is more economical to try the old, successful ways before trying to find new ways of looking and thinking.

If an expert says something can be done he is probably correct, but if he says it is impossible then consider getting another opinion.

– p.336

Anyone wading into a technical field will encounter experts at every turn. They have valuable information, but they are also going to give you dated, myopic advice (gatekeeping?). I like Hamming’s framing here and it reflects my experience when weighing expert opinion.

In some respects the expert is the curse of our society, with their assurance they know everything, and without the decent humility to consider they might be wrong. Where the question looms so important, I suggested to you long ago to use in an argument, “What would you accept as evidence you are wrong?” Ask yourself regularly, “Why do I believe whatever I do?” Especially in the areas where you are so sure you know, the area of the paradigms of your field.

– p.340

I love this exercise. It will also drive you crazy. Tread carefully.

Systems engineering is indeed a fascinating profession, but one which is hard to practice. There is a great need for real systems engineers, as well as perhaps a greater need to get rid of those who merely talk a good story but cannot play the game effectively.

– p.372

Controversial, harsh, but true.

The Binding

The last thing I want to recognize is the beautiful cloth resin binding and quality printing of the book. Bravo Stripe Press for still producing beautiful artifacts at affordable pricing in the age of print on demand.

Usage: async-neocities [options]

    Example: async-neocities --src public

    --help, -h            print help text
    --src, -s             The directory to deploy to neocities (default: "public")
    --cleanup, -c         Destructively clean up orphaned files on neocities
    --protect, -p         String to minimatch files which will never be cleaned up
    --status              Print auth status of current working directory
    --print-key           Print api-key status of current working directory
    --clear-key           Remove the currently associated API key
    --force-auth          Force re-authorization of current working directory

async-neocities (v3.0.0)

When you run it, you will see something similar to this:

> async-neocities --src public

Found siteName in config: bret
API Key found for bret
Starting inspecting stage...
Finished inspecting stage.
Starting diffing stage...
Finished diffing stage.
Skipping applying stage.
Deployed to Neocities in 743ms:
    Uploaded 0 files
    Orphaned 0 files
    Skipped 244 files
    0 protected files

async-neocities was previously available as a GitHub Action called deploy-to-neocities. This Action API remains available, however the CLI offers a local-first workflow that was not previously offered.

Local First Deploys

Now that async-neocities is available as a CLI, you can easily configure it as an npm script and run it locally when you want to push changes to neocities without relying on GitHub Actions. It also works great in Actions with side benefit of deploys working exactly the same way in both local and remote environments.

Here is a quick example of that:

• Install async-neocities@^3.0.0 to your project’s package.json.
• Set up a package.json deploy script:

   "scripts": {
      "build": "npm run clean && run-p build:*",
      "build:tb": "top-bun",
      "clean": "rm -rf public && mkdir -p public",
      "deploy": "run-s build deploy:*",
      "deploy:async-neocities": "async-neocities --src public --cleanup"
    },
  

• Run a deploy once locally to set up the deploy-to-neocities.json config file. Example config contents:

  {"siteName":"bret"}
  

• Run deploys locally with npm run deploy.
• Configure your CI to run npm run deploy and configure the token secret.

  name: Deploy to neociteis
  
  on:
    push:
      branches:
        - master
  
  env:
    node-version: 21
    FORCE_COLOR: 2
  
  concurrency: # prevent concurrent deploys doing starnge things
    group: deploy-to-neocities
    cancel-in-progress: true
  
  jobs:
    deploy:
      runs-on: ubuntu-latest
  
      steps:
      - uses: actions/checkout@v4
      - name: Create LFS file list
        run: git lfs ls-files -l | cut -d' ' -f1 | sort > .lfs-assets-id
      - name: Restore LFS cache
        uses: actions/cache@v3
        id: lfs-cache
        with:
          path: .git/lfs
          key: ${{ runner.os }}-lfs-${{ hashFiles('.lfs-assets-id') }}-v1
      - name: Git LFS Pull
        run: git lfs pull
  
      - name: Use Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{env.node-version}}
      - run: npm i
      - run: npm run deploy
        env:
          NEOCITIES_API_TOKEN: ${{ secrets.NEOCITIES_API_TOKEN }}
  

The async-neocities CLI re-uses the same ENV name as deploy-to-neocities action so migrating to the CLI requires no additional changes to the Actions environment secrets.

CLIs vs Actions

This prompts some questions regarding when are CLIs and when are actions most appropriate. Lets compare the two:

CLIs

• Pro: Local deploys
• Pro: Easily re-usable in CI as well
• Con: Requires Node.js, but this is not a problem when already using Node.js

Actions

• Pro: Works great with Non-node ecosystems without requiring a package.json or node_modules
• Con: Only runs in CI environments

Conclusion

In addition to the CLI, async-neocities migrates to full Node.js esm and internally enables ts-in-js though the types were far to dynamic to export full type support with the time I had available.

With respect to an implementation plan going forward regarding CLIs vs actions, I’ve summarized my thoughts below:

Implement core functionality as a re-usable library. Exposing a CLI makes that library an interactive tool that provides a local first workflow and is equally useful in CI. Exposing the library in an action further opens up the library to a wider language ecosystem which would otherwise ignore the library due to foreign ecosystem ergonomic overhead. The action is simpler to implement than a CLI but the CLI offers a superior experience within the implemented language ecosystem.

It’s still not great, but it should make it easier to keep it up to date going forward.

It has 3 sections:

• Featured Projects: important projects of note.
• Recent Posts: now that this site has proper blog support, I can highlight recent posts on the landing page.
• Open Source: interesting and notable projects that have found some use and that I still maintain. This section now includes a bunch of open source work from the past year that I’ve never had time to write about.
• Past projects: inactive projects that are not longer active, but still interesting enough to share.

I removed a bunch of older inactive projects and links and stashed them in a project.

Additionally, the edit button in the page footer now takes you to the correct page in GitHub for editing, so if you ever see a typo, feel free to send in a fix!

Finally, the about page includes a live dump of the dependencies that were used to build the website.