build.py, or how to generate a compressed Three.js file

Why compression?

The source code of Three.js is deliberately easy to read for a human being. This means that it’s split into several files and classes. While that’s great for developing and hacking on Three.js, it’s not that great when deploying code to the production server.

In production, you want to

1. use the least amount of files possible (to minimise the number of connections to your server)
2. transmit as few bytes as possible (to save on bandwidth and on wait-time on both sides)

So how do we put all files into just one and make it smaller than the sum of the parts? Well, the answer is the awesome combination of our build script plus Javascript compressors!

build.py

The build script is located in utils/build.py. As you might already have guessed, it’s written in Python, so you’ll need a working Python 2.6 (or higher) installation in order to execute it.

To create your first compressed Three.js file, simply chdir to the utils directory, and launch the script:

python build.py --common --minified

This will create a compressed version of the current Three.js source code, and place it in the build folder (i.e. a level above utils)

If you just want to create a version of Three.js in one file, without compressing anything, just ignore the --minified switch:

python build.py --common

This is way faster to produce, but the resulting file is also understandably larger than the compressed version!

Customising your build

Another advantage of using this script is that you can prepare a packed version with exactly the parts of Three.js that you use. So let’s say you only use the Canvas renderer in your project—then you don’t need to include the other renderers. Well, there are options for that in the build system:

python build.py --canvas --minified

This will generate the ThreeCanvas.js file in build/custom

Or if you just want to use WebGL:

python build.py --webgl --minified

will generate ThreeWebGL.js in build/custom

For a complete list of the available options, simply run build.py without arguments:

usage: build.py [-h] [--includes] [--common] [--extras] [--canvas] [--webgl]
                [--svg] [--dom] [--debug] [--minified] [--all]

Build and compress Three.js

optional arguments:
  -h, --help  show this help message and exit
  --includes  Build includes.js
  --common    Build Three.js
  --extras    Build ThreeExtras.js
  --canvas    Build ThreeCanvas.js
  --webgl     Build ThreeWebGL.js
  --svg       Build ThreeSVG.js
  --dom       Build ThreeDOM.js
  --debug     Generate debug versions
  --minified  Generate minified versions
  --all       Build all Three.js versions

Do you really need to use build.py?

Generally speaking, most people don’t need it, since we already create the builds with compressed files and upload them to the repository pretty much right after committing changes to the code (the builds are in the build folder).

But if you’re working in the very THREE.js source code and want to generate a compressed version for your own use, this is the tool you’ll need. Also, if you add a new class to the project, it will need to be added to the build.py script so that it’s included when on the builds. Read on for more information on how is it done.

How does build.py work?

The script has a list of files that are to be included in each ‘version’ of the build. For example, when you specify the --canvas option, it will read all the files defined in the CANVAS_FILES list, append them all together in just one big file, and then send the result through the compressor, which in turn, will create a significantly smaller version of the file, while still being equivalent code-wise. It does so by removing comments, extra spaces and tabs, and by using other advanced techniques such as renaming vars that can be safely renamed without breaking anything else, etc.

If you wanted to include a file only when building the Canvas version, you’ll add the relative path to the file to the CANVAS_FILE variable.

Three.js currently uses Google’s Closure compiler for producing its packed version. The compiler is included too in the download of Three.js, following the batteries included house style.

In the past we used Yahoo’s YUI compressor, but changed to Closure because it generated smaller files.