macintosh.js: System 8 in an Electron window, and why it is a toy

What macintosh.js actually is, and who it is for

macintosh.js is an Electron application that boots Mac OS 8 on an emulated 1991 Macintosh Quadra 900 with a Motorola CPU. The README describes it as "the full thing" and follows that with "I'm sorry", which sets the tone for everything else in the repository. The emulation core is not the author's work: the credits point to Christian Bauer and James Friend, and the README says the app "wouldn't be possible without" them. Felix Rieseberg's contribution is the packaging, the Electron shell, and the disk image full of preinstalled software.

The audience is narrow and the project knows it. Under the heading "Should I use this for [serious application]?" the README answers "Probably not", calling it a toy and stating it is neither the best nor the most performant way to emulate an old Macintosh. That is unusually honest positioning, and it should be taken literally. If you want a nostalgia hit on a laptop, this is the shortest path. If you want a reliable 68k Mac environment for software archaeology, this is not the tool the author is offering you.

The preinstalled content is the real draw. The disk image comes from an old MacWorld Demo CD from 1997 and includes Oregon Trail, Duke Nukem 3D, Civilization II, Alley 19 Bowling, Damage Incorporated, and Dungeons & Dragons, plus Photoshop 3, Premiere 4, Illustrator 5.5, StuffIt Expander, and the Apple Web Page Construction Kit. None of that requires configuration.

The architecture: Electron, TypeScript, and an emulator in JavaScript

The repository is a TypeScript Electron app built with Electron Forge. The package name is macintosh.js, the main entry is ./dist/src/main/main.js, and the build scripts are the standard Forge set: electron-forge start, package, make, and publish. Electron is pinned at 41.2.0, Vite at 7.3.1, TypeScript at 6.0.2. A postinstall script runs patch-package, which means the project patches at least one dependency at install time; the patches/ directory at the top level is where those live.

The runtime dependencies are small: electron-squirrel-startup for Windows installer handling and update-electron-app for updates. Everything else in package.json is a devDependency, which fits the model of an app that ships prebuilt binaries rather than a library you import.

The README states that the virtual machine is written entirely in JavaScript, which is the source of the performance caveat. A 68k emulator running in JavaScript inside Electron is doing instruction interpretation in a language that was never designed for it, and the README's "adjust your expectations" line is a direct acknowledgement of that. The README also answers "Should this have been a native app?" with "Absolutely", so the author is not defending the choice.

The networking layer is the most interesting recent addition. The emulator exposes a virtual Ethernet card using Infinite Mac's ether js driver. Frames are bridged to UDP port 6066, the same udptunnel scheme native Basilisk II and SheepShaver use. Two copies of macintosh.js on the same LAN can therefore speak AppleTalk to each other and share files through the Chooser. Reaching the modern Internet would need a userspace TCP/IP NAT, described in the README as a slirp-style gateway plugged into src/main/ethernet.ts, and that is not bundled.

Installing macintosh.js and running your first session

The README does not give a build-from-source path for end users. It points at the releases page instead, with per-platform downloads. Pick the asset that matches your machine. On Windows, the README links both 32-bit and 64-bit installers and standalone zips at v1.2.0. On macOS, it links standalone zips for Intel and Apple M1 at v1.1.0. On Linux, it links rpm and deb packages at v1.1.0 for 32-bit, 64-bit, ARM64, and ARMv7.

The README gives a platform-specific command for identifying your architecture on Linux. Run it in a console and match the output to the asset names:

uname -m

On Windows the README suggests hitting Start and entering "processor" instead. On macOS it links to an Apple support page. The version mismatch between platforms is worth noticing before you download: Windows assets are at v1.2.0 while macOS and Linux assets are at v1.1.0.

If you want to build from source rather than use a release, the package.json scripts imply the usual Forge workflow. This is not documented in the README, so treat it as reading the repository rather than following instructions:

npm install
npm start

The postinstall hook runs patch-package, so the install step is doing more than fetching dependencies. npm run make produces platform packages, and npm run lint runs prettier plus a link checker at tools/check-links.js.

Once the app is running, the Help button at the bottom of the window is where file transfer instructions live. The README states you can transfer files directly or mount disk images, but the details are in the app, not the README. That is a documentation gap: the README tells you the capability exists and then hands you off to a button.

Where macintosh.js falls short

Performance is the first limitation, and it is the author's own. The README states the VM is written entirely in JavaScript and asks you to adjust your expectations. That is not a throwaway line. Emulating a Motorola CPU in interpreted JavaScript inside a Chromium process is slow, and the README's answer to whether it should have been native is an unqualified yes.

Internet access is partial and the README is precise about why. AppleTalk over UDP port 6066 works between two instances on the same LAN. Reaching the modern Internet needs a slirp-style NAT gateway wired into src/main/ethernet.ts, and the README says that is not bundled yet. Even if you wrote it, the README points out that the 1997-era browsers on the disk image will not get far against today's TLS. So the networking feature is a LAN file-sharing feature, not a browsing feature. If you came for a retro web experience, the answer is no.

The third limitation is scope. The README's "Should I use this for [serious application]?" section is a flat no. This is not a general-purpose 68k Mac emulator with configurable ROMs and disk images. It is one machine, one system version, one prebuilt disk. If you need to boot a different System version, attach your own disk images, or script the emulator, look elsewhere.

Finally, the licence situation is unclear from the repository metadata. The README says the project is "provided for educational purposes only" and is not affiliated with or approved by Apple. The package.json declares MIT. Those two statements sit awkwardly together, and the README's framing is narrower than MIT. The emulated system software is Apple's, not the project's.

Basilisk II and SheepShaver: the difference in approach

The README names the alternative itself. The UDP port 6066 bridging scheme is described as "the same udptunnel scheme native Basilisk II / SheepShaver use", which tells you these are the reference implementations for 68k and PowerPC Mac emulation on modern hardware.

The architectural difference is the language and the host. Basilisk II and SheepShaver are native C and C++ applications that talk to the host OS directly. macintosh.js runs the emulator in JavaScript inside Electron, which means every emulated instruction passes through a JavaScript engine and a Chromium process before it reaches your CPU. That is the entire reason the README tells you to expect less.

What you get in return is packaging. Basilisk II and SheepShaver require you to supply a ROM, build or install a binary, and configure disk images yourself. macintosh.js ships a signed installer for Windows, a zip for macOS, and rpm and deb packages for Linux, with a working system and a pile of 1997 software already in place. The trade is control and speed for convenience.

Basilisk II is also the better choice if you need the slirp networking that macintosh.js explicitly does not bundle. If your goal is a usable retro Mac with Internet access, the native emulators already have the piece that macintosh.js is missing.

Maintenance, releases, and what the version numbers tell you

The last push to the repository was on 2026-05-05, which is recent enough that the project is not abandoned. The release history is more uneven. v1.0.6 landed on 2020-08-03, v1.1.0 on 2021-01-04, and v1.2.0 on 2023-03-15. There has not been a tagged release since 2023-03-15, even though commits have continued. The Ethernet work described in the README is one of those post-release changes, so it is present in the source tree but not in the v1.2.0 binaries most people will download.

That gap matters for adopters. If you install from the releases page, you are running code from before the AppleTalk bridging was added. The networking section of the README describes behaviour you will not see unless you build from source. Nothing in the README flags this, and the download table still points at v1.2.0 for Windows and v1.1.0 for everything else.

The upgrade cost is mostly the Electron version. The project pins Electron 41.2.0 and uses update-electron-app, so the app checks for updates on its own. Because the emulator runs inside Electron, an Electron upgrade is a potential source of breakage, and the patches/ directory suggests dependency patching is already part of the maintenance routine. For a user, the practical answer is that upgrading means downloading a new release, not running a package manager command.

On licensing, the README's "educational purposes only" language and the MIT declaration in package.json are not the same permission. The MIT licence covers the project's own code. The system software inside the disk image is a separate question that the README does not address beyond the Apple disclaimer.

Editorial conclusion

Adopt macintosh.js if you want a few minutes of System 8 on a modern desktop and you accept the performance ceiling the README admits to. Do not adopt it for serious emulation work, for Internet access, or for anything you need to keep. Before installing, check which release your platform needs: the 64-bit Windows installer exists at v1.2.0, while macOS and Linux builds sit at v1.1.0, and the README points you at `uname -m` or a processor check to pick the right one.

Frequently asked questions

Official sources

1. felixrieseberg/macintosh.js on GitHub
2. Issues
3. README
4. Releases