In order to overcome the lack of support for Markdown on PyPi, buildingthis package can use `pandoc <http://pandoc.org/installing.html>`__along with `pypandoc <https://pypi.python.org/pypi/pypandoc>`__ toconvert the README.md into a Restructured Text format compatible withPyPI. This requires installing ``pandoc`` for your operating system(installation instructions on the pandoc site), and ``pypandoc`` whichwill be installed if you:

::

pip install -r requirements-dev.txt

before uploading to PyPI.

If pandoc or pypandoc fails, the README.md file will be uploaded as itwas before this enhancement.

Compatibility-------------

Test cases cover Django>=1.6 on Python 2.7 and Python>=3.3. 100% codecoverage is the target so we can be sure everything works anytime. Itshould probably work on older version of django as well but the packagedoes not ship any test cases for them.

Install-------

.. code:: bash

npm install --save-dev webpack-bundle-tracker

pip install django-webpack-loader

Configuration-------------

Assumptions~~~~~~~~~~~

Assuming ``BASE_DIR`` in settings refers to the root of your django app.

When ``CACHE`` is set to True, webpack-loader will read the stats fileonly once and cache the result. This means web workers need to berestarted in order to pick up any changes made to the stats files.

``BUNDLE_DIR_NAME`` refers to the dir in which webpack outputs thebundles. It should not be the full path. If ``./assets`` is one of youstatic dirs and webpack generates the bundles in``./assets/output/bundles/``, then ``BUNDLE_DIR_NAME`` should be``output/bundles/``.

If the bundle generates a file called ``main-cf4b5fab6e00a404e0c7.js``and your STATIC\_URL is ``/static/``, then the ``<script>`` tag willlook like this

``STATS_FILE`` is the filesystem path to the file generated by``webpack-bundle-tracker`` plugin. If you initialize``webpack-bundle-tracker`` plugin like this

.. code:: javascript

new BundleTracker({filename: './webpack-stats.json'})

and your webpack config is located at ``/home/src/webpack.config.js``,then the value of ``STATS_FILE`` should be``/home/src/webpack-stats.json``

IGNORE^^^^^^

``IGNORE`` is a list of regular expressions. If a file generated bywebpack matches one of the expressions, the file will not be included inthe template.

POLL\_INTERVAL^^^^^^^^^^^^^^

``POLL_INTERVAL`` is the number of seconds webpack\_loader should waitbetween polling the stats file. The stats file is polled every 100miliseconds by default and any requests to are blocked while webpackcompiles the bundles. You can reduce this if your bundles take shorterto compile.

**NOTE:** Stats file is not polled when in production (DEBUG=False).

TIMEOUT^^^^^^^

``TIMEOUT`` is the number of seconds webpack\_loader should wait forwebpack to finish compiling before raising an exception. ``0``, ``None``or leaving the value out of settings disables timeouts.

Usage-----

Manually run webpack to build assets.~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

One of the core principles of django-webpack-loader is to not managewebpack itself in order to give you the flexibility to run webpack theway you want. If you are new to webpack, check one of the`examples <https://github.com/owais/django-webpack-loader/tree/master/examples>`__,read `my detailed blogpost <http://owaislone.org/blog/webpack-plus-reactjs-and-django/>`__ orcheck `webpack docs <http://webpack.github.io/>`__.

Settings~~~~~~~~

Add ``webpack_loader`` to ``INSTALLED_APPS``

::

INSTALLED_APPS = ( ... 'webpack_loader', )

Templates~~~~~~~~~

.. code:: html+django

{% load render_bundle from webpack_loader %}

{% render_bundle 'main' %}

``render_bundle`` will render the proper ``<script>`` and ``<link>``tags needed in your template.

``render_bundle`` also takes a second argument which can be a fileextension to match. This is useful when you want to render differenttypes for files in separately. For example, to render CSS in head and JSat bottom we can do something like this,

Version 2.0 and up of webpack loader also supports multiple webpackconfigurations. The following configuration defines 2 webpack statsfiles in settings and uses the ``config`` argument in the template tagsto influence which stats file to load the bundles from.

``webpack_static`` template tag provides facilities to load staticassets managed by webpack in django templates. It is like django's builtin ``static`` tag but for webpack assets instead. In the below example,``logo.png`` can be any static asset shipped with any npm or bowerpackage.

**It is up to you**. There are a few ways to handle this. I like to haveslightly separate configs for production and local. I tell git to ignoremy local stats + bundle file but track the ones for production. Beforepushing out newer version to production, I generate a new bundle usingproduction config and commit the new stats file and bundle. I store thestats file and bundles in a directory that is added to the``STATICFILES_DIR``. This gives me integration with collectstatic forfree. The generated bundles are automatically collected to the targetdirectory and synched to S3.