# Plugin Loading and Security Read {doc}`../guides/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 {doc}`../guides/plugins`. ```python vlc.configure( vega_plugins=[ "./double-value.js", "https://cdn.example.com/acme-plugin.js", "export default function (vega) { vega.expressionFunction('answer', () => 42) }", ] ) ``` ## 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: :::{dropdown} scale-plugin.js :open: ```{literalinclude} /_examples/scale-plugin.js :language: javascript ``` ::: This chart calls `scaledPercent` to convert fractions to percentages: :::{dropdown} scale-chart.vl.json :open: ```{literalinclude} /_examples/plugin-scale.vl.json :language: json ``` ::: ```python from pathlib import Path import vl_convert as vlc vlc.configure( vega_plugins=["./scale-plugin.js"], plugin_import_domains=["esm.sh"], ) spec = Path("scale-chart.vl.json").read_text(encoding="utf-8") Path("scale-chart.svg").write_text(vlc.vegalite_to_svg(spec), encoding="utf-8") ``` The resulting bars show values of 25, 50, and 75: ```{vl-chart} /_examples/plugin-scale.vl.json :vega-plugin: /_examples/scale-plugin.js :plugin-import-domains: esm.sh :alt: 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](https://esbuild.github.io/getting-started/#install-esbuild), bundle the plugin: ```console $ 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 {doc}`../guides/plugins`. ```python from pathlib import Path import vl_convert as vlc vlc.configure(allow_per_request_plugins=True) spec = Path("chart.vl.json").read_text(encoding="utf-8") plugin_source = Path("double-value.js").read_text(encoding="utf-8") svg = vlc.vegalite_to_svg( spec, vega_plugin=plugin_source, ) Path("chart.svg").write_text(svg, encoding="utf-8") ``` ## 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 {doc}`../guides/html-output`.