async-neocities v5.0.0 automates the monthly sync of supported Neocities file types.async-neocities v5.0.0 modernize release workflow.deploy-to-neocities v3.0.6 upgrades async-neocities to v5.deploy-to-neocities v3.0.6 upgrades domstack to v12 beta.deploy-to-neocities v3.0.6 modernizes release and site-maintenance tooling.deploy-to-neocities v3.0.6 updates build, test, and deployment dependencies.He has been making movies for a while now, but I only caught up with them the other year. His movies have a sort of self-aware Wes Anderson feel without much pretension. Most of them are silly, entertaining, and generally well executed. Nothing goes to waste in these movies.
Mandibles is about two lowlife criminals who steal a car, find a gigantic fly in the trunk, and then get mistaken for old high school friends and invited to a vacation home. It’s silly, energetic, and youthful. It captures his filmmaking style without being too bizarre, while still being funny and surreal. Highly recommended!
Yannick is about a young construction worker who attends a play called Le Cocu. The play is boring, so he stands up and interrupts the performance to tell the actors they should make it better, offering some earnest and honestly good ideas. The whole theater thinks he’s insane and treats him that way. Having traveled a long way to attend the play, only to be let down and disrespected, our protagonist hijacks the theater with a pistol, demands a typewriter and a printer, and sets out to rewrite the play. It ends with an incredible crescendo with a touching emotional high.
This movie is about a Power Rangers-inspired, monster-fighting team, except their superpowers somehow come from the deadly chemicals in cigarettes. The movie is kind of a flex in filmmaking, pulling out and executing all the classic special effects, costumes, and gore. Beyond the technical filmmaking, the story follows a series of bizarre, funny, and generally entertaining tales.
The Piano Accident is a movie about influencers and journalists.
It’s a bunch of funny dialogue between a group of great French actors. It’s set in a surreal restaurant run by a waiter who can’t pour wine without spilling it. Simple, satisfying, and worth a watch.
This movie follows a suspect and the cop interviewing him. He is clearly innocent, but the evidence and circumstances keep stacking up against him. It almost feels like a bad dream you can’t wake up from.
This is a funny movie about a couple who buy a house with a tunnel in the basement. If you go down the tunnel, you end up climbing down a ladder from the attic, sort of like a portal. Every time you go through it, you emerge six days younger, but two weeks pass for those outside it. The wife immediately becomes addicted to the tunnel and seeks to regain her younger self. Meanwhile, her husband gets two weeks older every time she goes through. He ages considerably while she ultimately becomes only a few years younger. The ending is shocking, and there are a slew of funny side stories, like the husband’s obnoxious boss flying to Japan to get a “smart penis” augmentation that he can control with an iPhone app.
Deerskin is about a serial killer who’s going through a divorce and his sycophantic assistant.
I saw these when they came out, and I still really like them. They are surreal and don’t make much sense, but they’re entertaining, and it’s fun to watch the obnoxious characters develop on screen. Wrong Cops is the better of the two. The story about the psychic dog is really entertaining, and all the locations they shoot in are interesting on their own. These movies feature a lot of Mr. Oizo music, and it fits perfectly.
Steak is very bizarre. It’s also really funny. It mixes a weird American letterman-jock aesthetic with a compulsive drive for plastic surgery, while everyone is obsessed with drinking milk and eating raw eggs. The old lifted square-body trucks they drive are really cool, too.
Reality is about a movie in a movie or something I can’t remember. Eric Wareheim steals the show.
It’s a movie about Salvador Dalí, and it makes about as much sense as his art!
It’s a movie about a killer tire. Most of the movie is just full of “no reason.” In a lot of ways, it seems like a filmmaking flex. There are some funny scenes, but overall it’s pretty slow, though it does have a few good songs.
As a professional dorker, I’ve always been annoyed that it denied me full orbital controls with pan and zoom, so I went ahead and added those here. Enjoy!
I love the idea of full 3D icons and would like to learn to make these for projects of my own, so I started by picking this one apart.
(P.S. — Panic: If there is any concern about this, just contact me and I’ll be happy to take it down.)
]]>I’m selling my graphics card from my You can just build a Steam Machine blog post.
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 three days after writing this, TanStack released a native Preact TanStack Query adapter! Just use that and ignore the rest. Thanks to everyone involved in that.
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!).
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.
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} />`)
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 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:
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:
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:
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.
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.
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.
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:
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:
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.
(This will go stale quickly, but as of this writing, it works.)
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:
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.
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!
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
SteamOS has been around for a while—so much so that there are two distinct versions of it.
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”!
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.
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.”
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.
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.
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.
Try them all! See what works best for your goals and your hardware.
If you enjoyed this post, you might also like:
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.
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:
npm packages from a single git repositoryThis approach gained popularity largely as a response to:
npm linkMonorepos 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.
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.
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.
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:
node_modules/foo) than single repo = single package project organization.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!
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.jsonBecause 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.
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.
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.
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.
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?
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.
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.
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.
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.
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.
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.
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!
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?!
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.
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.
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.
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.
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.
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.
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.
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.
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 they lack API depth). Annoying modules are annoying Get rid of your annoying dependencies, and cross your fingers the replacement is less annoying.
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.
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!
This is probably true. Do whatever you need. Just enumerating a few common hazards to avoid.
Yeah Agreed. Single module repo strategies are sadly very underdeveloped and misunderstood.
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.