How mercoa-finance/react works
Project Type and Purpose
• This is a React component library (package name “@mercoa/react”) that provides UI components, utilities, and a context provider (MercoaSession) for embedding the Mercoa entity portal in host applications.
• It includes:
• A “src” folder with library source code (components, modules, shared utilities).
• A “docs” folder implementing the public documentation site (Next.js + MDX).
• An “examples” folder with several sample Next.js applications demonstrating library usage.
• Build/config files (Vite, Tailwind, TypeScript) and a GitHub Actions workflow for publishing to npm.
File Structure
• Top-level modules:
• src/components – exported React components
• src/modules – domain-driven feature modules (common, counterparties, payables, receivables) each with API queries/mutations, hooks, providers, stores, UI subcomponents
• src/lib – shared utilities, style helpers, react-query wrappers
• docs – Next.js application providing MDX-based component and API documentation
• examples – three standalone Next.js demo apps showing basic integration, advanced Auth flows, styling options
• Config & tooling:
• vite.config.ts – library bundling configuration
• tailwind.config.ts & CSS files – styling pipeline
• .github/workflows/publish.yml – CI/CD publishing pipeline
• tsconfig.json & eslint/prettier – linting/type checking
README for Additional Insights
• Emphasizes that the library ships with two CSS files (tailwind.base.css, style.css) and relies on a React Context (MercoaSession) that must wrap any host application.
• Points to an external docs site (docs.mercoa.com) generated from the “docs” folder.
• Shows that host apps import components directly from npm, wrap in MercoaSession, and consume domain modules (Payables, Receivables, Counterparties, etc.).
Main Components and Their Relationships
• Core Library (src/)
• MercoaSession Context Provider
• Domain Modules (common, counterparties, payables, receivables)
• UI Components (e.g., PayablesTable, ReceivablePreview, ApprovalPolicy)
• Utilities & React-Query hooks
• Build & Distribution
• Vite → produces ESM/CJS bundles + CSS assets → npm registry
• GitHub Actions → triggers on tag → runs build/tests → publishes
• Documentation Site
• Next.js + MDX → imports built library locally → renders docs/components examples
• Deployed as static site (docs folder)
• Example Applications
• Three Next.js demo apps → each imports @mercoa/react → wraps in MercoaSession → uses domain components
• External Dependencies
• React, React-DOM
• React Query
• TailwindCSS
• Next.js (docs & examples)
Architectural Patterns & Design Principles
• Domain-Driven Modularization: each domain (Payables, Receivables, Counterparties) lives in its own folder with API layer, hooks, providers, stores, and UI components.
• Context-Based Configuration: a single MercoaSession context provider supplies authentication and global settings to all components.
• Pluggable UI Library: separated into sub-directories under src/components and src/modules, promoting tree-shaking and selective imports.
• Documentation as Code: documentation lives alongside source in “docs” and uses MDX to mix examples with narrative.