Codakey
Play
← Back to plotly/plotly.js

How to Deploy & Use plotly/plotly.js

# Plotly.js Deployment & Usage Guide

## 1. Prerequisites

### Runtime Requirements
- **Node.js**: 14.x or higher (LTS recommended for development/building)
- **npm**: 7.x or higher, or **yarn** 1.22+
- **Browser Support**: Modern evergreen browsers (Chrome, Firefox, Safari, Edge) with ES6 support
- **WebGL**: Required for 3D charts and scattergl traces (WebGL 1.0 or 2.0)

### Optional Dependencies
- **MathJax**: v2.7.5+ or v3.2.2+ for LaTeX/math rendering in charts
- **Mapbox GL JS**: Required only for mapbox traces (requires API token)
- **virtual-webgl**: v1.0.6+ if displaying multiple WebGL charts on a single page

## 2. Installation

### Option A: NPM (Recommended for Bundled Applications)

Install the minified distribution package:
```bash
npm install plotly.js-dist-min

For debugging/development (unminified):

npm install plotly.js-dist

Import in your application:

// ES6 Module
import Plotly from 'plotly.js-dist-min';

// CommonJS
var Plotly = require('plotly.js-dist-min');

Option B: CDN (Recommended for Static HTML)

Add to your HTML <head>. Important: Always specify an exact version. As of v2.0, plotly-latest is frozen at v1.58.5 and will not receive updates.

<!-- Minified (Production) -->
<script src="https://cdn.plot.ly/plotly-3.3.1.min.js" charset="utf-8"></script>

<!-- Unminified (Development) -->
<script src="https://cdn.plot.ly/plotly-3.3.1.js" charset="utf-8"></script>

Alternative: ES6 Module import in browser:

<script type="module">
    import "https://cdn.plot.ly/plotly-3.3.1.min.js"
    Plotly.newPlot("gd", [{ y: [1, 2, 3] }])
</script>

Option C: Build from Source (For Development/Contributing)

# Clone repository
git clone https://github.com/plotly/plotly.js.git
cd plotly.js

# Install dependencies
npm install

# Build distribution bundles (generates dist/ folder)
npm run build

3. Configuration

Bundle Selection

Plotly.js provides multiple official bundles optimized for different use cases. See dist/README.md for available bundles (basic, cartesian, geo, gl3d, etc.).

For minimal bundles, import specific trace types:

// Example: Import only scatter and bar traces
var Plotly = require('plotly.js/lib/core');
Plotly.register([
    require('plotly.js/lib/scatter'),
    require('plotly.js/lib/bar')
]);

MathJax Configuration

Add MathJax before Plotly.js for LaTeX support:

MathJax v2:

<script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js?config=TeX-AMS-MML_SVG.js"></script>

MathJax v3 (SVG output for plots):

<script src="https://cdn.jsdelivr.net/npm/mathjax@3.2.2/es5/tex-svg.js"></script>

Note: MathJax v3 allows chtml output for the page alongside svg for Plotly. Reference devtools/test_dashboard/index-mathjax3chtml.html for implementation.

WebGL Context Management

For pages with multiple WebGL charts (3D plots, scattergl), load virtual-webgl before Plotly to overcome browser context limits:

<script src="https://unpkg.com/virtual-webgl@1.0.6/src/virtual-webgl.js"></script>
<script src="https://cdn.plot.ly/plotly-3.3.1.min.js"></script>

Mapbox Configuration (if using maps)

Obtain a Mapbox access token and configure per-chart:

Plotly.newPlot('gd', data, layout, {
    mapboxAccessToken: 'YOUR_MAPBOX_TOKEN'
});

4. Build & Run

Development Workflow

After cloning and installing dependencies:

# Start development server (serves test dashboard)
npm start

# Run tests
npm test

# Build specific bundles
npm run build -- --outdist dist/plotly-custom.js --traces scatter,bar

Creating Custom Bundles

To optimize bundle size for production, create a custom bundle containing only required trace types:

  1. Create an entry file (e.g., custom-plotly.js):
module.exports = require('./lib/core');
module.exports.register([
    require('./lib/scatter'),
    require('./lib/bar'),
    // Add only needed traces
]);
  1. Build using the project's build tools (requires webpack/rollup configuration as per CUSTOM_BUNDLE.md):
npm run custom-bundle -- --input ./custom-plotly.js --output ./dist/plotly-custom.min.js

Basic Usage Example

<!DOCTYPE html>
<html>
<head>
    <script src="https://cdn.plot.ly/plotly-3.3.1.min.js"></script>
</head>
<body>
    <div id="gd" style="width:600px;height:400px;"></div>
    <script>
        Plotly.newPlot("gd", {
            "data": [{ 
                "x": [1, 2, 3], 
                "y": [4, 5, 6], 
                "type": "scatter" 
            }],
            "layout": { 
                "title": "Sample Plot",
                "width": 600, 
                "height": 400 
            }
        });
    </script>
</body>
</html>

5. Deployment

Production CDN Strategy

  • Pin exact versions: Never use plotly-latest.min.js in production (frozen at v1.58.5)
  • Use minified bundles: plotly-3.3.1.min.js vs unminified .js
  • Subresource Integrity (SRI): Use integrity hashes when available
  • Fastly CDN: Primary CDN is https://cdn.plot.ly/ (backed by Fastly)

NPM Package Deployment

For applications using bundlers (webpack, rollup, vite):

// Import specific modules for tree-shaking
import Plotly from 'plotly.js-dist-min';
  • The plotly.js-dist-min package is pre-built; no additional webpack configuration required
  • For custom builds, ensure your bundler handles JSON and d3 dependencies

Server-Side Rendering (SSR)

Plotly.js requires a browser environment (DOM, Canvas, WebGL). For SSR:

  • Use plotly.js-dist-min with jsdom or similar DOM emulation
  • Or generate static images using the separate orca tool (Plotly's image export utility)

Performance Optimization

  • Bundle Splitting: Load heavy trace types (3D, maps) only when needed via dynamic imports
  • Web Workers: Consider using webgl-dist variants for heavy computational tasks
  • Asset Compression: Ensure gzip/brotli compression on CDN (handled automatically by cdn.plot.ly)

6. Troubleshooting

WebGL Context Limit

Symptom: "Too many active WebGL contexts" or black/blank 3D charts Solution:

  • Load virtual-webgl.js before Plotly (see Configuration section)
  • Limit simultaneous WebGL charts to <16 per page without virtual-webgl
  • Use SVG trace types (scatter vs scattergl) for simpler datasets

Bundle Size Issues

Symptom: JavaScript bundle >3MB Solution:

  • Switch from full bundle to partial bundles (e.g., plotly-basic.min.js for basic charts)
  • Create custom bundles with only required trace types (see CUSTOM_BUNDLE.md)
  • Use CDN with browser caching instead of bundling

MathJax Not Rendering

Symptom: LaTeX strings display as raw text (e.g., $\alpha$) Solution:

  • Verify MathJax loads before Plotly
  • Check browser console for MathJax loading errors
  • For MathJax v3, ensure using tex-svg.js or tex-mml-svg.js, not just tex-chtml.js
  • Verify config attribute points to TeX-AMS-MML_SVG for v2

Version Conflicts

Symptom: "Plotly is not defined" or method errors Solution:

  • Check that plotly-latest URL is not being used (frozen at v1.58.5)
  • Verify no duplicate Plotly loads (CDN + npm)
  • Check browser console for specific version mismatch errors

Build Errors (Development)

Symptom: npm install fails on node-gyp or canvas dependencies Solution:

  • Install system dependencies: build-essential, libcairo2-dev, libpango1.0-dev, libjpeg-dev, libgif-dev, librsvg2-dev (Ubuntu/Debian)
  • For Windows, use npm install --build-from-source with Windows Build Tools
  • Use Node.js LTS version (14, 16, 18, or 20)

Map Charts Not Displaying

Symptom: Blank map tiles or "Access Token Required" error Solution:

  • Provide valid Mapbox access token in layout or config
  • Check browser network tab for 401 errors on mapbox API calls
  • Verify internet connection (tiles loaded from Mapbox servers)
← Project overviewView alternatives to plotly/plotly.js →