Awesome
django-webpack-loader
Integrate Webpack bundles in Django templates by using a simple template tag:
{% load render_bundle from webpack_loader %}
<html>
<head>
{% render_bundle 'main' 'css' %}
</head>
</html>
Behind the scenes, Django Webpack Loader consumes a stats file generated by webpack-bundle-tracker and lets you use the generated bundles in Django.
A changelog is available.
Compatibility
Generally, Python, Django, and Node LTS releases will be supported until EOL. Check tests/tox.ini
for details.
Versions not listed in tests/tox.ini
may still work, but maintainers will not test them, nor solve issues with them.
Examples below are in Webpack 5.
Install
npm install --save-dev webpack-bundle-tracker
pip install django-webpack-loader
Configuration
For kick-starting a full example project with opinionated development and production settings, you can check the django-react-boilerplate
. For a more flexible configuration, keep reading.
Configuring webpack-bundle-tracker
Before configuring django-webpack-loader
, let's first configure what's necessary on webpack-bundle-tracker
side. Update your Webpack configuration file (it's usually on webpack.config.js
in the project root). Make sure your file looks like this (adapt to your needs):
const path = require("path");
const webpack = require("webpack");
const BundleTracker = require("webpack-bundle-tracker");
module.exports = {
context: __dirname,
entry: "./assets/js/index",
output: {
path: path.resolve(__dirname, "assets/webpack_bundles/"),
publicPath: "auto", // necessary for CDNs/S3/blob storages
filename: "[name]-[contenthash].js",
},
plugins: [
new BundleTracker({ path: __dirname, filename: "webpack-stats.json" }),
],
};
The configuration above expects the index.js
(the app entrypoint file) to live inside the /assets/js/
directory (this guide going forward will assume that all frontend related files are placed inside the /assets/
directory, with the different kinds of files arranged within its subdirectories).
The generated compiled files will be placed inside the /assets/webpack_bundles/
directory and the stats file with the information regarding the bundles and assets (webpack-stats.json
) will be stored in the project root. You may add webpack-stats.json
to your .gitignore
.
Configuring the Django settings file
First of all, add webpack_loader
to INSTALLED_APPS
.
INSTALLED_APPS = (
...
'webpack_loader',
...
)
Below is the recommended setup for the Django settings file when using django-webpack-loader
.
STATICFILES_DIRS = (
os.path.join(BASE_DIR, 'assets'),
)
WEBPACK_LOADER = {
'DEFAULT': {
'BUNDLE_DIR_NAME': 'webpack_bundles/',
'CACHE': not DEBUG,
'STATS_FILE': os.path.join(BASE_DIR, 'webpack-stats.json'),
'POLL_INTERVAL': 0.1,
'IGNORE': [r'.+\.hot-update.js', r'.+\.map'],
}
}
Note that you must set the path where you're keeping your static assets and Webpack bundles in STATICFILES_DIRS
.
For that setup, we're using the DEBUG
variable provided by Django. Since in a production environment (DEBUG = False
) the assets files won't constantly change, we can safely cache the results (CACHE=True
) and optimize our flow, as django-webpack-loader
will read the stats file only once and store the assets paths in memory. If CACHE=False
, we'll always read the stats file to get the assets paths.
The STATS_FILE
parameter represents the output file produced by webpack-bundle-tracker
. Since in the Webpack configuration file we've named it webpack-stats.json
and stored it on the project root, we must replicate that setting on the backend side.
During development, the stats file will change often, therefore we want to always poll for its updated version (every 0.1s, as defined on POLL_INTERVAL
).
⚠️ In production (
DEBUG=False
), we'll only fetch the stats file once, soPOLL_INTERVAL
is ignored.
IGNORE
is a list of regular expressions. If a file generated by Webpack matches one of the expressions, the file will not be included in the template.
Compiling the frontend assets
Using Webpack, you must generate the frontend bundle along with the stats file using webpack-bundle-tracker
before using django-webpack-loader
in Django templates. Note you'll probably want different configurations in development vs. production. The pipeline should look like this:
flowchart TD
A("Run webpack")
A --> |CSS, JS, imgs, fonts| B(Collect compiled assets)
A --> |webpack-stats.json| C(Read on Django templates)
In development, we can simply do:
# in one shell
npx webpack --mode=development --watch
# in another shell
python manage.py runserver
Check the full example for development here.
Aditionally, hot reload is available through a specific config. Check this section.
⚠️ For compiling and serving the frontend assets in production, check this section.
Usage
In order to render the frontend code into the Django templates, we use the render_bundle
template tag.
Its behavior is to accept a string with the name of an entrypoint from the stats file (in our case, we're using main
, which is the default) and it'll proceed to include all files under that entrypoint. You can read more about the entrypoints concept here.
⚠️ You can also check an example on how to use multiple
entry
values here.
Below is the basic usage for render_bundle
within a template:
{% load render_bundle from webpack_loader %}
<html>
<head>
{% render_bundle 'main' 'css' %}
</head>
</html>
That will render the proper <script>
and <link>
tags needed in your template.
Using in tests
To run tests where render_bundle
shows up, since we don't have webpack-bundle-tracker
at that point to generate the stats file, the calls to render the bundle will fail. The solution is to use the FakeWebpackLoader
in your test settings:
WEBPACK_LOADER['DEFAULT']['LOADER_CLASS'] = 'webpack_loader.loaders.FakeWebpackLoader'
Using in Production
The recommended apporach is to have a production pipeline that generates the frontend bundle along with the stats file during the deployment phase. We recommend keeping the generated bundles and the stats file outside the version control. In other words, add webpack-stats.json
and assets/webpack_bundles/
to your .gitignore
.
Assuming static files is properly configured using Django built-ins or something like django-storages, a simple production deployment can use Django's own collectstatic
. Remember the Django settings values of STATICFILES_DIRS
, BUNDLE_DIR_NAME
, STATS_FILE
, and Webpack's output.path
must all be compatible:
// webpack.config.js
module.exports = {
// ...
context: __dirname,
output: {
// Emit bundle files at "assets/webpack_bundles/":
path: path.resolve(__dirname, "assets/webpack_bundles/"),
publicPath: "auto", // necessary for CDNs/S3/blob storages
filename: "[name]-[contenthash].js",
},
plugins: [
// Emit 'webpack-stats.json' in project root for Django to find it:
new BundleTracker({ path: __dirname, filename: "webpack-stats.json" }),
],
};
# app/settings.py
BASE_DIR = ... # set to project root
STATICFILES_DIRS = (
# make Django collect all "assets/" and "assets/webpack_bundles"
# to be served at "my-static-url.com/asset-name.png"
# and "my-static-url.com/webpack_bundles/main.js"
os.path.join(BASE_DIR, 'assets'),
)
WEBPACK_LOADER = {
'DEFAULT': {
# Bundle directory, like in "my-static-url.com/webpack_bundles/main.js":
'BUNDLE_DIR_NAME': 'webpack_bundles/',
# Absolute path to where 'webpack-stats.json' is in Django project root:
'STATS_FILE': os.path.join(BASE_DIR, 'webpack-stats.json'),
# ...
}
}
In your deployment script, you must first run your Webpack build in production-mode, before calling collectstatic
:
NODE_ENV=production webpack --progress --bail --mode=production
python manage.py collectstatic --noinput
This means we're building the assets and, since we have webpack-bundle-tracker
in our Webpack building pipeline, the webpack-stats.json
stats file is also populated. If you followed the default configuration, the webpack-stats.json
will be at Django's project root (BASE_DIR
) and the render_bundle
template tag will be able to use it.
However, production usage for this package is fairly flexible, as the entire Django-Webpack integration depends only on the webpack-stats.json
file.
⚠️ Heroku is one platform that automatically runs collectstatic for you, so you need to set the
DISABLE_COLLECTSTATIC=1
environment var and manually run collectstatic after running Webpack. In Heroku, this is achieved with apost_compile
hook. Here's an example.
Advanced Usage
Hot reload
Hot reload (Hot Module Replacement) is critical for a improving the development workflow. In case you wish to enable for your project, please check out this example, in particular how webpack.config.js is configured. The key is to set the publicPath
and devServer
.
Dynamic Imports
In case you wish to use Dynamic Imports, please check out this example, in particular how webpack.config.js is configured.
Extra options for webpack-bundle-tracker
Check webpack-bundle-tracker
README for all supported options, such as relative paths, integrity hashes, timestamp logging, etc.
Extra WEBPACK_LOADER
settings in Django
Set those extra settings inside like this:
WEBPACK_LOADER = {
'DEFAULT': {
# settings go here
}
-
TIMEOUT
is the number of seconds webpack_loader should wait for Webpack to finish compiling before raising an exception.0
,None
or leaving the value out of settings disables timeouts -
INTEGRITY
is flag enabling Subresource Integrity on rendered<script>
and<link>
tags. Integrity hash is get from stats file and configuration on side ofBundleTracker
, where configuration optionintegrity: true
is required. -
LOADER_CLASS
is the fully qualified name of a python class as a string that holds the custom Webpack loader. This is where behavior can be customized as to how the stats file is loaded. Examples include loading the stats file from a database, cache, external URL, etc. For convenience,webpack_loader.loaders.WebpackLoader
can be extended. Theload_assets
method is likely where custom behavior will be added. This should return the stats file as an object.
Here's a simple example of loading from an external URL:
import requests
from webpack_loader.loaders import WebpackLoader
class ExternalWebpackLoader(WebpackLoader):
def load_assets(self):
url = self.config['STATS_URL']
return requests.get(url).json()
SKIP_COMMON_CHUNKS
(Default:False
) is a flag which prevents already generated chunks from being included again in the same page. This should only happen if you use more than one entrypoint per Django template (multiplerender_bundle
calls). By enabling this, you can get the same default behavior of the HtmlWebpackPlugin. The same caveats apply as when usingskip_common_chunks
onrender_bundle
, see that section below for more details.
Rendering by file extension
render_bundle
also takes a second argument which can be a file extension to match. This is useful when you want to render different types for files in separately. For example, to render CSS in head and JS at bottom we can do something like this:
{% load render_bundle from webpack_loader %}
<html>
<head>
{% render_bundle 'main' 'css' %}
</head>
<body>
....
{% render_bundle 'main' 'js' %}
</body>
</head>
Using preload
The is_preload=True
option in the render_bundle
template tag can be used to add rel="preload"
link tags:
{% load render_bundle from webpack_loader %}
<html>
<head>
{% render_bundle 'main' 'css' is_preload=True %}
{% render_bundle 'main' 'js' is_preload=True %}
{% render_bundle 'main' 'css' %}
</head>
<body>
{% render_bundle 'main' 'js' %}
</body>
</html>
Accessing other webpack assets
webpack_static
template tag provides facilities to load static assets managed by Webpack in Django templates. It is like Django's built in static
tag but for Webpack assets instead.
In the example below, logo.png
can be any static asset shipped with any npm package:
{% load webpack_static from webpack_loader %}
<!-- render full public path of logo.png -->
<img src="{% webpack_static 'logo.png' %}"/>
The public path is based on webpack.config.js
output.publicPath.
Please note that this approach will use the original asset file, and not a post-processed one from the Webpack pipeline, in case that file had gone through such flow (e.g.: You've imported an image on the React side and used it there, the file used within the React components will probably have a hash string on its name, etc. This processed file will be different than the one you'll grab with webpack_static
).
Use skip_common_chunks
on render_bundle
You can use the parameter skip_common_chunks=True
or skip_common_chunks=False
to override the global SKIP_COMMON_CHUNKS
setting for a specific bundle.
In order for this option to work, django-webpack-loader
requires the request
object to be in the template context. The request
object is passed by default via the django.template.context_processors.request
context processor, so make sure you have that.
If you don't have request
in the context for some reason (e.g. using Template.render
or render_to_string
directly without passing the request), you'll get warnings on the console and the common chunks will remain duplicated.
Appending file extensions
The suffix
option can be used to append a string at the end of the file URL. For instance, it can be used if your Webpack configuration emits compressed .gz
files.
{% load render_bundle from webpack_loader %}
<html>
<head>
<meta charset="UTF-8">
<title>Example</title>
{% render_bundle 'main' 'css' %}
</head>
<body>
{% render_bundle 'main' 'js' suffix='.gz' %}
</body>
</html>
Multiple Webpack configurations
django-webpack-loader
also supports multiple Webpack configurations. Assuming you have different Webpack configs, each with a different output.path
, the following configuration defines 2 Webpack stats files in settings and uses the config
argument in the template tags to influence which stats file to load the bundles from:
WEBPACK_LOADER = {
'DEFAULT': {
'BUNDLE_DIR_NAME': 'bundles/',
'STATS_FILE': os.path.join(BASE_DIR, 'webpack-stats.json'),
},
'DASHBOARD': {
'BUNDLE_DIR_NAME': 'dashboard_bundles/',
'STATS_FILE': os.path.join(BASE_DIR, 'webpack-stats-dashboard.json'),
}
}
{% load render_bundle from webpack_loader %}
<html>
<body>
....
{% render_bundle 'main' 'js' 'DEFAULT' %}
{% render_bundle 'main' 'js' 'DASHBOARD' %}
<!-- or render all files from a bundle -->
{% render_bundle 'main' config='DASHBOARD' %}
<!-- the following tags do the same thing -->
{% render_bundle 'main' 'css' 'DASHBOARD' %}
{% render_bundle 'main' extension='css' config='DASHBOARD' %}
{% render_bundle 'main' config='DASHBOARD' extension='css' %}
<!-- add some extra attributes to the tag -->
{% render_bundle 'main' 'js' 'DEFAULT' attrs='async charset="UTF-8"'%}
</body>
</head>
File URLs instead of HTML tags
If you need the URL to an asset without the HTML tags, the get_files
template tag can be used. A common use case is specifying the URL to a custom CSS file for a Javascript plugin.
get_files
works exactly like render_bundle
except it returns a list of matching files and lets you assign the list to a custom template variable.
Each object in the returned list has 2 properties:
name
, which is the name of a chunk from the stats file;url
, which can be:- The
publicPath
if the asset has one; - The
path
to the asset in the static files storage, if the asset doesn't have apublicPath
.
For example:
{% load get_files from webpack_loader %}
{% get_files 'editor' 'css' as editor_css_files %}
CKEDITOR.config.contentsCss = '{{ editor_css_files.0.url }}';
<!-- or list down name and url for every file -->
<ul>
{% for css_file in editor_css_files %}
<li>{{ css_file.name }} : {{ css_file.url }}</li>
{% endfor %}
</ul>
Jinja2 Configuration
If you need to output your assets in a jinja template, we provide a Jinja2 extension that's compatible with django-jinja.
To install the extension, add it to the TEMPLATES
configuration in the ["OPTIONS"]["extension"]
list.
from django_jinja.builtins import DEFAULT_EXTENSIONS
TEMPLATES = [
{
"BACKEND": "django_jinja.backend.Jinja2",
"OPTIONS": {
"extensions": DEFAULT_EXTENSIONS + [
"webpack_loader.contrib.jinja2ext.WebpackExtension",
],
}
}
]
Then in your base jinja template, do:
{{ render_bundle('main') }}
Note: get_files
in Jinja2 is called webpack_get_files
.
Migrating from version < 1.0.0
In order to use django-webpack-loader>=1.0.0
, you must ensure that webpack-bundle-tracker@1.0.0
is being used on the JavaScript side. It's recommended that you always keep at least minor version parity across both packages for full compatibility.
Contributing
This project includes a Makefile that provides several useful commands for building, installing, and publishing the project. Please feel free to open PRs or create issues!
Available Commands
clean
: Removes generated files and directories.build
: Cleans the project and builds the distribution packages.test
: Run the tests.install
: Installs the project's build dependencies. Will initialize a virtual environment if one does not exist.publish
: Builds the distribution packages and publishes them to the specified repository.register
: Registers the package on the specified repository.
To execute a command, run make <command>
in the project's root directory.
Virtual Environment Settings
ENV
: The name of the virtual environment. (Default:venv
)REPOSITORY
: The repository to publish the distribution packages to. (Default:pypi
)
Special Thanks
Django Webpack Loader was originally created by Owais Lone and received contributions from more than 50 developers since its inception, as well as many others who assisted with issues, comments, articles, talks, etc. Thanks for everyone who's been part of Django Webpack Loader community!
Commercial Support
This project is currently maintained by Vinta Software and is used in products of Vinta's clients. We are always looking for exciting work, so if you need any commercial support, feel free to get in touch: contact@vinta.com.br