Dev Admin

Core Principles

1. Server-first: Data fetching trong loader, mutations trong action — KHÔNG fetch từ client trừ khi realtime
2. Polaris-only UI: Dùng Polaris components, không custom HTML/CSS cho admin UI
3. App Bridge 4.x: Navigation, toasts, modals đều qua App Bridge — không dùng browser APIs
4. Type-safe: Strict TypeScript, Zod validation cho form data, API responses
5. Error boundaries: Mọi route đều có ErrorBoundary component
6. Loading states: Dùng Polaris SkeletonPage / SkeletonBodyText cho loading

Route Structure

app/
├── routes/
│   ├── app._index.tsx          # Dashboard / landing
│   ├── app.settings.tsx        # Settings page
│   ├── app.[resource].tsx      # Resource list (e.g., app.products.tsx)
│   ├── app.[resource].$id.tsx  # Resource detail (e.g., app.orders.$id.tsx)
│   └── app.[resource].new.tsx  # Resource create
├── components/                  # Shared Polaris components
├── utils/                       # Helpers, validators
├── models/                      # Prisma model helpers
└── graphql/                     # Shopify GraphQL queries/mutations

Route Naming

• Prefix app. cho tất cả authenticated routes
• kebab-case cho route segments
• $id cho dynamic params
• .new suffix cho create pages

Code Patterns

Xem chi tiết tại patterns.md bao gồm:

• Loader pattern (data fetching + authentication)
• Action pattern (form handling + validation)
• Polaris page layout pattern
• Error boundary pattern
• GraphQL query pattern (Shopify Admin API)
• Resource picker pattern (App Bridge)
• Toast/Banner notification pattern
• Pagination pattern (cursor-based)
• Bulk action pattern

Shopify Authentication

// LUÔN authenticate trước khi access admin API
const { admin, session } = await authenticate.admin(request);

// GraphQL query
const response = await admin.graphql(`
  #graphql
  query GetProducts($first: Int!) {
    products(first: $first) {
      edges {
        node {
          id
          title
        }
      }
    }
  }
`, { variables: { first: 10 } });

Do's and Don'ts

DO

• Dùng authenticate.admin(request) ở đầu mọi loader/action
• Dùng Polaris Page, Layout, Card cho page structure
• Dùng useNavigation() để show loading states
• Dùng Zod schema validate form data trong action
• Handle Response errors từ Shopify API gracefully
• Dùng useAppBridge() cho App Bridge interactions

DON'T

• Không dùng useState cho data có thể fetch từ server
• Không custom CSS override Polaris styles
• Không fetch() từ client-side cho admin API calls
• Không hardcode shop domain, lấy từ session
• Không skip error boundaries
• Không dùng window.location — dùng App Bridge navigation

$ARGUMENTS