Uniface Developing Shell

中文文档

Introduction:

In micro-frontend architectures based on iframes, development and debugging often face numerous challenges: frequent manual modification of iframe src, difficulty in managing multiple micro-applications, lack of a unified debugging entry, and so on. To address these issues, we have developed a development-period shell package specifically for front-end developers, which greatly simplifies the iframe-based micro-frontend development process and improves development efficiency.

Core Features:

• Menu-Driven Micro-Application Management:
  • Easily switch and manage multiple micro-applications through an intuitive menu interface.
  • Load the target micro-application with one click, without manually modifying the iframe src.
• Unified Development Entry:
  • Provide a unified development and debugging entry to facilitate centralized management and debugging of various micro-applications by developers.
  • Simplify development environment setup and reduce configuration complexity.
• Development-Period Specific:
  • This shell package is only used during the development and debugging phase and does not affect product building and release.
  • Remove the shell package from the production environment through simple configuration to ensure product purity.
• Convenient Function Switching:
  • Through the menu, you can easily switch each function, and quickly locate the function that needs to be debugged.

Usage Scenarios:

• Suitable for micro-frontend projects using the iframe architecture.
• Suitable for development scenarios that require frequent switching and debugging of multiple micro-applications.
• Suitable for teams that want to simplify development environment setup and improve development efficiency.

Advantages:

• Improve Development Efficiency:
  • Simplify micro-application management, reduce repetitive operations, and save development time.
• Optimize Development Experience:
  • Provide a unified development entry to facilitate centralized management and debugging by developers.
  • The intuitive menu interface improves the convenience of development and debugging.
• Reduce Maintenance Costs:
  • Development-period specific, does not affect product building and release, and reduces maintenance costs.

How to Use:

1. Integrate the shell package into your development environment.
2. Configure the micro-application menu and specify the entry address of each micro-application.
3. Start the development server, and select the target micro-application for debugging through the menu.

Summary:

This iframe-based micro-frontend development and debugging shell package is a powerful assistant for front-end developers during micro-frontend development. It can effectively improve development efficiency, optimize the development experience, and reduce maintenance costs. If you are developing an iframe-based micro-frontend, you may want to try this tool, and I believe it will bring you surprises!

Requirements

@ticatec/uniface-dev-shell declares svelte ^5.0.0 as a peer dependency, and expects the host app to separately provide:

• @ticatec/uniface-element ^5.0.0 — the shell's TopAppBar, Drawer, NavigatorMenu and HeaderLayout all come from it.
• Google Material Icons styles, from @ticatec/uniface-google-material-icons — the shell's menu toggle button renders an icon_google_menu icon, so google_material_icons.css must be loaded somewhere in the host app.

Usage

pnpm add -D @ticatec/uniface-dev-shell

The shell is meant to be mounted conditionally — only in development, and only when the page isn't already running inside an iframe — with your real production entry point taking over otherwise. The example below uses @ticatec/uniface-app-component's HomePage as that production entry point; swap in whatever your app actually uses.

+page.svelte文件示例

<script lang="ts">

    import "@ticatec/uniface-element/ticatec-uniface-web.css"
    import "@ticatec/uniface-google-material-icons/google_material_icons.css" // required by the shell's menu icon
    import "./app.css";
    import {onMount} from "svelte";

    // Production entry point and its own requirements — replace with your own.
    import HomePage from "@ticatec/uniface-app-component";
    import "@ticatec/uniface-app-component/uniface-app-component.css";
    import "@ticatec/uniface-icons/feather-style.css"
    import RestService, {ApiError} from "@ticatec/axios-restful-service";
    import {BaseDataService} from "@ticatec/app-data-service";
    import routes from "./routes";

    const isDev = import.meta.env.MODE == "development" || import.meta.env.DEV;
    const inFrame = window.frameElement !== null;
    let mainHome: any = $state();
    let params: any = $state();

    onMount(async () => {
        if (isDev && !inFrame) {
            mainHome = (await import('@ticatec/uniface-dev-shell')).default;
            params = {
                menu: (await import('./menu')).default,
                title: 'Uniface Application Components'
            }
        } else {
            let service = new RestService(window.location.origin, (ex: any) => {
                if (ex instanceof ApiError) {

                }
                return true
            });
            BaseDataService.setProxy(service);
            mainHome = HomePage;
            params = {
                routes
            }
        }
    });
</script>

{#if mainHome}
    {@const MainHome = mainHome}
    <MainHome {...params}/>
{/if}

Menu Configuration

The menu prop accepts a multi-level MenuNode[] structure. Each node has:

• item: leaf data — set href (the micro-app URL loaded into the iframe) and text (menu label)
• children: nested child nodes (for grouping)
• expand: whether the group is expanded by default

menu.ts example (multi-level):

import type {MenuNode} from "@ticatec/uniface-element/NavigatorMenu";

const menu: Array<MenuNode> = [
    {
        item: { text: "Card Showcase" },
        children: [
            { item: { text: "Card List", mod: "card", href: "/card" } },
            { item: { text: "Paged Cards", mod: "app", href: "/paged-cards" } }
        ],
        expand: true
    },
    {
        item: { text: "Form Center" },
        children: [
            {
                item: { text: "Basic Form" },
                children: [
                    { item: { text: "Text Input", href: "/form/text" } },
                    { item: { text: "Selector", href: "/form/select" } }
                ],
                expand: true
            },
            {
                item: { text: "Advanced Form" },
                children: [
                    { item: { text: "Validation", href: "/form/validate" } },
                    { item: { text: "Linkage", href: "/form/linkage" } }
                ],
                expand: false
            }
        ],
        expand: true
    }
];

export default menu;

Syncing navigation from inside the iframe

The shell keeps the outer address bar's hash in sync with whatever micro-app is loaded, so it can be refreshed, shared as a link, or navigated with the browser's back/forward buttons. That works automatically for navigation the shell itself initiates (menu clicks, hash changes), but if the micro-app inside the iframe navigates on its own (its own internal router, a redirect, etc.), it needs to tell the shell so the outer hash stays correct:

window.parent.postMessage({
  type: 'navigation',
  path: '/target/path'
}, window.location.origin);

• path should be in the same format as the href values in your menu.ts (an iframe-relative path, e.g. /form/text).
• This only updates location.hash in the shell — it does not reload the iframe, since the iframe is already there.
• The shell is a development-only tool that only ever runs same-origin, so it doesn't validate event.origin on the receiving end; don't rely on this message channel for anything beyond dev-time hash syncing.

Only leaf nodes with an href trigger an iframe reload when clicked; parent nodes act as collapsible groups, so you can nest as many levels as needed.