Ratings extension tutorial

Navigate to Cursor > Settings > Cursor Settings > Tools & MCP and verify that the commerce-extensibility toolset is enabled without errors. If you see errors, toggle the toolset off and on.

{width="600" modal="regular"}

Disable any documentation in Cursor’s context:

• Navigate to Cursor > Settings > Cursor Settings > Indexing & Docs and delete any documentation listed.

{width="600" modal="regular"}

Generate code for a product ratings extension:

• From the Cursor chat window, select Agent mode.
• Enter the following prompt:

Implement an Adobe Commerce as a Cloud Service extension to handle Product Ratings.

Implement a REST API to handle GET ratings requests.

GET requests will have to support the following query parameters:

sku -> product SKU

Answer the agent’s questions precisely to help it generate the best code.

{width="600" modal="regular"} {width="600" modal="regular"}

Use the following example text to answer the agent’s questions to set up randomized ratings data:

Yes, this headless extension is for Adobe Commerce as a Cloud Service storefront,
but we do not need any authentication for the GET API because guest users should be able to use it on the storefront.

This extension is called directly from the storefront, no async invocation, such as events or webhooks, is required.

Start with just the GET API for now, we will implement other CRUD operations at a later time.

We do not need a DB or storage mechanism right now, just return random ratings data between 1 and 5 and a ratings count between 1 and 1000.

The API should only return the average rating for the product and the total number of ratings.
We do not need to add tests right now.

The agent creates a requirements.md file that serves as the source of truth for the implementation.

{width="600" modal="regular"}

Review the requirements.md file and verify the plan.

If everything looks correct, instruct the agent to move to Phase 2 - Architecture Planning.

Review the architecture plan.

Instruct the agent to proceed with code generation.

The agent generates the necessary code and provides a detailed summary with your next steps.

{width="600" modal="regular"} {width="600" modal="regular"} {width="600" modal="regular"}

Ask the agent to help you test the code locally.

Test the ratings API locally on a dev server using cURL.

Follow the agent’s instructions and confirm that the API is working locally.

{width="600" modal="regular"} {width="600" modal="regular"}

After verifying the generated code, deploy the extension using the following prompt:

Deploy the ratings API.

The agent performs a pre-deployment readiness assessment before deploying.

{width="600" modal="regular"}

When you are confident with the assessment results, instruct the agent to proceed with deployment.

The agent uses the MCP toolkit to verify, build, and deploy automatically.

{width="600" modal="regular"}

Navigate to the storefront folder:

cd storefront

Open the storefront folder in a new Cursor window.

Alternatively, if you have the Cursor CLI installed, open the window by using the following command in your terminal:

cursor .

Start the local development server:

npm run start

In a browser, navigate to a product page:

http://localhost:3000/products/llama-plush-shortie/adb336

Observe the boilerplate storefront product detail page (PDP) and note the lack of visual product ratings.

Use the following prompt with your agent:

Integrate the ratings API into the PDP to show star ratings and a review count for products. Here's the service contract: @RATINGS_API_CONTRACT.md

The agent assesses the task complexity and invokes a phased workflow. During Phase 1 (Requirements Gathering), the agent creates a requirements document and asks clarifying questions such as:

• Where on the PDP should ratings appear?
• Should this be a new standalone block, or a slot customization inside the existing PDP drop-in component?
• What should the fallback be if the API is unavailable or returns no data?
• Should ratings appear on the PLP (product listing) as well, or PDP only?
• Are there any design specs or mockups?

Answer these questions based on your project requirements. The agent updates the requirements document and marks the phase as complete.

During Phase 2 (Architectural Planning), the agent researches documentation and your codebase before proposing an architecture. Expect the agent to:

• Search Commerce documentation for PDP drop-in containers, slots, and event payloads.
• Scan your blocks directory and scripts/initializers/ folder for existing PDP-related code.
• Explore TypeScript definitions for available containers and slot context shapes.

The agent then presents architecture options such as:

• Option A: Customize an existing PDP drop-in slot to inject ratings near the product title — a lighter touch that is upgrade-friendly.
• Option B: Create a new standalone product-ratings block that fetches from the API independently — more flexible and decoupled.
• Option C: Create a new block that also listens to PDP drop-in events for the product SKU — a hybrid approach.

The plan also includes details on API integration, performance considerations (lazy loading, caching), security (input sanitization), and a testing approach.

Review the architecture plan and instruct the agent to proceed.

During Phase 3 (Implementation Approach), the agent asks you to choose between:

• Option A: Review a detailed implementation plan before code generation (see all files, patterns, and code structure first).
• Option B: Proceed directly to code generation.

Select your preferred approach.

During Phase 4 (Implementation), the agent generates code based on the chosen architecture. Depending on the approach, the agent uses several specialized skills:

• Content modeling: If a new block is needed, the agent designs an author-friendly content structure, such as a configuration table with the API endpoint URL.
• Block development: The agent creates block files following Edge Delivery Services conventions, including JavaScript decoration functions, scoped CSS styles, ARIA labels for accessibility, and loading and error state handling.
• Drop-in customization: If the architecture uses slot customization, the agent imports the correct container, uses a verified slot near the product title, and subscribes to product data events for the current SKU.

Watch the code being generated and ask questions or redirect the agent as needed. The agent produces a production readiness summary when code generation completes.

During Phase 4.5 (Testing), the agent offers to test the implementation. If you accept, the agent:

• Creates a local test page with the proper scripts and styles.
• Starts a development server.
• Runs browser-based verification for visual rendering, interactivity, responsive behavior, accessibility, and performance.
• Generates a structured test report with the results.

Follow along in the browser to confirm the behavior and report any issues.

Observe the changes in the codebase, and watch the product page for updates.

You should see the following changes in your development environment and browser:

• A product rating component is automatically created.
• The component is integrated into the PDP using drop-in slots or as a standalone block, depending on the chosen architecture.
• Stars display with proper fill proportions based on the rating values from your API.

{width="600" modal="regular"}

Before starting: Save the following mock image and paste it into the chat with your storefront agent.

{width="600" modal="regular"}

Follow these steps to create the ratings distribution modal using the reference image as a guide:

• Update the API to return additional data representing the ratings distribution.
• Update the API contract.
• Update the contract in the storefront codebase.
• Ask the storefront agent to use the reference image and updated API contract to add the ratings distribution to the PDP page.

Observe the following changes in the codebase, and watch the product page for updates:

• How the agent interprets the visual mockup
• Whether it uses appropriate HTML structure for accessibility
• How it handles the positioning and interaction states