Create your first Curio

Before you start#

You need macOS and access to a working Trove build. On Trove’s Development page, install or check the shell command, open a new terminal, and confirm the executable:

trove --version
trove curio --help

The Web template requires Node.js 20.19+ or 22.12+ and your selected package manager. The following walkthrough uses npm. The static template does not require Node, Rust, or package installation. A public Trove installer is not available yet.

Create the project#

Run this from the parent directory where you want a new project. my-curio must not already exist, even as an empty directory.

trove curio init my-curio --name "My Curio" --id dev.example.my-curio --template web --package-manager npm --yes
cd my-curio
npm install
trove curio check
trove curio dev

--yes accepts configuration defaults; it does not install dependencies. Alternatively, run trove curio init for the interactive prompts. Choose Web and your preferred package manager, then follow its generated commands.

The CLI starts or connects to Host, launches the UI server, and opens your Curio window. Keep that terminal open. The starter page shows the Host connection and two buttons for communication and storage examples. A successful call displays the actual response on the page and in Console.

Find the files you will edit#

The starter UI supports system light/dark appearance. Keep the generated component licenses and third-party notices when reusing its UI.

Make your first call#

Use this in a module or an async event handler in your frontend. The echo service returns the JSON value you send.

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

await trove.ready();
const result = await trove.call<{ message: string }>(
  "host.runtime",
  "echo",
  { message: "Hello from my Curio" },
  { timeoutMs: 5_000 },
);
console.log(result.message);
console.log(trove.context.curioId);

Expected result: Hello from my Curio, followed by dev.example.my-curio. Render the response in your UI and handle rejection; the SDK reference shows structured error handling. Editing the Web template updates the window through Vite’s development server.

Opening the page in an ordinary browser does not provide the Host bridge. Real native calls must run in a Trove window. Use the explicit mock bridge for browser-only tests.

Build and verify the package#

Stop the development session with Ctrl-C before checking the installed version, then run:

trove curio pack
trove curio install

The archive is written to dist/packages/<id>-<version>-<target>.curio. install selects it automatically when there is exactly one candidate. Open the installed Curio in Trove and repeat the communication example with the development server stopped. This verifies the production entry and packaged assets.

Start without a build tool#

trove curio init my-static-curio --template static --yes
cd my-static-curio
trove curio check
trove curio dev

The static template contains its UI and SDK in ui/index.html. Edit that file and reload the Curio window to see changes; there is no Vite hot reload. For editable JSX, styles, and SDK imports, use the Web template. Continue with local development.