Building Blockly

Blockly is made up of over a hundred JavaScript files. Loading these over the Internet is a sluggish experience for end users. To make Blockly load faster, it can be compressed down to half a dozen files totaling about 720kb.

Blockly also uses advanced JavaScript features in its uncompressed code that may not be compatible with all browsers. Building the code transpiles it down to es5, which is generally compatible with older browsers such as Internet Explorer. Thus, it's important that you serve only the compressed code to your end users.

Blockly comes with both the source code and compressed files, so there is no need to build Blockly unless you are hacking in the core, blocks, generators, or msg directories.

Note: In this documentation we often use "build" and "compress" interchangeably, because our build process also compresses the code.

Compressing Blockly is extremely simple. Just run the following command:

npm run build

This command takes about 20 seconds and uses Google's Closure Compiler to rebuild several key files:

• The contents of the core/ directory becomes blockly_compressed.js.
• An alternative file named blockly_uncompressed.js is generated (see below).
• The contents of the blocks/ directory becomes blocks_compressed.js.
• The contents of the generators/ directory becomes javascript_compressed.js, python_compressed.js, php_compressed.js, lua_compressed.jsand dart_compressed.js.
• Any changes to messages.js file are mapped onto the msg/json files, after which the msg/js files are regenerated.

The output of this script is located in the build directory, which is not checked in to git. To copy this output to the top-level built files, run npm run checkin:built. You only need to do this if you need the top-level files to reflect your changes (such as accessing the playground directly via file url, which is not recommended, or if you are a Blockly team member preparing for a new release). You do not need to do this if you are testing Blockly by running one of the playgrounds or if you are making a routine change to Blockly.

Build Scripts

You may not want to build all of Blockly for your development process. You can use the following commands to build a subset of the files:

• npm run build builds everything.
• npm run build:blocks builds blocks_compressed.
• npm run build:compressed builds blockly_compressed.
• npm run build:core builds blockly_compressed, blockly_uncompressed, and blocks_compressed.
• npm run build:generators builds every <language>_compressed.js file.
• npm run build:langfiles builds every msg/js/<LANG>.js file.
• npm run build:uncompressed builds blockly_uncompressed.

The output of each of these scripts is in the build directory, as above.

Compressed Mode

As a result of compression, Blockly can be loaded with a small number of HTTP requests:

<script src="blockly_compressed.js"></script>
<script src="blocks_compressed.js"></script>
<script src="javascript_compressed.js"></script>
<script src="msg/js/en.js"></script>

Remember that as a developer you probably have a better Internet connection and a more modern browser than your users. Compressing the code makes a tremendous difference for users.

Uncompressed Mode

That said, compressed code is difficult to read. When modifying core Blockly, use uncompressed mode. Let's pull apart the four scripts listed above and find their uncompressed versions:

Note: uncompressed Blockly may use ES6 language features, and is not compatible with Internet Explorer. If you are releasing to IE, make sure you use the compressed files.

Core

<script src="blockly_compressed.js"></script>

This one is easy. Just change "compressed" to "uncompressed":

<script src="blockly_uncompressed.js"></script>

The blockly_uncompressed.js file is generated by the build script and loads all the required core/ files.

Blocks

<script src="blocks_compressed.js"></script>

If one is hacking the default blocks, replace the compressed blocks file with the original source files:

<script src="blocks/logic.js"></script>
<script src="blocks/loops.js"></script>
<script src="blocks/math.js"></script>
<script src="blocks/text.js"></script>
<script src="blocks/lists.js"></script>
<script src="blocks/colour.js"></script>
<script src="blocks/variables.js"></script>
<script src="blocks/procedures.js"></script>

Generators

<script src="javascript_compressed.js"></script>

If one is hacking the default blocks, replace the compressed blocks file with the original source files (change "javascript" to "python", "php", "lua", or "dart" as needed):

<script src="generators/javascript.js"></script>
<script src="generators/javascript/logic.js"></script>
<script src="generators/javascript/loops.js"></script>
<script src="generators/javascript/math.js"></script>
<script src="generators/javascript/text.js"></script>
<script src="generators/javascript/lists.js"></script>
<script src="generators/javascript/colour.js"></script>
<script src="generators/javascript/variables.js"></script>
<script src="generators/javascript/procedures.js"></script>

Language

<script src="msg/js/en.js"></script>

Replace the language file (en, ru, vi, etc) with messages.js:

<script src="msg/messages.js"></script>