Preventing Waterfall Requests with Dynamic Import Maps

Modern SPAs suffer from module resolution bottlenecks when dynamic chunk discovery occurs at runtime. This guide establishes deterministic loading patterns within the broader Route-Based Code Splitting & Dynamic Import Strategies framework. By implementing native import maps, you shift dependency resolution to the browser level, eliminating sequential fetch chains and enabling parallel HTTP/2 multiplexing from the initial route transition.

Error Signature: Identifying Sequential Module Waterfalls

Diagnose cascading fetches by auditing the network waterfall. Open Chrome DevTools > Network tab and filter by JS. Look for sequential timing gaps where the startTime of Chunk B exceeds the responseEnd of Chunk A.

Key diagnostic indicators:

  • DOMContentLoaded fires late because the main thread remains blocked waiting for nested chunk execution.
  • Elevated TTFB on secondary chunks signals missing dependency graph pre-resolution.
  • Network waterfall displays staggered, non-overlapping request bars instead of parallel multiplexing.

Root Cause: Native ES Module Resolution Cascades

Browsers resolve dynamic import() calls sequentially by default. Each chunk triggers an independent HTTP request, parse cycle, and execution phase before discovering nested imports. This directly contradicts optimized Dynamic Import Patterns for On-Demand Loading.

The bundler’s default chunk graph flattening fails to communicate the complete dependency tree to the browser’s native module loader. Consequently, runtime discovery forces the engine to block execution until each dependency resolves, creating a cascading latency penalty that scales linearly with route depth.

Exact Config/CLI Fix: Vite 5 & Webpack 5 Implementation

Implement deterministic resolution by generating and injecting import maps at build time.

Step 1: Generate build manifest

# Vite 5 — generates dist/.vite/manifest.json
npx vite build --manifest

# Webpack 5 — generates stats.json for manual processing
npx webpack --json=stats.json

Step 2: Inject <script type="importmap"> via build hook

Vite 5 (vite.config.js):

import { defineConfig } from 'vite';
import { readFileSync } from 'fs';

export default defineConfig({
  build: {
    manifest: true, // Required to generate .vite/manifest.json
  },
  plugins: [
    {
      name: 'inject-importmap',
      // transformIndexHtml runs after the manifest is written
      transformIndexHtml: {
        order: 'post',
        handler(html) {
          let manifest;
          try {
            manifest = JSON.parse(readFileSync('dist/.vite/manifest.json', 'utf-8'));
          } catch {
            return html; // Skip if manifest not yet available (e.g., dev mode)
          }
          const imports = Object.fromEntries(
            Object.entries(manifest)
              .filter(([, val]) => typeof val === 'object' && val !== null && 'file' in val)
              .map(([key, val]) => [key, `/${val.file}`])
          );
          return html.replace(
            '</head>',
            `<script type="importmap">${JSON.stringify({ imports })}</script></head>`
          );
        }
      }
    }
  ]
});

Webpack 5: Import maps are a browser-native feature; Webpack does not have a built-in output.importMap option. To inject an import map with Webpack, parse the generated stats.json and write the <script type="importmap"> tag via HtmlWebpackPlugin’s template or a custom plugin:

// webpack.config.js
const HtmlWebpackPlugin = require('html-webpack-plugin');

class ImportMapPlugin {
  apply(compiler) {
    compiler.hooks.emit.tapAsync('ImportMapPlugin', (compilation, callback) => {
      const assets = compilation.getAssets();
      const imports = {};
      for (const asset of assets) {
        if (asset.name.endsWith('.js')) {
          imports[`/src/${asset.name}`] = `/assets/${asset.name}`;
        }
      }
      compilation.importMapJson = JSON.stringify({ imports });
      callback();
    });
  }
}

module.exports = {
  output: {
    publicPath: '/assets/'
  },
  plugins: [
    new ImportMapPlugin(),
    new HtmlWebpackPlugin({
      templateParameters: (compilation) => ({
        importMap: compilation.importMapJson || '{}'
      }),
      template: 'src/index.html' // Must include <%= importMap %> in <head>
    })
  ]
};

Step 3: Flatten chunk graph & co-locate dependencies

Webpack:

// webpack.config.js
module.exports = {
  optimization: {
    splitChunks: {
      chunks: 'all',
      maxAsyncRequests: 10,
      cacheGroups: {
        vendor: { test: /[\\/]node_modules[\\/]/, name: 'vendors', chunks: 'all' },
      },
    },
  },
};

Vite:

// vite.config.js
import { defineConfig } from 'vite';

export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks(id) {
          if (id.includes('node_modules')) return 'vendor';
        },
      },
    },
  },
});

Step 4: Disable module preload polyfill if using native import maps

Vite injects a module preload polyfill by default. If you are relying on native import map support, disable it to avoid double-resolution:

// vite.config.js
import { defineConfig } from 'vite';

export default defineConfig({
  build: {
    modulePreload: { polyfill: false },
  },
});

Fallback for older browsers: For browsers lacking native import map support (Safari < 16.4, Firefox < 108), inject es-module-shims before your entry point:

<script async src="/es-module-shims.js"></script>
<script type="importmap">{ "imports": { ... } }</script>
<script type="module" src="/app-entry.js"></script>

es-module-shims intercepts import() calls and resolves them against the injected import map, falling back gracefully without altering application routing logic.

Verification Metric: Quantifying Parallel Resolution

1. Console validation

Run in DevTools Console to measure fetch deltas across dynamic chunks:

const jsResources = performance.getEntriesByType('resource')
  .filter(r => r.name.endsWith('.js') && r.initiatorType === 'script');
const maxDelta = Math.max(...jsResources.map((r, i, arr) =>
  i === 0 ? 0 : r.fetchStart - arr[i - 1].fetchStart
));
console.log(`Max fetchStart delta: ${maxDelta}ms`); // Target: < 50 ms

2. Lighthouse CI audit

npx lhci autorun --config=lighthouserc.json

Parse the report and verify:

  • audits['avoid-chaining-critical-requests'].score === 1.0
  • audits['network-requests'].details.items shows parallel timing for chunk requests

3. Network waterfall & INP tracking

Confirm DevTools Network waterfall displays parallel HTTP/2 multiplexing for all chunk requests. Instrument custom metrics to track execution latency:

performance.mark('import-start');
const module = await import('./heavy-module.js');
performance.mark('module-loaded');
performance.measure('import-execution', 'import-start', 'module-loaded');
const [entry] = performance.getEntriesByName('import-execution');
console.log(`Import execution: ${entry.duration.toFixed(1)} ms`);

Sustained parallel resolution directly reduces main-thread blocking during route transitions. Maintain fetchStart deltas near 0 ms and keep request chaining depth at 1 across all critical paths to guarantee deterministic loading behavior.

More in this section

Dynamic Import Patterns for On-Demand JS