🛒 Business Cart App (@windstream/business-cart)

The Business Cart App is a self-contained, React-based cart application built with Next.js and designed to be embedded inside the Windstream Business site. It replaces the legacy StencilJS version, improves developer experience, and aligns with the consumer cart’s tech stack.

⚙️ Architecture Summary

| Component | Technology | Notes | | -------------- | --------------- | ------------------------------------------------------- | | Cart App | React (Next.js) | Client-side app rendered into DOM via NPM bundle | | Browse App | WordPress | Hosts marketing pages; injects Cart via <script> | | Middleware | NestJS API | Shared API used by both Business and Consumer carts | | Config | appConfig | Loads env vars from Azure KeyVault or .env | | Analytics | Segment | Tracks cart events via Business-specific Segment source |

🚀 Tech Stack

| Area | Technology | | ------------ | --------------------------------------------------------- | | UI Framework | React 18 + Next.js (CSR only) | | Styling | TailwindCSS (utility-first) | | Routing | Next.js Router (next/router) | | State Mgmt | Zustand (lightweight, scalable) | | Tracking | @segment/analytics-next | | Packaging | Built with next build && next export, published via NPM | | Testing | Jest + React Testing Library | | CI/CD | Azure DevOps (build, test, publish) |

📁 Folder Structure

business-cart/
├── public/                              # Static assets
├── src/
│   ├── pages/
│   │   ├── check-availability/
│   │   │   └── index.tsx
│   │   ├── check-in-progress/
│   │   │   └── index.tsx
│   │   ├── options/
│   │   │   └── index.tsx
│   │   ├── contact-information/
│   │   │   └── index.tsx
│   │   ├── summary/
│   │   │   └── index.tsx
│   │   ├── order-completed/
│   │   │   └── index.tsx
│   │   └── unserviceable/
│   │       └── index.tsx
│   ├── index.tsx                       # DOM mount entry point
│   ├── components/
│   │   ├── core/                       # Atomic components
│   │   │   ├── button/
│   │   │   │   └── index.tsx
│   │   │   ├── input/
│   │   │   │   └── index.tsx
│   │   │   └── select/
│   │   │       └── index.tsx
│   │   └── blocks/                     # Composed UI blocks
│   │       ├── contact-form/
│   │       │   └── index.tsx
│   │       ├── summary-panel/
│   │       │   └── index.tsx
│   │       └── step-header/
│   │           └── index.tsx
│   ├── context/
│   │   ├── cart-context/
│   │   │   └── index.ts
│   │   └── user-session/
│   │       └── index.ts
│   ├── hooks/
│   │   ├── use-cart-state.ts           # ✅ Flat for simple state
│   │   └── use-debounced-input/
│   │       ├── index.ts                # ✅ Folder for custom debounce logic
│   │       └── types.ts
│   ├── services/
│   │   ├── availability/
│   │   │   └── index.ts
│   │   ├── order/
│   │   │   └── index.ts
│   │   └── segment/
│   │       └── index.ts
│   ├── tracking/                       # Segment utils may follow flat or folder pattern
│   └── config/
│       └── app-config.ts
├── .env.local
├── package.json
├── next.config.js
├── tailwind.config.js
└── README.md

📩 Rendering Strategy

This app is published as a pure NPM package and embedded into the WordPress Browse site.

It mounts into an HTML container:

<div id="business-cart-root"></div>
<script src="/static/cart.bundle.js"></script>

Upon script load, the app mounts automatically:

// src/index.tsx
import ReactDOM from "react-dom/client";
import { BusinessCartApp } from "./business-cart-app";

const container = document.getElementById("business-cart-root");
if (container) {
  const root = ReactDOM.createRoot(container);
  root.render(<BusinessCartApp />);
}

Cart steps (pages) are navigated using Next.js router with full back/forward support.

🔀 Routing Strategy

• Next.js routing is used internally for multi-step flows:

  • /check-availability
  • /options
  • /contact-information
  • /summary
  • /order-completed
  • /unserviceable, etc.

• The entire app is mounted inside a single DOM container on WordPress — routing is SPA-style and not tied to the host site’s URL structure.

• Browser history support is included.

📊 Segment Integration

• Integrated with @segment/analytics-next
• Automatically initialized using the Segment Write Key for Business Cart
• Sends standard and custom events (e.g., page views, CTA clicks, form submissions)

Example:

import { trackEvent } from "@/tracking/segment";

trackEvent("Cart Step Viewed", { step: "contact-information" });

📦 Publishing as an NPM Package

On CI build success (e.g., merge to main), the app:

1. Builds using:

   next build && next export

2. Publishes to NPM usin npm publish: @windstream/business-cart command: bash npm publish --access=public

3. The package is consumed by the WordPress Browse site by:

   • Importing the compiled JS bundle (e.g., cart.bundle.js)
   • Adding the mount container in the HTML:

   <div id="business-cart-root"></div>
   <script src="/static/cart.bundle.js"></script>

4. The app initializes automatically and handles routing, rendering, and tracking independently inside the injected DOM element.

✅ Features

• Modern React + TailwindCSS setup with atomic design pattern
• Client-side routing across steps (/check-availability, /options, /summary, etc.)
• Fully isolated from host — does not require WordPress to use React
• Config-driven using appConfig from Azure KeyVault
• Integrated analytics via Segment
• Future-proof for add-ons (e.g., feature flags, multi-brand themes)

🚀 Automating Versioning & Publishing (CI/CD)

To automate version bumping and publishing via CI pipeline (e.g., GitHub Actions, Azure DevOps):

1. Enable Conventional Commits

All commits should follow Conventional Commits, such as:

feat: add summary panel block
fix: address layout bug in contact form

2. Use pnpm version strategy

For automatic versioning:

pnpm version patch     # or: major / minor
git push --follow-tags

This updates the version in package.json, creates a Git tag, and allows the CI to detect a new version for publishing.

3. CI Example: Azure Pipelines

- task: NodeTool@0
  inputs:
    versionSpec: "18.x"

- script: |
    pnpm install
    pnpm build
    npm config set //registry.npmjs.org/:_authToken=$(NPM_TOKEN)
    npm publish --access=public
  env:
    NPM_TOKEN: $(NPM_TOKEN)
  displayName: "Publish to npm"
  condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main'))

🔐 NPM_TOKEN should be configured as a secure pipeline variable with publish access to the Windstream org on npmjs.com.