C3 AI Documentation Home

Use libraries from the npm ecosystem

The C3 Agentic AI Platform allows you to use libraries from the npm ecosystem, but the platform enforces a different workflow than a typical Node.js project. Instead of using package.json or running npm install, the platform requires you to declare libraries in a shared, version-locked runtime named js-webpack_c3.

This runtime controls all frontend dependencies, including those for custom React components. You must declare each dependency in this runtime and resolve it using the C3 AI Console.

Do not run npm install. Do not create a local package.json. The platform controls all dependency resolution centrally.

Use platform-provided core libraries

The platform automatically includes these core libraries:

  • Node.js
  • React
  • Redux

The runtime already contains these libraries. Do not redeclare them. If you redeclare them, the platform may throw runtime errors or load conflicting versions.

Understand how the platform runtime works

The js-webpack_c3 runtime replaces the standard Node.js dependency mechanism. The table below maps traditional concepts to platform equivalents:

Node.js conceptC3 AI Platform equivalent
package.jsonDeclares runtime dependencies
package-lock.jsonLocks exact versions during runtime resolution
npm installResolves and locks libraries using console methods
node_modules/Platform manages code distribution internally
Console commandsUpserts and resolves declared libraries
Metadata outputStores version-locked runtime and dependency graph

To declare libraries, create or edit the file:

Text
{package}/metadata/ImplLanguage.Runtime/js-webpack_c3.json

Declare the libraries, then use the C3 AI Console commands under "Step 3: Resolve the runtime". These commands write the resolved runtime state to:

Text
{package}/metadata/ImplLanguage.Runtime/
{package}/metadata/Js.Runtime/

Every component that references js-webpack_c3 loads libraries only from the resolved runtime. The platform enforces exact version matches and ensures consistent builds across teams and environments.

To understand how the runtime system supports platform-wide resolution, read Understanding Action Engines.

Add a new npm library

Use the steps below to add Material UI to your runtime.

Step 1: List installed libraries

Run the following command in the C3 AI Console:

JavaScript
ImplLanguage.Runtime.forName("js-webpack_c3").libraries

The console prints all installed libraries and their locked versions. Check this list before you add a new dependency.

Step 2: Edit the runtime definition

If the runtime file exists:

  1. Open the file:

    Text
    {package}/metadata/ImplLanguage.Runtime/js-webpack_c3.json

  2. Add the packages:

    JSON
    {
  "name": "js-webpack_c3",
  "libraries": [
    "npm @mui/material@5.14.0",
    "npm @emotion/react@11.11.1",
    "npm @emotion/styled@11.11.0"
  ]
}

If the runtime file does not exist:

  1. Create the file at the path above.

  2. Add a basic definition:

    JSON
    {
  "name": "js-webpack_c3",
  "libraries": []
}

  3. Run the resolution commands (see Step 3) to initialize the metadata.

  4. Reopen the file and declare the libraries you want.

Step 3: Resolve the runtime

Run the following commands in the C3 AI Console:

JavaScript
var runtime = ImplLanguage.Runtime.forName("js-webpack_c3");
Pkg.setDevMode(true);
Js.upsertRuntime(runtime, "client");

These commands register the runtime, download all dependencies, lock their versions, and write the metadata to your package.

Step 4: Import and use the libraries

Once you resolve the runtime, import libraries into your component:

TypeScript
// {package}/ui/c3/src/customInstances/MyComponent.tsx

import Button from '@mui/material/Button';

const MyComponent = () => {
  return <Button variant="contained">Hello world</Button>;
};

Use SDL or route configuration to render your component in the UI.

See also

Was this page helpful?