esbuild.do API Deep Dive: Mastering Virtual Files, Loaders, and Output Formats

Build toolchains can be fragile, complex, and a pain to manage, especially across different environments like CI/CD pipelines, serverless functions, or collaborative online editors. While esbuild has set a new standard for speed, integrating it everywhere still requires managing Node.js environments and binary dependencies.

Enter esbuild.do. We provide esbuild's blazing-fast performance through a simple, robust API, letting you bundle, minify, and transpile assets without the configuration headache.

You might have seen our basic example for bundling a simple TypeScript string. Today, we're going on a deep dive to unlock the full potential of the esbuild.do agent. We'll explore three powerful features that give you granular control over your builds: virtual files, custom loaders, and output formats.

The Magic of Virtual Files with the sources Parameter

One of the most powerful features of the esbuild.do API is the ability to work with a virtual file system. Instead of needing physical files on a disk, you can pass your source code directly as strings in the sources object. The agent creates an in-memory file system, making it perfect for dynamic content generation, online playgrounds, or restricted environments.

Let's look at a multi-file example. Here we have a utils.ts that exports a function, and an index.ts that imports and uses it.

import { Agent } from '@do-business/sdk';

const esbuild = new Agent('esbuild.do');

async function bundleMultiFile() {
  const { code } = await esbuild.bundle({
    entryPoints: ['index.ts'],
    sources: {
      'index.ts': `
        import { double } from './utils';
        console.log('The double of 4 is', double(4));
      `,
      'utils.ts': `
        export const double = (n: number): number => n * 2;
      `
    },
    bundle: true,
    minify: true,
    target: 'es2020'
  });

  console.log('--- Bundled JS ---');
  console.log(code);
  // Expected output will be a minified bundle containing the logic from both files.
}

bundleMultiFile();

The agent seamlessly resolves the import ./utils within its virtual environment, bundling the two "files" together as if they were on your local disk. This abstraction is the key to integrating a powerful build step into any workflow, regardless of file system access.

Harnessing Loaders for Any File Type

Esbuild uses "loaders" to determine how to parse and include different file types in your bundle. Our API gives you full access to this feature, allowing you to bundle much more than just JavaScript and TypeScript.

The loader option lets you configure rules for specific file extensions. Let's see it in action.

1. Bundling CSS

Need to import CSS directly into your JavaScript? The css loader makes it trivial.

import { Agent } from '@do-business/sdk';

const esbuild = new Agent('esbuild.do');

async function bundleWithCSS() {
  const { code } = await esbuild.bundle({
    entryPoints: ['app.js'],
    sources: {
      'app.js': `
        import './styles.css';
        document.body.innerHTML = '<div class="container">Hello World</div>';
      `,
      'styles.css': `
        .container { 
          background-color: #f0f0f0; 
          padding: 20px; 
          border-radius: 8px; 
        }
      `
    },
    bundle: true,
    minify: true,
    // esbuild automatically picks up the .css loader, but you can be explicit
    // loader: { '.css': 'css' },
  });

  console.log('--- Bundled JS with CSS ---');
  console.log(code);
  // The output JS will contain the CSS injected into the document head!
}

bundleWithCSS();

2. Importing JSON as Objects

Seamlessly import JSON files and have them converted into JavaScript objects in your bundle.

import { Agent } from '@do-business/sdk';

const esbuild = new Agent('esbuild.do');

async function bundleWithJSON() {
  const { code } = await esbuild.bundle({
    entryPoints: ['config.js'],
    sources: {
      'config.js': `
        import settings from './settings.json';
        console.log('API URL is:', settings.apiUrl);
      `,
      'settings.json': `
        {
          "version": "1.0.0",
          "apiUrl": "https://api.example.com"
        }
      `
    },
    loader: { '.json': 'json' }, // Tell esbuild how to handle .json files
    bundle: true,
  });

  console.log('--- Bundled JS with JSON ---');
  console.log(code);
}

bundleWithJSON();

Controlling Your Build with Output Formats

Not all JavaScript is created equal. The environment where your code will run—a browser, a Node.js server, or an ES module-aware environment—dictates the required format. The esbuild.do agent gives you control over this via the format option.

The three most common formats are:

• iife (Immediately Invoked Function Expression): Wraps your code in a function (function(){...})() to prevent polluting the global scope. This is the default and is great for browser scripts.
• cjs (CommonJS): The format used by Node.js, utilizing require() and module.exports.
• esm (ES Modules): The modern standard using import and export statements, supported by modern browsers and recent versions of Node.js.

Example: Building for Node.js (CJS)

Let's build the multi-file TypeScript example from earlier, but this time targeting a Node.js environment.

import { Agent } from '@do-business/sdk';

const esbuild = new Agent('esbuild.do');

async function bundleForNode() {
  const { code } = await esbuild.bundle({
    entryPoints: ['index.ts'],
    sources: {
      'index.ts': `import { double } from './utils'; console.log(double(4));`,
      'utils.ts': `export const double = (n: number): number => n * 2;`
    },
    bundle: true,
    platform: 'node', // Important for targeting Node.js built-ins
    format: 'cjs',   // Specify CommonJS output
  });

  console.log('--- CJS Bundle for Node.js ---');
  console.log(code);
}

bundleForNode();

By changing platform and format, you can direct the same source code to entirely different JavaScript ecosystems, all through a simple API call.

Your Build Toolchain, Simplified

By mastering virtual files, loaders, and output formats, you can move beyond simple transpilation and leverage esbuild.do as a complete, high-speed build tool-as-a-service. You get the power and flexibility of a local esbuild setup without any of the installation or maintenance overhead.

Ready to streamline your development workflow and build faster than ever? Explore the esbuild.do API today and make complex build pipelines a thing of the past.