@botanicastudios/preview-app-bridge-remix

Preview App Bridge React

A comprehensive React package for Shopify App Bridge preview functionality. This package provides mock implementations and preview components that allow developers to build and test Shopify apps without requiring a full Shopify environment.

Features

Components

• Modal: Preview modal component with App Bridge-like functionality
• TitleBar: Preview title bar with actions and breadcrumbs
• PreviewTitleBar: Enhanced title bar for preview mode
• NavMenu: Navigation menu component
• PreviewNavMenu: Enhanced nav menu for preview mode
• SaveBar: Save bar component for form workflows
• ResourcePicker: Resource picker component with mock data
• PortalTitleBar: Portal-based title bar component

Hooks

• useAppBridge: Hook for accessing App Bridge functionality
• useAppBridgeContext: Hook for accessing App Bridge context

Context

• AppBridgeProvider: Provider component for App Bridge context
• AppBridgeContext: React context for App Bridge state

APIs

• toast: Toast notification API
• loading: Loading state management API
• resourcePicker: Resource picker API with mock data
• picker: Generic picker API
• reviews: Review request API

Services

• TokenGenerator: JWT token generation and caching service
• RequestInterceptor: Request interception service
• GraphQLClient: GraphQL client with mock capabilities

Server Utilities

• JWTSigner: Server-side JWT signing utilities

Installation

This package is designed to be used as a local module within your Shopify app project.

Usage

Basic Setup

import React from 'react';
import { AppBridgeProvider } from 'preview-app-bridge-react';

function App() {
  return (
    <AppBridgeProvider>
      {/* Your app components */}
    </AppBridgeProvider>
  );
}

Using the Hook

import React from 'react';
import { useAppBridge } from 'preview-app-bridge-react';
import { Button } from '@shopify/polaris';

function MyComponent() {
  const shopify = useAppBridge();
  
  const handleSelectProducts = async () => {
    try {
      const products = await shopify.resourcePicker({
        type: 'product',
        multiple: true,
      });
      
      shopify.toast.show(`Selected ${products.length} products`);
    } catch (error) {
      shopify.toast.error('Failed to select products');
    }
  };
  
  return (
    <Button onClick={handleSelectProducts}>
      Select Products
    </Button>
  );
}

Using Components

import React, { useState } from 'react';
import { Modal, TitleBar } from 'preview-app-bridge-react';

function MyPage() {
  const [modalOpen, setModalOpen] = useState(false);
  
  return (
    <>
      <TitleBar
        title="My Page"
        primaryAction={{
          content: 'Open Modal',
          onAction: () => setModalOpen(true),
        }}
      />
      
      <Modal
        open={modalOpen}
        onClose={() => setModalOpen(false)}
        title="Example Modal"
        primaryAction={{
          content: 'Save',
          onAction: () => {
            // Handle save
            setModalOpen(false);
          },
        }}
      >
        <p>Modal content goes here</p>
      </Modal>
    </>
  );
}

Development Mode

The package includes auto-initialization functionality that can be enabled in preview mode:

import { initializePreviewAppBridge } from 'preview-app-bridge-react';

// Initialize preview mode (typically in your app's entry point)
if (process.env.NODE_ENV === 'development') {
  initializePreviewAppBridge();
}

File Structure

preview-app-bridge-react/
├── index.ts                      # Main package exports
├── package.json                  # Package configuration
├── components/                   # React components
│   ├── Modal.tsx
│   ├── TitleBar.tsx
│   ├── NavMenu.tsx
│   └── ...
├── hooks/                        # React hooks
│   ├── useAppBridge.tsx
│   └── index.ts
├── context/                      # React context
│   ├── AppBridgeContext.tsx
│   └── index.ts
├── apis/                         # Mock APIs
│   ├── toast.ts
│   ├── loading.ts
│   ├── resource-picker.ts
│   └── ...
├── services/                     # Utility services
│   ├── token-generator.ts
│   ├── request-interceptor.ts
│   └── ...
├── types/                        # TypeScript type definitions
│   └── index.ts
├── server/                       # Server-side utilities
│   └── jwt-signer.ts
├── auto-init.ts                  # Auto-initialization
├── examples.ts                   # Usage examples
└── comprehensive-usage-example.tsx

TypeScript Support

This package is built with TypeScript and provides comprehensive type definitions for all components, hooks, and APIs.

License

MIT