As a general rule, everything on this page only applies if
django.contrib.staticfiles is found in your
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
collectstaticmanagement 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.pngin one folder will overwrite a
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
staticfilesserve view does. You can work with all of your assets the way you’d expect.
In production, this mechanism is disabled, and you are expected to run
./manage.py collectstaticbefore you deploy your application and/or want to use
./manage.py assets build.
If you are using automatic rebuilding in production, changes will not be picked up until you have run
Specific steps to make
django-assets work with staticfiles¶
django.contrib.staticfilesis listed in
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_ROOTare served in debug mode by the
staticfilesserve 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.
Make sure you run
./manage.py collectstaticin production first, before letting webassets build.
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,
./manage.py collectstatic second, so that
version the output files generated by your
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
ASSETS_ROOT setting that points to a different directory
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
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.