powerbi-client: embedding Power BI reports in your own app

A client library for a service that stays in the loop

powerbi-client is described as a client side library for embedding Power BI using JavaScript or TypeScript into your apps, and the package description is more specific about what you get.

It provides a service which makes it easy to embed different types of components, and an object model which allows easy interaction with these components, such as changing pages, applying filters, and responding to data selection.

That second half is the part that distinguishes a client library from an embed snippet. A report in a frame is a picture as far as the host page is concerned unless something bridges the two, and the object model is that bridge: the host application can drive the report and can listen to what the user does inside it.

The audience is therefore a product team embedding analytics into an application, not an analyst publishing a report to a browser. The documentation the README points at is the Power BI embedded analytics Client APIs documentation, with the code docs separately at learn.microsoft.com for the classes, interfaces and types, and the sample applications live in the PowerBI-Developer-Samples repository.

For exploring rather than integrating, there is the Power BI Embedded Analytics Playground at playground.powerbi.com, which the README suggests for understanding the capabilities of embedded analytics in your applications.

The project is not archived, the last push was on 2026-10-07, and the package is published as powerbi-client on npm and Microsoft.PowerBI.JavaScript on NuGet.

npm and NuGet, with a beta channel

The installation section is short and covers three cases, which is the right amount for a client library.

For .NET projects, the NuGet package:

Install-Package Microsoft.PowerBI.JavaScript

For JavaScript projects, the npm package:

npm install --save powerbi-client

And for the pre-release line:

npm install --save powerbi-client@beta

The beta channel is worth noticing in a library whose feature set is tied to a hosted service. The embedded analytics surface changes when the Power BI service changes, and the beta tag is how a client library tracks a service release that is not yet the default.

There is a version story here that needs checking before you depend on it. The published GitHub releases are v2.18.7 from 2021-12-12, and then v2.19.0 and v2.19.1, both on 2022-02-21. The version in package.json is 2.25.0. So the release tags on GitHub are several minor versions behind the version the package declares, which means the npm and NuGet artefacts and the tagged source in this repository are not the same thing, and a reader who starts from the tags will be reading older code than the package they installed.

The repository also carries PowerBI.JavaScript.nuspec for the NuGet packaging, a SECURITY.md, a gulpfile.js, webpack.config.js and a karma.conf.js, with src/, test/ and dist/ directories.

The script tag path and the two globals it creates

How you get the library onto the page is a decision with two branches, and the README is explicit about what each one gives you.

Ideally you would use a module loader or a compilation step to import using ES6 modules:

import * as pbi from 'powerbi-client';

However, the library is exported as a Universal Module, and the powerbi.js script can be included before your app's closing </body> tag as:

<script src="/powerbi-client/dist/powerbi.js"></script>

When included directly, the library is exposed as a global named powerbi-client. There is also another global named powerbi, which is an instance of the service.

So the script tag route gives you two names, and the distinction matters. The first is the module namespace, which holds the constructors, the enums and the factory functions. The second is an already constructed service instance, which is why a plain script include can embed a report without any setup code. It is a small convenience that also means two similarly named globals in the page, which is worth keeping in mind if the application already has a variable called powerbi.

The Universal Module packaging is the part that has aged best. A library that publishes one artefact that works as a CommonJS bundle and as a script tag means the consumer does not have to pick a distribution model, and the package manifest matches that with main pointing at dist/powerbi.js and types at dist/powerbi-client.d.ts, with the published files limited to the dist directory.

The service and the object model in one paragraph

The README does not document the API in any detail, which is a deliberate division of labour: the client API documentation on docs.microsoft.com is the reference, and the code docs on learn.microsoft.com cover the classes, interfaces and types.

What can be said from the package description is the shape of the object model, and it is the part an integrator actually needs to know before reading the reference. There is a service, which is the entry point for embedding, and there is an object model over the embedded components. The operations named are changing pages, applying filters, and responding to data selection.

Those three describe three distinct integration needs. Changing pages is navigation control, so the host application decides which page of a report is visible rather than the user scrolling. Applying filters is programmatic data narrowing, so the host can show one slice of the data to one user and another slice to somebody else. Responding to data selection is the event direction, the host learning that the user clicked a data point so it can act on that, for instance to show a detail panel for the selected row.

That last one is what turns an embedded report into a component of an application rather than a picture of one. And it is the reason the library has an object model at all rather than being a thin wrapper around an iframe.

A gulp and webpack build with karma tests

The repository is a TypeScript project with a conventional Microsoft open source toolchain, and the package manifest describes it precisely.

The scripts are three lines: build runs gulp build, test runs gulp test, and there is a tests script that runs the test command with a chrome flag and watch. The dependencies show the shape of the build: gulp 4 with plugins for eslint, flatten, help-four, prepend, rename, replace, typedoc, typescript, watch and a run-sequence helper, plus webpack in the repository root for the bundle configuration, and karma with jasmine for the tests.

Two of the dev dependencies are worth naming because they explain the design. The typedoc plugin sits in the dev dependencies, and the README links separate code docs on learn.microsoft.com. And the eslint configuration is a plugin set with import, jsdoc and prefer-arrow rules, which is the house style of a library that has to look like the rest of the Microsoft JavaScript.

The dev dependencies list @typescript-eslint 4.7 and eslint 7.13, and the test tooling is jasmine-core 3.10.1 with @types/jasmine 3.5. The karma configuration file is at the root with a separate webpack.test.config.js and a webpack.test.tsconfig.json, so the test build is a separate webpack configuration rather than a variant of the main one.

The typescript configuration is split the same way, with tsconfig.json for the project and tsconfig.test.json for the tests, and the published type declaration is generated into dist/powerbi-client.d.ts, which is what the types field points at.

Where powerbi-client is the wrong tool

The limits here are about what kind of problem the library is for, and about the coupling it creates.

The first is that the content lives in Microsoft's service. This is a client for a hosted analytics platform, and the report, the data and the rendering all happen on that side. If the requirement is an offline report, a static export, a screenshot for a slide, or a copy of the data in your own warehouse, none of that is what this library does, and the work of reproducing a report in a form you own is a different project entirely.

The second is the coupling to a service version. The client library tracks the embedded analytics surface of the Power BI service, which is why there is a beta channel and why the version numbers in the manifest have run ahead of the GitHub tags. A team that wants a stable, long lived dependency has to accept that the version is dictated from the service side, and the beta tag is a reasonable way to track a service release that is not the default yet.

The third is the licence paperwork, and it is a real difference from a normal MIT project. The repository's licence is not classified by GitHub, there is a LICENSE.txt and a NOTICE.txt in the root, and the package metadata says MIT. Those three are not the same thing, and the file is what governs. It is a note about where the terms are rather than a reading of them.

The fourth is the contribution process, which is heavier than a typical open source project. Most contributions require you to agree to a Contributor License Agreement, a CLA bot decides automatically whether you need to sign one and decorates the pull request, and the README asks people to follow the bot's instructions. You only have to do it once across all the repos using the CLA, and it also sits alongside the Microsoft Open Source Code of Conduct.

And the fifth is support routing. The README points feature requests at the Fabric Ideas Portal, bugs and technical assistance at the Fabric Developer Community Forum, and anything else at the account manager or the Fabric Support Team. That is a clear support model, and it is also a clear sign of where the project sits.

Editorial conclusion

Adopt powerbi-client if you are building an application that has to show live Power BI content and you want a typed object model over the report rather than raw postMessage plumbing, and if you are comfortable taking a dependency on Microsoft's release cadence for the client. Do not adopt it for a static report screenshot, a one-off export, or an offline scenario, because the content is served from the Power BI service. Verify first that the powerbi-client version you install matches the Power BI service features you need, that your build can consume the library as an ES module or a script tag, and that the licence file in the repository, which is separate from the MIT field in the package metadata, says what you expect it to say.

Frequently asked questions

Official sources

1. Issues
2. microsoft/PowerBI-JavaScript on GitHub
3. README
4. Releases