---
description: The process for building Blockly.
title: Build scripts
image: images/blockly_banner.png
---

# Build scripts

:::warning
Unless you are modifying the Blockly source code directly, you probably
don't need to build Blockly run any of the scripts documented below yourself.
Instead, follow the instructions in [the "Get the Code"
section](/guides/get-started/get-the-code#get-the-code-1) of the [Get Started](/guides/get-started/get-the-code) page to install [the `blockly` NPM package](https://www.npmjs.com/package/blockly) or download the `.tgz` file attached to
[the latest release on GitHub](https://github.com/RaspberryPiFoundation/blockly/releases/latest).
:::

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](https://developers.google.com/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 [RaspberryPiFoundation/blockly repository](https://github.com/RaspberryPiFoundation/blockly) 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](https://www.npmjs.com/package/blockly) and since
2022 also attached as a `.tgz` file to [each GitHub release](https://github.com/RaspberryPiFoundation/blockly/releases), 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](https://docs.npmjs.com/cli/v9/using-npm/scripts) to run [Gulp
tasks](https://gulpjs.com/). 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

:::warning
Unless you are modifying the Blockly source code directly, you probably
don't need to build Blockly run any of the scripts documented below yourself.
Instead, follow the instructions in [the "Get the Code"
section](/guides/get-started/get-the-code#get-the-code-1) of the [Get Started](/guides/get-started/get-the-code) page to install [the `blockly` NPM package](https://www.npmjs.com/package/blockly) or download the `.tgz` file attached to
[the latest release on GitHub](https://github.com/RaspberryPiFoundation/blockly/releases/latest).
:::

- If you've made local changes and want to make sure they've not broken the
  build or any tests, run

  ```shell
  npm test
  ```

  to build Blockly and run its test suite.

- If you want to test local changes in the browser, run

  ```shell
  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

  ```shell
  npm run package
  ```

  to build Blockly package, then

  ```shell
  cd dist && npm link
  ```

  to tell npm where to find the compiled files, and then `cd` to your project's
  directory before running

  ```shell
  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](https://github.com/umdjs/umd) 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](https://github.com/umdjs/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](https://eslint.org/), 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.
