Perspective esbuild Plugin

The Perspective esbuild Plugin enables seamless integration of the Perspective data visualization library into applications bundled with esbuild. It handles WebAssembly (WASM) module loading, web worker integration, and provides specialized build configurations required by Perspective's high-performance analytics engine.

Package Information

• Package Name: @finos/perspective-esbuild-plugin
• Package Type: npm
• Language: JavaScript (CommonJS)
• Installation: npm install @finos/perspective-esbuild-plugin

Core Imports

const { PerspectiveEsbuildPlugin } = require("@finos/perspective-esbuild-plugin");

For ES modules:

import { PerspectiveEsbuildPlugin } from "@finos/perspective-esbuild-plugin";

Basic Usage

const esbuild = require("esbuild");
const { PerspectiveEsbuildPlugin } = require("@finos/perspective-esbuild-plugin");

esbuild.build({
    entryPoints: ["src/index.js"],
    plugins: [PerspectiveEsbuildPlugin()],
    format: "esm",
    bundle: true,
    loader: {
        ".ttf": "file",
    },
});

When using this plugin, you must:

• Use the format: "esm" option in your esbuild configuration
• Use the type="module" attribute in your app's <script> tag
• Import from Perspective's ESM distributions: @finos/perspective/dist/esm/perspective.js and @finos/perspective-viewer/dist/esm/perspective-viewer.js

Architecture

The plugin is composed of several specialized internal sub-plugins that work together:

• Main Plugin: PerspectiveEsbuildPlugin orchestrates the WASM and Worker plugins
• WASM Handler: Processes WebAssembly files with inline and external loading strategies
• Worker Handler: Bundles web workers with single-threaded fallback support

Capabilities

Main Plugin Configuration

Primary plugin factory that creates an esbuild plugin combining WASM and Worker functionality.

function PerspectiveEsbuildPlugin(options?: PluginOptions): EsbuildPlugin;

interface PluginOptions {
  wasm?: {
    inline?: boolean;      // Whether to inline WASM files as binary data
    webpack_hack?: boolean; // Disable webpack URL compatibility mode (default: false, meaning webpack compatibility enabled)
  };
  worker?: {
    targetdir?: string;    // Worker output directory (default: "build/worker")
  };
}

interface EsbuildPlugin {
  name: string;
  setup: (build: PluginBuild) => void;
}

WASM Processing

Web Worker Processing

Handles web worker bundling with automatic fallback to single-threaded mode when workers are not available.

Worker Processing

Integration Requirements

• ES Modules Only: The plugin only supports ES module (format: "esm") builds
• Direct ESM Imports: Must use direct imports from Perspective's ESM distributions
• Module Script Tags: HTML must use type="module" for script tags
• Target Compatibility: Requires modern JavaScript environment with ES2021+ support
• esbuild Dependency: Designed specifically for esbuild bundler integration