No native modules, pod install steps, or Expo prebuild steps are required. This is a pure browser/web package.

Project setup

1. Copy the source/ directory into your project, e.g. src/illa-builder/.

2. Add path aliases to tsconfig.json so the internal @/ alias resolves:

   {
     "compilerOptions": {
       "baseUrl": ".",
       "paths": {
         "@/*": ["src/illa-builder/*"]
       }
     }
   }
   

3. If using Vite, mirror the alias in vite.config.ts:

   import { defineConfig } from "vite"
   import path from "path"
   export default defineConfig({
     resolve: {
       alias: { "@": path.resolve(__dirname, "src/illa-builder") }
     }
   })
   

4. Set required environment variables (declared in env.d.ts). At minimum:

   VITE_API_BASE_URL=https://your-backend/api/v1
   VITE_CLOUD_URL=https://cloud.illacloud.com
   

5. Mount the Redux store from source/store.ts in your app root before rendering any builder component:

   import { Provider } from "react-redux"
   import store from "@/store"
   // wrap your app in <Provider store={store}>
   

6. Render App.tsx or individual pages from page/ inside the Provider and a React Router context.

Public API

createResource

import { createResource } from "@/api/actions"
// signature (from api/actions/index.ts)
async function createResource(
  data: ResourceInitialConfig<ResourceContent>
): Promise<string>  // resolves to resourceID

Call this to persist a new data source (database, REST, etc.) for the current team. The function dispatches resourceActions.addResourceItemReducer to keep the Redux store in sync and returns the server-assigned resourceID.

createAction

import { createAction } from "@/api/actions"
// signature
async function createAction(
  appId: string,
  data: Partial<ActionItem<ActionContent>>
): Promise<string>  // resolves to actionID

Attaches a new action (query, mutation, or transformer) to an existing app. Use after creating or selecting a resource. Returns the actionID for subsequent updates or execution triggers.

transformComponentReduxPayloadToWsPayload

import { transformComponentReduxPayloadToWsPayload } from "@/api/ws"
// signature
function transformComponentReduxPayloadToWsPayload(
  componentNodes: ComponentTreeNode[] | ComponentTreeNode
): ILLAWebSocketComponentPayload[]

Converts one or more Redux component tree nodes into the wire format expected by the ILLA WebSocket protocol. Use this before calling getTextMessagePayload to broadcast component mutations to collaborators.

getTextMessagePayload

import { getTextMessagePayload } from "@/api/ws"
// signature
function getTextMessagePayload<T>(
  signal: TextSignal,
  target: TextTarget,
  broadcast: boolean,
  reduxBroadcast: Broadcast | null,
  teamID: string,
  uid: string,
  payload: T[]
): string  // JSON string ready for ws.send()

Serialises a real-time collaboration message. Use in any place where local Redux changes must be broadcast over the text WebSocket channel to other editor sessions.

Working examples

Scenario - Create a PostgreSQL resource and wire it to the store

A backend developer wants to register a PostgreSQL data source programmatically on app initialisation.

import { Provider } from "react-redux"
import store from "@/store"
import { createResource } from "@/api/actions"
import type { ResourceInitialConfig } from "@/redux/resource/resourceState"
import type { ResourceContent } from "@illa-public/public-types"

const pgConfig: ResourceInitialConfig<ResourceContent> = {
  resourceName: "my-postgres",
  resourceType: "postgresql",
  content: {
    host: "db.example.com",
    port: "5432",
    databaseName: "prod",
    username: "app",
    password: "secret",
    ssl: false,
  },
}

async function initResource() {
  const resourceID = await createResource(pgConfig)
  console.log("Created resource:", resourceID)
  // Redux store now contains the new resource entry
  console.log(store.getState().resource)
}

initResource()

Scenario - Attach an action to an app and retrieve its ID

After a resource exists, create a SQL query action bound to an app.

import { createAction } from "@/api/actions"
import type { ActionItem, ActionContent } from "@illa-public/public-types"

const APP_ID = "app_abc123"

async function addQueryAction(resourceID: string) {
  const partial: Partial<ActionItem<ActionContent>> = {
    actionType: "postgresql",
    displayName: "getUserList",
    resourceID,
    content: {
      mode: "sql",
      query: "SELECT * FROM users LIMIT 100;",
    },
    transformer: { enable: false, rawData: "" },
    triggerMode: "manually",
  }
  const actionID = await createAction(APP_ID, partial)
  console.log("Action created with ID:", actionID)
  return actionID
}

Scenario - Broadcast a component update to collaborators via WebSocket

When a user moves a widget, serialize the change and send it over the live collaboration socket.

import {
  transformComponentReduxPayloadToWsPayload,
  getTextMessagePayload,
} from "@/api/ws"
import { TextSignal, TextTarget } from "@/api/ws/textSignal"
import type { ComponentTreeNode } from "@illa-public/public-types"

function broadcastComponentMove(
  ws: WebSocket,
  node: ComponentTreeNode,
  teamID: string,
  uid: string
) {
  const wsPayload = transformComponentReduxPayloadToWsPayload(node)
  const message = getTextMessagePayload(
    TextSignal.UPDATE_STATE,
    TextTarget.COMPONENTS,
    true,       // broadcast to other clients
    null,
    teamID,
    uid,
    wsPayload
  )
  ws.send(message)
}

File walkthrough

• api/actions/index.ts - Typed wrappers for CRUD operations on resources and actions; dispatches results into Redux.
• api/http/base.ts - Axios instance configuration, interceptors, and base URL wiring.
• api/ws/illaWS.ts - Text-protocol WebSocket class with listener registration and reconnect logic.
• api/ws/illaBinaryWS.ts - Binary (protobuf) WebSocket for high-frequency cursor and presence messages.
• api/ws/textSignal.ts - Enumerations for TextSignal and TextTarget used in collaboration messages.
• api/ws/interface.ts - Shared TypeScript interfaces for WebSocket payloads and room types.
• api/ws/ILLA_PROTO.ts - Protobuf schema bindings (Signal, Target, MovingMessageBin).
• api/ws/index.ts - Public facade: exports transformComponentReduxPayloadToWsPayload and getTextMessagePayload.
• components/CodeEditor/ - Full-featured expression editor built on CodeMirror 6 with ILLA context autocompletion.
• components/CodeEditor/CodeMirror/extensions/ - CodeMirror extensions: SQL dialects, JS/HTML/JSON language support, bracket matching, history.
• redux/ - All Redux Toolkit slices for app metadata, component tree, execution results, and resources.
• store.ts - Pre-configured Redux store combining all slices; import directly or wrap with Provider.
• utils/ - Stateless helpers: evaluateDynamicString, estimateMemoryUsage, validationFactory, team ID extraction.
• widgetLibrary/ - Registry of all built-in widget types with their config schemas and render components.
• page/ - Route-level React components (editor canvas, preview mode, deployment view).
• router/ - React Router v6 route tree; import and nest under your own router if partial embedding.
• i18n/config - i18next instance; call i18n.changeLanguage() to switch locales at runtime.
• middleware/ - Redux middleware registration (listener middleware, async thunks).

Common pitfalls and fixes

• @/ alias not resolved at runtime: Ensure both tsconfig.json paths and your bundler alias (vite.config.ts or webpack resolve.alias) point to the same absolute path; a mismatch causes silent 404s.
• getCurrentTeamID() returns undefined: The helper reads team state from the Redux store; mount the Provider with store before any API call is made.
• WebSocket binary messages silently ignored: ILLABinaryWebsocket expects protobuf-encoded frames; passing plain JSON to the binary socket will cause deserialization failures—use illaWS for text messages.
• @illa-public/* packages not found: These are workspace packages from the monorepo; when using outside the monorepo, publish or symlink them, or replace their imports with equivalent standalone packages.
• CodeMirror peer version conflicts: All @codemirror/* packages must be the same minor version; mixing versions causes Facet identity mismatches and silent extension failures.
• lodash-es in a CJS consumer: lodash-es is ESM-only; if your bundler targets CJS, add it to optimizeDeps.include in Vite or use babel-plugin-lodash with the lodash-es alias.

Vibe-coding prompt template

I have dropped the ILLA Builder frontend source into my project at src/illa-builder/.
The integration guide is in USAGE.md next to this message.
The upstream npm package is user@example.com (Apache 2.0 licensed).

Please help me integrate this source into my existing TypeScript + React project step by step:

1. Read USAGE.md and the file excerpts to understand the real exported symbols.
2. Add the required path alias "@/" pointing to "src/illa-builder/" in tsconfig.json
   and vite.config.ts (or webpack config if applicable).
3. Install all dependencies listed in USAGE.md "Required dependencies".
4. Wrap my app root with the Redux Provider using the store from src/illa-builder/store.ts.
5. Show me how to call createResource() and createAction() from src/illa-builder/api/actions/index.ts
   with real TypeScript types.
6. Show me how to broadcast a component change using transformComponentReduxPayloadToWsPayload
   and getTextMessagePayload from src/illa-builder/api/ws/index.ts.
7. Point out any environment variables I need to set based on env.d.ts.
8. Flag any import that references an @illa-public/* workspace package and suggest
   how to resolve it outside the monorepo.

Do not invent any API; only use symbols visible in the source excerpts and USAGE.md.

License and credit

ILLA Builder is released under the Apache License 2.0. See source/LICENSE if present, or refer to the upstream repository for the full license text. Upstream package: user@example.com by the ILLA Cloud team.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.