CLI Reference - BYO SDK

The BYO SDK provides CLI tools and npm scripts for the full development lifecycle:

• create: Scaffold new projects.
• npm scripts: Dev server, builds, and preview.
• byo: Validation, code generation, and version bumping.

Project Scaffolding

Scaffold a new BYO project from a template using the create command.

Usage

# Interactive mode (prompts for options)
npx --package=./sdk.tgz create

# Non-interactive mode
npx --package=./sdk.tgz create <name> [options]

Arguments

Options

Examples

# Interactive — prompts for framework, language, CSS framework, etc.
npx --package=./sdk.tgz create

# Vanilla + TypeScript with PostCSS (default)
npx --package=./sdk.tgz create my-button --framework vanilla --ts

# React + TypeScript with PostCSS
npx --package=./sdk.tgz create my-component --framework react --ts --css-option postcss

# React + TypeScript with Plain CSS (no preprocessing)
npx --package=./sdk.tgz create my-component --framework react --ts --css-option plain

# React + JavaScript with custom component name
npx --package=./sdk.tgz create my-react-component --framework react --js --component-name MyReactComponent

# Preview without writing files
npx --package=./sdk.tgz create my-component --framework vue --ts --dry-run

Output Structure

<name>/
├── package.json          # includes "byo" metadata field
├── vite.config.ts        # Vite configuration with byoPlugin
├── postcss.config.js     # PostCSS configuration (if --css-option postcss)
├── tsconfig.json         # TypeScript configuration (if --ts)
├── manifest.json         # component/event descriptors
├── src/
│   ├── entry.ts          # bundle entry — exports all components
│   ├── <ComponentName>.ts
│   ├── <ComponentName>.css    # component styles
│   ├── <ComponentName>.test.ts
│   ├── <ComponentName>.mocks.ts
│   └── shared.css        # shared styles (if --css-option postcss)
└── .env.example          # environment variable template

CSS Framework Options

The --css-option flag determines how styles are processed:

PostCSS (default):

• Supports modern CSS features like nesting, mixins, and custom properties.
• Compiles to standard CSS for broad browser support.
• Includes postcss.config.js and shared.css for reusable styles.
• Recommended for most projects.

Plain CSS:

• No preprocessing or build-time transformations.
• Traditional CSS with no additional dependencies.
• Suitable for simple styling needs or minimal build complexity.
• Styles are imported as raw strings and injected into Shadow DOM.

For detailed styling guidance, see the Styling Guide.

npm Scripts

Scaffolded projects include the following npm scripts for development and builds:

npm run dev

Start the development server with hot module reload and the host simulation harness.

npm run dev

What it does:

1. Reads the .env file and injects BYO_* variables.
2. Starts the Vite dev server with hot module reload.
3. Serves the host simulation harness.
4. Opens the browser at http://localhost:5173.
5. Auto-reloads on file changes.

Dev Harness Features:

• Scenario drop-down: Switch between mock scenarios defined in *.mocks.ts.
• Props panel: Shows current prop values.
• Commands panel: Dispatch command events with test payloads.
• Callback log: Logs all callback invocations with payloads.
• Console integration: Callback events also logged to browser console.

Environment Variables:

Create a .env file in the project root:

BYO_API_URL=https://api.example.com
BYO_FEATURE_FLAG=true
BYO_DEBUG=true

Only variables prefixed with BYO_ are injected. Access in code:

const apiUrl = process.env.BYO_API_URL

npm run build

Build for development (no version bump).

npm run build

What it does:

1. Bundles the source code with Vite.
2. Generates dist/manifest.json.
3. Does not bump the version.

When to use:

• Testing the build locally.
• Verifying the bundle without changing the version.

npm run build:prod

Build for production with automatic version bumping.

npm run build:prod

What it does:

1. Bumps the patch version in package.json.
2. Bundles the source code with Vite.
3. Generates dist/manifest.json.
4. Creates dist/<assetName>.tar.gz.

Output Structure:

dist/
├── <assetName>.js        # bundled component code
├── manifest.json         # platform manifest
└── <assetName>.tar.gz    # upload artifact

When to use:

• Building for production upload.
• Ready to deploy a new version.

npm run preview

Serve the production build in the dev harness.

npm run preview

What it does:

1. Serves files from dist/ without rebuilding.
2. Opens the dev harness at http://localhost:4173.
3. Loads the production bundle with mock scenarios.

Differences from npm run dev:

• Serves the minified production bundle.
• Does not watch for file changes.
• Does not inject environment variables.

When to use:

• Verifying the production bundle works correctly after building.
• Running a final check on file size, performance, and errors before uploading.

npm test

Run unit tests.

npm test

Runs all *.test.ts files using Vitest.

npm run lint

Lint source code.

npm run lint

Runs ESLint on src/ directory.

npm run typecheck

Type-check TypeScript code without emitting files.

npm run typecheck

What it does:

• Runs tsc --noEmit to verify type correctness.
• Reports type errors without generating output files.
• Automatically runs before build and build:prod.

When to use:

• Verifying types without building.
• Getting fast feedback during development.
• Running type validation in CI/CD.

Note: Only available in TypeScript projects scaffolded with --ts.

Code Generation

Add a new component, event, or command to an existing project using the byo generate command.

Usage

npx byo generate <type> <name> [options]

Arguments

Options

Generate Component

npx byo generate component DatePicker

The command creates the following:

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

The file extension is inferred from the following:

• Project framework (react → .tsx or .jsx).
• Presence of tsconfig.json (TypeScript → .ts or .tsx).

Generate Event

npx byo generate event ItemSelected

Appends a new event definition to src/<ComponentName>/<ComponentName>.schema.ts:

import { z } from 'zod'

export const ItemSelectedEvent = z.object({
  // Define event payload shape
})

export type ItemSelectedEvent = z.infer<typeof ItemSelectedEvent>

Generate Command

npx byo generate command Reset

Adds a command definition to src/<ComponentName>.schema.ts:

import { defineCommand } from '@unqork/byo-sdk/schema'

const resetSchema = z.object({
  silent: z.boolean().optional(),
})

export const resetDefinition = defineCommand({
  name: 'Reset',
  type: 'reset',
  description: 'Reset component to initial state',
  schema: resetSchema,
})

The command is automatically added to the component's commands array and exported from entry.ts.

What happens:

• Platform triggers containing BYOC Execute outputs can dispatch the command.
• Command events are named by type, like reset.
• Your component listens using addEventListener('reset', handler).

Examples

# Generate a new component
npx byo generate component TaskCard

# Generate an event
npx byo generate event TaskCompleted

# Generate a command
npx byo generate command Reset

# Preview without writing
npx byo generate component Calendar --dry-run

SDK Version

Display the installed SDK version using the byo version command.

Usage

npx byo version

Example

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

Global Options

All byo commands support the following options:

Typical Workflows

Development Workflow

# Scaffold project
npx --package=./sdk.tgz create my-component --framework react --ts
cd my-component
npm install

# Start dev server
npm run dev

# Edit files, see changes in browser

# Add more components
npx byo generate component SecondComponent

# Run tests
npm test

Build and Deploy Workflow

# Build for production
npm run build:prod

# Preview production bundle
npm run preview

# Upload dist/my-component.tar.gz to Unqork

Troubleshooting

Dev Server Won't Start

Problem: Dependencies not installed

Solution:

npm install
npm run dev

Port Already in Use

Problem: Error: listen EADDRINUSE: address already in use

Solution: Vite will automatically try the next available port. Check the console output for the actual port being used.

Build Fails with TypeScript Errors

Problem: error TS2304: Cannot find name 'X'

Solution:

1. Check that tsconfig.json includes your source directory.
2. Install missing type definitions: npm install -D @types/X.
3. Ensure imports are correct.

Next Steps

• Building Components — step-by-step guide.
• Testing Guide — testing strategies.
• SDK Overview — SDK features and configuration.