Skip to content

Tutorial UI Packs

Jump to bottom
Adrian Burlacu edited this page Feb 2, 2026 · 2 revisions

Tutorial: Developing UI Packs

This tutorial covers developing, bundling, and deploying UI applications as Stark packs that run in browser nodes.

Overview

Stark Orchestrator can deploy UI applications to browser nodes, treating them as managed workloads just like server-side processes. This enables:

  • Versioned UI deployments
  • Instant rollbacks
  • Coordinated frontend/backend releases
  • Unified observability

Prerequisites

  • Stark Orchestrator running
  • Node.js 20+
  • pnpm 9+
  • Basic Vue/Nuxt knowledge (for the examples)

Part 1: Creating a Nuxt UI Pack

Step 1: Initialize a Nuxt Project

# Create new Nuxt project
pnpm create nuxt my-ui-pack
cd my-ui-pack
pnpm install

Step 2: Configure for Static Bundle

Edit nuxt.config.ts:

export default defineNuxtConfig({
  // Disable server-side rendering
  ssr: false,
  
  // Generate static files
  nitro: { 
    preset: 'static' 
  },
  
  // Vite bundling configuration
  vite: {
    build: {
      // Inline assets under 100KB as base64
      assetsInlineLimit: 100 * 1024,
      
      rollupOptions: {
        output: {
          // Disable code splitting - single bundle
          inlineDynamicImports: true,
          manualChunks: undefined,
        },
      },
    },
  },
})

Step 3: Create Your UI

Edit pages/index.vue:

<template>
  <div class="container">
    <h1>My Stark UI Pack</h1>
    <p>Version: {{ version }}</p>
    <p>Deployed at: {{ deployedAt }}</p>
    
    <button @click="count++">
      Count: {{ count }}
    </button>
  </div>
</template>

<script setup lang="ts">
const version = '1.0.0'
const deployedAt = new Date().toISOString()
const count = ref(0)
</script>

<style scoped>
.container {
  max-width: 600px;
  margin: 0 auto;
  padding: 2rem;
  text-align: center;
}

button {
  padding: 1rem 2rem;
  font-size: 1.2rem;
  cursor: pointer;
}
</style>

Step 4: Bundle the Pack

# From the Nuxt project directory
node packages/cli/dist/index.js pack bundle . --out ./ui-bundle.js

Step 5: Register for Browser Runtime

node packages/cli/dist/index.js pack register ./ui-bundle.js \
  --name my-ui-pack \
  --ver 1.0.0 \
  --runtime browser

Part 2: Deploying to Browser Nodes

Understanding Browser Nodes

Browser nodes are browsers that have:

  1. Loaded the Stark browser runtime adapter
  2. Connected to the orchestrator via WebSocket
  3. Registered their capabilities

Deploying the UI Pack

# Deploy to a specific browser node
node packages/cli/dist/index.js pod create \
  --pack my-ui-pack \
  --node browser-node-1

# Or deploy to all browser nodes with a label
node packages/cli/dist/index.js deployment create ui-deployment \
  --pack my-ui-pack \
  --replicas 0 \
  --node-selector runtime=browser

Part 3: Asset Handling

Inline Assets

For assets to work in bundled packs, they must be inlined:

// nuxt.config.ts
export default defineNuxtConfig({
  vite: {
    build: {
      // Increase limit for larger assets
      assetsInlineLimit: 100 * 1024, // 100KB
    },
  },
})

Using Images

Place images in assets/images/ and reference them:

<template>
  <img src="@/assets/images/logo.png" alt="Logo" />
</template>

The bundler will inline them as base64 data URIs.

CSS Handling

CSS is automatically extracted and inlined in the bundle.

<style>
/* Component styles are bundled automatically */
.my-class {
  color: blue;
}
</style>

Part 4: Version Management

Updating Your UI Pack

When you make changes:

# Update version in your code
# Then bundle and register new version
node packages/cli/dist/index.js pack bundle . --out ./ui-bundle-v2.js
node packages/cli/dist/index.js pack register ./ui-bundle-v2.js \
  --name my-ui-pack \
  --ver 2.0.0 \
  --runtime browser

Rolling Back

If the new version has issues:

node packages/cli/dist/index.js pod rollback <pod-id> --ver 1.0.0

Or update the deployment:

node packages/cli/dist/index.js deployment update ui-deployment --ver 1.0.0

Part 5: Best Practices

Bundle Size Optimization

Technique Impact
Minimize dependencies Smaller bundle
Use production builds Removes dev code
Compress images Smaller inline assets
Tree-shaking Removes unused code

Development Workflow

  1. Local development: Use pnpm dev for hot reload
  2. Build: Use pnpm generate to create static output
  3. Bundle: Use Stark CLI to create pack bundle
  4. Test: Deploy to a test browser node
  5. Release: Register with production version

Handling Environment-Specific Config

Use runtime configuration:

<script setup>
// Access runtime config
const config = useRuntimeConfig()
const apiUrl = config.public.apiUrl
</script>
// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      apiUrl: process.env.API_URL || 'https://localhost/api'
    }
  }
})

Example Project

See the complete example at examples/nuxt-pack.

TODO: Additional Documentation

Related Topics

Clone this wiki locally