⚙️

@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 ↗

安装

npm install @tuvix.js/core

快速开始

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.

MicroApp 接口

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>;
}

示例：错误边界

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';