sveltekit-python-vercel 1.0.2 → 1.0.3-beta.pr16.2a0070d

package/README.md

@@ -22,6 +22,7 @@ Write Python endpoints in [SvelteKit](https://kit.svelte.dev/) and seamlessly de
 ## Current Features
 
 - Write `+server.py` files nearly the same way you would write `+server.js` files
+- Write server `load` functions in `+page.server.py` and `+layout.server.py`
 - Deploy automatically to Vercel Serverless (Python 3.12 runtime)
 
 ## Installing
@@ -153,6 +154,59 @@ Just push to your repository — no extra steps required.
 - `GET` endpoints receive query parameters directly as function arguments. Type annotations are used for coercion (e.g. `a: float` parses `?a=3` as `3.0`).
 - All other HTTP methods receive the request body as JSON. The recommended pattern is a Pydantic model as the single argument — FastAPI handles validation and parsing automatically.
 
+### Python load functions
+
+Server-side `load` functions work in `+page.server.py` and `+layout.server.py`. No extra Python package install is required — the runtime is bundled automatically like `+server.py`.
+
+```python
+async def load(event):
+    if event.params["id"] == "secret":
+        return ("redirect", 307, "/demo/public")
+
+    if event.params["id"] not in ("public", "1", "2"):
+        return ("error", 404, "Not found")
+
+    return {
+        "title": f"Item {event.params['id']}",
+        "parent_theme": event.parent.theme if event.parent else None,
+    }
+```
+
+Errors and redirects can also use injected helpers (no import needed):
+
+```python
+async def load(event):
+    if not event.cookies.get("session"):
+        redirect(307, "/login")
+    return {"ok": True}
+```
+
+Available on `event`: `params`, `url`, `route`, `parent` (layout data), `data` (from a sibling universal load), `cookies`.
+
+**Current limitations:** no `event.fetch`, `setHeaders`, `depends`, or page options (`prerender`, etc.) in `.py` files yet.
+
+## npm channels
+
+| Tag | When it updates | Install |
+|-----|-----------------|---------|
+| `latest` | GitHub Release created | `pnpm add -D sveltekit-python-vercel` |
+| `beta` | Every push to `main` | `pnpm add -D sveltekit-python-vercel@beta` |
+| `pr-<n>` | Open/update PR `#n` (same-repo only) | `pnpm add -D sveltekit-python-vercel@pr-15` |
+
+Beta versions look like `1.0.3-beta.abc1234` (main) or `1.0.3-beta.pr15.abc1234` (PRs).
+
+All publishes run through `.github/workflows/publish.yml` because npm trusted publishing only allows one workflow filename per package.
+
+### Developing the package locally
+
+If you work on this repo and a consumer app side by side (e.g. `test-skpv-deploy`):
+
+1. Build: `deno run -A dnt.ts $(npm view sveltekit-python-vercel version)` (or any version string)
+2. In the consumer: `pnpm add -D sveltekit-python-vercel@link:../sveltekit-python-vercel/npm`
+3. Rebuild and restart the consumer dev server after library changes
+
+Commit `^x.y.z` or `@beta` in the consumer for Vercel — `link:` only works on your machine.
+
 ## Fork of `sveltekit-modal`
 
 Check out the awesome [sveltekit-modal](https://github.com/semicognitive/sveltekit-modal) package by [@semicognitive](https://github.com/semicognitive), the original way to get your python code running in SvelteKit. Modal even has GPU support for running an entire ML stack within SvelteKit.
@@ -163,5 +217,5 @@ Check out the awesome [sveltekit-modal](https://github.com/semicognitive/sveltek
 - [X] Generate endpoints automatically during build (via Vercel Build Output API)
   - [X] Auto-bundle requirements.txt / pyproject.toml / Pipfile at build time
 - [ ] Add form actions
-- [ ] Add load functions
+- [X] Add load functions
 - [ ] Add helper functions to automatically call API endpoints in project

package/esm/src/vite/mod.js

@@ -0,0 +1,188 @@
+import { $ as run$, cd as cd$, which, path, chalk, } from "zx";
+const get_pyServerEndpointAsString = (app_url, serve = false) => `
+    const handle = (method) => (async ({ request, fetch, url }) => {
+        const headers = new Headers()
+        headers.append('content-type', request.headers.get('content-type'));
+        headers.append('accept', request.headers.get('accept'));
+
+        let fullURL;
+
+        if (${serve}) {
+          fullURL = new URL('/api' + url.pathname, new URL('${app_url}')) + url.search;
+        } else {
+          fullURL = new URL('/api' + url.pathname, url.origin) + url.search;
+        }
+
+        console.log(\`PY: Reached python endpoint of \${method} \${fullURL}\`)
+        let requestBody = await request.clone().text();
+        console.log(\`PY: Body: \${requestBody}\`);
+
+        if (method === 'GET') {
+          requestBody = null;
+        }
+
+        return fetch(fullURL, { headers, method, body: requestBody, signal: request.signal, duplex: 'half' });
+    });
+    
+    export const GET = handle('GET');
+    export const POST = handle('POST');
+    export const PATCH = handle('PATCH');
+    export const PUT = handle('PUT');
+    export const DELETE = handle('DELETE');
+`;
+function getLoadRouteTemplate(id) {
+    const marker = "/src/routes/";
+    const idx = id.indexOf(marker);
+    if (idx === -1) {
+        throw new Error(`Cannot derive load route from ${id}`);
+    }
+    let routePart = id.slice(idx + marker.length);
+    routePart = routePart.replace(/\/\+(?:page|layout)\.server\.py$/, "");
+    if (!routePart) {
+        return "/api/_load";
+    }
+    const segments = routePart
+        .split("/")
+        .filter((part) => !(part.startsWith("(") && part.endsWith(")")))
+        .map((part) => part.replace(/^\[(.+)\]$/, "{$1}"));
+    return `/api/_load/${segments.join("/")}`;
+}
+const get_pyLoadAsString = (loadRouteTemplate, app_url, serve = false) => `
+    import { error, redirect } from '@sveltejs/kit';
+
+    const LOAD_ROUTE_TEMPLATE = ${JSON.stringify(loadRouteTemplate)};
+
+    function buildLoadPath(params) {
+        let path = LOAD_ROUTE_TEMPLATE;
+        for (const [key, value] of Object.entries(params)) {
+            path = path.replaceAll(\`{\${key}}\`, encodeURIComponent(String(value)));
+        }
+        return path;
+    }
+
+    export async function load(event) {
+        const parent = event.parent ? await event.parent() : undefined;
+
+        const body = JSON.stringify({
+            params: event.params,
+            route: { id: event.route.id },
+            url: event.url.href,
+            parent,
+            data: event.data ?? undefined,
+            cookies: Object.fromEntries(event.cookies.getAll().map((c) => [c.name, c.value])),
+        });
+
+        const apiPath = buildLoadPath(event.params);
+        const fullURL = ${serve}
+            ? new URL(apiPath, new URL('${app_url}'))
+            : new URL(apiPath, event.url.origin);
+
+        const res = await event.fetch(fullURL, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body,
+        });
+
+        const result = await res.json();
+
+        if (result.type === 'redirect') redirect(result.status, result.location);
+        if (result.type === 'error') error(result.status, result.body);
+        return result.data;
+    }
+`;
+function isPyServerFile(id) {
+    return /\+server\.py$/.test(id);
+}
+function isPyLoadFile(id) {
+    return /\+(?:page|layout)\.server\.py$/.test(id);
+}
+export async function sveltekit_python_vercel(opts = {}) {
+    const child_processes = [];
+    async function kill_all_process() {
+        for (const ps of child_processes) {
+            await ps.kill();
+            await ps.exitCode;
+        }
+    }
+    let sveltekit_url;
+    const plugin_python_serve = {
+        name: "vite-plugin-sveltekit-python-serve",
+        apply: "serve",
+        async closeBundle() {
+            await kill_all_process();
+        },
+        async configureServer({ config }) {
+            const packagelocation = path.join(config.root, "node_modules", "sveltekit-python-vercel", "esm/src/vite");
+            run$.verbose = false;
+            run$.env.PYTHONDONTWRITEBYTECODE = "1";
+            cd$(packagelocation);
+            const python_path = opts.python_path ?? (await which("python3"));
+            const host = opts.host ?? "0.0.0.0";
+            const port = opts.port ?? 8000;
+            const local_process = run$ `${python_path} -m sveltekit_python_vercel.serve --host ${host} --port ${port} --root ${config.root}`;
+            child_processes.push(local_process);
+            sveltekit_url ??= new URL(`http://${host}:${port}`);
+            cd$(config.root);
+            local_process.nothrow();
+            local_process.stderr.on("data", (s) => {
+                console.log(s.toString().trimEnd());
+            });
+            local_process.stderr.on("error", (s) => {
+                console.error(chalk.red("Error: Python Serve Failed"));
+                console.error(s.toString().trimEnd());
+            });
+            local_process.stdout.on("error", (s) => {
+                console.error(chalk.red("Error: Python Serve Failed"));
+                console.error(s.toString().trimEnd());
+            });
+        },
+    };
+    const plugin_python_build = {
+        name: "vite-plugin-sveltekit_python-build",
+        apply: "build",
+        async configResolved(config) {
+            console.log("PY: ROOT PATH: " + config.root);
+        },
+    };
+    const transformPyFile = (id, serve, app_url) => {
+        if (!/\.py$/.test(id))
+            return undefined;
+        if (isPyServerFile(id)) {
+            return {
+                code: get_pyServerEndpointAsString(app_url, serve),
+                map: null,
+            };
+        }
+        if (isPyLoadFile(id)) {
+            const loadRouteTemplate = getLoadRouteTemplate(id);
+            return {
+                code: get_pyLoadAsString(loadRouteTemplate, app_url, serve),
+                map: null,
+            };
+        }
+        return undefined;
+    };
+    const plugin_py_server_endpoint_serve = {
+        name: "vite-plugin-sveltekit_python-server-endpoint",
+        apply: "serve",
+        transform(src, id) {
+            if (sveltekit_url === undefined) {
+                throw new Error(`${plugin_python_serve.name} failed to produce a sveltekit_url`);
+            }
+            return transformPyFile(id, true, sveltekit_url);
+        },
+    };
+    const plugin_py_server_endpoint_build = {
+        name: "vite-plugin-sveltekit_python-server-endpoint",
+        apply: "build",
+        transform(src, id) {
+            return transformPyFile(id, false, new URL("http://localhost"));
+        },
+    };
+    return [
+        plugin_python_serve,
+        plugin_python_build,
+        plugin_py_server_endpoint_serve,
+        plugin_py_server_endpoint_build,
+    ];
+}

package/esm/src/vite/sveltekit_python_vercel/__init__.py

@@ -0,0 +1,3 @@
+from .load_runtime import error, redirect
+
+__all__ = ["error", "redirect"]

package/esm/src/vite/sveltekit_python_vercel/bin.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env zx --install
+
+import {$} from "zx";
+
+const python_path = await $`which python3`;
+await $`${python_path} ./node_modules/sveltekit-python-vercel/esm/src/vite/sveltekit_python_vercel/build.py --root . --packagedir ./node_modules/sveltekit-python-vercel/esm/src/vite/sveltekit_python_vercel`;

package/esm/src/vite/sveltekit_python_vercel/build.py

@@ -0,0 +1,117 @@
+import argparse
+import glob
+import json
+import shutil
+import subprocess
+import sys
+from pathlib import Path, PurePosixPath
+
+sys.path.insert(0, str(Path(__file__).parent))
+from routes import api_route, load_route, rel_path_from_routes, route_parent
+
+parser = argparse.ArgumentParser(description="Run SvelteKit Python Deployment")
+parser.add_argument("--root", default=".", help="Root directory of the SvelteKit project")
+parser.add_argument("--packagedir", default=None, help="Directory of the sveltekit-python-vercel package")
+args = parser.parse_args()
+
+root_dir = Path(args.root).absolute()
+routes_root = root_dir / "src/routes"
+
+func_dir = root_dir / ".vercel" / "output" / "functions" / "api" / "index.func"
+func_dir.mkdir(parents=True, exist_ok=True)
+
+if args.packagedir:
+    package_dir = Path(args.packagedir).absolute()
+    shutil.copy(package_dir / "deploy.py", func_dir / "index.py")
+    for helper in ("load_runtime.py", "routes.py", "__init__.py"):
+        src = package_dir / helper
+        if src.exists():
+            shutil.copy(src, func_dir / helper)
+
+manifest = []
+
+
+def _bundle_route_module(module_path: str, *, kind: str) -> None:
+    abs_path = Path(module_path).absolute()
+    rel = rel_path_from_routes(abs_path, routes_root)
+    target_dir = func_dir / route_parent(rel)
+    target_dir.mkdir(parents=True, exist_ok=True)
+    shutil.copy(abs_path, target_dir / rel.name)
+
+    if not (target_dir / "__init__.py").exists():
+        (target_dir / "__init__.py").touch()
+
+    parent = route_parent(rel)
+    if kind == "load":
+        route = load_route(parent)
+    else:
+        route = api_route(parent)
+
+    entry = {"file": str(PurePosixPath(rel)), "route": route, "kind": kind}
+    manifest.append(entry)
+    print(f"PYTHON {'LOAD' if kind == 'load' else 'ENDPOINT'}: {module_path} → {route}")
+
+
+for module_path in glob.glob(str(routes_root / "**/+server.py"), recursive=True):
+    _bundle_route_module(module_path, kind="server")
+
+for pattern in ("**/+page.server.py", "**/+layout.server.py"):
+    for module_path in glob.glob(str(routes_root / pattern), recursive=True):
+        _bundle_route_module(module_path, kind="load")
+
+(func_dir / "_manifest.json").write_text(json.dumps(manifest, indent=2))
+
+dep_files = ["requirements.txt", "pyproject.toml", "uv.lock", "Pipfile", "Pipfile.lock"]
+found_dep = False
+for dep_file in dep_files:
+    src = root_dir / dep_file
+    if src.exists():
+        shutil.copy(src, func_dir / dep_file)
+        print(f"PYTHON ENDPOINT: Bundled {dep_file}")
+        found_dep = True
+
+if not found_dep:
+    (func_dir / "requirements.txt").write_text("fastapi\nuvicorn\n")
+    print("PYTHON ENDPOINT: No dependency file found, created minimal requirements.txt")
+
+dep_dir = func_dir / "_deps"
+dep_dir.mkdir(exist_ok=True)
+pip_cmd = [sys.executable, "-m", "pip", "install", "--target", str(dep_dir), "--quiet"]
+if (func_dir / "requirements.txt").exists():
+    pip_cmd += ["-r", str(func_dir / "requirements.txt")]
+    subprocess.run(pip_cmd, check=True)
+    print("PYTHON ENDPOINT: Installed deps from requirements.txt")
+elif (func_dir / "pyproject.toml").exists():
+    try:
+        import tomllib
+    except ImportError:
+        import tomli as tomllib  # type: ignore
+    with open(func_dir / "pyproject.toml", "rb") as _f:
+        _pyproject = tomllib.load(_f)
+    _deps_list = _pyproject.get("project", {}).get("dependencies", [])
+    if _deps_list:
+        subprocess.run(pip_cmd + _deps_list, check=True)
+        print(f"PYTHON ENDPOINT: Installed {len(_deps_list)} deps from pyproject.toml")
+
+vc_config = {"runtime": "python3.12", "handler": "index.handler"}
+(func_dir / ".vc-config.json").write_text(json.dumps(vc_config, indent=2))
+print("PYTHON ENDPOINT: Created .vc-config.json")
+
+config_path = root_dir / ".vercel" / "output" / "config.json"
+if config_path.exists():
+    config = json.loads(config_path.read_text())
+    routes = config.get("routes", [])
+    python_route = {"src": "^/api(/.*)?$", "dest": "api/index"}
+    fs_idx = next(
+        (i for i, r in enumerate(routes) if r.get("handle") == "filesystem"),
+        0,
+    )
+    routes.insert(fs_idx, python_route)
+    config["routes"] = routes
+    config_path.write_text(json.dumps(config, indent=2))
+    print("PYTHON ENDPOINT: Patched .vercel/output/config.json")
+else:
+    print(
+        "WARNING: .vercel/output/config.json not found. "
+        "Make sure to run `vite build` before this script."
+    )

package/esm/src/vite/sveltekit_python_vercel/deploy.py

@@ -0,0 +1,160 @@
+import asyncio
+import base64
+import importlib.util
+import json
+import sys
+from pathlib import Path
+from urllib.parse import urlsplit
+
+_base = Path(__file__).parent
+_deps = _base / "_deps"
+if _deps.exists() and str(_deps) not in sys.path:
+    sys.path.insert(0, str(_deps))
+if str(_base) not in sys.path:
+    sys.path.insert(0, str(_base))
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+from load_runtime import run_load
+from routes import route_registration_order
+
+app = FastAPI()
+
+
+def _load_module(file_path: Path):
+    spec = importlib.util.spec_from_file_location("_route_module", file_path)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+def _make_load_handler(mod):
+    async def handler(request: Request):
+        payload = await request.json()
+        return JSONResponse(await run_load(mod, payload))
+
+    return handler
+
+
+_manifest_path = _base / "_manifest.json"
+if _manifest_path.exists():
+    _manifest = json.loads(_manifest_path.read_text())
+    _load_entries = [e for e in _manifest if e.get("kind") == "load"]
+    _server_entries = [e for e in _manifest if e.get("kind", "server") != "load"]
+
+    for _entry in sorted(_load_entries, key=lambda e: route_registration_order(e["route"])):
+        _mod = _load_module(_base / _entry["file"])
+        _route = _entry["route"]
+        app.add_api_route(_route, _make_load_handler(_mod), methods=["POST"])
+        print(f"PYTHON LOAD: Registered POST {_route}")
+
+    for _entry in _server_entries:
+        _mod = _load_module(_base / _entry["file"])
+        _route = _entry["route"]
+
+        for _method in ["GET", "POST", "PATCH", "PUT", "DELETE"]:
+            _has_upper = hasattr(_mod, _method)
+            _has_lower = hasattr(_mod, _method.lower())
+
+            if _has_upper and _has_lower:
+                raise Exception(
+                    f"Duplicate method {_method} and {_method.lower()} in {_route}"
+                )
+            elif _has_upper:
+                app.add_api_route(_route, getattr(_mod, _method), methods=[_method])
+                print(f"PYTHON ENDPOINT: Registered {_method} {_route}")
+            elif _has_lower:
+                app.add_api_route(_route, getattr(_mod, _method.lower()), methods=[_method])
+                print(f"PYTHON ENDPOINT: Registered {_method} {_route}")
+
+
+@app.exception_handler(Exception)
+async def _exception_handler(request: Request, exc: Exception):
+    return JSONResponse(status_code=500, content={"error": str(exc)})
+
+
+async def _dispatch(scope: dict, body: bytes) -> tuple[int, dict, bytes]:
+    """Run FastAPI for one HTTP request and collect the response."""
+    queue: asyncio.Queue = asyncio.Queue()
+    queue.put_nowait({"type": "http.request", "body": body, "more_body": False})
+
+    status = 500
+    resp_headers: dict = {}
+    resp_body = b""
+
+    async def receive():
+        return await queue.get()
+
+    async def send(message):
+        nonlocal status, resp_body
+        if message["type"] == "http.response.start":
+            status = message["status"]
+            for k, v in message.get("headers", []):
+                if isinstance(k, bytes):
+                    k = k.decode()
+                if isinstance(v, bytes):
+                    v = v.decode()
+                k = k.lower()
+                if k in resp_headers:
+                    existing = resp_headers[k]
+                    resp_headers[k] = (existing if isinstance(existing, list) else [existing]) + [v]
+                else:
+                    resp_headers[k] = v
+        elif message["type"] == "http.response.body":
+            resp_body += message.get("body", b"")
+
+    await app(scope, receive, send)
+    return status, resp_headers, resp_body
+
+
+def handler(event, context):
+    payload = json.loads(event.get("body") or "{}")
+
+    parsed = urlsplit(payload.get("path", "/"))
+    path = parsed.path or "/"
+    query = (parsed.query or "").encode()
+
+    raw_headers: dict = payload.get("headers") or {}
+    headers_list = []
+    host = payload.get("host", "localhost")
+    scheme = "https"
+    for k, v in raw_headers.items():
+        k_lower = k.lower()
+        if k_lower == "host":
+            host = v
+        if k_lower == "x-forwarded-proto":
+            scheme = v
+        headers_list.append((k_lower.encode(), str(v).encode()))
+
+    scope = {
+        "type": "http",
+        "http_version": "1.1",
+        "method": payload.get("method", "GET").upper(),
+        "path": path,
+        "raw_path": path.encode(),
+        "query_string": query,
+        "root_path": "",
+        "headers": headers_list,
+        "server": (host, 443 if scheme == "https" else 80),
+        "client": (raw_headers.get("x-real-ip", "127.0.0.1"), 0),
+        "scheme": scheme,
+    }
+
+    body = payload.get("body") or b""
+    if payload.get("encoding") == "base64":
+        body = base64.b64decode(body)
+    elif isinstance(body, str):
+        body = body.encode()
+
+    status, resp_headers, resp_body = asyncio.run(_dispatch(scope, body))
+
+    result: dict = {"statusCode": status, "headers": resp_headers}
+    if resp_body:
+        try:
+            result["body"] = resp_body.decode("utf-8")
+        except UnicodeDecodeError:
+            result["body"] = base64.b64encode(resp_body).decode()
+            result["encoding"] = "base64"
+
+    return result

package/esm/src/vite/sveltekit_python_vercel/load_runtime.py

@@ -0,0 +1,91 @@
+import inspect
+import types
+from typing import Any, Optional
+
+
+class SKPVError(Exception):
+    def __init__(self, status: int, body: Any):
+        self.status = status
+        self.body = body
+        super().__init__(body)
+
+
+class SKPVRedirect(Exception):
+    def __init__(self, status: int, location: str):
+        self.status = status
+        self.location = location
+        super().__init__(location)
+
+
+def error(status: int, body: Any) -> None:
+    raise SKPVError(status, body)
+
+
+def redirect(status: int, location: str) -> None:
+    raise SKPVRedirect(status, location)
+
+
+def inject_load_helpers(mod) -> None:
+    if not hasattr(mod, "error"):
+        mod.error = error
+    if not hasattr(mod, "redirect"):
+        mod.redirect = redirect
+
+
+def _to_namespace(value: Any) -> Any:
+    if value is None:
+        return None
+    if isinstance(value, dict):
+        ns = types.SimpleNamespace()
+        for key, val in value.items():
+            setattr(ns, key, _to_namespace(val))
+        return ns
+    if isinstance(value, list):
+        return [_to_namespace(item) for item in value]
+    return value
+
+
+class _Cookies:
+    def __init__(self, data: Optional[dict]):
+        self._data = data or {}
+
+    def get(self, name: str, default: Optional[str] = None) -> Optional[str]:
+        return self._data.get(name, default)
+
+
+def wrap_event(payload: dict) -> types.SimpleNamespace:
+    event = types.SimpleNamespace()
+    event.params = payload.get("params") or {}
+    event.route = _to_namespace(payload.get("route") or {})
+    event.url = payload.get("url", "")
+    event.parent = _to_namespace(payload.get("parent"))
+    event.data = payload.get("data")
+    event.cookies = _Cookies(payload.get("cookies"))
+    return event
+
+
+def parse_load_result(result: Any) -> dict:
+    if (
+        isinstance(result, tuple)
+        and len(result) == 3
+        and result[0] in ("error", "redirect")
+    ):
+        kind, status, payload = result
+        if kind == "error":
+            return {"type": "error", "status": status, "body": payload}
+        return {"type": "redirect", "status": status, "location": payload}
+    return {"type": "data", "data": result}
+
+
+async def run_load(mod, payload: dict) -> dict:
+    inject_load_helpers(mod)
+    event = wrap_event(payload)
+    try:
+        result = mod.load(event)
+        if inspect.iscoroutine(result):
+            result = await result
+        return parse_load_result(result)
+    except SKPVRedirect as exc:
+        return {"type": "redirect", "status": exc.status, "location": exc.location}
+    except SKPVError as exc:
+        return {"type": "error", "status": exc.status, "body": exc.body}

package/esm/src/vite/sveltekit_python_vercel/routes.py

@@ -0,0 +1,39 @@
+from pathlib import Path, PurePosixPath
+
+
+def rel_path_from_routes(module_path: Path, routes_root: Path) -> PurePosixPath:
+    """Route file path relative to src/routes, with groups stripped and [param] → {param}."""
+    rel = module_path.absolute().relative_to(routes_root)
+    rel = Path(str(rel).replace("[", "{").replace("]", "}"))
+    parts = [
+        p
+        for p in PurePosixPath(rel).parts
+        if not (p.startswith("(") and p.endswith(")"))
+    ]
+    return PurePosixPath(*parts)
+
+
+def route_parent(rel: PurePosixPath) -> PurePosixPath:
+    return PurePosixPath(rel).parent
+
+
+def api_route(rel_parent: PurePosixPath, *, prefix: str = "/api") -> str:
+    if str(rel_parent) == ".":
+        return prefix
+    return f"{prefix}/{rel_parent}"
+
+
+def load_route(rel_parent: PurePosixPath) -> str:
+    return api_route(rel_parent, prefix="/api/_load")
+
+
+def resolve_route_path(template: str, params: dict) -> str:
+    path = template
+    for key, value in params.items():
+        path = path.replace(f"{{{key}}}", str(value))
+    return path
+
+
+def route_registration_order(route: str) -> tuple:
+    """Static routes before dynamic; longer paths before shorter."""
+    return ("{" in route, -len(route), route)

package/esm/src/vite/sveltekit_python_vercel/serve.py

@@ -0,0 +1,110 @@
+import argparse
+import glob
+import importlib.util
+import shutil
+import sys
+from pathlib import Path
+
+import uvicorn
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+sys.path.insert(0, str(Path(__file__).parent))
+from load_runtime import run_load
+from routes import (
+    api_route,
+    load_route,
+    rel_path_from_routes,
+    route_parent,
+    route_registration_order,
+)
+
+parser = argparse.ArgumentParser(description="Run Sveltekit Python Server")
+parser.add_argument("--host", default="0.0.0.0", help="Server hostname")
+parser.add_argument("--port", type=int, default=8000, help="Server port")
+parser.add_argument("--root", default=".", help="Directory where the API is located")
+args = parser.parse_args()
+
+app = FastAPI()
+
+root_dir = Path(args.root).absolute()
+api_dir = Path("./sveltekit_python_vercel").absolute()
+routes_root = root_dir / "src/routes"
+watch_modules = []
+
+
+def _copy_module(module_path: Path) -> Path:
+    api_route_path = api_dir.joinpath(module_path.relative_to(routes_root))
+    api_route_path.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy(module_path, api_route_path.parent / api_route_path.name)
+    return api_route_path.parent / api_route_path.name
+
+
+def _load_module(api_route_path: Path):
+    spec = importlib.util.spec_from_file_location(api_route_path.stem, api_route_path)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+def _make_load_handler(mod):
+    async def handler(request: Request):
+        payload = await request.json()
+        return JSONResponse(await run_load(mod, payload))
+
+    return handler
+
+
+for module_path in glob.glob(routes_root.joinpath("**/+server.py").as_posix(), recursive=True):
+    abs_module_path = Path(module_path).absolute()
+    watch_modules.append(abs_module_path.parent.as_posix())
+
+    api_route_path = _copy_module(abs_module_path)
+    mod = _load_module(api_route_path)
+
+    rel = rel_path_from_routes(abs_module_path, routes_root)
+    api_path = api_route(rel.parent)
+
+    for method in ["GET", "POST", "PATCH", "PUT", "DELETE"]:
+        if hasattr(mod, method) and hasattr(mod, method.lower()):
+            raise Exception(
+                f"Duplicate method {method} and {method.lower()} in {api_route_path}"
+            )
+        elif hasattr(mod, method):
+            app.add_api_route(api_path, getattr(mod, method), methods=[method])
+        elif hasattr(mod, method.lower()):
+            app.add_api_route(api_path, getattr(mod, method.lower()), methods=[method])
+
+load_entries = []
+for pattern in ("**/+page.server.py", "**/+layout.server.py"):
+    for module_path in glob.glob(routes_root.joinpath(pattern).as_posix(), recursive=True):
+        abs_module_path = Path(module_path).absolute()
+        watch_modules.append(abs_module_path.parent.as_posix())
+
+        api_route_path = _copy_module(abs_module_path)
+        mod = _load_module(api_route_path)
+
+        if not hasattr(mod, "load"):
+            raise Exception(f"Missing load function in {abs_module_path}")
+
+        rel = rel_path_from_routes(abs_module_path, routes_root)
+        load_path = load_route(route_parent(rel))
+        load_entries.append((load_path, mod, abs_module_path))
+
+for load_path, mod, abs_module_path in sorted(
+    load_entries, key=lambda entry: route_registration_order(entry[0])
+):
+    app.add_api_route(load_path, _make_load_handler(mod), methods=["POST"])
+    print(f"PYTHON LOAD: Registered POST {load_path} ← {abs_module_path}")
+
+
+if __name__ == "__main__":
+    uvicorn.run(
+        "sveltekit_python_vercel.serve:app",
+        host=args.host,
+        port=args.port,
+        log_level="info",
+        reload=True,
+        reload_includes=[*set(watch_modules)],
+        reload_excludes=[api_dir.as_posix()],
+    )

package/esm/src/vite/sveltekit_python_vercel/test_load_runtime.py

@@ -0,0 +1,119 @@
+import types
+import unittest
+
+from load_runtime import (
+    SKPVError,
+    inject_load_helpers,
+    parse_load_result,
+    redirect,
+    run_load,
+    wrap_event,
+)
+
+
+class ParseLoadResultTests(unittest.TestCase):
+    def test_data(self):
+        self.assertEqual(
+            parse_load_result({"ok": True}),
+            {"type": "data", "data": {"ok": True}},
+        )
+
+    def test_error_tuple(self):
+        self.assertEqual(
+            parse_load_result(("error", 404, "Not found")),
+            {"type": "error", "status": 404, "body": "Not found"},
+        )
+
+    def test_redirect_tuple(self):
+        self.assertEqual(
+            parse_load_result(("redirect", 307, "/login")),
+            {"type": "redirect", "status": 307, "location": "/login"},
+        )
+
+    def test_tuple_data_not_misread(self):
+        self.assertEqual(
+            parse_load_result(("items", 1, 2)),
+            {"type": "data", "data": ("items", 1, 2)},
+        )
+
+
+class RunLoadTests(unittest.IsolatedAsyncioTestCase):
+    async def test_injected_error(self):
+        mod = types.ModuleType("test")
+        exec(
+            compile(
+                "async def load(event):\n    error(403, 'denied')\n",
+                "<test>",
+                "exec",
+            ),
+            mod.__dict__,
+        )
+        result = await run_load(mod, {"params": {}})
+        self.assertEqual(result["type"], "error")
+        self.assertEqual(result["status"], 403)
+
+    async def test_injected_redirect(self):
+        mod = types.ModuleType("test")
+        exec(
+            compile(
+                "async def load(event):\n    redirect(307, '/home')\n",
+                "<test>",
+                "exec",
+            ),
+            mod.__dict__,
+        )
+        result = await run_load(mod, {"params": {}})
+        self.assertEqual(result["type"], "redirect")
+        self.assertEqual(result["location"], "/home")
+
+    async def test_return_tuple_error(self):
+        mod = types.ModuleType("test")
+
+        async def load(event):
+            return ("error", 404, "missing")
+
+        mod.load = load
+        result = await run_load(mod, {"params": {}})
+        self.assertEqual(result, {"type": "error", "status": 404, "body": "missing"})
+
+    async def test_wrap_event_parent_and_cookies(self):
+        mod = types.ModuleType("test")
+        captured = {}
+
+        async def load(event):
+            captured["theme"] = event.parent.theme
+            captured["session"] = event.cookies.get("session")
+            return {"ok": True}
+
+        mod.load = load
+        await run_load(
+            mod,
+            {
+                "params": {"id": "1"},
+                "parent": {"theme": "dark"},
+                "cookies": {"session": "abc"},
+            },
+        )
+        self.assertEqual(captured["theme"], "dark")
+        self.assertEqual(captured["session"], "abc")
+
+    async def test_user_error_helper_not_overwritten(self):
+        mod = types.ModuleType("test")
+
+        def custom_error(status, body):
+            raise SKPVError(418, "teapot")
+
+        mod.error = custom_error
+
+        async def load(event):
+            custom_error(404, "ignored")
+
+        mod.load = load
+        inject_load_helpers(mod)
+        with self.assertRaises(SKPVError) as ctx:
+            await mod.load(wrap_event({}))
+        self.assertEqual(ctx.exception.status, 418)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/package.json

@@ -2,7 +2,7 @@
   "module": "./esm/mod.js",
   "types": "./types/mod.d.ts",
   "name": "sveltekit-python-vercel",
-  "version": "1.0.2",
+  "version": "1.0.3-beta.pr16.2a0070d",
   "description": "Write Sveltekit server endpoints in Python and seamlessly deploy to Vercel",
   "repository": {
     "type": "git",

package/types/src/vite/mod.d.ts

@@ -0,0 +1,8 @@
+import { type Plugin } from "vite";
+export interface SveltekitPythonOptions {
+    python_path?: string;
+    log?: boolean;
+    host?: string;
+    port?: number;
+}
+export declare function sveltekit_python_vercel(opts?: SveltekitPythonOptions): Promise<Plugin[]>;