Skip to content

Custom Admin Pages Documentation

This document describes the custom admin extension pages added to the Medusa admin dashboard for managing AzharStore's custom modules.

Overview

Three custom admin pages have been created to manage the Advertisement, Settings, and Translation modules. These pages integrate with the Medusa admin dashboard and provide a UI for CRUD operations on the custom data models.

Page Locations

The custom pages are accessible from the Medusa admin sidebar:

  • Advertisements: /app/advertisements
  • Settings: /app/settings
  • Translations: /app/translations

Page Structure

Each custom page consists of two files:

  1. route.ts: Defines the page route, label, and icon
  2. page.tsx: The React component implementing the UI

File Locations

backend/src/admin/extensions/
├── advertisements/
│   ├── route.ts
│   └── page.tsx
├── settings/
│   ├── route.ts
│   └── page.tsx
└── translations/
    ├── route.ts
    └── page.tsx

Advertisements Page

Route Configuration

File: backend/src/admin/extensions/advertisements/route.ts

import { defineAdminExtension } from "@medusajs/framework"

export default defineAdminExtension({
  label: "Advertisements",
  icon: "LayoutTemplate",
  route: "/advertisements",
})

Page Features

File: backend/src/admin/extensions/advertisements/page.tsx

The Advertisements page provides:

  • List View: Displays all advertisements in a table with columns:
  • Title
  • Location (home_slider, banner)
  • Display Order
  • Status (Active/Inactive badge)

  • Actions (Edit, Delete buttons)

  • Create Modal: Form to create new advertisements with fields:

  • Title (optional)
  • Image URL (required)
  • Link URL (optional)
  • Location (dropdown: home_slider, banner)
  • Display Order (number)

  • Active (checkbox)

  • Delete Confirmation: Confirmation dialog before deleting

API Integration

The page uses the following admin API endpoints:

  • GET /admin/advertisements - Fetch all advertisements
  • POST /admin/advertisements - Create new advertisement
  • DELETE /admin/advertisements/:id - Delete advertisement

State Management

Uses TanStack Query (@tanstack/react-query) for: - Fetching advertisements list with useQuery - Deleting advertisements with useMutation - Automatic cache invalidation after mutations

UI Components

Uses Medusa UI components (@medusajs/ui): - Container - Page layout wrapper - Heading - Page and section titles - Button - Action buttons - Table - Data table display - Badge - Status indicators

Settings Page

Route Configuration

File: backend/src/admin/extensions/settings/route.ts

import { defineAdminExtension } from "@medusajs/framework"

export default defineAdminExtension({
  label: "Settings",
  icon: "Settings",
  route: "/settings",
})

Page Features

File: backend/src/admin/extensions/settings/page.tsx

The Settings page provides:

  • Form View: Single-page form with all application settings:
  • Free Delivery Threshold (cents)
  • Pickup Message

  • CEO WhatsApp

  • Field Descriptions: Helper text below each field explaining the setting's purpose

  • Save Button: Single button to save all settings at once

API Integration

The page uses the following admin API endpoints:

  • GET /admin/settings - Fetch current settings
  • PATCH /admin/settings - Bulk update settings

State Management

Uses TanStack Query for: - Fetching current settings with useQuery - Updating settings with useMutation - Automatic cache invalidation after save

UI Components

Uses Medusa UI components: - Container - Page layout wrapper - Heading - Page title - Input - Text and number input fields - Label - Field labels - Button - Save button

Translations Page

Route Configuration

File: backend/src/admin/extensions/translations/route.ts

import { defineAdminExtension } from "@medusajs/framework"

export default defineAdminExtension({
  label: "Translations",
  icon: "Globe",
  route: "/translations",
})

Page Features

File: backend/src/admin/extensions/translations/page.tsx

The Translations page provides:

  • Filter Dropdown: Filter translations by language code (All, Arabic, English)

  • List View: Displays translations in a table with columns:

  • Language (badge with language code)
  • Key (monospace font)
  • Value
  • Section

  • Actions (Edit, Delete buttons)

  • Create Modal: Form to create new translations with fields:

  • Language Code (dropdown: Arabic, English)
  • Key (required)
  • Value (required)

  • Section (optional)

  • Delete Confirmation: Confirmation dialog before deleting

API Integration

The page uses the following admin API endpoints:

  • GET /admin/translations - Fetch all translations
  • POST /admin/translations - Create new translation
  • DELETE /admin/translations/:id - Delete translation

State Management

Uses TanStack Query for: - Fetching translations list with useQuery - Deleting translations with useMutation - Creating translations with useMutation - Automatic cache invalidation after mutations

UI Components

Uses Medusa UI components: - Container - Page layout wrapper - Heading - Page title - Button - Action buttons - Table - Data table display - Label - Form labels

Authentication

All admin pages automatically inherit authentication from the Medusa admin dashboard. Users must be logged in to access these pages. The pages use credentials: "include" in fetch requests to include the admin session cookie.

Styling

The pages use Medusa's built-in UI components for consistent styling with the rest of the admin dashboard. Custom styling is minimal and uses inline styles for specific needs (e.g., modal positioning).

Error Handling

Each page includes basic error handling:

  • Loading States: Display "Loading..." while data is being fetched
  • Error States: API errors are logged to console (can be enhanced with error toasts)
  • Validation: Required fields are validated before API calls
  • Confirmation: Delete actions require user confirmation

Future Enhancements

Potential improvements for the admin pages:

  1. Edit Modals: Add edit modals for updating existing records
  2. Error Toasts: Integrate Medusa's toast notification system for error feedback
  3. Pagination: Add pagination for large datasets
  4. Search: Add search/filter functionality
  5. Bulk Actions: Add bulk delete or bulk update operations
  6. Image Upload: Add image upload for advertisement images
  7. Translation Editor: Add rich text editor for translation values
  8. Validation: Add client-side validation for all form fields

Development Notes

Dependencies Required

The admin pages require the following dependencies (should be installed in the backend):

{
  "@medusajs/ui": "latest",
  "@tanstack/react-query": "latest",
  "react": "latest",
  "react-dom": "latest"
}

Type Errors

TypeScript errors related to missing MedusaJS types and React types are expected until dependencies are installed. Run npm install in the backend directory to resolve these errors.

Testing the Pages

To test the admin pages:

  1. Start the Medusa backend: docker compose up medusa
  2. Navigate to http://localhost:9000/app
  3. Log in with admin credentials
  4. Access custom pages from the sidebar

Troubleshooting

Pages Not Appearing in Sidebar

If custom pages don't appear in the admin sidebar:

  1. Verify the route files are in the correct location: backend/src/admin/extensions/*/route.ts
  2. Check that the backend is running with the admin extensions loaded
  3. Check browser console for JavaScript errors
  4. Ensure the admin is built and cached correctly (try hard refresh)

API Errors

If API calls fail:

  1. Check that the admin API routes are registered correctly
  2. Verify authentication is working (check session cookie)
  3. Check browser network tab for failed requests
  4. Review backend logs for errors

Styling Issues

If UI components don't render correctly:

  1. Verify @medusajs/ui is installed
  2. Check that the admin dashboard is using the correct version
  3. Ensure CSS is not being blocked by browser extensions