{"id":6270,"library":"trame-client","title":"trame-client","description":"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.","status":"active","version":"3.11.4","language":"en","source_language":"en","source_url":"https://github.com/Kitware/trame-client","tags":["trame","web development","client-side","javascript","framework","visualization"],"install":[{"cmd":"pip install trame-client","lang":"bash","label":"Install trame-client"},{"cmd":"pip install trame","lang":"bash","label":"Recommended: Install trame (includes trame-client)"}],"dependencies":[{"reason":"trame-client is an internal component of the trame framework and is generally used as a dependency of the main 'trame' package.","package":"trame","optional":false}],"imports":[{"note":"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.","symbol":"trame.widgets.html","correct":"from trame.widgets import html"}],"quickstart":{"code":"from trame.app import get_server\nfrom trame.ui.html import Div\nfrom trame.widgets import html\n\n# -----------------------------------------------------------------------------\n# Trame setup (trame-client is implicitly used by trame)\n# -----------------------------------------------------------------------------\n\nserver = get_server(name=\"trame_client_example\")\n# Explicitly set client_type for trame v3+ to manage Vue.js version\nserver.client_type = \"vue3\"\n\nstate, ctrl = server.state, server.controller\n\n# 1. Initial state\nstate.value = 0\nstate.message = \"Initial message\"\n\n# 2. Callbacks\n@state.change(\"value\")\ndef update_message(value, **kwargs):\n    state.message = f\"Value is now: {value}\"\n\ndef increment():\n    state.value += 1\n\n# 3. UI definition using trame.widgets.html (which relies on trame-client)\nwith Div(classes=\"container\") as main_layout:\n    with html.Div(\"Hello Trame-client!\", classes=\"text-h4 q-my-md\"):\n        pass\n    with html.Div(classes=\"text-h6 q-my-md\"):\n        html.P(\"Current message: {{ message }}\")\n    with html.Button(\"Increment\", click=increment, classes=\"q-mr-sm\"):\n        pass\n    with html.Span(\"Value: {{ value }}\", classes=\"q-ml-sm\"):\n        pass\n\n# 4. Start server\nif __name__ == \"__main__\":\n    # This will open a browser window with the Trame application\n    server.start()","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"trame >= 3.0.0, trame-client >= 3.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"trame >= 3.0.0, trame-client >= 3.0.0"},{"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`).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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'.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z","problems":[]}