django-assets

django-assets helps you to integrate webassets into your Django application.

Quickstart

First, add django_assets to your INSTALLED_APPS setting:

INSTALLED_APPS = (
    ...,
    'django_assets',
)

Create an assets.py file inside your application directory. This is where you define your assets, and like Django’s admin.py files, they will automatically be picked up:

from django_assets import Bundle, register
js = Bundle('common/jquery.js', 'site/base.js', 'site/widgets.js',
            filters='jsmin', output='gen/packed.js')
register('js_all', js)

Note

Make sure your assets.py is inside a Django application, not in the project. That is, the path might be something like my_project/my_application/assets.py.

If you want to define assets in a different place, you can use the ASSETS_MODULES setting.

Finally, include the bundle you defined in the appropriate place within your templates:

{% load assets %}
{% assets "js_all" %}
    <script type="text/javascript" src="{{ ASSET_URL }}"></script>
{% endassets %}

django-assets will now automatically merge and compress your bundle’s source files the first time the template is rendered, and will automatically update the compressed file every time a source file changes. If ASSETS_DEBUG is enabled, then each source file will be outputted individually instead.

Templates only

If you prefer, you can also do without defining your bundles in code, and simply define everything inside your template:

{% load assets %}
{% assets filters="jsmin", output="gen/packed.js", "common/jquery.js", "site/base.js", "site/widgets.js" %}
    <script type="text/javascript" src="{{ ASSET_URL }}"></script>
{% endassets %}

You can also pass in depends through templatetags with a slightly modified comma-delimated syntax, e.g. depends="myfile.js,path/to/file.js".

The management command

django-assets also provides a management command, manage.py assets. It can be used to manually cause your bundles to be rebuilt:

$ ./manage.py assets build
Building asset: cache/site.js
Building asset: cache/ie7.js
Building asset: cache/site.css

Note that this is more difficult if you are defining your bundles within your templates, rather than in code. You then need to use the --parse-templates option, so the build command can find the bundles.

staticfiles integration

django-assets can integrate with Django’s django.contrib.staticfiles.

Jinja2 support

See Jinja2 support if you want to use django-assets with the Jinja2 templating language.

Settings

See Settings for on overview of Django configuration values.

webassets documentation

For further information, have a look at the complete webassets documentation, and in particular, the following topics:

  • All about bundles
  • Builtin filters
  • Custom filters
  • CSS compilers
  • FAQ