A CookieCutter template for modern, full-stack web applications.
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.
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.
- Use CookieCutter on the template:
cookiecutter gh:madelyneriksen/react-django-goodstuff- Start development!
make startAll 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.
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 testAll 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 lintIn cases where code can be auto-formatted (eslint --fix or black), you can use make to format the offending files:
make formatWhile 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 startUnder 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.
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 shellA 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!"""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):
pass
instance = MyClass()
instance.redis.ping()
# The redis instance is shared, and won't be duplicated.
assert instance.redis is redisTo 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!
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/0A 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 - www.madelyneriksen.com/contact
- audreyr's CookieCutter for making this possible.
- This README template from othneildrew.
- The vibrant open-source community that enables projects like this. 🌈