Django Inertia Starter

A powerful CLI tool to quickly scaffold Django + Inertia.js projects with React or Vue.js frontends.

🚀 Quick Start

Installation

pip install create-django-inertia

Create a New Project

# Basic project creation (interactive prompts)
create-django-inertia myproject

# Create with React and TypeScript
create-django-inertia myproject --react --typescript

# Create with Vue 3 and TypeScript  
create-django-inertia myproject --vue --typescript

# Create in current directory
create-django-inertia myproject . --react

Run Your Project

cd myproject

# Backend setup
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
python manage.py migrate

# Frontend setup  
npm install

# Run development servers
python manage.py runserver & npm run dev

Visit http://localhost:8000 to see your app!

📁 Project Structure

myproject/
├── manage.py
├── requirements.txt
├── package.json             # Frontend dependencies
├── vite.config.ts           # Vite configuration
├── tsconfig.json            # TypeScript config (if --typescript)
├── postcss.config.mjs       # Tailwind v4 via PostCSS
├── README.md                # Project-specific instructions
├── .env                     # Generated SECRET_KEY (gitignored)
├── .env.example             # Template for teammates
├── .gitignore
│
├── myproject/               # Django project settings
│   ├── settings.py          # Pre-configured with Inertia.js
│   ├── urls.py
│   ├── wsgi.py
│   └── asgi.py
│
├── home/                    # Sample Django app - serves the landing page
│   ├── views.py             # Inertia view, renders the 'home' component
│   ├── urls.py
│   ├── models.py
│   ├── admin.py
│   ├── tests.py             # Passing tests for the home page
│   └── migrations/
│
├── templates/
│   └── base.html            # Inertia.js layout with Vite integration
│
├── static/                  # Frontend source files
│   ├── components/          # Reusable components
│   ├── pages/               # Inertia.js pages
│   │   └── home/
│   │       └── page.tsx     # Home page component
│   ├── css/
│   │   └── app.css          # Tailwind CSS with OKLCH colors
│   ├── lib/                 # Utilities and helpers
│   ├── dist/                # Vite build output (gitignored)
│   └── main.tsx             # Frontend entry point
│
└── media/                   # User uploads

⚙️ Features

🏗️ Full-Stack Integration

• Django Backend: Robust Python web framework with ORM, admin, and security
• Inertia.js: Seamless SPA experience without separate API
• Modern Frontend: React 18 or Vue 3 with Vite 6.0 for fast development

🎨 Frontend Options

• React: Modern React with hooks and TypeScript support
• Vue 3: Composition API with <script setup> syntax
• TypeScript: Full TypeScript support for both frameworks
• Vite 6.0: Latest build tool with improved performance

🔧 Developer Experience

• Hot Module Replacement: Instant updates during development
• Pre-configured: Ready-to-use setup with modern defaults
• Modern Design: Beautiful landing page with OKLCH color system
• Tailwind CSS v4: Latest CSS framework with inline theming
• Geist Fonts: Modern typography from Vercel

📦 Production Ready

• Static Files: Optimized Django static file handling with Vite
• Modern Dependencies: Latest stable versions of all packages
• Build Process: Optimized production builds
• Deployment: Works with any Django hosting solution

🛠️ Command Options

create-django-inertia

create-django-inertia PROJECT_NAME [DIRECTORY] [OPTIONS]

Arguments:

• PROJECT_NAME: Name of your project (required)
• DIRECTORY: Directory to create project in (optional, defaults to project name or use . for current directory)

Options:

• --react: Use React frontend framework
• --vue: Use Vue 3 frontend framework
• --typescript: Use TypeScript
• --javascript: Use JavaScript (without either flag, you are prompted)
• --force: Clear and regenerate an existing directory. Version control (.git), node_modules, and virtualenvs are preserved
• --no-install: Omit the dependency steps from the printed next steps. The CLI never installs packages itself - it generates files and exits
• --version: Print the version
• --help: Show help message

Examples:

# Interactive setup (prompts for framework choice)
create-django-inertia myblog

# React with TypeScript
create-django-inertia myblog --react --typescript

# Vue 3 with TypeScript
create-django-inertia myblog --vue --typescript

# Create in current directory
create-django-inertia myblog . --react

# Force overwrite existing directory
create-django-inertia myblog --react --force

# Skip installation steps
create-django-inertia myblog --vue --no-install

🏃‍♂️ Development Workflow

1. Create and Setup Project

create-django-inertia myapp --react --typescript
cd myapp
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
npm install

2. Database Setup

python manage.py migrate
python manage.py createsuperuser  # Optional: create admin user

3. Development Servers

# Single command (runs both servers)
python manage.py runserver & npm run dev

# Or in separate terminals:
# Terminal 1: Django backend
python manage.py runserver

# Terminal 2: Vite frontend  
npm run dev

4. Create New Pages

1. Add a Django view in home/views.py:

def about(request):
    return inertia_render(request, 'about', {
        'message': 'About our company'
    })

2. Add the URL route in home/urls.py:

path('about/', views.about, name='about'),

3. Create the component at static/pages/about/page.tsx (React) or static/pages/about/page.vue (Vue).

The component name passed to inertia_render maps to static/pages/<name>/page.<ext>, and every value in the dict arrives as a prop.

🎯 What's Included

Backend (Django)

• ✅ Django 4.2+ with modern Python features
• ✅ Inertia.js middleware enabled (303 redirects, asset versioning, CSRF refresh)
• ✅ Sample home app with a passing test suite
• ✅ SECRET_KEY generated into a gitignored .env, loaded via python-dotenv
• ✅ WhiteNoise configured for production static files
• ✅ Home app with sample Inertia views
• ✅ Admin interface ready
• ✅ Static files configuration for Vite
• ✅ CSRF protection integrated
• ✅ Modern Django project structure

Frontend (React/Vue)

• ✅ React 18 or Vue 3 with modern patterns
• ✅ TypeScript support (optional)
• ✅ Vite 6.0 for lightning-fast development
• ✅ Inertia.js client-side routing
• ✅ Tailwind CSS v4 with OKLCH colors
• ✅ Modern landing page with components
• ✅ Hot module replacement
• ✅ Geist fonts integration
• ✅ Production build optimization

📚 Learn More

• Django Documentation
• Inertia.js Documentation
• React Documentation
• Vue 3 Documentation
• Vite Documentation
• TypeScript Documentation

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Django team for the amazing web framework
• Inertia.js team for bridging frontend and backend
• React and Vue teams for excellent frontend frameworks
• Vite team for the blazing fast build tool

Happy coding! 🚀