FEAT: DVR-292 | Prompts to create new example apps (#2615)

Co-authored-by: Craig M. <[email protected]>

Author: darrenmelvison1

examples/README.md

@@ -21,16 +21,17 @@
 - [Contribution guidelines](#contribution-guidelines)
 - [Adding examples](#adding-examples)
 - [End to end testing](#end-to-end-testing)
+- [Generating examples apps using Cursor](#generating-example-apps-using-cursor)
 - [Using code examples in the docs site](#using-code-examples-in-the-docs-site)
-- [Generating Tutorials and Metadata](#generating-tutorials-and-metadata)
+- [Generating Tutorials and Metadata with cursor](#generating-tutorials-and-metadata-with-cursor)
 
 <hr />
 
 # Introduction
 
 The example apps in this examples directory are compiled and tested as part of our CI CD pipeline. The goal of this is to ensure the examples found here are always able to run against the latest version of the Immutable Typescript SDK. 
 
-Selected portions of code from these example apps are then displayed as code snippets in our docs site, which means our code snippets in the docs are inherently always accurate as well. How to include the code from here in the docs site is explained below. 
+Selected portions of code from these example apps are then displayed as code snippets in our docs site, which means our code snippets in the docs are inherently always accurate as well. How to include the code from here in the docs site is explained below.
 
 These example apps can also be used directly as a reference and run locally to test and develop with.
 
@@ -325,6 +326,95 @@ Run your tests
 ```bash
 pnpm test
 ```
+
+# Generating example apps using cursor
+
+1) Open the product folder under /examples/{product}
+
+2) Under the {product} directory, open the prompt-part2.txt file.
+
+3) Copy all of the content in the prompt-part2.txt file.
+
+4) Paste it on to Cursor. Make sure that you're using Agent mode and the model to be used is Claude 3.7 (Thinking)
+
+5) After pasting the prompt, in the chat window you can type: 
+app name: <app name(if exists)>
+feature name: <name of the feature>
+and cursor will generate the feature page in the given app.
+
+6) To update an existing feature, the prompt will identify if the given <feature name> exists in the <app name> directory. If it does, it will check if 
+the <feature name> has the manually-edited field value as true in the feature.json file.
+
+7) If the flag above exists, it will ask for a confirmation, otherwise, it will use best practices to update the existing feature page.
+
+8) Once the feature page is completed, under the same directory as prompt-part2.txt, open prompt-part3.txt and copy all of its contents.
+
+9) Paste it on to a new Cursor window and in the chat window you can type: 
+
+feature name: <name of the feature>
+
+Here, cursor will check and fix pages with styling issues to ensure that it looks consistent with other example apps.
+
+10) Once the styling changes have been made, under the same directory as prompt-part2.txt, open prompt-part4.txt and copy all of its contents.
+
+11) Paste it on to a new Cursor window and in the chat window you can type: 
+app name: <app name(if exists)>
+feature name: <name of the feature>
+
+12) Cursor will then run tests and build until everything passes and renders properly.
+
+13) When the prompt is done running, make sure to double check if the tests are comprehensive enough and also check if the feature page was built properly using best practices.
+
+14) Run `pnpm dev` and check every page's styling. If something looks off, you can manually fix it.
+
+## If an App Doesn't Exist Yet
+
+You must create the app first by going to the prompt-part1.txt file and paste it on to Cursor's chat window and use Agent Mode + Claude 3.7 Sonnet Thinking.
+
+In the chat window, type in:
+feature name: <name>
+
+Then Cursor will build out the example app's setup, etc.
+IF Cursor doesn't run build at the end, manually type on the chat window 'run build'.
+
+IMPORTANT: For any prompts, if cursor is not done with its operations but it has reached 25 tool calls, you will need to manually type "continue" on the chat window for cursor to continue building.
+
+## Understanding the Prompt Files
+
+The example generation process uses three different prompt files, each with a specific purpose:
+
+### prompt-part1.txt
+- **Purpose**: Creates the initial app structure and boilerplate
+- **When to use**: Only when you need to create a completely new example app
+- **What it does**: Sets up the project structure, configuration files, basic components, and placeholder pages
+- **Output**: A functioning but minimal app with no implemented features
+
+### prompt-part2.txt
+- **Purpose**: Implements or updates a specific feature within an existing app
+- **When to use**: After creating an app with prompt-part1.txt, or when adding/updating features
+- **What it does**: Creates or modifies the feature implementation with proper error handling, UI states, and best practices
+- **Output**: A fully implemented feature page within the app structure
+
+### prompt-part3.txt
+- **Purpose**: Apply styling changes to the given example app if possible to ensure styling consistency with other example apps
+- **When to use**: After running prompt-part2.txt to implement a feature
+- **What it does**: Modifies the example app's UI/UX to ensure that the app looks consistent with other example apps
+- **Output**: A fully implemented feature page within the app structure with consistent UI/UX looks.
+
+### prompt-part4.txt
+- **Purpose**: Tests, validates, and fixes issues in the implementation
+- **When to use**: After running prompt-part2.txt to implement a feature
+- **What it does**: Runs tests, checks coverage, builds the app, and fixes any detected issues
+- **Output**: A tested, validated feature ready for use
+
+**Typical Workflow:**
+1. Use prompt-part1.txt to create a new app (only once per app)
+1. Use prompt-part2.txt to implement each feature in the app
+1. Use prompt-part3.txt to fix the app's UI/UX styling and make it look consistent to other example apps.
+1. Use prompt-part4.txt after each feature implementation to test and validate
+1. Once you've generated the example app or feature, you should manually review the implementation and the UI. It's likely you will need to make some manual adjustments to get the app to function and look like our other example apps because the cursor can not reliably get it 100% correct. 
+1. Once you're happy with your example app or feature, you need to [re-run the tutorial generation prompt](#generating-tutorials-and-metadata-with-cursor) for your example app before creating your PR so the new example app or feature is piped into the docs site with it's corresponding tutorial.
+
 # Using code examples in the docs site
 
 Creating and using code snippets is relatively straight forward. You can pull in a whole file or by adding some comments you can pull in just a particular few lines of a file as necessary.
@@ -369,7 +459,6 @@ It's very simple to use the code snippet in the docs site, you just add a code b
 ````md
 ```tsx reference=examples/checkout/sdk-connect-with-nextjs/src/app/connect-with-metamask/page.tsx#get-wallet-allow-list title="Get the wallet allow list"
 ```
-```
 ````
 Or if you want to display the whole file just don't include a `#` label at the end of the file reference e.g.
 
@@ -416,7 +505,7 @@ Once your `docs` PR is merged, Netlify should automatically build and deploy the
 
 If this happens you will need to log into the Netlify site, check the error and retry the build. Usually this will fix the deployment issue, otherwise follow up on the error message shown by Netlify.
 
-# Generating Tutorials and Metadata
+# Generating tutorials and metadata with cursor
 
 Whenever you add a new example app, or update an existing example app, you can use the prompts in the `prompt.txt` files in each `examples/product` folder to generate the tutorials and metadata for the example apps using Cursor AI.
 

examples/checkout/prompt-part1.txt

@@ -0,0 +1,193 @@
+## Immutable Checkout SDK Example App Generator - Part 1: Create the App
+
+Make sure to always write tests first. You must do Test Driven Development.
+# Overview
+This prompt helps you create a new React example app that demonstrates the {feature name} feature of the Immutable Checkout SDK. The output will be a fully functional, self-contained example with proper documentation and adherence to best practices.
+
+# App Information
+- Feature name: {feature name}
+- Framework: nextjs
+
+## UI Best Practices
+- Always ensure that you ONLY use available Biom3 Components without assuming they exist. (Text and Spinner DOES NOT exist in the Biom3 UI Library)
+- Use standard HTML elements (h1, h2, h3, p) for text content. 
+- Use Biom3 Button and other UI components as documented
+- Show clear loading/error states
+- Keep UI simple and focused on demonstrating the {feature name}
+
+## Critical Error Prevention
+- Always check if objects exist before accessing their properties or methods
+- Use optional chaining when accessing potentially undefined properties: obj?.prop?.method?.()
+- Wrap all {feature name} setup and teardown in try/catch blocks
+- Test component mounting/unmounting thoroughly to catch cleanup issues
+
+## ALWAYS READ THIS BEFORE YOU DO ANYTHING
+- DO NOT call methods that don't exist on the SDK instances
+- DO NOT try to import types that aren't explicitly exported
+- DO NOT forget to clean up {feature name} setup and teardown
+- DO NOT use custom components or providers unless necessary
+- DO NOT modify dependency versions in package.json
+- DO NOT use inconsistent import methods (mixing default and named imports)
+- DO NOT forget to include 'use client' directive in client components
+- DO NOT assume any property or method exists without checking first 
+- DO NOT MAKE ANY TUTORIAL/METADATA FILE FOR THE {feature name} EXAMPLE APP
+- NEVER ADD `"ignoreDuringBuilds": true` TO .eslintrc.json 
+- ALways do lint checks and never turn it off when building.
+- NEVER FORGET TO RUN BUILD ONCE YOU'RE DONE WITH EVERYTHING ELSE. THIS IS VERY VERY VERY IMPORTANT TO ENSURE THAT EVERYTHING WORKS.
+
+
+# Step 1: Core Setup
+Create a new example app named {feature name}-with-nextjs in /examples/checkout/ with this structure:
+
+```
+/examples/checkout/{feature name}-with-nextjs/
+├── src/app/
+│ ├── page.tsx # Main landing page with feature links
+│ ├── {feature name}/page.tsx # Primary feature implementation
+│ ├── redirect/page.tsx # Auth redirect handler
+│ ├── logout/page.tsx # Logout functionality
+│ ├── utils/ # Shared utilities
+│ │ ├── setupDefault.ts # SDK initialization
+│ │ └── wrapper.tsx # App context wrapper
+│ ├── layout.tsx # App layout with wrapper
+│ └── globals.css # Basic styles
+├── tests # Test directory
+│ └── base.spec.ts # E2E Test file
+├── README.md # Documentation
+├── package.json # Dependencies
+├── next.config.mjs # Next.js config
+├── tsconfig.json # TypeScript config
+├── .env.example # Environment variables
+├── .gitignore # Git ignore file
+├── playwright.config.ts # Playwright configuration
+|── eslintrc.json                   # ESLint configuration
+|── babel.config.jest.js            # Babel config for tests
+└── features.json                   # JSON file showcasing the feature present in the {feature name} app
+```
+Copy these essential files from an existing example (e.g., login-with-nextjs):
+- package.json (update the name to "{feature name}-with-nextjs", but keep ALL dependency versions the same)
+- next.config.mjs
+- tsconfig.json
+- .env.example
+- .gitignore
+- src/app/utils/setupDefault.ts
+- src/app/utils/wrapper.tsx
+- src/app/layout.tsx (modify to use AppWrapper)
+- src/app/globals.css
+- playwright.config.ts
+- .eslintrc.json
+
+IMPORTANT: Ensure that you've gone through the Checkout SDK Documentation and have a very deep understanding of the SDK before you start.
+IMPORTANT: We have an internal UI Library called Biom3. Make sure that you thoroughly understand all of the components. DON'T ASSUME that a component exists. ALWAYS DOUBLE CHECK BEFORE YOU IMPORT OR USE ANYTHING
+IF THE COMPONENT THAT YOU WANT DOESN'T EXIST IN BIOM3, ALWAYS USE NORMAL CSS/HTML AND NEVER ASSUME. (https://github.com/immutable/biom3 | https://immutable.atlassian.net/wiki/spaces/DS/pages/2335965298/BIOME+Docs)
+
+# Step 2: Features.json creation (IMPORTANT: This must be done before you make components, etc. Without this file, you're not allowed to make components/pages.)
+Take a look at another example apps' (such as login-with-nextjs) features.json file and understand the structure.
+Once that's done, create the features.json file in the {feature name} example app root directory
+Make sure that IF {feature name} is to showcase login functionality, set silent-login/silent-logout to false. Otherwise, set it to true.
+The feature name in the features.json file will always be {feature name}
+The manually-edited field will always be false if you're the one who's generating the feature.
+Set the order field to be {total number of apps under product (e.g. Checkout, checkout, etc)} + 1
+
+# Step 3: Testing Files
+COPY OVER THE RELEVANT E2E TEST FILES (INCLUDING SETUP, ETC) FROM OTHER EXAMPLE APPS SUCH AS LOGIN-WITH-NEXTJS
+
+- Add the following dependencies to package.json:
+  - @playwright/test
+
+- Test all pages renders perfectly
+- Test {feature name} functionality thoroughly with all possible scenarios. (If it's Checkout specific, this is not required)
+- Test all {feature name} handling and cleanup
+- Explicitly validate that components render without errors
+- Use act() for all asynchronous operations
+
+# Step 4: Component Implementation
+
+## Critical Import/Export Requirements
+For ALL component files:
+- ALWAYS use default exports for page components (export default function ComponentName)
+- ALWAYS import React explicitly if using JSX fragments (<>...</>): import React from 'react'
+- Verify all imports are correctly spelled and point to existing files
+- When importing from libraries, verify the component exists in that library
+- For Next.js client components, always include 'use client' at the top of the file
+
+IMPORTANT: MAKE SURE THAT THE Checkout SDK IS INITIALIZED CORRECTLY IN THE SETUPDEFAULT.TS FILE. REFER TO OTHER EXAMPLE APPS LIKE LOGIN-WITH-NEXTJS FOR THE CORRECT SETUP.
+IMPORTANT: DON'T IMPLEMENT THE {feature name} AT ALL. JUST SETUP THE PROJECT STRUCTURE AND DOCUMENTATION.
+
+## Main Landing Page (src/app/page.tsx)
+Create a simple landing page with:
+- Brief description of the Checkout {feature name} features
+- Link to the {feature name} implementation page
+- Clear, concise UI using standard HTML (h1, h2, p) and Biom3 Button components
+
+## Redirect and Logout Pages
+Create minimal, functional redirect and logout pages:
+- Ensure the redirect page properly handles the authentication callback
+- Implement robust error handling for failed auth callbacks
+- For the logout page, implement proper token cleanup
+- VERIFY that all components used in these pages are properly imported
+
+## Feature Implementation (src/app/{feature name}/page.tsx)
+- THIS PAGE SHOULD JUST BE A PLACEHOLDER FOR NOW. IT SHOULD NOT IMPLEMENT ANY FUNCTIONALITY.
+
+## setupDefault modification (If Applicable)
+- Go to the features.json file and check for the silent logout field.
+- If {feature name} has the silent logout field as true, ensure that the 'logoutMode' field in the setupDefault file is set to 'silent'
+
+## Silent Login mode (If Applicable)
+- Go to the features.json file and check for the silent login field.
+- If {feature name} has the silent login field as true, go through all of the pages in the app and change all login modes to silent login.
+
+# Step 5: Documentation
+IMPORTANT: Ensure that the command for installation, etc uses pnpm not npm.
+Create a comprehensive README.md including:
+- {feature name} feature description and purpose
+- Setup instructions including environment variables
+- Usage instructions with code examples for all {feature name} types
+- Common issues and troubleshooting
+- References to official documentation
+- {feature name} cleanup best practices
+
+# Step 6: Implementation Guidelines
+IMPORTANT: MAKE SURE THAT THE Checkout SDK IS INITIALIZED CORRECTLY IN THE SETUPDEFAULT.TS FILE. REFER TO OTHER EXAMPLE APPS LIKE LOGIN-WITH-NEXTJS FOR THE CORRECT SETUP.
+## SDK Usage Best Practices
+- Use only documented public SDK methods
+- If using internal properties, document with comments and type assertions
+- Always implement proper cleanup in useEffect hooks
+- Use local type definitions instead of importing non-exported types
+- Add robust error handling for all {feature name} and operations
+- Add TypeScript type guards for any SDK properties that might be undefined
+
+# Step 7: Final Checks
+- Ensure that the app can build.
+- Ensure that all of the components, etc are used appropriately.
+- run `pnpm build` and ensure that the setup is perfect.
+- Ensure that there's no problem in all files. Make sure that when using a component, you use the available properties and values.
+- Features.json exists and everything make sense
+- Always check for the login/logout mode if they are consistent with the features.json file.
+
+## UI Best Practices
+- Always ensure that you ONLY use available Biom3 Components without assuming they exist. (Text and Spinner DOES NOT exist in the Biom3 UI Library)
+- Use standard HTML elements (h1, h2, h3, p) for text content. 
+- Use Biom3 Button and other UI components as documented
+- Show clear loading/error states
+- Keep UI simple and focused on demonstrating the {feature name}
+
+## Critical Error Prevention
+- Always check if objects exist before accessing their properties or methods
+- Use optional chaining when accessing potentially undefined properties: obj?.prop?.method?.()
+- Wrap all {feature name} setup and teardown in try/catch blocks
+- Test component mounting/unmounting thoroughly to catch cleanup issues
+
+## ALWAYS READ THIS BEFORE YOU DO ANYTHING
+- DO NOT call methods that don't exist on the SDK instances
+- DO NOT try to import types that aren't explicitly exported
+- DO NOT forget to clean up {feature name} setup and teardown
+- DO NOT use custom components or providers unless necessary
+- DO NOT modify dependency versions in package.json
+- DO NOT use inconsistent import methods (mixing default and named imports)
+- DO NOT forget to include 'use client' directive in client components
+- DO NOT assume any property or method exists without checking first 
+- DO NOT MAKE ANY TUTORIAL/METADATA FILE FOR THE {feature name} EXAMPLE APP
+- NEVER ADD `"ignoreDuringBuilds": true` TO .eslintrc.json 
+- ALways do lint checks and never turn it off when building.