trame-client

3.11.4 · active · verified Tue Apr 14

trame-client is the internal JavaScript core of the trame framework, providing client-side infrastructure for web applications. It handles connections to a trame server, state synchronization, method calls, dynamic component loading, and template feeding in the browser. It is typically installed as a dependency of the main 'trame' package and is not intended for direct end-user Python interaction. The current version is 3.11.4, and it follows the release cadence of the trame ecosystem.

Warnings

breaking Trame v3 (and by extension, trame-client in its context) changed the default client type from Vue 2 to Vue 3 starting December 2023. Existing applications built with Vue 2 components might break if not explicitly configured.
Fix: Explicitly set `server.client_type = 'vue2'` in your Trame application if you need to maintain compatibility with Vue 2 components. For new development or migration, embrace Vue 3 and its compatible widgets.
breaking With trame v3, the default dependency list was shrunk. Core widgets like Vuetify, VTK, and Plotly are no longer bundled by default with the main `trame` package. They must be installed separately as `trame-vuetify`, `trame-vtk`, `trame-plotly`, etc.
Fix: Ensure you explicitly install any required trame widget libraries (e.g., `pip install trame-vuetify trame-vtk`) in your project's dependencies if your application uses them.
gotcha trame-client is primarily a client-side (JavaScript) library bundled for Python's trame framework. It is not intended for direct Python imports or standalone usage for application logic. All client-side interactions are abstracted and managed by the main `trame` library.
Fix: Avoid attempting to import directly from `trame_client` in your Python application code. Instead, use the `trame` API (e.g., `from trame.app import get_server`, `from trame.widgets import html`).
gotcha When deploying Trame applications, a common issue is the client loading screen appearing before the Trame server's WebSocket connection is fully established, leading to a 'connection_error'.
Fix: Ensure that the Trame server is fully started and its WebSocket endpoint is ready before making the application accessible to users (e.g., deferring Nginx startup until the Trame server responds successfully). Consider implementing client-side retries or automatic page refreshes if the WebSocket connection fails initially.

Install

pip install trame-client Install trame-client
pip install trame Recommended: Install trame (includes trame-client)

Imports

trame.widgets.html
```
from trame.widgets import html
```
While trame-client is the underlying JavaScript engine, end-users interact with client-side components primarily through trame's Python API, such as widgets exposed in `trame.widgets.html` or other trame widget libraries.

Quickstart

This quickstart demonstrates a basic Trame application, which implicitly uses `trame-client` for its client-side functionality. Since `trame-client` is an internal dependency, end-users typically interact with Trame through its main API and widgets. Run this Python script and navigate to the displayed URL in your browser.

from trame.app import get_server
from trame.ui.html import Div
from trame.widgets import html

# -----------------------------------------------------------------------------
# Trame setup (trame-client is implicitly used by trame)
# -----------------------------------------------------------------------------

server = get_server(name="trame_client_example")
# Explicitly set client_type for trame v3+ to manage Vue.js version
server.client_type = "vue3"

state, ctrl = server.state, server.controller

# 1. Initial state
state.value = 0
state.message = "Initial message"

# 2. Callbacks
@state.change("value")
def update_message(value, **kwargs):
    state.message = f"Value is now: {value}"

def increment():
    state.value += 1

# 3. UI definition using trame.widgets.html (which relies on trame-client)
with Div(classes="container") as main_layout:
    with html.Div("Hello Trame-client!", classes="text-h4 q-my-md"):
        pass
    with html.Div(classes="text-h6 q-my-md"):
        html.P("Current message: {{ message }}")
    with html.Button("Increment", click=increment, classes="q-mr-sm"):
        pass
    with html.Span("Value: {{ value }}", classes="q-ml-sm"):
        pass

# 4. Start server
if __name__ == "__main__":
    # This will open a browser window with the Trame application
    server.start()

view raw JSON →