Teloce-Py: .vel to a mobile app

Teloce-Py compiles Teloce Single File Components into browser JavaScript and CSS. A .vel file is source code, not an APK. Use it to build the UI, call Flaxon over HTTPS, and package the compiled web app with Capacitor or use a native client.

1. Bootstrap

mkdir flaxon-mobile
cd flaxon-mobile
python -m pip install flaxon teloce-py
mkdir static templates

Create static/App.vel:

<template>
  <main>
    <h1>{{ title }}</h1>
    <button @click="load">{{ status }}</button>
  </main>
</template>
<script>
export default {
  data() { return { title: "Flaxon Mobile", status: "Load health" }; },
  methods: { async load() {
    const response = await fetch("https://api.example.com/api/v1/health");
    this.status = response.ok ? "API online" : "API unavailable";
  }}
};
</script>

2. Serve it from Flaxon

from pathlib import Path
from flaxon import Flaxon
from flaxon.jinax import Jinax
from teloce.build import build_project

ROOT = Path(__file__).parent
build_project(ROOT, options={"dev": True, "source_maps": True})
app = Flaxon("teloce-mobile")
app.use_templates(Jinax(str(ROOT / "templates")))
app.mount_static("/static", str(ROOT / "dist" / "static"))

@app.get("/")
async def index(request):
    return await request.render("index.html")

# Run: flaxon run app:app --reload

In templates/index.html, mount the generated module:

<div id="app"></div>
<script type="module">import { mount } from "/static/App.js"; mount("#app");</script>

You can also compile from CI with teloce build --out-dir dist --source-map --hash-assets. Keep .vel source in Git and deploy generated assets from your chosen output directory.

3. Package the web client

npm install @capacitor/core @capacitor/cli @capacitor/android
npx cap init "Flaxon Mobile" com.example.flaxonmobile --web-dir dist
npx cap add android
npx cap copy android
npx cap open android

Configure the production API origin, Android network policy, icons, splash screen, permissions, and deep links in the Android project. Then use Android Studio or ./gradlew bundleRelease to create the signed AAB. Follow the Play Store checklist.

References

Teloce-Py repository | Teloce-Py reference | Jinax starter

WebView and Trusted Web Activity

When a Teloce-Py app is deployed as an HTTPS PWA, an Android wrapper can display it. A WebView embeds the page in a native Android activity. A Trusted Web Activity (TWA) opens the PWA using the browser engine and requires domain verification. Both package the client shell; the Flaxon backend remains deployed remotely.

Minimal WebView shell

class MainActivity : Activity() {
    override fun onCreate(state: Bundle?) {
        super.onCreate(state)
        val web = WebView(this)
        web.settings.javaScriptEnabled = true
        web.settings.domStorageEnabled = true
        web.loadUrl("https://app.example.com/")
        setContentView(web)
    }
}

Use a release HTTPS origin, restrict navigation to approved hosts, avoid exposing an unnecessary JavaScript bridge, handle external links and back navigation, and follow Android WebView security guidance. A TWA uses a package tool such as Bubblewrap or PWABuilder output and normally requires Digital Asset Links at /.well-known/assetlinks.json.

Choose the wrapper

• WebView: more native control, but you own lifecycle, navigation, permissions, and security hardening.
• TWA: a browser-based PWA experience with less native UI code; configure domain verification and browser requirements.
• Capacitor: useful when the web app needs selected native plugins and a generated Android project.

After packaging, build a signed APK for device testing or a signed AAB for Google Play. Test cold start, offline state, API failures, cookies/tokens, deep links, external links, rotation, and updates.