⚙️

@tuvix.js/core

Core Orchestrator

The heart of Tuvix.js. Registers micro apps, manages their lifecycle (mount, unmount, update), and coordinates routing and sandboxing.

npm ↗ GitHub ↗

Installation

npm install @tuvix.js/core

Quick Start

import { createOrchestrator } from '@tuvix.js/core';

const orchestrator = createOrchestrator({ container: '#app' });

orchestrator.register('home', {
  entry: 'https://cdn.example.com/home.js',
});

orchestrator.register('dashboard', {
  entry: 'https://cdn.example.com/dashboard.js',
  props: { apiUrl: 'https://api.example.com' },
  sandbox: { css: true },
});

orchestrator.start();

API

createOrchestrator(options)

Creates the main orchestrator instance.

interface OrchestratorOptions {
  container: string | HTMLElement;
  onBeforeMount?: (app: RegisteredApp) => void | Promise<void>;
  onAfterMount?: (app: RegisteredApp) => void | Promise<void>;
  onError?: (error: Error, app: RegisteredApp) => void;
}

orchestrator.register(name, options)

Register a micro app.

interface AppOptions {
  entry: string | (() => Promise<string>);
  props?: Record<string, unknown>;
  container?: string | HTMLElement;
  sandbox?: { css?: boolean; js?: boolean };
}

orchestrator.mount(name, props?)

Manually mount a micro app.

await orchestrator.mount('dashboard', { userId: '42' });

orchestrator.unmount(name)

Manually unmount a micro app.

await orchestrator.unmount('dashboard');

orchestrator.update(name, props)

Update props of a mounted micro app.

await orchestrator.update('dashboard', { userId: '99' });

orchestrator.start()

Start the orchestrator. Integrates with the router if one is registered.

orchestrator.stop()

Stop the orchestrator. Unmounts all active micro apps and cleans up.

The MicroApp Interface

Your micro app bundle must export an object implementing this interface:

interface MicroApp {
  mount(container: HTMLElement, props?: Record<string, unknown>): Promise<void>;
  unmount(container: HTMLElement): Promise<void>;
  update?(container: HTMLElement, props?: Record<string, unknown>): Promise<void>;
}

Example: Error Boundaries

const orchestrator = createOrchestrator({
  container: '#app',

  onError(error, app) {
    console.error(`[${app.name}] crashed:`, error);

    // Render a fallback
    const container = document.querySelector(app.container as string);
    if (container) {
      container.innerHTML = `
        <div class="error-boundary">
          <p>Failed to load. <button onclick="location.reload()">Reload</button></p>
        </div>
      `;
    }
  },
});

TypeScript

import type { MicroApp, RegisteredApp, OrchestratorOptions } from '@tuvix.js/core';