Django + React Monorepo Boilerplate

A production-ready full-stack boilerplate featuring Django REST Framework with JWT authentication and a modern React frontend. This project is designed to be cloned and customized as a starting point for new applications.

Features

Backend (Django REST Framework)

• Authentication: Email-based login with Djoser + JWT tokens (djangorestframework-simplejwt)
• Database: PostgreSQL 15 with Docker containerization
• API Format: Camel case JSON responses via djangorestframework-camel-case
• Environment Management: Split settings for local/production environments
• Development Tools: Poetry for dependency management, Black + isort for formatting, Flake8 for linting
• Email: Console backend for development (configurable for production)

Frontend (React + Vite)

• Framework: React 19 with TypeScript
• Routing: React Router v7
• State Management: TanStack Query (React Query) for server state
• Forms: React Hook Form with Zod validation
• UI Components: Shadcn UI with Tailwind CSS
• API Client: Axios for HTTP requests
• Development: Vite for fast builds and HMR

Prerequisites

• Docker and Docker Compose
• Make (for convenience commands)
• Git

Quick Start

1. Clone this repository:

   git clone <repository-url>
   cd app-monorepo

2. Initial setup:

   make setup

   This will:

   • Copy .env.example to .env
   • Build Docker containers
   • Install frontend dependencies

3. Configure environment variables: Edit api/.env and set your SECRET_KEY and any other required variables.

4. Start the development environment:

   make up

   • Backend API: http://localhost:8000
   • Frontend: http://localhost:5173
   • API Documentation: http://localhost:8000/api/docs/

5. Run initial migrations:

   make api-migrate

Development Workflow

Common Commands

All development tasks use Make commands. Run make help to see all available commands.

General:

• make up - Start all services
• make down - Stop all services
• make build - Rebuild Docker containers
• make clean - Remove containers, volumes, and images

Backend (API):

• make api-shell - Open Django shell
• make api-migrate - Run database migrations
• make api-migrate-full - Create and run migrations
• make api-seed-dump - Dump current database to seed data fixture
• make api-seed-load - Flush database and load seed data
• make api-test - Run Django tests
• make api-format - Format code with Black and isort
• make api-lint - Run Flake8 linting

Frontend:

• make frontend-dev - Start frontend dev server (standalone)
• make frontend-build - Build for production
• make frontend-test - Run frontend tests
• make frontend-lint - Run ESLint
• make frontend-type-check - Run TypeScript type checking

Database Seeding

The project includes seed data fixtures for consistent development environments. Seed data is stored in api/fixtures/seed_data.json.

Creating/Updating Seed Data:

make api-seed-dump

This command exports your current database state to api/fixtures/seed_data.json. Use this when you want to save your current data as the baseline for the project.

Loading Seed Data:

make api-seed-load

Flushes all data from your current database and loads the seed data from api/fixtures/seed_data.json. This gives you a clean database with baseline data, useful for resetting to a known state.

For New Developers: When joining the project, after running make setup and make up, run:

make api-migrate
make api-seed-load

This ensures your local database has the same baseline data as other developers.

Project Structure

app-monorepo/
├── api/                    # Django backend
│   ├── settings/          # Environment-specific settings
│   │   ├── base.py       # Shared settings
│   │   ├── local.py      # Development settings
│   │   └── production.py # Production settings
│   ├── fixtures/         # Database seed data
│   │   └── seed_data.json # Baseline data for development
│   ├── users/            # Custom User app
│   └── manage.py
├── frontend/              # React frontend
│   ├── src/
│   │   ├── components/   # React components
│   │   │   └── ui/      # Shadcn UI components
│   │   ├── services/    # API client services
│   │   ├── hooks/       # Custom React hooks
│   │   └── utils/       # Utility functions
│   └── package.json
├── docker-compose.yml
├── Makefile
└── CLAUDE.md             # AI assistant guidance

Architecture Decisions

Backend

• Custom User Model: Uses email as USERNAME_FIELD instead of username
• Settings Structure: Split by environment (base, local, production) for better organization
• Djoser Configuration: Activation emails enabled by default for user registration
• API Versioning: Ready for versioned endpoints (configure as needed)

Frontend

• Component Organization: Scalable structure with separation of UI, forms, and feature components
• Form Management: All forms use react-hook-form as separate components
• API Layer: Centralized in /services with BaseService for standard CRUD operations
• Data Fetching: TanStack Query for caching, synchronization, and loading states
• Styling: Tailwind CSS with Shadcn UI components for consistent design

Authentication Flow

1. Registration: POST to /api/auth/users/ with email and password
2. Activation: Email link or manual activation (configurable)
3. Login: POST to /api/auth/jwt/create/ returns access and refresh tokens
4. Protected Routes: Include Authorization: Bearer <access_token> header
5. Token Refresh: POST to /api/auth/jwt/refresh/ with refresh token

Customization Guide

When forking this boilerplate for a new project:

1. Rename the project: Update names in docker-compose.yml, package.json, etc.
2. Update environment variables: Configure api/.env for your needs
3. Modify authentication: Adjust Djoser settings in api/settings/base.py
4. Create Django apps: Add your feature apps to the api/ directory
5. Build frontend features: Add components, hooks, and services following the established patterns
6. Configure deployment: Update api/settings/production.py for your hosting environment

Environment Variables

Copy api/.env.example to api/.env and configure:

SECRET_KEY=your-secret-key-here
DEBUG=True
ALLOWED_HOSTS=localhost,127.0.0.1
DATABASE_URL=postgresql://postgres:postgres@db:5432/postgres

Testing

Backend:

make api-test

Frontend:

make frontend-test

Code Style

Backend:

• Black for code formatting (line length 88)
• isort for import sorting
• Flake8 for linting

Run make api-format before committing.

Frontend:

• ESLint for linting
• TypeScript for type safety
• Prettier-compatible formatting

Run make frontend-lint before committing.

Production Deployment

1. Update api/settings/production.py with production settings
2. Set DEBUG=False in production environment
3. Configure proper ALLOWED_HOSTS
4. Use a production-grade WSGI server (Gunicorn recommended)
5. Set up proper database backups
6. Configure email backend for production
7. Serve frontend static files via CDN or reverse proxy

License

[Add your license here]

Contributing

This is a boilerplate project. Fork it and make it your own!