@kaena1/ecomm-remote-utils 1.0.0-f-EC-4239.1

package/README.md

@@ -0,0 +1,833 @@
+# ecomm-remote-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-remote-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')
+│   ├── lib/                 # Business logic
+│   │   ├── api/server/            # Server-side API functions
+│   │   │   └── getMintLayoutProps/ # Fetches MintLayout props from ecomm API
+│   │   └── mappers/               # Data mappers
+│   │       └── mapMintLayoutResponseToProps.ts
+│   ├── services/            # Core services
+│   │   ├── fetchManifest.ts        # Fetches component manifests
+│   │   ├── ImportMapService.ts     # Generates import map JSON
+│   │   └── moduleLoader.ts         # ES module loader service
+│   ├── types/               # TypeScript definitions
+│   ├── server.ts            # Server-safe exports for App Router
+│   ├── client.ts            # Client-only exports for App Router
+│   └── types.ts             # Type-only exports entry point
+├── 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                                             |
+| ----------- | ----------------------------------- | ---------------------------------------------------- |
+| Server      | `@kaena1/ecomm-remote-utils/server` | Server Components (App Router RSC, Pages Router SSR) |
+| Client      | `@kaena1/ecomm-remote-utils/client` | Client Components (App Router, Pages Router CSR)     |
+| Types       | `@kaena1/ecomm-remote-utils/types`  | Type-only imports                                    |
+
+**Server exports:** `fetchManifest`, `getRemoteManifest`, `ImportMapScripts`, `RemoteLinks`, `generateImportMap`, `generateImportMapJson`, `getMintLayoutProps`, `mapMintLayoutResponseToProps`
+
+**Client exports:** `RemoteRenderer`, `useRemoteComponent`, `moduleLoader`, `ModuleLoader`, `MintLayout`
+
+**Types exports:** `ComponentManifest`, `RemoteManifest`, `MintLayoutProps`, `MintLayoutPropsAPIResponse`, WP REST API types
+
+## Installation
+
+### In Consumer Applications (e.g., mm-mf-features)
+
+#### Install Latest Stable
+
+```bash
+npm install @kaena1/ecomm-remote-utils
+```
+
+#### Install Latest from a POC Branch
+
+Each `f-poc-*` branch publishes a prerelease automatically. Use the branch name as the tag:
+
+```bash
+npm install @kaena1/ecomm-remote-utils@f-poc-ec-3644
+```
+
+You don't need to track specific version numbers — the tag always points to the latest prerelease from that branch.
+
+#### Install Latest Beta (post-POC, from develop)
+
+```bash
+npm install @kaena1/ecomm-remote-utils@beta
+```
+
+#### Install Specific Version
+
+```bash
+npm install @kaena1/ecomm-remote-utils@1.0.5
+```
+
+#### Updating to Latest
+
+```bash
+npm update @kaena1/ecomm-remote-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-remote-utils package
+cd packages/ecomm-remote-utils
+npm run build
+npm pack
+# This generates: kaena1-ecomm-remote-utils-X.X.X.tgz
+
+# In the consumer application (mm-mf-features)
+npm install /absolute/path/to/kaena1-ecomm-remote-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
+
+> **Recommended approach:** Use [`withRemoteComponentsGSSP`](#withremotecomponentsgsspenvvars-pagegssP-getserversideprops) in each page's `getServerSideProps`. The `getInitialProps` pattern below is kept for reference but `withRemoteComponentsGSSP` is the mandatory pattern for new pages.
+
+##### Add Import Map Scripts to `_document.tsx`
+
+```typescript
+import { Html, Head, Main, NextScript } from 'next/document';
+import { ImportMapScripts } from '@kaena1/ecomm-remote-utils/server';
+
+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 { RemoteLinks, getRemoteManifest } from '@kaena1/ecomm-remote-utils/server';
+import { RemoteRenderer } from '@kaena1/ecomm-remote-utils/client';
+
+App.getInitialProps = async (ctx: AppContext) => {
+  let remoteManifest;
+  try {
+    remoteManifest = await getRemoteManifest(process.env.MANIFEST_URL);
+  } 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:
+>
+> - `@kaena1/ecomm-remote-utils/server` - Server-safe exports (fetchManifest, getRemoteManifest, ImportMapScripts, RemoteLinks, getMintLayoutProps, mapMintLayoutResponseToProps)
+> - `@kaena1/ecomm-remote-utils/client` - Client-only exports (RemoteRenderer, useRemoteComponent, moduleLoader, MintLayout)
+> - `@kaena1/ecomm-remote-utils/types` - Type-only exports
+
+> **MintLayout styles:** Importing `@kaena1/ecomm-remote-utils/client` now auto-injects package-owned MintLayout CSS at runtime in the browser. Consumers should not manually import `dist/style.css`.
+
+##### Add Import Map Scripts to `app/layout.tsx`
+
+```typescript
+// Use /server for server components
+import {
+  ImportMapScripts,
+  RemoteLinks,
+  getRemoteManifest,
+} from '@kaena1/ecomm-remote-utils/server';
+
+// Use /client for client components (in separate 'use client' files)
+// import { RemoteRenderer } from '@kaena1/ecomm-remote-utils/client';
+
+export default async function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const remoteManifest = await getRemoteManifest(process.env.MANIFEST_URL);
+  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 '@kaena1/ecomm-remote-utils/client';
+
+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} />;
+```
+
+---
+
+### Data fetching (server-side)
+
+#### `getRemoteManifest(environment, cookieStore): Promise<RemoteManifest>`
+
+Server-side function that fetches the remote component manifest. Encapsulates URL construction (cache-busting timestamp) and the fetch call.
+
+**Parameters:**
+
+- `environment`: `Environment` - Environment variable value set in the consumer app's repository. Can be `production` or `develop`. Defaults to `production`.
+- `cookieBranch`: `string | undefined` - f-branch can be set as a cookie with the name `cont-comp`. If it's not set or none is provided, it will default to `f-poc-live-update` for develop, and `master` for production.
+
+**Returns:** `Promise<RemoteManifest>`
+
+**Usage (NextJS):**
+
+```typescript
+import { getRemoteManifest } from '@kaena1/ecomm-remote-utils/server';
+import { cookies } from 'next/headers';
+
+const cookieStore = await cookies();
+const branchCookie = cookieStore.get('cont-comp')?.value;
+const remoteManifest = await getRemoteManifest(
+  process.env.NEXT_PUBLIC_ENVIRONMENT,
+  branchCookie,
+);
+```
+
+---
+
+#### `getMintLayoutProps(NEXT_PUBLIC_SITE_URL, ECOMM_API_URL, ECOMM_API_STANDALONE_DEVICE_CREDS): Promise<MintLayoutProps>`
+
+Server-side function that fetches MintLayout props from the ecomm API and maps them to the expected format.
+
+**Parameters:**
+
+- `NEXT_PUBLIC_SITE_URL`: `string` - The public site URL
+- `ECOMM_API_URL`: `string` - The ecomm API base URL
+- `ECOMM_API_STANDALONE_DEVICE_CREDS`: `string` - Credentials in `username|password` format
+
+**Returns:** `Promise<MintLayoutProps>`
+
+**Usage:**
+
+```typescript
+import { getMintLayoutProps } from '@kaena1/ecomm-remote-utils/server';
+
+const mintLayoutProps = await getMintLayoutProps(
+  process.env.NEXT_PUBLIC_SITE_URL,
+  process.env.ECOMM_API_URL,
+  process.env.ECOMM_API_STANDALONE_DEVICE_CREDS,
+);
+```
+
+---
+
+### Utils
+
+#### `getRemoteComponentsData(envVars): Promise<{remoteManifest: RemoteManifest, mintLayoutProps: MintLayoutProps}>`
+
+Server-side util function that handles all logic for app router NextJS apps.
+**IMPORTANT**: it is **mandatory** to use this in the app router. This **WON'T WORK** in the pages router.
+
+**Parameters:**
+
+- `envVars`: `RemoteComponentsEnvVars` - Environment variables object containing:
+  - `NEXT_PUBLIC_ENVIRONMENT`: `string` - The environment (e.g., 'production', 'develop')
+  - `NEXT_PUBLIC_SITE_URL`: `string` - The public site URL
+  - `ECOMM_API_URL`: `string` - The ecomm API base URL
+  - `ECOMM_API_STANDALONE_DEVICE_CREDS`: `string` - API credentials
+
+**Returns:** `Promise<{ remoteManifest: RemoteManifest, mintLayoutProps: MintLayoutProps }>`
+
+**Usage:**
+
+```typescript
+import { getRemoteComponentsData } from '@kaena1/ecomm-remote-utils/server';
+
+const { remoteManifest, mintLayoutProps } = await getRemoteComponentsData({
+  NEXT_PUBLIC_ENVIRONMENT: process.env.NEXT_PUBLIC_ENVIRONMENT,
+  NEXT_PUBLIC_SITE_URL: process.env.NEXT_PUBLIC_SITE_URL,
+  ECOMM_API_URL: process.env.ECOMM_API_URL,
+  ECOMM_API_STANDALONE_DEVICE_CREDS:
+    process.env.ECOMM_API_STANDALONE_DEVICE_CREDS,
+});
+```
+
+---
+
+#### `withRemoteComponentsGSSP(envVars, pageGSSP?): GetServerSideProps`
+
+A Higher-Order Function (HOF) for Next.js Pages Router that composes a `getServerSideProps` function to automatically fetch remote component data (manifest and layout props).
+**IMPORTANT**: It is **mandatory** to use this in the pages router. It handles fetching the manifest and layout props, merging them with your page's props.
+
+**Parameters:**
+
+- `envVars`: `RemoteComponentsEnvVars` - Environment variables object (same as `getRemoteComponentsData`).
+- `pageGSSP`: `GetServerSideProps` (optional) - Your page's existing `getServerSideProps` function. The results will be merged.
+
+**Returns:** A new `GetServerSideProps` function.
+
+**Usage:**
+
+```typescript
+// pages/index.tsx
+import { withRemoteComponentsGSSP } from '@kaena1/ecomm-remote-utils/server';
+
+async function pageGSSP() {
+  // Your existing logic (optional)
+}
+
+export const getServerSideProps = withRemoteComponentsGSSP(
+  {
+    NEXT_PUBLIC_ENVIRONMENT: process.env.NEXT_PUBLIC_ENVIRONMENT,
+    NEXT_PUBLIC_SITE_URL: process.env.NEXT_PUBLIC_SITE_URL,
+    ECOMM_API_URL: process.env.ECOMM_API_URL,
+    ECOMM_API_STANDALONE_DEVICE_CREDS:
+      process.env.ECOMM_API_STANDALONE_DEVICE_CREDS,
+  },
+  pageGSSP,
+);
+
+export default function Page({ remoteManifest, mintLayoutProps, customProp }) {
+  // remoteManifest and mintLayoutProps are automatically injected
+  // ...
+}
+```
+
+---
+
+## 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
+
+### Automatic Publishing (Active)
+
+Publishing is fully automated via semantic-release and Bitbucket Pipelines. No manual steps needed.
+
+| Branch    | npm tag                               | Example version         |
+| --------- | ------------------------------------- | ----------------------- |
+| `master`  | `latest`                              | `1.0.5`                 |
+| `develop` | `beta` _(post-POC)_                   | `1.0.5-beta.1`          |
+| `f-poc-*` | Branch name _(temporary, during POC)_ | `1.0.5-f-poc-ec-3644.1` |
+
+A release is triggered automatically when a push includes a `feat` or `fix` commit. The pipeline handles building, versioning, publishing to npm, and committing the updated `package.json` back to the branch.
+
+#### Installing a prerelease (POC)
+
+```bash
+# Latest from a specific POC branch
+npm install @kaena1/ecomm-remote-utils@f-poc-ec-3644
+
+# Specific version
+npm install @kaena1/ecomm-remote-utils@1.0.5-f-poc-ec-3644.1
+```
+
+> **⚠️ Pin prereleases exactly — no `^` or `~`**
+>
+> Semver range operators behave unexpectedly with prerelease versions. `^1.1.0-f-poc-live-update.8` resolves to any `1.1.0-<tag>` where `<tag>` sorts higher lexicographically, which can install a completely different branch.
+>
+> Always use an exact version in `package.json`:
+>
+> ```json
+> "@kaena1/ecomm-remote-utils": "1.1.0-f-poc-live-update.8"
+> ```
+
+## 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-remote-utils): add new remote component loader
+fix(ecomm-remote-utils): resolve React dependency conflicts
+docs: update README with usage examples
+```
+
+#### Release Rules
+
+Uses the default [Conventional Commits](https://www.conventionalcommits.org/) release rules:
+
+| Commit Type | Release Type  |
+| ----------- | ------------- |
+| `feat`      | Minor (1.x.0) |
+| `fix`       | Patch (1.0.x) |
+| `chore`     | None          |
+
+### 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-3570` → publishes as `1.0.3-f-poc-EC-3570.1`
+- Branch `f-poc-live-update` → publishes as `1.0.3-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-remote-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 (temporary, during POC):**
+
+```yaml
+- stage: <EcommContainedUtils> - POC
+  condition:
+    changesets:
+      includePaths:
+        - packages/ecomm-remote-utils/**
+  steps:
+    - Lint & Build
+    - Deploy (prerelease published to npm with branch name as tag)
+```
+
+**For `develop` branch (post-POC):**
+
+```yaml
+- stage: <EcommContainedUtils> - QA
+  condition:
+    changesets:
+      includePaths:
+        - packages/ecomm-remote-utils/**
+  steps:
+    - Lint & Build
+    - Deploy (beta prerelease published to npm)
+```
+
+**For `master` branch:**
+
+```yaml
+- stage: <EcommContainedUtils> - Production
+  condition:
+    changesets:
+      includePaths:
+        - packages/ecomm-remote-utils/**
+  steps:
+    - Lint & Build
+    - Deploy (stable release published to npm)
+```
+
+**Triggers:**
+
+- Runs when files in `packages/ecomm-remote-utils/**` are modified
+
+## Environment Variables
+
+All env vars are read in the consumer app, not in this package. These are passed into the utility functions as arguments.
+
+| Variable                            | Used by                                                                    | Description                                                                                                                               |
+| ----------------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `NEXT_PUBLIC_ENVIRONMENT`           | `getRemoteManifest`, `getRemoteComponentsData`, `withRemoteComponentsGSSP` | Controls which S3 bucket the manifest is fetched from. `production` → `assets.mintmobile.com`, anything else → `assets-qa.mintmobile.com` |
+| `NEXT_PUBLIC_SITE_URL`              | `getMintLayoutProps`, `getRemoteComponentsData`                            | Public-facing site URL, forwarded to MintLayout's `config` prop                                                                           |
+| `ECOMM_API_URL`                     | `getMintLayoutProps`, `getRemoteComponentsData`                            | Base URL of the ecomm API                                                                                                                 |
+| `ECOMM_API_STANDALONE_DEVICE_CREDS` | `getMintLayoutProps`, `getRemoteComponentsData`                            | API credentials in `username\|password` format                                                                                            |
+
+The `cont-comp` **cookie** (not an env var) can be set in the browser to override which branch's manifest is loaded. `getRemoteManifest` reads it when passed via `cookieBranch`. If absent, defaults to `f-poc-live-update` (develop) or `master` (production).
+
+## Troubleshooting
+
+**`Invalid hook call` / "You may have more than one copy of React"**
+Caused by `npm link` creating two separate React instances. Use `npm pack` instead — see [For Local Development](#for-local-development).
+
+**Component renders nothing / stays on placeholder indefinitely**
+Check the browser console for a module load error. Common causes:
+
+- `bundleUrl` in the manifest is unreachable (wrong environment, pipeline hasn't run)
+- Import map is missing — confirm `<ImportMapScripts />` is rendered before the component loads
+
+**`getRemoteManifest` returns `null` or throws in production**
+The manifest fetch failed server-side. The consumer app should handle `null` gracefully and render a fallback (e.g. render `children` without the layout wrapper). `withRemoteComponentsGSSP` and `getRemoteComponentsData` do this automatically.
+
+**`RemoteRenderer` throws "Cannot use import statement" or similar ESM error**
+`es-module-shims` is not loaded. Confirm `<ImportMapScripts />` is in `<head>` before any contained component scripts are executed.
+
+**TypeScript: "Module has no exported member" for a remote component**
+The `urlImports.d.ts` type declarations in the consumer app are out of date. Re-run `getMintLayoutTypes` (or update the file manually) to pull the latest type definitions.
+
+**Wrong branch loaded in QA**
+Check the `cont-comp` cookie value in the browser. It is case-sensitive and must match the branch name exactly (e.g. `f-poc-EC-3808`, not `f-poc-ec-3808`). Clear or update the cookie to switch branches.