django-webpack-loader
Use webpack to generate your static bundles without django's staticfiles or opaque wrappers.
Django webpack loader consumes the output generated by webpack-bundle-tracker and lets you use the generated bundles in django.
A changelog is also available.
Compatibility
Test cases cover Django>=2.0 on Python>=3.5. 100% code coverage is the target so we can be sure everything works anytime. It should probably work on older version of django as well but the package does not ship any test cases for them.
Install
npm install --save-dev webpack-bundle-tracker
pip install django-webpack-loader
Configuration
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('./assets/webpack_bundles/'),
filename: "[name]-[hash].js"
},
plugins: [
new BundleTracker({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 front-end 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 file with the information regarding the bundles and assets (webpack-stats.json) will be stored in the project root.
Compiling the front-end assets
You must generate the front-end bundle using webpack-bundle-tracker before using django-webpack-loader. You can compile the assets and generate the bundles by running:
npx webpack --config webpack.config.js --watch
This will also generate the stats file. You can also refer to how django-react-boilerplate configure the package.json scripts for different situations.
⚠️ Hot reload is available through a specific config. Check this section.
⚠️ This is the recommended usage for the development environment. For usage in production, please refer to this section
Configuring the 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.
WEBPACK_LOADER = {
'DEFAULT': {
'CACHE': not DEBUG,
'STATS_FILE': os.path.join(BASE_DIR, 'webpack-stats.json'),
'POLL_INTERVAL': 0.1,
'IGNORE': [r'.+\.hot-update.js', r'.+\.map'],
}
}
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 files paths in memory. From that point onwards, it will use these stored paths as the source of truth. If CACHE=False, we'll always read the stats file to get the assets paths.
⚠️ IfCACHE=True, any changes made in the assets files will only be read when the web workers are restarted.
During development, when the stats file changes a lot, we want to always poll for its updated version (in our case, we'll fetch it every 0.1s, as defined on POLL_INTERVAL).
⚠️ In production (DEBUG=False), we'll only fetch the stats file once, soPOLL_INTERVALis ignored.
While CACHE isn't directly related to POLL_INTERVAL, it's interesting to keep CACHE binded to the DEBUG logic value (in this case, the negation of the logic value) in order to only cache the assets in production, as we'd not continuously poll the stats file in that environment.
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 back-end side.
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.
Extra settings
-
TIMEOUTis the number of seconds webpack_loader should wait for webpack to finish compiling before raising an exception.0,Noneor leaving the value out of settings disables timeouts -
LOADER_CLASSis 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.loader.WebpackLoadercan be extended. Theload_assetsmethod 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.loader import WebpackLoader
class ExternalWebpackLoader(WebpackLoader):
def load_assets(self):
url = self.config['STATS_URL']
return requests.get(url).json()
Rendering
In order to render the front-end 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 multipleentryvalues here.
Below is the basic usage for render_bundle within a template:
{% load render_bundle from webpack_loader %}
{% render_bundle 'main' %}
That will render the proper
4 Nov 16, 2021
1 Mar 04, 2022
2.7k Jan 01, 2023
21 Dec 26, 2022
4.8k Jan 03, 2023
328 Dec 07, 2022
2 Oct 20, 2022
1.6k Dec 22, 2022
1 Oct 29, 2021
15 Aug 30, 2022
1 Jan 10, 2022
1 Dec 10, 2021
5 Dec 06, 2022
3 Nov 20, 2022
4.3k Dec 29, 2022
3.3k Jan 04, 2023
1 Nov 16, 2021
183 Jan 04, 2023
408 Jan 08, 2023