Home

Awesome

Django React Boilerplate

Contributor Covenant License: MIT

About

A Django project boilerplate/template with a multitude of state-of-the-art libraries and tools. If pairing Django with React is a possibility for your project or spinoff, this is the best solution available. Save time with tools like:

For continuous integration, a Github Action configuration .github/workflows/main.yml is included.

Also, includes a Render.com render.yaml and a working Django production.py settings, enabling easy deployments with 'Deploy to Render' button. The render.yaml includes the following:

Features Catalogue

Frontend

Backend

Share your project!

Several people have leveraged our boilerplate to start spinoffs or to boost their efforts in the challenging pursuit of securing funding. Starting with a solid foundation allows you to create more resilient products and focus on what really matters: discovering and delivering value to your customers. If you are one of those people, we're eager to help you even more! We can spread the word about your project across our social media platforms, giving you access to a broader audience.

Send us an email at contact@vintasoftware.com telling us a bit more about how our boilerplate helped you boost your project.

Project bootstrap main Known Vulnerabilities

In the next steps, always remember to replace {{project_name}} with your project's name (in case it isn't yet):

After completing ALL of the above, remove this Project bootstrap section from the project README. Then follow Running below.

Running

Tools

Setup

If you are using Docker:

Adding new dependencies

If you are not using Docker:

Setup the backend app

Run the backend app

Setup and run the frontend app

Setup Celery

Setup Redis

Mailhog

Testing

make test

Will run django tests using --keepdb and --parallel. You may pass a path to the desired test module in the make command. E.g.:

make test someapp.tests.test_views

Adding new pypi libs

To add a new backend dependency, run poetry add {dependency}. If the dependency should be only available for development user append -G dev to the command.

API Schema and Client generation

We use the DRF-Spectacular tool to generate an OpenAPI schema from our Django Rest Framework API. The OpenAPI schema serves as the backbone for generating client code, creating comprehensive API documentation, and more.

The API documentation pages are accessible at http://localhost:8000/api/schema/swagger-ui/ or http://localhost:8000/api/schema/redoc/.

[!IMPORTANT] Anytime a view is created, updated, or removed, the schema must be updated to reflect the changes. Failing to do so can lead to outdated client code or documentation.

To update the schema, run:

We use the openapi-ts tool to generate TypeScript client code from the OpenAPI schema. The generated client code is used to interact with the API in a type-safe manner.

[!IMPORTANT] Anytime the API schema is updated, the client code must be regenerated to reflect the changes. Failing to do so can lead to type errors in the client code.

To update the client code, run:

[!NOTE] If pre-commit is properly enabled, it will automatically update both schema and client before each commit whenever necessary.

Github Actions

To enable Continuous Integration through Github Actions, we provide a proj_main.yml file. To connect it to Github you need to rename it to main.yml and move it to the .github/workflows/ directory.

You can do it with the following commands:

mkdir -p .github/workflows
mv proj_main.yml .github/workflows/main.yml

Production Deployment

Setup

This project comes with an render.yaml file, which can be used to create an app on Render.com from a GitHub repository.

Before deploying, please make sure you've generated an up-to-date poetry.lock file containing the Python dependencies. This is necessary even if you've used Docker for local runs. Do so by following these instructions.

After setting up the project, you can init a repository and push it on GitHub. If your repository is public, you can use the following button:

Deploy to Render

If you are in a private repository, access the following link replacing $YOUR_REPOSITORY_URL$ with your repository link.

Keep reading to learn how to configure the prompted environment variables.

ALLOWED_HOSTS

Chances are your project name isn't unique in Render, and you'll get a randomized suffix as your full app URL like: https://{{project_name}}-a1b2.onrender.com.

But this will only happen after the first deploy, so you are not able to properly fill ALLOWED_HOSTS yet. Simply set it to * then fix it later to something like {{project_name}}-a1b2.onrender.com and your domain name like example.org.

ENABLE_DJANGO_COLLECTSTATIC

Default is 1, meaning the build script will run collectstatic during deploys.

AUTO_MIGRATE

Default is 1, meaning the build script will run collectstatic during deploys.

Build script

By default, the project will always run the render_build.sh script during deployments. This script does the following:

  1. Build the frontend
  2. Build the backend
  3. Run Django checks
  4. Run collectstatic
  5. Run Django migrations
  6. Push frontend source maps to Sentry

Celery

As there aren't free plans for Workers in Render.com, the configuration for Celery workers/beat will be commented by default in the render.yaml. This means celery won't be available by default.

Uncommenting the worker configuration lines on render.yaml will imply in costs.

SendGrid

To enable sending emails from your application you'll need to have a valid SendGrid account and also a valid verified sender identity. After finishing the validation process you'll be able to generate the API credentials and define the SENDGRID_USERNAME and SENDGRID_PASSWORD environment variables on Render.com.

These variables are required for your application to work on Render.com since it's pre-configured to automatically email admins when the application is unable to handle errors gracefully.

Media storage

Media files integration with S3 or similar is not supported yet. Please feel free to contribute!

Sentry

Sentry is already set up on the project. For production, add SENTRY_DSN environment variable on Render.com, with your Sentry DSN as the value.

You can test your Sentry configuration by deploying the boilerplate with the sample page and clicking on the corresponding button.

Sentry source maps for JS files

The render_build.sh script has a step to push Javascript source maps to Sentry, however some environment variables need to be set on Render.com.

The environment variables that need to be set are:

After enabling dyno metadata and setting the environment variables, your next Render.com Deploys will create a release on Sentry where the release name is the commit SHA, and it will push the source maps to it.

Linting

Pre-commit hooks

If you are using Docker:

If you are not using Docker:

Opinionated Settings

Some settings defaults were decided based on Vinta's experiences. Here's the rationale behind them:

DATABASES["default"]["ATOMIC_REQUESTS"] = True

CELERY_TASK_ACKS_LATE = True

Django-CSP

Django-CSP helps implementing Content Security Policy (CSP) in Django projects to mitigate cross-site scripting (XSS) attacks by declaring which dynamic resources are allowed to load.

In this project, we have defined several CSP settings that define the sources from which different types of resources can be loaded. If you need to load external images, fonts, or other resources, you will need to add the sources to the corresponding CSP settings. For example:

Please note that you should only add trusted sources to these settings to maintain the security of your site. For more details, please refer to the Django-CSP documentation.

Contributing

If you wish to contribute to this project, please first discuss the change you wish to make via an issue.

Check our contributing guide to learn more about our development process and how you can test your changes to the boilerplate.

Commercial Support

alt text

This project is maintained by Vinta Software and is used in products of Vinta's clients. We are always looking for exciting work! If you need any commercial support, feel free to get in touch: contact@vinta.com.br