Celerity Technical Documentation

Phorge Contributor Documentation (Developer Guides)

Technical overview of the Celerity system.

Overview

Celerity is a static resource (CSS and JS) management system, which handles:

• Keeping track of which resources a page needs.
• Generating URIs for the browser to access resources.
• Managing dependencies between resources.
• Packaging resources into fewer HTTP requests for performance.
• Preprocessing resources (e.g., stripping comments and whitespace).
• Delivering resources and managing resource cache lifetimes.
• Interfacing with the client to manage resources.

Celerity is an outgrowth of the Haste system at Facebook. You can find more information about Celerity here:

• Things You Should Do Soon: Static Resources describes the history and context of the system and the problems it solves.
• Adding New CSS and JS provides a developer guide to using Celerity.

Class Relationships

Celerity's primary API is require_celerity_resource(), which marks a resource for inclusion when a response is rendered (e.g., when the HTML page is generated, or when the response to an Ajax request is built). For instance, if you use a CSS class like "widget-view", you must ensure the appropriate CSS is included by calling require_celerity_resource('widget-view-css') (or similar), at your use site.

This function uses CelerityAPI to access the active CelerityStaticResourceResponse and tells it that it needs to include the resource later, when the response actually gets built. (This layer of indirection provides future-proofing against certain complex situations Facebook eventually encountered).

When the time comes to render the response, the page renderer uses CelerityAPI to access the active CelerityStaticResourceResponse and requests that it render out appropriate references to CSS and JS resources. It uses CelerityResourceMap to determine the dependencies for the requested resources (so you only have to explicitly include what you're actually using, and not all of its dependencies) and any packaging rules (so it may be able to generate fewer resource requests, improving performance). It then generates <script /> and <link /> references to these resources.

These references point at /res/ URIs, which are handled by CelerityResourceController. It responds to these requests and delivers the relevant resources and packages, managing cache lifetimes and handling any necessary preprocessing. It uses CelerityResourceMap to locate resources and read packaging rules.

The dependency and packaging maps are generated by bin/celerity map, which updates resources/celerity/map.php.

CelerityStaticResourceResponse also manages some Javelin information, and celerity_generate_unique_node_id() uses this metadata to provide a better uniqueness guarantee when generating unique node IDs.