UI Package Structure for `npm` Applications
A C3 AI package can include an npm-based UI application, such as a React application, that the C3 Agentic AI Platform builds, tests, and packages during a build. To enable this, add a ui declaration to your package's .c3pkg.json manifest.
Packages without a ui block are not built or tested by the platform build.
Enable the UI build for your package
Add a ui block to your .c3pkg.json manifest. The ui block is an instance of Pkg.Ui.Decl.
The following manifest enables a UI build with explicit install, build, and test commands:
{
"name": "myApp",
"version": "1.0.0",
"dependencies": {
"uiComponentLibraryReact": "8.11"
},
"ui": {
"installCommand": "npm install",
"buildCommand": "npm run build",
"testCommand": "npm run test",
"buildDirectory": "dist",
"testOutputDir": ["coverage"],
"uiRootDirectory": "ui/react"
}
}UI build fields
Every field is optional. When you omit a field, the platform applies the default value. The following table describes each field:
| Field | Description | Default |
|---|---|---|
installCommand | The command that installs the UI dependencies. | install |
buildCommand | The command that builds the UI application. | run build |
testCommand | The command that runs the UI tests. | run test |
buildDirectory | The directory where the build produces its output. | dist |
uiRootDirectory | The root directory of the UI application within the package. | ui/react |
testOutputDir | The directories that hold test output, such as coverage or reports. | Empty |
testContainer | The container settings that run the UI build and tests. | See below |
The testContainer settings default to 8192 MiB of memory, the c3genesis/c3genesis-ui repository, and image tag 2.4.3.
Expected directory layout
With the default values, the platform expects the following structure. Your npm project defines the build and test scripts, and produces the output directories you name in the manifest:
myApp/
myApp.c3pkg.json # Manifest with a "ui" block
src/ # C3 AI Types and back-end code
ui/
react/ # uiRootDirectory (default)
package.json # npm project that defines the build and test scripts
src/ # UI application source
dist/ # buildDirectory (default), produced by the build command
coverage/ # A testOutputDir entry, produced by the test commandHow the build uses the declaration
The platform runs the install, build, and test commands as separate, labeled steps and shows each step's output in the build:
- Install and build: A failure in either step stops the UI package build.
- Test: A test failure is reported without failing the overall build, so test results stay visible.