How to start building a project with esbuild

This article will show how to start a project with esbuild as a bundler. I assume you have:

  • npm & node installed -
  • the folder you are working in is exposed with some HTTP server - Apache, Nginx, etc.

Package init

In an empty folder named esbuild-tutorial, I run:

$ npm init -y
Wrote to /home/marcin/workspace/github/esbuild-tutorial/package.json:

  "name": "esbuild-tutorial",
  "version": "1.0.0",

This creates package.json for our project, and the -yattribute makes it use default values instead of asking questions interactively. Each value can be changed later on, directly in the package file.


For now, there will be 2 files in our project.



    <title>esbuild tutorial</title>

    <meta http-equiv="content-type" content="text/html; charset=utf-8" />
    <link rel="shortcut icon" href="#" />

    <script type="module" src="./main.js"></script>

The code meaning is as follow:

  • <title>... - sets what appears in the browser tab, or title bar
  • <meta>... - we set the encoding instead of forcing the browser to use default & complain in the console log.
  • <link rel="shortcut icon" href="#" /> - stop the browser from loading default icon form /favicon.ico, which doesn't exist
  • <script type="module" src="./main.js"></script> - loads js we will create in the next step



console.log("Lorem ipsum");

A simple code that will allow us to see in the browser console if the code is built and included as expected.


Before we can build, we have to install esbuild:

$ npm install esbuild --save-dev 

> esbuild@0.12.19 postinstall /home/marcin/workspace/github/esbuild-tutorial/node_modules/esbuild
> node install.js

npm notice created a lockfile as package-lock.json. You should commit this file.
+ esbuild@0.12.19
added 1 package and audited 1 package in 0.586s
found 0 vulnerabilities

By adding --save-dev, npm adds the package as a dev dependency. It means it will be installed automatically when we run npm install on the project in a new location.

If you use git, it's a good idea to add node_modules to .gitignore. It will stop git from including external packages in the repository - we have npm that takes care of it. You can do it quickly with:

$ echo node_modules >> .gitignore


You can already build the application by running:

$ ./node_modules/.bin/esbuild --bundle src/index.js --outfile=www/main.js

  www/main.js  63b 

⚡ Done in 8ms

As it's not handy to type such a long command, we can add a script command to package.json:

  "scripts": {
    "build": "esbuild --bundle src/index.js --outfile=www/main.js"

With this in place, we can run the build with:

$ npm run build

> esbuild-tutorial@1.0.0 build /home/marcin/workspace/github/esbuild-tutorial
> esbuild --bundle src/index.js --outfile=www/main.js

  www/main.js  63b 

⚡ Done in 1ms


You can find the code in the step-1 branch of the example repository.

You can check out my video course about esbuild.


We have seen how to start a simple, hello-world example with esbuild. Stay tuned for the following parts.