Plugin Loading and Security#

Read Vega Plugins first for the plugin contract and a complete startup example. This page covers where plugin code can come from and how to control its network access.

Choose a Loading Mode#

Startup plugins are part of the converter configuration. VlConvert loads them in order when a worker starts and makes them available to every conversion that converter performs. Use startup plugins for stable extensions maintained with the application.

Per-request plugins let a caller supply a plugin for one conversion. They are disabled by default and run in a separate temporary JavaScript runtime, which adds startup overhead and executes code chosen by the caller. Use them only when a trusted caller must choose plugin code dynamically.

Supported Plugin Sources#

A plugin entry can be one of three forms:

  • A .js or .mjs file path. VlConvert reads and bundles the file before loading it.

  • An http:// or https:// URL. VlConvert fetches and bundles the module.

  • Inline ESM source. Configuration files and library APIs accept source text. The --vega-plugin CLI flag does not, so a mistyped path is never treated as executable source.

The file-based examples use the double-value.js plugin from Vega Plugins.

Each vega_plugins entry can be a path, URL, or source string:

let config = VlcConfig {
    vega_plugins: vec![
        "./double-value.js".to_string(),
        "https://cdn.example.com/acme-plugin.js".to_string(),
    ],
    ..Default::default()
};

Control HTTP Imports#

A plugin can import other ESM modules. HTTP imports are blocked unless their domain matches plugin_import_domains. This plugin imports scaleLinear from esm.sh and registers a scaledPercent expression function:

scale-plugin.js
import { scaleLinear } from "https://esm.sh/d3-scale@4"

export default function registerScale(vega) {
  const scale = scaleLinear().domain([0, 1]).range([0, 100])
  vega.expressionFunction("scaledPercent", value => scale(value))
}

This chart calls scaledPercent to convert fractions to percentages:

scale-chart.vl.json
{
  "$schema": "https://vega.github.io/schema/vega-lite/v6.json",
  "data": {
    "values": [
      {"category": "A", "value": 0.25},
      {"category": "B", "value": 0.5},
      {"category": "C", "value": 0.75}
    ]
  },
  "transform": [
    {"calculate": "scaledPercent(datum.value)", "as": "percent"}
  ],
  "mark": "bar",
  "encoding": {
    "x": {"field": "category", "type": "nominal", "title": "Category"},
    "y": {"field": "percent", "type": "quantitative", "title": "Percent"}
  }
}
use vl_convert_rs::{VlcConfig, VlConverter};

let converter = VlConverter::with_config(VlcConfig {
    vega_plugins: vec!["./scale-plugin.js".to_string()],
    plugin_import_domains: vec!["esm.sh".to_string()],
    ..Default::default()
})?;
let spec = std::fs::read_to_string("scale-chart.vl.json")?;
let output = converter
    .vegalite_to_svg(spec, Default::default(), Default::default())
    .await?;
std::fs::write("scale-chart.svg", output.svg)?;

The resulting bars show values of 25, 50, and 75:

Bar chart with categories A, B, and C at 25, 50, and 75 percent.

esm.sh matches that host only. *.jsdelivr.net matches the named host and its subdomains. * allows any domain and should be reserved for trusted code. Redirect targets must also match the allowlist.

The domain of a URL plugin entry is added to the allowlist automatically, so the plugin can import from its own host. Imports from any other host still need an explicit entry. This allowlist is separate from allowed_base_urls, which controls data and image URLs.

Bundle Multi-File Plugins#

Bundle TypeScript and multi-file JavaScript before passing it to VlConvert. Prebundling keeps startup independent of package registries and produces one artifact that can be reviewed and deployed with the application.

After installing esbuild with npm, bundle the plugin:

$ npx esbuild src/acme-plugin.ts \
>   --bundle \
>   --format=esm \
>   --platform=browser \
>   --outfile=dist/acme-plugin.js

Register dist/acme-plugin.js as the startup plugin. The plugin must not rely on browser globals such as window or document during static conversion.

Enable Per-Request Plugins#

Enable per-request plugins in the converter configuration, then pass one plugin as the conversion’s vega_plugin value. The following examples reuse double-value.js and chart.vl.json from Vega Plugins.

use vl_convert_rs::{VlcConfig, VlConverter, VlOpts};

let converter = VlConverter::with_config(VlcConfig {
    allow_per_request_plugins: true,
    ..Default::default()
})?;
let spec = std::fs::read_to_string("chart.vl.json")?;
let plugin_source = std::fs::read_to_string("double-value.js")?;

let output = converter
    .vegalite_to_svg(
        spec,
        VlOpts {
            vega_plugin: Some(plugin_source),
            ..Default::default()
        },
        Default::default(),
    )
    .await?;
std::fs::write("chart.svg", output.svg)?;

Plugins in HTML Output#

With bundle=true, the generated HTML contains its dependencies and the plugin code. With bundle=false, the browser loads Vega from a CDN, URL-backed startup plugins keep their original URLs so the browser loads them too, and file and inline plugins are embedded because the browser cannot read the converter’s files. See Interactive HTML Output.