Blockly is made up of over a hundred TypeScript files. These must be compiled
by the TypeScript compiler,
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
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;
as readable as the original TypeScript sources, obviating the need to depend
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
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.
If you've made local changes and want to make sure they've not broken the build or any tests, run
to build Blockly and run its test suite.
If you want to test local changes in the browser, run
This compiles Blockly and opens a web browser pointing at the Blockly playground running Blockly in uncompressed mode.
Any files in
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
cdto 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
Detailed Script Reference
This section lists the principle
scripts in Blockly's
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.
npm run clean cleans up any previous builds by deleting the
dist/ directories. Useful for fixing arcane build failures, particularly
ones caused by renaming a source file.
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.
npm run langfiles generates the compiled language files in
from the messages files in
npm run tsc runs the TypeScript compiler on the contents of the
generators/ directories, and outputs individual
npm run minify runs
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
- The contents of
- The contents of
- The contents of
- And likewise for
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.
npm run build runs the
langfiles tasks. This should do
everything that's needed to load the Blockly playground in either compressed
or uncompressed mode.
npm run package runs the
build tasks and then:
- Applies a UMD wrapper the files in
build/msg/, placing the wrapped versions in
- Adds various additional support files to
dist/, with UMD wrappers where applicable.
npm run publish is used by the Blockly team to publish the
package. It depends on Google-internal infrastructure so is not useful
to external developers.
npm run lint runs ESLint, performing static analysis
of the Blockly source code to find problems.
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.