@burdenoff/microfe-store

Standalone micro-frontend for the Store tenant module, providing app marketplace functionality including product discovery, shopping cart, checkout, installation management, licensing, and publisher portal.

Overview

The Store micro-frontend is a fully isolated, production-ready module for:

• End Users: Browse, purchase, and install digital/physical products
• Publishers: Submit products, manage listings, track revenue
• Workspace Admins: Install apps, manage entitlements, configure permissions
• Platform Admins: Review submissions, moderate content, manage categories

Project Structure

microfe-store/
├── package.json              # Package configuration with subpath exports
├── vite.config.ts            # Vite build configuration
├── tsconfig.json             # TypeScript configuration
├── tsconfig.build.json       # Build-specific TS config
├── tsconfig.node.json        # Node config for Vite
├── .graphqlrc.yml            # GraphQL codegen configuration
├── eslint.config.mjs         # ESLint configuration
├── prettier.config.mjs       # Prettier configuration
├── .gitignore                # Git ignore rules
├── index.html                # Dev server entry
└── src/
    ├── index.ts              # Main exports
    ├── StoreRoot.tsx         # Root component (entry point)
    ├── StoreRoutes.tsx       # Internal routing
    ├── components/           # Reusable UI components
    │   ├── index.ts
    │   ├── cart/
    │   │   └── CartDrawer.tsx
    │   └── marketplace/
    │       └── ProductCard.tsx
    ├── hooks/                # Custom React hooks
    │   ├── index.ts
    │   ├── useCart.ts
    │   ├── useProductSearch.ts
    │   ├── useStorePermissions.ts
    │   └── useStoreGraphQL.ts    # 22+ GraphQL hooks
    ├── graphql/              # GraphQL client & operations
    │   ├── index.ts
    │   ├── store-client.ts   # Apollo Client singleton
    │   ├── operations.ts     # Queries, mutations, fragments
    │   └── operations/       # .graphql files by domain
    ├── pages/                # Page components
    │   ├── MarketplaceHomePage.tsx
    │   ├── ProductDetailPage.tsx
    │   ├── CartPage.tsx
    │   └── InstalledAppsPage.tsx
    ├── providers/            # React context providers
    │   └── StoreProvider.tsx
    ├── store/                # Zustand state management
    │   └── storeStore.ts
    ├── types/                # TypeScript type definitions
    │   └── index.ts
    ├── utils/                # Utility functions
    │   └── index.ts
    └── dev/                  # Development entry point
        └── main.tsx

Installation

npm install @burdenoff/microfe-store
# or
bun add @burdenoff/microfe-store

Usage

Basic Integration

import { StoreRoot, type StoreRootProps } from '@burdenoff/microfe-store';

function App() {
  const props: StoreRootProps = {
    basePath: '/store',
    apiGatewayUrl: 'https://api.example.com/tenant/graphql',
    authToken: 'your-jwt-token',
    user: {
      id: 'user-1',
      email: '[email protected]',
      roles: ['user', 'publisher'],
    },
    features: {
      enablePhysicalProducts: true,
      enablePublisherPortal: true,
      enableReviews: true,
      enableSubscriptions: true,
    },
    registerNavItems: (items) => {
      // Register navigation items with your shell
      return () => {}; // Cleanup function
    },
  };

  return <StoreRoot {...props} />;
}

Subpath Exports

// Main entry
import { StoreRoot, useStore, useCart } from '@burdenoff/microfe-store';

// Components only
import { ProductCard, CartDrawer } from '@burdenoff/microfe-store/components';

// Hooks only
import { useProductSearch, useStorePermissions } from '@burdenoff/microfe-store/hooks';

// GraphQL client
import { getStoreClient, resetStoreClient } from '@burdenoff/microfe-store/graphql';

// Types only
import type { Product, CartItem, Order } from '@burdenoff/microfe-store/types';

// Utilities
import { formatPrice, calculateCartTotals } from '@burdenoff/microfe-store/utils';

Features

Implemented

• Product catalog with search and filtering
• Shopping cart with quantity management
• Marketplace homepage with featured products
• Installed apps management page
• Cart page with order summary
• Permission-based navigation
• Feature flag support

Routes

| Route | Description | | -------------------------- | ------------------------------ | | /marketplace | Product catalog & search | | /marketplace/product/:id | Product details | | /cart | Shopping cart | | /orders | Order history | | /installed | Installed apps | | /licenses | License management | | /publisher/* | Publisher portal (conditional) | | /admin/reviews | Review moderation (admin only) |

Architecture

State Management

• Zustand with persistence middleware
• Cart state persisted to localStorage
• View preferences (grid/list, sort) persisted

GraphQL Integration

• Apollo Client singleton with auth token injection
• 22+ hooks for store operations
• Pagination support with cache merge

Permission Scopes

// Example scopes
'tenantmodule-store:catalog:product:read';
'tenantmodule-store:commerce:order:create';
'tenantmodule-store:fulfillment:installation:create';
'tenantmodule-store:publisher:submission:create';

Development

# Install dependencies
bun install

# Start dev server
bun run dev

# Build for production
bun run build

# Type check
bun run type:check

# Run all checks
bun run sanity

Configuration

Environment Variables

| Variable | Description | Default | | ---------------------- | ---------------------- | -------------------------------------- | | VITE_API_GATEWAY_URL | GraphQL API endpoint | http://localhost:4000/tenant/graphql | | VITE_AUTH_TOKEN | Development auth token | - |

Peer Dependencies

• react ^19.0.0
• react-dom ^19.0.0
• react-router-dom ^7.0.0
• @apollo/client ^3.12.0
• zustand ^5.0.0
• @burdenoff/fe-libs workspace:*

License

MIT