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.

.. toctree::
   :maxdepth: 1
   :caption: Tutorials

   tutorials/index

.. toctree::
   :maxdepth: 1
   :caption: How-To Guides

   how-to/fastapi
   how-to/django
   how-to/flask
   how-to/starlette

.. toctree::
   :maxdepth: 1
   :caption: Specifications

   specs/index

.. toctree::
   :maxdepth: 1
   :caption: Reference

   reference/cli
   reference/components
   reference/javascript

.. toctree::
   :maxdepth: 1
   :caption: Explanation

   explanation/architecture
   explanation/bundling
   explanation/standalone-loader
   explanation/request-lifecycle
   explanation/live-preview

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:

.. code-block:: text

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

Write your React component:

.. code-block:: tsx

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

.. code-block:: python

   # 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:

.. code-block:: tsx

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

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

Documentation
-------------

.. list-table::
   :widths: 25 75
   :header-rows: 0

   * - :doc:`tutorials/index`
     - Learning-oriented lessons to get started with wilco
   * - :doc:`how-to/index`
     - Goal-oriented guides for specific tasks (FastAPI, Django, Flask, Starlette)
   * - :doc:`reference/index`
     - Technical reference for APIs and specifications
   * - :doc:`explanation/index`
     - Architecture overview, request lifecycle, bundling internals, live preview

API endpoints
-------------

All framework integrations expose these endpoints:

.. list-table::
   :widths: 40 60
   :header-rows: 1

   * - 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:

.. list-table::
   :widths: 20 80
   :header-rows: 1

   * - Framework
     - Description
   * - `Django Unfold <https://github.com/msqd/wilco/tree/main/examples/django-unfold>`_
     - Jinja2 templates, Django Unfold admin with live preview, component discovery
   * - `Django Vanilla <https://github.com/msqd/wilco/tree/main/examples/django-vanilla>`_
     - Jinja2 templates, standard Django admin with live preview
   * - `Flask <https://github.com/msqd/wilco/tree/main/examples/flask>`_
     - Jinja2 templates, Flask-Admin with live preview, SQLAlchemy models
   * - `FastAPI <https://github.com/msqd/wilco/tree/main/examples/fastapi>`_
     - React SPA frontend with SQLAdmin, live preview, REST API, and component bundles
   * - `Starlette <https://github.com/msqd/wilco/tree/main/examples/starlette>`_
     - Jinja2 templates, Starlette-Admin with live preview, SQLAlchemy models
   * - `ASGI Minimal <https://github.com/msqd/wilco/tree/main/examples/asgi-minimal>`_
     - Pure ASGI application for educational/low-dependency use
   * - `WSGI Minimal <https://github.com/msqd/wilco/tree/main/examples/wsgi-minimal>`_
     - Pure WSGI application for educational/low-dependency use

See the :doc:`how-to/index` guides for detailed integration instructions.

Quick links
-----------

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`