Django/Webpack Multi-Page Web App: Introduction
A setup to preserve your Django workflow with Webpack.
When was the last time you heard of someone talking about a “multi-page” web app? For me it’s been never. All over the internet we read articles of “single-page” this and “single-page” that. But what about the situations that don’t call for a single-page web-app? What if you’re not using one of the many front-end frameworks but still want to use ES6, SASS or other useful front-end tools? What if you’re using a more veteran technology, say, Django? Well then you’re in luck my friend.
This is a multi-part Medium series where I show you how I successfully use Webpack within my Django projects without sacrificing any of the standard Django workflows. Actually, the setup I will show works well for a variety of situations. You can choose to rely on front-end tools OR Django tools OR you can even mix it up into a hybrid approach. The beauty of this is the flexibility behind it.
The “Why”
I don’t like front-end frameworks…period. Ok that’s not entirely true. I really enjoy React and I’ve used it on a few projects. However, over the years I’ve seen front-end technologies come and go and watch the ecosystem become ever more volatile with change. It seems like every day a new framework comes out that you must learn or fear being left behind. There seemed to be no end.
That is when I fell in love with Django. Django has been around since 2005 and has seen great support over the years. It’s tried and true and works well. I was drawn in not only by the stability and reliability but also from it’s simplicity and elegance. However, I found that some things were just missing or at least easier to do with front-end technologies. I started to miss using npm to solve some of my needs. Not to mention being able to use ES6 classes, oh man do I hate not using ES6 classes.
Initially I had a choice:
- Go full on Django and create widgets for everything and use raw Javascript/CSS as needed.
- Separate the front-end into a separate web project.
I didn’t like either of these choices. I loved the Django workflow with templates and routing. But I also loved how with Webpack I can use many niceties that made the front-end easier. I wanted the best of both worlds.
I want to have my cake and to eat it too! I soon discovered I could!
It took me a while but with the help of a short tutorial by VALENTINO GAGLIARDI I was finally pointed in the right direction. I started to see the light at the end of the tunnel.
Goals of Setup
Now, I didn’t want just any setup. I wanted something that could fit my needs and also be flexible as front-end tools change in the future. I came up with the following goals.
1. Must integrate into Django templates
I want to continue using the {% static 'resource' %} template tag with my frontend code. I want to include specific Javascript files on specific screens and not load all JS on every screen. This is the point of multi-page web-apps after all.
2. Webpack must work similar to a compiler
Those static tag imports wouldn’t work very well if it meant I couldn’t share code between files. Webpack must be able to bundle up shared code on an as-needed basis.
3. Maintain front-end file hierarchy
This one is huge. Webpack usually builds to a “bundle” file. This breaks the idea of #1 since the bundle contains ALL code and it would be loaded on every screen.
Instead, the build directory should look identical to the development directory so using {% static 'resource_path' %} can look identical to the hierarchy you are organizing within your front-end assets directories. This maintains the integrity of the Django development workflow when working with templates. You don’t need to look up special build paths for the Javascript files you need to use with the static keyword.
More on this one later in the series.
4. Must be able to specify entry points outside of the Webpack Config
Webpack needs to know what JS files to use as entrypoints to it’s dependency graph. Trying to maintain that list within the config file can be a nightmare at scale. The setup must have a way of specifying entrypoints within the file structure.
5. Must be cache friendly
What’s the point of all this if your load times suffer.
6. Must be easy to use and make my life easier
The biggest one of them all. As a developer I need a setup that enhances my workflow not inhibits it. It MUST be easy to use.
When To Use
I’ll be honest with you. This is NOT a trivial setup. While it is simple to use, after the architecture is up and running, it is not for everyone. Small projects will most likely not benefit that much from this as you could just use a single-page setup for those.
However, once you master the system and set it up once it’s pretty simple to just copy the necessary files to a new project. The choice to use it falls on you.
Personally, I find this setup is best used in the following situations:
- The app will be large with many screens.
- You need a “mixed bag” of tools for specific situations.
- You already set up the architecture and can easily reuse it on a small project (it still works well here).
- You’re migrating a legacy Django project slowly to new front-end tools.
- You really want to use newer front-end tools and not using them is giving you gray hairs that your spouse doesn’t like.
When NOT To Use
I’ll give you this warning only once. DO NOT use this architecture without formal documentation. This is an opinionated architecture and as of the writing of this article it has not been used much. If you just throw it into a project and expect the next developer to “know” what’s going on you are going to cause issues. At the very least link back to this article for reference within a README.md file.
My Teaching Style
My intention is not to just throw code at you and hope you figure it out. I was never a fan of those kinds of tutorials anyway. My goal is to be as verbose as I can so you readers will get (what I hope will be) a good understanding on what is going on and why it does the things it does.
Although, if you’re looking for something to sink your teeth into I’ll be linking tutorial files you can us to follow along with in the next article.
Next Steps:
That’s the end of the introduction. In the next article we’ll get the Django Polls project set up as a starting point for the architecture.
