Javascript and CSS packaging

Last modified: 22 February 2011

We minimize the number of requests and payload size when retrieving external JS and CSS files (see Best practices for speeding up your website) by combining and minifying our javascript and stylesheet content.

Follow these steps when adding new JS/CSS files that may be shared across multiple pages:
  1. Make sure any new JS and CSS files are placed in "-package" suffixed directories in /javascript and /stylesheets (see /javascript/maps-package/ and /javascript/shared-package).
  2. Add your file to the list of external files in your package's template tag HTML file. Example: if adding a new file to the "shared" javascript package, you'd edit shared_javascript.html to include your file when using the development server:
    {% if not App.is_dev_server %}
        <script type="text/javascript" src="/javascript/shared-package/compressed.js?{{App.version}}"></script>
    {% else %}

        <script type="text/javascript" src="/javascript/shared-package/jquery.js?{{App.version}}"></script>
        <script type="text/javascript" src="/javascript/shared-package/jquery-ui.js?{{App.version}}"></script>
        <script type="text/javascript" src="/javascript/shared-package/{{App.version}}"></script>
        <script type="text/javascript" src="/javascript/shared-package/jquery.watermark.js?{{App.version}}"></script>
        <script type="text/javascript" src="/javascript/shared-package/jquery.placeholder.js?{{App.version}}"></script>
        <script type="text/javascript" src="/javascript/shared-package/discussion.js?{{App.version}}"></script>
        <script type="text/javascript" src="/javascript/shared-package/pageutil.js?{{App.version}}"></script>
    {% endif %}
  3. Our deploy script will automatically combine all files in each of the -package directories and use YUICompressor to minimize them before deploy. The single file created will be used by the production server instead of the separate, un-minimized external files used on developer machines (see bold code above).
  4. Don't add a bunch of files to the "shared" packages unless the code you're adding is actually used across the majority of the site. If you need to add a whole new package because the files you're adding don't fit into any of the existing packages, that's no problem. Just follow the existing examples.