pyxle-framework 0.9.4

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, ...yourReturn }
        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

python3 -m venv venv && source venv/bin/activate   # PEP 668: needed on Debian/Ubuntu
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'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 renders dynamic SSR ~2× faster than Next.js per core — the same DOM in 2–3× fewer bytes — and runs on par with FastAPI on API throughput, pulling ahead once a request does real database work. → See the benchmarks — full data with framework versions, honest caveats, and a 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 19) 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 (Vite 7)
• Styling — plain CSS and CSS Modules out of the box; opt into Tailwind v4 or shadcn/ui at pyxle init
• Production build — pyxle build + pyxle serve; deploy anywhere Python runs
• AI accessibility — serve any page as clean Markdown (append .md, or Accept: text/markdown) plus an llms.txt index, so AI agents read your app as text — one flag, agent-friendly out of the box
• Editor tooling — LSP, linter, and a VS Code extension

Status

Pyxle is early (0.9.x) but real. The framework, SSR, routing, CLI, editor tooling, and the official plugins (auth, database, mail) all work today — pyxle.dev itself is built with Pyxle. APIs may still shift before 1.0. 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

Examples

Runnable apps in examples/:

• charts — a Recharts chart rendered from data a Python @server loader aggregated, in one .pyxl file. npm install recharts@^2.15, import it, done — server-rendered SVG and a live React tree after hydration.
• chat — realtime chat over a page WebSocket with useWebSocket().

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 20.19+.

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