diff --git a/.cursor/rules/storefront-development/component-generation-requirements.mdc b/.cursor/rules/storefront-development/component-generation-requirements.mdc deleted file mode 100644 index b5ca1258b4..0000000000 --- a/.cursor/rules/storefront-development/component-generation-requirements.mdc +++ /dev/null @@ -1,29 +0,0 @@ ---- -description: USE when creating new components -globs: -alwaysApply: false ---- -# Component Generation Requirements - -## Process -1. **Preferred** - - Ask user to provide the component name, purpose and requirements. - - Determine the appropriate component type (presentational, container, form, etc.). - - Collected component information must be displayed and asked for confirmation. -2. **Default to Simple** - Start with minimal implementation -3. DO NOT add extra features unless asked - -## General Rules -Create components at the components directory: `**/components/[component-name]/index.jsx` - -## Guidelines -**IMPORTANT** -- Use functional components with hooks -- Use PascalCase for component names -- Use kebab-case for directories -- Start simple, expand only if requested -- One main purpose per component - - - - diff --git a/packages/pwa-kit-create-app/CHANGELOG.md b/packages/pwa-kit-create-app/CHANGELOG.md index 11ecb70f68..9fd1d50361 100644 --- a/packages/pwa-kit-create-app/CHANGELOG.md +++ b/packages/pwa-kit-create-app/CHANGELOG.md @@ -1,3 +1,6 @@ +## v3.12.0-dev.0 +- Add development guidelines and create page Cursor rules for generated project [2786](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2786) + ## v3.11.0-dev.0 (May 23, 2025) - Fix exiting before `program.json` content can be flushed [#2699](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2699) - Add `program.json` + Support for Agent-Friendly CLI Input via stdio [#2662](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2662) diff --git a/packages/pwa-kit-create-app/assets/cursor-rules/development-guidelines.mdc b/packages/pwa-kit-create-app/assets/cursor-rules/development-guidelines.mdc new file mode 100644 index 0000000000..31626aa03b --- /dev/null +++ b/packages/pwa-kit-create-app/assets/cursor-rules/development-guidelines.mdc @@ -0,0 +1,40 @@ +--- +description: Salesforce Commerce Composable Storefront Development Guidelines +globs: +alwaysApply: false +--- + +# Commerce Composable Storefront Development Guidelines + +## Overview +Guidelines for Salesforce Commerce Composable Storefront development using PWA Kit, Retail React App, and Chakra UI. + +## Core Principles +- Analyze requirements and existing codebase thoroughly +- Use existing components and hooks when possible +- Plan before implementing +- Test comprehensively with Jest + +## PWA Kit Essentials + +### Architecture +- Server-side rendering (SSR) for initial loads +- Client-side rendering (CSR) for interactions +- Isomorphic code (works on server and client) +- Proxy requests via `/mobify/proxy/` + +### Special Components +- Components starting with `_` are special PWA Kit components +- `_app-config`: Top-level app configuration +- `_app`: Persistent layout (header, footer, sidebar) +- `_error`: 404 and error pages + +## Development Rules +- Use kebab-case for file names (except special components with `_`) +- Use Chakra UI and existing components +- Create modular, reusable components +- Use React Hooks for state management +- Access data via commerce-sdk-react hooks +- Ensure mobile-friendly and accessible components +- Maintain consistent code formatting using project standards +- Write comprehensive test coverage diff --git a/packages/pwa-kit-create-app/assets/cursor-rules/page-creation.mdc b/packages/pwa-kit-create-app/assets/cursor-rules/page-creation.mdc new file mode 100644 index 0000000000..a36d503e30 --- /dev/null +++ b/packages/pwa-kit-create-app/assets/cursor-rules/page-creation.mdc @@ -0,0 +1,16 @@ +--- +description: Page Creation Rule - automatically apply when user asks to create new page, add page, make page, build page, generate page +globs: +alwaysApply: false +--- +USE WHEN create a new page, add a new page, make a new page, build a new page, generate a new page, create page, add page, make page, build page, generate page + +**Mandatory** +- DO ask user to clarify page name and page route before proceed +- ONLY Create a bare minimum page component +- Do NOT include other project components or hooks unless specifically requested +- Do NOT add extra styling, layout, or features unless explicitly asked + +## Implementation Steps +1. Create simple component in `app/pages/[page-name]/index.jsx` +2. Add route to `app/routes.jsx` \ No newline at end of file diff --git a/packages/pwa-storefront-mcp/src/utils/pwa-developer-guideline-tool.js b/packages/pwa-storefront-mcp/src/utils/pwa-developer-guideline-tool.js index 2652bfa594..9111144f68 100644 --- a/packages/pwa-storefront-mcp/src/utils/pwa-developer-guideline-tool.js +++ b/packages/pwa-storefront-mcp/src/utils/pwa-developer-guideline-tool.js @@ -6,103 +6,40 @@ */ import {EmptyJsonSchema} from './utils' -const guidelinesText = `# Salesforce Commerce Composable Storefront Development Guidelines +const guidelinesText = `# Commerce Composable Storefront Development Guidelines ## Overview -This document offers guidelines in the development of Salesforce Commerce Composable Storefront applications using PWA Kit. The AI should possess a comprehensive understanding of the PWA Kit architecture, sample Retail React App, Chakra UI, and standard React application practices. +Guidelines for Salesforce Commerce Composable Storefront development using PWA Kit, Retail React App, and Chakra UI. ## Core Principles - -### Project Understanding -- Thoroughly analyze requests and the existing project for successful implementation. -- Promptly clarify ambiguous requirements. - -### Development Workflow -- **Analyze Requirements** - Clearly define the objectives and functionalities required. -- **Review Existing Code** - Examine the current codebase to identify similar solutions and potentially reusable components. -- **Understand Existing Hooks and Utilities** - Familiarize with hooks and utility functions available within the project, including those from commerce-sdk-react and template-retail-react-app modules. -- **Plan Implementation** - Design component structure before coding. -- **Implement Incrementally** - Develop and test the service in small, manageable steps. -- **Test Thoroughly** - Ensure comprehensive testing, including the use of Jest. - -## Technical Stack - -### Core Technologies -- **React** - UI components and SPA architecture -- **Express** - Server-side rendering and backend -- **@salesforce/commerce-sdk-react** - Commerce Cloud API integration (hooks) -- **PWA Kit** - SSR, routing, config, Salesforce integration -- **Chakra UI V2** - UI components and theming -- **Emotion** - CSS-in-JS styling -- **React Router** - Routing -- **React Intl** - Localization -- **React Query** - Data fetching/caching -- **Webpack** - Bundling -- **React Testing Library, Jest** - Testing libraries -- **react-helmet, framer-motion, etc.** - Utilities, animation, head management -- **ESLint/Prettier** - Code formatting and linting - -## PWK Kit Architecture - -### Configuration Files -- PWA Kit apps are customized using configuration files for API access, URL formatting, and server-side rendering. -- These files support JavaScript, YAML, and JSON formats, with default.js being the standard. -- Configuration values are serialized for isomorphic rendering, so secrets must not be included. -- Environment-specific configuration files can replace or complement default.js. -- File precedence is .js > .yml > .yaml > .json if base names are the same. - -### Proxy Requests -- Managed Runtime's proxy feature routes API requests through the storefront domain to avoid CORS issues and improve performance. -- Local proxy configurations are set in config/default.js, while Managed Runtime deployments use Runtime Admin or the Managed Runtime API. -- Requests use the /mobify/proxy/ pattern. -- Proxied requests and responses are modified for transparent operation. -- Proxied requests are uncached by default but can be cached using a caching path prefix. - -### Rendering -- PWA Kit uses server-side rendering (SSR) for fast initial page loads, leveraging CDN caching. -- After the first load, client-side rendering (CSR) takes over for fluid user interactions. -- Application code must be isomorphic, functioning in both server and client environments, often with conditional logic. -- Props from API requests are serialized into the page source during SSR for client-side hydration. -- A correlation ID is provided on each page for tracking requests across PWA Kit and other systems. - -### Routing -- PWA Kit uses Express.js and React Router for handling requests and rendering components. -- Routes are defined in app/routes.jsx as an array of objects with 'path' and 'component' properties. -- You can use both withReactQuery and withLegacyGetProps at the same time. -- getProps and shouldGetProps were removed from the default template of pages of the Retail React App, but aren't deprecated. Long-term support for these methods remains. - -### PWA Kit Special Components -- Customize your storefront by overriding default special components that start with an underscore (_), such as app/components/_app-config/index.jsx. -- app/components/_app-config: The top-level component for app-wide configurations like theme providers and state management. -- app/components/_app: The child of _app-config. Use it for layout and UI that persist throughout your React app, such as the header, footer, and sidebar. -- app/components/_error: Renders when a page or its data isn't found, or when an error occurs, returning a 404 status. - -### State Management -- PWA Kit applications support various state management approaches, including simple prop-passing or React's Context API. -- The React Context API can be used with useReducer and useContext for shared global state. -- The AppConfig special component is the primary place to initialize a state management system. -- When integrating libraries like Redux, AppConfig methods such as restore, freeze, extraGetPropsArgs, and render are utilized. - -### PWA Kit Extensibility -- In PWA Kit v3, you can extend a base template (@salesforce/retail-react-app) by replacing specific files using a local "overrides directory." -- Extensibility is configured in package.json with the base template (ccExtensibility.extends) and your overrides directory (ccExtensibility.overridesDir). -- To override a file, recreate its exact path and filename in your overrides directory. - -### PWA Kit Storefront Development -- Start development with Retail React App sample codebase and tooling. -- Use included npm scripts for automating development tasks like build, test, and lint. -- Access Shopper data through the commerce-sdk-react hooks to fetch, cache, and mutate utilizing Salesforce Commerce API (SLAS) and OCAPI. -- Use Chakra UI and existing components when available. -- Create simple, functional, modular, reusable components. -- Use the React Helmet library to modify the HTML tags in Document, such as . -- Use kebab-case for file names. Only start with an underscore (_) if they are special components. -- Use React Hooks (e.g., useState, useEffect, useContext, useMemo, useCallback) for state management and side effects. - -## Quality Standards -- Maintain consistent code formatting using project standards. -- Write comprehensive test coverage. -- Ensure components are accessible and mobile-friendly. -- Follow security best practices for all code. +- Analyze requirements and existing codebase thoroughly +- Use existing components and hooks when possible +- Plan before implementing +- Test comprehensively with Jest + +## PWA Kit Essentials + +### Architecture +- Server-side rendering (SSR) for initial loads +- Client-side rendering (CSR) for interactions +- Isomorphic code (works on server and client) +- Proxy requests via \`/mobify/proxy/\` + +### Special Components +- Components starting with \`_\` are special PWA Kit components +- \`_app-config\`: Top-level app configuration +- \`_app\`: Persistent layout (header, footer, sidebar) +- \`_error\`: 404 and error pages + +## Development Rules +- Use kebab-case for file names (except special components with \`_\`) +- Use Chakra UI and existing components +- Create modular, reusable components +- Use React Hooks for state management +- Access data via commerce-sdk-react hooks +- Ensure mobile-friendly and accessible components +- Maintain consistent code formatting using project standards +- Write comprehensive test coverage ` export default { diff --git a/packages/pwa-storefront-mcp/src/utils/pwa-developer-guideline-tool.test.js b/packages/pwa-storefront-mcp/src/utils/pwa-developer-guideline-tool.test.js index 3945affad1..dfd92d09b5 100644 --- a/packages/pwa-storefront-mcp/src/utils/pwa-developer-guideline-tool.test.js +++ b/packages/pwa-storefront-mcp/src/utils/pwa-developer-guideline-tool.test.js @@ -27,7 +27,7 @@ describe('PWA Development Guidelines', () => { { type: 'text', text: expect.stringContaining( - 'Salesforce Commerce Composable Storefront Development Guidelines' + 'Commerce Composable Storefront Development Guidelines' ) } ] @@ -41,9 +41,8 @@ describe('PWA Development Guidelines', () => { const requiredSections = [ 'Overview', 'Core Principles', - 'Technical Stack', - 'PWK Kit Architecture', - 'Quality Standards' + 'PWA Kit Essentials', + 'Development Rules' ] requiredSections.forEach((section) => { diff --git a/packages/template-retail-react-app/.cursor/rules/accessibility-rule.mdc b/packages/template-retail-react-app/.cursor/rules/accessibility-rule.mdc new file mode 100644 index 0000000000..0c0b40a403 --- /dev/null +++ b/packages/template-retail-react-app/.cursor/rules/accessibility-rule.mdc @@ -0,0 +1,8 @@ +--- +description: Check and verify accessibility on local project +globs: +alwaysApply: false +--- +To check accessibility of a project, use the accessibility rules defined in ./cursor-accessibility-mdc/ directory. +Run an automated scan for the entire codebase within the project and check for any violations. +Show the scanned results in summary and detailed violations if any. \ No newline at end of file diff --git a/packages/template-retail-react-app/.cursor/rules/cursor-accessibility-mdc/accessibility-button-name.mdc b/packages/template-retail-react-app/.cursor/rules/cursor-accessibility-mdc/accessibility-button-name.mdc new file mode 100644 index 0000000000..e7e9e2b063 --- /dev/null +++ b/packages/template-retail-react-app/.cursor/rules/cursor-accessibility-mdc/accessibility-button-name.mdc @@ -0,0 +1,26 @@ +--- +description: When accessibility is checked. Check if Buttons must have a discernible name using text or aria attributes +globs: +alwaysApply: false +--- + +# Rule: accessibility-button-name + +Buttons must have a discernible name using text or aria attributes + +## 🔍 Pattern + +```regex +]*\b(aria-label|aria-labelledby|title|name)=) +``` + +## 📍 Examples + +```tsx +// ❌ Bad + +// ✅ Good + +// ✅ Good + +``` diff --git a/packages/template-retail-react-app/.cursor/rules/cursor-accessibility-mdc/accessibility-heading-order.mdc b/packages/template-retail-react-app/.cursor/rules/cursor-accessibility-mdc/accessibility-heading-order.mdc new file mode 100644 index 0000000000..e8dc617420 --- /dev/null +++ b/packages/template-retail-react-app/.cursor/rules/cursor-accessibility-mdc/accessibility-heading-order.mdc @@ -0,0 +1,26 @@ +--- +description: When accessibility is checked. Check if heading levels should increase sequentially for semantic structure +globs: +alwaysApply: false +--- + +# Rule: accessibility-heading-order + +Heading levels should increase sequentially for semantic structure + +## 🔍 Pattern + +```regex + +``` + +## 📍 Examples + +```tsx +// ❌ Bad +

Main Title

+

Subsection

+// ✅ Good +

Main Title

+

Subsection

+``` diff --git a/packages/template-retail-react-app/.cursor/rules/cursor-accessibility-mdc/accessibility-image-alt.mdc b/packages/template-retail-react-app/.cursor/rules/cursor-accessibility-mdc/accessibility-image-alt.mdc new file mode 100644 index 0000000000..fbea04b3fe --- /dev/null +++ b/packages/template-retail-react-app/.cursor/rules/cursor-accessibility-mdc/accessibility-image-alt.mdc @@ -0,0 +1,24 @@ +--- +description: When accessibility is checked. Ensure all tags include descriptive alt attributes +globs: +alwaysApply: false +--- + +# Rule: accessibility-image-alt + +Ensure all tags include descriptive alt attributes + +## 🔍 Pattern + +```regex +]*\balt=) +``` + +## 📍 Examples + +```tsx +// ❌ Bad + +// ✅ Good +Company logo +``` diff --git a/packages/template-retail-react-app/.cursor/rules/cursor-accessibility-mdc/accessibility-input-label.mdc b/packages/template-retail-react-app/.cursor/rules/cursor-accessibility-mdc/accessibility-input-label.mdc new file mode 100644 index 0000000000..736fb0d739 --- /dev/null +++ b/packages/template-retail-react-app/.cursor/rules/cursor-accessibility-mdc/accessibility-input-label.mdc @@ -0,0 +1,27 @@ +--- +description: When accessibility is checked. Check if Input fields must have a label or aria-label for screen readers +globs: +alwaysApply: false +--- + +# Rule: accessibility-input-label + +Input fields must have a label or aria-label for screen readers + +## 🔍 Pattern + +```regex +]*(aria-label|aria-labelledby|id=)) +``` + +## 📍 Examples + +```tsx +// ❌ Bad + +// ✅ Good + +// ✅ Good with label + + +``` diff --git a/packages/template-retail-react-app/.cursor/rules/cursor-accessibility-mdc/accessibility-link-name.mdc b/packages/template-retail-react-app/.cursor/rules/cursor-accessibility-mdc/accessibility-link-name.mdc new file mode 100644 index 0000000000..3d12ed311e --- /dev/null +++ b/packages/template-retail-react-app/.cursor/rules/cursor-accessibility-mdc/accessibility-link-name.mdc @@ -0,0 +1,26 @@ +--- +description: When accessibility is checked. Check if Anchor tags must have accessible names +globs: +alwaysApply: false +--- + +# Rule: accessibility-link-name + +Anchor tags must have accessible names + +## 🔍 Pattern + +```regex +]*\b(aria-label|aria-labelledby|title)=)(?![^>]*>\s*\w+\s*) +``` + +## 📍 Examples + +```tsx +// ❌ Bad + +// ✅ Good +Your Profile +// ✅ Good + +``` diff --git a/packages/template-retail-react-app/.cursor/rules/cursor-rule.mdc b/packages/template-retail-react-app/.cursor/rules/cursor-rule.mdc new file mode 100644 index 0000000000..774d83ff2c --- /dev/null +++ b/packages/template-retail-react-app/.cursor/rules/cursor-rule.mdc @@ -0,0 +1,66 @@ +--- +description: How to add or edit Cursor rules in our project +globs: +alwaysApply: false +--- +# Cursor Rules Location + +How to add new cursor rules to the project + +1. Always place rule files in PROJECT_ROOT/.cursor/rules/: + ``` + .cursor/rules/ + ├── your-rule-name.mdc + ├── another-rule.mdc + └── ... + ``` + +2. Follow the naming convention: + - Use kebab-case for filenames + - Always use .mdc extension + - Make names descriptive of the rule's purpose + +3. Directory structure: + ``` + PROJECT_ROOT/ + ├── .cursor/ + │ └── rules/ + │ ├── your-rule-name.mdc + │ └── ... + └── ... + ``` + +4. Never place rule files: + - In the project root + - In subdirectories outside .cursor/rules + - In any other location + +5. Cursor rules have the following structure: + +```` +--- +description: Short description of the rule's purpose +globs: optional/path/pattern/**/* +alwaysApply: false +--- +# Rule Title + +Main content explaining the rule with markdown formatting. + +1. Step-by-step instructions +2. Code examples +3. Guidelines + +Example: +```typescript +// Good example +function goodExample() { + // Implementation following guidelines +} + +// Bad example +function badExample() { + // Implementation not following guidelines +} +``` +```` \ No newline at end of file diff --git a/packages/template-retail-react-app/.cursor/rules/development-guidelines.mdc b/packages/template-retail-react-app/.cursor/rules/development-guidelines.mdc new file mode 100644 index 0000000000..31626aa03b --- /dev/null +++ b/packages/template-retail-react-app/.cursor/rules/development-guidelines.mdc @@ -0,0 +1,40 @@ +--- +description: Salesforce Commerce Composable Storefront Development Guidelines +globs: +alwaysApply: false +--- + +# Commerce Composable Storefront Development Guidelines + +## Overview +Guidelines for Salesforce Commerce Composable Storefront development using PWA Kit, Retail React App, and Chakra UI. + +## Core Principles +- Analyze requirements and existing codebase thoroughly +- Use existing components and hooks when possible +- Plan before implementing +- Test comprehensively with Jest + +## PWA Kit Essentials + +### Architecture +- Server-side rendering (SSR) for initial loads +- Client-side rendering (CSR) for interactions +- Isomorphic code (works on server and client) +- Proxy requests via `/mobify/proxy/` + +### Special Components +- Components starting with `_` are special PWA Kit components +- `_app-config`: Top-level app configuration +- `_app`: Persistent layout (header, footer, sidebar) +- `_error`: 404 and error pages + +## Development Rules +- Use kebab-case for file names (except special components with `_`) +- Use Chakra UI and existing components +- Create modular, reusable components +- Use React Hooks for state management +- Access data via commerce-sdk-react hooks +- Ensure mobile-friendly and accessible components +- Maintain consistent code formatting using project standards +- Write comprehensive test coverage diff --git a/packages/template-retail-react-app/.cursor/rules/page-creation.mdc b/packages/template-retail-react-app/.cursor/rules/page-creation.mdc new file mode 100644 index 0000000000..a36d503e30 --- /dev/null +++ b/packages/template-retail-react-app/.cursor/rules/page-creation.mdc @@ -0,0 +1,16 @@ +--- +description: Page Creation Rule - automatically apply when user asks to create new page, add page, make page, build page, generate page +globs: +alwaysApply: false +--- +USE WHEN create a new page, add a new page, make a new page, build a new page, generate a new page, create page, add page, make page, build page, generate page + +**Mandatory** +- DO ask user to clarify page name and page route before proceed +- ONLY Create a bare minimum page component +- Do NOT include other project components or hooks unless specifically requested +- Do NOT add extra styling, layout, or features unless explicitly asked + +## Implementation Steps +1. Create simple component in `app/pages/[page-name]/index.jsx` +2. Add route to `app/routes.jsx` \ No newline at end of file