npm package: @salesforce/metadata-plugins
Description: Visualizer implementations for Salesforce metadata
Author: salesforce
Latest version: 1.0.2

# @salesforce/metadata-plugins

Visualization plugin implementations for Salesforce metadata types, used with [`@salesforce/metadata-core-sdk`](https://www.npmjs.com/package/@salesforce/metadata-core-sdk).

## Overview

This package provides metadata visualization plugins that parse Salesforce XML metadata files and render interactive visualizations. Each plugin provides:

- **Parser** — Extracts structured data from XML metadata files
- **Visualizer** — Generates interactive React-based visualizations

## Supported Metadata Types

| Metadata Type | File Pattern                          | Plugin ID   | Description                                                         |
| ------------- | ------------------------------------- | ----------- | ------------------------------------------------------------------- |
| FlexiPages    | `.flexipage-meta.xml`                 | `flexipage` | Lightning Page layout visualization                                 |
| Data Model    | `.object-meta.xml`, `.field-meta.xml` | `schema`    | Interactive ERD visualization of objects, fields, and relationships |

## Installation

```bash
npm install @salesforce/metadata-plugins
```

**Peer dependency:** `@salesforce/metadata-core-sdk@^1.0.0` must be installed.

## Usage

### Loading All Plugins

```typescript
import { getAllVisualizers } from '@salesforce/metadata-plugins';

const plugins = getAllVisualizers();
```

### Filtering Plugins via Configuration

Plugins can be disabled at runtime using `PluginConfig`:

```typescript
import { getAllVisualizers } from '@salesforce/metadata-plugins';
import type { PluginConfig } from '@salesforce/metadata-core-sdk';

const config: PluginConfig = {
  pluginSettings: {
    flexipage: false, // Disable flexipage plugin
  },
};

const plugins = getAllVisualizers(config);
```

### Using Individual Plugins

```typescript
import { FlexipageVisualizer, SchemaVisualizer } from '@salesforce/metadata-plugins';

const flexipageViz = new FlexipageVisualizer();
const schemaViz = new SchemaVisualizer();

// Check plugin metadata
const info = schemaViz.getMetadataPluginInfo();
console.log(info.id); // 'schema'
console.log(info.filePatterns); // ['.object-meta.xml', '.field-meta.xml']
```

## API

### Entry Point

- **`getAllVisualizers(config?)`** — Returns all plugin instances, optionally filtered by `PluginConfig.pluginSettings`

### Plugins

- **`FlexipageVisualizer`** — Implements `IVisualizationPlugin<FlexipageMetadata>` for Lightning Page metadata
- **`SchemaVisualizer`** — Implements `IVisualizationPlugin<SchemaERDData>` for Custom Object and Field metadata

### Parsers

- **`FlexipageParser`** — Implements `IMetadataParser<FlexipageMetadata>`
- **`SchemaParser`** — Implements `IMetadataParser<SchemaERDData>`

### Types

- **`FlexipageMetadata`** — Parsed FlexiPage structure
- **`SchemaERDData`** — Parsed ERD data with objects, fields, and relationships

## Package Exports

```typescript
// Plugins
import {
  FlexipageVisualizer,
  SchemaVisualizer,
  getAllVisualizers,
} from '@salesforce/metadata-plugins';

// Parsers
import { FlexipageParser, SchemaParser } from '@salesforce/metadata-plugins';

// Types
import type { FlexipageMetadata, SchemaERDData } from '@salesforce/metadata-plugins';
```

## Creating a New Plugin

1. Create a folder under `src/plugins/<type>/`
2. Implement `IVisualizationPlugin` from `@salesforce/metadata-core-sdk`
3. The plugin `id` in `MetadataPluginInfo` **must** match the folder name
4. Add a React UI in `ui/` (optional — framework auto-detects builds)
5. Export the plugin in `src/index.ts` and add it to `getAllVisualizers()`

## License

BSD-3-Clause

## Support

For issues or questions, please file an issue at:
https://github.com/forcedotcom/salesforce-metadata-visualizer-support/issues