Staticfiles support

Note

As a general rule, everything on this page only applies if django.contrib.staticfiles is found in your INSTALLED_APPS setting.

As a refresher, this is how Django’s staticfiles application works:

  • You spread your assets across multiple directories; often, for example, you’d have a separate static folder for each application.

  • For development, a special view is provided that will search all these static directories, and serve the the requested file from wherever it is found.

  • For production, a collectstatic management command is provided that will copy the files from all these locations into a single folder, and then this directory can be served by the webserver.

    All the individual static directories are thus part of the same url space. A foo.png in one folder will overwrite a foo.png in another.

django-assets integrates into this in the following way:

  • When Django is in debug mode (DEBUG=True), webassets uses the staticfiles mechanism to find the files you reference in bundles, in the same way the staticfiles serve view does. You can work with all of your assets the way you’d expect.

    This even works with globs, so “*.js” will query Javascript files from across all of your applicatnion’s static directories.

  • In production, this mechanism is disabled, and you are expected to run ./manage.py collectstatic before you deploy your application and/or want to use ./manage.py assets build.

    Warning

    If you are using automatic rebuilding in production, changes will not be picked up until you have run collectstatic.

Specific steps to make django-assets work with staticfiles

  1. Make sure django.contrib.staticfiles is listed in INSTALLED_APPS.

  2. Add django_assets.finders.AssetsFinder to your STATICFILES_FINDERS. It might then look like this:

    STATICFILES_FINDERS = (
   "django.contrib.staticfiles.finders.FileSystemFinder",
   "django.contrib.staticfiles.finders.AppDirectoriesFinder",
   "django_assets.finders.AssetsFinder"
)

    This is necessary so that output files written to STATIC_ROOT are served in debug mode by the staticfiles serve view, which is not the case by default. If you are not building anything in debug mode (e.g. CoffeeScript, Sass), you can get away without this addition, but it doesn’t hurt to have it anway.

  3. Make sure you run ./manage.py collectstatic in production first, before letting webassets build.

CachedStaticFileStorage

The new CachedStaticFileStorage in Django 1.4 is able to rename all files to include their content hash in the filename, and rewrite references to them within other static files.. This is somewhat overlapping with webassets’ own versioning system.

If you prefer to use CachedStaticFileStorage, you shouldn’t run into any problems. Just make sure you run ./manage.py assets build first, and ./manage.py collectstatic second, so that collectstatic may version the output files generated by your django-assets bundles.

The only case where this doesn’t just work is if you are defining bundles in your templates. If that is the case, you currently need to define an ASSETS_ROOT setting that points to a different directory then STATIC_ROOT. Only then will collectstatic be able to find the output files created with ./manage.py build --parse-templates, and process them into STATIC_ROOT, like any other static file.

ManifestStaticFileStorage or White Noise

If you are using Django’s ManifestStaticFilesStorage or White Noise’s GzipManifestStaticFilesStorage then you must build your assets after calling collectstatic using the --manifest django option:

./manage.py assets build --manifest django

This will add the built assets to Django’s static files manifest. In particular, this ensures that White Noise realises they are cacheable static files and will add appropriate far-future expiry headers when serving them.