Connect an existing web app

Check the integration boundary#

This guide assumes you have a frontend that can build to static HTML, JavaScript, and CSS. Trove loads those assets in its WebView. React and Vue can use the same SDK; no Trove-specific rendering framework is required.

An SSR server is not automatically bundled or hosted by Trove. Export a static client or move the necessary native/server logic into a Backend. Keep credentials and native-only modules out of your browser bundle.

Obtain the matching SDK#

The SDK is currently distributed with the CLI template. Create a separate temporary template next to your existing project:

trove curio init sdk-starter --template web --yes

Copy sdk-starter/vendor/ into your project. Add the dependency below to its existing package.json, preserving your other dependencies, then run your package manager’s install command:

{
  "dependencies": {
    "@trove/plugin-sdk": "file:vendor/trove-plugin-sdk-0.1.0.tgz"
  }
}

This is a dependency fragment, not a replacement package file. Use the filename generated by your installed CLI if its version differs. Commit vendor/ and the updated lockfile. trove curio init always creates a new directory; it does not import or overwrite an existing project.

Add a manifest#

Create curio.json at the existing project root. This complete UI-only example assumes npm scripts named dev and build, with production output in dist/:

{
  "schemaVersion": 1,
  "id": "dev.example.my-web-app",
  "name": "My Web App",
  "version": "0.1.0",
  "engine": { "trove": ">=0.1.0 <1.0.0" },
  "ui": { "entry": "dist/index.html" },
  "development": {
    "ui": {
      "url": "http://127.0.0.1:5173",
      "command": ["npm", "run", "dev"]
    }
  },
  "build": { "command": ["npm", "run", "build"] },
  "package": { "files": ["dist"] }
}

Change the ID, display name, output path, and commands to match your project. ui.entry is a local production HTML file; development.ui.url is the development address. Do not put a remote website URL into ui.entry.

Align the development and asset paths#

For Vite, merge these settings into your existing config and keep its framework plugins:

import { defineConfig } from "vite";

export default defineConfig({
  base: "./",
  server: { host: "127.0.0.1", port: 5173, strictPort: true },
  build: { outDir: "dist" },
});

Relative asset URLs keep JavaScript and CSS resolvable from the packaged entry. Check images, fonts, lazy imports, and navigation after packaging. For a single HTML entry, hash-based client routing avoids requiring an HTTP history fallback.

If your server is already running, connect to it without starting a second process:

trove curio dev --no-start-ui --ui-url http://127.0.0.1:5173

For simultaneous projects, use distinct fixed ports or adopt the template’s dynamic port setup described in local development.

Connect from your UI#

Call the SDK from an event handler or a client-side lifecycle hook. Give the user loading, success, and error feedback:

import { trove, TroveError } from "@trove/plugin-sdk";

export async function inspectHost() {
  try {
    await trove.ready();
    return await trove.call("host.runtime", "getHostInfo", {});
  } catch (error) {
    if (error instanceof TroveError) {
      console.error(error.code, error.message, error.traceId);
    }
    throw error;
  }
}

Importing the SDK is safe outside Trove; using the default client or reading its context requires Host. Do not silently replace failed native calls with fake successful results. Use a separately configured mock client only in tests.

Verify both modes#

1. Run trove curio check from your project. Resolve manifest and dependency errors.
2. Run trove curio dev; confirm the UI and a real Host response.
3. Stop that session, run trove curio pack, and install the archive with trove curio install.
4. Open the installed Curio with the UI server stopped. Exercise navigation and asset loading, then repeat the native call.

A working development URL alone does not verify the packaged application. See distribution for file selection and native runtime requirements.