Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

React Django GoodStuff

License: MIT PRs Welcome

A CookieCutter template for modern, full-stack web applications.

Table of Contents

About The Project

A major barrier to creating new projects is having to create the same basic infrastructure code over and over. Instead of recreating the same project structure over and over, use this polygot, opinionated boilerplate to start new projects in a flash.


  • Frontend powered by React.js
  • Python backend with Django and Django Rest Framework 🐍
  • Container-first development- entire project built in Docker 🐳
  • Built-in Github Actions for Integration & Unit Tests
  • Postgres as the relational database 🐘
  • Redis session and storage for fast caching. 🚀
  • Django Allauth for easy social logins.
  • Hot reloading development with Docker Compose, 12-factor inspired configuration, and more.

Getting Started

To get a local copy up and running follow these simple steps.


You will need GNU make and CookieCutter installed on your system to use this template. Please note that usage on Windows (without WSL) is untested and likely to have issues.


  1. Use CookieCutter on the template:
cookiecutter gh:madelyneriksen/react-django-goodstuff
  1. Start development!
make start


Docker First Philosophy 🐳

All dependencies of the project are bundled into Docker, with the final version of the project being a single Docker container. This is to maximize portability; on any machine with Docker you can build or even deploy the project effortlessly.

The implications on the project are that all commands, including tests, linting, and formatting, run via a Docker container. This ensures Docker remains a first-class citizen for the project and prevents discrepancies between development and production environments.

Running Tests

Python tests are run with Pytest while React tests use Jest and Enzyme.

While the tests themselves are run in Docker, for convenience there is a make target to run all tests:

make test

Linting and Formatting

All Python code follows the Black codestyle, while Javascript uses the Airbnb Styleguide.

You can check style and lint code with make, which wraps around a Docker command:

make lint

In cases where code can be auto-formatted (eslint --fix or black), you can use make to format the offending files:

make format


While creating webapps, it's handy to have hot module reloading to see changes as they are ready. Thankfully, you can do just that with this project on both the Python and Javascript codebases, at the same time:

make start

Under the hood, this uses Parcel's hot module reloading feature alongside Gunicorn's --reload flag. Docker Compose binds the HMR websocket to the host, and the compiled javascript is collected and served by Gunicorn using WhiteNoise.

Shell Commands

Sometimes, you just need a plain-old bash shell in your project. Maybe you need to run Django management commands, database migrations, or do some interactive debugging. You can open a shell with (you guessed it) make:

make shell

Python Extras

Abstract Base Model

A BaseModel is included in app.base.models that uses a UUID field instead of an auto-incrementing integer. Oftentimes, this plays better with a single page application than an auto-incrementing ID does.

You can use the base model like you would the standard models.Model class in Django:

class MyModel(BaseModel):
    """Just a regular model here, folks!"""

Redis Utilities

Interacting with Redis directly is often a requirement, so a couple utilities are included to do just that:

from my_app.base.utils.redis import connection, RedisMixin

# connection() creates a singleton instance
redis = connection()

# You can also use a mixin to add a `.redis` property to any class

class MyClass(RedisMixin):

instance = MyClass()

# The redis instance is shared, and won't be duplicated.
assert instance.redis is redis

Testing Utilities

To make writing tests easier, Pytest Django is included. It adds useful fixtures for testing routes, integration tests on the database, and other helpers. Check it out!

URL-style configuration

Both Redis and Postgres connection settings are configured through environment variables that contain a URL string. This makes deployment of the application super straightforward.

# Some examples...
DATABASE_URL = postgres://username:password@host:5432/database
REDIS_URL = redis://redis:6379/0

Rest Framework

A standard integration with Django Rest Framework and Django Filters is included out of the box. An example route for Users is included in base.api, with the router stored in the main project folder.

If you want to use Graphql instead, try Graphene Django. There is also a tutorial on using Graphql with Django on my blog if you are interested in the details.


Thanks to Docker and WhiteNoise, deployment on most cloud providers or any Kubernetes cluster is easy, and steps outside of the scope of this boilerplate.

However, you should take care to set required environment variables:

  • DATABASE_URL - Postgres uri string.
  • REDIS_URL - Redis uri string.
  • SECRET_KEY - Django secret key.

It might be nice to set these too:

  • ADMINS - Add email addresses of the admin team.
  • EMAIL_BACKEND - Configure your email solution.

Additionally, set ALLOWED_HOSTS in your settings file, and change the default site domain created by the Django sites framework. For more Django deployment information see the official documentation.


Contributions are welcome, including bug, documentation, or feature requests. PRs/suggestions are also welcome and greatly appreciated!


Distributed under terms of the MIT License.


Madelyn Eriksen -