Teloce-Py and .vel

Teloce-Py is the Python compiler and browser runtime for Teloce Single File Components. A .vel file combines a template, JavaScript component logic, and optional scoped CSS. Flaxon, Flask, FastAPI, Django, or a static server delivers the generated assets; Teloce does not replace the Python application layer.

Teloce-Py repository | Cheatsheet | Android packaging

What Teloce-Py does

  • Discovers and compiles .vel components into JavaScript and CSS.
  • Supports templates, interpolation, conditions, loops, events, forms, bindings, components, slots, imports, filters, plugins, and scoped styles.
  • Provides reactive state, computed values, watchers, lifecycle hooks, props, emits, DOM mounting, and router/runtime utilities.
  • Works with Python backends while keeping authorization, validation, persistence, jobs, secrets, and integrations on the server.
Boundary: browsers receive generated .js/.css, never the source .vel file. Teloce-Py does not compile Python into an APK or MSIX.

Bootstrap a project

python -m pip install flaxon teloce-py
mkdir my-app
cd my-app
mkdir static templates
teloce doctor --verbose

On Windows PowerShell, use New-Item -ItemType Directory -Force static, templates. Recommended layout:

my-app/
  app.py
  templates/index.html
  static/js/App.vel
  static/js/components/
  manifest.webmanifest
  sw.js
  dist/

Write a component

Create static/js/App.vel:

<template>
  <main class="app">
    <h1>{{ title }}</h1>
    <p>{{ message }}</p>
    <input v-model="name" placeholder="Your name">
    <button @click="greet">Greet</button>
    <ul><li v-for="item in items" :key="item.id">{{ item.label }}</li></ul>
  </main>
</template>
<script>
export default {
  data() { return { title: "Teloce", message: "Edit a .vel file", name: "", items: [{ id: 1, label: "Flaxon" }] }; },
  computed: { greeting() { return "Hello " + this.name; } },
  methods: { greet() { this.message = this.greeting; } },
  mounted() { console.log("component mounted"); }
};
</script>
<style scoped>
.app { max-width: 40rem; margin: 4rem auto; font-family: system-ui; }
</style>

The original Teloce forms remain valid: <if condition="ready">, <for each="item in items">, @click, and :model. Familiar aliases such as v-if, v-for, v-on:click, and v-model are also supported. Use v-text for escaped text and only use v-html with trusted, sanitized HTML.

Components and imports

Create static/js/components/Message.vel:

<template><p class="message">{{ text }}</p></template>
<script>
export default { props: { text: { type: String, default: "Hello" } } };
</script>

Import it from App.vel:

<script>
import Message from "./components/Message.vel";
export default { components: { Message }, data() { return { text: "Reusable UI" }; } };
</script>
<template><Message :text="text" /></template>

Use stable prop and event contracts, keys for lists, semantic HTML, keyboard support, visible focus states, touch-sized controls, and responsive layouts. Test phone, tablet, desktop, and wide screens.

Mount from HTML

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

Run with 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-flaxon")
app.use_templates(Jinax(str(ROOT / "templates"), auto_reload=True))
app.mount_static("/static", str(ROOT / "static"))

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

# Development: flaxon run app:app --reload

A component calls the backend with fetch() or WebSockets. The server validates every request and owns authentication, CSRF, authorization, database operations, and secrets.

CLI workflow

teloce create my-app
teloce doctor --verbose
teloce lint --strict
teloce dev
teloce watch
teloce build --out-dir dist --source-map
teloce build --out-dir dist --hash-assets --bundle
teloce debug

Use teloce dev or teloce watch for local iteration. Run lint and a clean production build in CI. Keep source maps available to your error pipeline but do not expose secrets in them.

npm Teloce connection

Teloce-Py targets the same component ideas as Teloce on npm: .vel SFCs, reactive state, events, loops, conditions, components, styles, filters, plugins, and runtime mounting. Existing source can often be copied into a Python project because the original syntax and common v-* aliases are supported.

The workflows are different:

npm Teloce: JavaScript package tooling -> browser assets
Teloce-Py: Python compiler -> browser assets -> Flask/FastAPI/Django/Flaxon

Node-only plugins are not automatically executable in Python. A syntax-only plugin may be ported to the Teloce-Py plugin system; a plugin that imports npm packages, starts Node, or uses Node APIs needs a replacement. Migrate one component at a time, keep the HTTP contract stable, compile it, and run browser tests.

When to use npm tooling

  • Use npm Teloce when the frontend already depends on Node packages, bundlers, or Node-specific plugins.
  • Use Teloce-Py when the team wants a Python-only build workflow alongside Flask, FastAPI, Django, or Flaxon.
  • Use either runtime with the same component design, but do not assume generated output or third-party plugins are byte-for-byte compatible.

Reactivity and browser runtime

Component state is local to the browser. Teloce supports object-style data, methods, computed, watch, lifecycle hooks, props, and emits. The runtime also exposes signal primitives for fine-grained state when a larger application needs them. Use IndexedDB only for local browser drafts or offline cache; synchronization and conflict resolution belong in a server API.

PWA setup

Create manifest.webmanifest:

{
  "name": "Flaxon Mobile",
  "short_name": "Flaxon",
  "start_url": "/",
  "display": "standalone",
  "theme_color": "#0f172a",
  "background_color": "#ffffff",
  "icons": [
    { "src": "/static/icons/icon-192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/static/icons/icon-512.png", "sizes": "512x512", "type": "image/png" }
  ]
}

Link it in the HTML head and register sw.js:

<link rel="manifest" href="/manifest.webmanifest">
<script>
if ("serviceWorker" in navigator) navigator.serviceWorker.register("/sw.js");
</script>
const CACHE = "flaxon-shell-v1";
const ASSETS = ["/", "/static/js/App.js", "/manifest.webmanifest"];
self.addEventListener("install", event => event.waitUntil(caches.open(CACHE).then(cache => cache.addAll(ASSETS))));
self.addEventListener("fetch", event => event.respondWith(caches.match(event.request).then(cached => cached || fetch(event.request))));

Serve the manifest, service worker, icons, and generated assets over HTTPS. Test install, offline fallback, updates, cache invalidation, API failures, and authentication expiry before packaging.

PWABuilder: Android package and MSIX

PWABuilder packages a deployed PWA; it does not package the Flaxon Python server. First deploy the compiled frontend at a public HTTPS URL and verify the manifest, service worker, icons, responsive UI, and offline behavior.

  1. Open PWABuilder and enter the HTTPS PWA URL.
  2. Fix manifest and service-worker diagnostics, then choose the Android package or Windows package option.
  3. For Android, review the generated Trusted Web Activity/package settings, application ID, signing configuration, API origin, and icon set. Use the generated Android project to build a signed APK for testing or AAB for Google Play where required.
  4. For Windows, review the generated Windows package and identity details, then build/sign the MSIX with the generated project or supported packaging workflow.
  5. Test the installed package on clean devices. Confirm deep links, external links, back navigation, offline state, permissions, API connectivity, and update behavior.

Follow platform signing and store rules. Google Play generally uses signed Android App Bundles for new releases; the Microsoft Store requires a correctly signed MSIX and package identity. Keep the Flaxon backend deployed separately.

Production checklist

  • Pin Python, Teloce-Py, and runtime versions.
  • Compile all .vel files in CI and deploy immutable hashed assets.
  • Use HTTPS, secure authentication, server-side authorization, request validation, rate limiting, and durable storage.
  • Do not place credentials, signing keys, or privileged operations in .vel or browser storage.
  • Test compiler diagnostics, generated asset paths, browser behavior, PWA install, package signing, and API error states.
  • Run teloce doctor --verbose, teloce lint --strict, Python tests, and browser end-to-end tests before release.

Lesson map

The full Teloce-Py lessons cover first components, building blocks, reusable design, Flaxon apps, OS-style interfaces, production delivery, Django/FastAPI/Flask integration, case studies, PWA/MSIX, search applications, animation and Three.js, plugins, compiler internals, CLI workflow, signals, runtime/router behavior, and a Vel IDE. Start with the lesson directory and use this page as the website reference.