@salesforce/b2c-dx-mcp 2.0.0 → 2.1.1

package/content/sfnext/pitfalls.md

@@ -1,141 +0,0 @@
-# Common Pitfalls
-
-## 1. Using Client Loaders/Actions
-
-```typescript
-// ❌ NEVER USE - Client loaders are not permitted
-export function clientLoader() { ... }
-
-// ❌ NEVER USE - Client actions are not permitted  
-export function clientAction() { ... }
-
-// ✅ REQUIRED - Server-only data loading
-export function loader({ context }: LoaderFunctionArgs) {
-    const clients = createApiClients(context);
-    return { product: clients.shopperProducts.getProduct({...}) };
-}
-
-// ✅ REQUIRED - Server-only actions
-export async function action({ request, context }: ActionFunctionArgs) {
-    const clients = createApiClients(context);
-    // Handle mutation on server
-}
-```
-
-**Decision tree:**
-
-```text
-Need data for page render?
-└─ Use server `loader`
-
-Need to handle mutations (form submissions, cart updates)?
-└─ Use server `action`
-
-Need on-demand fetching after page load?
-└─ Use `useScapiFetcher` (search, modals, infinite scroll)
-```
-
-**Key Point:** ALL SCAPI requests happen on the server:
-- `loader`: Runs on server, SCAPI direct (prod) or proxied (dev)
-- `action`: Runs on server, handles mutations securely
-- `useScapiFetcher`: Triggers server route that calls SCAPI
-
-## 2. Module-Level i18n in Schemas
-
-```typescript
-// ❌ RACE CONDITION
-const schema = z.object({
-  email: z.string().email(t('error')),
-});
-
-// ✅ FACTORY PATTERN
-export const createSchema = (t: TFunction) => {
-  return z.object({
-    email: z.string().email(t('error')),
-  });
-};
-```
-
-## 3. Using Async Loaders (Blocks Page Transitions)
-
-```typescript
-// ❌ BLOCKS PAGE TRANSITIONS - Async loader with await
-export async function loader({ context }: LoaderFunctionArgs) {
-    const product = await fetchProduct();    // Blocks!
-    const reviews = await fetchReviews();    // Blocks!
-    return { product, reviews };
-}
-
-// ✅ NON-BLOCKING - Synchronous loader returning promises
-export function loader({ context }: LoaderFunctionArgs): PageData {
-    return {
-        product: fetchProduct(),    // Streams progressively
-        reviews: fetchReviews(),    // Streams progressively
-    };
-}
-```
-
-**Key insight:** Defining loaders as `async` and using `await` causes the entire page transition to block until all data resolves. Use synchronous loaders returning promises for streaming.
-
-**Reference:** See `data-fetching` section for comprehensive loader patterns including mixed strategies (awaited + streamed).
-
-## 4. Modifying shadcn/ui
-
-```typescript
-// ❌ NEVER modify src/components/ui/
-
-// ✅ Create wrapper
-import { Button } from '@/components/ui/button';
-export function MyButton(props) {
-    return <Button {...props} className="custom" />;
-}
-```
-
-## 5. Missing Namespace in i18n
-
-```typescript
-// ❌ MISSING NAMESPACE
-const {t} = useTranslation();
-t('title'); // Won't work
-
-// ✅ USE NAMESPACE
-const {t} = useTranslation('product');
-t('title'); // Works
-```
-
-## 6. Not Using Context in Server Loaders
-
-```typescript
-// ❌ MISSING CONTEXT
-export function loader() {
-    const config = getConfig(); // Wrong!
-}
-
-// ✅ PASS CONTEXT
-export function loader({ context }: LoaderFunctionArgs) {
-    const config = getConfig(context); // Correct
-}
-```
-
-## 7. Forgetting to Namespace i18n Keys
-
-```typescript
-// ❌ MISSING NAMESPACE
-const { t } = useTranslation();
-t('title'); // Won't work without namespace
-
-// ✅ USE NAMESPACE
-const { t } = useTranslation('product');
-t('title'); // Works
-
-// OR
-const { t } = getTranslation();
-t('product:title'); // Works
-```
-
-## 8. Using JavaScript Files
-
-```text
-❌ .js, .jsx, .mjs, .cjs files are BLOCKED
-✅ Use .ts, .tsx files only
-```

package/content/sfnext/quick-reference.md

@@ -1,226 +0,0 @@
-# Storefront Next - Development Guidelines (Quick Reference)
-
-⚠️ **READ THESE CRITICAL RULES BEFORE WRITING ANY CODE** ⚠️
-
-## 🏗️ Architecture Overview
-
-**Server-rendered SPA** built on React Server Components:
-- **React Router 7** in framework mode
-- **Managed Runtime (MRT)** as data orchestration layer
-- **All SCAPI requests execute on MRT server** (both SSR and client-side navigation)
-
-**Key Point**: Client-side routing does NOT mean client-side data fetching. Loaders always run on the server.
-
----
-
-## 🚨 Non-Negotiable Rules
-
-### 1. Server-Only Data Loading
-
-✅ **REQUIRED**: Use server `loader` for all SCAPI data fetching
-
-```typescript
-export function loader({ context }: LoaderFunctionArgs): PageData {
-    const clients = createApiClients(context);
-    return {
-        product: clients.shopperProducts.getProduct({...}),  // Promise - streams
-        reviews: clients.shopperProducts.getReviews({...}),  // Promise - streams
-    };
-}
-```
-
-**Why?** Keeps SCAPI requests on MRT server for security, performance, and bundle size.
-
-### 2. Synchronous Loaders (Not Async)
-
-✅ **CRITICAL**: Loaders must be **synchronous functions that return promises**, NOT async functions.
-
-```typescript
-// ✅ CORRECT - Enables streaming
-export function loader({ context }: LoaderFunctionArgs): PageData {
-    const clients = createApiClients(context);
-    return {
-        product: clients.shopperProducts.getProduct({...}),  // Promise - streams
-    };
-}
-
-// ❌ AVOID - Blocks page transitions
-export async function loader({ context }: LoaderFunctionArgs) {
-    const product = await clients.shopperProducts.getProduct({...}); // Blocks!
-    return { product };
-}
-```
-
-**Why?** Async loaders block page transitions. Synchronous loaders enable progressive streaming.
-
-### 3. TypeScript-Only
-
-✅ **REQUIRED**: Use `.ts` and `.tsx` file extensions  
-❌ **BLOCKED**: `.js`, `.jsx`, `.mjs`, `.cjs` files are forbidden by ESLint
-
-### 4. Use createPage() HOC
-
-✅ **RECOMMENDED**: Use `createPage()` for standardized page patterns
-
-```typescript
-import { createPage } from '@/components/create-page';
-
-const ProductPage = createPage({
-    component: ProductView,
-    fallback: <ProductSkeleton />
-});
-
-export default ProductPage;
-```
-
-### 5. Tailwind CSS 4 Only
-
-✅ **REQUIRED**: Use Tailwind utility classes only  
-❌ **BLOCKED**: No inline styles (`style={{...}}`), no CSS modules, no separate CSS files
-
-```typescript
-// ✅ CORRECT - Tailwind utilities
-<div className="rounded-lg border border-border bg-card p-4">
-    <h2 className="text-lg font-semibold text-card-foreground">
-        {product.name}
-    </h2>
-</div>
-
-// ❌ AVOID - Inline styles
-<div style={{ padding: '1rem' }}>
-
-// ❌ AVOID - CSS modules
-import styles from './product-card.module.css';
-```
-
-**Why?** Consistent styling approach, better performance, automatic dark mode support via theme variables.
-
----
-
-## 📋 Quick Patterns
-
-### Data Fetching
-
-```typescript
-import { createApiClients } from '@/lib/api-clients';
-
-export function loader({ context }: LoaderFunctionArgs): PageData {
-    const clients = createApiClients(context);
-    return {
-        product: clients.shopperProducts.getProduct({...}),
-        reviews: clients.shopperProducts.getReviews({...}),
-    };
-}
-```
-
-**See `data-fetching` section for:** loaders, actions, useScapiFetcher, parallel requests, data flow
-
-### Authentication
-
-```typescript
-import { getAuth } from '@/middlewares/auth.server';
-
-export function loader({ context }: LoaderFunctionArgs) {
-    const auth = getAuth(context);
-    return { 
-        isGuest: auth.userType === 'guest',
-        customerId: auth.customer_id 
-    };
-}
-```
-
-**See `auth` section for:** cookie architecture, client usage, token management
-
-### Configuration
-
-```typescript
-// Components
-import { useConfig } from '@/config';
-const config = useConfig();
-
-// Loaders/Actions
-import { getConfig } from '@/config';
-const config = getConfig(context);
-```
-
-**See `config` section for:** adding config, environment variables, security
-
-### Internationalization
-
-```typescript
-// Components
-import { useTranslation } from 'react-i18next';
-const { t } = useTranslation('product');
-
-// Loaders/Actions
-import { getTranslation } from '@/lib/i18next';
-const { t } = getTranslation(context);
-```
-
-**See `i18n` section for:** validation schemas (factory pattern), language switching, extensions
-
-### Components
-
-```typescript
-// Suspense boundaries
-import { Suspense } from 'react';
-import { Await } from 'react-router';
-
-<Suspense fallback={<ProductSkeleton />}>
-    <Await resolve={product}>
-        {(data) => <ProductHeader product={data} />}
-    </Await>
-</Suspense>
-```
-
-**See `components` section for:** createPage HOC, file organization, best practices
-
-### Styling
-
-```typescript
-// Tailwind utility classes
-<div className="bg-background text-foreground border-border">
-    <button className="bg-primary text-primary-foreground rounded-md px-4 py-2">
-        Click me
-    </button>
-</div>
-
-// shadcn/ui: Add via npx shadcn@latest add <component-name>
-import { Button } from '@/components/ui/button';
-import { Card } from '@/components/ui/card';
-```
-
-**See `styling` section for:** Tailwind CSS 4 rules, Shadcn/ui components, dark mode, responsive design
-
----
-
-## 🔍 Get Detailed Guidelines
-
-Use the `sfnext_get_guidelines` MCP tool with specific sections:
-
-```json
-{
-  "sections": ["data-fetching", "components", "testing"]
-}
-```
-
-**Available sections:**
-- `data-fetching` - Loaders, actions, useScapiFetcher, data flow
-- `components` - createPage HOC, Suspense, file organization
-- `styling` - Tailwind CSS 4, Shadcn/ui, styling guidelines
-- `testing` - Vitest, Storybook, coverage requirements
-- `auth` - Authentication and session management
-- `config` - Configuration system
-- `i18n` - Internationalization patterns
-- `state-management` - Client-side state with Zustand
-- `page-designer` - Page Designer integration
-- `performance` - Optimization techniques
-- `extensions` - Extension development
-- `pitfalls` - Common mistakes to avoid
-
----
-
-**When in doubt:**
-1. Check existing code for similar examples
-2. Use the MCP tool to get detailed section guidance
-3. Follow architectural principles: server-only, streaming, TypeScript

package/content/sfnext/state-management.md

@@ -1,75 +0,0 @@
-# Client-Side State Management
-
-## Zustand Store Pattern
-
-Storefront Next uses Zustand for client-side state (basket, wishlist):
-
-```typescript
-// src/middlewares/basket.client.ts
-import {create} from 'zustand';
-
-interface BasketStore {
-  basket: Basket | null;
-  setBasket: (basket: Basket | null) => void;
-  clearBasket: () => void;
-}
-
-export const useBasketStore = create<BasketStore>((set) => ({
-  basket: null,
-  setBasket: (basket) => set({basket}),
-  clearBasket: () => set({basket: null}),
-}));
-```
-
-## Context Integration
-
-Access Zustand state via context helpers:
-
-```typescript
-import { getBasket, updateBasket } from '@/middlewares/basket.client';
-
-// In clientLoader
-export const clientLoader: ClientLoaderFunction = ({ context }) => {
-    const basket = getBasket(context);
-    return { basket, itemCount: basket?.productItems?.length ?? 0 };
-};
-
-// In components
-function CartIcon() {
-    const basket = getBasket(context);
-    return <Badge count={basket?.productItems?.length ?? 0} />;
-}
-```
-
-## Update Pattern
-
-After mutations, update the store:
-
-```typescript
-export async function clientAction({request, context}: ActionFunctionArgs) {
-  const formData = await request.formData();
-  const productId = formData.get('productId') as string;
-
-  const basket = getBasket(context);
-  const clients = createApiClients(context);
-
-  const {data: updatedBasket} = await clients.shopperBasketsV2.addItemToBasket({
-    params: {path: {basketId: basket.basketId}},
-    body: [{productId, quantity: 1}],
-  });
-
-  // Update Zustand store
-  updateBasket(context, updatedBasket);
-
-  return Response.json({success: true, basket: updatedBasket});
-}
-```
-
-## Best Practices
-
-1. **Use for ephemeral client state**: Shopping cart, UI state, temporary selections
-2. **Don't duplicate server state**: Prefer React Router loaders for server data
-3. **Keep stores focused**: Separate stores for basket, wishlist, etc.
-4. **Sync with server**: Update store after successful mutations
-
-For full documentation on client-side state management patterns, see the Zustand documentation and React Router state management patterns.

package/content/sfnext/styling.md

@@ -1,51 +0,0 @@
-# Styling Guidelines
-
-## Rules
-
-- ✅ **Use Tailwind utility classes** in component JSX
-- ✅ **Use `cn()` utility** for conditional classes (`import { cn } from '@/lib/utils'`)
-- ✅ **Follow mobile-first** responsive patterns (`md:`, `lg:` breakpoints)
-- ❌ **NO inline styles** (`style={{...}}`)
-- ❌ **NO CSS modules** (`.module.css` files)
-- ❌ **NO separate CSS files** for component styles
-- ✅ **Custom CSS** only in `src/app.css` for global styles and theme configuration
-
-## Shadcn/ui Components
-
-**Adding components:**
-
-```bash
-npx shadcn@latest add <component-name>
-```
-
-**Rules:**
-
-- ✅ **DO** customize components by editing files in `src/components/ui/`
-- ❌ **DON'T** create custom components inside `src/components/ui/`
-- ❌ **DON'T** manually copy components (use CLI instead)
-
-## Dark Mode
-
-Dark mode is supported via CSS variables and the `.dark` class. Theme variables automatically adapt:
-
-```typescript
-<div className="bg-background text-foreground border-border">
-    <button className="bg-primary text-primary-foreground">
-        Click me
-    </button>
-</div>
-```
-
-## Responsive Design
-
-Follow mobile-first responsive design:
-
-```typescript
-<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
-    {/* Content */}
-</div>
-```
-
----
-
-**Reference:** See [README-UI-STYLING.md](docs/README-UI-STYLING.md) in your project for complete UI and styling documentation.