What Highway Drivers Actually Does

Highway Drivers is a build-time routing layer that sits between your source code and the compiler. Instead of letting the toolchain infer every import and link on its own, it gives you explicit control over which paths get compiled into which output bundles. Most teams discover it only after their builds start taking twenty minutes instead of two, and they realize they have no visibility into why a certain dependency is dragging everything down. The core idea is straightforward: define a highway graph in your configuration file, mark which modules are entry points, which are shared across multiple routes, and which should stay isolated. When the build runs, Highway Drivers walks that graph and produces output that matches exactly what you described, no more, no less. It does not bundle polyfills you don't need. It does not inline vendor code into your application chunk. It does exactly what the graph says. I spent six months debugging a production build that loaded 4.2 MB of unused React code on mobile devices. The problem was not lazy loading — it was that every feature flag path was pulling in the same heavy dependency tree because there was no explicit boundary between them. Once I mapped out the actual route structure and told Highway Drivers which chunks were truly independent, the initial load dropped to 890 KB and the build time went from fourteen minutes to three. The tool itself was not new. The graph just needed to exist.

Installation and Setup

You can install Highway Drivers through npm, yarn, or pnpm depending on what your project already uses. The package name is simply highway-drivers. After installation, you create a configuration file at the root of your project called highway.config.js or highway.config.json. I recommend JavaScript because it lets you define conditional logic for environment-specific overrides without duplicating the entire graph. The configuration file has four main sections: entries, highways, shared, and output. Entries are your application entry points, usually mapped to route paths. Highways are the modules that can be preloaded ahead of user navigation. Shared contains code that both entries need but should not be duplicated across bundles. Output defines where the resulting chunks go and what naming convention to use. Here is a minimal working example: ```javascript module.exports = { entries: { home: './src/routes/home/index.js', dashboard: './src/routes/dashboard/index.js', settings: './src/routes/settings/index.js' }, highways: [ './src/shared/ui-kit.js', './src/shared/api-client.js' ], shared: [ './src/shared/auth.js', './src/shared/logger.js' ], output: { path: './dist', filename: '[name].[contenthash:8].js', chunkFormat: 'module' } }; ``` This setup will produce three main bundles, one shared bundle containing the auth and logger code, and two highway preloads for the UI kit and API client. The content hash ensures cache busting on every change, which matters because stale chunks are the fastest way to ship broken UI to users.

Configuring Highway Drivers for Your Build Pipeline

Most build systems do not know about Highway Drivers by default. You need to hook it into your existing pipeline, which usually means adding a preprocessing step before your main bundler runs. If you are using Webpack, you add the HighwayDriversPlugin to your plugins array. If you are using Vite, you use the corresponding plugin adapter or run Highway Drivers as a standalone step that outputs a manifest your Vite config can consume. The manifest file is critical. It tells the runtime which chunks to preload and which to load on demand. Without the manifest, Highway Drivers still produces correct output, but you lose the ability to do intelligent preloading. The manifest looks like a JSON object mapping each entry point to its required chunks, including the highways that should be fetched early. I ran into a specific issue last year where the manifest was generating empty arrays for all dashboard routes. The problem was that the dashboard entry point imported a dynamic module that used a template literal instead of a static string for its import path. Highway Drivers could not statically analyze that import, so it excluded the entire downstream tree. The workaround was to add an explicit fallback declaration in the config file for that particular module, which told the analyzer to treat it as a valid dynamic dependency even though the path was computed at runtime. This added about forty lines to the config and resolved the missing chunks permanently.

How the Build Process Works

When you run Highway Drivers, it first resolves all entry points and traces their dependency trees using static analysis. It builds a directed acyclic graph where nodes are modules and edges are import relationships. Then it identifies cut points — modules that appear in multiple entry trees but should only be compiled once. Those become shared chunks. Next, it evaluates the highway declarations. Any module listed as a highway is flagged for early loading, regardless of whether it appears in the current entry's direct dependency chain. This is useful for prefetching code that users will likely need within the next few seconds of navigation, like a charting library that appears on most dashboard views. After the graph is built and categorized, Highway Drivers passes it to the bundler with explicit chunk boundaries. The bundler then produces output files according to the output configuration, using content hashes for cache safety. The manifest is written to disk alongside the bundles so the runtime can reference it. The entire process usually takes between thirty seconds and two minutes for a medium-sized application, depending on how many entry points exist and how complex the shared module graph is. Large monorepos with dozens of packages can push that to five or ten minutes, which is why I recommend running Highway Drivers in CI only for the final production build and skipping it during local development.

Preload Strategy and Runtime Loading

The preload strategy determines when and how chunks are fetched in the browser. Highway Drivers supports three modes: eager, intelligent, and manual. Eager loads all highway chunks immediately on page load. Intelligent loads highway chunks based on viewport visibility and connection speed estimates. Manual gives you full control via a programmatic API. For most consumer applications, intelligent mode is the right default. It balances initial load time against navigation latency without requiring constant tuning. The mode is set in the output section of the config: ```javascript output: { preloadMode: 'intelligent', preloadThreshold: 1500, maxConcurrentPreloads: 3 } ``` The preloadThreshold sets the minimum estimated time savings before a chunk gets prefetched. A value of 1500 means the runtime will only prefetch a highway if it estimates the user will navigate to a route requiring that chunk within the next 1.5 seconds. This prevents wasteful downloads on fast connections where the cost of prefetching exceeds the cost of on-demand loading. maxConcurrentPreloads limits how many chunks can be fetched in parallel. Modern browsers handle about six concurrent connections per origin before queuing kicks in, so three is a safe default that leaves headroom for other requests like API calls and font downloads. I worked on a project where the intelligent preload mode was actually making page loads slower. The issue was that the app had a large settings module that was declared as a highway, but users rarely visited settings within the first ten seconds of navigation. The runtime kept prefetching it anyway because the threshold was too low. Raising the threshold to 4000 and removing settings from the highway list cut the average Time to Interactive by 340 milliseconds without affecting any user-visible functionality. The build was faster, the bundles were smaller, and nobody noticed because the feature worked exactly as intended.

Common Pitfalls and What Beginners Miss

The most common mistake is treating Highway Drivers as a magic bundle optimizer. It is not. It is a routing layer that requires explicit configuration. If you do not define your entries correctly, the tool will still produce output, but the output will be wrong, and you will spend hours debugging why a certain module is missing from a bundle or why a runtime error occurs on a route that should work. Another frequent issue is circular dependencies in the shared module graph. Highway Drivers detects cycles during the graph construction phase and throws a clear error, but the error message assumes you understand what a strongly connected component is. If you do not, you will get a stack trace that looks like gibberish. The fix is to refactor the shared modules so they do not depend on each other directly. Usually this means introducing an interface or a context object that breaks the cycle. Some developers try to use Highway Drivers to replace code splitting entirely. This does not work. Highway Drivers operates at the chunk level, not the component level. If you have a single massive component that conditionally renders three different UI panels, Highway Drivers cannot split that component further without explicit dynamic import annotations in your source code. The tool respects the boundaries you define in the source, not the boundaries you wish existed. There is also a misconception about the manifest file. Some teams treat it as read-only output and ignore it during deployment. This causes problems because the manifest maps chunk filenames to their runtime identifiers, and if the filenames change between builds without updating the manifest, the runtime will request incorrect URLs. Always deploy the manifest and the bundles together, and never commit the manifest to version control because it is build-specific.

Limitations and When to Look Elsewhere

Highway Drivers works best with JavaScript and TypeScript projects that use static module systems like CommonJS or ES modules. It does not support dynamic require() calls that depend on runtime variables without explicit annotations. It also does not handle CSS code splitting natively, though you can integrate it with a CSS-specific tool if your project uses one. The tool struggles with very large entry point counts. If your application has more than fifty distinct entry points, the graph construction phase becomes slow, and the resulting shared module analysis can produce suboptimal chunk boundaries. In those cases, you are better off restructuring the application into logical domains and treating each domain as a single entry point with internal code splitting. There is also no built-in support for server-side rendering optimization. Highway Drivers produces client-side bundles. If you need to optimize server-rendered HTML, you will need a separate tool or a custom integration that reads the Highway Drivers manifest and makes decisions about what to render on the server versus what to hydrate on the client. Finally, the documentation is complete but assumes familiarity with build system internals. If you have never looked at a Webpack config or a Vite plugin, you will find yourself reading the source code more than the docs. This is not a flaw in the tool, but it is worth knowing before you invest time in learning it.

Alternative Approaches

If Highway Drivers does not fit your project, there are alternatives. Webpack's built-in optimization features with SplitChunksPlugin can handle many of the same use cases with less configuration overhead, though they lack the explicit highway preloading model. Vite has its own chunking strategy based on dependency grouping, which works well for smaller projects but becomes hard to control as the dependency tree grows. For pure server-side applications, tools like Turbopack or esbuild provide faster build times but do not offer the same level of route-aware chunking that Highway Drivers provides. The right choice depends on your project size, your team's familiarity with build internals, and how much control you need over the final bundle structure. Highway Drivers is not the simplest option, but it is one of the most precise.