Build a library with esbuild (vol. 2)

Photo by Joseph Greve on Unsplash

A year ago I shared a post ​that explains how to build a library with esbuild. While it remains a valid solution, I developed some improvements in my tooling since its publication.

Here are these few add-ons that I hope, will be useful for your projects too.

​Source and output

It can be sometimes useful to define more than one entry point for the library — i.e. not just use a unique index.ts​ file as entry but multiple sources that provides logically-independent groups of code. esbuild supports such option through the parameter entryPoints.

For example, in my projects, I often list all the TypeScript files present in my src​ folder and use these as separate entries.

import {
  readdirSync,
  statSync
} from "fs";
import { join } from "path";

// Select all typescript files of src directory as entry points
const entryPoints = readdirSync(join(process.cwd(), "src"))
  .filter(
    (file) =>
      file.endsWith(".ts") &&
      statSync(join(process.cwd(), "src", file)).isFile()
  )
  .map((file) => `src/${file}`);

​As the output folder before each build might have been deleted, I also like to ensure it exists by creating it before proceeding.

import {
  existsSync,
  mkdirSync
} from "fs";
import { join } from "path";

// Create dist before build if not exist
const dist = join(process.cwd(), "dist");

if (!existsSync(dist)) {
  mkdirSync(dist);
}

// Select entryPoints and build

Global is not defined

​Your library might use some dependency that leads to a build error “Uncaught ReferenceError: global is not defined” when building ESM target. Root cause being the dependency expecting a global​ object (as in NodeJS) while you would need window​ for the browser.

To overcome the issue, esbuild has a define option that can be use to replace global identifiers with constant expression.

import esbuild from "esbuild";

esbuild
  .build({
    entryPoints,
    outdir: "dist/esm",
    bundle: true,
    sourcemap: true,
    minify: true,
    splitting: true,
    format: "esm",
    define: { global: "window" },
    target: ["esnext"],
  })
  .catch(() => process.exit(1));