Cursor Rules for Shopify Remix App Template

gistfile1.txt

# Cursor Rules for Shopify Remix App Template

## Project Context & Core Technologies

1.  **Identify the Stack:** Recognize that this project is a Shopify App built using the Remix framework, Bun, TypeScript, React, Prisma (usually), and Shopify's Polaris component library.
2.  **Key Files:** Be aware of critical configuration and setup files:
    *   `shopify.app.toml`: Main app configuration.
    *   `remix.config.js`: Remix configuration.
    *   `prisma/schema.prisma`: Database schema definition.
    *   `app/shopify.server.ts`: Server-side Shopify utilities (authentication, API clients, webhook registration, billing).
    *   `app/root.tsx`: Root layout component.
    *   `app/entry.server.tsx` & `app/entry.client.tsx`: Server and client entry points.
3.  **Primary Language:** Use TypeScript for all code generation and modifications. Ensure strong typing wherever possible.

## Shopify Integration Rules

4.  **Admin API:**
    *   **Authentication:** Always use the authenticated `admin` GraphQL client provided by `shopify.server.ts` (typically passed via loader/action context) for interacting with the Shopify Admin API.
    *   **Preference:** Prefer the **GraphQL Admin API** over the REST Admin API unless REST is strictly necessary or significantly simpler for a specific task.
    *   **Context:** Expect the authenticated Shopify context (containing `admin`, `session`, `billing` etc.) to be available within Remix `loader` and `action` functions.
5.  **UI Components (Polaris):**
    *   **Mandatory Use:** For *all* UI within the embedded Shopify Admin section (routes under `/app`), **exclusively use React components from `@shopify/polaris`**.
    *   **Styling:** Ensure Polaris CSS is correctly imported (usually handled in `root.tsx` or relevant layout files). Do not introduce custom global stylesheets that conflict with Polaris unless absolutely necessary and scoped.
    *   **Layout:** Utilize Polaris layout components (`Page`, `Layout`, `Card`, `BlockStack`, `InlineStack`, etc.) for proper structure within the Shopify Admin iframe.
6.  **Frontend Interactions (App Bridge):**
    *   Use `@shopify/app-bridge-react` for interacting with the Shopify Admin frontend from within your embedded app.
    *   Common uses: `useAppBridge` hook, `Toast`, `modal-ui`, `Redirect`, `TitleBar`, Resource Pickers.
7.  **Webhooks:**
    *   When creating webhook handlers, use the utilities provided in `app/shopify.server.ts` for registration and request validation.
    *   Place webhook handler logic within appropriate Remix `action` functions, typically in dedicated routes like `app/routes/webhooks.tsx`.

## Remix Framework Rules

9.  **Routing:** Understand Remix's file-based routing within the `app/routes/` directory.
    *   Admin-facing app routes typically live under `app/routes/app.**`.
    *   API endpoints or webhook handlers might live at the root or under specific paths like `app/routes/api.**` or `app/routes/webhooks.tsx`.
10. **Data Loading:** Place server-side data fetching logic inside `loader` functions. Use the `json` helper from `@remix-run/node` to return data. Access loader data in components using `useLoaderData`.
11. **Data Mutations:** Place server-side data mutation logic (form submissions, API calls triggered by user actions) inside `action` functions. Use `redirect` or `json` helpers for responses.
12. **Forms & Submissions:** Use Remix's `<Form>` component for submissions that trigger actions. Use `useSubmit` or `useFetcher` for more controlled submissions (e.g., JavaScript-driven updates, background actions).

## Database (Prisma) Rules

13. **Interaction:** Use the Prisma client (usually initialized or imported, e.g., `import { db } from "~/db.server";`) for all database operations within `loader` and `action` functions.
14. **Schema Changes:** If asked to modify the data model, update `prisma/schema.prisma`.
15. **Migrations:** Remind the user to run `npx prisma migrate dev` (for development) after schema changes and `npx prisma generate` to update the Prisma client.

## General Coding Practices

16. **Error Handling:** Implement robust error handling, especially around API calls (Shopify API, database operations). Use `try...catch` blocks and provide meaningful feedback to the user.
17. **Security:** Assume all user input needs validation/sanitization. Ensure authenticated API clients are always used for Shopify interactions.
18. **Modularity:** Create reusable React components within the `app/components/` directory where appropriate. Keep loaders and actions focused on their specific tasks.
19. **Clarity:** If a request is ambiguous (e.g., "add a button"), ask for clarification on its purpose, placement, data requirements, and expected action.

Use Shopify MCP as needed. You hava acess to the following tools:
- introspect_admin_schema
- search_dev_docs