or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

child-applications.mdcontext-utilities.mdframework-applications.mdindex.mdplugin-configuration.md
tile.json

child-applications.mddocs/

Child Applications

Child/sub-application functionality for lifecycle management and integration with framework applications.

Capabilities

Child Configuration

Configuration interface for child applications in a micro-frontends architecture.

/**
 * Configuration for child/sub-applications
 */
interface ChildConfig {
  /** Called before sub-application is mounted */
  mount?: (options?: LifecycleOptions) => Promise<void> | void;
  /** Called after sub-application is unmounted */
  unmount?: (options?: LifecycleOptions) => Promise<void> | void;
  /** Called during bootstrap phase (qiankun compatibility) */
  bootstrap?: (options?: any) => Promise<void> | void;
}

Lifecycle Options

Options passed to lifecycle methods containing container and custom properties.

/**
 * Options passed to lifecycle methods
 */
interface LifecycleOptions {
  /** DOM container element where the app will be mounted */
  container: Element;
  /** Additional custom properties from the framework */
  customProps?: Record<string, any>;
}

Configuration Helper

Helper function to define child configuration with optional function wrapper.

/**
 * Helper function to define child configuration
 * @param config - Child configuration object or function returning config
 * @returns Resolved child configuration
 */
function defineChildConfig(config: ChildConfig | (() => ChildConfig)): ChildConfig;

Usage Examples:

import { defineChildConfig } from '@ice/plugin-icestark/types';

// Basic lifecycle configuration
export const icestark = defineChildConfig({
  mount: (options) => {
    console.log('Child app mounting in container:', options?.container);
    // Initialize child app resources
  },
  unmount: (options) => {
    console.log('Child app unmounting from container:', options?.container);
    // Clean up child app resources
  },
});

// Advanced configuration with async operations
export const icestark = defineChildConfig(() => ({
  bootstrap: async (props) => {
    // Initialize shared libraries, global state, etc.
    await initializeSharedResources();
  },
  mount: async (options) => {
    const { container, customProps } = options || {};
    
    // Setup child app with custom properties
    if (customProps?.theme) {
      setTheme(customProps.theme);
    }
    
    // Perform mount operations
    await startChildApp(container);
  },
  unmount: async (options) => {
    // Cleanup operations
    await stopChildApp();
    clearGlobalState();
  },
}));

Child Runtime Behavior

The child runtime automatically handles:

  1. Container Detection: Identifies the correct DOM container for rendering
  2. Framework Compatibility: Supports both icestark and qiankun frameworks
  3. Lifecycle Management: Calls user-defined lifecycle methods at appropriate times
  4. Context Injection: Provides framework context data to child components
  5. Root Management: Handles React root creation and cleanup

Automatic Lifecycle Integration

The plugin automatically generates lifecycle functions that:

  • Call user-defined bootstrap, mount, and unmount methods
  • Handle React root creation and destruction
  • Manage compatibility with different micro-frontend frameworks
  • Set the library name in the global scope for icestark

Generated Lifecycle Functions

The plugin generates these functions automatically:

/**
 * Bootstrap lifecycle (qiankun compatibility)
 * Automatically generated - calls user's bootstrap method
 */
export async function bootstrap(props: any): Promise<void>;

/**
 * Mount lifecycle 
 * Automatically generated - handles React root creation and calls user's mount method
 */
export async function mount(props: any): Promise<void>;

/**
 * Unmount lifecycle
 * Automatically generated - handles React root cleanup and calls user's unmount method
 */
export async function unmount(props: any): Promise<void>;

Container Resolution

The child runtime resolves the rendering container in this order:

  1. qiankun single-spa mode: Uses or creates #ice-container within provided container
  2. Runtime options: Uses container from runtimeOptions if provided
  3. Props container: Uses container from mount props
  4. Default: Falls back to existing root if already mounted

Framework Context Integration

Child applications automatically receive framework context data through the FrameworkContext provider. This allows child apps to access:

  • Custom properties passed from the framework
  • Shared state and configuration
  • Communication mechanisms with the parent framework

Library Name Management

The plugin automatically:

  • Sets window.ICESTARK.library to the configured library name
  • Ensures the library name matches the UMD module configuration
  • Provides library identification for the icestark framework

Conditional Rendering

Child applications only render when:

  • Not already mounted (prevents duplicate mounting)
  • Not running in icestark framework without proper container
  • Not running in qiankun framework without proper setup

This prevents issues with multiple micro-frontend frameworks and ensures proper lifecycle management.