Django Webpack Loader

Warnings

• breaking Versions >= 1.0.0 of `django-webpack-loader` require `webpack-bundle-tracker@1.0.0` or higher due to a change in the `webpack-stats.json` file format. It is recommended to maintain at least minor version parity between both packages for full compatibility.
  Fix: Ensure your `package.json` specifies `webpack-bundle-tracker` version `1.0.0` or higher (e.g., `^2.0.0` for recent `django-webpack-loader` versions) and rebuild your Webpack assets.
• breaking Version 3.0.0 introduced improved support for `publicPath: 'auto'` in Webpack configurations. If your existing setup relied on specific workarounds for `publicPath` behavior with earlier versions, you might need to review and adjust your Webpack and `WEBPACK_LOADER` configurations.
  Fix: Review your `webpack.config.js` `output.publicPath` and `WEBPACK_LOADER['DEFAULT']['PUBLIC_PATH']` settings. Test thoroughly, especially if you were using complex `publicPath` configurations before version 3.0.0.
• gotcha The default `TIMEOUT` for `webpack_loader` in development is `0` (never timeout). This can cause your Django development server to hang silently if the Webpack development server is not running, is slow to compile, or gets stuck in a 'compile' state, blocking all requests without explicit error messages. Version 3.2.3 added a warning log for this scenario.
  Fix: It is highly recommended to set a sensible `TIMEOUT` value in your `WEBPACK_LOADER` settings (e.g., `10` seconds) to prevent infinite waits during development: `'TIMEOUT': 10,`.
• gotcha Incorrectly configured `STATS_FILE` or `BUNDLE_DIR_NAME` in `WEBPACK_LOADER` settings relative to your Webpack output and Django's `STATICFILES_DIRS` is a very common setup error. These paths must precisely match how Webpack is configured to output `webpack-stats.json` and its bundles.
  Fix: Double-check that `WEBPACK_LOADER['DEFAULT']['STATS_FILE']` is the absolute path to your `webpack-stats.json` and `WEBPACK_LOADER['DEFAULT']['BUNDLE_DIR_NAME']` is the *relative path* from one of your `STATICFILES_DIRS` to where Webpack places bundles. Ensure `webpack.config.js` `output.path` aligns with `STATICFILES_DIRS` and `BUNDLE_DIR_NAME`.
• gotcha The `skip_common_chunks=True` option in `render_bundle` requires the Django `request` object to be present in the template context (e.g., via `django.template.context_processors.request` middleware) to function correctly and deduplicate chunks. Without it, common chunks might be duplicated in the output, and you might receive console warnings.
  Fix: Ensure `django.template.context_processors.request` is included in your `TEMPLATES` `OPTIONS['context_processors']` in `settings.py`.

Install

• pip install django-webpack-loader Install Python package
• npm install --save-dev webpack-bundle-tracker Install Node.js companion package

Imports

• webpack_loader

  INSTALLED_APPS = ['webpack_loader', ...]

  Add 'webpack_loader' to your Django project's INSTALLED_APPS in settings.py.
• render_bundle

  {% load render_bundle from webpack_loader %}

  Used in Django templates to render Webpack bundles (e.g., JS or CSS files) for a specific entry point.
• webpack_static

  {% load webpack_static from webpack_loader %}

  Similar to Django's built-in `static` tag, but for Webpack-managed static assets.

Quickstart

This quickstart demonstrates the essential Django `settings.py` configuration for `django-webpack-loader` and an example of its usage within a Django template. It defines `INSTALLED_APPS`, `STATICFILES_DIRS` to tell Django where static assets are located, and the `WEBPACK_LOADER` dictionary, which points to the `webpack-stats.json` file and specifies the bundle output directory. A minimal `webpack.config.js` setup is also provided as context, showing how to configure `webpack-bundle-tracker` to generate the necessary `webpack-stats.json` file. Remember that `webpack-bundle-tracker` must be separately installed and configured in your Webpack build process.

import os

# settings.py

BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))

INSTALLED_APPS = [
    # ... other Django apps
    'webpack_loader',
]

STATICFILES_DIRS = (
    os.path.join(BASE_DIR, 'assets'), # Where your frontend source and webpack bundles might live
)

WEBPACK_LOADER = {
    'DEFAULT': {
        'BUNDLE_DIR_NAME': 'webpack_bundles/', # Webpack output directory within STATICFILES_DIRS
        'STATS_FILE': os.path.join(BASE_DIR, 'webpack-stats.json'), # Path to webpack-stats.json
        'POLL_INTERVAL': 0.1, # Optional: Poll interval for stats file changes in dev mode (default 0.1s)
        'TIMEOUT': 10, # Optional: Timeout for webpack compilation in dev mode (default 0, never timeouts)
        'CACHE': not DEBUG, # Cache results in production
        'PUBLIC_PATH': '/static/webpack_bundles/', # Typically matches output.publicPath in webpack config
    }
}

# myapp/templates/myapp/index.html
# {% load render_bundle from webpack_loader %}
# <!DOCTYPE html>
# <html>
# <head>
#     <title>My Django App</title>
#     {% render_bundle 'main' 'css' %}
# </head>
# <body>
#     <div id="app"></div>
#     {% render_bundle 'main' 'js' %}
# </body>
# </html>

# Corresponding minimal webpack.config.js snippet (requires webpack-bundle-tracker):
# const path = require('path');
# const BundleTracker = require('webpack-bundle-tracker');
#
# module.exports = {
#   context: __dirname,
#   entry: './assets/js/index.js',
#   output: {
#     path: path.resolve('./assets/webpack_bundles/'),
#     filename: '[name]-[contenthash].js',
#     publicPath: '/static/webpack_bundles/',
#   },
#   plugins: [
#     new BundleTracker({ filename: './webpack-stats.json' }),
#   ],
# };