We’re building a small Webpack-powered JavaScript app that loads “heavy” features only when the user needs them, using code splitting and dynamic import(). This directly improves startup time by shrinking the initial bundle and deferring non-critical code. Prerequisites: Node.js 18+ (or 20+), basic ES modules knowledge, and comfort running terminal commands.
SETUP: project scaffold + Webpack install
This setup creates a minimal, reproducible baseline: one entry file, one HTML file, and a Webpack config that outputs hashed bundles. Hashes matter because code splitting creates multiple files and you want long-term caching without cache bugs.
mkdir webpack-code-splitting-demo
cd webpack-code-splitting-demo
npm init -y
npm install --save-dev webpack webpack-cli webpack-dev-server html-webpack-plugin clean-webpack-plugin
mkdir -p src
touch src/index.js src/heavy-math.js src/analytics.js src/styles.css
Next, add scripts so you can run a dev server and produce a production build. The dev server is the fastest way to verify that dynamic chunks are requested only when needed.
{
"name": "webpack-code-splitting-demo",
"version": "1.0.0",
"private": true,
"type": "module",
"scripts": {
"dev": "webpack serve --mode development",
"build": "webpack --mode production",
"analyze:stats": "webpack --mode production --profile --json > dist/stats.json"
},
"devDependencies": {
"clean-webpack-plugin": "^4.0.0",
"html-webpack-plugin": "^5.6.0",
"webpack": "^5.90.0",
"webpack-cli": "^5.1.4",
"webpack-dev-server": "^5.0.4"
}
}
Create the HTML template Webpack will inject scripts into. HtmlWebpackPlugin will automatically add the right bundle filenames (including hashed chunk names) so you don’t hardcode script tags.
<!-- src/index.html -->
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Webpack Code Splitting Demo</title>
</head>
<body>
<div id="app"></div>
</body>
</html>
Add a tiny stylesheet so you can visually confirm the app is running. Webpack can handle CSS too, but to keep the guide focused on code splitting we’ll inject it in a simple way later.
/* src/styles.css */
:root {
font-family: system-ui, -apple-system, Segoe UI, Roboto, Arial, sans-serif;
}
#app {
max-width: 820px;
margin: 40px auto;
padding: 16px;
}
button {
margin-right: 12px;
padding: 10px 14px;
border-radius: 8px;
border: 1px solid #ddd;
background: #fff;
cursor: pointer;
}
pre {
background: #f6f8fa;
padding: 12px;
border-radius: 8px;
overflow: auto;
}
⚠️ Note: The
"type": "module"inpackage.jsonmakes Node treatwebpack.config.jsas ESM too. If you prefer CommonJS config, remove"type": "module"and userequire()in the config.
IMPLEMENTATION 1: Webpack config with split chunks + long-term caching
This config does three performance-focused jobs: cleans old builds, generates HTML with correct script tags, and enables chunk splitting so shared code can be cached. It also outputs content-hashed filenames so browsers keep stable files cached across deploys.
import path from "node:path";
import { fileURLToPath } from "node:url";
import HtmlWebpackPlugin from "html-webpack-plugin";
import { CleanWebpackPlugin } from "clean-webpack-plugin";
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
export default {
entry: path.join(__dirname, "src", "index.js"),
output: {
path: path.join(__dirname, "dist"),
filename: "assets/[name].[contenthash:8].js",
chunkFilename: "assets/[name].[contenthash:8].js",
publicPath: "/",
},
devtool: "source-map",
devServer: {
static: {
directory: path.join(__dirname, "dist"),
},
port: 3000,
open: true,
hot: true,
historyApiFallback: true,
},
plugins: [
new CleanWebpackPlugin(),
new HtmlWebpackPlugin({
template: path.join(__dirname, "src", "index.html"),
}),
],
optimization: {
runtimeChunk: "single",
splitChunks: {
chunks: "all",
minSize: 10_000,
cacheGroups: {
vendors: {
test: /[\\/]node_modules[\\/]/,
name: "vendors",
chunks: "all",
},
},
},
},
module: {
rules: [
{
test: /\.css$/i,
type: "asset/source",
},
],
},
resolve: {
extensions: [".js"],
},
};
Run the dev server to confirm the baseline works (even before we render UI). You should see a blank page, which is expected because we haven’t populated #app yet.
npm run dev
Expected result: your browser opens http://localhost:3000 and shows an empty page with no errors in the console. The Network tab should show one main bundle request (plus the runtime chunk) at this stage.
⚠️ Note: If you see 404s for bundles, it’s usually a
publicPathmismatch. KeeppublicPath: "/"for dev server, and ensure you’re not serving the app from a subdirectory without adjusting it.
IMPLEMENTATION 2: Dynamic imports for “heavy” features (true code splitting)
Now we’ll build a UI with two buttons: one triggers a heavy calculation module, the other loads an analytics module. The key is using import() inside the click handler so Webpack creates separate chunks and only downloads them on demand.
import stylesText from "./styles.css";
function injectStyles(cssText) {
const style = document.createElement("style");
style.textContent = cssText;
document.head.append(style);
}
function renderApp() {
const app = document.querySelector("#app");
app.innerHTML = `
<h2>Webpack Code Splitting Demo</h2>
<p>Open DevTools → Network. Click buttons and watch new chunk files download only when needed.</p>
<div>
<button id="btn-calc">Run heavy calculation</button>
<button id="btn-analytics">Load analytics</button>
</div>
<h3>Output</h3>
<pre id="output">Ready.</pre>
`;
const output = app.querySelector("#output");
const calcBtn = app.querySelector("#btn-calc");
const analyticsBtn = app.querySelector("#btn-analytics");
calcBtn.addEventListener("click", async () => {
output.textContent = "Loading heavy-math chunk...";
const { runHeavyCalculation } = await import(
/* webpackChunkName: "heavy-math" */
"./heavy-math.js"
);
const startedAt = performance.now();
const result = runHeavyCalculation(250_000);
const elapsedMs = Math.round(performance.now() - startedAt);
output.textContent = `Heavy calculation result: ${result}\nTime: ${elapsedMs}ms`;
});
analyticsBtn.addEventListener("click", async () => {
output.textContent = "Loading analytics chunk...";
const { initAnalytics, trackEvent } = await import(
/* webpackChunkName: "analytics" */
"./analytics.js"
);
initAnalytics();
trackEvent("button_click", { buttonId: "btn-analytics" });
output.textContent = "Analytics loaded. Check the console for events.";
});
}
injectStyles(stylesText);
renderApp();
Create the “heavy” module. This code is intentionally CPU-heavy to simulate expensive logic (or a large dependency) that you don’t want in the initial bundle.
export function runHeavyCalculation(iterations) {
let acc = 0;
for (let i = 0; i < iterations; i += 1) {
// A bit of math to keep the loop from being optimized away too easily.
acc += Math.sqrt(i ^ (i >> 3)) % 97;
}
return Math.round(acc);
}
Create the analytics module. In real apps this might wrap a vendor SDK, which is a perfect candidate for lazy loading because it’s often non-critical for first paint.
let analyticsReady = false;
export function initAnalytics() {
if (analyticsReady) return;
analyticsReady = true;
console.log("[analytics] initialized");
}
export function trackEvent(name, payload) {
if (!analyticsReady) {
console.warn("[analytics] trackEvent called before init; initializing now");
initAnalytics();
}
const event = {
name,
payload,
at: new Date().toISOString(),
};
console.log("[analytics] event", event);
}
Expected result: refresh the page, open DevTools → Network, and click “Run heavy calculation.” You should see a new request for a chunk named something like heavy-math.[hash].js. Clicking “Load analytics” should request analytics.[hash].js and print logs in the console.
⚠️ Note: If you accidentally write
import { runHeavyCalculation } from "./heavy-math.js"at the top level, Webpack will include it in the initial bundle and you won’t get code splitting. Dynamic import must happen inside a function path that runs later.
IMPLEMENTATION 3: Prefetch/preload hints + splitting shared code
Some chunks are “not needed now, but probably soon.” Webpack supports resource hints like prefetch to download a chunk in idle time after initial load. This can make button clicks feel instant without bloating the initial bundle.
Update the analytics import to prefetch. This keeps initial JS smaller while allowing the browser to fetch analytics when it has bandwidth.
import stylesText from "./styles.css";
function injectStyles(cssText) {
const style = document.createElement("style");
style.textContent = cssText;
document.head.append(style);
}
function renderApp() {
const app = document.querySelector("#app");
app.innerHTML = `
<h2>Webpack Code Splitting Demo</h2>
<p>Open DevTools → Network. Click buttons and watch chunks download on demand.</p>
<div>
<button id="btn-calc">Run heavy calculation</button>
<button id="btn-analytics">Load analytics</button>
</div>
<h3>Output</h3>
<pre id="output">Ready.</pre>
`;
const output = app.querySelector("#output");
const calcBtn = app.querySelector("#btn-calc");
const analyticsBtn = app.querySelector("#btn-analytics");
calcBtn.addEventListener("click", async () => {
output.textContent = "Loading heavy-math chunk...";
const { runHeavyCalculation } = await import(
/* webpackChunkName: "heavy-math" */
"./heavy-math.js"
);
const startedAt = performance.now();
const result = runHeavyCalculation(250_000);
const elapsedMs = Math.round(performance.now() - startedAt);
output.textContent = `Heavy calculation result: ${result}\nTime: ${elapsedMs}ms`;
});
analyticsBtn.addEventListener("click", async () => {
output.textContent = "Loading analytics chunk...";
const { initAnalytics, trackEvent } = await import(
/* webpackChunkName: "analytics" */
/* webpackPrefetch: true */
"./analytics.js"
);
initAnalytics();
trackEvent("button_click", { buttonId: "btn-analytics" });
output.textContent = "Analytics loaded. Check the console for events.";
});
}
injectStyles(stylesText);
renderApp();
Expected result: after a hard refresh, you may see the analytics chunk appear in Network with a “prefetch” initiator (browser-dependent). It should download after the initial page becomes idle, and clicking “Load analytics” should feel faster.
⚠️ Note: Prefetch is a hint, not a guarantee. Browsers may ignore it on slow connections or data-saver mode, so your code must still work if the chunk isn’t already cached.
TESTING/VERIFICATION: prove you’re shipping less JS up front
First verify behavior in devtools: initial page load should not request heavy-math or analytics until you click (or until prefetch runs). Then verify production output: you should see multiple files in dist/assets rather than a single giant bundle.
npm run build
ls -R dist
Expected result: dist contains an index.html plus several JS files like runtime.[hash].js, main.[hash].js, and chunk files such as heavy-math.[hash].js and analytics.[hash].js.
To quantify what Webpack did, generate a stats file you can feed into tools like webpack-bundle-analyzer later. Even without extra tooling, the stats file is useful for CI artifacts and comparing builds over time.
npm run analyze:stats
node -e "const s=require('./dist/stats.json'); console.log({assets: s.assets.length, chunks: s.chunks.length});"
Expected result: the command prints counts for assets and chunks (both should be greater than 1). If chunks stay at 1, you likely imported everything statically or disabled splitting.
⚠️ Note: If you test only in development mode, you may misread performance. Always run
npm run buildand test the production output because minification, tree-shaking, and chunking behavior differ.
WRAP-UP
You built a Webpack app that improves startup performance by splitting non-critical features into on-demand chunks, with caching-friendly hashed filenames and optional prefetching for likely-next code. Next steps: add route-based splitting (one chunk per page), introduce a real analytics SDK, and plug in a bundle visualizer to set size budgets so performance regressions get caught early.
