D3 v7 ES Module Transition: Why Local Scripts Fail in Production

The Root Cause

Local development servers typically serve files from the root (/), whereas production deployments often use subpaths (/app/). Because d3.json uses the native Fetch API, relative paths are resolved against the current browser URL. If your app is at example.com/app/index.html, a request for data.json targets example.com/app/data.json instead of the root, leading to 404 errors.

Likely Explanations vs. Confirmed Facts

Confirmed Facts

• ESM Nature: D3 v7 is distributed as ES modules. Importing it via import * as d3 from 'd3' does not create a window.d3 object.
• Fetch Dependency: d3.json is a wrapper for fetch(). It is subject to the Same-Origin Policy and requires Access-Control-Allow-Origin headers if the data resides on a different domain.

Likely Explanations

• Path Mismatch: The failure in production is most likely a 404 caused by the subpath resolution rather than a D3-specific bug.
• Tree-Shaking: If legacy scripts are failing, the bundler has likely removed the D3 reference because it wasn't explicitly attached to the global scope.

Resolution Steps

1. Fix Asset Path Resolution

Avoid hard-coded relative strings. Use a base URL variable provided by your bundler (e.g., process.env.PUBLIC_URL in React/Webpack) to prefix your data paths:

const dataPath = `${process.env.PUBLIC_URL}/data/dataset.json`;
d3.json(dataPath).then(data => { ... });

2. Handle CORS for External Data

If the JSON is hosted on a separate server, ensure that server returns the following header. Do not use * in production; specify your actual domain:

Access-Control-Allow-Origin: https://your-production-domain.com

3. Restore Global d3 for Legacy Code

If you have non-module scripts that expect a global d3 object, explicitly assign it in your main entry point (e.g., index.js):

import * as d3 from 'd3';
window.d3 = d3;
// Now legacy scripts can access d3.select()

Verification

To isolate the failure, check the browser Network Tab:

• 404 Not Found: The path is incorrect. Compare the requested URL with the actual file location on the server.
• CORS Error: The request reached the server, but the server rejected the origin.
• ReferenceError (d3 is not defined): The ESM import is working, but the global object was never assigned.

Missing Diagnostic: Are the JSON files hosted on the same origin as the HTML, or a separate CDN/API server?