figma-webview-bridge

A TypeScript React bridge client for seamless communication between Figma WebView integrations and parent applications.

Installation

npm install figma-webview-bridge

Quick Start

import { useBridge, useGlobalData, useItemData } from 'figma-webview-bridge';
import type { BridgeInstance } from 'figma-webview-bridge';

function MyFigmaApp() {
  const { bridge, isReady, context } = useBridge();
  const [globalData, setGlobalData] = useGlobalData();
  const [itemData, setItemData] = useItemData();

  if (!isReady) {
    return <div>Connecting to Figma...</div>;
  }

  return (
    <div>
      <h1>Figma Bridge App</h1>
      <p>Session: {context?.sessionId}</p>
      {/* Your app content */}
    </div>
  );
}

Features

• 🔄 Real-time data synchronization between WebView and parent application
• 📱 Cross-platform support for both mobile and desktop environments
• 🎯 Dual function patterns - implicit (context-based) and explicit (parameter-based) data management
• 🧩 Static assets included - Wordle word lists and other game utilities
• 📡 Custom messaging system for navigation and events
• 🛡️ TypeScript support with full type safety
• 🔧 Automatic fallback for development environments

Core Hooks

useBridge()

Main connection hook that provides bridge instance and connection status:

const { bridge, isReady, context } = useBridge();
// bridge: BridgeInstance for direct communication  
// isReady: boolean - true when connected to parent app
// context: { sessionId, gameId, viewId } - context information

useGlobalData<T>()

Manages shared data across all instances:

const [globalData, setGlobalData] = useGlobalData<MyGlobalType>();
// Automatically syncs across all connected instances

useItemData<T>() (Implicit)

Manages instance-specific data using current context:

const [itemData, setItemData] = useItemData<MyItemType>();
// Uses context.viewId automatically

useItemDataById<T>() (Explicit)

Manages data for specific instances:

const [itemData, setItemData] = useItemDataById<MyItemType>('specific-id');
// Explicitly specify which instance's data to manage

Bridge Methods

Data Operations

// Implicit pattern (uses context)
await bridge.setItem(data);
await bridge.subscribeItem(handler);

// Explicit pattern (specify ID)
await bridge.setItemById('item-id', data);
await bridge.subscribeItemById('item-id', handler);

// Global data
await bridge.setGlobal(data);
await bridge.subscribeGlobal(handler);

Navigation & Events

// Navigate within parent app
await bridge.navigate('/next-page', params);
await bridge.back();

// Send custom events
await bridge.send('app/event', {
  type: 'celebration',
  data: { confetti: true }
});

// Send navigation messages
await bridge.send('app/navigation', {
  action: 'navigateToCard',
  cardId: 'target-card',
  dismiss: true
});

Utility Functions

import { 
  completeCard,
  completeCardById,
  savePuzzleProgress,
  savePuzzleProgressById,
  updateGlobalGameState,
  navigateToNextCard
} from 'figma-webview-bridge';

// Complete current instance (implicit)
await completeCard(bridge, { score: 100 });

// Complete specific instance (explicit)  
await completeCardById(bridge, 'item-id', { score: 100 });

// Save progress
await savePuzzleProgress(bridge, 0.75, { hintsUsed: 2 });

// Navigate forward
await navigateToNextCard(bridge, { completedPuzzle: true });

Static Assets

The package includes ready-to-use static assets:

Wordle Word Lists

import { VALID_WORDS, isValidWord } from 'figma-webview-bridge/assets/games/wordle-words';

// Validate user input (2,343 valid 5-letter words)
if (!isValidWord(userGuess)) {
  showError("Not a valid word");
}

// Use in your word games
const randomWord = VALID_WORDS[Math.floor(Math.random() * VALID_WORDS.length)];

API Patterns

Implicit Pattern (Recommended)

Best for most use cases - automatically uses current context:

// Simpler, cleaner code
const [data, setData] = useItemData();
await completeCard(bridge, completionData);

Explicit Pattern (Advanced)

For cross-instance coordination and advanced workflows:

// Full control over which instance
const [data, setData] = useItemDataById('specific-id');
await completeCardById(bridge, 'specific-id', completionData);

Error Handling

const saveData = async () => {
  try {
    await setItemData({ completed: true });
    console.log('Data saved successfully');
  } catch (error) {
    console.error('Failed to save data:', error);
    // Handle error appropriately
  }
};

Development & Debugging

The bridge includes extensive debug logging and works standalone for development:

// Bridge will work in regular browser with console logging
// No need for special development setup
if (!isReady) {
  // Shows "Connecting..." in development
  // Shows "Connected" when running in parent app
}

TypeScript Support

Full type safety with TypeScript definitions included:

import type { 
  BridgeInstance, 
  BridgeContext, 
  BridgeMessage,
  UseBridgeReturn,
  UseItemDataReturn,
  UseGlobalDataReturn
} from 'figma-webview-bridge';

interface MyDataType {
  progress: number;
  completed: boolean;
  timestamp: number;
}

const [data, setData] = useItemData<MyDataType>();

Requirements

• React >=16.8.0
• Node.js >=14.0.0
• TypeScript (optional but recommended)

License

MIT License - see LICENSE file for details.

Contributing

Issues and pull requests welcome at GitHub repository.