App Bridge - Cursor AI Project Rule

---
description: Shopify App Bridge – Best-practice rules for Cursor AI
globs:
  - "src/**/*.{js,jsx,ts,tsx}"
alwaysApply: true
---

## 1. App Bridge & Polaris Integration

- **Single Provider**:  
  - Wrap the entire React tree in one App Bridge Provider.  
  - Create the App instance only once, at the root.  
  - Polaris `<AppProvider>` must wrap the app, outside App Bridge.

- **useAppBridge Hook**:  
  - In function components, obtain the instance with `useAppBridge()`.  
  - Never use or reference a global App Bridge singleton.

- **Official UI Components**:  
  - Use App Bridge UI components (`Modal`, `ResourcePicker`, `TitleBar`, `NavigationMenu`, `ContextualSaveBar`, `Toast`) for admin interactions.  
  - Avoid custom iframe overlays for these patterns.

- **Contextual Save Bar**:  
  - Show a Save Bar only while the resource is dirty; hide it once the save succeeds.

- **Loading & Toast**:  
  - Indicate progress with `loading.start()/stop()`.  
  - Provide feedback with `toast.show()`.

## 2. API & Data

- **Authenticated Fetch**:  
  - Send all API calls through `authenticatedFetch(app)` (v3) or v4's auto-injected `fetch`.  
  - Always include session tokens; treat third-party cookies as unreliable.  
  - On 401, trigger re-auth and retry.

## 3. Code Structure & Standards

- **Component Structure**:  
  - Define `Props` at the top.  
  - Use named exports.  
  - Organize imports clearly.

- **TSDoc**:  
  - Add TSDoc comments for all new public functions, components, and types.

- **Feature Toggles**:  
  - Wrap risky or in-progress features behind `process.env.FEATURE_*` toggles.

## 4. Workflow & AI Guardrails

- **Pre-Finalization**:  
  - Ensure `tsc --noEmit` passes before finalizing changes.  
  - Update or add Jest tests for every edited function; all tests must pass.

- **App Bridge Additions**:  
  - Place new App Bridge calls only at `// TODO(ai):` markers unless told otherwise.  
  - If no marker exists, use best judgment or ask for clarification.

- **Commit Messages**:  
  - Use the format `<scope>: <imperative summary>` (e.g., `app-bridge: migrate to v4 fetch`).

- **Changelog & Rollback**:  
  - Update `CHANGELOG.md` (Keep-a-Changelog format) and `rollback.md` for every deploy.

- **Smoke Test Prompt**:  
  - After refactors, run an embedded-store smoke test: navigation renders, modal opens, session-token requests succeed.

## 5. Versioning

- **App Bridge**:  
  - Pin `@shopify/app-bridge*` to the current minor (`^4.x`).  
  - Follow the official Shopify migration guide before major upgrades.

## 6. Ask-Before-Act

- Seek clarification before touching auth flow, major dependencies, or core App Bridge/Polaris setup.