Skip to content

docs: update advanced compilation docs #10234

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
zspriggs merged 3 commits into from
Aug 5, 2026
+29 −116
Merged

docs: update advanced compilation docs #10234

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6e9af99
docs: rm outdated tutorial
zspriggs Aug 5, 2026
eba68a4
docs: advanced comp edits
zspriggs Aug 5, 2026
86e35bc
docs: fix playground link
zspriggs Aug 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
143 changes: 28 additions & 115 deletions packages/docs/docs/guides/contribute/core/building_and_compilation/advanced.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,133 +1,46 @@
---
description: Reducing the size of Blockly using Closure Compiler.
description: Blockly's support for advanced compilation with Closure Compiler
title: Advanced compilation
image: images/blockly_banner.png
---

# Advanced compilation

The regular [build process](/guides/contribute/core/building) uses Google's online JavaScript compiler to reduce Blockly to a half a dozen files totaling about 720kb (160kb zipped). Alternatively one can use the Google's offline JavaScript compiler in "advanced compilation" mode which has a number of advantages:
The regular [build process](/guides/contribute/core/building_and_compilation/building) uses the
[Closure Compiler](https://developers.google.com/closure/compiler) to compress
Blockly. Although the regular build uses
[`SIMPLE_OPTIMIZATIONS`](https://developers.google.com/closure/compiler/docs/compilation_levels#simple_optimizations)
mode, Blockly also supports the use of
[`ADVANCED_OPTIMIZATIONS`](https://developers.google.com/closure/compiler/docs/compilation_levels#advanced_optimizations)
mode.

- Total Blockly size reduced to 300kb (100kb zipped) due to tree shaking.
- Faster build times and no network traffic due to local compiler execution.
- Unlimited compilations (the online compiler is rate-limited).
:::warning
Unless you have a specific need to further reduce the compressed size of
Blockly, you should avoid `ADVANCED_OPTIMIZATIONS` mode. Instead,
you can use the compressed version of Blockly from [npm](https://www.npmjs.com/package/blockly).
:::

## Setup
## Advanced compilation test

For the purposes of this minimal tutorial, start by creating a new directory in the Blockly root directory.
Blockly contains a test which builds Blockly and a small test app using
`ADVANCED_OPTIMIZATIONS` to ensure that new changes remain compatible with
`ADVANCED_OPTIMIZATIONS` mode.

### Download Closure Compiler.

Download [`compiler.jar`](https://unpkg.com/google-closure-compiler-java/compiler.jar), rename it to `closure-compiler.jar`, and place it in your directory.

Verify that your Java Runtime Environment can run the compiler by running this
on the command line:

```shell
java -jar closure-compiler.jar --version
```

### Boiler Plate

First, create an HTML file which defines a minimal Blockly toolbox and a `div`
in which to inject it. To do so, create a file in your directory called
`index.html` that contains this code:

```html
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<title>Blockly: Advanced Compilation</title>
<script src="main_compressed.js"></script>
<script src="../msg/en.js"></script>
</head>
<body>
<h1>Blockly: Advanced Compilation</h1>
<div id="blocklyDiv" style="height: 480px; width: 600px;"></div>
<xml id="toolbox" style="display: none">
<block type="controls_if"></block>
<block type="logic_compare"></block>
<block type="controls_repeat_ext"></block>
<block type="math_number"></block>
<block type="math_arithmetic"></block>
<block type="text"></block>
<block type="text_print"></block>
</xml>
</body>
</html>
```

Be sure to edit the language path (`../msg/en.js`) as required for
your path to Blockly and for your desired language.

Second, create a JavaScript file that loads Blockly and any necessary message
files or block definitions, then injects Blockly into the provided `div`.
To do so, create a file in your directory called `main.js` that contains
this code:

```js
goog.provide('Main');
// Core
goog.require('Blockly.requires');
// Blocks
goog.require('Blockly.Constants.Logic');
goog.require('Blockly.Constants.Loops');
goog.require('Blockly.Constants.Math');
goog.require('Blockly.Constants.Text');

Main.init = function () {
Blockly.inject('blocklyDiv', {
toolbox: document.getElementById('toolbox'),
});
};
window.addEventListener('load', Main.init);
```

### Compile

Compile `main.js`, Blockly, and Closure Library together by running the
Closure Compiler from the command line:

```shell
java -jar closure-compiler.jar --js='main.js' \
--js='../blocks/**.js' \
--js='../core/**.js' \
--js='../generators/**.js' \
--generate_exports \
--externs ../externs/svg-externs.js \
--compilation_level ADVANCED_OPTIMIZATIONS \
--dependency_mode=PRUNE --entry_point=Main \
--js_output_file main_compressed.js
```

Or by using our advanced compilation script:
This `ADVANCED_OPTIMIZATIONS` test is called `compileAdvancedCompilationTest()`
and located in `packages/blockly/scripts/gulpfiles/build_tasks.mjs`.
The associated test app is located in `packages/blockly/tests/compile/`.

If you want to run this `ADVANCED_OPTIMIZATIONS` test locally, you can use:
```
npm run test:compile:advanced
```

Point a browser at `index.html` to verify everything worked.

### Even More Advanced

For even greater reductions in size, you can include only the Blockly components
that your application actually uses. For example, if your application isn't
configured to have a trashcan, then you can remove the trashcan from the list
of components that are compiled in. To do so, delete the requirement for
`Blockly.requires` from your code:

```js
// Core
goog.require('Blockly.requires');
```

In its place, open `core/requires.js` and copy all the require statements into
your code. You can then comment out the ones you don't need.
## Use advanced compilation

Note that the Closure Compiler preserves licences in the compiled output.
Feel free to strip the Apache licenses from this output file to reduce the
size further.
Since `ADVANCED_OPTIMIZATIONS` includes aggressive renaming, you must compile
Blockly *with* your own app in order to use it.

The Closure Compiler has a lot of features and options, do check out their
[documentation](https://developers.google.com/closure/compiler/docs/gettingstarted_app).
You can reference the [advanced compilation test](#advanced-compilation-test) and
the associated test app as an example of how to use `ADVANCED_OPTIMIZATIONS`
mode on your own project. You can also consult the [Closure Compiler documentation](https://developers.google.com/closure/compiler/docs/api-tutorial3)
on advanced compilation.
2 changes: 1 addition & 1 deletion packages/docs/docs/guides/contribute/core/testing/playground.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,7 +117,7 @@ the `test/playground.html` file in your browser. This is still possible with the
simple and multi playgrounds, but it is no longer recommended. If you do this,
the playground will detect that you are not running a local server and
automatically use compressed Blockly files (see the
[Building Blockly page](/guides/contribute/core/building) for more
[Building Blockly page](/guides/contribute/core/building_and_compilation/building) for more
info) and whenever you change something in core Blockly, you will have to
rebuild core and stage the changes. You can still access these pages if hosted
on a remote server, such as our example hosted on our demo site. The background
Expand Down
Loading