powerbi-visuals-webpack-plugin

5.0.1 verified Sat Apr 25 auth: no javascript

Webpack plugin for building Power BI custom visuals. Current stable version is 5.0.1, released on an ongoing cadence under Microsoft. Key differentiators vs powerbi-visuals-tools: it integrates with webpack, provides developer server assets and .pbiviz packaging, supports localization, certification auditing, and removal of forbidden network calls for certified visuals. Requires Node >=18.0.0 and webpack 5. The plugin generates GUID, handles pbiviz.json, and enforces API version compatibility.

Common errors

error Cannot find module 'powerbi-visuals-webpack-plugin' ↓

cause Package not installed or incorrectly imported.

fix

Run 'npm install powerbi-visuals-webpack-plugin --save-dev' and ensure the import uses named export.

error TypeError: PowerBICustomVisualsWebpackPlugin is not a constructor ↓

cause Importing default export instead of named export.

fix

Use 'import { PowerBICustomVisualsWebpackPlugin } from ...' or 'const { PowerBICustomVisualsWebpackPlugin } = require(...)'

error Error: Unsupported API version. Required at least 3.0.0 ↓

cause Visual uses an outdated powerbi-visuals-api version.

fix

Upgrade powerbi-visuals-api: 'npm install powerbi-visuals-api@latest --save'

error Module parse failed: Unexpected token (1:0) - You may need an appropriate loader to handle this file type. ↓

cause Missing loader for .ts or .less files.

fix

Add ts-loader for TypeScript and less-loader + css-loader for Less files in webpack config.

Warnings

breaking v5.0.0 requires Node >=18.0.0; Node <18 is no longer supported. ↓

fix Upgrade Node to version 18 or higher.

breaking v4.0.0 changed imports: plugin class renamed from PowerBIVisualsWebpackPlugin to PowerBICustomVisualsWebpackPlugin. LocalizationLoader introduced. ↓

fix Update import statements: use 'PowerBICustomVisualsWebpackPlugin' and optionally 'LocalizationLoader'.

deprecated Option 'string' for capabilities has been deprecated; use object form. ↓

fix Pass capabilities as an object instead of a string file path.

gotcha If npm install fails due to missing git or node-gyp, ensure build tools are installed (e.g., Visual Studio Build Tools on Windows). ↓

fix Install build-essential on Linux (apt install build-essential) or Windows build tools (npm install --global windows-build-tools).

Install

npm install powerbi-visuals-webpack-plugin

yarn add powerbi-visuals-webpack-plugin

pnpm add powerbi-visuals-webpack-plugin

Imports

PowerBICustomVisualsWebpackPlugin

wrong

import PowerBICustomVisualsWebpackPlugin from 'powerbi-visuals-webpack-plugin'

correct

import { PowerBICustomVisualsWebpackPlugin } from 'powerbi-visuals-webpack-plugin'

ESM default import does not work; must use named import. CJS: const { PowerBICustomVisualsWebpackPlugin } = require(...)

LocalizationLoader
wrong
```
require('powerbi-visuals-webpack-plugin').LocalizationLoader
```
correct
```
import { LocalizationLoader } from 'powerbi-visuals-webpack-plugin'
```
Added in v4.0.0. Both named ESM import and destructured require are valid, but require on dot property is more common and works.

PowerBICustomVisualsWebpackPlugin

wrong

const PowerBICustomVisualsWebpackPlugin = require('powerbi-visuals-webpack-plugin')

correct

const { PowerBICustomVisualsWebpackPlugin } = require('powerbi-visuals-webpack-plugin')

CommonJS: must destructure the named export, not assign the whole module. Wrong usage yields undefined.

Quickstart

Configures webpack with PowerBICustomVisualsWebpackPlugin for a Power BI custom visual, including TypeScript, Less, CSS extraction, and devServer.

const path = require('path');
const { PowerBICustomVisualsWebpackPlugin } = require('powerbi-visuals-webpack-plugin');
const MiniCssExtractPlugin = require('mini-css-extract-plugin');

module.exports = {
  entry: './src/visual.ts',
  output: { path: path.resolve(__dirname, 'dist'), filename: 'visual.js' },
  resolve: { extensions: ['.ts', '.js'] },
  module: {
    rules: [
      { test: /\.ts$/, use: 'ts-loader', exclude: /node_modules/ },
      { test: /\.less$/, use: [MiniCssExtractPlugin.loader, 'css-loader', 'less-loader'] },
      { test: /\.json$/, type: 'json' }
    ]
  },
  plugins: [
    new PowerBICustomVisualsWebpackPlugin({
      visual: {
        name: 'MyVisual',
        displayName: 'My Visual',
        guid: 'myVisual123ABC',
        visualClassName: 'Visual',
        version: '1.0.0',
        description: 'A sample custom visual',
        supportUrl: 'https://example.com'
      },
      author: 'Author',
      apiVersion: '5.3.0',
      capabilities: {},
      iconImage: 'data:image/png;base64,...',
      devMode: true,
      packageOutPath: path.resolve(__dirname, 'dist'),
      generatePbiviz: true
    }),
    new MiniCssExtractPlugin({ filename: 'visual.css' })
  ],
  devServer: {
    https: true,
    port: 8080
  }
};