🚀 Django TailwindCSS Template Project

---

---

✨ Features

• ✅ Django 5.2.8 - Latest stable version
• 🎨 Tailwind CSS 4.1 - Modern utility-first CSS framework
• 🔐 Custom User Model - Email-based authentication ready
• 🔒 Environment Variables - Secure configuration management
• 📁 Static & Media Files - Pre-configured file handling
• 💾 SQLite Database - Easy switch to PostgreSQL/MySQL
• 🎯 Clean Structure - Well-organized apps and templates

---

📋 Table of Contents

• Features
• Prerequisites
• Quick Start
• Project Structure
• Configuration
• Tailwind CSS
• Common Commands
• Development Workflow

---

🎯 Quick Start

1️⃣ Clone the Repository

git clone https://github.com/PyBoilerplate/django-tailwindcss-template.git
cd django-tailwindcss-template

2️⃣ Create Virtual Environment

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# On macOS/Linux:
source .venv/bin/activate

# On Windows:
.venv\Scripts\activate

3️⃣ Install Dependencies

pip install -r requirements.txt

4️⃣ Environment Configuration

Create a .env file in the project root by copying the example:

cp .env.example .env

Edit .env and configure your settings:

SECRET_KEY=your-secret-key-here
DEBUG=True
ALLOWED_HOSTS=127.0.0.1,localhost

💡 Tip: Generate a strong SECRET_KEY for production:

python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"

5️⃣ Database Setup

Run migrations to set up your database:

python manage.py migrate

6️⃣ Create Superuser (Admin)

python manage.py createsuperuser

7️⃣ Run Development Server

python manage.py runserver

🎉 Success! Visit http://127.0.0.1:8000 to see your application!

🔐 Admin panel: http://127.0.0.1:8000/admin

---

📁 Project Structure

project_pyboilerplate_free_django_boilerplate/
├── 📂 app_main/                 # Main application
│   ├── migrations/
│   ├── admin.py
│   ├── models.py
│   ├── views.py
│   └── urls.py
│
├── 📂 user/                     # Custom user authentication app
│   ├── migrations/
│   ├── models.py               # CustomUser model
│   ├── forms.py                # User forms
│   └── admin.py
│
├── 📂 project_pyboilerplate_free_django_boilerplate/
│   ├── settings.py             # Main settings file
│   ├── urls.py                 # Root URL configuration
│   └── wsgi.py
│
├── 📂 templates/                # HTML templates
├── 📂 static/                   # Static files (CSS, JS, images)
├── 📂 media/                    # User-uploaded files
├── 📄 .env                      # Environment variables (not in git)
├── 📄 .env.example              # Environment template
├── 📄 requirements.txt          # Python dependencies
└── 📄 manage.py                 # Django management script

---

⚙️ Configuration Sections

🔐 Environment Variables (.env)

The project uses django-environ to manage configuration via environment variables:

Variable	Description	Example
SECRET_KEY	Django secret key for cryptographic signing	your-secret-key-here
DEBUG	Debug mode (True for dev, False for prod)	True
ALLOWED_HOSTS	Comma-separated list of allowed hosts	127.0.0.1,localhost

📁 Static & Media Files

Static Files Configuration

Developer-provided files (CSS, JavaScript, images):

• STATIC_URL: /static/ - URL prefix for static files
• STATICFILES_DIRS: static/ - Development static files
• STATIC_ROOT: staticfiles/ - Collected static files for production

Media Files Configuration

User-uploaded files:

• MEDIA_URL: /media/ - URL prefix for media files
• MEDIA_ROOT: media/ - Directory for uploaded files

💾 Database

Default configuration uses SQLite for development:

• Database file: db.sqlite3
• Easy to switch to PostgreSQL/MySQL by updating DATABASES in settings.py

🔑 Authentication

Custom user model configured in user/models.py:

• ✅ Uses email instead of username for authentication
• ✅ Customizable user fields
• ✅ Configured via AUTH_USER_MODEL = 'user.CustomUser'

📦 Installed Apps

App	Purpose
app_main	Main application for core functionality
user	Custom user authentication and profile management

🎨 Tailwind CSS

This project uses Tailwind CSS 4.1 for styling. Tailwind is configured using the standalone CLI for easy setup without Node.js dependencies.

Running Tailwind CSS in Development

To compile and watch Tailwind CSS during development:

# Run Tailwind in watch mode
npx @tailwindcss/cli -i ./static/tailwind/input.css -o ./static/tailwind/output.css --watch --minify

Using Tailwind CSS in Templates

In your HTML templates, include the compiled CSS:

{% load static %}
<!DOCTYPE html>
<html>
<head>
    <link href="{% static 'src/output.css' %}" rel="stylesheet">
</head>
<body>
    <div class="bg-blue-500 text-white p-4">
        Hello, Tailwind!
    </div>
</body>
</html>

---

🛠️ Common Commands

Create a New App

python manage.py startapp app_name

Make Migrations

python manage.py makemigrations
python manage.py migrate

Collect Static Files (for production)

python manage.py collectstatic

Run Tests

python manage.py test

Create Superuser

python manage.py createsuperuser

---

📝 License

This project is open source and available for use.

---

Happy Coding! 🎨✨