tableau-api

2.2.3 verified Sat Apr 25 auth: no javascript maintenance

NPM wrapper for the Tableau JavaScript API (v2.2.3, last release December 2020). This package provides a convenient way to include the Tableau JS library in Node.js or browser bundlers (Webpack, Rollup). It mirrors the official Tableau JS API, which allows embedding Tableau visualizations, interacting with workbooks and sheets, and extracting underlying data. Key differentiators: simplifies dependency management for Tableau JS compared to manual script tags; however, it lags behind the official CDN version (current Tableau API is v3.x). Release cadence is low (last update in 2020). For new projects, prefer the official CDN or the '@tableau/embedding-api' package.

Common errors

error TypeError: tableau is not defined ↓

cause Imported package but forgot that tableau is attached to window.

fix

Use 'window.tableau.Viz(...)' instead of 'tableau.Viz(...)'.

error Uncaught ReferenceError: window is not defined ↓

cause Code running in Node.js or SSR where window is not available.

fix

Ensure code runs only in browser; use dynamic import or conditional check.

error Cannot read property 'Viz' of undefined ↓

cause tableau-api not properly imported or CDN script not loaded.

fix

Wait for tableau script to load: use 'tableau' global, not import.

error Module not found: Error: Can't resolve 'tableau-api' ↓

cause Package not installed or not in node_modules.

fix

Run 'npm install tableau-api' and ensure correct import path.

Warnings

gotcha Using window.tableau.Viz instead of imported tableau.Viz: the package only adds the tableau script to window; direct named imports like tableau.Viz do not exist. ↓

fix Always use 'new window.tableau.Viz(...)' after importing 'tableau-api'.

deprecated Tableau JS API v2 (embedded in this package) is deprecated by Tableau; v3 is available via CDN or @tableau/embedding-api. ↓

fix Migrate to @tableau/embedding-api or use CDN script for v3.

gotcha Importing in server-side rendering (SSR) environments: package expects browser globals (window, document) which are not available in Node.js. ↓

fix Use dynamic import or only load in browser environment.

breaking Breaking change: In v2.1, the package switched from bundling the full Tableau JS API to referencing the CDN, breaking users who depended on the bundled version. ↓

fix Pin to v2.0 if you need bundled version.

deprecated The 'getUnderlyingDataAsync' method previously returned a promise with .getData() method; now returns data directly? Check Tableau docs. ↓

fix Refer to official Tableau JS API docs for current return types.

Install

npm install tableau-api

yarn add tableau-api

pnpm add tableau-api

Imports

default (tableau)
wrong
```
const tableau = require('tableau-api');
```
correct
```
import tableau from 'tableau-api';
```
ESM import is preferred; CommonJS require also works but is not tree-shakable.

Viz

wrong

const viz = new tableau.Viz(container, url, options);

correct

const viz = new window.tableau.Viz(container, url, options);

tableau is attached to window; after importing tableau-api, use window.tableau objects.

Worksheet

wrong

const sheet = viz.getWorkbook().getActiveSheet().getWorksheets()[0];

correct

const sheet = viz.getWorkbook().getActiveSheet().getWorksheets().get('Table');

Worksheets collection uses .get(name) not array indexing.

Quickstart

Embeds a Tableau visualization and logs underlying data when interactive.

import tableau from 'tableau-api';
const container = document.getElementById('vizContainer');
const url = 'https://public.tableau.com/views/WorldIndicators/GDPpercapita?:embed=y';
const options = {
  hideTabs: true,
  width: '800px',
  height: '600px',
  onFirstInteractive: () => {
    const sheet = viz.getWorkbook().getActiveSheet();
    sheet.getUnderlyingDataAsync().then(data => console.log(data));
  }
};
const viz = new window.tableau.Viz(container, url, options);