saleor-dashboard

Saleor Dashboard Extensions

Before writing code

Fetch live docs:

1. Fetch https://docs.saleor.io/docs/developer/extending/apps/extending-dashboard-with-apps for Dashboard extension guide
2. Web-search site:docs.saleor.io app bridge actions dispatch notification for App Bridge API
3. Web-search site:docs.saleor.io dashboard mounting points extensions for extension points reference
4. Web-search site:github.com saleor/macaw-ui components for MacawUI component library
5. Web-search site:docs.saleor.io app iframe communication for iframe messaging patterns

Dashboard Extension Architecture

Saleor Dashboard extensions are rendered as Apps inside iframes. The Dashboard loads your App's URL in a sandboxed iframe and communicates with it through the App Bridge messaging protocol.

Layer	Component
Dashboard	React SPA (host application)
Extension	Your App (rendered in an iframe)
Communication	App Bridge (postMessage API)
Styling	MacawUI component library

Mounting Points

Mounting points define where your App's extension appears in the Dashboard UI:

Mounting Point	Location	Use Case
PRODUCT_DETAILS_MORE_ACTIONS	Product detail page dropdown	Product-level actions
PRODUCT_OVERVIEW_CREATE	Product list page	Custom product creation flows
PRODUCT_OVERVIEW_MORE_ACTIONS	Product list actions	Bulk product operations
ORDER_DETAILS_MORE_ACTIONS	Order detail page dropdown	Order-level actions
ORDER_OVERVIEW_CREATE	Order list page	Custom order creation flows
ORDER_OVERVIEW_MORE_ACTIONS	Order list actions	Bulk order operations
CUSTOMER_DETAILS_MORE_ACTIONS	Customer detail page	Customer-level actions
CUSTOMER_OVERVIEW_CREATE	Customer list page	Custom customer flows
NAVIGATION_CATALOG	Catalog navigation section	Custom catalog pages
NAVIGATION_ORDERS	Orders navigation section	Custom order pages
NAVIGATION_CUSTOMERS	Customers navigation section	Custom customer pages

Mounting points are declared in the App manifest under the extensions array.

Manifest Extension Fields

Field	Type	Purpose
label	string	Button or menu item text
mount	string	Mounting point identifier
target	string	APP_PAGE (full page) or POPUP (modal)
permissions	string[]	Required permissions to see the extension
url	string	App URL path for this extension

Extension Declaration Example

# In App manifest JSON (extensions array)
# Fetch live docs for current manifest extension shape
# label: "My Extension"
# mount: "PRODUCT_DETAILS_MORE_ACTIONS"
# target: "APP_PAGE"
# url: "/extensions/product-action"

App Bridge

The App Bridge is the communication layer between the Dashboard and your iframe App:

App Bridge Actions

Action	Direction	Purpose
dispatch	App -> Dashboard	Trigger a Dashboard action
redirect	App -> Dashboard	Navigate the Dashboard to a URL
notification	App -> Dashboard	Show a toast notification
handshake	Dashboard -> App	Initial connection with context data
theme	Dashboard -> App	Current Dashboard theme (light/dark)
token	Dashboard -> App	JWT token for authenticated API calls
response	Dashboard -> App	Result of a dispatched action

Notification Types

Type	Appearance
success	Green toast -- operation completed
error	Red toast -- operation failed
warning	Yellow toast -- caution needed
info	Blue toast -- informational message

App Bridge Setup

// Fetch live docs for current App Bridge initialization
import { useAppBridge } from "@saleor/app-sdk/app-bridge"

function MyExtension() {
  const { appBridge } = useAppBridge()
  // Use appBridge.dispatch(), appBridge.state, etc.
}

MacawUI Components

MacawUI is the official design system for Saleor Dashboard extensions:

Component	Purpose
Button	Primary and secondary action buttons
Input, Select	Form input fields and dropdowns
Box, Sprinkles	Layout primitives with design tokens
Text	Typography component with variants
List, Table	Data display components
Chip	Tag/badge component
Combobox	Searchable select with autocomplete
Checkbox, Switch	Toggle controls
Skeleton	Loading state placeholders
Tooltip	Contextual information popover

Install via npm install @saleor/macaw-ui -- fetch live docs for the current version and available components.

Theming

MacawUI supports the Dashboard's light and dark themes. Use the theme tokens from the App Bridge to ensure your extension matches the current Dashboard appearance.

Extension Development Flow

Step	Action
1	Scaffold App with saleor app create
2	Define extension mounting points in the manifest
3	Create Next.js pages for each extension URL
4	Initialize App Bridge in each extension page
5	Build UI with MacawUI components
6	Use App Bridge token for authenticated GraphQL calls
7	Tunnel and install for local testing
8	Deploy and update the App manifest URL

Iframe Communication Details

Aspect	Detail
Protocol	window.postMessage over the iframe boundary
Origin	Messages are validated against the Saleor instance origin
Handshake	Dashboard sends initial state (domain, token, theme)
Security	Always verify message origin before processing
Size	Use ResizeObserver to communicate content height to Dashboard

Dashboard Navigation

Your App can register full navigation entries that appear in the Dashboard sidebar:

Navigation Area	Manifest Mount
Catalog section	NAVIGATION_CATALOG
Orders section	NAVIGATION_ORDERS
Customers section	NAVIGATION_CUSTOMERS

These appear as sidebar links that load your App's page in the main content area.

Best Practices

• Use MacawUI components exclusively for a consistent Dashboard look and feel
• Initialize App Bridge on every extension page to receive the auth token and theme
• Keep extension pages lightweight -- they load inside an iframe
• Use the redirect action for Dashboard navigation instead of direct URL changes
• Show loading states with MacawUI Skeleton while fetching data
• Handle both light and dark themes using MacawUI design tokens
• Test extensions at different Dashboard viewport sizes for responsive behavior
• Verify postMessage origins to prevent cross-origin security issues

Fetch the Saleor Dashboard extension documentation for exact mounting point identifiers, App Bridge action signatures, and MacawUI component APIs before implementing.