Blockly's Build Scripts

Blockly is made up of over a hundred TypeScript files. These must be compiled by the TypeScript compiler, tsc, into JavaScript before they can be used. This creates an equally large number of .js files which are suitable for local testing, but loading such a large number of files over the Internet is a sluggish experience for end users. To make Blockly load faster, the Closure Compiler is used to compress (minify) and combine them into a half a dozen files ("bundles" or "chunks") with total size less than half that of uncompressed files.

In the process, code using the latest ECMAScript features—ones which may not be compatible with all browsers—are transpiled down to ES6, which is generally compatible with most widely-used browsers. Thus, it's important that you serve only the minified code to your end users.

The google/blockly repository contains only the source code. It previously also contained the build products, but since 2019 the minified bundles have been published as the blockly NPM package and since 2022 also attached as a .tgz file to each GitHub release, so there is no need to build Blockly unless you are hacking on Blockly itself—in particular on files in the core, blocks, generators, or msg directories.

The process of building, testing, and publishing Blockly is automated using npm scripts to run Gulp tasks. This page documents the principle scripts and what each does.

Compressed and Uncompressed Mode

Loading Blockly directly from the individual .js files generated by the TypeScript compiler is referred to as "uncompressed mode". Because it avoids several slow build steps, this facilitates a quick edit-compile-run cycle; it also facilitates debugging as the JavaScript code being executed is nearly as readable as the original TypeScript sources, obviating the need to depend on sourcemaps.

Loading Blockly from the minified bundles is referred to as "compressed mode". This is the best way to test changes to Blockly when using it as a dependency of another package, because it tests (an unpublished version of) the blockly npm package.

N.B.: There are some places in the blockly repository where the terms "uncompiled mode" and "compiled mode" are used as synonyms for "uncompressed mode" and "compressed mode" respectively. This usage made sense in the past as Closure Compiler was used to compress (minify) the code, but now the the TypeScript compiler is always needed, even in uncompressed mode, so this alternative terminology is potentially confusing and discouraged.

Quick Start

If you've made local changes and want to make sure they've not broken the build or any tests, run
```
npm test
```
to build Blockly and run its test suite.
If you want to test local changes in the browser, run
```
npm start
```
This compiles Blockly and opens a web browser pointing at the Blockly playground running Blockly in uncompressed mode.

Any files in core/, blocks/ and generators/ that are modified are automatically recompiled; reload the browser tab to see the changes.
To build your locally-modified version of Blockly and test it, in compressed mode, as a dependency of another npm package, run
```
npm run package
```
to build Blockly package, then
```
cd dist && npm link
```
to tell npm where to find the compiled files, and then cd to your project's directory before running
```
npm link blockly
```
to have your package use the freshly-compiled version of Blockly in place of the published blockly package.

Detailed Script Reference

This section lists the principle scripts in Blockly's package.json file with an explanation of what they do.

These scripts generate files in two places:

Files in the build/ subdirectory are intermediary files used for local testing or ingested by later parts of the build pipeline.
Files in the dist/ subdirectory form the contents of the published npm package.

Neither directory is tracked in the blockly git repository.

`clean`

npm run clean cleans up any previous builds by deleting the build/ and dist/ directories. Useful for fixing arcane build failures, particularly ones caused by renaming a source file.

`messages`

npm run messages updates the messages files in msg/json/ with any changes that have been made to msg/messages.js, and should be run after each time that file is modified.

`langfiles`

npm run langfiles generates the compiled language files in build/msg/ from the messages files in msg/json.

`tsc`

npm run tsc runs the TypeScript compiler on the contents of the core/, blocks/ and generators/ directories, and outputs individual .js files to build/src/.

`minify`

npm run minify runs closure-make-deps and closure-calculate-chunks to determine how to divide up the compiled .js files into chunks (minified bundles), after which it runs closure-compiler to create the chunks as follows:

The contents of build/src/core/ become dist/blockly_compressed.js.
The contents of build/src/blocks/ become dist/blocs_compressed.js.
The contents of build/src/generators/javascript/ (plus build/src/generators/javascript.js) become dist/javascript_compressed.js.
And likewise for dart, lua, php, and python.

The generated chuks use a wrapper to ensure compatibility with the Universal Module Definition so no extra processing is needed before they are included in the package.

`build`

npm run build runs the minify and langfiles tasks. This should do everything that's needed to load the Blockly playground in either compressed or uncompressed mode.

`package`

npm run package runs the clean and build tasks and then:

Applies a UMD wrapper the files in build/msg/, placing the wrapped versions in dist/msg/.
Adds various additional support files to dist/, with UMD wrappers where applicable.

`publish`

npm run publish is used by the Blockly team to publish the blockly npm package. It depends on Google-internal infrastructure so is not useful to external developers.

`lint`

npm run lint runs ESLint, performing static analysis of the Blockly source code to find problems.

`test`

npm test (or npm run test) runs the package task and then runs various automated tests (including running ESLint). This should be run—and pass—on any code submitted as a pull request against the blockly repository.