name: mini-apps-debugging description: Debug and troubleshoot Mini-Apps when they fail to load, build, or run. Covers build checks, browser console inspection, bridge issues, and asset routing fixes.

Mini-Apps Debugging Skill

Debug and troubleshoot Mini-Apps in the Orient. Use this skill when an app fails to load, has runtime errors, or behaves unexpectedly.

Trigger Phrases

Use this skill when:

• "The mini-app is broken"
• "App won't load"
• "Console errors in the app"
• "Debug the meeting-scheduler app"
• "Why is the app failing?"
• "Fix the mini-app errors"

Quick Debugging Checklist

1. Build Status Check

# Check if app is built
curl -s http://localhost/api/apps/<app-name> | jq '.app.isBuilt'

# Rebuild if needed
cd apps/<app-name> && npm run build

2. Common Build Errors

3. Runtime Debugging with Browser MCP

Use the browser extension MCP tools:

1. browser_navigate - Go to the app URL
2. browser_console_messages - Check for JS errors
3. browser_snapshot - Get current page state
4. browser_take_screenshot - Visual verification

4. Bridge Connection Issues

If the app shows "Loading..." forever:

• App is waiting for bridge ping (30s timeout)
• In standalone mode, useBridge() should immediately set isReady=true

Fix in _shared/hooks/useBridge.ts:

if (window.parent === window) {
  // Standalone mode - immediately ready
  setIsReady(true);
  return;
}

5. Asset Loading (404) Errors

If assets fail to load:

• Check vite.config.ts has correct base path

// vite.config.ts
export default defineConfig({
  base: '/apps/<app-name>/', // Must match the serving path
  // ...
});

Rebuild after fixing:

cd apps/<app-name> && npm run build

6. Preview/Mock Mode

Apps running standalone (not in iframe) use mock responses. The app should show a "Preview Mode" banner.

Mock responses are returned for:

• calendar.createEvent → Mock event with fake Meet link
• scheduler.createJob → Mock job ID
• slack.sendDM/sendChannel → No-op

Debugging Workflow

Step 1: Identify the Problem

# Get app status
curl -s http://localhost/api/apps/<app-name> | jq '.'

# Check build output
cd apps/<app-name> && npm run build 2>&1

Step 2: Check Browser Console

Use browser MCP:

browser_navigate({ url: "http://localhost/apps/<app-name>/" })
browser_console_messages()

Step 3: Common Error Categories

Build Errors (TypeScript):

• Props interface issues
• Missing React types
• Path resolution failures

Runtime Errors (Browser):

• Bridge timeout
• Asset 404s
• React rendering failures

Server Errors (Nginx/Express):

• 502 Bad Gateway → Server not running
• 404 → Route not configured
• SPA fallback catching app routes

Step 4: Fix and Verify

1. Make the fix
2. Rebuild: cd apps/<app-name> && npm run build
3. Reload: curl -X POST http://localhost/api/apps/reload
4. Test: browser_navigate + browser_snapshot

Server-Side Debugging

Check Dashboard Server Logs

# In dev mode, check terminal output for:
grep -i "apps\|error" /tmp/dev.log | tail -20

Check Apps Service Initialization

# Should see these logs on startup:
# [apps-service] Apps service created
# [apps-service] initializeApps: Apps initialized
# [dashboard-server] Apps services initialized

Route Debugging

Check nginx routes /apps/ in:

• docker/nginx-local.conf (dev)
• docker/nginx.conf (prod)

Should proxy to dashboard server:

location /apps/ {
    proxy_pass http://dashboard_api_local/apps/;
}

Testing Mini-Apps

Manual Testing via Browser

1. Navigate to http://localhost/apps/<app-name>/
2. Check for "Preview Mode" banner (expected in standalone)
3. Fill out form and submit
4. Verify mock success response

Automated Testing

# Use browser MCP for automated testing
browser_navigate({ url: "http://localhost/apps/<app-name>/" })
browser_type({ element: "Title input", ref: "e14", text: "Test" })
browser_click({ element: "Submit button", ref: "e29" })
browser_snapshot()  # Verify success state

Adding Debug Logging to Apps

For deeper debugging, add console logs:

// In App.tsx
const { bridge, isReady, isPreviewMode } = useBridge();
console.log('[App] Bridge state:', { isReady, isPreviewMode });

// In useBridge.ts
console.log('[Mock Bridge] Calling:', method, params);

Related Skills

• mini-apps - Creating new apps
• testing-strategy - General testing patterns
• production-debugging - Server-side issues