---
title: "Bring Your Own (BYO) Overview"
slug: "bring-your-own-byo-overview"
updated: 2026-10-05T15:17:36Z
published: 2026-10-05T15:17:36Z
canonical: "docs.unqork.io/bring-your-own-byo-overview"
stale: true
---
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unqork.io/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](/unqorkai/docs/building-components-byo-sdk).
## 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
```typescript
// 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 = `
`
}
}
```
In the Module Builder, configure a that executes when `onButtonClicked` fires:
```json
{
"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:
```typescript
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:
```typescript
this.onButtonClicked?.({ label: this._label })
```
### Triggers (Module Builder Configuration)
Triggers connect component events to platform logic:
```json
{
"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 `CustomEvent`s 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:
```typescript
// 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:
```json
{
"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](/unqorkai/docs/vega-to-centauri-byo-migration-guide). Centauri BYO has a simpler, more explicit integration model:
| Feature | Vega BYO | Centauri BYO |
| --- | --- | --- |
| **Platform integration** | Operations API — call platform methods directly | Properties + callbacks — declarative data flow |
| **Event dispatch** | Direct API calls | Callbacks configured as triggers |
| **State management** | Manual sync with platform state | Automatic property updates from platform |
| **Configuration** | API keys and methods | Properties defined in model schema |
[Learn more in the Migration Guide](/unqorkai/docs/vega-to-centauri-byo-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
```bash
npx --package=./sdk.tgz create my-button --framework react --ts
cd my-button
npm install
```
#### 2. Start the Dev Server
```bash
npm run dev
```
The dev harness opens at `http://localhost:5173`, simulating how the platform will mount the component.
#### 3. Build for Production
```bash
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**](/unqorkai/docs/building-components-byo-sdk) — step-by-step guide.
### Development
- [**Styling guide**](/unqorkai/docs/styling-guide-byo) — CSS best practices, Shadow DOM, theming.
- [**Best practices**](/unqorkai/docs/best-practices-byo) — performance, security, maintainability.
- [**Testing guide**](/unqorkai/docs/testing-guide-byo-sdk) — write tests for your components.
- [**CLI reference**](/unqorkai/docs/cli-reference-byo-sdk) — complete command documentation.
### Migration & Support
- [**Migration guide**](/unqorkai/docs/vega-to-centauri-byo-migration-guide) — migrate from Vega BYO.
- [**FAQ**](/unqorkai/docs/faq-byo) — common questions and answers.
- [**Troubleshooting**](/unqorkai/docs/troubleshooting-byo) — solve common issues.
---
**Changelog**
| Date | Change |
| --- | --- |
| 2026-09-29 | Specified upload location in Getting Started steps; updated command event listener to use namespaced format (EN-8153). |
| 2026-09-11 | Added BYO Logic Components to What Is BYO; added Promoting BYO Bundles section for Admin dashboard promotions (EN-8097). |
**Technical Details**
- **Contract version**: 1.0.0
- **Module Builder type**: `byoc`
- **Bundle format**: ESM (ECMAScript modules)
- **Runtime environment**: Modern browsers (ES2020+)
JavaScript is an object-oriented computer programming language. It is most-commonly used for interactive effects in the browser.
AngularJS is a JavaScript framework added to an HTML page with a