Bring Your Own (BYO) Overview

Build custom components for the UnqorkAI platform using vanilla JavaScript, React, Vue, Angular, or Lit. BYO (Bring Your Own) gives Creators full control over component behavior and appearance while integrating with the Unqork runtime.

BYO is a developer feature that requires JavaScript expertise. Creators evaluating whether a project needs a custom component will find the relevant context in this overview. Developers ready to build can skip directly to Building Components.

What Is BYO?

BYO lets Creators build custom components that run inside Unqork applications. Two types are available:

BYO UI Components: Custom interface components rendered in the Module Builder canvas. BYO UI components can do the following:

• Integrate with platform state: Receive data from submission data and other components.

• Trigger workflows: Dispatch events that can execute platform logic.

• Use any framework: Build with vanilla JavaScript, React, Vue, Angular, or Lit.

• Deploy globally: Upload, use across all applications in the environment.

BYO Logic Components: Custom headless components that execute logic without rendering a UI. BYO Logic components run in the platform's logic layer and integrate with the same properties and callbacks model as UI components. Use BYO Logic components when business logic requires code that cannot be expressed with platform components alone.

When to Use BYO

Appropriate Use Cases

Use BYO when the following apply:

• Third-party libraries: A specific JavaScript library provides functionality Unqork doesn't offer natively. Examples include charting (D3.js, Chart.js), payment processing (Stripe Elements, Plaid), document signing (DocuSign, Adobe Sign), and embedded analytics (Power BI).

• Existing proprietary logic: Code that already exists, like a pricing engine, insurance rater, or domain-specific algorithm, must run inside an Unqork application.

• Specialized UI components: Branded or domain-specific components from an existing system need to integrate with Unqork.

When to Avoid BYO

Avoid BYO when the following apply:

• Built-in Unqork components can meet the need with configuration.

• Simple CSS styling achieves the visual goal.

• Logic components like Triggers or Calculators can implement the business logic.

• The requirement is temporary or-off. The maintenance overhead is not worth it.

Decision Flowchart

How It Works

BYO components use a properties + callbacks model with the following interactions:

1. Platform → Component: The platform sets data as JavaScript properties on the component.

2. Component → Platform: The component calls callback functions to dispatch events.

The component is intentionally isolated from the platform's internal APIs. All integration happens through a clean, versioned contract.

Example: Button Component

// Define your component as a Web Component
class MyButton extends HTMLElement {
  // Platform sets these properties
  set label(value: string) {
    this._label = value
    this.render()
  }
  
  set disabled(value: boolean) {
    this._disabled = value
    this.render()
  }
  
  // Your component calls this callback
  handleClick() {
    this.onButtonClicked?.({ label: this._label })
  }
  
  render() {
    this.innerHTML = `
      <button ${this._disabled ? 'disabled' : ''}>
        ${this._label}
      </button>
    `
  }
}

In the Module Builder, configure a  that executes when onButtonClicked fires:

{
  "key": "myButton",
  "type": "byoc",
  "triggers": {
    "onButtonClicked": {
      "contextId": "clickData",
      "targetId": "someLogicComponent"
    }
  }
}

When the button is clicked, clickData is populated with { label: "Click me" } and the logic component executes.

Key Concepts

Properties (Platform → Component)

The platform sets the following properties on the component element:

• submissionData: The component's current submission value.

• State properties: Any properties defined in the component's model, like label, items, and disabled.

Implement a setter for each property the component must handle:

set label(value: string) {
  this._label = value
  this.render()
}

Callbacks (Component → Platform)

The platform wires callback functions as properties on the component. Call them to dispatch the following events:

• onSubmissionUpdate(value): Updates the component's submission data.

• on<EventName>(payload): Fires a trigger configured in the Module Builder.

Always guard with optional chaining because callbacks are set after mount:

this.onButtonClicked?.({ label: this._label })

Triggers (Module Builder Configuration)

Triggers connect component events to platform logic:

{
  "triggers": {
    "onItemSelected": {
      "contextId": "selectedItem",
      "targetId": "processSelectionLogic"
    }
  }
}

When the component calls this.onItemSelected({ id: 123 }), the platform stores { id: 123 } in the selectedItem context field and executes the processSelectionLogic component.

Commands (Platform → Component)

Commands are fire-and-forget CustomEvents dispatched to the component from the platform. They enable imperative method-like interactions for headless or service components.

The component listens for commands using event listeners on the element:

// Listen for commands via event listeners
element.addEventListener('myComponent:reset', (e) => {
  const { silent } = e.detail || {}
  this.resetState(silent)
})

Commands are dispatched when BYOC Execute outputs are triggered from logic components like the Initializer, Decision, and Logic Block components. Configure them in the Module Builder:

{
  "outputs": [
    {
      "targetId": "myComponent",
      "type": "byocExecute",
      "value": {
        "componentType": "myComponent",
        "commandType": "reset",
        "args": { "silent": true }
      }
    }
  ]
}

When to Use Commands

• Imperative operations like reset, refresh, focus, and validate.

• Headless or service components like payment gateways and analytics integrations.

• Third-party library integrations with method-based APIs.

How Commands Differ from Events

• Direction: Commands flow to components; events flow from components.

• Pattern: Fire-and-forget with no return value; events trigger workflows.

• Use case: Imperative actions; events represent state changes.

Differences from Vega BYO

Centauri BYO is the recommended architecture for new components. Creators with existing Vega BYO components can migrate using the Migration Guide. Centauri BYO has a simpler, more explicit integration model:

Learn more in the Migration Guide

Getting Started

BYO development has two phases: a-time environment setup and a per-component build cycle. Complete the setup steps per developer environment. Repeat the build cycle for each component created or updated.

One-Time Setup

1. Download and Install the BYO SDK

Download the BYO SDK from the Unqork administration screen:

1. In the UnqorkAI platform, navigate to Custom Assets Administration.

2. Click BYO SDK.

3. Follow the BYO SDK installation instructions.

For Each Component

1. Scaffold a New Project

npx --package=./sdk.tgz create my-button --framework react --ts
cd my-button
npm install

2. Start the Dev Server

npm run dev

The dev harness opens at http://localhost:5173, simulating how the platform will mount the component.

3. Build for Production

npm run build:prod

This creates a .tar.gz archive in dist/ ready for upload to the UnqorkAI platform.

4. Upload to Unqork

In the UnqorkAI platform, navigate to Custom Assets Administration. Upload the .tar.gz file to make the component available in the Module Builder.

Promoting BYO Bundles

Creators with Administrator access can promote BYO component bundles to upper environments directly from the Administration dashboard. The Promotions modal displays available target environments and a history of past promotions, including destination, timestamp, and the Creator who initiated each.

To promote a BYO bundle:

1. In the UnqorkAI platform, navigate to Custom Assets Administration.

2. Locate the bundle to promote and select Promote.

3. Select the target environment in the Promotions modal.

4. Review the promotion history, then confirm.

The bundle becomes available in the target environment immediately after promotion completes.

Documentation

Getting Started

• Build your first component — step-by-step guide.

Development

• Styling guide — CSS best practices, Shadow DOM, theming.

• Best practices — performance, security, maintainability.

• Testing guide — write tests for your components.

• CLI reference — complete command documentation.

Migration & Support

• Migration guide — migrate from Vega BYO.

• FAQ — common questions and answers.

• Troubleshooting — solve common issues.