At 11:47 PM last Friday, a frontend deploy looked clean, CI was green, and the “data panel” still crashed in production. The bug was boring on the surface: import data from './flags.json' worked in local tooling, but real browsers rejected it with strict MIME errors. The part that made it expensive was not syntax, it was assumptions. We treated JSON as “just another file,” while the platform treated it as a distinct module type with explicit security rules.

This post is the runbook I wish we had before that incident. If you are moving modern apps to native ESM in 2026, JavaScript import attributes are one of those small features that save you from very large outages.

Why import attributes exist (and why they are not optional theater)

On the web, module loading is tied to MIME types, not filename endings. A URL ending in .json can still return a different content type if a proxy, CDN rule, or origin config goes wrong. Import attributes make the expected module type explicit, which closes a class of “wrong content, still executed” failures.

In plain English, you are declaring intent at import time:

• “This file must be JSON.”
• “If it is not JSON, fail fast.”

That gives you tighter security posture and clearer errors during rollouts.

The 2026 baseline you can actually plan around

Based on current platform docs, modern support is now practical for production defaults:

• Node.js ESM docs show import attributes are stable and import assertions were removed in newer lines.
• MDN documents with { type: 'json' } as the standard syntax and explains runtime behavior.
• Can I Use reports broad support across current Chromium, Firefox, and Safari generations.

That means the right strategy in 2026 is not “wait forever,” it is “ship with compatibility guardrails.”

A practical migration pattern: strict by default, graceful by boundary

The mistake teams make is all-or-nothing conversion. A better pattern is:

1. Use import attributes in all native ESM entry points.
2. Keep compatibility wrappers at system boundaries (SSR workers, legacy scripts, build plugins).
3. Monitor module-load errors separately from API/runtime errors.

If this sounds familiar, it is the same principle we use in frontend reliability work: narrow blast radius, then expand confidently. We used a similar staged approach in our BFCache state-restore playbook and service worker update runbook.

Code pattern 1: browser-side JSON import with explicit expectations

// config-loader.js (native ESM in browser)
export async function loadFeatureFlags() {
  // Explicitly require JSON module semantics
  const mod = await import('/assets/flags.json', {
    with: { type: 'json' }
  });

  // JSON modules export through `default`
  const flags = mod.default;

  // Minimal shape validation for safer startup
  if (!flags || typeof flags !== 'object' || !('releaseRing' in flags)) {
    throw new Error('Invalid flags schema');
  }

  return flags;
}

Tradeoff: this is stricter, so bad CDN headers fail harder. That is good for integrity, but you should pair it with fast rollback and config observability, similar to the failure containment ideas in our rendering integrity guide.

Code pattern 2: Node.js ESM loader that tolerates mixed runtime estates

// load-json.mjs
import { readFile } from 'node:fs/promises';

export async function loadJsonPortable(fileUrl) {
  try {
    // Preferred in modern Node lines
    const mod = await import(fileUrl, { with: { type: 'json' } });
    return mod.default;
  } catch (err) {
    // Boundary fallback for older/heterogeneous environments
    if (
      err &&
      (String(err.code).includes('ERR_IMPORT') ||
       String(err.message).includes('type'))
    ) {
      const raw = await readFile(new URL(fileUrl), 'utf8');
      return JSON.parse(raw);
    }
    throw err;
  }
}

Tradeoff: fallback logic adds maintenance cost and can hide rollout drift if you never remove it. Set a sunset date. Fallbacks should be temporary operational scaffolding, not permanent architecture.

What usually breaks in real deployments

Most incidents are not syntax errors. They are environment mismatches:

• Origin serves JSON as text/plain or application/octet-stream.
• Edge rule rewrites headers on cache hit but not miss.
• SSR runtime pinned to older Node in one region.
• Bundler transforms syntax inconsistently between app and worker.

This is the same class of split-brain behavior we saw in Node.js permission rollouts: control plane says “done,” runtime reality says “not everywhere.”

Troubleshooting: quick diagnosis map

1) “Expected a JavaScript module script but got application/json”

• Cause: missing with { type: 'json' } in browser import.
• Fix: add import attribute and redeploy.

2) “Import attribute type unsupported” (or similar)

• Cause: runtime line is older than your assumed baseline.
• Fix: verify browser/Node versions, then apply boundary fallback while upgrading.

3) Works in one region, fails in another

• Cause: inconsistent CDN/header policy or staggered runtime image rollout.
• Fix: compare response headers and runtime versions by region, then enforce a single deploy artifact + config bundle.

4) JSON import passes, app still crashes

• Cause: payload shape changed; module loaded correctly but contract broke.
• Fix: add schema validation and version fields at load boundary.

A rollout checklist that avoids midnight rollback

When we introduced this pattern, the biggest win came from sequencing, not clever code. Here is the order that worked:

1. Inventory import points: find every direct JSON import in browser, SSR, worker, and tooling code paths.
2. Enable attributes in leaf modules first: start where blast radius is smallest, then move toward app entry points.
3. Pin runtime minimums: lock Node and browser support assumptions in CI so new environments cannot silently regress.
4. Add header checks: verify Content-Type: application/json on all JSON-module endpoints in smoke tests.
5. Expose one clear metric: chart module-load failures per release ring, not mixed into generic JS errors.

The tradeoff here is process overhead. You spend extra setup time in exchange for much lower incident volatility. In my experience, that is a good deal, especially on teams that already run frequent deploys. If you are shipping often, defensive clarity is cheaper than heroic debugging.

FAQ

Q1) Can I skip import attributes if my JSON is local and trusted?

You can, but you should not for production ESM paths. The value is not only security against hostile servers, it is deterministic behavior when infrastructure changes unexpectedly.

Q2) Are import attributes the same as old import assertions?

No. Assertions used the assert form. Current docs and runtimes are aligned on with syntax for import attributes. Treat assert as legacy migration history, not new default.

Q3) Do bundlers remove the need to care about this?

Only partially. Bundlers can abstract syntax, but native ESM boundaries still exist in browsers, workers, SSR edges, and plugin ecosystems. You still need explicit runtime policy.

Actionable takeaways

• Adopt JavaScript import attributes as the default for JSON modules in native ESM entry points.
• Define one temporary compatibility fallback for mixed runtime estates, with a removal date.
• Add CI checks for content-type headers on JSON module endpoints.
• Track module-load errors as a first-class signal in observability dashboards.
• Document boundary ownership, so app, CDN, and platform teams do not assume someone else owns MIME integrity.

If your app already survived service worker churn, BFCache edge cases, and render regressions, this is the same discipline in a smaller package: be explicit at the boundary, fail predictably, and recover fast.