vite-plugin-milpa

Vite integration for the milpa framework (FastAPI + Jinja), in the spirit of laravel-vite-plugin. Docs below in Spanish — milpa's home language.

El laravel-vite-plugin de milpa: conecta tu app Vite (React, Vue, Svelte, vanilla…) con el backend milpa, que sirve el shell Jinja e inyecta tus assets con su helper vite().

// vite.config.js — todo el pegamento en una llamada
import {defineConfig} from 'vite';
import react from '@vitejs/plugin-react';
import {milpa} from 'vite-plugin-milpa';

export default defineConfig({
    plugins: [
        react(),
        milpa({
            entry: 'src/main.jsx',
            pwa: {shell: '/spa'}, // opcional — omite para un SPA sin PWA
        }),
    ],
});

{# El template Jinja de TU app (milpa lo sirve) #}
{{ vite_react_refresh(app='demo-spa') }}
{{ vite('src/main.jsx', app='demo-spa') }}

Qué hace

1. base + build.manifest + entry — lo que el helper vite() de milpa necesita para emitir <link>/<script> hasheados en prod. La base se deriva de la carpeta: surcos/<app> → /vite/<app>/. Los chunks salen con NOMBRE legible derivado de la ruta del módulo (modules/tienda/pages/productos/[id].jsx → tienda-productos-id-<hash>.js) — sin esto, el file-routing produce puros index-<hash>.js indistinguibles.
2. Build a public/<app> del proyecto (estilo mix.js → public/ de Laravel): milpa monta public/ completo y un solo mount sirve a todas las apps.
3. Hot-file (modelo Laravel) — npm run dev escribe ./hot con la URL real del dev server y lo borra al apagarse; milpa decide dev/prod por su existencia. Un hot-file POR app: tu equipo en dev con HMR mientras los demás corren su build.
4. PWA opcional (Serwist injectManifest) — compila src/sw.js a un sw.js ESTÁTICO junto al build, precachea el shell del backend y prefija los precache entries con la base (los relativos 404ean bajo subpath). Solo en build: en dev el SW pelearía con HMR.
5. ASSET_URL (env, solo build) — se antepone a la base derivada, igual que en laravel-vite-plugin: deploy bajo sub-ruta de reverse proxy (ASSET_URL=/nombre-reverse) o CDN, sin tocar el vite.config. Es la MISMA env var que lee el backend milpa en runtime.

Opciones

| Opción | Default | Qué controla | |---|---|---| | entry | 'src/main.jsx' | Entry point (va a rollupOptions.input) | | assetsUrl | ${ASSET_URL}/vite/<carpeta> | URL pública donde milpa sirve esta app | | publicDir | '../../public' | public/ del proyecto, relativo a la app | | hotFile | 'hot' | Ruta del hot-file, relativa a la app | | pwa | false | false | {swSrc, swDest, shell, globDirectory} |

Nada es mandatorio: cualquier opción se overridea, o no uses el plugin y configura a mano — milpa solo necesita el manifest, la base y el hot-file.

vite-plugin-milpa/router — file-based routing (react-router 7)

El subpath runtime del paquete (mismo patrón que @serwist/vite/worker): rutas por convención de archivos para createBrowserRouter (modo library — el que usa un SPA servido por un backend), sin plugin extra, sin codegen, sin virtual modules. ~70 líneas auditables.

// src/router.jsx de TU app — los globs van en TU código (import.meta.glob es
// compile-time y resuelve relativo al archivo que lo contiene):
import {buildRoutes} from 'vite-plugin-milpa/router';

const routes = buildRoutes({
    pages:   import.meta.glob('./pages/**/*.jsx'),           // rutas core del shell
    modules: import.meta.glob('./modules/*/pages/**/*.jsx'), // rutas por módulo /<m>/...
});

| Convención | Resultado | |---|---| | pages/acerca.jsx | /acerca | | pages/index.jsx | / (índice de su carpeta) | | pages/productos/[id].jsx | /productos/:id (useParams()) | | modules/tienda/pages/index.jsx | /tienda (espejo de Modules/<X>/Http del backend) | | modules/tienda/pages/_layout.jsx | layout del módulo (envuelve sus rutas; opcional) | | _loquesea.jsx | ignorado (prefijo _ = no-ruta) |

Globs SIN eager ⇒ cada página es un chunk propio (code-splitting por ruta gratis). Acepta .jsx/.tsx/.js/.ts. Peers: react >=18 y react-router >=7 — opcionales: un surco vanilla usa el plugin sin React y sin warnings (solo los necesita quien importa /router).

El lado milpa

Requiere milpa-core con el helper Vite (Core/View/Vite.py): settings VITE_APPS_DIR (default surcos), VITE_PUBLIC_DIR (default public), VITE_ASSETS_URL (default /vite). Sin apps detectadas, la integración simplemente no se activa.

Licencia

MIT