wilco

Server-defined React components for Python backends.

Documentation: FastAPI Guide | Django Guide | Flask Guide | Starlette Guide

Features

• Co-locate components with backend logic — 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
• Framework agnostic — Works with FastAPI, Django, Flask, Starlette, or any ASGI/WSGI-compatible framework

Quick Start

pip install wilco[fastapi]  # or wilco[django], wilco[flask], wilco[starlette]

Create a component

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

// 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

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 in React

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

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

For component schemas, composition patterns, and framework-specific guides, see the documentation.

API Endpoints

Endpoint	Description
GET /api/bundles	List available components
GET /api/bundles/{name}.js	Get bundled JavaScript
GET /api/bundles/{name}/metadata	Get component metadata

Requirements

• Python 3.10+
• Node.js (for esbuild bundling)
• React 19 on the frontend (bundled in the standalone loader)

CLI

wilco serve                        # Start development server (default)
wilco build --output dist/wilco/   # Pre-compile bundles for production
wilco build --output dist/wilco/ --prefix store --no-minify --sourcemap

See the CLI reference for all options.

Development

This project follows strict TDD methodology.

make test    # Run all tests
make docs    # Build documentation
make help    # Show all available commands

License

Makersquad Source License 1.0 — see LICENSE.md for details.

Free for non-commercial use. Commercial use requires a license. Contact licensing@makersquad.fr for inquiries.