avr8js: an AVR CPU core that expects you to bring the hardware

A CPU core with no pins, timers or serial

avr8js is a JavaScript and TypeScript library that implements the AVR 8-bit architecture, and the README is unusually clear about how narrow that promise is. It states that the library only implements the AVR CPU core, and that you have to supply it pre-compiled machine code to run and implement functional simulations of any external hardware yourself. The repository description calls it an Arduino simulator, which oversells it slightly. What you get is the instruction set and the register file. What you do not get is a pin, a timer, a serial port, or a display. That split is the single most important fact for anyone evaluating the project, because the interesting work of a simulator is the boring half: modelling what happens when a pin goes high, converting a timer tick into elapsed milliseconds, pushing bytes out of a UART. The project's own framing is that it is the heart but not the whole body of the Arduino simulator at wokwi.com.

Machine code in, glue code out, picture on screen

The README gives a conceptual pipeline that explains the data flow. Pre-compiled machine code feeds into AVR8js, AVR8js talks to glue code, glue code talks to a functional simulation of the external hardware, and that simulation connects to a display of the simulation state for the user. Four layers, and only the second one is in this repository. The consequence for a user is that a running program means very little on its own. A program that toggles a pin inside avr8js changes CPU state, and if nothing is listening to that state the user sees nothing happen. You have to write the layer that watches a port register, decides what a physical LED would do, and updates whatever the user is looking at. The README also mentions that you will probably want to add audio or visual representations of the external hardware being simulated, which confirms the same boundary from the other side. This is why avr8js reads more like a kernel for a simulator than a simulator.

The demo is the shortest path to seeing a program run

The repository includes a demo project that lets you edit Arduino code, compile it, and run it in the simulator. It also simulates 2 LEDs connected to pins 12 and 13, which the README identifies as PB4 and PB5. Running it locally is a clone away, and the documented commands are an install followed by a start.

npm install
npm start

The start script maps to vite demo, and the demo folder carries its own index.html, a vite.config.js and a TypeScript config, so the demo is a Vite application rather than something served by the library itself. Seeing two LEDs respond to pin changes is the fastest way to understand the glue code boundary, because the demo has to implement those two LED behaviours somewhere, and that implementation is the pattern you would repeat for a button, a display or a NeoPixel matrix. The demo also gives you a working sketch compilation step, which avr8js itself does not provide: the library consumes machine code and leaves the Arduino toolchain outside its scope.

wokwi-elements draws the hardware but does not drive it

The visual side of a simulation has its own companion project, wokwi-elements, a collection of web components for visual representations of common hardware components. The README attaches an important note to it: these are visual only elements, and you will need to add the appropriate functional simulation and glue code. So a component library gives you something that looks like an LED on a canvas and nothing else. This is the part of the system most likely to cause a surprise, because a simulator UI that looks finished can still do nothing when the user clicks it. The devDependencies list pins @wokwi/elements at ^1.9.1, so the visual layer and the core are versioned together in practice. A related set of unofficial examples demonstrates the pattern in full: a 6 LEDs example, an LED PWM example, a Serial Monitor, a NeoPixel Matrix, an Arduino MEGA NeoPixel Matrix, a Simon Game with pushbuttons and sound, an XMAS LEDs example, an Assembly Code example, and an EEPROM persistence example. All of those are hosted outside this repository.

The ATmega328p is the target, other AVRs are configuration work

The library focuses on simulating the ATmega328p, the microcontroller used by the Arduino Uno. The README then says the code is built in a modular way and is highly configurable, making it possible to simulate many chips from the AVR8 family, such as the ATmega2560 and the ATtiny series. The qualifier matters. The mechanism for those other parts is configuration, and the documentation points at two GitHub issues, 67 and 73, for more information, rather than shipping a table of supported devices. A linked ATtiny85 simulation exists as a separate hosted project. If your hardware is an ATtiny or a MEGA, budget time for reading those threads and for working out which parts of the configuration you need to get right. The topics listed for the repository name atmega, atmega328p and avr, which is a reasonable summary of where the effort has gone. For a project that targets one chip well, this is a fair trade; for a project that has to support a spread of parts, the documentation is thin.

Tests run lint first, so a style error fails the suite

The test setup is one command, and it is worth knowing what is inside it.

npm test
npm run test:watch

The test script runs npm run lint and then vitest run, and lint is eslint src/ demo/. The watch script, npm run test:watch, is vitest on its own, so it skips the lint step and only reruns the tests of files you have changed since the last commit. The configuration files at the repository root match that split: vitest.config.ts, tsconfig.spec.json, eslint.config.mjs and prettier.config.js. A husky directory and a prepare script that runs husky and the build mean git hooks are part of the workflow for contributors, and lint-staged applies eslint and prettier to staged files under src. The test command is therefore stricter than a pure unit test run, which is worth remembering before you wire avr8js into a pipeline: a formatting regression can fail the same command that reports behavioural failures.

Version 0.21 after a long gap, on MIT terms

The release history is uneven. The latest tag is v0.21.1, published on 2026-08-31, and before it sit v0.20.1 and v0.20.0, both dated 2023-01-05. The repository is not archived and the last push was on 2026-08-31, so the current work is recent even though the previous release is more than three years old. The package version in package.json matches the latest tag, at 0.21.1, and the version prefix stays below 1.0, which signals an API that is still moving. The build emits two module formats, with main pointing at dist/cjs/index.js and module at ./dist/esm/index.js, and it ships type definitions at ./dist/esm/index.d.ts, so TypeScript consumers get types from the ESM entry. The declared engines are node >= 20.19.0 and npm >= 10.0.0, and the browserslist field targets the last 1 Chrome versions, which tells you the browser support is deliberately narrow. The code is released under the MIT license, copyright 2019-2025 Uri Shaked, so vendoring it into a commercial tool carries no conditions beyond keeping the licence text.

Editorial conclusion

Adopt avr8js if you need to execute AVR machine code in a browser tab, in a test suite, or in an Electron app, and you are prepared to write the peripheral models and the glue code yourself. Do not expect a finished Arduino simulator from it: the core ships without pins, timers, or serial, and the working examples live in separate StackBlitz projects rather than in the repository. Verify three things before building on it: that the ATmega328p is the chip you actually need, since other AVR parts depend on configuration work described only in issue threads; that your toolchain meets the declared engines of node >= 20.19.0 and npm >= 10.0.0; and that your loader can consume the package, which publishes CommonJS at dist/cjs/index.js alongside ESM at ./dist/esm/index.js with types at ./dist/esm/index.d.ts. If you want a drag-and-drop circuit you can wire up in the browser, wokwi.com is the ready-made option and avr8js is the piece underneath it.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. wokwi/avr8js on GitHub