Cross-Linking Between PWA and Docs

The PWA and Docs apps can link to each other with environment-aware URLs. Links automatically resolve to the correct environment (localhost, staging, or production).

Environment URL mapping

Environment	PWA URL	Docs URL
Development	http://localhost:5173	http://localhost:3003
Staging	https://flowpos-frontend-pwa-723334209984.us-central1.run.app	https://flowpos-docs-723334209984.us-central1.run.app
Production	https://flowpos-frontend-pwa-136147256555.us-central1.run.app	https://flowpos-docs-136147256555.us-central1.run.app

---

PWA → Docs: HelpLink

File: apps/frontend-pwa/src/components/ui/HelpLink.tsx

A small icon button (BookOpen) that opens a docs page in a new tab.

Props

Prop	Type	Default	Description
path	string	required	Docs page path (e.g. "/sales-pos")
label	string	"Documentation"	Tooltip / aria-label text
size	"sm" | "md"	"sm"	Icon button size
className	string	""	Additional CSS classes

Usage

import { HelpLink } from "@/components/ui/HelpLink";

// Inline next to a page title
<div className="flex items-center gap-2">
  <h1>Sales</h1>
  <HelpLink path="/sales-pos" />
</div>

// With custom label and larger size
<HelpLink path="/getting-started/quick-tour" label="Quick tour guide" size="md" />

// In a toolbar
<div className="flex items-center gap-1">
  <HelpLink path="/inventory" label="Inventory docs" />
  <HelpLink path="/fel" label="Invoicing docs" />
</div>

URL resolution

The component resolves the docs URL automatically from VITE_PUBLIC_DEPLOY_ENV:

1. If VITE_PUBLIC_DOCS_URL is set, that value is used directly
2. Otherwise, it maps VITE_PUBLIC_DEPLOY_ENV to the URL from the built-in table
3. Falls back to http://localhost:3003

No extra configuration needed for staging/production — just ensure VITE_PUBLIC_DEPLOY_ENV is set correctly in the deploy environment (it already is).

---

Docs → PWA: AppLink

File: apps/docs/src/components/AppLink.tsx

An inline link with an external-link icon that opens a PWA page in a new tab.

Props

Prop	Type	Default	Description
path	string	required	PWA route path (e.g. "/forms/sale")
children	ReactNode	required	Link text
style	CSSProperties	undefined	Additional inline styles

Usage in MDX pages

import { AppLink } from "@site/src/components/AppLink";

To process a sale, go to the <AppLink path="/forms/sale">Sales Page</AppLink>.

You can manage your products from the <AppLink path="/forms/ProductPage">Product Catalog</AppLink>.

Important: AppLink requires JSX, so the doc page must be .mdx — not .md. See Migrating .md to .mdx below.

URL resolution

The component reads pwaUrl from docusaurus.config.ts custom fields:

// docusaurus.config.ts
customFields: {
  pwaUrl: process.env.PWA_URL || "http://localhost:5173",
},

For staging/production deploys, set the PWA_URL environment variable:

# Staging
PWA_URL=https://flowpos-frontend-pwa-723334209984.us-central1.run.app

# Production
PWA_URL=https://flowpos-frontend-pwa-136147256555.us-central1.run.app

---

Migrating .md to .mdx

Plain .md files are rendered as standard Markdown — they cannot use React components like AppLink or Callout. To use components in a doc page, rename it from .md to .mdx.

Steps

1. Rename the file

   mv apps/docs/docs/sales-pos/index.md apps/docs/docs/sales-pos/index.mdx

   Docusaurus routes by filename (without extension), so the URL stays the same.

2. Add the component import right after the frontmatter closing ---

   ---
   title: Sales & POS
   sidebar_position: 2
   ---
   
   import { AppLink } from "@site/src/components/AppLink";
   
   # Sales & POS

   The import must be outside the frontmatter block and before any usage.

3. Use the component inline in your Markdown content

   - **Cash register sessions** — Opening and closing your register. <AppLink path="/forms/CashRegisterPage">Open Cash Register</AppLink>

4. Verify — run the dev server and check the page renders correctly

   pnpm --filter @flowpos-workspace/docs start

What changes between .md and .mdx

Feature	.md	.mdx
Standard Markdown	Yes	Yes
Frontmatter (YAML)	Yes	Yes
React component imports	No	Yes
JSX in content	No	Yes
Angle brackets in text (e.g. <generic>)	Rendered as-is	Parsed as JSX — must escape with backticks or curly braces

Gotchas

• Angle brackets: In .mdx, bare <something> is treated as a JSX tag. If your content has HTML-like text (e.g. <your-value>), wrap it in backticks: `<your-value>`.
• Curly braces: In .mdx, { and } are JSX expression delimiters. If your content has literal braces (e.g. JSON examples), wrap them in a code block or escape with {'{}'}.
• Import placement: Imports must go between the frontmatter --- and the first heading. They cannot be inside the frontmatter block.
• No partial migration needed: You only need to rename pages where you want to use components. Plain .md files work fine alongside .mdx files.

Available components

These components are available via @site/src/components/:

Component	Import	Purpose
AppLink	import { AppLink } from "@site/src/components/AppLink"	Link to PWA pages (environment-aware)
Callout	import { Callout } from "@site/src/components/Callout"	Styled tip/info/warning/danger box
VideoEmbed	import { VideoEmbed } from "@site/src/components/VideoEmbed"	Responsive YouTube/Vimeo embed

---

Common PWA routes

Reference for docs authors — use these paths with AppLink:

Page	Path
Sales	/forms/sale
Products	/forms/ProductPage
Inventory	/forms/InventoryPage
Customers	/forms/CustomerPage
Cash Register	/forms/CashRegisterPage
Purchases	/forms/purchase
Quotes	/forms/quotePage
Employees	/forms/EmployeePage
Locations	/forms/LocationPage
Restaurant Dining	/forms/restaurantDining
Restaurant Orders	/forms/restaurantOrders

Common docs paths

Reference for PWA developers — use these paths with HelpLink:

Section	Path
Home	/
Getting Started	/getting-started
Sales & POS	/sales-pos
Inventory	/inventory
Customers & CRM	/customers-crm
Reports	/reports
Electronic Invoicing	/fel
Settings	/settings