@kaena1/ecomm-contained-utils 1.0.0

package/README.md

@@ -0,0 +1,681 @@
+# ecomm-contained-utils
+
+Shared utilities for loading and managing remote React components in Mint Mobile microfrontends.
+
+## Package Overview
+
+This package provides the essential infrastructure for dynamically loading remote React components (contained components) from external URLs into Next.js applications. It handles module loading, dependency resolution via import maps, and component rendering.
+
+### Key Features
+
+- **Dynamic Component Loading**: Load React components from remote URLs at runtime
+- **Import Map Management**: Automatic dependency resolution for React and React DOM
+- **Type-Safe**: Full TypeScript support with generated type definitions
+- **Optimized for CDN**: Preserves CDN cache and TTL through native ES modules
+- **Caching**: Built-in module caching to avoid redundant network requests
+
+## Package Structure
+
+```
+packages/ecomm-contained-utils/
+├── src/
+│   ├── components/          # React components
+│   │   ├── ImportMapScripts.tsx    # Injects import map for dependency resolution
+│   │   ├── RemoteLinks.tsx         # Preloads remote component resources
+│   │   └── RemoteRenderer.tsx      # Renders remote components ('use client')
+│   ├── hooks/               # React hooks
+│   │   └── useRemoteComponent.ts   # Hook for loading remote components ('use client')
+│   ├── services/            # Core services
+│   │   ├── fetchManifest.ts        # Fetches component manifests
+│   │   ├── ImportMapService.ts     # Generates import map JSON
+│   │   └── moduleLoader.ts         # ES module loader service
+│   ├── types/               # TypeScript definitions
+│   ├── index.ts             # Main entry point (exports everything)
+│   ├── server.ts            # Server-safe exports for App Router
+│   └── client.ts            # Client-only exports for App Router
+├── dist/                    # Built files (generated)
+├── vite.config.ts          # Build configuration
+├── package.json
+├── release.config.cjs      # Semantic Release configuration
+└── README.md
+```
+
+### Entry Points
+
+The package provides three entry points for different use cases:
+
+| Entry Point | Import Path | Use Case |
+|-------------|-------------|----------|
+| Main | `ecomm-contained-utils` | Everything (Pages Router, or when you need all exports) |
+| Server | `ecomm-contained-utils/server` | Server Components (App Router RSC) |
+| Client | `ecomm-contained-utils/client` | Client Components (App Router) |
+
+**Server exports:** `fetchManifest`, `ImportMapScripts`, `RemoteLinks`, `generateImportMap`, `generateImportMapJson`, all types
+
+**Client exports:** `RemoteRenderer`, `useRemoteComponent`, `moduleLoader`, `ModuleLoader`
+
+## Installation
+
+### In Consumer Applications (e.g., mm-mf-features)
+
+#### Option 1: Install Latest from POC (Recommended)
+
+Always get the latest version from the POC branch:
+
+```bash
+npm install ecomm-contained-utils@f-poc-EC-3301
+```
+
+This installs the latest version tagged with `f-poc-EC-3301`. You don't need to track specific version numbers.
+
+#### Option 2: Install Specific Version
+
+If you need a specific version:
+
+```bash
+npm install ecomm-contained-utils@1.25.0-f-poc-EC-3301.5
+```
+
+#### Updating to Latest
+
+To update to the latest POC version:
+
+```bash
+# Update and save to package.json
+npm install ecomm-contained-utils@f-poc-EC-3301 --save
+
+# Or use npm update (if version is already in package.json with the tag)
+npm update ecomm-contained-utils
+```
+
+#### For Local Development
+
+**⚠️ Important: Use npm pack instead of npm link**
+
+Due to React's requirement of a single instance, `npm link` causes "Invalid hook call" errors. Use `npm pack` instead:
+
+```bash
+# In the ecomm-contained-utils package
+cd packages/ecomm-contained-utils
+npm run build
+npm pack
+# This generates: ecomm-contained-utils-X.X.X.tgz
+
+# In the consumer application (mm-mf-features)
+npm install /absolute/path/to/ecomm-contained-utils-X.X.X.tgz
+```
+
+## Usage
+
+### 1. Setup in Next.js Application
+
+The setup differs slightly between Next.js Pages Router and App Router.
+
+#### Pages Router Setup
+
+##### Add Import Map Scripts to `_document.tsx`
+
+```typescript
+import { Html, Head, Main, NextScript } from 'next/document';
+import { ImportMapScripts } from 'ecomm-contained-utils';
+
+export default function Document() {
+  return (
+    <Html lang="en-US">
+      <Head>
+        {/* Required: Enables import map for dependency resolution */}
+        <ImportMapScripts />
+      </Head>
+      <body>
+        <Main />
+        <NextScript />
+      </body>
+    </Html>
+  );
+}
+```
+
+##### Fetch Remote Manifest in `_app.tsx`
+
+```typescript
+import type { AppProps, AppContext } from 'next/app';
+import {
+  RemoteRenderer,
+  RemoteLinks,
+  fetchManifest,
+} from 'ecomm-contained-utils';
+
+App.getInitialProps = async (ctx: AppContext) => {
+  const manifestUrl = `https://assets-qa.mintmobile.com/contained-components/manifest-poc/f-poc-live-update/manifest.json?_ts=${Date.now()}`;
+
+  let remoteManifest;
+  try {
+    remoteManifest = await fetchManifest(manifestUrl);
+  } catch (e) {
+    console.error('Failed to fetch manifest:', e);
+    remoteManifest = null;
+  }
+
+  const app = await (await import('next/app')).default.getInitialProps(ctx);
+  return {
+    ...app,
+    pageProps: {
+      ...app.pageProps,
+      remoteManifest,
+    },
+  };
+};
+
+export default function App({ Component, pageProps }: AppProps) {
+  const remoteManifest = pageProps?.remoteManifest;
+  const layoutManifest = remoteManifest?.components?.MintLayout;
+
+  return (
+    <>
+      <Head>
+        {/* Preload component resources */}
+        {layoutManifest && <RemoteLinks manifest={layoutManifest} />}
+      </Head>
+
+      {/* Render remote component as wrapper */}
+      {layoutManifest ? (
+        <RemoteRenderer
+          manifest={layoutManifest}
+          componentName="MintLayout"
+          autoLoad={true}
+          componentProps={{
+            config: { NEXT_PUBLIC_SITE_URL: process.env.NEXT_PUBLIC_SITE_URL },
+          }}
+        >
+          <Component {...pageProps} />
+        </RemoteRenderer>
+      ) : (
+        <Component {...pageProps} />
+      )}
+    </>
+  );
+}
+```
+
+#### App Router Setup
+
+> **Note:** App Router is fully supported. The package provides separate entry points for server and client code:
+> - `ecomm-contained-utils/server` - Server-safe exports (fetchManifest, ImportMapScripts, RemoteLinks, types)
+> - `ecomm-contained-utils/client` - Client-only exports (RemoteRenderer, useRemoteComponent, moduleLoader)
+
+##### Add Import Map Scripts to `app/layout.tsx`
+
+```typescript
+// Use /server for server components
+import {
+  ImportMapScripts,
+  RemoteLinks,
+  fetchManifest
+} from 'ecomm-contained-utils/server';
+
+// Use /client for client components (in separate 'use client' files)
+// import { RemoteRenderer } from 'ecomm-contained-utils/client';
+
+// Fetch manifest at build time
+async function getRemoteManifest() {
+  try {
+    const manifestUrl = `https://assets-qa.mintmobile.com/contained-components/manifest-poc/f-poc-live-update/manifest.json?_ts=${Date.now()}`;
+    return await fetchManifest(manifestUrl);
+  } catch (e) {
+    console.error('Failed to fetch manifest:', e);
+    return null;
+  }
+}
+
+export default async function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const remoteManifest = await getRemoteManifest();
+  const layoutManifest = remoteManifest?.components?.MintLayout;
+
+  return (
+    <html lang="en-US">
+      <head>
+        {/* Required: Enables import map for dependency resolution */}
+        <ImportMapScripts />
+
+        {/* Preload component resources */}
+        {layoutManifest && <RemoteLinks manifest={layoutManifest} />}
+      </head>
+      <body>
+        {layoutManifest ? (
+          <RemoteRenderer
+            manifest={layoutManifest}
+            componentName="MintLayout"
+            autoLoad={true}
+            componentProps={{
+              config: { NEXT_PUBLIC_SITE_URL: process.env.NEXT_PUBLIC_SITE_URL },
+            }}
+          >
+            {children}
+          </RemoteRenderer>
+        ) : (
+          children
+        )}
+      </body>
+    </html>
+  );
+}
+```
+
+### 2. Using Remote Components in Pages
+
+```typescript
+import { RemoteRenderer } from 'ecomm-contained-utils';
+
+export default function MyPage({ remoteManifest }) {
+  const pocComponentManifest = remoteManifest?.components?.PocComponent;
+
+  return (
+    <div>
+      <h1>My Page</h1>
+
+      {pocComponentManifest && (
+        <RemoteRenderer
+          manifest={pocComponentManifest}
+          componentName="PocComponent"
+          autoLoad={true}
+          componentProps={{
+            list: [
+              { id: 1, name: 'Item 1' },
+              { id: 2, name: 'Item 2' },
+            ],
+          }}
+        />
+      )}
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### Components
+
+#### `<ImportMapScripts />`
+
+Injects the import map script tags required for ES module dependency resolution.
+
+**Props:** None
+
+**Usage:**
+
+```tsx
+<Head>
+  <ImportMapScripts />
+</Head>
+```
+
+---
+
+#### `<RemoteLinks manifest={ComponentManifest} />`
+
+Preloads CSS and JS resources for a remote component.
+
+**Props:**
+
+- `manifest`: `ComponentManifest` - Component manifest with `bundleUrl` and optional `styleUrl`
+
+**Usage:**
+
+```tsx
+<RemoteLinks manifest={pocComponentManifest} />
+```
+
+---
+
+#### `<RemoteRenderer />`
+
+Renders a remote React component.
+
+**Props:**
+
+- `manifest`: `ComponentManifest` - Component manifest
+- `componentName`: `string` - Name of the component to extract from the module
+- `componentProps?`: `Record<string, unknown>` - Props to pass to the remote component
+- `autoLoad?`: `boolean` - Whether to auto-load on mount (default: `true`)
+- `placeholder?`: `ReactNode` - Content to show while loading
+- `errorFallback?`: `(error: string) => ReactNode` - Custom error UI
+- `children?`: `ReactNode` - Children to pass to the remote component
+
+**Usage:**
+
+```tsx
+<RemoteRenderer
+  manifest={manifest}
+  componentName="MyComponent"
+  autoLoad={true}
+  componentProps={{ title: 'Hello' }}
+  placeholder={<div>Loading...</div>}
+  errorFallback={(error) => <div>Error: {error}</div>}
+>
+  <ChildComponent />
+</RemoteRenderer>
+```
+
+---
+
+### Hooks
+
+#### `useRemoteComponent(options)`
+
+Hook for loading remote components with manual control.
+
+**Parameters:**
+
+- `options.manifest`: `ComponentManifest` - Component manifest
+- `options.componentName`: `string` - Component name
+- `options.autoLoad?`: `boolean` - Auto-load on mount (default: `true`)
+
+**Returns:**
+
+```typescript
+{
+  component: React.ComponentType | null,
+  manifest: ComponentManifest | null,
+  loading: boolean,
+  error: string | null,
+  loaded: boolean,
+  loadComponent: () => Promise<void>,
+  reload: () => Promise<void>,
+  clearError: () => void
+}
+```
+
+**Usage:**
+
+```tsx
+const {
+  component: Component,
+  loading,
+  error,
+} = useRemoteComponent({
+  manifest: pocManifest,
+  componentName: 'PocComponent',
+  autoLoad: true,
+});
+
+if (loading) return <div>Loading...</div>;
+if (error) return <div>Error: {error}</div>;
+if (!Component) return null;
+
+return <Component {...props} />;
+```
+
+---
+
+### Services
+
+#### `fetchManifest(manifestUrl: string): Promise<RemoteManifest>`
+
+Fetches and validates a remote component manifest.
+
+**Parameters:**
+
+- `manifestUrl`: `string` - URL to the manifest JSON file
+
+**Returns:** `Promise<RemoteManifest>`
+
+**Usage:**
+
+```typescript
+const manifest = await fetchManifest(
+  'https://assets-qa.mintmobile.com/.../manifest.json',
+);
+```
+
+---
+
+## Build & Development
+
+### Build the Package
+
+```bash
+# Production build (minified)
+npm run build
+
+# Development build (unminified, preserves modules)
+npm run build:debug
+
+# Watch mode (rebuilds on changes)
+npm run dev
+```
+
+### Type Checking & Linting
+
+```bash
+# Type check
+npm run typecheck
+
+# Lint
+npm run lint
+```
+
+## Publishing
+
+### Current State (Manual Publishing)
+
+**⚠️ Automatic npm publishing via semantic-release is currently disabled** because the NPM_TOKEN is not configured in Bitbucket Pipelines.
+
+#### Manual Publishing Process
+
+1. **Update version in `package.json`:**
+
+   ```json
+   {
+     "version": "1.25.0-f-poc-EC-3301.5"
+   }
+   ```
+
+2. **Build the package:**
+
+   ```bash
+   npm run build
+   ```
+
+3. **Publish to npm:**
+
+   ```bash
+   npm publish --tag f-poc-live-update
+   ```
+
+4. **Install in consumer apps:**
+
+   ```bash
+   # Specific version
+   npm install ecomm-contained-utils@1.25.0-f-poc-EC-3301.5
+
+   # Or use the tag for latest POC version
+   npm install ecomm-contained-utils@f-poc-live-update
+   ```
+
+### Enabling Automatic Publishing (Future)
+
+To enable automatic npm publishing via semantic-release:
+
+1. **Create an Automation token**
+2. **Add token to Bitbucket:**
+3. **Uncomment `@semantic-release/npm` in `release.config.cjs`:**
+
+   ```javascript
+   '@semantic-release/npm',  // ← Uncomment this line
+   ```
+
+4. **Commit and push changes** - semantic-release will now automatically publish on merge.
+
+## Versioning & Branching
+
+### Semantic Release Configuration
+
+The package uses [semantic-release](https://github.com/semantic-release/semantic-release) for automated versioning based on commit messages.
+
+#### Supported Branches
+
+| Branch Pattern | Prerelease Tag | Use Case             |
+| -------------- | -------------- | -------------------- |
+| `master`       | None           | Production releases  |
+| `develop`      | `true`         | QA/Staging releases  |
+| `f-poc-*`      | Branch name    | POC/Feature releases |
+
+#### Commit Message Format
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+```
+
+**Examples:**
+
+```bash
+feat(ecomm-contained-utils): add new remote component loader
+fix(ecomm-contained-utils): resolve React dependency conflicts
+docs: update README with usage examples
+```
+
+#### Release Rules
+
+| Commit Type | Scope          | Release Type  |
+| ----------- | -------------- | ------------- |
+| `feat`      | `ecomm-contained-utils` | Minor (1.x.0) |
+| `fix`       | `ecomm-contained-utils` | Patch (1.0.x) |
+| `feat`      | Any            | Minor         |
+| `fix`       | Any            | Patch         |
+
+### POC Branch Strategy
+
+For the POC, we use the branch pattern `f-poc-*` with a specific prerelease identifier.
+
+**Current setup:**
+
+```javascript
+{
+  name: 'f-poc-*',
+  prerelease: '${name}',  // Uses full branch name as tag
+}
+```
+
+This means:
+
+- Branch `f-poc-EC-3301` → publishes as `1.25.0-f-poc-EC-3301.1`
+- Branch `f-poc-live-update` → publishes as `1.25.0-f-poc-live-update.1`
+
+## How It Works
+
+### Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Consumer App (Next.js)                   │
+│  ┌────────────────────────────────────────────────────────┐ │
+│  │  _document.tsx: <ImportMapScripts />                   │ │
+│  │  └─> Injects import map for React dependency resolution│ │
+│  └────────────────────────────────────────────────────────┘ │
+│  ┌────────────────────────────────────────────────────────┐ │
+│  │  _app.tsx:                                             │ │
+│  │  1. fetchManifest() - Gets component URLs             │ │
+│  │  2. <RemoteLinks /> - Preloads resources              │ │
+│  │  3. <RemoteRenderer /> - Loads & renders component    │ │
+│  └────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────┘
+                           ↓
+         ┌─────────────────────────────────┐
+         │  ModuleLoader (ecomm-contained-utils) │
+         │  1. Checks cache                │
+         │  2. Loads ES module via script  │
+         │  3. Extracts component          │
+         │  4. Returns React component     │
+         └─────────────────────────────────┘
+                           ↓
+         ┌─────────────────────────────────┐
+         │  Remote Component (S3/CDN)      │
+         │  • MintLayout                   │
+         │  • PocComponent                 │
+         │  • TestComponent                │
+         │  etc.                           │
+         └─────────────────────────────────┘
+```
+
+### Component Manifest Format
+
+Remote components are described by a manifest JSON file:
+
+```json
+{
+  "components": {
+    "MintLayout": {
+      "bundleUrl": "https://.../MintLayout.abc123.es.js",
+      "styleUrl": "https://.../MintLayout.def456.css"
+    },
+    "PocComponent": {
+      "bundleUrl": "https://.../PocComponent.xyz789.es.js",
+      "styleUrl": "https://.../PocComponent.uvw012.css"
+    }
+  },
+  "version": "0.1.0",
+  "generatedAt": "2026-01-20T12:00:00.000Z"
+}
+```
+
+### Import Map Resolution
+
+The `ImportMapScripts` component injects an import map that resolves bare specifiers to use the **host app's React instance**:
+
+```html
+<script type="importmap-shim">
+  {
+    "imports": {
+      "react": "data:text/javascript,...(uses window.React)",
+      "react/jsx-runtime": "data:text/javascript,...(uses window.React.createElement)",
+      "react-dom": "https://esm.sh/react-dom@18.3.1",
+      "react-dom/client": "https://esm.sh/react-dom@18.3.1/client"
+    }
+  }
+</script>
+```
+
+**Key design:** Both `react` and `react/jsx-runtime` are mapped to use `window.React`, ensuring remote components use the exact same React instance as the host app. This prevents "multiple copies of React" errors.
+
+### Module Loading Flow
+
+1. **Component Manifest** is fetched via `fetchManifest()`
+2. **ModuleLoader** dynamically imports the ES module from `bundleUrl`
+3. **Component extraction** finds the named export or default export
+4. **React component** is returned and rendered via `<RemoteRenderer>`
+
+## CI/CD Pipeline
+
+### Bitbucket Pipelines Configuration
+
+The package is built and deployed via Bitbucket Pipelines (`bitbucket-pipelines.yml` in repo root).
+
+#### Pipeline Stages
+
+**For `f-poc-*` branches:**
+
+```yaml
+- stage: <EcommContainedUtils> - POC
+  condition:
+    changesets:
+      includePaths:
+        - packages/ecomm-contained-utils/**
+  steps:
+    - Lint & Build
+    - Deploy (currently disabled, manual publishing)
+```
+
+**Triggers:**
+
+- Runs when files in `packages/ecomm-contained-utils/**` are modified
+- Pushes to any branch matching `f-poc-*` pattern