Garfish Micro Front-end Framework

Garfish is a micro front-end framework designed to compose multiple independently delivered applications into a single cohesive product.

Key capabilities include:

• Framework Agnostic: Supports any framework or technology system.
• Independent Lifecycle: Enables independent development, testing, and deployment of sub-applications.
• Pre-loading: Automatically records user loading habits to reduce application switching time.
• Dependency Sharing: Reduces package size and prevents repeated loading of dependencies.
• Multiple Instances: Ability to run multiple sub-applications on a single page simultaneously.
• Debugging Tools: Provides tools specifically for the micro front-end development experience.

Garfish is a micro-frontend framework designed to provide the essential capabilities needed to build micro-frontend systems. It allows you to combine multiple frontend applications (such as Vue, React, and Angular) into a single cohesive product with simple integration.

To begin using Garfish, you can follow the Quick Start or Getting Started guides available in the documentation.

Garfish is a micro-frontend solution designed to provide a Single Page Application (SPA) user experience with the flexibility of a Multi-Page Application (MPA). The architecture consists of three main layers:

1. Deployment Platform: Handles service discovery, registration, version control, gray releases, incremental upgrades, and dependency analysis to reduce redundant loading.
2. Framework Runtime: The core engine that manages application lifecycles, sandboxing, routing, and communication.
3. Debugging Tools: Tools to assist in the development and debugging of micro-frontend applications.

Garfish uses an SPA-based architecture where the host (main) application controls the rendering and destruction of sub-applications.

Garfish provides two primary sandbox isolation strategies to prevent sub-applications from polluting the global environment:

1. Snapshot Sandbox: Captures a snapshot of the current running environment (e.g., window variables) at a specific stage. When the application is deactivated, it compares the current state with the snapshot and restores the original state.
2. VM Sandbox: Uses a mechanism similar to Node.js's vm module to create a sandbox environment and execute code within it. This approach handles both style and DOM nodes and supports strict/non-strict modes.

Garfish prioritizes using Proxy for isolation and falls back to the Snapshot Sandbox in environments where Proxy is not supported.

In micro-frontend architectures, multiple independent applications are organized together. Without native isolation like iframe, conflicts such as global variable collisions and style conflicts can occur, leading to broken styles or non-functional features.

Garfish implements a sandbox mechanism to provide isolation between sub-applications. This mechanism must also support multi-instance scenarios, where multiple instances of the same sub-application can run simultaneously without interfering with each other.

To ensure correct routing within the micro-frontend environment, you must set the router's base (Vue 2) or history base (Vue 3) using the basename passed from the main application. It is strongly recommended to use the basename provided by Garfish rather than a hardcoded value to ensure synchronization between the main and sub-applications. Note that Garfish currently only supports sub-applications using history mode.

// Vue 2 Example
function newRouter(basename) {
  const router = new VueRouter({
    mode: 'history',
    base: basename,
    routes: [
      { path: '/home', component: Home },
    ],
  });
  return router;
}

// Vue 3 Example
function newRouter(basename) {
  const router = createRouter({
    history: createWebHistory(basename),
    base: basename,
    routes,
  });
  return router;
}

To allow your micro-app to run independently (outside of the Garfish host) for development and deployment, add a check for window.__GARFISH__ in your entry file.

// For React v16/v17
if (!window.__GARFISH__) {
  ReactDOM.render(
    <RootComponent
      basename={
        process.env.NODE_ENV === 'production' ? '/examples/subapp/react18' : '/'
      }
    />, document.getElementById("root"));
}

// For React v18
if (!window.__GARFISH__) {
  const container = document.getElementById('root');
  const root = createRoot(container!);
  root.render(
    <RootComponent
      basename={
        process.env.NODE_ENV === 'production' ? '/examples/subapp/react18' : '/'
      }
    />
  );
}

Garfish supports two types of application entry points. For cross-team collaboration and reduced communication costs, HTML entry type is highly recommended.

• HTML Entry Type:

  • Mimics the independent nature of an iframe (allowing independent development, testing, and deployment).
  • The loader parses the HTML, decomposes Script, Style, and Link tags, and hands them to the sandbox.
  • Requires the sub-application to provide a provider containing lifecycle Hooks for rendering and destruction to enhance performance via caching.
  • Unlike an iframe, it runs in the same document flow as the host to avoid UX fragmentation.

• JS Entry Type:

  • The loader provides a basic DOM container for the application to mount into.