Skip to content

Tutorial Writing a Pack

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

Tutorial: Writing a Pack

This tutorial covers how to write, bundle, and deploy packs for Stark Orchestrator, from simple scripts to complex applications.

What is a Pack?

A pack is a self-contained JavaScript bundle that can be deployed to any Stark node. Packs can be:

  • Simple scripts
  • API servers
  • Workers and processors
  • UI applications (for browser nodes)

Pack Requirements

Packs must be:

  1. Self-contained: All dependencies bundled
  2. Versioned: Semantic versioning required
  3. Runtime-targeted: Specify node or browser

Tutorial 1: Simple Script Pack

Create the Source

Create counter.js:

// counter.js - A simple counter that runs for 10 iterations
let count = 0;
const interval = setInterval(() => {
  count++;
  console.log(`Count: ${count}`);
  
  if (count >= 10) {
    clearInterval(interval);
    console.log('Counter complete!');
  }
}, 1000);

Bundle and Register

# Bundle
node packages/cli/dist/index.js pack bundle ./counter.js --out ./counter-bundle.js

# Register
node packages/cli/dist/index.js pack register ./counter-bundle.js \
  --name counter \
  --ver 1.0.0 \
  --runtime node

Deploy

node packages/cli/dist/index.js pod create --pack counter --node my-node

Tutorial 2: Pack with Dependencies

For packs that use npm packages, the bundler will resolve and include them.

Create the Source

Create a project structure:

my-pack/
├── package.json
├── src/
│   └── index.js

package.json:

{
  "name": "my-pack",
  "version": "1.0.0",
  "main": "src/index.js",
  "dependencies": {
    "lodash": "^4.17.21"
  }
}

src/index.js:

const _ = require('lodash');

const data = [1, 2, 3, 4, 5];
const sum = _.sum(data);
console.log(`Sum of ${data.join(', ')} = ${sum}`);

Install and Bundle

cd my-pack
npm install  # or pnpm install

# Bundle from the project directory
node ../packages/cli/dist/index.js pack bundle ./src/index.js --out ./bundle.js

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

Tutorial 3: Long-Running Service Pack

For services that run continuously:

// api-server.js
const http = require('http');

const PORT = process.env.PORT || 3000;

const server = http.createServer((req, res) => {
  console.log(`${new Date().toISOString()} - ${req.method} ${req.url}`);
  
  if (req.url === '/health') {
    res.writeHead(200, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify({ status: 'healthy' }));
    return;
  }
  
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('Hello from Stark Pack!\n');
});

server.listen(PORT, () => {
  console.log(`Server listening on port ${PORT}`);
});

// Graceful shutdown
process.on('SIGTERM', () => {
  console.log('Received SIGTERM, shutting down...');
  server.close(() => {
    console.log('Server closed');
    process.exit(0);
  });
});

Bundling Web Applications

For Nuxt/Vue applications, special configuration is needed.

Requirements

Requirement Description
pnpm Project must use pnpm as package manager
Static output Must generate static HTML/JS/CSS (no SSR)
No code-splitting Disable dynamic imports (inlineDynamicImports: true)
Inline assets Assets must be inlined as base64 data URIs

Nuxt Configuration

nuxt.config.ts:

export default defineNuxtConfig({
  ssr: false,
  nitro: { preset: 'static' },
  vite: {
    build: {
      assetsInlineLimit: 100 * 1024, // 100KB - inline assets under this size
      rollupOptions: {
        output: {
          inlineDynamicImports: true,
          manualChunks: undefined,
        },
      },
    },
  },
})

See examples/nuxt-pack for a complete example.

Bundle Nuxt App

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

# Register for browser runtime
node packages/cli/dist/index.js pack register ./nuxt-bundle.js \
  --name my-nuxt-app \
  --ver 1.0.0 \
  --runtime browser

Pack Visibility

Control who can deploy your pack:

# Private (default) - only you can deploy
node packages/cli/dist/index.js pack register ./bundle.js \
  --name my-private-pack \
  --ver 1.0.0 \
  --runtime node

# Public - anyone can deploy
node packages/cli/dist/index.js pack register ./bundle.js \
  --name my-public-pack \
  --ver 1.0.0 \
  --runtime node \
  --visibility public

Versioning Best Practices

Semantic Versioning

Follow semver for pack versions:

  • MAJOR (1.0.0 → 2.0.0): Breaking changes
  • MINOR (1.0.0 → 1.1.0): New features, backward compatible
  • PATCH (1.0.0 → 1.0.1): Bug fixes

Version Commands

# List all versions of a pack
node packages/cli/dist/index.js pack versions my-pack

# Deploy specific version
node packages/cli/dist/index.js pod create --pack my-pack --ver 1.2.3

# Rollback to previous version
node packages/cli/dist/index.js pod rollback <pod-id> --ver 1.0.0

TODO: Additional Content

Related Topics

Clone this wiki locally