This document is aimed at developers who wish to create their own applications that incorporate Blockly as a code editor. It is assumed that one is generally familiar with Blockly's usage, and one has a basic understanding of HTML and JavaScript.
After reading this document, you may wish to try the Getting Started codelab.
Overview
Blockly is designed to easily install into your web application. Users drag blocks around, Blockly generates code, your application does something with that code. From your application's point of view, Blockly is just a textarea in which the user types syntactically perfect JavaScript, Python, PHP, Lua, Dart, or another language.
Blockly is 100% client side, requiring no support from the server. There are no 3rd party dependencies. Everything is open source.
Get the Code
Recommended: npm
Blockly is published on the npm registry and yarn registry. We recommend accessing Blockly through a package manager because:
- It is easier to stay up to date with changes in Blockly
- It encourages using plugins instead of monkeypatching Blockly
If you need more convincing you can watch our 2021 Blockly on npm talk. If you are already using a package manager, you can install Blockly with
npm install --save blockly
You can reference Blockly in your application code with:
import Blockly from 'blockly';
This will import the default packages. For more information, see the package readme.
Unpkg
If you aren't using a package manager for your project, but you still want to easily stay up to date, you can use unpkg.
<script src="https://unpkg.com/blockly/blockly.min.js"></script>
Unpkg grabs the latest version of the published code, so there won't be any version control with this method. It is great for demos or quick experiments, and we use it in many codelabs.
GitHub
You can also download the compressed code from our GitHub releases. However, this requires you to manually download the code at regular intervals in order to receive the latest updates and fixes to Blockly.
Once you've downloaded Blockly, you can add the following to your application code to load it:
<script src="blockly_compressed.js"></script>
You will probably also want to load Blockly's built-in blocks, at least one language generator, and at least one language file.
<script src="blocks_compressed.js"></script>
<script src="javascript_compressed.js"></script>
<script src="msg/js/en.js"></script>
Injecting Blockly
After you have acquired Blockly, you then need to inject it into a div on your application page.
→ More info on injecting fixed-sized Blockly...
More advanced web pages may wish to allow Blockly to resize to fill the page.
→ More info on injecting resizable Blockly...
Configuration
Blockly is highly configurable. For instance, you may set the theme or renderer on a workspace, set a workspace to RTL mode, or select from a variety of zoom and scroll modes.
Configuration is done per-workspace, by passing a configuration struct when injecting a Blockly workspace.
→ More info on configuring a workspace...
Defining Blocks
In addition to the default blocks that come with Blockly, custom blocks need to be built to call your web application's API. An example is this maze game which has custom blocks for movement.
→ More info on creating custom blocks...
Code Generators
Blockly is not a programming language, one cannot 'run' a Blockly program. Instead, Blockly can translate the user's program into JavaScript, Python, PHP, Dart, or some other language.
→ More info on code generators...
Importing and Exporting Blocks
If your application needs to save and store the user's blocks and restore them at a later visit, use this call to serialize to JSON:
var json = Blockly.serialization.workspaces.save(workspace);
And deserializing JSON to blocks is just as easy:
Blockly.serialization.workspaces.load(json);