Plotly.js Multi-Version Support (v1, v2, v3)

# Check npm dependency
grep -E "\"plotly.js|\"react-plotly" package.json

# Also check for CDN usage in HTML files
grep -r "cdn.plot.ly/plotly\|plotly-latest\|plotly\.js" --include="*.html" .

Extract the major version number:

const plotlyVersion = pkg.dependencies?.['plotly.js'] ||
                      pkg.devDependencies?.['plotly.js'] ||
                      pkg.dependencies?.['plotly.js-dist'] ||
                      pkg.dependencies?.['plotly.js-dist-min'];
const major = parseInt(plotlyVersion?.match(/\d+/)?.[0] ?? '');

Also check for partial bundles — Plotly ships several:

• plotly.js — full bundle (~3.5 MB minified)
• plotly.js-dist / plotly.js-dist-min — pre-bundled full distribution
• plotly.js-basic-dist — basic charts only (scatter, bar, pie)
• plotly.js-cartesian-dist — cartesian charts
• plotly.js-geo-dist — geographic charts
• plotly.js-gl3d-dist — WebGL 3D charts
• plotly.js-gl2d-dist — WebGL 2D charts (removed in v3)
• plotly.js-mapbox-dist — mapbox charts (deprecated in v3)
• plotly.js-finance-dist — financial charts

The partial bundle determines which chart types are available. If the user tries to use a chart type not in their bundle, suggest either switching to the full bundle or the appropriate partial bundle.

Competing Library Detection

Before suggesting Plotly.js patterns, scan for existing charting libraries:

grep -E "\"chart\.js\"|\"recharts\"|\"victory\"|\"highcharts\"|\"apexcharts\"|\"echarts\"|\"@nivo\"|\"visx\"|\"d3\"" package.json

If a competing library is found, ask the user before proceeding. Plotly can coexist with other libraries, but mixing chart libraries in the same project adds bundle size and inconsistency.

Exception: d3 as a dependency does not count as a competing chart library — Plotly.js itself uses D3 internally. Only flag D3 if the user is using it directly for charting (check for d3.select patterns creating SVG charts).

Version-Specific Breaking Changes

Plotly.js v1.x (Legacy)

• Title: Accepts plain string title: "My Chart" — this is the original format
• Transforms: Supported (aggregate, filter, groupby, sort)
• jQuery events: $(graphDiv).on('plotly_click', ...) works
• AMD/UMD: Bundle supports RequireJS and AMD loaders
• GL traces: pointcloud and heatmapgl available
• Mapbox: Full scattermapbox, choroplethmapbox, densitymapbox support
• Build target: ES5
• Note: v1 is no longer maintained. Security patches and new features only land in v2+/v3+

Plotly.js v2.x

Key changes from v1:

• Title format: title: { text: "My Chart" } is now the canonical form. Plain strings still work but are deprecated
• mapbox traces deprecated (v2.35+): New map traces introduced (scattermap, choroplethmap, densitymap) using MapLibre instead of Mapbox GL JS — no access token needed
• subtitle added (v2.34+): layout.title.subtitle for chart subtitles
• Multiple legends (v2.22+): legend2, legend3, etc. in layout
• zorder (v2.31+): Control stacking order of cartesian traces
• Bar corner radius (v2.29+): marker.cornerradius for rounded bars
• insiderange (v2.27+): Avoid tick label overlap on inner axes
• Shape labels (v2.19+): label attribute on shapes with texttemplate
• Container-referenced legends (v2.23+): legend.xref/yref = "container"
• TypeScript types: Available via @types/plotly.js (community maintained)

// v2 title (canonical form)
Plotly.newPlot('div', data, {
  title: { text: 'Revenue by Quarter', font: { size: 20 } }
});

// v2.35+ map traces (replaces mapbox)
{
  type: 'scattermap',
  lat: [45.5, 46.0],
  lon: [-73.5, -74.0],
  mode: 'markers'
}

Plotly.js v3.x (Current — latest: 3.4.0)

Major breaking changes from v2:

1. String Titles Removed (CRITICAL)

// v1-v2: Plain string works