How to start building a project with esbuild
Tags: javascript, bundling
Published: 2021-08-09 06:32:10

This article will show how to start a project with [esbuild](https://esbuild.github.io/) as a bundler. I assume you have:
* npm & node installed - https://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:
```sh
$ 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 `-y`attribute 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
<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`:
```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:
```sh
$ 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:
```sh
$ ./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`:
```JSON
{
  ...
  "scripts": {
    ...
    "build": "esbuild --bundle src/index.js --outfile=www/main.js"
  },
  ...
}
```

With this in place, we can run the build with:
```sh
$ 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](https://github.com/marcin-wosinek/esbuild-tutorial/tree/step-1) of the example [repository](https://github.com/marcin-wosinek/esbuild-tutorial).

You can check out my [video course about esbuild](https://bit.ly/esbuild-course).

# Summary
We have seen how to start a simple, hello-world example with esbuild. Stay tuned for the following parts - [here you can sign up for updates](https://landing.mailerlite.com/webforms/landing/b8k4x6).