Design and Implementation of a Universal Bundler Based on esbuild

Background

Because Lynx's cross‑platform compilation tool differs significantly from traditional web toolchains (e.g., no dynamic style/script, bundle‑less and code‑splitting are unavailable, module system based on JSON, no browser environment), a universal bundler that works locally and in the browser and can be customized per business needs was required. The team built such a bundler on top of esbuild.

What is a Bundler

A bundler packages code organized as modules into one or more output files. Common bundlers include webpack, rollup, and esbuild. While most focus on JavaScript modules, they also support other module types such as WASM, JSON‑based components, CSS, and HTML imports.

webpack – strong plugin system, HMR, broad module compatibility, but produces less clean output and lacks native ESM output.

rollup – excellent for library development, clean output, good tree‑shaking, but limited CJS support and no HMR.

esbuild – extremely fast (100× faster than webpack/rollup), built‑in support for CSS, images, React, TypeScript, but has a simpler plugin ecosystem.

How a Bundler Works

Similar to compilers, bundlers use a three‑stage design: they first build a module graph, then apply optimizations like tree‑shaking, code‑splitting, and minification, and finally generate code in the requested format.

Rollup Example

Rollup’s bundling process consists of two steps: rollup() (frontend) and generate() (backend). The following snippets illustrate a minimal rollup workflow.

import lib from './lib';
console.log('lib:', lib);

const rollup = require('rollup');
const util = require('util');
async function main() {
  const bundle = await rollup.rollup({
    input: ['./src/index.js'],
  });
  console.log(util.inspect(bundle.cache.modules, { colors: true, depth: null }));
}
main();

Plugin System

Most bundlers expose a plugin API. For rollup, plugins have input (module‑graph creation) and output (code generation) hooks. esbuild’s plugin system is demonstrated with a simple LESS loader:

export const less = (): Plugin => {
  return {
    name: 'less',
    setup(build) {
      build.onLoad({ filter: /.less$/ }, async (args) => {
        const content = await fs.promises.readFile(args.path);
        const result = await render(content.toString());
        return { contents: result.css, loader: 'css' };
      });
    },
  };
};

More advanced plugins handle sourcemaps, caching, and error reporting, as shown in the Svelte loader example.

let sveltePlugin = {
  name: 'svelte',
  setup(build) {
    let svelte = require('svelte/compiler');
    let path = require('path');
    let fs = require('fs');
    let cache = new LRUCache();
    build.onLoad({ filter: /.svelte$/ }, async (args) => {
      let value = cache.get(args.path);
      let input = await fs.promises.readFile(args.path, 'utf8');
      if (value && value.input === input) return value;
      // compile and return
    });
  },
};

Virtual Modules

esbuild’s support for virtual modules enables powerful patterns such as glob imports, memory‑based modules, and function‑style modules.

export const pluginGlob = (): Plugin => {
  return {
    name: 'glob',
    setup(build) {
      build.onResolve({ filter: /^glob:/ }, (args) => ({
        path: path.resolve(args.resolveDir, args.path.replace(/^glob:/, '')),
        namespace: 'glob',
        pluginData: { resolveDir: args.resolveDir },
      }));
      build.onLoad({ filter: /.*/, namespace: 'glob' }, async (args) => {
        const matchPath = await new Promise((resolve, reject) => {
          glob(args.path, { cwd: args.pluginData.resolveDir }, (err, data) => {
            if (err) reject(err); else resolve(data);
          });
        });
        const result = {};
        await Promise.all(matchPath.map(async (x) => {
          const contents = await fs.promises.readFile(x);
          result[path.basename(x)] = contents.toString();
        }));
        return { contents: JSON.stringify(result), loader: 'json' };
      });
    },
  };
};

Other virtual‑module patterns include environment‑based modules, function‑style modules (e.g., Fibonacci), and streaming imports from CDNs.

Universal Bundler Challenges

Porting a bundler to the browser requires handling filesystem abstraction (memfs), node‑style module resolution, main‑field prioritization, conditional exports, and shims/polyfills for Node APIs. Strategies include using enhanced‑resolve with a custom FS, leveraging unpkg for on‑demand CDN loading, and applying eval‑wrapped requires to externalize modules.

Where esbuild Fits

esbuild can serve as a minifier, transformer, and bundler. It excels as a fast pre‑bundle tool, a register replacement for ts‑node, and a backend bundler for Node services, offering benefits such as reduced bundle size, faster cold starts, and protection against upstream semver breaks.

Limitations

Debugging is difficult because the core is compiled Go binary.

Only supports target >= ES6; additional transpilation is needed for ES5 environments.

Go‑compiled WASM has performance and size overhead.

Plugin API is limited to onLoad and onResolve, lacking hooks for post‑chunk processing.

Overall, the article provides a comprehensive guide to building a universal bundler using esbuild, addressing both technical concepts and practical implementation details.