--- title: "BYO SDK" slug: "byo-sdk" updated: 2026-10-07T18:37:20Z published: 2026-10-07T18:37:20Z canonical: "docs.unqork.io/byo-sdk" --- > ## 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. # BYO SDK The BYO SDK provides the tools needed to build, develop, test, and deploy custom components for the UnqorkAI platform. ## What Is 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](https://vitejs.dev)-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 Custom Assets Administration in the UnqorkAI platform. 1. Select **BYO SDK**. 2. Download the SDK package for the target 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. ```bash npx --package=./sdk.tgz create my-component --framework react --ts ``` To be prompted for all configuration options, run the command without arguments: ```bash npx --package=./sdk.tgz create ``` The `--framework` flag accepts the following values: - `vanilla`: Plain Web Components. - `react`: React with `@r2wc/react-to-web-component` bridge. - `vue`: Vue 3. - `angular`: Angular 19+. - `lit`: Lit 3. ### 2. Install Dependencies Navigate into the new project directory and install its dependencies. ```bash 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. ```bash npm run dev ``` ### 4. Build for Production This creates a production-ready `.tar.gz` archive in the `dist/` directory, ready to upload to Unqork. ```bash npm run build:prod ``` ## Project Structure Every BYO project scaffolded by the SDK has the following file structure: ```plaintext my-component/ ├── package.json          # includes "byo" metadata field ├── vite.config.ts        # Vite configuration with byoPlugin ├── tsconfig.json         # TypeScript configuration ├── src/ │   ├── entry.ts          # bundle entry — exports all components │   └── MyComponent/ │       ├── MyComponent.ts        # component implementation │       ├── MyComponent.schema.ts # component/event descriptors │       ├── MyComponent.css       # component styles │       ├── MyComponent.test.ts │       └── MyComponent.mocks.ts  # dev harness mock scenarios └── dist/                 # build output (generated)    ├── 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: ```json {  "name": "my-component",  "version": "1.0.0",  "byo": {    "name": "my-component",    "main": "my-component.js",    "framework": "react",    "runtimeVersion": "1.0.0",    "description": "A custom button component"  } } ``` | Field | Required | Description | | --- | --- | --- | | `name` | Yes | Unique asset identifier | | `main` | Yes | entry filename | | `framework` | Yes | `vanilla`, `react`, `vue`, `angular`, or `lit` | | `runtimeVersion` | No | BYO contract version (default: `"1.0.0"`) | | `description` | No | Human-readable description | ### Vite Configuration The SDK provides a Vite plugin that handles BYO-specific bundling: ```typescript import { defineConfig } from 'vite' import { byoPlugin } from '@unqork/byo-sdk/plugins' export default defineConfig({  plugins: [byoPlugin()], }) ``` You can extend the base configuration: ```typescript 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](/unqorkai/docs/building-components-byo-sdk) 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. ```bash npm run dev ``` ### 3. Build for Production When the component is ready to upload, run the following command to create the production bundle. ```bash 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. ```bash 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. ```bash 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: ```ini # .env BYO_API_URL=https://api.example.com BYO_FEATURE_FLAG=true ``` Access the following variables in your component code using `process.env`: ```typescript const apiUrl = process.env.BYO_API_URL ``` The dev server injects `BYO_*` variables. For production, use CI/CD environment variables. ## TypeScript Support The SDK includes complete type definitions: ```typescript 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: ```bash npx --package=./sdk.tgz create my-component --framework react --js ``` ## Linting and Formatting Scaffolded projects include ESLint and Prettier. To lint the project, run the following command: ```bash npm run lint ``` Both configurations are shareable and extensible. To add custom rules, update your `eslint.config.js` as follows: ```javascript // 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: ```bash npm run build:prod npm run preview ``` This serves `dist/` in the same harness used by `npm run dev`. ## Next Steps - [Building Components](/unqorkai/docs/building-components-byo-sdk) — step-by-step guide. - [CLI Reference](/unqorkai/docs/cli-reference-byo-sdk) — complete command documentation. - [Testing Guide](/unqorkai/docs/testing-guide-byo-sdk) — testing strategies and utilities. **SDK Version** The SDK version matches the platform release version. To check the current version, run the following command: ```bash npx byo version # Output: @unqork/byo-sdk v1.2.3 ``` **Changelog** | Date | Change | | --- | --- | | 2026-09-29 | Accuracy fixes: corrected project structure (component files live in src/MyComponent/ subdirectory; manifest.json is generated, not scaffolded), removed undocumented componentName from byo field table, fixed byoPlugin import to @unqork/byo-sdk/plugins (EN-8153). | | 2026-05-01 | Initial publication | OS (operating system) is the program that manages other application programs on your computer. AngularJS is a JavaScript framework added to an HTML page with a