scratch-blocks: the Blockly-based library behind Scratch's block editor

What scratch-blocks is for, and who it is not for

Scratch Blocks is a library for building creative computing interfaces. The README frames it as a design specification and codebase, not an application: you get the block editor layer, and you supply the runtime and the surrounding product. The intended pairing is explicit. Together with the Scratch Virtual Machine, the README says, this codebase allows for the rapid design and development of visual programming interfaces. So the target user is someone building a block-based coding environment, most likely a Scratch derivative, an educational tool, or an embedded editor inside a larger product.

The audience is narrower than the name suggests. If you want to run Scratch projects, you want scratch-vm and probably scratch-gui, not this repository. If you want a general-purpose block editor with no opinion about how blocks execute, Blockly alone is the smaller dependency. Scratch Blocks sits in between: it carries Scratch's block shapes, colours and workspace behaviour, and it expects the Scratch VM on the other end to give those blocks meaning.

The 2.0 change: from fork to Blockly dependency

Version 2.0 is a structural rewrite. The README states that this release is no longer a fork of Blockly, but rather depends on Blockly as a library, and that the underlying Blockly version moved to version 12. That distinction matters for anyone who previously vendored scratch-blocks and patched it in place. A fork lets you modify Blockly internals freely; a dependency does not. Upgrades now arrive through the blockly package rather than through a merge of upstream changes.

The package.json confirms the shape of that dependency. The runtime dependencies are blockly ^12.4.1 plus two Blockly plugins, @blockly/continuous-toolbox and @blockly/field-colour. The library is written in TypeScript and bundled with webpack, and it publishes an ESM entry at ./dist/main.mjs with types at ./dist/types/src/index.d.ts. There is a single export map entry for ".", with import, default and types conditions all pointing at that ESM file. There is no CommonJS build listed, which is a practical constraint for older toolchains.

The other half of the architecture is what the library deliberately does not do. Unlike Blockly, the README says, Scratch Blocks does not use code generators, but rather leverages the Scratch Virtual Machine to create highly dynamic, interactive programming environments. In a conventional Blockly setup, blocks are translated into JavaScript, Python or another target and then executed. Here the blocks are a front end for a VM that interprets them directly, which is why the blocks can change shape and grow inputs while a script runs.

Building scratch-blocks from a clean checkout

The README's development section is short. It gives two commands, and both are run from the repository root. The first installs exactly what the lockfile pins, which matters because the project uses semantic release and expects dependency bumps to follow semver.

npm ci
npm run build

The build script is webpack --mode production, so the output lands in dist/ and the published entry point is dist/main.mjs. If you are working on the library rather than consuming it, npm start runs webpack serve --open --mode development, which starts a dev server and opens a browser. The README does not describe a demo page or what that server renders, so treat it as a development convenience rather than a documented playground.

Tests split into two projects. Unit tests run in jsdom with no extra setup, while browser tests need Chromium installed once through Playwright.

npm run test:unit
npx playwright install chromium
npm run test:browser

Running npm test executes vitest run across both projects. When a browser test fails, the README offers two debugging paths: npm run test:browser -- --browser.headless=false to watch it happen, or PWDEBUG=1 npm run test:browser to pause on startup and open devtools. Those flags come from the README verbatim; do not assume other Playwright options are wired up.

Where scratch-blocks will not carry you

The README is candid about release readiness. It says there will likely be a few bumps in the road as the team works toward a user-facing release, and it asks readers to file issues with as much detail as possible. That is a public statement that the 2.0 API should be treated as moving. If your product depends on internal module paths or on specific workspace behaviours, plan for churn between minor versions.

The documentation gap is the second limitation. The README points to the wiki for a getting started guide, FAQ and design documentation, and the homepage is the Scratch developers page. There is no API reference in the repository README itself, no migration guide for code written against the 1.x fork, and no documented rollback path if a Blockly 12 upgrade breaks your integration. The commit conventions are documented in more detail than the public API: the project uses semantic release with conventional-changelog commit messages, and the README suggests the commitizen CLI for formatting them. That tells you version numbers will be meaningful, not that the surface is stable.

There is also a licensing boundary worth reading before you ship. The repository is Apache-2.0, but a separate TRADEMARK file sits at the top level. Apache-2.0 grants copyright and patent rights to the code; it does not grant rights to the Scratch name or logo. If you are building a product on top of this library, the trademark file is the one to read with your own counsel, not the licence header.

scratch-blocks compared with Blockly on its own

The honest alternative is Blockly, and the comparison is not about quality but about which layer you want to own. Blockly gives you a block editor plus code generators: you define blocks, and Blockly emits JavaScript, Python, PHP, Lua, Dart or another target that you then run somewhere else. Scratch Blocks removes that translation step and instead hands block execution to the Scratch VM, which is why the README describes the result as highly dynamic and interactive rather than as a code generation pipeline.

The trade-off follows directly. With Blockly alone you get a smaller dependency tree and a well-trodden path to generated source code, which suits tools that teach a text language. With scratch-blocks you get Scratch's visual language and the expectation of a VM that can mutate the workspace at runtime, at the cost of a heavier dependency on blockly 12 plus two plugins, and at the cost of the code-generation escape hatch. If your users need to see the JavaScript their blocks produce, scratch-blocks is the wrong layer; if your users need blocks that reshape themselves as the program runs, Blockly's generator model is the wrong fit.

Maintenance, releases and what an upgrade costs

The repository is not archived, and the last push was on 2026-04-28, which is under six months before today. Recent releases are frequent and close together: v2.1.17 on 2026-04-21, v2.1.18 on 2026-04-27 and v2.1.19 on 2026-04-28. The version numbers are produced automatically by semantic release from conventional commit messages, so the patch-level cadence reflects the commit stream rather than a hand-written changelog.

The upgrade cost is mostly Blockly's. Because scratch-blocks depends on blockly ^12.4.1 and on @blockly/continuous-toolbox and @blockly/field-colour, a Blockly major release can force changes here even when no scratch-blocks API changed. The caret range means minor and patch Blockly updates arrive on npm install; a major bump would not, but the project's own move from a fork to Blockly 12 shows that major bumps do happen. Pin your lockfile and read the release notes before moving.

On licensing: Apache-2.0 is permissive and includes an explicit patent grant. It does not cover the Scratch trademarks, which the TRADEMARK file addresses separately. Nothing here is legal advice; if you are distributing a commercial product built on this code, have someone qualified read both files.

Editorial conclusion

Adopt scratch-blocks if you are building a Scratch-like visual programming interface and intend to drive it with scratch-vm, and you accept that the README points to the wiki for getting started. Do not adopt it if you need a stable documented API or generated code output; the README says the project does not use code generators, and it warns of bumps on the road toward a user-facing release. Before committing, verify the current state of the v2.0 API against the wiki design documentation, confirm that your bundler can consume the ESM-only ./dist/main.mjs entry, and check the develop branch for the latest changes rather than the release tag.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes