mini-star

Common errors

• Uncaught ReferenceError: React is not defined

  cause A plugin attempted to use `React` but it was not globally available or registered as a shared dependency with `mini-star`.
  fix Ensure `React` (and other global dependencies) are properly imported and then registered using `ministar.registerShared('react', React);` in the host application before any plugins are loaded.

• Error: Plugin 'my-plugin-name' not found or failed to load. (Network error, or script parsing error)

  cause The specified plugin script could not be fetched from the `base` URL or parsed correctly due to network issues, incorrect path, or syntax errors in the plugin bundle.
  fix Verify the `base` path in `MiniStar` configuration. Check the network tab in browser dev tools for 404s on the plugin URL. Ensure the plugin's bundle is correctly built and accessible at the expected location.

• TypeScript Error: Property 'render' does not exist on type 'Plugin'

  cause The loaded plugin object does not match the expected interface, often because the plugin itself does not correctly expose the `render` method or the TypeScript type assertion is incorrect.
  fix Ensure your plugin's entry file explicitly exports the `render` function (or whatever methods you expect). If using TypeScript, cast the loaded plugin to its specific interface: `await ministar.loadPlugin<MyPluginInterface>('my-plugin');`

Warnings

• gotcha Ensure all shared dependencies are registered with `ministar.registerShared()` *before* attempting to load any plugins that rely on those dependencies. Failing to do so will result in runtime errors within the plugin due to missing globals.
  Fix: Call `ministar.registerShared('dependencyName', dependencyObject);` for all common libraries (e.g., React, Vue, lodash) in your host application's initialization phase, prior to any `ministar.loadPlugin()` calls.
• gotcha Plugin path resolution can be tricky, especially when moving between development and production environments. Relative paths or incorrect `base` configuration in `MiniStar` can lead to 'Plugin not found' errors.
  Fix: Thoroughly test plugin loading paths. For production, consider using absolute URLs or a CDN-based `base` path in `MiniStar` configuration. Ensure your bundler outputs plugins to the expected location and that the host application can access them.
• breaking `mini-star` has moved towards a modern module approach. Older CommonJS `require()` patterns for the main `mini-star` library itself might not work as expected or could lead to compatibility issues in projects configured for ESM.
  Fix: Always use `import { ... } from 'mini-star';` for consuming the `mini-star` library in your host application. Ensure your project's build setup (e.g., Webpack, Rollup) correctly handles ESM.
• gotcha When a plugin fails to load or execute, `mini-star`'s default error handling might be generic. Implementing a custom `errorHandler` in `MiniStarConfig` is crucial for better diagnostics in production.
  Fix: Provide a custom `errorHandler` function in the `MiniStar` constructor options to log detailed information, capture stack traces, or report to an error monitoring service, enabling quicker debugging of plugin issues.

Install

• npm install mini-star npm
• yarn add mini-star yarn
• pnpm add mini-star pnpm

Imports

• MiniStar
  wrong:

  const MiniStar = require('mini-star');

  correct:

  import { MiniStar } from 'mini-star';

  The `MiniStar` class is the primary entry point for the runtime, enabling plugin loading and management. CommonJS `require` syntax is not recommended for modern usage and may lead to issues with ESM-only builds since v2.
• MiniStarConfig

  import type { MiniStarConfig } from 'mini-star';

  To ensure type safety when configuring the `MiniStar` instance, import `MiniStarConfig` for the configuration object. TypeScript types are shipped with the package.
• Plugin

  import type { Plugin } from 'mini-star';

  When defining or interacting with plugin structures, import the `Plugin` type to leverage TypeScript's type-checking capabilities for plugin interfaces.

Quickstart

This quickstart demonstrates how to initialize `mini-star`, register shared dependencies like React and ReactDOM, and dynamically load a plugin. It shows basic configuration, error handling, and how a plugin's exposed methods can be invoked.

import { MiniStar } from 'mini-star';

interface MyPluginInstance {
  render: (selector: string) => void;
  // ... other methods/properties exposed by the plugin
}

async function initializeMiniStar() {
  const ministar = new MiniStar({
    // Optional: Configure base path for plugins, e.g., for local development or CDN
    base: '/plugins/', 
    // Optional: Global error handler for plugin loading failures
    errorHandler: (error, pluginName) => {
      console.error(`Failed to load plugin ${pluginName}:`, error);
    }
  });

  // Register shared dependencies that plugins might use, preventing duplication
  // This should be done before loading plugins that depend on them.
  ministar.registerShared('react', window.React || require('react'));
  ministar.registerShared('react-dom', window.ReactDOM || require('react-dom'));
  console.log('Shared dependencies registered.');

  try {
    // Load a plugin by its registered name or path
    const myPlugin = await ministar.loadPlugin<MyPluginInstance>('my-plugin-entry');
    console.log('Plugin loaded successfully:', myPlugin);

    // Assume the plugin exports a render function
    if (myPlugin && typeof myPlugin.render === 'function') {
      myPlugin.render('#app-root');
      console.log('Plugin rendered to #app-root');
    }
  } catch (error) {
    console.error('Error during plugin loading or rendering:', error);
  }
}

// Ensure React and ReactDOM are available globally for demonstration if not bundled
// In a real app, these would be proper imports in your host application
(window as any).React = require('react');
(window as any).ReactDOM = require('react-dom');

initializeMiniStar();