Configuration options

Fanstatic makes available a number of configuration options. These can be passed to the Fanstatic WSGI component as keyword arguments. They can also be configured using Paste Deploy configuration patterns (see our Paste Deploy documentation for more information on that).

versioning

If you turn on versioning, Fanstatic will automatically include a version identifier in the resource URLs it generates and injects into web pages. This means that for each version of your Javascript resource its URL will be unique. The Fanstatic publisher will set cache headers for versioned resource URLs so that they will be cached forever by web browsers and caching proxies [1].

By default, versioning is disabled, because it needs some extra explanation. We highly recommend you to enable it however, as the performance benefits are potentially huge and it’s usually entirely safe to do so. See also recompute_hashes if you want to use versioning during development.

The benefit of versioning is that all resources will be cached forever by web browsers. This means that a web browser will never talk to the server to request a resource again once it retrieved it once, as long as it is still in its cache. This puts less load on your web application: it only needs to publish the resource once for a user, as long as the resource remains in that user’s cache.

If you use a server-side cache such as Squid or Varnish, the situation is even better: these will hold on to the cached resources as well, meaning that your web application needs to serve the resource exactly once. The cache will serve them after that.

But what if you change a resource? Won’t users now get the wrong, old versions of the changed resource? No: with versioning enabled, when you change a resource, a new URL to that resource will be automatically generated. You never will have to instruct users of your web application to do a “shift-reload” to force all resources to reload – the browser will see the resource URL has changed and will automatically load a new one.

How does this work? There are two schemes: explicit versioning and an automatically calculated hash-based versioning. An explicit version looks like this (from the js.jquery package):

/fanstatic/jquery/:version:1.4.4/jquery.js

A hash-based version looks like this:

/fanstatic/my_library/:version:d41d8cd98f00b204e9800998ecf8427e/my_resource.js

The version of Resource depends on the version of the python package in which the Library is defined: it takes the explicit version information from this. If no version information can be found or if the python package is installed in development mode, we still want to be able to create a unique version that changes whenever the content of the resources changes.

To this end, the most recent modification time from the files and directories in the Library directory is taken. Whenever you make any changes to a resource in the library, the hash version will be automatically recalculated.

The benefit of calculating a hash for the Library directory is that resource URLs change when a referenced resource changes; If resource A (i.e. logo.png) in a library that is referenced by resource B (i.e. style.css) changes, the URL for resource A changes, not because A changed, but because the contents of the library to which A and B belong has changed.

Fanstatic also provides an MD5-based algorithm for the Library version calculation. This algorithm is slower, but you may use if you don’t trust your filesystem. Use it through the versioning_use_md5 parameter.

recompute_hashes

If you enable versioning, Fanstatic will automatically calculate a resource hash for each of the resource directories for which no version is found.

During development you want the hashes to be recalculated each time you make a change, without having to restart the application all the time, and having a little performance impact is no problem. The default behavior is to recompute hashes for every request.

Calculating a resource hash is a relatively expensive operation, and in production you want Fanstatic to calculate the resource hash only once per library, by setting recompute_hashes to false. Hashes will then only be recalculated after you restart the application.

bottom

While CSS resources can only be included in the <head> section of a web page, Javascript resources can be included in <script> tags anywhere on the web page. Sometimes it pays off to do so: by including Javascript resources at the bottom of a web page (just before the </body> closing tag), the page can already load and partially render for the user before the Javascript files have been loaded, and this may lead to a better user experience.

Not all Javascript files can be loaded at this time however: some depend on being included as early as possible. You can mark a Resource as “bottom safe” if they are safe to load at the bottom of the web page. If you then enable bottom, those Javascript resources will be loaded there. If bottom is turned off (the default), all Javascript resources will be included in the <head> section.

force_bottom

If you enable force_bottom (default it’s disabled) then if you enable bottom, all Javascript resources will be included at the bottom of a web page, even if they’re not marked “bottom safe”.

minified and debug

By default, the resource URLs included will be in the normal human-readable (and debuggable) format for that resource.

When creating Resource instances, you can specify alternative modes for the resource, such as minified and debug versions. The argument to minified and debug are a resource path or resource that represents the resource in that alternative mode.

You can configure Fanstatic so that it prefers a certain mode when creating resource URLs, such as minified. In this case Fanstatic will preferentially serve minified alternatives for resources, if available. If no minified version is available, the default resource will be served.

ignores

You can prevent the Fanstatic publisher from publishing certain files and directories by using the ignores option. You can leave the source files of your graphics and client side logic near the result files without worrying about Fanstatic ‘leaking’ this information. The ignores option accepts a list of glob patterns.

rollup

A performance optimization to reduce the amount of requests sent by a client is to roll up several resources into a bundle, so that all those resources are retrieved in a single request. This way a whole collection of resources can be served in one go.

You can create special Resource instances that declare they supersede a collection of other resources. If rollup is enabled, Fanstatic will serve a combined resource if it finds out that all individual resources that it supersedes are needed.

base_url

The base_url URL will be prefixed in front of all resource URLs. This can be useful if your web framework wants the resources to be published on a sub-URL. By default, there is no base_url, and resources are served in the script root.

Note that this can also be set using the set_base_url method on a NeededResources instance during run-time, as this URL is generally not known when NeededResources is instantiated.

publisher_signature

The default publisher signature is fanstatic. What this means is that the Fanstatic() WSGI component will look for the string /fanstatic/ in the URL path, and if it’s there, will take over to publish resources. If you would like the root for resource publication to be something else in your application (such as resources), you can change this to another string.

bundle

Bundling of resources minimizes HTTP requests from the client by finding efficient bundles of resources. In order to configure bundling of resources, set the bundle argument to True.

[1]

Well, for 10 years into the future at least.

compile

To automatically run compilers and minifiers when needed, set the compile argument to True. (This argument is only about running compilers automatically; you can always compile your resources manually via the fanstatic-compile command-line program.)