blockly README

The project's README from github.com/RaspberryPiFoundation/blockly. As one markdown file: README.md.

Blockly

Blockly is a library that adds a visual code editor to web apps. The Blockly editor uses interlocking, graphical blocks to represent code concepts like variables, logical expressions, loops, and more. It allows users to apply programming principles without having to worry about syntax or the intimidation of a blinking cursor on the command line. All code is free and open source.

An example program built with Blockly that checks for a game over state

Getting Started with Blockly

Blockly has many resources for learning how to use the library. You can try a live demo or visit our developer site to read the documentation on how to get started, configure Blockly, and integrate it into your application. The developer site also contains links to:

Installing Blockly

If you're starting a new project using Blockly, you can bootstrap it using our create-package tool:

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

Or, if you're adding Blockly to an existing project, just install it with npm:

npm install blockly

Getting Help

blockly-samples

We have a number of examples which demonstrate various techniques to include and extend the Blockly library. These examples can be found in another repository called blockly-samples.

Plugins

A plugin is a self-contained piece of code that adds functionality to Blockly. Plugins can add fields, define themes, create renderers, and much more. For more information, see the Plugins documentation.

Contributing to Blockly

Want to make Blockly better? We welcome contributions to Blockly in the form of pull requests, bug reports, documentation, answers on the forum, and more! Check out our Contributing Guidelines for more information. You might also want to look for issues tagged "Help Wanted" which are issues we think would be great for external contributors to help with.

Releases

We release new versions on npm and GitHub releases, and then update our docs and demo pages. If there are breaking regressions, such as a crash when performing a standard action or a rendering issue that makes Blockly unusable, we will cherry-pick fixes into patch releases. The releases page has a list of all releases.

We use semantic versioning. Releases that have breaking changes or are otherwise not backwards compatible will have a new major version. Patch versions are reserved for bug-fix patches between scheduled releases.

We now have a beta release on npm. If you'd like to test the upcoming release, or try out a not-yet-released new API, you can use the beta channel with:

npm install blockly@beta

As it is a beta channel, it may be less stable, and the APIs there are subject to change.

Branches

Most development happens in the main branch. Pull requests should typically be made against main. This branch should be stable; features that aren't ready yet should be merged to a feature branch instead. Once something is in main we expect it to be part of the next release. However, features and APIs here are subject to change until they are released. If you're working on a production application using Blockly, you should use the release from npm or the GitHub release page, not the main branch.

Larger changes may have their own branches until they are good enough for people to try out. These will be developed separately until we think they are almost ready for release. They will be merged into main when ready.

New APIs

Once a new API is released, it is considered beta until the following release. We generally try to avoid changing an API after it has been released, but sometimes we need to make changes after seeing how an API is used. If an API has been around for at least two releases we'll do our best to avoid breaking it.

Unreleased APIs may change radically. Anything that is in main but not released is subject to change without warning.

Issues and Milestones

We typically triage all bugs within 1 week, which includes adding any appropriate labels and assigning it to a milestone. Please keep in mind, we are a small team so even feature requests that everyone agrees on may not be prioritized.

Accessibility

Although Blockly is built around drag-and-drop, it is fully usable with the keyboard alone. Blockly is also accessible to screenreader users by default. We provide Accessibility Conformance Reports in the VPAT format that outline Blockly's conformance to WCAG 2.2 Level AA.

blockly (RaspberryPiFoundation/blockly)

Searching Database…

13.6K ·GitHub
Blockly
What is this?Blockly is a library that adds a drag-and-drop visual code editor to web apps, using interlocking graphical blocks to represent variables, logical expressions, loops, and other code concepts instead of raw syntax.
Is this a standalone app or a library I embed in my own site?It is a library you embed into your own web application; it is not a finished app by itself. You install it and integrate the editor into your project's UI.
How do I add Blockly to a project?For a new project, bootstrap it with the create-package tool; for an existing project, install it via npm.
Do I need Node and npm to work with this?Yes, Blockly is distributed and installed through npm, and the monorepo's scripts run via npx/nx, so a Node.js and npm setup is expected.
Is the API stable, or can things break between versions?Code on the main branch and unreleased APIs can change radically without warning; even released APIs are only considered stable after surviving two releases, and breaking changes bump the major version.
Who is this aimed at?Developers building educational or beginner-friendly coding tools who want to let users program with blocks instead of typed syntax, avoiding intimidation from a blank command line.
Is Blockly accessible to users who can't use drag-and-drop?Yes, despite being built around drag-and-drop, Blockly is fully usable with the keyboard alone and is accessible to screen reader users by default, with published Accessibility Conformance Reports in VPAT format against WCAG 2.2 Level AA.
Can I extend Blockly with custom functionality?Yes, through plugins, which are self-contained pieces of code that can add fields, define themes, create custom renderers, and more; there is also a separate blockly-samples repo with example integrations.
Is there a way to try Blockly before integrating it?Yes, the developer site offers a live demo along with Getting Started articles and codelabs to learn the library before installing.
Can I try unreleased features early?Yes, there is a beta channel published on npm for testing upcoming releases and not-yet-released APIs, though it may be less stable.
What are similar projects?rete, dnd-kit, chakra-ui, plate, handsontable, tambo, MathJax, lexical
Which topics is it in?visual-programming, accessibility, ui, framework, education, npm, frontend, apache-2.0, nodejs, library, typescript, javascript
Creator
RaspberryPiFoundation
Size
185.2 MB
Stars
13.6K
Updated
CommitOct 16Releaseblockly-v13.4.0Oct 13
Age
12y
Commits · 90 Days