1. Description

This script can help you reduce your website loading times by minimizing the size of your website static resources.

It can minify CSS files (using YUI compressor), compile JavaScript files (using Google Closure Compiler) and compress images (using jpegoptim and optipng).

Not only it can compile external JavaScript files, but it can also find and automatically compile blocks of inline JavaScript and internal CSS code located in your templates / html files.

It would ideally be used some where in your website deployment process.

If you happen to develop web applications using Django and you currently don’t use a deployment script, check django-deployment-script.

2. Requirements

• Java (http://www.java.com/en/download/manual.jsp)
• YUI Compressor (http://developer.yahoo.com/yui/compressor/)
• Google Closure Compiler (http://code.google.com/closure/compiler/)
• jpegoptim (http://freshmeat.net/projects/jpegoptim/)
• optipng (http://optipng.sourceforge.net/)

3. Basic usage and setup

1. Set the path to the external tools / binaries in the asset_deflator.py file
2. Run the script

python asset_deflator.py --path=/path/to/your/assets/ --all -v -s

This will run the script in the verbose mode (-v) and a short report will be displayed (-s) at the end.

—all option means that the script will search for css files, javascript files, files with inline javascript and/or internal css and images and try to minify / compile / compress them.

If you don’t want to run all the actions, skip the —all argument and for example use —minify-css (this will cause the script to only look for CSS files in the provided path and try to minify them).

By default, the script will create new files with .min suffix after the file name and not overwrite the original files (you can change this behavior with -o option).

For the description of all the arguments, run the script with the —help option.

python asset_deflator.py --help

If everything goes well, you should see something like this:

Statistics

Performed work on 170 files located in /usr/home/some/where
Running time: 0:01:04

CSS files:
Size before: 13237 bytes, size after: 10066 bytes -23.96%

JavaScript files:
Size before: 50386 bytes, size after: 23982 bytes -52.40%

Templates:
Size before: 14926 bytes, Size after: 13269 bytes -11.10%

Image files:
Size before: 3941782 bytes, size after: 3146148 bytes -20.18%

Total:
Size before: 4020331 bytes, size after: 3193465 bytes -20.57%

4. Using the “save state” option

If you plan to use this tool multiple times on the same path, you should consider using the “save state” option.

This allows program to save the current state to a file and the next time you run it and provide it with the path to the state file, only the new files and the ones which have been modified will be acted upon (there is no point in compressing the file which has already been compressed and hasn’t changed).

The save state option can be used like this:

python asset_deflator.py --path=/path/to/your/assets/ --save-state=/path/to/state.file --all -v -o -s

This will run all the actions (—all) on the files located in /path/to/your/assets/ and at the end, save the current state (file names and modification times) to a file located at /path/to/state.file.

On the next run, you would provide the program with the path to the previously saved state file:

python asset_deflator.py --path=/path/to/your/assets/ --skip-not-modified=/path/to/state.file --save-state=/path/to/state.file --all -v -o -s

This time, we provided the —skip-not-modified option, meaning that only the new files and the ones which have been modified since the last run will be acted upon.

Note that we also provided the —save-state option with the path to the same state file, which means that the state will again be saved to this file (it will be updated) at the end of the run.

If you plan to periodically run this tool on the same path, you should always provide the program with both options (—skip-not-modified and —save-state) pointing to the same file, which allows it to always reuse and update the same state file and only act on the new and modified files.

5. Frequently asked questions

Which image formats are currently supported?

png, jpg and gif (basically all you need, unless you are a guy who is still including 2MB large bmp files on their homepage :P)

How does this script find blocks of JavaScript code inside my templates?

Well, the regular expression which matches the inline JavaScript in this version isn’t exactly a rocket science, but it will probably work for 90% of the cases.

How does the program know if the file has been modified?

When using the “save state” option, the program saves the file names and modification times to a file.

If the current file modification time is different from the on saved in the state file, the file is considered modified and all the actions you have specified will be performed on this file.

6. Notes

This script has been tested and confirmed to work with YUI compressor 2.4.2 and Google Closure Compiler 20091217.

7. Upcoming features

Packing multiple CSS and JavaScript files together into one file and replacing the references to this files in your templates with the reference to a new file.

8. Changelog

• 1.2.0 (20.05.2010):

- Option to save a list of the files which were compressed during this run (—save-state=STATE_FILE) to a file and load this file on subsequent run (—skip-not-modified=STATE_FILE) and skip the files which were not modified

• 1.1.1 (23.01.2010):

- Now multiple instances can run at once, but only if they are working on different paths (—path option)

• 1.1.0 (19.01.2010):

- Added support for minification of inline (internal) CSS styles (—minify-inline-css)
- Only one instance of program is allowed to run at once
- Tweaked regular expressions for matching CSS and JavaScript blocks
- Size of all assets before and after compression process is displayed if using —statistics option

• 1.0.0 (17.01.2010):

- Initial release