BYO SDK

The BYO SDK provides everything you need to build, develop, test, and deploy custom components for the Unqork platform.

What's Included

• CLI (create): Scaffold new projects from templates.
• CLI (byo): Dev server, production builds, code generation, and validation.
• TypeScript types: Complete type definitions for the BYO contract.
• Build tooling: Vite-based bundler with framework presets.
• Dev harness: Host simulation for local development.
• Testing utilities: Helpers for mounting and testing components.
• Lint configs: Shareable ESLint and Prettier configurations.

Installation

Download the BYO SDK from the Unqork administration screen:

Navigate to Administration > Environment Settings > Assets > Custom Assets Administration in the Unqork IDE.

1. Select BYO SDK.
2. Download the SDK package for your operating system.
3. Extract and follow the installation instructions included in the package.

Quick Start

1. Scaffold a New Project

This command runs the create scaffolding tool directly from the downloaded sdk.tgz file. Replace my-component with the name of your new component project. The --framework flag sets the component framework, and --ts enables TypeScript.

npx --package=./sdk.tgz create my-component --framework react --ts

To be prompted for all configuration options, run the command without arguments:

npx --package=./sdk.tgz create

The --framework flag accepts the following values:

• vanilla: Plain Web Components.
• react: React with react-to-webcomponent bridge.
• vue: Vue 3.
• angular: Angular 18+.
• lit: Lit 3.

2. Install Dependencies

Navigate into the new project directory and install its dependencies.

cd my-component
npm install

3. Start Dev Server

This opens the dev harness at http://localhost:5173. The server hot-reloads as you edit source files, so you can see changes in real time without restarting.

npm run dev

4. Build for Production

This creates a production-ready .tar.gz archive in the dist/ directory, ready to upload to Unqork.

npm run build:prod

Project Structure

Every BYO project scaffolded by the SDK has the following file structure:

my-component/
├── package.json          # includes "byo" metadata field
├── vite.config.ts        # Vite configuration with byoPlugin
├── tsconfig.json         # TypeScript configuration
├── manifest.json         # component/event descriptors
├── src/
│   ├── entry.ts          # bundle entry — exports all components
│   ├── MyComponent.ts    # component implementation
│   ├── MyComponent.test.ts
│   └── MyComponent.mocks.ts  # dev harness mock scenarios
└── dist/                 # build output
    ├── my-component.js
    ├── manifest.json
    └── my-component.tar.gz

Configuration

The byo Field in package.json

The SDK reads its configuration from a byo field in package.json. The following example displays all available fields:

{
  "name": "my-component",
  "version": "1.0.0",
  "byo": {
    "name": "my-component",
    "main": "my-component.js",
    "framework": "react",
    "componentName": "MyComponent",
    "runtimeVersion": "1.0.0",
    "description": "A custom button component"
  }
}

Vite Configuration

The SDK provides a Vite plugin that handles BYO-specific bundling:

import { defineConfig } from 'vite'
import { byoPlugin } from '@unqork/byo-sdk'

export default defineConfig({
  plugins: [byoPlugin()],
})

You can extend the base configuration:

export default defineConfig({
  plugins: [
    byoPlugin({
      build: { sourcemap: true },
      rollupOptions: {
        output: { manualChunks: undefined }
      }
    })
  ],
  resolve: {
    alias: {
      '@': '/src'
    }
  }
})

Development Workflow

1. Create Component

Build your component using web standards or your preferred framework. All components must extend HTMLElement or use a framework wrapper to become a custom element.

See Building Components for detailed implementation patterns and framework-specific examples.

2. Run Dev Server

Test your component against different mock scenarios in the browser at http://localhost:5173. The dev harness displays a callback log panel and reloads on file changes.

npm run dev

3. Build for Production

When your component is ready to upload, run the following command to create the production bundle.

npm run build:prod

The build runs the following steps:

1. Bumps the patch version.
2. Bundles source code.
3. Generates manifest.json.
4. Creates .tar.gz archive.

Note: Use npm run build for development builds without version bumping.

The build also runs the following validation checks:

• Manifest schema is valid.
• All components in manifest have corresponding exports.
• Each export has view and model functions.

Adding More Components

To add another component to an existing project, run the following command. Replace DatePicker with the name of your new component in PascalCase.

npx byo generate component DatePicker

The command creates the following:

• src/DatePicker.ts — file extension varies by framework.
• src/DatePicker.test.ts — test file for the new component.
• src/entry.ts — updated with the new export.

To generate a new event type for a component, run the following command. Replace ItemSelected with your event name in PascalCase.

npx byo generate event ItemSelected

This appends a new event type to src/<ComponentName>.events.ts, or creates the file if it does not exist.

Environment Variables

The dev server reads a .env file in your project root and injects any variables prefixed with BYO_* into your component code. Create a .env file with the following format:

# .env
BYO_API_URL=https://api.example.com
BYO_FEATURE_FLAG=true

Access the following variables in your component code using process.env:

const apiUrl = process.env.BYO_API_URL

The dev server injects only BYO_* variables. For production, use CI/CD environment variables.

TypeScript Support

The SDK includes complete type definitions:

import type {
  ByoComponentExport,
  ByoEventExport,
  ManifestSchema,
} from '@unqork/byo-sdk'

const myComponent: ByoComponentExport = {
  view: async () => MyComponentElement,
  model: async () => MyComponentModel,
}

TypeScript is the default and recommended option. JavaScript is supported through the --js flag:

npx --package=./sdk.tgz create my-component --framework react --js

Linting and Formatting

Scaffolded projects include ESLint and Prettier. To lint your project, run the following command:

npm run lint

Both configurations are shareable and extensible. To add custom rules, update your eslint.config.js as follows:

// eslint.config.js
import { byoEslintConfig } from '@unqork/byo-sdk/lint'

export default [
  ...byoEslintConfig(),
  {
    rules: {
      // Your custom rules
    }
  }
]

Preview Production Build

To verify the final bundle before uploading to Unqork, build and open it in the dev harness:

npm run build:prod
npm run preview

This serves dist/ in the same harness used by npm run dev.

Next Steps

• Building Components — step-by-step guide.
• CLI Reference — complete command documentation.
• Testing Guide — testing strategies and utilities.

npx byo version
# Output: @unqork/byo-sdk v1.2.3