vegabase 0.2.0

Full-stack React + Python with zero configuration. Build modern React apps with FastAPI, Bun, Inertia.js, and Tailwind CSS.

Vegabase

Full-stack React + Python with zero configuration.

Build modern React applications powered by FastAPI, Bun, TanStack Router, and Tailwind CSS — all from a single pip install.

Motivation

When building React apps with Python, you typically have two choices:

• SPA-only: An empty HTML shell, React takes over in the browser. No SEO, slow initial loads, and you still need to build a REST/GraphQL API.
• Jinja + Islands: Server-render with templates, sprinkle React for interactivity. But you're constantly juggling two mental models.

Full-stack JS frameworks like Next and TanStack have SSR, hydration, and flexible rendering modes. Vegabase brings this experience to Python — use Python for backend logic, JavaScript for rendering html.

Features

• 🚀 Zero Config: Just install and run. Handles TS, TSX/JSX, CSS bundling with Tailwind support.
• 🐍 Python-First: FastAPI backend with Python's full ecosystem.
• ⚛️ Modern React: React 19 with server-side rendering out of the box.
• ⚡ Bun-Powered: Lightning-fast bundling and SSR performance.
• 🗄️ Type-Safe Database: Built-in database module with Pydantic validation.
• 🎨 Flexible Rendering: SSR, client-only, ISR caching, or static HTML per-page.

Requirements:

• Bun v1.0+ must be installed
• Python 3.11+

Quick Start

# Create a new project with uvx (no install needed)
uvx vegabase init my-app --example posts

cd my-app
uv sync && bun install

# Terminal 1: Frontend dev server
vegabase dev

# Terminal 2: Backend
APP_ENV=development python -m backend.main

Visit http://localhost:8000 🎉

CLI Commands

Command	Description
vegabase init	Create a new project
vegabase dev	Start dev server with hot reloading
vegabase build	Build optimized production bundles
vegabase ssr	Start the SSR server for production
vegabase db plan	Preview database schema changes
vegabase db apply	Apply schema changes to database

Init Options

vegabase init --name my-app              # Create empty project
vegabase init --name my-app --example posts  # Start from posts example
vegabase init --name my-app --db sqlite      # Include SQLite setup
vegabase init --name my-app --db postgres    # Include PostgreSQL setup

Rendering Modes

Control how each page is rendered:

from vegabase import ReactRenderer

react = ReactRenderer(app)

# Default: Server-side rendering
await react.render("Home", props, request, mode="ssr")

# Client-only: Skip SSR, render in browser
await react.render("Dashboard", props, request, mode="client")

# Cached (ISR): Cache for 60 seconds
await react.render("Posts/Index", props, request, mode="cached", revalidate=60)

# Static: Pure HTML, no JavaScript bundle
await react.render("About", props, request, mode="static")

Mode	SSR	Hydration	Use Case
ssr	✅	✅	Default, SEO-important pages
client	❌	✅	Dashboards, authenticated pages
cached	✅	✅	Blog posts, product pages (ISR)
static	✅	❌	Landing pages, pure content

Flash Messages

Built-in flash message support:

from starlette.middleware.sessions import SessionMiddleware

app.add_middleware(SessionMiddleware, secret_key="...")
react = ReactRenderer(app)

@app.post("/posts/create")
async def create_post(request: Request):
    # ... create post ...
    react.flash(request, "Post created!", type="success")
    return RedirectResponse(url="/posts", status_code=303)

Access in React:

export default function Index({ flash }) {
  return (
    <div>
      {flash && <Alert type={flash.type}>{flash.message}</Alert>}
    </div>
  );
}

Database Module

Type-safe database queries with Pydantic validation:

from sqlalchemy import MetaData, Table, Column, Integer, String, select
from pydantic import BaseModel
from vegabase.db import Database, query

# Define schema
metadata = MetaData()
users = Table('users', metadata,
    Column('id', Integer, primary_key=True),
    Column('name', String),
    Column('email', String),
)

# Define model
class User(BaseModel):
    id: int
    name: str
    email: str

# Query with full type safety
db = Database("sqlite:///app.db")

with db.connection() as conn:
    user = conn.one(query(User, select(users).where(users.c.id == 42)))
    print(user.name)  # IDE autocomplete works!
    
    all_users = conn.all(query(User, select(users)))  # Returns List[User]

Query Methods

Method	Returns	On Empty
one()	Single T	Raises NotFoundError
maybe_one()	T | None	Returns None
many()	List[T]	Raises NotFoundError
all()	List[T]	Returns []

Async Support

from vegabase.db import AsyncDatabase

db = AsyncDatabase("sqlite+aiosqlite:///app.db")

async with db.connection() as conn:
    users = await conn.all(query(User, select(users)))

Schema Management

No migration files — just compare and apply:

vegabase db plan   # Preview changes
vegabase db apply  # Apply changes

Project Structure

my-app/
├── backend/
│   ├── main.py           # FastAPI application
│   └── db/
│       └── schema.py     # Database tables
├── frontend/
│   ├── pages/            # React pages (auto-discovered)
│   ├── components/       # Reusable components
│   └── styles.css        # Tailwind entry point
├── static/dist/          # Generated assets (gitignored)
├── .vegabase/            # Generated entry files (gitignored)
├── package.json          # JS dependencies
└── pyproject.toml        # Python dependencies

Production

# Build optimized bundles
vegabase build

# Start the SSR server (background)
vegabase ssr &

# Start the FastAPI server
APP_ENV=production python -m backend.main

Examples

See the examples/ directory:

• basic-app — Minimal single-page example
• posts — CRUD app with flash messages and database
• ticketing — Full app with authentication, multi-page routing

License

MIT