~~~~~~~~~~~~~~~~~~~ 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 -------------------------------------------------------------- 0. Make sure ``django.contrib.staticfiles`` is listed in ``INSTALLED_APPS``. 1. 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. 2. 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 :ref:`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.