Aura microfrontend base

Description of aura-microfrontend-base, foundational component for the development of user interfaces in Aura ecosystem

Aura Virtual Assistant component

Introduction

aura-microfrontend-base is a foundational component that provides a common structure and libraries for the development of user interfaces in Aura ecosystem (Aura Virtual Assistant and ATRIA).

Its microfrontend component is a small, self-contained element that is part of a larger microfrontend architecture. It follows the same principles as microservices, but for the frontend, allowing independent development, deployment and scaling of different parts of a web application.

As defined before, this is a base component over which certain interfaces will be developed, but it will not be directly productized.

Technical foundations

This is a Next.js project bootstrapped with create-next-app.

The project leverages the following technologies and tools:

React: A JavaScript library for building user interfaces, used as the core framework for component development.
@telefonica/mistica: A design system and component library that provides a set of reusable UI components and styles, ensuring consistency and best practices in UI development.
Tailwind CSS: A utility-first CSS framework for styling components and layouts.
TypeScript: A strongly typed programming language that builds on JavaScript, ensuring type safety and better developer experience.
Microfrontend Architecture: Enables independent development, deployment, and scaling of frontend components.
Dynamic Imports: Used to load microfrontend components at runtime, improving modularity and performance.
Environment Variables: Configuration is managed through environment variables like AURA_SITE_CONFIG_PATH to ensure flexibility and adaptability across environments.

These foundations ensure scalability, maintainability, and a seamless developer experience.

Architecture and components

aura-microfrontend-base is composed of two main components:

Core Framework: The foundational Next.js structure that handles routing, rendering, and component lifecycle.
Dynamic Component Loader: The system responsible for loading and rendering components based on the site configuration.

Basic architecture diagram

sequenceDiagram
    participant Project as user request
    participant Config as site-config.json
    participant Pages as Page Manager
    participant Layout as Layout Engine
    participant ComponentLoader as Component Loader
    participant DOM as Browser DOM

    Project->>Config: read site configuration
    Config-->>Project: return site structure
    
    Note over Project: site path or default page
    Project->>Pages: setup page routes from config
    
    Pages->>Layout: process page layout configuration
    
    Layout->>Layout: setup container with containerClass
    Layout->>Layout: create grid with gridClass
    
    Note over Layout: process components by position
    
    loop for each component
        Layout->>ComponentLoader: request component by importType
        
        alt importType is "internal"
            ComponentLoader->>ComponentLoader: load from local components folder
        else importType is "external"
            ComponentLoader->>ComponentLoader: load from library dependency
        else importType is "microfrontend"
            ComponentLoader->>ComponentLoader: load dynamically from remote source
        end
        
        ComponentLoader-->>Layout: Return component
        Layout->>Layout: Apply className and position
        Layout->>Layout: Inject attributes and props
        Layout->>DOM: Render component in grid position
        DOM-->>Layout: Component rendered
    end
    
    Layout-->>Pages: Page layout rendered

    
    Pages-->>Project: page configured and route ready
    Project->>Project: start listening for navigation

Server features

The server component of aura-microfrontend-base provides:

Dynamic Routing: Routes are generated based on the configuration file and mapped to corresponding components.
Server-Side Rendering (SSR): Components can be rendered on the server for improved performance and SEO.
API Integration: Built-in capabilities for connecting to backend services and APIs.
Environment Variable Management: Configuration is handled through environment variables for different deployment environments.
Development Server: Local development environment with hot-reloading for a smooth development experience.

Configuration

The AURA_SITE_CONFIG_PATH environment variable must be set to point to your project’s configuration file, as in the example below:

AURA_SITE_CONFIG_PATH=site-config.json npm run dev

aura-microfrontend-base configuration file must be a valid JSON that defines the structure of the site, including the layout of the pages and the components to render.

The configuration file must follow this structure:

{
    "mainPage": "home",
    "pages": [
        {
            "id": "home",
            "name": "Home",
            "path": "/home",
            "layout": {
                "containerClass": "min-h-screen flex flex-col container mx-auto",
                "gridClass": "grid grid-cols-1 grid-rows-[200px_1fr] flex-1",
                "components": [
                    {
                        "library": "@telefonica/example-library",
                        "componentName": "Header",
                        "position": 1,
                        "importType": "external",
                        "className": "col-span-2 row-span-1"
                    },
                    {
                        "componentName": "TestComponent",
                        "position": 2,
                        "importType": "internal",
                        "className": "h-full col-span-1 row-span-2"
                    },
                    {
                        "componentName": "TestPlugin",
                        "position": 3,
                        "importType": "microfrontend",
                        "className": "h-full col-span-1 row-span-2",
                        "attributes": {
                            "API_ENDPOINT": "${AURA_MICROFRONTENDS_SERVER_HOST}/api/plugin-test",
                            "REFRESH_INTERVAL": "1000"
                        }
                    }
                ]
            }
        }
    ]
}

Configuration fields

mainPage: Default page ID to load when accessing the root path
pages: Array of page configurations
- id: Unique identifier for the page
- name: Display name of the page
- path: URL path for the page
- layout: Container configuration - containerClass: Tailwind classes for the main container - gridClass: Tailwind classes for the grid layout - components: Array of component configurations - library: (Optional) External library name - componentName: Name of the component to render - position: Order in the layout - importType: Type of component (internal, external, or microfrontend) - internal: Components that are part of the current project and are located in the components directory - external: Components from external libraries (like @telefonica packages) that are installed as dependencies - microfrontend: Components that are loaded dynamically from a remote server, allowing for runtime integration of independent applications - className: Tailwind classes for the component - attributes: (Optional) Additional component properties

Technical guidelines

Guides to manage the aura-microfrontend-base component: