Shopify Debugger

Local debugger and shim for Shopify Polaris App Bridge APIs.

This package lets a Shopify embedded app keep calling the normal App Bridge API during local development:

import { useAppBridge } from "@shopify/app-bridge-react";

const shopify = useAppBridge();

shopify.modal.show("delete-modal");
shopify.toast.show("Saved");
const products = await shopify.resourcePicker({ type: "product" });

When debugger mode is enabled, @shopify/app-bridge-react is aliased to this package's local shim. Your app code does not need to change.

Install

bun add -d shopify-debugger

Vite setup

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { shopifyDebugger } from "shopify-debugger/vite";

export default defineConfig({
  plugins: [react(), shopifyDebugger()],
});

Run local dev with debugger mode:

SHOPIFY_DEBUGGER=true bun run dev

SHOPIFY_APP_BRIDGE_DEBUG=true also works.

When enabled, the Vite plugin also registers a local debugger shell at:

http://localhost:5173/_debugger

Open that route to load your app inside a lightweight iframe host. This gives you a local Shopify-like debugging surface without going through admin.shopify.com.

You can customize the route or the iframe URL:

shopifyDebugger({
  debuggerRoute: "/_debugger",
  appUrl: "/?shop=debug-store.myshopify.com&embedded=1",
});

Set debuggerRoute: false to disable the route while keeping the App Bridge alias.

Debug panel

You do not need to add a debug panel to the client app. The primary flow is zero client-code changes: open /_debugger and use the shell panel there.

The exported <ShopifyDebuggerPanel /> still exists as an optional escape hatch for apps that cannot use the iframe shell route.

Release

This package uses changelogen for changelog and release automation.

Dry-run release notes:

bun run release:dry

Build, update changelog, tag, and push:

bun run release

Build, update changelog, tag, push, and publish to npm:

bun run release:publish

Example

This repo includes a runnable example app:

cd example
bun install
bun run dev

Then open:

http://127.0.0.1:5173/_debugger

The example imports useAppBridge from @shopify/app-bridge-react normally. Only its Vite config uses shopifyDebugger().

What is supported?

Initial shim support:

• useAppBridge() from @shopify/app-bridge-react
• shopify.modal.show(id)
• shopify.modal.hide(id)
• shopify.modal.toggle(id)
• shopify.toast.show(message, options?)
• shopify.resourcePicker(options)
• shopify.loading.show() / shopify.loading.hide()
• shopify.saveBar.show(id) / shopify.saveBar.hide(id)
• shopify.navigation.navigate(destination)

The /_debugger shell shows a local event timeline and lets you switch resource picker behavior between:

• success
• cancel
• error
• manual

Manual resource picker flow

When resource picker mode is manual, calls to shopify.resourcePicker(...) stay pending until you resolve, cancel, or reject them from the /_debugger shell.

Modal fallback

When shopify.modal.show('my-modal') is called, the debugger tries to find document.getElementById('my-modal') and adds open plus data-shopify-debugger-open="true".

A small CSS fallback is included for ui-modal[data-shopify-debugger-open="true"] so App Bridge modal content is visible locally.

Programmatic control

import { shopifyDebugger } from "shopify-debugger";

shopifyDebugger.__debug.setResourcePickerMode("cancel");
shopifyDebugger.__debug.setResourcePickerResponse([
  {
    id: "gid://shopify/Product/123",
    title: "Custom debug product",
  },
]);

Important caveat

This package mimics the public App Bridge API shape for local debugging. It does not emulate Shopify Admin, OAuth, billing, permissions, or the real Admin iframe host protocol.