New Webpack Boilerplate Project for Django & Flask

Background

About 1 month ago, I started writing tutorials about Webpack and Django Definitive Guide to Django and Webpack, and I hope it can help people to learn Webpack better because there are not many good tutorials in this area.

After receiving some user feedback, I realize a webpack boilerplate project is better, because many readers might not have much time to learn how Webpack works. What they want is just a project which can let them quickly write ES6 and SCSS in Django projects.

So I decided to take some time to solve this problem.

My Plan

The boilerplate project should contain two components:

A Webpack project template which has good structure, easy to use and customize. User can create frontend project using cookiecutter, and use it even they have no idea how to config Webpack.
Template tags which can help load Webpack bundle file in the templates, it should be smart to auto load dependency files. (Because Webpack has code splitting feature)

Webpack project template

There are some awesome open source Webpack boilerplate projects on Github. After researching, I chose wbkd/webpack-starter because it has all features I need.

And then I did some customization:

I added manifest plugin to the Webpack project, which generate manifest.json when Webpack compiling. So later I can write webpack loader to read the manifest.json to load the entrypoints and the dependency files.
The Webpack project would read entrypoints from a specific directory, so users do not need to edit Webpack config file but just create new files in the directory, which is very convenient

Webpack bundle loader

If you have some experience with Django, then you might hear of django-webpack-loader. I used it in many projects but also found some problems.

It should read webpack-stats.json generated by Webpack Bundle Tracker, a npm package create by the same author. It takes time to maintain both npm package and Django package, and the author is now looking for maintainers.
I do not like the API of django-webpack-loader, and it can not auto load dependency files when loading bundle files.

So I decide to write a new webpack loader based on django-webpack-loader, and solve the above problems at once.

Python Webpack Boilerplate

Here is my solution:

https://github.com/AccordBox/python-webpack-boilerplate

Easy to create

This project has a webpack project template and you can easily create frontend project like this:

$ python manage.py webpack_init
# here we use the default frontend slug
project_slug [frontend]:

Now you can go to frontend project and run command below:

$ cd frontend
$ npm install
$ npm run start

The project already supports ES6 and SCSS by default.
You can also import React or Vue to it by install extra packages (instructions can be found in the doc)

Webpack Loader

I also created new template tags to help people load Webpack bundle file in template

{% javascript_pack 'app' %}

If the entrypoint has other dependency, the template tag would also load it automatically

For example:

<script type="text/javascript" src="/static/js/runtime.5c7f161e.js" ></script>
<script type="text/javascript" src="/static/js/963.225830a8.js" ></script>
<script type="text/javascript" src="/static/js/app.c9e79e69.js" ></script>

As you can see, app.c9e79e69.js is loaded after dependency js files.

So now in templates we can only focus on the entrypoints without caring about the dependency and this template tag can help you handle it automatically.

You can also import multiple entrypoints in one page like this

{% javascript_pack 'app' 'app2' %}

You can also do the same thing for the css file

{% stylesheet_pack 'app' %}

The API is inspired by rails/webpacker

Flask

At first, I build this project for Django community, after I finish the draft version. I realize I can make it also work with Flask to help more people.

I made it work after some hours.

My wish

I have seen many cookiecutter-xxx projects use Webpack as frontend solution, but the config and file structures are different. So it is a PAIN to maintain the Webpack, Babel, and other config.

This project can work with both cookiecutter-django and cookiecutter-flask, and the frontend part would have consistent patterns.

Now Django developers and Flask developers can both contribute and help improve this project and make it become better.

And some people who have both Flask projects and Django projects would be happy!

That is why I give it name python-webpack-boilerplate, and I am open to support more Python web frameworks in the future.

Main Features

Supports Django and Flask (will support more framework in the future)
Automatic multiple entry points
Automatic code splitting
Hot Module Replacement (HMR)
Easy to config and customize
ES6 Support via babel (v7)
JavaScript Linting via eslint-loader
SCSS Support via sass-loader
Autoprefixing of browserspecific CSS rules via postcss and autoprefixer
Style Linting via stylelint

Project Link

https://github.com/AccordBox/python-webpack-boilerplate