Usage

Template tag

Usually, in your template you would write something like:

<script src="/static/jspm_packages/system.js"></script>
<script src="/static/config.js"></script>
<script>System.import('my/awesome/app.js');</script>

With Django SystemJS you can replace this with:

{% load staticfiles system_tags %}

<script src="{% static 'jspm_packages/system.js' %}"></script>
<script src="{% static 'config.js' %}"></script>
{% systemjs_import 'my/awesome/app.js' %}

In development mode (DEBUG = True), the tag will output the previous System.import('my/awesome/app.js'); statement. In production mode, it will output:

<script src="/static/SYSTEMJS/my/awesome/app.js"></script>

This url is generated by the configured static files backend, so if you use the CachedStaticFilesStorage, you will get the hashed path:

<script src="/static/SYSTEMJS/my/awesome/app.12ab459edf22.js"></script>

Note

django-storages(-redux) and S3 is untested. If you run into any issues, please raise an issue on Github.

If you want to use django.contrib.staticfiles.storage.ManifestStaticFilesStorage, you need to use the systemjs-version: systemjs.storage.SystemJSManifestStaticFilesStorage. This storage ensures that during bundling the collected staticfiles (from collectstatic) aren’t removed from the manifest file.

The tag accepts any number of (custom) attributes you may want to add, making it possible to load scripts async, or specify html ids for example.

{% load system_tags %}
{% systemjs_import 'my/awesome/app.js' async id="my-awesome-app" %}

this will output (in production mode)

<script type="text/javascript" async id="my-awesome-app" src="/static/SYSTEMJS/my/awesome/app.12ab459edf22.js"></script>

Management commands

Django-SystemJS comes with a few management commands to create and manage all the bundles. It does so by checking all your template files and extracting the {% systemjs_import '...' %} nodes.

systemjs_bundle

Process the project templates, extract the apps and bundle them with jspm.

python manage.py systemjs_bundle

By default it will look at all templates in your app directories, and the additional template dirs for the vanilla Django template engine - Jinja2 is unsupported.

Supporting all the jspm command line arguments is work in progress. Currently the following options are supported:

Options

  • --minify: passes the --minify flag down to jspm to generate minified bundles

  • --sfx: generates a self-executing bundle.

  • --template, -t: pass the name of a template (for example myapp/base.html), and Django SystemJS will only look in those files for imported apps. It will no longer parse all project templates. This option can be specified multiple times to look in a set of templates.

  • --minimal: the minimal option will only rebundle apps that have changed. If you have multiple {% systemjs_import <...> %} statements, and only one app was changed, this can speed up the total bundle time. Comparison happens based on mtimes and md5 hashes of the involved files.

    Note

    Changes to the source files for the bundles are detected, but changes to jspm config files (jspm.config.js, jspm.browser.js) are not included. These files can change relatively frequently, hereby invalidating the depcache when it’s not needed. Be careful when making bundle-altering config file changes.

    The first time you use the --minimal option, you will get an error saying that the deps.json file cannot be located. This is because we have never written the dependency tree yet.

    You can do this manually the first time by executing the systemjs_write_depcaches command.

  • --node-path: path to the node_modules directory of your project. Required if Django-SystemJS cannot figure it out by itself and the NODE_PATH environment variable is not set.

systemjs_show_packages

Parses the templates and reports the apps found in them. Useful to get a quick overview of all the bundles to be generated.

systemjs_write_depcaches

Parses the templates and extracts the apps found in them. For every app, the dependencies are traced and written to disk. This depcache is used with the --minimal option of the systemjs_bundle command.

Note

If you bundle with any of the --sfx, --minimal or minify options, you need to use the same options to write the depcache. A difference in bundle options will trigger a re-bundle.

Example workflow

Django SystemJS is designed as a non-intrusive library in development mode, so that it won’t sit in your way too much. Simply using the template tag will be all you have to do as long as you’re running with DEBUG=True.

Example steps for deployment:

  • Run git pull to update your copy of the code
  • Install the dependencies: npm install, followed by jspm install
  • Run collectstatic: python manage.py collectstatic
  • Bundle the apps in your project: python manage.py systemjs_bundle.

The order of operations matters: to bundle, all the bits and pieces must be collected so that jspm can retrieve them in your STATIC_ROOT. It has no notion of your static folders within your apps.