Build a library with esbuild (vol. 2)

A few new tips and tricks to build a library with esbuild

Jul 5, 2022

#javascript #programming #webdev #showdev

Wake Skate

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

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", }


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


esbuild is still slick!

To infinity and beyond