# Vibetuner

> Vibetuner is a production-ready FastAPI project scaffolding tool that generates full-stack web applications with authentication, flexible database support (MongoDB or SQL), frontend, Docker deployment, and CLI tools pre-configured in seconds. Built by All Tuner Labs for rapid iteration and modern development.

Important notes:

- Vibetuner consists of three packages: a Python framework (`vibetuner`), a JavaScript package (`@alltuner/vibetuner`), and a Copier scaffolding template
- The framework separates immutable framework code (`vibetuner` package) from your application code (`src/app/`) for clean updates
- In all examples, `app` refers to your project's Python package (the directory under `src/`). The actual name depends on your project slug (e.g., `src/myproject/` for a project named "myproject")
- HTMX is used instead of React/Vue for simplicity - server-rendered HTML with sprinkles of interactivity
- All tools are chosen for speed: uv (Python), bun (JavaScript), Granian (ASGI server), Ruff (linting)
- The project is designed to work excellently with AI coding assistants like Claude, Cursor, and ChatGPT

## Quick Start

- [Quick Start Guide](https://vibetuner.alltuner.com/quick-start/): Get started with Vibetuner in 5 minutes
- [Installation](https://vibetuner.alltuner.com/installation/): Prerequisites and installation options
- [Your First Project](https://vibetuner.alltuner.com/quick-start/#create-your-first-project): Interactive project setup with `uvx vibetuner scaffold new`

## Core Documentation

- [Development Guide](https://vibetuner.alltuner.com/development-guide/): Daily development workflow, adding routes, models, templates, and background jobs
- [Architecture](https://vibetuner.alltuner.com/architecture/): System design, three-package architecture, request flow, and core components
- [Tech Stack](https://vibetuner.alltuner.com/tech-stack/): Detailed information about all technologies used and why they were chosen
- [Authentication](https://vibetuner.alltuner.com/authentication/): OAuth and magic link authentication setup and configuration
- [Background Tasks](https://vibetuner.alltuner.com/background-tasks/): Background task system powered by Streaq and Redis with retries, cron scheduling, and SSE integration
- [Runtime Configuration](https://vibetuner.alltuner.com/runtime-config/): Layered configuration system with MongoDB persistence, debug UI, and feature flags
- [HTMX v2 to v4 Migration](https://vibetuner.alltuner.com/htmx-migration/): Breaking changes and migration guide for upgrading from HTMX v2 to v4

## Features

- **HTMX Request Detection**: `request.state.htmx` available on every request
  (via `starlette-htmx` middleware). Properties: `.boosted`, `.target`, `.trigger`,
  `.trigger_name`, `.current_url`, `.prompt`. Use `require_htmx` dependency from
  `vibetuner.frontend.deps` to reject non-HTMX requests with 400
- **CRUD Factory**: `create_crud_routes()` generates list/create/read/update/delete
  endpoints for Beanie models with pagination, filtering, sorting, and search
- **SSE Helpers**: `@sse_endpoint()` and `broadcast()` for real-time streaming with
  HTMX. Import from `vibetuner.sse`. Redis pub/sub for multi-worker support
- **`@render` Decorator**: `@render("template.html.jinja")` eliminates
  `render_template()` boilerplate — route returns a dict, decorator handles rendering.
  Returns `Response` objects unchanged (escape hatch). Import from `vibetuner`
- **Streaming HTML**: `render_template_stream()` returns a `StreamingResponse` using
  Jinja2's `generate()`, improving TTFB for large pages. Same context merging as
  `render_template()`. Import from `vibetuner`
- **Block Rendering**: `render_template_block(template, block_name, request, ctx)`
  renders a single `{% block %}` for HTMX partials. `render_template_blocks()` renders
  multiple blocks for OOB swaps. No extra dependencies. Import from `vibetuner`
- **`@cache_control` Decorator**: `@cache_control(max_age=300, public=True)` sets
  `Cache-Control` headers declaratively. Supports `public`, `private`, `no_cache`,
  `no_store`, `max_age`, `s_maxage`, `must_revalidate`, `stale_while_revalidate`,
  `immutable`. Import from `vibetuner.decorators`
- **HTMX Response Helpers**: `hx_redirect()`, `hx_location()`, `hx_trigger()`,
  `hx_push_url()`, `hx_reswap()`, `hx_retarget()`, `hx_refresh()`,
  `hx_replace_url()`, `hx_trigger_after_settle()`, `hx_trigger_after_swap()`.
  Handles JSON serialization internally. Import from `vibetuner.htmx`
- **Template Context Providers**: `register_globals()` and `@register_context_provider`
  inject variables into every template render
- **Service DI**: `get_email_service()`, `get_blob_service()`, `get_runtime_config()`
  FastAPI dependency wrappers
- **Health Checks**: `/health`, `/health/ping`, `/health/ready`, `/health/id` endpoints
  with service connectivity checks
- **Robust Tasks**: `@robust_task()` decorator with exponential backoff retries and
  MongoDB dead letter collection
- **Streaq UI**: Task queue monitoring dashboard at `/debug/tasks`
- **Doctor CLI**: `vibetuner doctor` validates project setup, services, and config
- **Config Decorators**: `@config_value()` and `ConfigGroup` for type-safe runtime
  configuration
- **Testing Fixtures**: `vibetuner_client`, `mock_auth`, `mock_tasks`,
  `override_config`, `vibetuner_db` pytest fixtures
- **Error Messages**: Actionable error messages with env var examples, Docker
  commands, and documentation links

## Reference

- [CLI Reference](https://vibetuner.alltuner.com/cli-reference/):
  Commands for `vibetuner scaffold`, `vibetuner run`, `vibetuner db`, and `vibetuner doctor`
- [Scaffolding Reference](https://vibetuner.alltuner.com/scaffolding/):
  Template prompts, post-generation tasks, and updating existing projects
- [Deployment](https://vibetuner.alltuner.com/deployment/):
  Docker production builds, environment configuration, and deployment options

## Development

- [Contributing Guidelines](https://vibetuner.alltuner.com/contributing/): How to contribute, code style, and PR title format (uses conventional commits)
- [Development Workflow](https://vibetuner.alltuner.com/development/): Setting up the development environment for contributing to Vibetuner itself
- [Changelog](https://vibetuner.alltuner.com/changelog/): Version history and release notes

## Packages

- [Python Package](https://pypi.org/project/vibetuner/): Core framework published to PyPI
- [JavaScript Package](https://www.npmjs.com/package/@alltuner/vibetuner): Frontend dependencies published to npm
- [Repository](https://github.com/alltuner/vibetuner): Source code and issue tracking