Vibetuner

Production-ready FastAPI web application scaffolding in seconds

Vibetuner generates full-stack web applications with authentication, database, frontend, Docker deployment, and CLI tools pre-configured.

Built by All Tuner Labs for rapid iteration and modern development.

✨ What You Get

Option 1: Just add the package

uv add vibetuner
vibetuner run dev
# → Working app at http://localhost:8000

Option 2: Full project scaffolding

uvx vibetuner scaffold new my-project
cd my-project && just dev
# → Full application with Docker, CI/CD, and more

What vibetuner provides immediately (no scaffolding needed):

• ✅ FastAPI backend with async support
• ✅ OAuth + magic link authentication
• ✅ Default templates and styles
• ✅ Hot reload in development
• ✅ Auto-discovery of your routes, models, and tasks

What scaffolding adds:

• ✅ Flexible database: MongoDB (Beanie) or SQL (SQLModel/SQLAlchemy)
• ✅ HTMX reactive frontend
• ✅ Tailwind CSS + DaisyUI styling
• ✅ Docker dev/prod environments
• ✅ Background jobs with Redis (optional)
• ✅ i18n support
• ✅ CI/CD workflows

🚀 Quick Start

Installation

No installation needed - use uvx:

uvx vibetuner scaffold new my-app

Or install globally:

uv tool install vibetuner
vibetuner scaffold new my-app

Your First Project

# Create project (interactive)
uvx vibetuner scaffold new my-app

# Or skip questions with defaults
uvx vibetuner scaffold new my-app --defaults

# Start developing
cd my-app
just dev              # Docker mode with hot reload

Visit http://localhost:8000 - your app is running!

🎯 Core Principles

Born from real needs at All Tuner Labs when spawning new projects:

• Simplicity: Minimal boilerplate, clear conventions, obvious patterns
• Speed: Sub-second hot reload, one command to start, fast iteration
• Modern Stack: Latest stable versions, async-first, production-tested
• Assistant-Friendly: Works great with Claude, Cursor, and other coding AI

📦 Tech Stack

Backend

• FastAPI - Modern async web framework
• Granian - High-performance ASGI server

Database (choose your stack)

• MongoDB + Beanie ODM - Document database (optional)
• SQLModel / SQLAlchemy - SQL databases: PostgreSQL, MySQL, MariaDB, SQLite (optional)
• Redis + Streaq - Caching and background jobs (optional)

Frontend

• HTMX - Dynamic HTML without complex JavaScript
• Tailwind CSS - Utility-first CSS framework
• DaisyUI - Beautiful Tailwind components
• Jinja2 - Template engine with i18n

DevOps

• Docker - Multi-stage builds for dev/prod
• uv - Fast Python package management
• bun - Fast JavaScript tooling
• just - Command runner

Why These Choices?

FastAPI: Async-first, automatic API docs, Pydantic validation, type hints everywhere.

Flexible databases: Start with MongoDB for rapid prototyping, or use PostgreSQL/MySQL/SQLite with SQLModel for relational data. Both are optional - use what fits your project.

HTMX over React/Vue: Simplicity wins. Server-rendered HTML with sprinkles of interactivity. Less complexity, faster development, easier to reason about.

Tailwind + DaisyUI: Utility-first CSS is fast once you learn it. DaisyUI provides components without JavaScript bloat.

Docker-first: Consistent environments, easy deployment, no "works on my machine" problems.

uv + bun: Speed matters. Both are order-of-magnitude faster than pip/npm. Fast lockfiles, fast installs, fast everything.

💻 Development

Local Development

just local-all        # Runs server + assets with auto-port (recommended)

Docker Development

just dev              # All-in-one with hot reload
just worker-dev       # Background worker (if enabled)

Common Commands

just install-deps     # Install dependencies from lockfiles
just format           # Format code
just test-build-prod  # Test production build locally

🏗️ Project Structure

The vibetuner package is installed as a dependency. Your application code lives under src/ in a directory named after your project slug (shown as app below):

my-app/
├── src/app/                # Your application code (you create this)
│   ├── config.py           # App configuration (optional)
│   ├── cli/                # Your CLI commands (auto-discovered)
│   ├── frontend/           # Your web routes
│   │   └── routes/        # (auto-discovered)
│   ├── models/             # Your database models (auto-discovered)
│   ├── services/           # Your business logic
│   └── tasks/              # Your background jobs (auto-discovered)
├── templates/              # Jinja2 templates
│   ├── frontend/           # Web templates (override defaults)
│   ├── email/              # Email templates
│   └── markdown/           # Markdown templates
├── assets/statics/         # Static files (css, js, img, fonts)
├── locales/                # i18n translation files
└── Dockerfile              # Production deployment

vibetuner (installed package) handles auth, database, email, auto-discovery, and more. Your code goes in src/<your_package>/ (scaffolded projects). No boilerplate __init__.py files needed.

Flexible project structures: The framework auto-discovers code from your package directory. Scaffolded projects use src/<project_slug>/; non-scaffolded projects can use any structure.

🔐 Authentication

Built-in authentication with zero config:

• OAuth: Google, GitHub, and more via Authlib
• Magic Links: Passwordless email authentication
• Sessions: Secure cookie-based sessions
• Extensible: Add providers or custom auth easily

🌍 Internationalization

Full i18n support:

just extract-translations    # Extract strings
just compile-locales         # Compile translations

{% trans %}Welcome to {{ app_name }}{% endtrans %}

🐳 Deployment

Docker Production

just test-build-prod    # Test locally
just release            # Build and push

Configuration

Environment variables via .env:

# MongoDB (optional)
MONGODB_URL=mongodb://localhost:27017/mydb

# SQL database (optional) - PostgreSQL, MySQL, or SQLite
DATABASE_URL=postgresql+asyncpg://user:pass@localhost/mydb
# DATABASE_URL=sqlite+aiosqlite:///./data.db

# Redis for background jobs (optional)
REDIS_URL=redis://localhost:6379

SECRET_KEY=your-secret-key

📚 Documentation

• Development Guide – Daily workflow for generated projects
• CLI Reference – Usage for vibetuner scaffold and vibetuner run
• Scaffolding Reference – Copier prompts and update commands
• Changelog – Version history and release notes
• Contributing – Contribution guidelines
• Assistant Guidance – Tips for AI coding partners

📦 Packages

Vibetuner consists of three packages:

Package	Description	Published
vibetuner	Python framework	PyPI
@alltuner/vibetuner	Frontend dependencies	npm
Scaffolding template	Copier template	GitHub

All version-locked and tested together.

🔄 Updating Projects

Update existing projects to the latest template:

cd my-app
vibetuner scaffold update

🤝 Contributing

We welcome contributions that align with our core principles! See CONTRIBUTING.md.

Built for All Tuner Labs' internal needs, shared publicly because it might help you too.

📄 License

MIT License - Copyright (c) 2026 All Tuner Labs, S.L.

See LICENSE for details.

🔗 Links

• Repository: https://github.com/alltuner/vibetuner
• Changelog: https://github.com/alltuner/vibetuner/blob/main/CHANGELOG.md
• Issues: https://github.com/alltuner/vibetuner/issues
• PyPI: https://pypi.org/project/vibetuner/
• npm: https://www.npmjs.com/package/@alltuner/vibetuner

👨‍💻 Credits

Created and maintained by All Tuner Labs, S.L. and David Poblador i Garcia (@davidpoblador | davidpoblador.com)

---

Made with ❤️ for rapid prototyping and production deployments