pxt-microbit: the MakeCode target behind the BBC micro:bit editor

What a MakeCode target actually is

Microsoft MakeCode is a set of editors for block based and text based programming, and each supported board has its own target, a repository that carries the board's runtime libraries, the block definitions, the simulator and the configuration that ties them together.

pxt-microbit is the target for the BBC micro:bit. The README describes it as a Microsoft Programming Experience Toolkit target that allows you to program a BBC micro:bit, and the project description calls it a Blocks and JavaScript code editor for the micro:bit built on Microsoft MakeCode. The hosted editor is at makecode.microbit.org.

Two audiences use this repository. The first is educators and learners who want to write programs for the board, either by dragging blocks or by writing JavaScript, with both views editing the same project. The second is developers writing extensions for the micro:bit, and the README points to the GitHub packages documentation for authoring and testing extensions, noting that this can be done directly from the web editor.

The repository layout reflects both. There is an editor directory, a compiler directory, a sim directory for the simulator, libs for the runtime libraries such as core, radio and microphone, fieldeditors for the custom block editors, clients for the device flashing clients, a theme directory and a docs directory. The pxtarget.json and targetconfig.json files describe the target itself.

The implementation language is TypeScript. The package manifest shows version 9.1.1, with dependencies on pxt-core 13.0.1 and pxt-common-packages 14.0.2, and dev dependencies on React 16.8.3 and TypeScript 4.8.3.

Version branches pin the whole PXT stack

The most important thing in the README is the version matrix, because a MakeCode target is useless without a matching compiler and set of common packages.

pxt-microbit beta, which is the v3.0 series, requires the stable3.0 branch of pxt-microbit together with the stable6.0 branch of pxt and a stable branch of pxt-common-packages. The link text points at stable6.0 while the URL for pxt-common-packages points at its stable7.0 branch, so check the actual branch you are pairing rather than trusting the label.

The v2.0 series lives on the stable2.0 branch and requires pxt v5.15.x. That branch is described as the servicing branch for the live editor, which means it is the line that receives fixes for the editor that actual users load from the web.

The v1 series requires pxt v4.4, which lives in the stable4.4 branch of the pxt repository. The v0 series is in the v0 branch of this repository.

So there are four supported lines with three different PXT generations, and the README states the requirement for each explicitly. In practice, if you are contributing to the current editor you want the v2.0 servicing line, and if you are preparing for the next major release you work on the v3.0 beta.

The dependency direction matters too. pxt-microbit is not standalone. It sits on top of the pxt editor framework and on pxt-common-packages, and it also pulls the CODAL runtime for the board, which is why a developer setup involves three repositories and not one.

Running a local editor with pxt serve

Authoring and testing extensions can be done from the web editor, so a local server is optional. When you want it, the short setup is four steps.

Install Node.js 8.9.4 or higher, clone the repository and install the PXT command line globally, adding sudo on Mac and Linux shells:

git clone https://github.com/microsoft/pxt-microbit
cd pxt-microbit

npm install -g pxt

Then install the target's own dependencies:

npm install

And start the server from inside the pxt-microbit directory:

pxt serve

One detail causes confusion for newcomers. If the local server opens in the wrong browser, you have to copy the URL containing the local token, because without that token the editor cannot load the projects. The token is part of the URL the server prints, and the editor refuses to work without it.

Two flags cover most of the other cases. pxt serve --local enables yotta compilation, which is what you need if you are modifying .cpp files and have yotta installed. pxt serve --rebundle skips the build entirely and just refreshes the target information, which the README recommends when you want a faster turnaround and nothing in the native layer has changed.

When the built folder ends up in a bad state, pxt clean clears it and you start over.

The three-repository developer setup

The typical setup used by the MakeCode team is longer, and the reason is that the target, the editor framework and the shared libraries are separate repositories that have to be wired to each other.

The steps begin with Node.js 8.9.4 or higher, and Docker if you plan to build .cpp files, since the native compilation runs in a container. You then clone pxt, install its dependencies and build it with npm install and npm run build. Next you clone pxt-common-packages and install its dependencies, and link it back to pxt:

npm link ../pxt
cd ..

After that you clone pxt-microbit, install the PXT command line, install the target dependencies, and link the target back to both base repositories:

npm link ../pxt ../pxt-common-packages

The README is explicit that the final link step is only required if you intend to make changes to pxt or pxt-common-packages, and that it can be skipped if all you want is to serve a local MakeCode. The command also assumes a specific folder layout, which the README draws as three sibling directories named pxt, pxt-common-packages and pxt-microbit under a common parent.

The link model is worth understanding rather than copying. npm link points the installed package at a working directory instead of the registry copy, so the editor picks up your local edits to the framework or the shared libraries immediately. That is what makes it possible to change something in pxt-core and see the effect in the micro:bit target without publishing anything.

The maintenance note at the end of the setup section is also practical: pull changes from all of the repositories regularly, because the three of them move at different rates.

Forcing a local CODAL build

Most of the time the editor compiles in the cloud against a tagged version of the runtime. When you need to work on the native layer itself, the README documents a local path in detail.

First you force a local build of the target with:

pxt buildtarget --local

And you can turn Docker off entirely with:

export PXT_NODOCKER=1

The environment variables used together are PXT_FORCE_LOCAL=1, PXT_RUNTIME_DEV=1 and PXT_ASMDEBUG=1, and pxt help documents them. After setting them, you open the editor on localhost, create a project, and find that project folder under pxt-microbit/projects, typically with a name such as Untitled-42.

To point the build at your local copies of the native libraries you replace the wildcard entries in pxt.json, for example "core": "file:../../libs/core", and the same for radio and microphone. Running pxt build in that folder clones the CODAL runtime somewhere under built, depending on the build engine and whether Docker is in play.

There is a documented trap here. The Download button in the localhost editor produces a different binary from the command line, because the editor builds in the cloud against a tagged version of CODAL. If your change seems to have no effect, that difference is the first thing to check.

The output of a successful build lands in pxt-microbit/projects/<your project name>/built as binary.hex. From there you can flash it with pxt deploy, or just pxt, which builds and copies to the MICROBIT drive.

For deeper inspection, pxt gdb debugs the target and needs openocd installed, pxt dmesg dumps the DMESG buffer, and pxt heap visualises the PXT heap and, to some extent, the CODAL one.

Where the local workflow gets in the way

The documentation is unusually detailed about the native development path, and it is worth reading it as a description of the costs rather than just as instructions.

The local server is explicitly scoped. The README states that it lets you run the editor and serve the documentation from your own computer, and that it is meant for a single developer and is not designed to serve the editor to a large number of users. Anything that treats pxt serve as a hosting solution is outside what the project supports.

The native build is heavy. Changing .cpp files means having Docker available, or accepting the PXT_NODOCKER path with its own complications, and the README notes a separate issue where the variables exported from the build command may not be carried into the build itself, which is why a longer command line with PXT_FORCE, PXT_DEBUG and PXT_COMPILE_SWITCHES is given as a workaround.

Cache invalidation is another recurring source of confusion. The README mentions deleting files in the hexcache directory under pxt-microbit/built/hexcache to force a local build, and similarly for the dal.d.ts generation flow in libs/blocksprj, which involves removing the built folder and running pxt build and pxt builddaldts before moving dal.d.ts into ../core.

None of that is unusual for embedded tooling, but it does mean that a change to the runtime libraries has a much longer feedback loop than a change to a block definition or a TypeScript library.

There is also a simple structural limit. The micro:bit's runtime is CODAL and the PXT layer sits on top, so anything that changes the device behaviour has to travel through the fork of the CODAL repositories under the built directory, which the README tells you to check out by branch, noting that they are all in detached head state because that is how releases are tagged.

Licence, maintenance and the shape of the tree

The licence needs a sentence of care. The repository is classified with a custom licence that GitHub cannot categorise, and the files at the top level include LICENSE.txt and THIRD-PARTY-NOTICES.txt. The package manifest, on the other hand, declares the package licence as MIT. That combination is normal for a project that vendors or depends on code under several licences, and it means you should read LICENSE.txt and THIRD-PARTY-NOTICES.txt yourself before shipping anything, rather than relying on the MIT field. This is not legal advice.

The repository is not archived, and the last push was on 2026-10-20. There are no GitHub releases at all, which fits the model: versions are expressed as branches and version numbers in the README matrix, and the release artefacts are the hosted editor itself.

A SECURITY.md file sits at the top level, which is where a project that runs code in browsers and flashes binaries to physical devices would put its vulnerability reporting process.

The tree itself is organised by concern rather than by feature, with editor, compiler, sim, libs, fieldeditors, clients, electron, pxtwapp, docs, tests and theme directories, plus playlists.json and a webmanifest.json for the web app. The clients directory is where the code that talks to a connected micro:bit lives, and the electron directory is for the desktop shell.

The upgrade cost for a contributor is mostly dependency alignment. Because the target pins pxt-core and pxt-common-packages by exact version, a change in either of those projects means the target's package.json has to move with it, and the branch matrix has to keep describing a combination that actually builds.

Editorial conclusion

Adopt pxt-microbit if you are writing micro:bit extensions or changing the runtime libraries the board ships, since that is where the DAL typings, the blocks definitions and the simulator live. Do not adopt it if you only want to program a micro:bit in blocks, because the hosted editor at makecode.microbit.org already does that, and do not treat the local server as a production deployment, because the README states it is meant for a single developer. Before you start, pick the version branch first, since v3.0 beta, v2.0, v1 and v0 each pin different PXT and pxt-common-packages versions, and install Node.js 8.9.4 or higher along with Docker if you intend to build .cpp files.

Frequently asked questions

Official sources

1. Issues
2. microsoft/pxt-microbit on GitHub
3. Project website
4. README