{"id":18789815,"url":"https://github.com/marcelovicentegc/django-react-typescript","last_synced_at":"2025-10-11T07:41:54.302Z","repository":{"id":39026200,"uuid":"269163085","full_name":"marcelovicentegc/django-react-typescript","owner":"marcelovicentegc","description":"This is a non-opinionated Django 5 + React 18 boilerplate built with great development experience and easy deployment in mind.","archived":false,"fork":false,"pushed_at":"2024-12-15T15:45:37.000Z","size":3261,"stargazers_count":378,"open_issues_count":12,"forks_count":66,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-05-23T05:11:58.928Z","etag":null,"topics":["boilerplate","django","django-react","django-react-boilerplate","django-react-integration","djangorestframework","docker","docker-compose","github-actions","python","react","typescript"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marcelovicentegc.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"patreon":"marcelovicentegc","custom":"https://www.buymeacoffee.com/YkwcZVO"}},"created_at":"2020-06-03T18:21:42.000Z","updated_at":"2025-05-22T23:53:12.000Z","dependencies_parsed_at":"2024-11-14T22:01:18.863Z","dependency_job_id":"6f254df6-885a-4e3c-a4c0-a338aac05e8b","html_url":"https://github.com/marcelovicentegc/django-react-typescript","commit_stats":{"total_commits":113,"total_committers":3,"mean_commits":"37.666666666666664","dds":0.2831858407079646,"last_synced_commit":"e512919cc4ef2676d61eefe26298ea725f502728"},"previous_names":[],"tags_count":2,"template":true,"template_full_name":null,"purl":"pkg:github/marcelovicentegc/django-react-typescript","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcelovicentegc%2Fdjango-react-typescript","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcelovicentegc%2Fdjango-react-typescript/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcelovicentegc%2Fdjango-react-typescript/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcelovicentegc%2Fdjango-react-typescript/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marcelovicentegc","download_url":"https://codeload.github.com/marcelovicentegc/django-react-typescript/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcelovicentegc%2Fdjango-react-typescript/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279006626,"owners_count":26084131,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["boilerplate","django","django-react","django-react-boilerplate","django-react-integration","djangorestframework","docker","docker-compose","github-actions","python","react","typescript"],"created_at":"2024-11-07T21:08:44.325Z","updated_at":"2025-10-11T07:41:54.283Z","avatar_url":"https://github.com/marcelovicentegc.png","language":"Python","readme":"# django-react-typescript \u003c!-- omit from toc --\u003e\n\n\u003cimg alt=\"django-react-typescript logo\" src=\"assets/Logo.png\" align=\"right\" width=\"120\" height=\"120\" /\u003e\n\nThis is an non-opinionated Django 5 + React 18 boilerplate built with great development experience and easy deployment in mind.\n\nThis template is ideal if you want to bootstrap a blog or a portfolio website quickly, or even a more complex application that requires a CMS, all while leveraging the best from React and Django.\n\n---\n\n- [Getting started](#getting-started)\n  - [Setting up a database](#setting-up-a-database)\n  - [Setting up a CDN](#setting-up-a-cdn)\n  - [Running the project](#running-the-project)\n- [Application architecture](#application-architecture)\n  - [Features](#features)\n- [Going to production: infrastructure \\\u0026 deployment](#going-to-production-infrastructure--deployment)\n  - [Virtualized Deploy Workflow](#virtualized-deploy-workflow)\n  - [Bare-metal Deploy Workflow](#bare-metal-deploy-workflow)\n  - [Configuration](#configuration)\n  - [Architecture overview](#architecture-overview)\n- [Similar projects](#similar-projects)\n\n## Getting started\n\nThis project relies on [pnpm](https://pnpm.io/) and [Poetry](https://python-poetry.org/) to manage Node.js and Python dependencies, respectively. Make sure to have both installed on your machine before proceeding.\n\nAfter cloning this project, install all dependencies by running:\n\n```sh\npnpm run bootstrap\n```\n\nThis command will install all dependencies for the frontend (React) and backend (Django) apps.\n\n### Setting up a database\n\nTo start developing on this project, you will need a Postgres database instance running. It doesn 't matter if it's a local instance or a remote one. Just make sure to set up a Postgres database and configure the `.env` file with the correct credentials.\n\nFor convenience, if you want to use Docker + Docker Compose to spin up a Postgres instance locally, with pgAdmin using alongisde, use the following command:\n\n```sh\npnpm run dev:db:up\n```\n\n### Setting up a CDN\n\nThis project uses Cloudinary as a CDN, so you will need to have an account on Cloudinary and set up the `.env` file with the correct credentials. Use the [`.env.example`](./.env.example) file as a reference.\n\nFeel free to open an issue if you want to use another CDN, and I'll be happy to help you set it up.\n\n### Running the project\n\nOnce you've set up the database, you can start the project by running one of:\n\n```sh\npnpm dev # Starts the project while assuming you've setup a database not using the Docker Compose setup. Spins up only the backend and frontend apps\npnpm dev:full # Starts the project while assuming you've setup a database using the Docker Compose setup. Spins up a Postgres instance and pgAdmin alongside the backend and frontend apps\n```\n\nBy default, the frontend app will run on `localhost:4000` and the backend app will run on `localhost:8000`. If you're running the containerized Postgres, it will run on `localhost:5432` and pgAdmin will run on `localhost:5050`.\n\nIt's important to note that **for the best development experience, you should run the backend and frontend apps separately**. This way, you can take advantage of the hot-reload feature from Webpack and Django's development server.\n\nAlthough you can replicate the aforementioned behavior on a production environment (run the backend and frontend apps on differen servers), **this project is built to run both apps on the same server in production, with the frontend app being served by Django's template engine and view functions**. You can learn more about how everything is tied up together below 👇\n\n## Application architecture\n\nThis application's architect is quite simple and leverages the best of both Django and React. On a nutshell, React and Django integrate through Django's view functions and Django Rest Framework's API endpoints. There is no secret sauce here, just a simple and straightforward integration.\n\n```mermaid \nflowchart TD\n    ns(\"Frontend\") --\u003e ny(\"React\") \u0026 n9(\"Env. variables\")\n    nl(\"Backend\") --\u003e nt(\"Django\") \u0026 ni(\"Django Rest Framework\")\n    nt --\u003e n5(\"Views\") \u0026 nb(\"Templates\") \u0026 na(\"Models\")\n    n5 --\u003e nb\n    ny --\u003e n0(\"API Client\") \u0026 n4(\"Root Container\")\n    na --\u003e nn(\"API Key\") \u0026 nd(\"Publications\")\n    n4 -- Mounts on same file from\\nDjango templates --\u003e nb\n    n9 -.-\u003e nn \u0026 n0\n    ni -- Provides a REST\\nendpoint to manipulate\\ndata from models --\u003e ng(\"REST API\")\n    ng --\u003e nd\n    n0 -- Consumes API Key\\nto authenticate\\nwith backend --\u003e ng\n```\n\n### Features\n\nBelow you will find the stack used for each part of the application and the features that are already implemented.\n\n| Stack      | Libraries and services                                            | Features                         |\n| ---------- | ----------------------------------------------------------------- | -------------------------------- |\n| Frontend   | React 18, React Router 6, Typescript 5, Webpack 5, Tailwind CSS 3 | Publication listing and search   |\n| Backend    | Django 5, Django Rest Framework                                   | Publication CRUD, API Key CRUD   |\n| Database   | Postgres                                                          | -                                |\n| CDN        | Cloudinary                                                        | -                                |\n| CI/CD      | GitHub Actions                                                    | Multiple deploy workflow options |\n| Monitoring | Sentry                                                            | -                                |\n\n## Going to production: infrastructure \u0026 deployment\n\nAlthough this project provides some guidelines on how to deploy the app, it is not mandatory to follow them. You can deploy the app on any platform you want, as long as it supports Docker and Docker Compose, or even deploy the app on a bare-metal machine. **By the end of the day, you should use the provided GitHub Actions workflows as a reference to build your own deployment pipeline and meet your requirements**.\n\nNonetheless, this codebase has two deploy methods available via GitHub actions:\n\n### Virtualized Deploy Workflow\n\nThe `vm-deploy` branch will trigger this wokflow. You can use it to deploy the app to any Virtual Machine accessible via SSH (AWS EC2s, GCloud apps, Digital Ocean droplets, Hostgator VPSs, etc), and you would likely want to change the name of these branches to something more meaningful to your project.\n\nThis is what the workflow does:\n\n```mermaid\nflowchart LR\n    nv(\"Make changes to\\nthe application\") -- Commit --\u003e n7(\"Build and test frontend\\nand backend\")\n    n7 --\u003e nf{\"Success?\"}\n    nf -- Yes --\u003e n2(\"Build and test docker\\nimage\")\n    nf -- No --\u003e n4(\"Cancel pipeline\")\n    n2 --\u003e n5{\"Success?\"}\n    n5 -- No --\u003e n4\n    n5 -- Yes --\u003e nx(\"Publish docker image\\nto GitHub packages\")\n    nx --\u003e nj{\"Success?\"}\n    nj -- No --\u003e n4\n    nj -- Yes --\u003e nd(\"Deploy\")\n    nd --\u003e nc(\"Login into VM and copy\\ndocker compose file\\nfrom repo\")\n    nc --\u003e n6{\"Success?\"}\n    n6 -- Yes --\u003e no(\"Pull previously pushed Docker image\\nand execute most recent\\n docker compose file\")\n    n6 -- No --\u003e n4\n    no --\u003e na{\"Success?\"}\n    na -- No --\u003e ng(\"Better check your\\nsystem's health\")\n    na -- Yes --\u003e nk(\"Updates are live\")\n```\n\n### Bare-metal Deploy Workflow\n\nThe `bare-metal-deploy` branches will trigger this workflow. You can use it to deploy the app straight on the host machine, without any virtualization. This is not recommended, but ou never know when you will need to deploy an app on a bare-metal machine 🤷‍♀️. This pipeline assumes that you've got Node.js, Python, [Gunicorn](https://gunicorn.org/) and [Supervisord](http://supervisord.org/) installed on the host machine.\n\nThis is what the workflow does:\n\n```mermaid\nflowchart LR\n    nv(\"Make changes to\\nthe application\") -- Commit --\u003e n7(\"Build and test frontend\\nand backend\")\n    n7 --\u003e nf{\"Success?\"}\n    nf -- Yes --\u003e n2(\"Logs into host machine\\nand copy all relevant files\\nfrom repo to it\")\n    nf -- No --\u003e n4(\"Cancel pipeline\")\n    n2 --\u003e n5{\"Success?\"}\n    n5 -- No --\u003e n4\n    n5 -- Yes --\u003e nx(\"Builds the frontend\\nand the backend\")\n    nx --\u003e nj{\"Success?\"}\n    nj -- No --\u003e n4\n    nj -- Yes --\u003e nd(\"Deploy\")\n    nd --\u003e nc(\"Starts gunicorn server under\\nsupervisor to ensure the\\nsystem is never down\")\n    na{\"Success?\"} -- No --\u003e ng(\"Better manually log in\\ninto host and fix it\")\n    na -- Yes --\u003e nk(\"Updates are live\")\n    nc --\u003e na\n```\n\n### Configuration\n\nYou must be familiar with the expected environment variables to run the project. Here is a list of the environment variables you must set alongside the ones you already know ([`.env.example`](./.env.example) from root, [`.env.example`](./frontend/.env.example) from frontend) production environments and must be set as secrets on your GitHub repository and made available to GitHub Actions.\n\n| Environment variable | Description                                                                           |\n| -------------------- | ------------------------------------------------------------------------------------- |\n| IMAGE_NAME           | Docker image name                                                                     |\n| MODE                 | `production`. This is hardcoded on the [Dockerfile](./Dockerfile)                     |\n| ALLOWED_HOSTS        | A set of hosts allowed to pass CORS policy. I.g: \"www.example.com\" \"example.com\"      |\n| DEPLOY_TOKEN         | A Github token with permission to pull this project's image from your Github registry |\n| HOST                 | The domain under which your site will be hosted (i.g.:example.com)                    |\n| SSH_PRIVATE_KEY      | The SSH key used to access the host machine                                           |\n| USERNAME             | The SSH username used to access the host machine                                      |  |\n\n### Architecture overview\n\nBuilding up on the [application architecture diagram](#application-architecture), here is a more detailed overview of how the application is structured on a production environment:\n\n```mermaid\nflowchart TD\n subgraph subgraph_byfiey99u[\"Gunicorn\"]\n        ny(\"React\")\n        n9(\"Env. variables\")\n        ns(\"Frontend\")\n        nt(\"Django\")\n        ni(\"Django Rest Framework\")\n        nl(\"Backend\")\n        n5(\"Views\")\n        nb(\"Templates\")\n        na(\"Models\")\n        n0(\"API Client\")\n        n4(\"Root Container\")\n        nn(\"API Key\")\n        nd(\"Publications\")\n        ng(\"REST API\")\n        react_assets(\"Static assets\\n(React included)\")\n  end\n subgraph subgraph_3hmsyzvqm[\"Docker Image/Host\"]\n        subgraph_byfiey99u\n        nginx(\"NGINX\")\n        pg(\"Postgres\")\n  end\n    ns --\u003e ny \u0026 n9\n    nl --\u003e nt \u0026 ni\n    nt --\u003e n5 \u0026 nb \u0026 na \u0026 subgraph_3hmsyzvqm\n    nt -- Stores media\\nfiles on --\u003e nk(\"CDN\\n(Cloudinary)\")\n    n5 --\u003e nb\n    ny --\u003e n0 \u0026 n4\n    na --\u003e nn \u0026 nd\n    n4 -- Mounts on same file from\\nDjango templates --\u003e nb\n    n9 -.-\u003e nn \u0026 n0\n    ni -- Provides a REST\\nendpoint to manipulate\\ndata from models --\u003e ng\n    ng --\u003e nd\n    n0 -- Consumes API Key\\nto authenticate\\nwith backend --\u003e ng\n    nt -- Serves --\u003e react_assets\n    nginx -- Serves --\u003e subgraph_byfiey99u\n    nt -- Stores\\ndata\\non --\u003e pg\n    style subgraph_byfiey99u stroke:#000000\n    style subgraph_3hmsyzvqm stroke:#000000\n```\n\n## Similar projects\n\nReact and Django are a great combination, and there are many projects out there that leverage the best of both worlds. Make sure to check them out if you're looking for a more opinionated boilerplate/different approach:\n\n- [django-react-boilerplate](https://github.com/vintasoftware/django-react-boilerplate)\n","funding_links":["https://patreon.com/marcelovicentegc","https://www.buymeacoffee.com/YkwcZVO"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcelovicentegc%2Fdjango-react-typescript","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarcelovicentegc%2Fdjango-react-typescript","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcelovicentegc%2Fdjango-react-typescript/lists"}