wilco - Server-Defined React Components

Warning

Experimental Software

wilco is experimental software in active development. Breaking changes may occur until version 1.0. Use with care in production environments.

wilco is a framework that enables Python backends to serve isolated React/TypeScript components. Components are defined in the Python codebase alongside their TypeScript implementations, then dynamically bundled with esbuild and loaded by the frontend at runtime.

Tutorials

How-To Guides

Specifications

Reference

Explanation

Features

  • Co-located components — Keep UI components next to the Python code that powers them

  • No frontend build pipeline — Components bundled on-the-fly with esbuild when requested

  • Production-ready — Pre-compile bundles with wilco build for static file serving

  • Full source map support — Debug TypeScript directly in browser devtools

  • Component composition — Components can dynamically load other components via useComponent

  • Framework agnostic — Works with FastAPI, Django, Flask, Starlette, or any ASGI/WSGI-compatible framework

  • CLI tooling — wilco serve for development, wilco build for production

Quick example

Create a component directory with Python and TypeScript files:

my_components/
└── greeting/
    ├── __init__.py
    ├── index.tsx
    └── schema.json

Write your React component:

// index.tsx
interface GreetingProps {
  name: string;
  formal?: boolean;
}

export default function Greeting({ name, formal = false }: GreetingProps) {
  const message = formal ? `Good day, ${name}.` : `Hey ${name}!`;
  return <p>{message}</p>;
}

Mount the API in your Python application:

# FastAPI example
from pathlib import Path
from fastapi import FastAPI
from wilco import ComponentRegistry
from wilco.bridges.fastapi import create_router

app = FastAPI()
registry = ComponentRegistry(Path("./my_components"))
app.include_router(create_router(registry), prefix="/api")

Load components in the frontend:

import { useComponent } from '@wilcojs/react';

function App() {
  const Greeting = useComponent('greeting');
  return <Greeting name="World" />;
}

Documentation

Tutorials

Learning-oriented lessons to get started with wilco

How-To Guides

Goal-oriented guides for specific tasks (FastAPI, Django, Flask, Starlette)

Reference

Technical reference for APIs and specifications

Explanation

Architecture overview, request lifecycle, bundling internals, live preview

API endpoints

All framework integrations expose these endpoints:

Endpoint

Description

GET /api/bundles

List available components

GET /api/bundles/{name}.js

Get bundled JavaScript for a component

GET /api/bundles/{name}/metadata

Get component metadata (schema, props)

Examples

Complete example applications are available on GitHub:

Framework

Description

Django Unfold

Jinja2 templates, Django Unfold admin with live preview, component discovery

Django Vanilla

Jinja2 templates, standard Django admin with live preview

Flask

Jinja2 templates, Flask-Admin with live preview, SQLAlchemy models

FastAPI

React SPA frontend with SQLAdmin, live preview, REST API, and component bundles

Starlette

Jinja2 templates, Starlette-Admin with live preview, SQLAlchemy models

ASGI Minimal

Pure ASGI application for educational/low-dependency use

WSGI Minimal

Pure WSGI application for educational/low-dependency use

See the How-To Guides guides for detailed integration instructions.