LUA-SPA

Backend-first SPA framework in Python.

This project includes:

• LuaTemplate file served by the backend
• .lspa components (HTML + Python) with component import support
• Client hydration at component level
• DOM diff renderer inspired by React's virtual DOM flow
• useState hook-style state management
• Setup-only component contract via Component.setup(self, props)
• Server-call bridge for callable actions and lifecycle hooks
• Base app definitions isolated in src/lua_template/spa.config.json

Requirements

• Python 3.10+
• Poetry installed

How to use

Install locally (development)

poetry install

Create a new project

lua-spa create my_project
lua-spa create my_project ./apps

Create a component from template

lua-spa new component UserCard
lua-spa new component UserCard ./apps/my_project

The CLI copies ComponentTemplate, renames files/content, and prints the exact created paths.

Run the application

poetry run lua-spa serve

Enable hot reload:

poetry run lua-spa serve --reload

When reload is enabled, watcher logs use relative paths:

Live reload activated. Watching src for file changes...

Open in browser:

http://127.0.0.1:8000

Documentation

Docs are available in the docs/ directory:

Run locally:

cd docs
npx docusaurus start

Project Structure

lua-spa/
  pyproject.toml
  src/
    lua_spa/
      app.py
      codegen.py
      framework.py
      loader.py
      main.py
      renderer.py
      router.py
      scope.py
      server.py
      runtime_assets.py
    lua_template/
      index.lspa
      spa.config.json
      components/
  tests/

Tests

poetry run pytest

With coverage:

poetry run pytest --cov=src/lua_spa --cov-report=term

Component Format

Components are .lspa files composed of:

• optional imports
• <python> block with a Component subclass implementing setup(self, props)
• <template> block (HTML)

setup(self, props) can return a mapping with props, state, data, actions, and lifecycle, or omit return and let the server infer these sections from local variables/functions. Callable actions and lifecycle entries are executed through the POST /__lua_spa_action bridge. When actions/lifecycle mutate data, those keys are patched back to client props automatically.