Build a library with esbuild (vol. 2)

Wake Skate

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));

Both esm and cjs

To ship a library that supports both CommonJS (cjs) and ECMAScript module (esm), I output the bundles in two sub-folders of the distribution directory - e.g. dist/cjs and dist/esm. With esbuild, this can be achieved by specifying the options outdir or outfile to these relative paths.

import esbuild from "esbuild";
import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from "fs";
import { join } from "path";

const dist = join(process.cwd(), "dist");

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

const entryPoints = readdirSync(join(process.cwd(), "src"))
    .filter((file) => !file.endsWith(".ts") && statSync(join(process.cwd(), "src", file)).isFile())
    .map((file) => `src/${file}`);

// esm output bundles with code splitting
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));

// cjs output bundle
esbuild
    .build({
        entryPoints: ["src/index.ts"],
        outfile: "dist/cjs/index.cjs.js",
        bundle: true,
        sourcemap: true,
        minify: true,
        platform: "node",
        target: ["node16"]
    })
    .catch(() => process.exit(1));

// an entry file for cjs at the root of the bundle
writeFileSync(join(dist, "index.js"), "export * from './esm/index.js';");

// an entry file for esm at the root of the bundle
writeFileSync(join(dist, "index.cjs.js"), "module.exports = require('./cjs/index.cjs.js');");

As distributing two distinct folders leads to having no more entry files in the dist path of the library, I also like to add two files that re-export the code. It can be useful when importing the library in a project.

In addition, the package.json entries should be updated accordingly as well.

{
    "name": "mylibary",
    "version": "0.0.1",
    "main": "dist/cjs/index.cjs.js",
    "module": "dist/esm/index.js",
    "types": "dist/types/index.d.ts"
}

CSS and SASS

Did you know that esbuild can bundle CSS files too? There is even a SASS plugin that makes it easy to build .scss files 😃.

npm i -D esbuild-sass-plugin postcss autoprefixer postcss-preset-env

In following example, I bundle two different SASS files - src/index.scss and src/doc/index.scss. I use the plugin to transform the code - i.e. to prefix the CSS - and I also use the option metafile which tells esbuild to produce some metadata about the build in JSON format.

Using it, I can retrieve the paths and names of the generated CSS files to e.g. include these in my HTML files later on.

import esbuild from "esbuild";

import { sassPlugin } from "esbuild-sass-plugin";
import postcss from "postcss";
import autoprefixer from "autoprefixer";
import postcssPresetEnv from "postcss-preset-env";

const buildCSS = async () => {
    const { metafile } = await esbuild.build({
        entryPoints: ["src/index.scss", "src/doc/index.scss"],
        bundle: true,
        minify: true,
        format: "esm",
        target: ["esnext"],
        outdir: "dist/build",
        metafile: true,
        plugins: [
            sassPlugin({
                async transform(source, resolveDir) {
                    const { css } = await postcss([autoprefixer, postcssPresetEnv()]).process(source, {
                        from: undefined
                    });
                    return css;
                }
            })
        ]
    });

    const { outputs } = metafile;
    return Object.keys(outputs);
};

Conclusion

esbuild is still slick!

To infinity and beyond
David