README.md

Production-ready FastAPI scaffolding in seconds.
Authentication, database, frontend, Docker, and CLI tools, pre-configured.

Docs · Sponsor

---

Get Started

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 you get out of the package alone:

• FastAPI backend with async support.
• OAuth + magic-link authentication.
• Default templates and styles.
• Hot reload in development.
• Auto-discovery of 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.

---

What is Vibetuner?

Vibetuner is the scaffolding All Tuner Labs uses to spin up new web applications. It packages a FastAPI backend, an HTMX/Tailwind frontend, OAuth + magic-link auth, optional MongoDB or SQL persistence, and Docker for both dev and production into a single installable framework. The scaffolder generates the project; the framework runs it.

Core principles

• Simplicity — minimal boilerplate, clear conventions, obvious patterns.
• Speed — sub-second hot reload, one command to start.
• Modern stack — async-first, current stable versions.
• Assistant-friendly — works well with Claude, Cursor, and other coding agents.

Tech stack

Backend

• FastAPI — async web framework.
• Granian — Rust-based ASGI server.

Database (pick what fits)

• MongoDB + Beanie ODM — document database (optional).
• SQLModel / SQLAlchemy — PostgreSQL, MySQL, MariaDB, SQLite (optional).
• Redis + Streaq — caching and background jobs (optional).

Frontend

• HTMX — dynamic HTML without a separate JS build step.
• Tailwind CSS — utility-first CSS framework.
• DaisyUI — Tailwind component set.
• Jinja2 — template engine with i18n.

DevOps

• Docker — multi-stage builds for dev/prod.
• uv — Python package management.
• bun — JavaScript tooling.
• just — command runner.

Development

Local

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

Docker

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

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, 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

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

Updating projects

Update an existing project to the latest template:

cd my-app
vibetuner scaffold update

Documentation

• Development guide — daily workflow for generated projects.
• CLI reference — vibetuner scaffold and vibetuner run usage.
• 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 ships as three coordinated packages, version-locked and tested together:

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

License

MIT

Support the project

Vibetuner is an open source project built by David Poblador i Garcia through All Tuner Labs.

If this project was useful to you, consider supporting its development.

---

Built by David Poblador i Garcia with the support of All Tuner Labs.
Made with ❤️ in Poblenou, Barcelona.