Blockly's three stability lines: main, the beta channel, and what a patch release will not fix

Anything in main but not released can change without warning

The README separates three things that look identical in a clone: a release, a beta, and a commit. Pull requests go against main, main is where features land before they ship, and once something is in main the project expects it in the next release. The catch sits two sentences later. Features and APIs in main are subject to change until they are released, and anything that is in main but not released is subject to change without warning. Unreleased APIs may change radically, which is a wider permission than the two-release courtesy the project extends to shipped APIs.

The consequence for a team is concrete. If you pulled a commit from main because it contained a field, a theme, or a renderer you needed, the next merge can rewrite that API under your code. The version number that would warn you does not move, because the project uses semantic versioning and a new major version arrives only when a release is cut. Nothing in the repository layout flags which parts of a main checkout are frozen and which are not. The README's own instruction for people working on a production application is to take the release from npm or from the GitHub release page instead of the main branch, and that instruction is the whole difference between a moving target and a fixed one.

A new API gets one release of beta, then two releases of protection

Once a new API is released it is considered beta until the following release. After that, the project says it will do its best to avoid breaking an API that has been around for at least two releases. Two details make that promise weaker than it sounds. The README admits the team sometimes has to change an API after seeing how people use it, and the beta window itself sits before the two-release clock starts, so code written against a freshly released API gets one more scheduled release of stability and then no formal promise at all.

Patch versions are reserved for bug-fix patches between scheduled releases, and breaking changes take a new major version. So a signature you depend on cannot quietly move inside a patch release; it moves at a major version, which means a coordinated upgrade across your own code rather than a routine dependency bump you can schedule for a Tuesday. Teams that pin early to a new API trade that coordination cost for access to the feature, and teams that wait pay for it in lag. Neither is wrong, but the README's milestone is the one that matters: what is in main right now has no milestone attached to its stability at all.

Patch releases are held to crashes and unusable rendering

The project names the bar for a patch release narrowly. Breaking regressions get cherry-picked into patch releases when they are a crash during a standard action, or a rendering issue that makes Blockly unusable. Anything smaller waits for the next scheduled version. That is a useful filter for a reader deciding whether to install a patch and expect an annoyance to disappear: a misaligned connection or an occasional exception does not meet the stated bar, so the newest patch is not a fix for it.

The release tags show the cadence: blockly-v13.3.0 was published on 2026-09-10, blockly-v13.4.0 on 2026-10-13, and blockly-v13.4.1-beta.1 on 2026-11-02. The README says the beta channel may be less stable and its APIs are subject to change.

create-package takes a name and a --typescript flag; npm install takes neither

There are two documented ways in and they leave you in very different states. Starting a new project, the README points at the create-package tool:

npx @blockly/create-package app my-cool-blockly-app --typescript

The word app, then your package name, then the language flag. That gives you a project skeleton you can edit. Adding Blockly to something that already exists is one line:

npm install blockly

and that is the whole instruction. Neither command chooses a block set, registers a renderer, or tells you where a workspace file belongs, because those decisions are not encoded in the installer. The README routes both cases to docs.blockly.com for configuration and integration, and to a separate repository, blockly-samples, for worked examples and plugins. The library itself is written in TypeScript, but the flag on the scaffold command, not the package, decides the language of your host project. Budget for the gap between a clean install and a working editor, and read it as a documentation walkthrough rather than an automated step.

Blocks represent code concepts, and no execution step is documented

The README describes interlocking graphical blocks that stand for variables, logical expressions and loops, and says the point is to apply programming principles without worrying about syntax. What it does not contain is any step between a learner assembling blocks and code existing. No target language, no generator, no runtime, no statement about where a finished workspace goes after the user is done.

The repository layout points the same way. The root package.json is named blockly-repo, marked private, versioned 0.0.0, with workspaces at packages/* and packages/plugins/*. Top-level files are toolchain files: lerna.json, nx.json, eslint.config.mjs, commitlint.config.mjs, .prettierrc.js, AGENTS.md, CLAUDE.md, CHANGELOG.md. That is a library and its development apparatus, not an application with a server and a save path.

So adopting Blockly does not remove the hard part of the problem it visualizes. You still decide what the blocks mean when someone presses run, and you own that decision. The links the README offers are a live demo and the demos and plugins site in blockly-samples, and neither is described as a complete classroom environment. Expect to build the part around the editor.

Nx fans out the root scripts, and build leaves the docs package out

Inside a clone, build, test and lint are not compiler invocations. They are Nx fan-outs across the workspaces:

npm run build
npm run test
npm run lint

The build script is npx nx run-many -t build --exclude=blockly-docs, and test is npx nx run-many -t test. Only the default developer build drops the docs project; build-all removes the exclusion and build-docs targets blockly-docs on its own. A reader who only consumes the npm package will never run these, and a reader building from source should know that a plain build will not produce the documentation site.

Two smaller details matter if you plan to contribute. Lint runs as npm run lint --ws --if-present, so a workspace package that defines no lint script passes without complaint rather than failing the run. Formatting is checked separately by prettier --check ., and the devDependencies include prettier-plugin-organize-imports, which makes import order a machine-checked rule rather than something a reviewer argues about. Commit messages are governed by commitlint with the conventional config, so a pull request whose message does not parse as a conventional commit has a mechanical problem before anyone reads the diff.

One week to triage a bug, no schedule for the feature you wanted

The maintenance terms are stated in numbers, and they are small ones. Bugs are triaged within 1 week, which covers adding labels and assigning a milestone. Questions on the developer forum are actively monitored, with responses inside 2 working days. Then the README sets the boundary in the same breath: the team is small, so even a feature request that everyone agrees on may not be prioritized.

That limit is the one to plan around. A confirmed bug gets labels and a milestone, which is triage rather than a delivery date. An agreed feature request gets nothing on the schedule. The repository points external contributors at issues tagged Help Wanted, the ones the project thinks would suit outside help, which is a queue for people who want to write the code themselves rather than a forecast of maintainer capacity.

For a product built on Blockly, the practical effect is that the boundary of the library will not move for you on request. Work that sits outside it, such as a code generator for a language you need, or a persistence model that matches your curriculum, is yours to write and yours to keep working across major versions. Accessibility is the one place where the project commits broadly: the editor is usable with the keyboard alone, screen reader support is on by default, and conformance to WCAG 2.2 Level AA is published as VPAT reports at docs.blockly.com, which is a concrete artifact to point an auditor at.

Editorial conclusion

Adopt Blockly when your product is an editor embedded in a page you already control and your learners never need their work to run somewhere you did not build. Do not adopt it expecting a hosted coding environment, a target language, or an execution runtime, because the README documents none of those. Verify first that the block set, renderer and workspace file you need are covered by a plugin or a sample in blockly-samples, and pin to the npm release rather than a main branch commit, because the two-release protection the project offers does not cover code that has not shipped yet. The last push landed on 2026-11-02, so the source is moving faster than your pin.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. RaspberryPiFoundation/blockly on GitHub
4. README
5. Releases