DEV Community

Marcin Wosinek
Marcin Wosinek

Posted on • Updated on

esbuild in a simple html+js use case

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" />
Enter fullscreen mode Exit fullscreen mode

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";
Enter fullscreen mode Exit fullscreen mode

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


Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

--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:

Top comments (1)

marcinwosinek profile image
Marcin Wosinek

If you read it so far, probably you can be interested in the esbuild course I'm building:

It's free at the moment, but when I'll reach 2h of video the platform requires making it paid. The best option is to sign up now, and wait for the course to grow:)