A registry of 300 Blockly libraries where every block ships its own C++ generator

The repository is the product, and the product is a directory convention

The top-level listing is the design decision, so read it as a manifest rather than as source code. Every library sits in its own top-level directory named after the hardware part or the upstream Arduino library it wraps: BH1750, DS18B20, FastLED, LiquidCrystal_I2C, MAX31865, IRremote, Arduino_GFX, ESPUI, Blynk, Firmata, and several hundred more. The README calls this a rich ecosystem of more than 300 libraries, with internationalisation support for eleven languages. What the listing makes clear is that nothing sits between the directories and the platform. There is no central index of block categories, no shared build step that compiles all of them, and no runtime that loads them by convention. The single package.json at the root points its main field at a compliance validator rather than at anything a program would import, and its description calls the repository a collection of Arduino Blockly libraries plus a specification checking tool. The registry is therefore a source of material that a platform pulls from, and the root package is tooling for the people who maintain the material. That distinction matters for anyone who reads a registry as an index and assumes a resolver is hiding inside.

Eight files per library, and what each one obliges you to write

A library unit is defined by a fixed structure, and the definitions are separated by concern in a way that reveals where the real work sits. Block definitions live in block.json, the toolbox that decides where a block appears in the editor is toolbox.json, the npm package config is package.json, and user documentation is readme.md. An optional readme_ai.md is described as AI documentation, and the root README points at a README_AI.md intended for LLM understanding and usage, which makes a machine-readable second readme a first-class deliverable rather than a courtesy. Below that sits a src.7z described as the Arduino library source, compressed, and an i18n directory holding per-language JSON files with zh_cn.json and en.json as the named examples. Three of those files are configuration a Blockly runtime reads, two are documentation for humans and models, and one is a binary archive. The ratio tells you the cost model: adoption is cheap because the block definitions and the toolbox entry are declarative, and maintenance is not cheap because every library carries its own generator, its own translations and its own docs that a repository-wide audit will eventually look at.

generator.js is the contract, and it makes the compiler part of the runtime

Each library ships a generator described as the Arduino code generator, which is the single most consequential line in the structure. A block in this design is a template that emits C++ for the board, so the board's toolchain becomes a runtime dependency of a block a child drags onto a canvas, and the Arduino library the block wraps must be present in that toolchain's include path. The upside is directness: a block can call any function of any Arduino library the board can compile, with no intermediate protocol to design, and the learner sees readable generated code instead of a wire format. The price is that nothing runs until the whole sketch compiles, and errors surface as compiler output rather than as a friendly message at the block. Set that against the other entry in the same directory listing, Firmata, which represents the opposite strategy: firmware already flashed on the board, blocks talking to it over a serial link. Both live here, so the registry is not making a single architectural argument, it is carrying two. A school with locked firmware and a fixed hardware budget is better served by the second, and a school with an Arduino toolchain and a workshop full of varied sensors is better served by the first.

Why the firmware source is a 7z archive inside a git repository

Compressing the vendored Arduino source into a single archive per library is a choice with consequences. A plain directory of C++ files would be reviewable: a pull request touching a generator could show the diff of the vendored source too, and a reviewer could see whether a fix came from upstream or from the library author. An archive turns that into an opaque blob that changes without a readable diff, in a repository whose stated workflow is fork, branch, commit, push, pull request. It also puts a requirement in front of every contributor, since unpacking and repacking a 7z file is not something a browser-based code review or a light editor handles, and a mismatched repack produces a pull request that looks like a one-line change and is not. The upside is real and worth naming: the repository stays small, vendored code from many upstream projects does not clutter search results, and a library directory keeps a fixed shape that tooling can validate. The trade is that the compressed payload is not what the compliance scripts in the root package.json appear to address, since every script in that list is about block definitions, readme format or generator coverage.

Compliance is a script suite with diff flags, and a set of migrations

The root package.json is the most informative document in the repository, because it is a list of checks. Running the default validation executes a compliance script for a single library; a variant takes an all flag across the registry, and another takes a changed flag, which is the tell that a registry of this size cannot afford a full sweep on every push. The readme family is larger still, with separate scripts for a plain check, an audit that adds strict and absolute-path flags and emits JSON, a changed-files variant, a contract check that adds tracked, ai-only and strict-absolute flags, a runtime-contract check, a runtime compile check, a dynamic-shapes check, a generator-coverage check and a cross-library example checker. Then there are migrations, five of them, covering field variables, table statements, block tables, examples and example calls. Two things follow. First, the checks are shaped by what a large monorepo needs, which is incremental and machine-readable output rather than a single pass-fail gate, and the README states that library validation runs in GitHub Actions. Second, the existence of five migration scripts for readme content means the documentation contract was still moving while hundreds of libraries already existed, so a library can be valid today and non-conforming after the next migration, and a contributor needs to know which target the maintainers are currently enforcing.

Installing one library, and running the checks before you open a pull request

The install path is a single command run in the terminal of an aily blockly project, and the README writes it with a placeholder in place of a real library name, so a working install substitutes the actual published package name for the placeholder text:

npm i @aily-project/lib-library-name

The scope is worth being precise about. This is an npm install inside a project that already has the aily blockly platform, not a global tool, and the repository itself is not what you install. If your organisation cannot use the public registry, the documentation index lists a private deployment guide for setting up a private npm registry, which is the escape hatch for schools that need an audited mirror. The same package.json gives you the checks to run locally, and these are the lines as declared:

  "scripts": {
    "validate": "node .scripts/validate-library-compliance.js",
    "validate:all": "node .scripts/validate-library-compliance.js --all",
    "validate:changed": "node .scripts/validate-library-compliance.js --changed",

Expect the all form to walk every library directory and the changed form to inspect only what your working tree touched, which is the difference between a quick pre-commit check and a full audit. For the first real use of a new library, the shortest path is: install the package, open the aily blockly project, look for the block in the toolbox position that toolbox.json defines rather than assuming it landed in a default category, and generate the code to see what the generator emits. That last step matters more here than in a runtime-bound Blockly project, because the generated text is the actual behaviour, and reading it is how a teacher checks that a block does what its readme claims.

Contributing is three git commands and a pull request

The contribution path is the least interesting part of the documentation and the most honest about what the project is: a directory, a branch and a review. Fork the repository, create a feature branch with the naming convention the README spells out, commit, push, open a pull request.

git checkout -b feature/my-new-lib

git commit -m 'feat: add my-new-lib'

git push origin feature/my-new-lib

A contributor also inherits the structure problem, because a new library means writing the block definitions, the toolbox entry, the generator, the readme, the optional AI readme and the translations for at least the languages the project expects, and then making sure the validation script is satisfied before the pull request is worth opening. The documentation index points at separate guides for library standards, development and debugging, internationalisation conventions, contribution rules, private registry setup, a library test status table and a roadmap of planned libraries, which tells you that the process is documented in more depth than the root readme shows.

No releases, no root licence, and a very recent push

The maintenance picture has one strong signal and one gap. The strong signal is cadence: the last push to the main branch was on 2026-09-20, which is days before the date this was written, and a repository of several hundred libraries with a compliance toolchain and a documentation site is not being touched by an occasional contributor. The gap is that the repository has no GitHub releases at all, so there is no tag, no changelog and no versioned snapshot of the registry to pin against, and the root package.json reports version 1.0.0 while individual library packages carry their own versions inside their own directories. The licence situation has the same shape: the README states that each library follows its original open-source licence and points you at the documentation in the library directory, which is a sensible answer for a vendored collection and an unhelpful one for anyone who needs a single answer about the registry as a whole, since no root licence is declared. For a classroom, that is a paperwork task to schedule. Check the licence inside each library you install, and pin npm versions in your own project rather than relying on the registry to give you a stable set.

Editorial conclusion

Adopt this registry if you are teaching hardware programming to beginners on a board with a working Arduino toolchain, because the generator approach gives a block full access to any Arduino library call and hides the C++ from the learner, and skip it if your classroom hardware is locked to a fixed firmware, since the Firmata-style path in the same listing is the better fit there. Check four things before you commit: which library the npm name maps to, because the README's install command is a placeholder and the top-level directory names do not reveal the published package names; the licence of the specific library you are pulling, since the repository states that each library keeps its original open-source licence and says nothing about the registry itself; whether the i18n directory covers the languages you need, given that the registry advertises eleven; and that the board's compiler accepts what generator.js emits, since the validation scripts check the repository's own rules and do not compile your sketch. There are no tagged releases of the registry, so pinning a working combination means pinning npm package versions yourself. The last push was on 2026-09-20.

Frequently asked questions

Official sources

1. ailyProject/aily-blockly-libraries on GitHub
2. Issues
3. README