Description

A minimal command extension to manage.py for making webpack work with django. Allows you to use a unique webpack configuration per django app.

Requirements

• python 2.7
• django 1.9
• django-webpack-loader
• node
• npm
• webpack
• webpack-bundle-tracker

Quickstart

For a complete example, see exampleapp/ in this repository.

• Assuming you have created a django app mydjangoapp
• install django-webpack-loader, you'll use this to render the webpack bundles in your djago templaes.

pip install django-webpack-loader
pip install django-webpack-helper

• Make the following changes to your project's settings.py file

# ensure BASE_DIR is defined !!

INSTALLED_APPS = [
    # ... all django defaults
    'webpack_loader',
    'webpack_helper',
    # ... all your remaining apps
    # your webpack app
    'mydjangoapp'
]

STATIC_URL = '/static/'

STATICFILES_DIRS = [
    #... all other static files
] + [os.path.join(BASE_DIR, 'webpack/static/')]

# see django-webpack-loader for full configuration instructions.
# you can add multiple entries here for each app!
WEBPACK_LOADER = {
    'DEFAULT': {
        'BUNDLE_DIR_NAME': 'bundles/',
        # XXX Change `mydjangoapp` below to your apps label
        'STATS_FILE': os.path.join(BASE_DIR, 'webpack/stats/mydjangoapp.json'),
    }
}              

• Ensure that BASE_DIR and STATIC_URL are defined in your settings.py.
• Ensure that node and npm is installed (I highly recommend looking at node version manager ). Then execute
• create a package.json file in the root of your project (Look at the exampleapp/ in this respository). To do this, you can execute the following:

npm init

• Install the initial webpack (1.x.x) dependencies for django-webpack-helper

python manage.py npm_install webpack_helper --save

• Next we'll generate a boilerplate webpack config for your django app. Assuming your app is called mydjangoapp.

python manage.py gen_webpack_config mydjangoapp/webpack.config.js  

• You can optionally include a package.json in your project, which you can install using python manage.py npm_install mydjangoapp.
• Next create a directory for your webpack files

mkdir mydjangoapp/assets/

• Create your first webpack app mydjangoapp/assets/index.js

console.log("Hello World")

• Add an entry to the entries array in webpack.config.js, for example:

   entries: [
      'mydjangoapp-index': [ path.join(__dirname, '/assets/mydjangoapp/index.js') ],  
   ]

• Now compile using webpack

python manage.py webpackh mydjangoapp

• Follow instructions from django-webpack-loader too include the javascript into your django templates.

manage.py commands

The package provides three commands:

• gen_webpack_config
• npm_install
• webpackh

Execute python manage.py <commandname> --help for complete help of each command.

Live Reload

• install django-livereload-server to get live reload capabilities

Additional Resources

• http://owaislone.org/blog/webpack-plus-reactjs-and-django/

Settings

See the settings.py file in the root of this repository for a full example.

All options are specified in a dictionary WEBPACK_HELPER in your settings.py file. Sensible defaults are given for all options, so you really don't need to set any.

For your convenience, here is the settings.py file, in full.

import os

# Build paths inside the project like this: os.path.join(BASE_DIR, ...)
BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))

# Application definition

INSTALLED_APPS = [
    # ... all django defaults
    'webpack_loader',
    'webpack_helper',
    # ... all your remaining apps
    # 'livereload' # ensures that django refreshes on any changes
]

MIDDLEWARE_CLASSES = [
    # ... all your other middleware
    # 'livereload.middleware.LiveReloadScript'
]

# Static files (CSS, JavaScript, Images)
# https://docs.djangoproject.com/en/1.9/howto/static-files/


STATIC_URL = '/static/'

# NOTE: All the settings below are already set to sensible
# defaults
WEBPACK_HELPER = {}

# The ocation of your node_modules (will be used to find webpack binary)
# Can be a relative or absolute path
WEBPACK_HELPER['NODE_MODULES'] = 'node_modules'

# the base output directory for webpack
# Can be a relative or absolute path
WEBPACK_HELPER['BASE_DIR'] = os.path.join(BASE_DIR, 'webpack')

# --- paths relative to WEBACK_HELPER['BASE_DIR']
# the folder that will be used to collect all webpack
# related output

# statistics generated by `webpack-bundle-tracker` (node app)
WEBACK_HELPER['STATS_DIR'] = 'stats/'
# static files (all files in here will be exposed to the internet by django)
WEBACK_HELPER['STATIC_DIR'] = 'static/'  
# webpack_helper generated configuration files go in here as `appname.json`
WEBACK_HELPER['CONFIG_DIR'] = 'config/'

# --- relative to STATIC_DIR!
# this is where webpack places your compiled bundles
WEBACK_HELPER['BUNDLE_DIR'] = 'bundles/'

# Where will the bundles live when we SERVE the website?
# Where will the contents of `static/bundles/` become visible?
# it can be a full URL
WEBPACK_HELPER['PUBLIC_PATH_BASE'] = STATIC_URL


# We do this so that django's collectstatic copies our bundles to the STATIC_ROOT
# or syncs them to whatever storage we use.
STATICFILES_DIRS = [
    # ... all your other directories
] + [os.path.join(WEBPACK_HELPER['BASE_DIR'], WEBACK_HELPER['STATIC_DIR'])]

# NOTE You must add an entry below for each app you
# wish to include.
# See django-webpack-loader's documentation for more details
WEBPACK_LOADER = {
    'DEFAULT': {
        # bundles go here (relative to our static apps directory)
        # i.e. `bundle/` is inside the staticfiles dir {WEBPACK_BASE_DIR}/static/
        'BUNDLE_DIR_NAME': 'bundles/',

        # NOTE the stats file path is built as follows: {WEBPACK_BASE_DIR}/{WEBPACK_STATS_DIR}/{applabel}.json
        'STATS_FILE': os.path.join(WEBPACK_HELPER['BASE_DIR'], 'webpack/stats/applabel.json'),

    }
}