webpack-flush-chunks

2.0.3 verified Sat Apr 25 auth: no javascript maintenance

Server-side utility to flush Webpack chunks for SSR with React Loadable or similar packages (e.g., react-universal-component). Current version is 2.0.3 (last released Oct 2018, appears to be in maintenance mode with no recent updates). It extracts CSS and JS chunks rendered on the server and returns them as string tags for injection in the HTML response. Key differentiators: supports Webpack 4 aggressive code splitting, works with chunkNames or moduleIds, and integrates seamlessly with babel-plugin-universal-import. Compared to alternatives like react-loadable's own server-side logic, this library provides more flexibility for complex chunking strategies.

Common errors

error TypeError: flushChunks is not a function ↓

cause Incorrect import (destructuring named export instead of default import).

fix

Use: import flushChunks from 'webpack-flush-chunks' (ESM) or const flushChunks = require('webpack-flush-chunks') (CJS).

error Cannot read property 'assetsByChunkName' of undefined ↓

cause webpackStats is undefined or does not have expected shape.

fix

Ensure you pass the proper webpack stats object (e.g., from stats.json). Verify it contains assetsByChunkName and chunks.

error Chunk names not found in webpack stats ↓

cause The chunkNames provided do not match any key in webpackStats.assetsByChunkName.

fix

Check the chunk names from your code splitting library (e.g., react-universal-component). Ensure they match the actual output chunk names.

error Duplicate chunks in output ↓

cause Using version <2.0.2 where duplicate filtering was not applied.

fix

Upgrade to v2.0.2 or later.

Warnings

breaking Version 2.0.0 changed internal resolution system. Chunks now identified by ID instead of name. ↓

fix Ensure your webpackStats include chunk IDs. Use chunkNames option instead of moduleIds if migrating from v1.

deprecated The moduleIds option is deprecated in favor of chunkNames. ↓

fix Switch to using chunkNames from react-universal-component's flushChunkNames or equivalent.

gotcha flushChunks expects webpackStats object from server-side build (e.g., stats.json). Client-side stats will not include chunk information. ↓

fix Use webpack's --json flag or compiler.getStats() in Node to generate stats with chunks info.

gotcha If you are using Webpack 4 with aggressive code splitting, the chunkNames may not match file names directly. Use chunk IDs instead. ↓

fix Pass chunkIds in the options object: flushChunks(webpackStats, { chunkIds: [...] })

gotcha The library does not automatically filter duplicates. If the same chunk is flushed multiple times, it will appear multiple times in output. ↓

fix Upgrade to v2.0.2+ which includes unique filter for CSS and JS.

Install

npm install webpack-flush-chunks

yarn add webpack-flush-chunks

pnpm add webpack-flush-chunks

Imports

flushChunks
wrong
```
import { flushChunks } from 'webpack-flush-chunks'
```
correct
```
import flushChunks from 'webpack-flush-chunks'
```
Default export, not named. For CommonJS: const flushChunks = require('webpack-flush-chunks').default or const flushChunks = require('webpack-flush-chunks') depending on your bundler.
flushChunks
wrong
```
const flushChunks = require('webpack-flush-chunks').default
```
correct
```
const flushChunks = require('webpack-flush-chunks')
```
In CommonJS environments that support ES modules interop, require returns the exports object directly; the default is on module.exports, not .default.

flushChunks

wrong

const { flushChunks } = require('webpack-flush-chunks')

correct

const { default: flushChunks } = require('webpack-flush-chunks')

For strict CommonJS interop, use destructuring with default.

Quickstart

Shows server-side rendering with flushChunks to inject JS and CSS tags for rendered chunks.

import flushChunks from 'webpack-flush-chunks';
import { flushChunkNames } from 'react-universal-component/server';
import React from 'react';
import ReactDOMServer from 'react-dom/server';
import App from './App';

// Assume webpackStats is from stats.json or webpack output
const webpackStats = {
  assetsByChunkName: {
    main: 'main.js',
    vendor: 'vendor.js',
  },
  chunks: [
    { id: 'main', files: ['main.js'] },
    { id: 'vendor', files: ['vendor.js'] },
  ],
  publicPath: '/',
};

const app = ReactDOMServer.renderToString(<App />);
const { js, styles } = flushChunks(webpackStats, {
  chunkNames: flushChunkNames(), // from react-universal-component
});

const html = `
<!DOCTYPE html>
<html>
<head>${styles}</head>
<body><div id="root">${app}</div>${js}</body>
</html>`;

console.log(html);