My Django App

{"id":4520,"library":"django-webpack-loader","title":"Django Webpack Loader","description":"Django Webpack Loader transparently integrates Webpack-generated frontend assets (JavaScript, CSS, images, etc.) into Django templates. It achieves this by consuming a `webpack-stats.json` file, which is typically generated by the `webpack-bundle-tracker` plugin. The library is actively maintained, currently at version 3.2.3, and generally aligns its compatibility with Django and Node.js LTS releases.","status":"active","version":"3.2.3","language":"en","source_language":"en","source_url":"https://github.com/django-webpack/django-webpack-loader","tags":["django","webpack","frontend","asset management","staticfiles","javascript","css"],"install":[{"cmd":"pip install django-webpack-loader","lang":"bash","label":"Install Python package"},{"cmd":"npm install --save-dev webpack-bundle-tracker","lang":"bash","label":"Install Node.js companion package"}],"dependencies":[{"reason":"Essential Node.js package for Webpack that generates the `webpack-stats.json` file consumed by django-webpack-loader. It's crucial for the integration.","package":"webpack-bundle-tracker","optional":false}],"imports":[{"note":"Add 'webpack_loader' to your Django project's INSTALLED_APPS in settings.py.","symbol":"webpack_loader","correct":"INSTALLED_APPS = ['webpack_loader', ...]"},{"note":"Used in Django templates to render Webpack bundles (e.g., JS or CSS files) for a specific entry point.","symbol":"render_bundle","correct":"{% load render_bundle from webpack_loader %}"},{"note":"Similar to Django's built-in `static` tag, but for Webpack-managed static assets.","symbol":"webpack_static","correct":"{% load webpack_static from webpack_loader %}"}],"quickstart":{"code":"import os\n\n# settings.py\n\nBASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))\n\nINSTALLED_APPS = [\n # ... other Django apps\n 'webpack_loader',\n]\n\nSTATICFILES_DIRS = (\n os.path.join(BASE_DIR, 'assets'), # Where your frontend source and webpack bundles might live\n)\n\nWEBPACK_LOADER = {\n 'DEFAULT': {\n 'BUNDLE_DIR_NAME': 'webpack_bundles/', # Webpack output directory within STATICFILES_DIRS\n 'STATS_FILE': os.path.join(BASE_DIR, 'webpack-stats.json'), # Path to webpack-stats.json\n 'POLL_INTERVAL': 0.1, # Optional: Poll interval for stats file changes in dev mode (default 0.1s)\n 'TIMEOUT': 10, # Optional: Timeout for webpack compilation in dev mode (default 0, never timeouts)\n 'CACHE': not DEBUG, # Cache results in production\n 'PUBLIC_PATH': '/static/webpack_bundles/', # Typically matches output.publicPath in webpack config\n }\n}\n\n# myapp/templates/myapp/index.html\n# {% load render_bundle from webpack_loader %}\n# \n# \n# \n# My Django App\n# {% render_bundle 'main' 'css' %}\n# \n# \n#

\n# {% render_bundle 'main' 'js' %}\n# \n# \n\n# Corresponding minimal webpack.config.js snippet (requires webpack-bundle-tracker):\n# const path = require('path');\n# const BundleTracker = require('webpack-bundle-tracker');\n#\n# module.exports = {\n# context: __dirname,\n# entry: './assets/js/index.js',\n# output: {\n# path: path.resolve('./assets/webpack_bundles/'),\n# filename: '[name]-[contenthash].js',\n# publicPath: '/static/webpack_bundles/',\n# },\n# plugins: [\n# new BundleTracker({ filename: './webpack-stats.json' }),\n# ],\n# };","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"3.0.0"},{"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,`.","message":"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.","severity":"gotcha","affected_versions":"All versions, specifically noticeable before 3.2.3 which added a warning."},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure `django.template.context_processors.request` is included in your `TEMPLATES` `OPTIONS['context_processors']` in `settings.py`.","message":"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.","severity":"gotcha","affected_versions":"All versions using `skip_common_chunks`"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}