Skip to content

Latest commit

 

History

History
227 lines (172 loc) · 9.4 KB

01-getting-started-host-app.md

File metadata and controls

227 lines (172 loc) · 9.4 KB

SCION Microfrontend Platform

SCION Microfrontend Platform Projects Overview Changelog Contributing Sponsoring

SCION Microfrontend Platform > Getting Started > Create Host Application

The host app provides the top-level integration container for microfrontends. It is the web app which the user loads into the browser that provides the main application shell, defining areas to embed microfrontends.

  • Project directory:
    scion-microfrontend-platform-getting-started/host-app
  • Installing modules (if not already done):
    npm run install
  • Starting the app:
    npm run start
  • Opening the app in the browser:
    http://localhost:4200
Prerequisites

If you checked out the skeleton branch of the Git repository for this guide, the directory structure should look like this. If not, please refer to How to complete this guide for step-by-step instructions.

   scion-microfrontend-platform-getting-started
   ├── host-app
   │   ├── src
   │   │   ├── index.html // HTML template
   │   │   ├── host.ts // TypeScript file
   │   │   └── host.scss // SASS stylesheet
   │   ├── package.json
   │   └── tsconfig.json

Follow the following instructions to get the host app running.

Install the SCION Microfrontend Platform

Run the following command to install the SCION Microfrontend Platform.

npm install @scion/microfrontend-platform @scion/toolkit rxjs@^7.5.0 --save

SCION Microfrontend Platform requires some tools of the module @scion/toolkit. By using the above command, those are installed as well.

Start the SCION Microfrontend Platform

  1. Open the TypeScript file host-app/src/host.ts.

  2. Start the platform by adding the following lines to the init method:

          import { MicrofrontendPlatformHost } from '@scion/microfrontend-platform';   

      public async init(): Promise<void> {
[+]     await MicrofrontendPlatformHost.start({
[+]       applications: [],
[+]     });
      }

    Lines to be added are preceded by the [+] mark.

    For now, we are only starting the platform. Later in this tutorial we will register the Products App and the Customers App so that they can interact with the platform.

Embed microfrontends

In this section, we will embed the ProductList Microfrontend and CustomerList Microfrontend.

  1. Open the HTML template host-app/src/index.html.

  2. Add three router outputs to the <main> element, as follows:

          <main>
[+]     <sci-router-outlet></sci-router-outlet>
[+]     <sci-router-outlet name="aside"></sci-router-outlet>
[+]     <sci-router-outlet name="bottom"></sci-router-outlet>
      </main>

    Note that we do not name the first outlet, so it acts as the primary outlet to display main content such as our products and customers. The second output we name aside to display secondary content, such as details about a product or customer. The last outlet we named bottom will display the SCION DevTools to inspect our application.

    A router outlet is a placeholder that the platform dynamically fills based on the current router state. Using the router, you can instruct an outlet to embed a microfrontend. By giving an outlet a name, you can reference it as the routing target. If not naming an outlet, its name defaults to primary. The concept of the router outlet is inspired by the Angular routing mechanism. For more information, refer to the Developer Guide.

  3. Add two navigation buttons to the <nav> element to open the ProductList Microfrontend and CustomerList Microfrontend, as follows:

          <nav>
[+]     <button id="products">Products</button>
[+]     <button id="customers">Customers</button>
      </nav>

  4. In the host controller host-app/src/host.ts, register a click event handler on the buttons and navigate the primary router outlet to the ProductList Microfrontend respectively to the CustomerList Microfrontend, as follows:

    [+]   import {MicrofrontendPlatformHost, OutletRouter} from '@scion/microfrontend-platform';
[+]   import {Beans} from '@scion/toolkit/bean-manager';        

      public async init(): Promise<void> {
        await MicrofrontendPlatformHost.start({
          applications: [],
        });

[+]     // Install navigation listeners
[+]     document.querySelector('button#products').addEventListener('click', () => {
[+]       Beans.get(OutletRouter).navigate('http://localhost:4201/product-list/product-list.html');
[+]     });

[+]     document.querySelector('button#customers').addEventListener('click', () => {
[+]       Beans.get(OutletRouter).navigate('http://localhost:4202/customer-list/customer-list.html');
[+]     });
      }

    We get a reference to the router using the bean manager. The router can be passed a URL and options to control navigation. In the above example, we do not pass any options, so the routing refers to the primary router outlet.

Open the app in the browser

We did it! Run npm run start to serve the applications.

When you open the page http://localhost:4200, you see:

  • two navigation buttons to open the ProductList Microfrontend and CustomerList Microfrontend in the primary router outlet
  • three router outlets as placeholder for routed content

So far, the microfrontends only display a header. In the next chapters we are going to implement the Products App and Customers App.

What we did in this chapter

We installed and started the SCION Microfrontend Platform and added router outlets to the host app HTML template to display microfrontends. When you click the Products button, the primary router outlet will display the ProductList Microfrontend, and when you click the Customers button, the CustomerList Microfrontend will open.

The host-app/src/index.html looks as following: 
<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Getting Started with SCION</title>
    <link rel="stylesheet" type="text/css" href="host.scss">
    <script type="module" src="./host.ts"></script>
  </head>
  <body>
    <nav>
      <button id="products">Products</button>
      <button id="customers">Customers</button>
    </nav>
    <main>
      <sci-router-outlet></sci-router-outlet>
      <sci-router-outlet name="aside"></sci-router-outlet>
      <sci-router-outlet name="bottom"></sci-router-outlet>
    </main>
  </body>
</html>
The host-app/src/host.ts looks as following: 
import {MicrofrontendPlatformHost, OutletRouter} from '@scion/microfrontend-platform';
import {Beans} from '@scion/toolkit/bean-manager';

class HostController {

  public async init(): Promise<void> {
    await MicrofrontendPlatformHost.start({
      applications: [],
    });

    // Install navigation listeners
    document.querySelector('button#products').addEventListener('click', () => {
      Beans.get(OutletRouter).navigate('http://localhost:4201/product-list/product-list.html');
    });

    document.querySelector('button#customers').addEventListener('click', () => {
      Beans.get(OutletRouter).navigate('http://localhost:4202/customer-list/customer-list.html');
    });
  }
}

new HostController().init();
What's next

In the next chapter, we will develop the Products App. Click here to continue.