Skip to content

Commit e83e718

Browse files
yhsieh1yhsieh1
committed
dev guidelines tool
1 parent dbb0981 commit e83e718

15 files changed

Lines changed: 1634 additions & 26 deletions

File tree

‎packages/b2c-dx-mcp/README.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -214,13 +214,13 @@ Storefront Next development tools for building modern storefronts.
214214

215215
| Tool | Description |
216216
|------|-------------|
217-
| `sfnext_development_guidelines` | Get Storefront Next development guidelines and best practices |
218-
| `sfnext_site_theming` | Configure and manage site theming for Storefront Next |
219-
| `sfnext_figma_to_component_workflow` | Convert Figma designs to Storefront Next components |
220-
| `sfnext_generate_component` | Generate a new Storefront Next component |
221-
| `sfnext_map_tokens_to_theme` | Map design tokens to Storefront Next theme configuration |
222-
| `sfnext_design_decorator` | Apply design decorators to Storefront Next components |
223-
| `sfnext_generate_page_designer_metadata` | Generate Page Designer metadata for Storefront Next components |
217+
| `storefront_next_development_guidelines` | Get Storefront Next development guidelines and best practices |
218+
| `storefront_next_site_theming` | Configure and manage site theming for Storefront Next |
219+
| `storefront_next_figma_to_component_workflow` | Convert Figma designs to Storefront Next components |
220+
| `storefront_next_generate_component` | Generate a new Storefront Next component |
221+
| `storefront_next_map_tokens_to_theme` | Map design tokens to Storefront Next theme configuration |
222+
| `storefront_next_design_decorator` | Apply design decorators to Storefront Next components |
223+
| `storefront_next_generate_page_designer_metadata` | Generate Page Designer metadata for Storefront Next components |
224224
| `scapi_discovery` | Discover available SCAPI endpoints and capabilities |
225225
| `scapi_custom_api_discovery` | Discover custom SCAPI API endpoints |
226226
| `mrt_bundle_push` | Build, push bundle (optionally deploy) |
@@ -296,7 +296,7 @@ npx mcp-inspector --cli node bin/dev.js --toolsets all --allow-non-ga-tools --me
296296
# Call a specific tool
297297
npx mcp-inspector --cli node bin/dev.js --toolsets all --allow-non-ga-tools \
298298
--method tools/call \
299-
--tool-name sfnext_design_decorator
299+
--tool-name storefront_next_design_decorator
300300
```
301301

302302
#### 2. IDE Integration

‎packages/b2c-dx-mcp/src/tools/storefrontnext/content/auth.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# Authentication & Session Management
2+
3+
## Architecture
4+
5+
Split-cookie architecture with server/client contexts:
6+
7+
- **Server middleware** (`auth.server.ts`): Manages SLAS tokens, writes cookies
8+
- **Client middleware** (`auth.client.ts`): Reads cookies, maintains cache
9+
- **React Context** (`AuthProvider`): Provides auth state to components
10+
11+
## Cookie Design
12+
13+
| Cookie Name | Purpose | User Type | Expiry | HttpOnly |
14+
|-------------|---------|-----------|--------|----------|
15+
| `cc-nx-g` | Guest refresh token | Guest | 30 days | No |
16+
| `cc-nx` | Registered refresh token | Registered | 90 days | No |
17+
| `cc-at` | Access token | Both | 30 min | No |
18+
| `usid` | User session ID | Both | Matches refresh | No |
19+
| `customerId` | Customer ID | Registered | Matches refresh | No |
20+
21+
**Key Points**:
22+
23+
- Only ONE refresh token exists (guest OR registered, never both)
24+
- User type derived from which refresh token exists
25+
- Cookies auto-namespaced with `siteId`
26+
- Tokens auto-refresh when expired
27+
28+
## Usage in Loaders/Actions
29+
30+
```typescript
31+
import { getAuth } from '@/middlewares/auth.server';
32+
33+
export function loader({ context }: LoaderFunctionArgs) {
34+
const auth = getAuth(context);
35+
36+
// Access auth properties
37+
const accessToken = auth.access_token;
38+
const customerId = auth.customer_id;
39+
const isGuest = auth.userType === 'guest';
40+
const isRegistered = auth.userType === 'registered';
41+
42+
return { isGuest, customerId };
43+
}
44+
```
45+
46+
## Usage in Components
47+
48+
```typescript
49+
import { useAuth } from '@/providers/auth';
50+
51+
export function MyComponent() {
52+
const auth = useAuth();
53+
54+
if (auth?.userType === 'guest') {
55+
return <LoginPrompt />;
56+
}
57+
58+
return <div>Welcome, customer {auth?.customer_id}</div>;
59+
}
60+
```
61+
62+
**Reference:** See README-AUTH.md for complete authentication documentation.

‎packages/b2c-dx-mcp/src/tools/storefrontnext/content/components.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# Component Patterns
2+
3+
## Use the `createPage` HOC
4+
5+
The `createPage` higher-order component standardizes page patterns with built-in Suspense and page key handling:
6+
7+
```typescript
8+
import { use } from 'react';
9+
import { createPage } from '@/components/create-page';
10+
11+
// Define your view component
12+
function ProductView({
13+
product,
14+
category
15+
}: {
16+
product: Promise<Product>;
17+
category?: Promise<Category>
18+
}) {
19+
const productData = use(product);
20+
const categoryData = category ? use(category) : null;
21+
22+
return (
23+
<div>
24+
<h1>{productData.name}</h1>
25+
{categoryData && <p>Category: {categoryData.name}</p>}
26+
</div>
27+
);
28+
}
29+
30+
// Create page with fallback
31+
const ProductPage = createPage({
32+
component: ProductView,
33+
fallback: <ProductSkeleton />
34+
});
35+
36+
export default ProductPage;
37+
```
38+
39+
**Benefits:**
40+
41+
- Eliminates repetitive Suspense/Await boilerplate
42+
- Consistent loading states across pages
43+
- Built-in page key management for navigation transitions
44+
- Type-safe with full TypeScript support
45+
46+
## shadcn/ui Components
47+
48+
**RULES**:
49+
50+
- ✅ Add via: `npx shadcn@latest add <component-name>`
51+
- ❌ DO NOT modify `src/components/ui/` directly
52+
- ✅ Create custom components elsewhere
53+
54+
## Suspense Boundaries
55+
56+
Use granular Suspense boundaries for better UX:
57+
58+
```typescript
59+
// ✅ RECOMMENDED - Multiple Suspense boundaries
60+
export default function ProductPage({ loaderData: { product, reviews } }) {
61+
return (
62+
<div>
63+
<Suspense fallback={<ProductHeaderSkeleton />}>
64+
<Await resolve={product}>
65+
{(data) => <ProductHeader product={data} />}
66+
</Await>
67+
</Suspense>
68+
69+
<Suspense fallback={<ReviewsSkeleton />}>
70+
<Await resolve={reviews}>
71+
{(data) => <ProductReviews reviews={data} />}
72+
</Await>
73+
</Suspense>
74+
</div>
75+
);
76+
}
77+
78+
// ⚠️ OK - Single Suspense boundary (less granular)
79+
export default createPage({
80+
component: ProductView,
81+
fallback: <ProductPageSkeleton />
82+
});
83+
```
84+
85+
## File Organization
86+
87+
```
88+
src/components/product-tile/
89+
├── index.tsx # Component
90+
├── index.test.tsx # Tests
91+
└── stories/
92+
├── index.stories.tsx # Storybook stories
93+
└── __snapshots__/ # Storybook snapshots (optional)
94+
└── product-tile-snapshot.tsx.snap
95+
96+
# Skeleton components are separate components
97+
src/components/product-skeleton/
98+
├── index.tsx
99+
├── index.test.tsx
100+
└── stories/
101+
└── index.stories.tsx
102+
```
103+
104+
## Best Practices
105+
106+
1. **Extract view components** - Separate data handling from presentation
107+
2. **Type safety** - Define proper TypeScript interfaces
108+
3. **Consistent fallbacks** - Reusable skeleton components
109+
4. **Colocate tests** - Keep tests next to components
110+
5. **Story coverage** - Create stories for all reusable components

‎packages/b2c-dx-mcp/src/tools/storefrontnext/content/config.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# Configuration Management
2+
3+
## Overview
4+
5+
All configuration in `config.server.ts` with environment variable overrides.
6+
7+
## Adding Configuration
8+
9+
1. **Define type in `src/config/schema.ts`**:
10+
11+
```typescript
12+
export type Config = {
13+
app: {
14+
myFeature: {
15+
enabled: boolean;
16+
maxItems: number;
17+
};
18+
};
19+
};
20+
```
21+
22+
2. **Add defaults in `config.server.ts`**:
23+
24+
```typescript
25+
export default defineConfig({
26+
app: {
27+
myFeature: {
28+
enabled: false,
29+
maxItems: 10,
30+
},
31+
},
32+
});
33+
```
34+
35+
3. **Override via environment variables**:
36+
37+
```bash
38+
PUBLIC__app__myFeature__enabled=true
39+
PUBLIC__app__myFeature__maxItems=20
40+
```
41+
42+
## Usage Patterns
43+
44+
**In React Components**:
45+
46+
```typescript
47+
import { useConfig } from '@/config';
48+
49+
export function MyComponent() {
50+
const config = useConfig();
51+
52+
if (config.app.myFeature.enabled) {
53+
const maxItems = config.app.myFeature.maxItems;
54+
// Your feature code
55+
}
56+
}
57+
```
58+
59+
**In Loaders/Actions**:
60+
61+
```typescript
62+
import { getConfig } from '@/config';
63+
64+
export function loader({ context }: LoaderFunctionArgs) {
65+
const config = getConfig(context);
66+
67+
if (config.app.myFeature.enabled) {
68+
// Your loader code
69+
}
70+
}
71+
```
72+
73+
## Environment Variable Rules
74+
75+
Use the `PUBLIC__` prefix with double underscores (`__`) to set any config path:
76+
77+
```bash
78+
# Environment variable → Config path
79+
PUBLIC__app__site__locale=en-US → config.app.site.locale
80+
PUBLIC__app__site__currency=EUR → config.app.site.currency
81+
```
82+
83+
Values are automatically parsed (numbers, booleans, JSON arrays/objects).
84+
85+
Rules:
86+
1. **`PUBLIC__` prefix**: Exposed to browser (client-safe values)
87+
2. **No prefix**: Server-only (secrets, never exposed)
88+
3. **`__` separator**: Navigate nested paths (`PUBLIC__app__site__locale`)
89+
4. **Case-insensitive**: All casings work
90+
5. **Auto-parsing**: Strings, numbers, booleans, JSON
91+
6. **Validation**: Paths must exist in `config.server.ts`
92+
93+
## Security
94+
95+
```bash
96+
# ✅ Safe for client (PUBLIC__ prefix)
97+
PUBLIC__app__commerce__api__clientId=abc123
98+
99+
# ✅ Server-only (no prefix)
100+
COMMERCE_API_SLAS_SECRET=your-secret
101+
```
102+
103+
Read server-only secrets directly from `process.env` - never add to config.
104+
105+
**Reference:** See src/config/README.md for complete configuration documentation.

0 commit comments

Comments
 (0)