esbuild in a simple html+js use case

Marcin Wosinek's photo
Marcin Wosinek
·Jun 2, 2021·

3 min read

In this series, I'll take a look on a simple usecase of js+html application, build with various js bundlers. After checking what's possible no bundler at all & in webpack, let's take a look on esbuild - interesting option among the js-bundlers.


Key selling point of esbuild is speed. According to their data, they are even more then 100 times faster then alternatives. As it's written in go, instead of javascript, on can hope for a significant speed increase. In a simplified demo as we have in this series, the speed difference will be unnoticeable. For production application, every second saved in build adds across whole development team & it helps developers keep rebuilding & rerunning tests as often as possible - a good habit to have on a project.

The focus on speed mean that in case of feature vs speed trade-of, the speed was a priority. So for example, for compiling ts you can only use limited part of official building options & you should limit yourself to use only the supported syntax.

The app

application screenshot

same as other articles of this series, simple app with 1 component with template & data in separate files.


The html part is simple:

<!-- index.html -->
    <meta http-equiv="content-type" content="text/html; charset=utf-8" />
    <title>Contact App</title>
    <link rel="shortcut icon" href="#" />

    <script type="module" src="./dist/index.js"></script>
    <link rel="stylesheet" href="style.css" />

contrary to for example parcel, esbuild output works just fine with <script type="module">.

The location of the output file, ./dist/index.js is set in the build script. esbuild, by default will just output the file into the standard output - ie, will drop it on the screen.

Main js file:

// src/index.js
import "./contact-list/contact-list";

note, that similar to other modern bundlers esbuild try out different extensions for use to find a file we try to load - even though it comes with performance cost.

The component

The component is broken down into 3 files. Same as in webpack, we are able to keep each type of content with a correct extension - data in json, template in html.

// src/contact-list/contact-list.js
import template from "./contact-list.html";
import contacts from "./data.json";

const contactList = document.createElement("div");

contactList.className = "contact-list";

contacts.forEach((entry) => {
  const element = document.createElement("div");
  element.className = "contact";

  element.innerHTML = template;

  element.querySelector(".name").innerHTML =;
  element.querySelector(".phone").innerHTML =;



JSON files are understood by esbuild by default, src/contact-list/data.json, the data file:

    "name": "Christopher L Sanders",
    "phone": "769-232-1807"
    "name": "Frances J Nolte",
    "phone": "901-287-0419"

HTML files, need txt loader specified for html files:

<!-- src/contact-list/contact-list.html -->
<h2 class="name">name</h2>

<p class="phone">phone</p>

in this way, we can use them in a similar way one can be used to from webpack's html-loader.

Build dependencies & configuration

For a successful build of the above code, we just need esbuild package. To install it, you can run:

$  npm install --save-dev esbuild

For easy access to build script, you can add following line to package.json:

  "scripts": {
    // other scripts
    "build": "esbuild src/index.js --bundle --outfile=dist/index.js --loader:.html=text"

--outfile tells esbuild where to put our final bundle --loaders:.html=test makes each *.html imported as string

Note - for complex configuration, esbuild provides node API instead of configuration file - contrary to webpack and many other bundles.

Complete code & application example

If you want to see the application in action in the browser you can see it here:

and for the working code example you can go here:

You can check out my video course about esbuild.

Share this