pyxle-framework 0.4.0

Python-first full-stack framework with an intelligent CLI.

Python and React. One file.
A full-stack framework where your server logic (Python) and your UI (React) live in one
.pyxl file — no second service, no glue. Built for the age of AI coding agents.

   

---

A .pyxl file holds your Python server logic and your React UI side by side. Pyxle splits them at compile time: @server loaders and @action mutations run on the backend, the JSX renders with real server-side rendering, and React hydrates on the client. No FastAPI-plus-Next.js, no two repos, no CORS, no API glue.

# pages/users.pyxl
from db import fetch_users, delete_user

@server
async def load(request):
    users = await fetch_users()        # runs on the server
    return {"users": users}            # ...the returned dict becomes the component's `data`

@action
async def remove(request):
    body = await request.json()
    await delete_user(body["id"])      # a real server-side mutation
    return {"users": await fetch_users()}   # hand back the fresh list


import React, { useState } from 'react';
import { useAction } from 'pyxle/client';

export default function Users({ data }) {
    const [users, setUsers] = useState(data.users);
    const remove = useAction('remove');               // calls the @action above — no fetch, no route

    async function onRemove(id) {
        const res = await remove({ id });             // framework wraps the return as { ok, ...data }
        if (res.ok) setUsers(res.users);              // the server stays the source of truth
    }

    return (
        <ul>
            {users.map((u) => (
                <li key={u.id}>
                    {u.name}
                    <button onClick={() => onRemove(u.id)}>Delete</button>
                </li>
            ))}
        </ul>
    );
}

Data loading, a server mutation, and a React UI — one file, two languages, zero glue.

▶ Try it in your browser →   Edit a real .pyxl and run it. No install.

Quickstart

pip install pyxle-framework
pyxle init my-app && cd my-app
pyxle install
pyxle dev

Open http://localhost:8000, edit pages/index.pyxl, and watch it hot-reload.

Why Pyxle

	Pyxle	Next.js + FastAPI	Reflex / FastHTML
Server + UI in one file	✅	❌	✅
You write real React / JSX	✅	✅	❌ (UI is Python)
Services to run	one	two	one
API glue you write	none — @action is the call	yes	none
SSR + file-based routing	✅	✅	✅
Languages	Python + JS	Python + TS	Python

Pyxle's spot is the one nobody else occupies: real React, like Next.js — but one file and one service, like a single-language Python framework. The honest trade is that you do write some JavaScript; in return you get the whole React ecosystem with none of the two-repo, two-runtime tax.

Full framework comparison →   Honest about when to reach for Reflex, Django, NiceGUI, Streamlit, or Next.js + FastAPI instead.

Fast, and benchmarked in the open. Pyxle is faster than Next.js at dynamic SSR — 1.7–2.1× on heavy pages — and matches FastAPI on raw API throughput, giving you both in one framework. → See the benchmarks — full data, honest caveats, reproducible harness.

Built for AI coding agents. Shipping a feature on a Next.js + FastAPI stack means holding two languages, two type systems, an API contract, and a CORS config in your head — and your agent's context window — at the same time. In Pyxle it's one file with one predictable shape, so an agent (Claude Code, Cursor, Copilot) ships a working full-stack feature in a fraction of the tokens, files, and round-trips. Strong types, structured errors, no magic.

Every pyxle init scaffolds an AGENTS.md guide, so coding agents pick up Pyxle's conventions from the very first prompt — no priming, no setup. → Pyxle for AI coding agents

Features

• .pyxl files — Python + React in one file, split at compile time
• @server / @action — typed data loading and server mutations, called from the client with zero API boilerplate
• SSR — server-side rendering (esbuild + React 18) with hydration
• File-based routing — pages/ maps to URLs; [param].pyxl for dynamic segments
• Layouts & slots — nested layouts and slot composition
• Vite HMR — instant hot reload in development
• Tailwind — preconfigured out of the box
• Production build — pyxle build + pyxle serve; deploy anywhere Python runs
• Editor tooling — LSP, linter, and a VS Code extension

Status

Pyxle is early (0.4.x) but real. The framework, SSR, routing, CLI, and editor tooling all work today — pyxle.dev itself is built with Pyxle. APIs may still shift before 1.0, and a first-class plugin system (auth, database) is in progress. Feedback and contributions are very welcome.

Documentation

Full docs at pyxle.dev/docs:

Installation · Quick Start · .pyxl Files · Routing · Data Loading · Server Actions · Layouts · Deployment · CLI · Configuration

CLI

pyxle init <name>     Scaffold a new project
pyxle install         Install Python + Node dependencies
pyxle dev             Development server with hot reload
pyxle build           Production build
pyxle serve           Serve the production build

Requirements

Python 3.10+ and Node.js 18+.

Contributing

git clone https://github.com/pyxle-dev/pyxle.git
cd pyxle
pip install -e ".[dev]"
pytest

Issues and pull requests are welcome.

Links

pyxle.dev · Playground · Docs · Benchmarks · PyPI · Issues

License

MIT