Metadata-Version: 2.4
Name: lua-spa
Version: 1.2.1
Summary: Backend-first SPA framework in Python.
License-Expression: MIT
License-File: LICENSE
Author: Gabriel da Rosa Silveira
Author-email: gabrielsilveirapro@gmail.com
Requires-Python: >=3.10,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: requests (>=2.32.0,<3.0.0)
Description-Content-Type: text/markdown


<div align="center">
  <img src="http://github.com/roderiano/lua-spa/raw/release/src/lua_template/static/logo.png" alt="lua-spa logo" width="120" height="120" />
  <h1><strong>LUA-SPA</strong></h1>
</div>

<p align="center">
  <a href="https://github.com/roderiano/lua-spa/actions?query=branch%staging">
    <img src="https://github.com/roderiano/lua-spa/actions/workflows/quality-and-tests.yaml/badge.svg?branch=staging" />
  </a>
  <a href="https://codecov.io/gh/roderiano/lua-spa">
    <img src="https://codecov.io/gh/roderiano/lua-spa/branch/staging/graph/badge.svg" />
  </a>
  <img src="https://img.shields.io/pypi/dm/lua-spa" />
  <img src="https://img.shields.io/github/license/roderiano/lua-spa" />
  <img src="https://img.shields.io/github/v/release/roderiano/lua-spa" />
  <img src="https://img.shields.io/github/stars/roderiano/lua-spa?style=flat" />
</p>

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)

``` bash
poetry install
```


### Create a new project

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

### Create a component from template

``` bash
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

``` bash
poetry run lua-spa serve
```

Enable hot reload:

``` bash
poetry run lua-spa serve --reload
```

When reload is enabled, watcher logs use relative paths:

``` text
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:

``` bash
cd docs
npx docusaurus start
```



## Project Structure

``` text
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

``` bash
poetry run pytest
```

With coverage:

``` bash
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.

