The Local Dev Loop
This page describes how to run a scaffolded application on your machine so you can build and style the interface with hot reload. You start the dev server, see the interface render, learn why the local build shows no live data, and set the test runner. When you finish, the application runs at localhost with hot reload, and you understand that real data arrives once the C3 Agentic AI Platform serves the application after you deploy.
Before you begin
Complete Start from the Template, so a scaffolded application with a ui/ directory exists.
Step 1: Start the dev server
From the package root, move into ui/ and start the Vite dev server:
cd ui
npm run devThe dev server serves your index.html with hot module replacement, so a saved change appears in the browser without a full reload. The build sets base: './' so assets resolve under the application path prefix rather than the domain root.
End state: the dev server reports a local address, such as http://localhost:5173.
Step 2: Understand what runs locally
Open the local address, and the interface renders: the layout, the components, the styling, and the interactions all work. The alarm list stays empty, though, and the browser console shows api/8/Alarm/fetch returning 404. This is the correct behavior, and it confirms the interface works. The empty list and the 404 errors are not a misconfiguration.
The data client resolves each api/8/... call relative to wherever the C3 Agentic AI Platform serves the application. On your machine that resolves to localhost, where no C3 backend answers, so every data call returns 404. By default the dev server holds no data of its own and does not reach an environment. The application reaches real data once the C3 Agentic AI Platform serves it, covered in Deploy to an Environment, where the browser and the backend share an origin and the session cookie authenticates each call with no token handling.
End state: the interface renders at localhost, and you understand that, by default, live data arrives after you deploy.
See live data locally (optional)
The default dev server reaches no backend, so deploying is the primary way to see real data, which Deploy to an Environment covers. If you would rather see live data while you iterate, you can point the dev server at a running environment: set VITE_C3_URL and an authentication token in a .env file, and add a server.proxy entry to vite.config.ts that forwards /api (and the other api-style paths) to that environment, which then attaches the token to each proxied request. This is an advanced, development-only setup, and the deployed application never uses a proxy.
Step 3: Iterate on the interface
Edit a component and save it, and the change appears in the browser at once through hot module replacement. Everything about the interface is testable locally: the layout, the component styling, the responsive behavior, and the interactions such as opening a menu or toggling a control. The one thing you cannot exercise locally is real data, so build the interface against the shape your data client returns, and confirm the data path after you deploy.
End state: you can build and style the interface locally with immediate feedback.
Step 4: Set the test runner
Configure the test runner in the test block of vite.config.ts, where you set the test environment, the setup files, and which files to include. The templates use Vitest with a browser-like test environment, and the base applications use Jest. Both run in the C3 Agentic AI Platform, so either is a defensible choice; the guide notes the split rather than forcing one.
To set up Vitest, install the test tools from the ui/ directory:
npm install -D vitest @testing-library/react @testing-library/jest-dom @testing-library/dom jsdomCreate the setup file src/test-setup.ts, which loads the jest-dom matchers:
import '@testing-library/jest-dom'Add the Vitest type reference as the first line of vite.config.ts, and add a test property to defineConfig. The globals: true setting makes the global expect available to the jest-dom matchers:
/// <reference types="vitest/config" /> test: { globals: true, environment: "jsdom", setupFiles: "./src/test-setup.ts" },Then add a test script, and run your tests with npm run test:
npm pkg set scripts.test="vitest run"Quickstart: Build and Deploy an Alarm Clock adds a complete component test with a mocked data client.
End state: a test runner is configured for the application.
What you have now
You have the application running on your machine with hot reload, ready to build and style the interface against real components and layout. Real data arrives when the C3 Agentic AI Platform serves the application, so the next step is to make and write data from your own components in Make API Requests, then serve and deploy the application.
Decisions on this page
The one choice on this page is the test runner.
| Decision | Options | Recommendation |
|---|---|---|
| Test runner | Vitest or Jest | Open; Vitest ships in the template and Jest in the base applications |