| name | powerbi-custom-visuals |
| description | Power BI custom visual (.pbiviz) development with the pbiviz toolchain and its MCP server. Automatically invoke when the user mentions "custom visual", "pbiviz", "develop a Power BI visual", "powerbi-visuals-tools", "IVisual", "capabilities.json", "visual formatting model", "visual certification", "publish a visual to AppSource", or asks to scaffold, build, debug, package, certify, or publish a .pbiviz developer visual. |
Power BI Custom Visuals (pbiviz)
Build distributable Power BI developer visuals: TypeScript/D3 visuals packaged
as a .pbiviz file, written against the powerbi-visuals-api and built with the
pbiviz CLI (powerbi-visuals-tools). This skill covers the full loop: scaffold,
develop, live-preview, package, certify, and publish.
Pick the right tool first
This plugin holds five visual approaches. Choose before building:
deneb-visuals: no-code Vega / Vega-Lite specs inside a report; no packaging, no TypeScript
python-visuals: matplotlib / seaborn script visuals (static image, computes at render)
r-visuals: ggplot2 script visuals (static image); R's stats ecosystem
svg-visuals: SVG drawn by a DAX measure (ImageUrl); inline in tables/cards, no visual sandbox
powerbi-custom-visuals (this skill): a real .pbiviz developer visual, reusable across
reports and shareable on AppSource; full interactivity, formatting pane, certification
Reach for this skill when the need is a reusable, interactive, distributable visual
with its own formatting pane. For a one-off chart in a single report, a sibling
skill is usually faster and lighter.
Prerequisites
- Node.js 20.19 or later (the
powerbi-visuals-tools engine minimum)
pbiviz CLI: run via npx -y powerbi-visuals-tools <command>, or install it globally- Developer mode for live preview: enable the developer visual in Power BI Desktop, or
turn on developer mode in the Power BI service
Core workflow
- Scaffold:
pbiviz new <VisualName> creates the project (src/visual.ts,
capabilities.json, pbiviz.json, tsconfig.json, package.json, style/, assets/)
- Implement the visual class in
src/visual.ts. Implement the IVisual interface;
the class name must equal visualClassName in pbiviz.json. Core methods:
constructor (set up DOM and services), update (render on data/size/settings change),
getFormattingModel (populate the format pane), destroy (cleanup)
- Declare data and formatting in
capabilities.json: dataRoles (the field wells),
dataViewMappings (how roles map to the dataView), and objects (format-pane properties)
- Build the formatting model with
powerbi-visuals-utils-formattingmodel
(FormattingSettingsService, cards, slices). A card name matches a capabilities.json
object; a slice name matches a property
- Live-preview:
pbiviz start, then add the developer visual to a report and iterate
against real data
- Package:
pbiviz package produces the .pbiviz under dist/; import it into a report
Full command flags, the project layout, the IVisual lifecycle, and formatting-model
patterns are in references/pbiviz-toolchain.md.
Use the bundled pbiviz MCP server
This plugin ships a .mcp.json that starts the pbiviz MCP server
(npx -y powerbi-visuals-tools mcp). It grounds development in current, correct API
usage instead of guessed code. Prefer its tools while building:
get_available_apis: look up data, formatting, interaction, and utility APIs with examples
get_best_practices: API-version management, performance, security, accessibility, testing
add_feature: list features available to add (bookmarks, tooltips, drill-down, selection, localization)
implement_feature: step-by-step instructions, code templates, and config changes for a feature
list_visual_info: extract a project's GUID, version, author, data roles, dependencies
check_vulnerabilities: scan dependencies and source for
Setup, client config, and per-tool detail are in references/mcp-server.md.
Certify and publish
Certification unlocks export to PowerPoint and email subscriptions, and signals a
reviewed visual. Key gates: a lowercase certification branch matching the package,
eslint-plugin-powerbi-visuals passing, no eval/fetch/XMLHttpRequest, a clean
npm audit, and the latest API. Audit with pbiviz package --certification-audit.
Publishing goes through Partner Center to AppSource. R-based visuals cannot be certified.
Requirements and the submission flow are in references/certification-publishing.md.
Learn from shipped visuals
Microsoft publishes the full source of official and certified visuals. Start from the
tutorials (circlecard, sampleBarChart) and read a production visual close to the
target (gantt, sankey, sunburst, timeline, ChicletSlicer) for real patterns.
A curated list with what each one teaches is in references/community-examples.md.
Additional resources
Reference files
references/pbiviz-toolchain.md ... CLI commands, project structure, IVisual lifecycle, capabilities.json, formatting model, key npm packagesreferences/mcp-server.md ... the bundled pbiviz MCP: setup and its toolsreferences/certification-publishing.md ... certification requirements and AppSource publishingreferences/community-examples.md ... official and certified example visuals worth reading
Examples
examples/vscode-mcp.json ... standalone .vscode/mcp.json for a visual project outside this pluginexamples/capabilities-objects.json ... a capabilities.json objects block wired to a formatting card
