scratch-blocks: a Blockly dependency, a daily tag, and a 2.0 announcement at the top
Project brief: Scratch Blocks is a library for building creative computing interfaces.
At a glance
- What is it?
- Scratch Blocks is a TypeScript library for building creative computing interfaces that depends on Blockly 12 rather than forking it, and that generates code through the Scratch Virtual Machine instead of Blockly code generators. Its README still leads with the 2.0 announcement while the package sits at 2.1.27 and tags land every day.
- Who is it for?
- scratch-blocks fits a team building a block-based editor on top of the Scratch Virtual Machine, and the dependency arrangement is the reason to choose it over maintaining a Blockly fork. Two things to plan around.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 21, 2026, and from our analysis. They are not legal advice.
Star history
- scratchfoundation/scratch-blocks2,774 ★ · +18
| Repository | 2026-07-30 | 2026-11-21 |
|---|---|---|
| scratchfoundation/scratch-blocks | 2.8k | 2.8k |
18 Stars in the last 114 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The page still announces 2.0 while the package reads 2.1.27
The first section of the README is still the 2.0 announcement. It announces Scratch Blocks 2.0 from the Scratch and Blockly teams, and it makes the one architectural claim that matters: this release is no longer a fork of Blockly but depends on Blockly as a library. The same paragraph still carries a literal placeholder where the previous Blockly version used to be, written as an update from version (mumble mumble) of Blockly, and it warns in advance about bumps on the way to a user-facing release. Meanwhile package.json reads version 2.1.27, and the tag list shows 2.1.25 on 2 October 2026, 2.1.26 on 3 October and 2.1.27 on 4 October. So the news section describes a release twenty one minor versions back, on a branch that was pushed on 3 October. Nothing on the page marks that announcement as historical.
Version numbers come out of your commit messages
The project uses semantic-release so that version bumps follow semver and dependents are not broken unexpectedly. That only works if commit messages carry the meaning, so semantic-release expects them to follow the conventional-changelog specification, and the repository enforces that with commitlint through a commitlint.config.js at the root. For contributors there is a helper that writes the message for you, installed globally:
npm install -g commitizen@latest cz-conventional-changelog@latestAfter that, commits go in through `git cz` instead of `git commit`. The visible consequence of the arrangement is the tag list: three patch releases on three consecutive days, which is what a project publishing from every merged commit looks like. There is a second config file, release.config.js, alongside a shared scratch-semantic-release-config package in devDependencies, so the release behaviour is configured in the repository rather than left to defaults. The trade-off is worth naming: a repository that bumps on commit content punishes a careless commit message with a wrong version number.
Unit tests need no setup, browser tests need Playwright once
There are two test suites and they have different setup costs, which the page is careful to separate. Unit tests run in jsdom and need nothing extra:
npm run test:unitBrowser tests run in Chromium through Playwright, and the browser has to be installed once after the dependency install:
npx playwright install chromium
npm run test:browserRunning everything is a third command:
npm testIn the package manifest those map onto vitest projects rather than onto separate runners: `test` is `vitest run`, `test:unit` is `vitest run --project unit` and `test:browser` is `vitest run --project browser`. So the suites share one runner and are selected by project name. The jsdom claim is scoped to the unit project only, and a fresh clone that skips the Playwright install will fail at the browser project rather than at install time, which is the usual first surprise for a new contributor.
Debugging a browser test needs headless turned off or PWDEBUG set
Two escape hatches are documented for a failing browser test, and both work on the same script. The first opens a visible browser window:
npm run test:browser -- --browser.headless=falseThe flag is passed straight through to the underlying browser runner, which is why the command form is `npm run` with an extra `--` before the option rather than a dedicated script. The second variant pauses on startup and opens devtools, using an environment variable rather than an argument:
PWDEBUG=1 npm run test:browserNeither is exposed as its own script in the manifest, so both are typed by hand at the terminal. What is worth noting is that this only applies to the browser project. Unit failures are debugged in whatever environment jsdom gives you, and the page offers nothing comparable for them, which follows from the unit suite having no real browser attached in the first place.
Three Blockly packages in dependencies, and no code generators
The dependency list is short and entirely Blockly. `blockly` is pinned to `^12.4.1`, with `@blockly/continuous-toolbox` at `^7.0.8` and `@blockly/field-colour` at `^6.0.11` alongside it. That is the whole runtime surface, and it is the concrete form of the announcement's claim about no longer being a fork: an upstream Blockly upgrade arrives by changing a version range rather than by merging a patch set. The second difference from Blockly is architectural. Unlike Blockly, Scratch Blocks does not use code generators, and instead leverages the Scratch Virtual Machine to create highly dynamic, interactive programming environments. That is the design decision worth understanding before adopting it, because it means the runtime and the block model live in another project, and this one supplies the design specification and the codebase for the interface. Like Blockly it is written in TypeScript and bundled with webpack.
Translations leave through Transifex and the English source is validated
Two scripts handle localisation, and they point in opposite directions. `i18n:push` runs `tx-push-src scratch-editor blocks msg/json/en.json`, which pushes the English source strings for the scratch-editor and blocks projects to Transifex. `i18n:src` runs `node scripts/validate-en-json.mjs`, a local validation pass over the English JSON. A `msg/` directory at the root holds the message files, and a `scratch-l10n` package sits in devDependencies, which is how translations come back in. So the source of truth is a checked-in English file, the round trip goes through an external translation service, and the check that catches a malformed file is a script you can run without the service. Nothing about that arrangement is explained in prose on the page; it is entirely in the manifest, which is where anyone changing a block label needs to look first.
npm test runs vitest only and linting is a separate command
The manifest carries lint and format commands that the default test command does not include. `test` is `vitest run`, and linting lives in `test:lint`, which is `eslint && prettier --check .`. Formatting writes instead of checking, through `format`, which is `prettier --write . && eslint --fix`. Both tools are configured in their own files at the root, eslint.config.mjs and prettier.config.mjs, so the rules are versioned with the code. Renovation is configured too, in a renovate.json5 at the root, which is the file to look at when a dependency bump needs to be held back. A `prepare` script runs husky and is written to never fail the install, so a machine without the hooks still installs cleanly. The practical upshot for a contributor is that a green `npm test` says nothing about style, and `test:lint` is a command you have to remember.
The published entry point is a single .mjs file with types beside it
The package manifest describes a very narrow published surface. `main` is `./dist/main.mjs` and `types` is `./dist/types/src/index.d.ts`, and the exports map has exactly one entry, the bare package, with an import condition, a default condition and a types condition all pointing at the same generated files. There are no subpath exports here, so a consumer has one entry point rather than a set of named entry points to choose between. The build is webpack, with `build` set to `webpack --mode production` and a separate `watch` script that adds `--watch`, plus a `start` script that serves and opens a browser in development mode. Two tsconfig files sit at the root, one for the build and one general, and the generated type output is derived from the source tree, which is why the types path contains `src/index.d.ts` inside it rather than pointing at a top level declaration file.
Editorial conclusion
scratch-blocks fits a team building a block-based editor on top of the Scratch Virtual Machine, and the dependency arrangement is the reason to choose it over maintaining a Blockly fork. Two things to plan around. The README's opening section still describes release 2.0, twenty one minor versions behind the package, so treat the architecture paragraph as current and the announcement framing as history. And the release cadence is daily, which means the version you depend on moves unless you pin it: semantic-release derives each bump from a commit message, so a patch release can be published the day a commit lands. Before wiring it into a build, check whether your own commit messages follow the conventional-changelog format, since that is what decides your next version number.
Frequently asked questions
how to use scratch blocks
Install and build with `npm ci` followed by `npm run build`, then run the suites with `npm run test:unit` for jsdom, `npm run test:browser` for Chromium after `npx playwright install chromium`, or `npm test` for everything. The getting started guide, FAQ and design documentation are in the repository wiki.
what is scratch blocks
A library for building creative computing interfaces, written in TypeScript and bundled with webpack. It builds on the Blockly library and depends on it rather than forking it, and it does not use Blockly code generators, instead leveraging the Scratch Virtual Machine to create the programming environments.
what are scratch blocks used for
It provides a design specification and codebase for building creative computing interfaces. Together with the Scratch Virtual Machine it allows rapid design and development of visual programming interfaces, and its runtime dependencies are blockly, @blockly/continuous-toolbox and @blockly/field-colour.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/scratchfoundation-scratch-blocks)Star history chart for your README
[](https://hysenlabs.com/projects/scratchfoundation-scratch-blocks)Was this useful?