Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.launchmystore.io/llms.txt

Use this file to discover all available pages before exploring further.

​
App Bridge

App Bridge is our JavaScript SDK for building embedded apps. It provides a secure communication channel between your app (running in an iframe) and the LaunchMyStore admin.

​
Installation

npm install @launchmystore/app-bridge

​
Quick Start

import { createApp } from '@launchmystore/app-bridge';

// Initialize App Bridge
const app = createApp({
  apiKey: 'your-client-id',
  host: new URLSearchParams(location.search).get('host')
});

// Show a toast notification
app.dispatch({
  type: 'TOAST',
  payload: {
    message: 'Changes saved successfully!',
    duration: 3000
  }
});

// Open a modal
app.dispatch({
  type: 'MODAL_OPEN',
  payload: {
    title: 'Confirm Action',
    message: 'Are you sure you want to proceed?',
    primaryAction: { content: 'Confirm', destructive: false },
    secondaryAction: { content: 'Cancel' }
  }
});

​
Available Actions

App Bridge supports 19 action types:
ActionDescription
TOASTShow toast notifications
MODAL_OPEN/CLOSEOpen confirmation modals
RESOURCE_PICKERSelect products, collections, customers, etc.
TITLE_BARUpdate the title bar
LOADING_START/STOPShow/hide loading indicator
CONTEXTUAL_SAVE_BARShow save/discard bar
REDIRECTNavigate to other pages
FULLSCREENToggle fullscreen mode
SESSION_TOKENGet session JWT
See Actions Reference for complete documentation.

​
Core Methods

​
dispatch()

Fire-and-forget action dispatch: 
app.dispatch({
  type: 'TOAST',
  payload: { message: 'Hello!' }
});

​
dispatchAndWait()

Dispatch and wait for response: 
const result = await app.dispatchAndWait({
  type: 'RESOURCE_PICKER',
  payload: {
    resourceType: 'product',
    multiple: true
  }
});

console.log(result.selection); // Selected products

​
subscribe()

Listen for events from the host: 
const unsubscribe = app.subscribe('MODAL_CLOSED', (data) => {
  console.log('Modal was closed:', data);
});

// Later: unsubscribe()

​
getSessionToken()

Get a JWT for authenticated API calls: 
const token = await app.getSessionToken();

// Use token for API calls
const response = await fetch('/api/my-endpoint', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

​
React Integration

Use @launchmystore/app-bridge-react for React apps: 
npm install @launchmystore/app-bridge-react

import { AppBridgeProvider, useAppBridge, useToast } from '@launchmystore/app-bridge-react';

function App() {
  return (
    <AppBridgeProvider
      apiKey="your-client-id"
      host={new URLSearchParams(location.search).get('host')}
    >
      <MyComponent />
    </AppBridgeProvider>
  );
}

function MyComponent() {
  const app = useAppBridge();
  const showToast = useToast();
  
  const handleSave = async () => {
    await saveData();
    showToast('Saved successfully!');
  };
  
  return <button onClick={handleSave}>Save</button>;
}

​
Resource Picker

Select resources like products, collections, and customers: 
const result = await app.dispatchAndWait({
  type: 'RESOURCE_PICKER',
  payload: {
    resourceType: 'product',  // See types below
    multiple: true,           // Allow multiple selection
    initialSelection: []      // Pre-selected items
  }
});

if (!result.cancelled) {
  console.log('Selected:', result.selection);
}

​
Resource Types

TypeDescription
productProducts
product_variantProduct variants
collectionCollections
customerCustomers
orderOrders
blogBlogs
articleBlog articles
pagePages
menuNavigation menus
fileFiles/media
metaobjectMetaobjects

​
Session Tokens

Session tokens are JWTs that authenticate your API calls: 
const token = await app.getSessionToken();

// Token payload:
{
  "iss": "launchmystore",
  "aud": "your-client-id",
  "sub": "merchant-shop-id",
  "exp": 1234567890,
  "iat": 1234567800,
  "jti": "unique-token-id"
}
Tokens are cached and auto-refreshed. The backend verifies tokens using your app’s client secret.

​
Error Handling

try {
  const result = await app.dispatchAndWait({
    type: 'RESOURCE_PICKER',
    payload: { resourceType: 'product' }
  });
} catch (error) {
  if (error.code === 'TIMEOUT') {
    console.error('Action timed out');
  } else if (error.code === 'CANCELLED') {
    console.log('User cancelled');
  } else {
    console.error('Unknown error:', error);
  }
}

​
Security

Never include your client secret in frontend code. Session tokens are signed server-side.
  • App Bridge only works when embedded in the LaunchMyStore admin
  • All messages are validated against your app’s apiKey
  • Session tokens expire after 1 hour
  • The host parameter is validated to prevent spoofing