phorge / src / docs / contributor / celerity.diviner

@title Celerity Technical Documentation
@group developer

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:

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

= Class Relationships =

Celerity's primary API is @{function: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 @{class:CelerityAPI} to access the active
@{class: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
@{class:CelerityAPI} to access the active
@{class:CelerityStaticResourceResponse} and requests that it render out
appropriate references to CSS and JS resources. It uses
@{class: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
@{class:CelerityResourceController}. It responds to these requests and delivers
the relevant resources and packages, managing cache lifetimes and handling any
necessary preprocessing. It uses @{class: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`.

@{class:CelerityStaticResourceResponse} also manages some Javelin information,
and @{function:celerity_generate_unique_node_id} uses this metadata to provide
a better uniqueness guarantee when generating unique node IDs.