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

npm & node installed - nodejs.org
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.

Code

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

HTML

www/index.html:

<html>
  <head>
    <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>
  </head>
  <body></body>
</html>

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

JS

src/index.js:

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.

Dependencies

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

Build

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

Links

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

You can check out my video course about esbuild.

Summary

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

How to start building a project with esbuild