Cookiecutter Python Web Application

A cookiecutter template for creating modern Python web applications with a JavaScript frontend.

Features

FastAPI backend with async SQLite database
Vite frontend with plain JavaScript (no framework)
Live reload development environment
Type checking with Pyright
Linting & formatting with Ruff
Testing with Pytest
Database migrations with Alembic
Project management with uv
Make targets for all development tasks

Prerequisites

Python 3.11+ (for running cookiecutter)
cookiecutter: pip install cookiecutter

Generated projects require:

Python 3.11, 3.12, or 3.13 (configurable)
Node.js 18+
uv: Python package manager

Quick Start

# Generate a new project
cookiecutter https://github.com/yourusername/cookiecutter-python-webapp

# Or from local path
cookiecutter /path/to/cookiecutter-python-webapp

You'll be prompted for:

project_name: Display name (e.g., "My Web App")
project_slug: Directory/package name (auto-generated from project_name)
project_description: Short description
author_name: Your name
author_email: Your email
python_version: Python version (3.13, 3.12, or 3.11)
backend_port: Backend server port (default: 8000)
frontend_port: Frontend dev server port (default: 5173)

What Gets Generated

my-web-app/
├── backend/                    # FastAPI application
│   ├── app/                   # Application code
│   ├── tests/                 # Backend tests
│   ├── alembic/               # Database migrations
│   └── pyproject.toml         # Python dependencies & config
├── frontend/                   # Vite application
│   ├── src/                   # JavaScript source
│   ├── index.html             # HTML template
│   └── package.json           # Node.js dependencies
├── scripts/
│   └── dev.py                 # Development server manager
├── Makefile                   # All development commands
├── .gitignore                 # Git ignore rules
├── .env.example               # Environment variables template
└── README.md                  # Project documentation

Post-Generation Setup

The template automatically runs a setup script that:

Initializes a git repository
Installs Python dependencies with uv
Installs Node.js dependencies with npm
Creates initial database migration
Applies migrations to create the database

After generation completes:

cd my-web-app
make dev

Visit:

Frontend: http://localhost:5173
Backend API: http://localhost:8000/docs

Development Workflow

Available Make Targets

make dev              # Start both servers with live reload
make test             # Run tests with coverage
make format           # Auto-format all code
make lint             # Run linter
make typecheck        # Run type checker
make check            # Run all quality checks
make migrate          # Apply database migrations
make build            # Build production frontend
make help             # Show all available targets

Example: Adding a New Feature

Start development servers:
```
make dev
```
Make changes to code
- Backend changes trigger automatic reload
- Frontend changes trigger HMR (Hot Module Replacement)
Run quality checks:
```
make check
```
Commit changes:
```
git add .
git commit -m "Add feature"
```

Tech Stack

Backend

FastAPI - Modern async web framework
SQLAlchemy - Async ORM
Alembic - Database migrations
Pydantic - Data validation
Uvicorn - ASGI server
Ruff - Linting & formatting
Pyright - Type checking
Pytest - Testing

Frontend

Vite - Fast build tool
Vanilla JavaScript - No framework
Modern CSS - Custom properties, flexbox, grid
Prettier - Code formatting

Development Tools

uv - Fast Python package manager
Make - Task automation
Git - Version control

Template Customization

Modifying the Template

Clone this repository
Make changes to files in {{cookiecutter.project_slug}}/
Test your changes:
```
cookiecutter .
cd test-project
make dev
```

Template Variables

Template variables are defined in cookiecutter.json:

{
  "project_name": "My Web App",
  "project_slug": "{{ cookiecutter.project_name.lower().replace(' ', '-') }}",
  "project_description": "A Python web application",
  "author_name": "Your Name",
  "author_email": "you@example.com",
  "python_version": ["3.13", "3.12", "3.11"],
  "backend_port": "8000",
  "frontend_port": "5173"
}

Use variables in files with Jinja2 syntax: {{ cookiecutter.variable_name }}

Post-Generation Hook

The hooks/post_gen_project.py script runs after project generation. It:

Makes scripts executable
Initializes git
Installs dependencies
Creates initial migration
Displays success message

Testing the Template

The template includes comprehensive end-to-end tests to ensure it works correctly.

Running Tests

# Install test dependencies
make install

# Run all E2E tests
make test-template

What Gets Tested

The E2E test suite validates:

Project generation: All files and directories are created correctly
Dependency installation: Both Python and Node.js dependencies install successfully
Quality checks: Format, lint, type check, and tests all pass
Server startup: Backend and frontend servers start and respond to HTTP requests
Database migrations: Migrations are created and applied correctly
Production build: Frontend builds successfully for production

Test Structure

tests/
└── test_e2e.py    # Comprehensive E2E test suite

Example Projects

See the examples/ directory for sample projects created with this template.

License

MIT License - see LICENSE file for details.

lkollar/template-python-webapp