# App Bridge Actions

> How to add or change app-to-Dashboard communication in @saleor/app-sdk's App Bridge. Use when adding a Dashboard command, iframe resize/sizing, exporting a postMessage helper, or reviewing a PR that introduces a new message type. Enforces the actions + dispatch pattern and prevents a second, parallel postMessage protocol.

- Skill: `saleor/app-bridge-actions` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add saleor/app-bridge-actions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/saleor/app-bridge-actions/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: saleor (https://skillmd.com/u/saleor)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/saleor/app-bridge-actions

---


# App Bridge Actions

Guide for extending the app-to-Dashboard communication layer in `@saleor/app-sdk`. The app (inside
the Dashboard iframe) sends commands through **exactly one** channel: an `actions.*` action sent via
`appBridge.dispatch()`. These rules keep new features on that channel instead of inventing a parallel
`postMessage` protocol.

## Why App Bridge Exists

Apps are third-party web apps embedded in the Dashboard via a cross-origin `<iframe>`. That boundary
blocks shared JS, DOM, and cookies, so the browser's only sanctioned transport is
`window.postMessage`. App Bridge is the typed wrapper over that single link: **app → Dashboard =
actions (`dispatch`)**, **Dashboard → app = events (`subscribe`)**. There is one physical pipe — a
second message protocol isn't a new capability, just an ungoverned use of the same pipe. That is why
every command must be an action.

## When to Apply

- Adding a new app → Dashboard command (redirect, notification, resize, popup close, etc.)
- Reporting iframe size / height / layout to the Dashboard
- Adding or exporting a helper or hook that calls `window.parent.postMessage`
- Reviewing a PR that introduces a new `postMessage` `type` string or message constant
- Touching `src/app-bridge/actions.ts`, `app-bridge.ts`, or `index.ts`

## Rule Categories

| Priority | Category   | Impact   | Prefix       |
| -------- | ---------- | -------- | ------------ |
| 1        | App Bridge | CRITICAL | `appbridge-` |

## Quick Reference

### 1. App Bridge (CRITICAL)

- `appbridge-use-dispatch` — Use `actions.*` + `dispatch()`, never manual `postMessage`; helpers/hooks wrap dispatch; fire-and-forget for frequent actions
- `appbridge-add-action` — Recipe for adding an action in `actions.ts` (ActionType → payload → creator → register → test)
- `appbridge-release-safety` — The action `type`, exported constants, and helper signatures are public API; pre-release/breaking-change checklist

## How to Use

Read individual rule files for explanations and code examples:

```
rules/appbridge-use-dispatch.md
rules/appbridge-add-action.md
rules/appbridge-release-safety.md
```

## Full Compiled Document

For the complete guide with all rules expanded: `AGENTS.md`