@grasp-labs/ds-microfrontends-integration

A React library for integrating microfrontend applications. Built with TypeScript, Vite, and Tailwind CSS.

Installation

npm install @grasp-labs/ds-microfrontends-integration

Components

Vault

Components for managing secrets with JSON Schema-based forms.

React Components

import {
  VaultProvider,
  VaultInput,
  VaultSecretDialog,
} from "@grasp-labs/ds-microfrontends-integration";
import "@grasp-labs/ds-microfrontends-integration/styles.css";

<VaultProvider
  secretsList={secrets}
  schema={jsonSchema}
  generateSecret={async (data) => newSecret}
  updateSecret={async (secret) => updatedSecret}
  deleteSecret={async (id) => {}}
>
  <VaultInput name="apiKey" label="API Key" />
  <VaultSecretDialog isOpen={isOpen} onClose={handleClose} />
</VaultProvider>;

Translation

i18next-based translation system with dynamic resource loading.

import {
  TranslationProvider,
  useTranslation,
} from "@grasp-labs/ds-microfrontends-integration";

<TranslationProvider language="en">
  <App />
</TranslationProvider>;

function MyComponent() {
  const t = useTranslation();
  return <h1>{t("common.title")}</h1>;
}

Toast Notifications

Toast notification system for displaying temporary messages.

import {
  ToastProvider,
  useToast,
} from "@grasp-labs/ds-microfrontends-integration";

<ToastProvider>
  <App />
</ToastProvider>;

function MyComponent() {
  const { addToast, removeToast, clearToasts } = useToast();

  const showSuccess = () => {
    addToast({
      title: "Success",
      description: "Operation completed successfully",
      variant: "success",
      duration: 5000, // optional, defaults to 5000ms
    });
  };

  return <button onClick={showSuccess}>Show Toast</button>;
}

Schema Fields

Auto-generated form fields from JSON Schema.

import { SchemaFields } from "@grasp-labs/ds-microfrontends-integration";

<SchemaFields schema={jsonSchema} control={control} errors={errors} />;

Styling

The library requires styles from @grasp-labs/ds-react-components:

import "@grasp-labs/ds-microfrontends-integration/styles.css";

Microfrontend Configuration (/mf-common)

Standardized Module Federation configuration for remote microfrontend applications.

Basic Setup

// vite.config.ts
import {
  createMicrofrontendsBase,
  dsFederation,
} from "@grasp-labs/ds-microfrontends-integration/mf-common";
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { name } from "./package.json";

const MICROFRONTENDS_BASE = createMicrofrontendsBase(name);

export default defineConfig(({ mode }) => ({
  base: mode === "production" ? MICROFRONTENDS_BASE : "/",
  plugins: [react(), dsFederation(name)],
}));

Default exposes:

• "." → "./src/App" - Your main React component (not a full app with ReactDOM.render, just a component)
• "./navigationConfig" → "./src/navigationConfig" - Navigation configuration object of type NavigationConfig

App Component Example

Your src/App.tsx should export a React component with Routes, not render it:

// src/App.tsx
import { Routes, Route } from "react-router";
import { HomePage } from "./layouts/HomePage";
import { SettingsPage } from "./layouts/SettingsPage";
import { InternalPage } from "./layouts/InternalPage";

function App() {
  return (
    <Routes>
      <Route path="/" element={<HomePage />} />
      <Route path="/settings" element={<SettingsPage />} />
      <Route path="/internal" element={<InternalPage />} />
    </Routes>
  );
}

export default App;

Navigation Configuration Example

// src/navigationConfig.ts
import type { NavigationConfig } from "@grasp-labs/ds-microfrontends-integration/mf-common";

export const navigationConfig = {
  INDEX: {
    label: "Home",
    path: "/",
    icon: "database",
    type: "visible",
  },
  SETTINGS: {
    label: "Settings",
    path: "/settings",
    icon: "cogWheel",
    type: "visible",
  },
  INTERNAL: {
    label: "Internal Page",
    path: "/internal",
    type: "hidden",
  },
} satisfies NavigationConfig;

What it provides:

• Pre-configured Module Federation settings with standard shared dependencies (React, React Router, etc.)
• Automatic public path configuration for microfrontend deployment
• Type-safe navigation and route configuration helpers

Available utilities:

• dsFederation(name, overrides?) - Vite plugin for Module Federation
• createModuleFederationConfig(name, overrides?) - Generate config object
• COMMON_SHARED_DEPS - Shared dependency configuration
• Types: RouteConfig, NavigationConfig, MicrofrontendExposes

Shared Dependencies

Your microfrontend project must install compatible versions of these shared dependencies. Compatible versions are those that match the version ranges specified in this package's COMMON_SHARED_DEPS configuration:

| Dependency | Purpose | | ------------------------------------------- | ------------------------------------------------------------------------------------ | | react | UI library - singleton ensures one React instance across all microfrontends | | react-dom | React DOM renderer - must match React version | | react-router | Routing library - singleton required for React context to work across microfrontends | | @grasp-labs/ds-microfrontends-integration | This package - singleton required for React context to work across microfrontends |

These dependencies are configured as singletons to prevent multiple instances and ensure compatibility across the microfrontend architecture.

Development

Prerequisites: Node.js >= 22

npm install

Dev auth middleware

devAuthMiddleware provides an optional login page for local development and injects Authorization: Bearer <token> for backend calls when a token is available. Mount it before anything that proxies to your APIs so outbound requests receive the token automatically.

import express from "express";
import { devAuthMiddleware } from "@grasp-labs/ds-microfrontends-integration/dev";

const app = express();

app.use(devAuthMiddleware());

// Or with custom options:
app.use(
  devAuthMiddleware({
    loginPagePath: "/__login", // Path for the login page
    afterLoginRedirectPath: "/", // Where to redirect after login
    authServerLoginUrl: "https://auth-dev.grasp-daas.com/rest-auth/login/", // Auth server endpoint
  }),
);

The login page is available at /__login (configurable via loginPagePath). Navigate there manually when you need to authenticate. Alternatively, set DEV_AUTH_TOKEN (env var or .env file) before starting the server to skip the login form entirely.

After a successful login, the middleware redirects to process.env.VITE_BASE_PATH when set, otherwise / (override via afterLoginRedirectPath if needed).

Scripts

• npm run build - Build the library
• npm run dev - Build in watch mode
• npm run storybook - Run Storybook dev server
• npm run build-storybook - Build Storybook static files
• npm run lint - Run ESLint
• npm run lint:fix - Fix ESLint errors
• npm run format - Format code with Prettier
• npm run format:check - Check code formatting
• npm test - Run tests
• npm run test:watch - Run tests in watch mode
• npm run test:coverage - Generate test coverage report

Project Structure

src/
├── components/        # React components (vault, translation, schema fields, etc.)
├── hooks/             # Custom React hooks
├── lib/               # JSON schema utilities and shared logic
├── types/             # TypeScript type definitions
├── utils/             # Shared helper functions
├── mf-common.ts       # Microfrontend configuration utilities
└── index.ts           # Main entry point

Contributing

1. Create a feature branch
2. Ensure npm test, npm run lint, and npm run format:check pass
3. Create a pull request