README.md

English | 中文

Lingjie (零界)

Documentation

Background

Currently, most micro-frontend frameworks aim to decouple web apps by any scale of sections as desired. It enables to split of complex features or shared areas out of the app and lets them develop and deploy independently. However, in the case of decoupling pages, the extra overhead is unavoidable; sometimes, the cost is too high for medium and large apps to adopt these frameworks. We wish to organize multiple apps with simple, low-cost, and modified existed apps as little as possible.

Introduction

Lingjie (means zero boundary) is a zero-cost way to implement micro-frontend. It enables users to switch different apps back and forth smoothly without page refreshing, just like SPA, and simulates the switch effect of web view in the native app.

Lingjie, in contrast, concentrates on decoupling page dimensions and integrates multiple apps with nearly zero cost. Moreover, apps would not bind into lingjie in depth. All apps could freely connect and disconnect lingjie micro-frontend at any time.

Use case

• Apps integration. Integrate multiple medium and large apps. Refactor is not needed at all.

• MPA optimization. Solving white flickering problems when switching pages among MPA.

• H5 enhancement. Taking advantage of framework mechanism to get transition effect with very low cost.

Features

• 🔨 No need to rewrite existing app

  • Technology agnostic, no worries about the difficulty of development.

• 🔌 Only one line of code is needed

  • Every web page only needs to import one script file to join the lingjie micro-frontend.

• ⚡️ Switch page without refreshing

  • Users could switch different web pages back and forth without refreshing and get consistent UX via lingjie.

• 💪 Safe and strong

  • Every web page can disconnect lingjie micro-frontend at any time.

• 🚀 State synchronization

  • Refreshing page will not lose its routing state. All web pages could remain in their original state, such as scroll bar position, and show rapidly when back to the previous page.

• ☔ Perfect isolation

  • Lingjie isolates both styles and scripts perfectly and avoids namespace pollution among different pages.

Demo

As shown above, home Page, page A, page B, and page C are four different vanilla HTML, representing four separate apps. The transition effect is not made by traditional SPA (like TransitionGroup component in React or Vue). Lingjie mechanism entirely powers it.

How lingjie Works

All apps that join lingjie micro-frontend will load in iframes.

Lingjie, as a shell, manages loading and switching iframes via a microapp-shell.

Thus, every page that wants to connect with lingjie must import a script to redirect to shell, and then these pages will load in the iframe and be managed by lingjie.

Therefore, lingjie micro-frontend contains two parts:

• One is the shell. A regular HTML file will become a shell if it imports lingjie-shell script. Don't forget to define the path rules that allow connecting lingjie micro-frontend and related actions in the shell.

• The other is the pages that joined lingjie micro-frontend. Once a page imports the lingjie-page script, it will redirect to the lingjie micro-frontend whenever it loads.

Read more on documentation

Quick Start

Initialization

mkdir micro-frontend

cd ./micro-frontend

Create lingjie-shell

Create a folder to place lingjie-shell. Lingjie-shell will load each page in the iframe individually. All related operations about the iframe, such as loading, switching, and destroying, will take place in this shell.

Create lingjie folder

mkdir lingjie

cd ./lingjie

Create entry file index.html

touch index.html

Import lingjie-shell script in the entry file, then this file will become the shell. Next, configure the __lingjie_shell_config__ variable in the shell to define the path rules that allow connecting lingjie micro-frontend and related actions. Please note that the __lingjie_shell_config__ configuration should place before importing the lingjie-shell script. Following is the demonstration. About lingjie rule.

<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8" />
  <meta http-equiv="X-UA-Compatible" content="IE=edge" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Lingjie Microapp Shell</title>
  <style>
    * {
      margin: 0;
      padding: 0;
    }
  </style>
</head>

<body>
  <script>
    // lingjie rule
    window.__lingjie_shell_config__ = {
      rules: [
        {
          "test": "/demo(/.+)?",
          "timeout": 5000,
          "backAction": "reload",
          "disabled": false
        }
      ]
    }
  </script>
  <!-- import lingjie-shell script -->
  <script src="https://unpkg.com/lingjie/dist/shell/lingjie-shell.umd.js"></script>
</body>

</html>

Connect with lingjie-shell

Now, lingjie-shell is ready, creating apps connect with lingjie-shell next. Following is the demonstration.

Change the directory to one level up

cd ..

Create demo folder

mkdir demo

cd ./demo

Creating index.html, projectA.html, and projectB.html. index.html is the entry file of the demo. projectA.html and projectB.html represent two different apps.

touch index.html projectA.html projectB.html

Copy the following code to index.html, projectA.html, and projectB.html separately. Modify the title and content correspondingly. Please note we import lingjie-page script here, which let the app redirect to lingjie-shell.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <!-- modify the title correspondingly -->
  <title>index</title>
  <!-- import lingjie-page script -->
  <script src="https://unpkg.com/lingjie/dist/page/lingjie-page.umd.js"></script>
</head>
<body>
  <li>
    <a href="/demo/index.html">go to index</a>
  </li>
  <li>
    <a href="/demo/projectA.html">go to project A</a>
  </li>
  <li>
    <a href="/demo/projectB.html">go to project B</a>
  </li>
  <!-- modify the content correspondingly -->
  <h1>This is index page</h1>
</body>
</html>

File structure

micro-frontend
  |-demo
    |-index.html
    |-projectA.html
    |-projectB.html
  |-lingjie
    |-index.html

Check the Effect

Install npx, skip this step if it's installed already.

npm install -g npx

Create a static HTTP server at port 8080

npx http-server -p 8080

Open http://localhost:8080/demo in the browser. Pages should switch without refreshing when click go to index, go to project A or go to project B.

---

Issues / Pull Requests / Contributions are welcomed!