From 6e9af99cd1fc0fcd1635181bfc73a0d25bceb073 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zo=C3=AB=20Spriggs?= Date: Wed, 5 Aug 2026 12:30:27 -0400 Subject: [PATCH 1/3] docs: rm outdated tutorial --- .../building_and_compilation/advanced.mdx | 143 ++++-------------- 1 file changed, 28 insertions(+), 115 deletions(-) diff --git a/packages/docs/docs/guides/contribute/core/building_and_compilation/advanced.mdx b/packages/docs/docs/guides/contribute/core/building_and_compilation/advanced.mdx index 6d707386843..c35e96654f5 100644 --- a/packages/docs/docs/guides/contribute/core/building_and_compilation/advanced.mdx +++ b/packages/docs/docs/guides/contribute/core/building_and_compilation/advanced.mdx @@ -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) 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). +## Build test -## Setup +Blockly includes a test (`compileAdvancedCompilationTest()`) in +`packages/blockly/scripts/gulpfiles/build_tasks.mjs` which builds Blockly and a +small test app using `ADVANCED_OPTIMIZATIONS` to ensure compatibility. -For the purposes of this minimal tutorial, start by creating a new directory in the Blockly root directory. - -### 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 - - - - - Blockly: Advanced Compilation - - - - -

Blockly: Advanced Compilation

-
- - - -``` - -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 test serves as an example of using `ADVANCED_OPTIMIZATIONS`. The test app +can be found in `packages/blockly/tests/compile/`. +You can run this test via: ``` 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'); -``` +This test is also run automatically as part of Blockly's broader build suite, so +that new changes remain compatible with `ADVANCED_OPTIMIZATIONS`. -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. +## Using 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. +:::warning +Unless you need to reduce compressed size of Blockly even more, you +should avoid `ADVANCED_OPTIMIZATIONS` mode. Instead, +you can use the compressed version of Blockly from [npm](https://www.npmjs.com/package/blockly). +::: -The Closure Compiler has a lot of features and options, do check out their -[documentation](https://developers.google.com/closure/compiler/docs/gettingstarted_app). +Since `ADVANCED_OPTIMIZATIONS` includes aggressive renaming, you must compile +Blockly *with* your own app in order to use it. You can use the +[advanced compilation test](#build-test) as a reference for how to do this. +You may also want to consult the +[Closure Compiler documentation](https://developers.google.com/closure/compiler/docs/api-tutorial3). From eba68a43dc6af87a0a8f0ce57a1a104f0da83ff1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zo=C3=AB=20Spriggs?= Date: Wed, 5 Aug 2026 14:25:10 -0400 Subject: [PATCH 2/3] docs: advanced comp edits --- .../building_and_compilation/advanced.mdx | 44 +++++++++---------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/packages/docs/docs/guides/contribute/core/building_and_compilation/advanced.mdx b/packages/docs/docs/guides/contribute/core/building_and_compilation/advanced.mdx index c35e96654f5..4678f8d578d 100644 --- a/packages/docs/docs/guides/contribute/core/building_and_compilation/advanced.mdx +++ b/packages/docs/docs/guides/contribute/core/building_and_compilation/advanced.mdx @@ -6,7 +6,7 @@ image: images/blockly_banner.png # Advanced compilation -The regular [build process](/guides/contribute/core/building) uses the +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) @@ -14,33 +14,33 @@ mode, Blockly also supports the use of [`ADVANCED_OPTIMIZATIONS`](https://developers.google.com/closure/compiler/docs/compilation_levels#advanced_optimizations) mode. -## Build test +:::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). +::: -Blockly includes a test (`compileAdvancedCompilationTest()`) in -`packages/blockly/scripts/gulpfiles/build_tasks.mjs` which builds Blockly and a -small test app using `ADVANCED_OPTIMIZATIONS` to ensure compatibility. +## Advanced compilation test -This test serves as an example of using `ADVANCED_OPTIMIZATIONS`. The test app -can be found in `packages/blockly/tests/compile/`. +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. -You can run this test via: +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 ``` -This test is also run automatically as part of Blockly's broader build suite, so -that new changes remain compatible with `ADVANCED_OPTIMIZATIONS`. - -## Using advanced compilation - -:::warning -Unless you need to reduce compressed size of Blockly even more, you -should avoid `ADVANCED_OPTIMIZATIONS` mode. Instead, -you can use the compressed version of Blockly from [npm](https://www.npmjs.com/package/blockly). -::: +## Use advanced compilation Since `ADVANCED_OPTIMIZATIONS` includes aggressive renaming, you must compile -Blockly *with* your own app in order to use it. You can use the -[advanced compilation test](#build-test) as a reference for how to do this. -You may also want to consult the -[Closure Compiler documentation](https://developers.google.com/closure/compiler/docs/api-tutorial3). +Blockly *with* your own app in order to use it. + +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. From 86e35bc8b3c1de3c2e28c034081003e380abb701 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zo=C3=AB=20Spriggs?= Date: Wed, 5 Aug 2026 14:25:20 -0400 Subject: [PATCH 3/3] docs: fix playground link --- .../docs/docs/guides/contribute/core/testing/playground.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/docs/docs/guides/contribute/core/testing/playground.mdx b/packages/docs/docs/guides/contribute/core/testing/playground.mdx index 5f33413330f..b404d575946 100644 --- a/packages/docs/docs/guides/contribute/core/testing/playground.mdx +++ b/packages/docs/docs/guides/contribute/core/testing/playground.mdx @@ -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