# 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. ## 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`. Use a path or URL with `--vega-plugin`: ```console $ vl-convert --vega-plugin ./double-value.js \ > vl2svg --input chart.vl.json --output chart.svg ``` Here, `chart.vl.json` is the plugin-dependent input from {doc}`../guides/plugins`. Put inline source in a JSONC config file: :::{dropdown} plugins.vlc.jsonc :open: ```json { "vega_plugins": [ "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 ``` ::: ```console $ vl-convert \ > --vega-plugin ./scale-plugin.js \ > --plugin-import-domains esm.sh \ > vl2svg --input scale-chart.vl.json --output scale-chart.svg ``` 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. ## 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`.