Heads up! This project (inculding this documentation) is a work in progress! It is functional and the api probably won't change too much, but the overall "hygiene" leaves a lot to be desired -- there will be improvements to documentation, code comments, tests, and overall file structure... at some point.

esb4esm

A VERY opinionated layer on top of esbuild to build source code du jour in to ES Modules

Goal

The goal is to enable developers to author code using the tools of their choosing, but without needing to maintain a build script or be locked in to a particular platform or framework.

Specifically, esb4esm exists so that developers can write native es modules and import external packages without having to worry about bundling, static asset serving, or other build script concerns -- just author code for the web and run it on the web.

Install

> npm install -g esb4esm

Overview

At a high-level, this package takes a glob of web* source files (html, css, js), "compiles**" them and their dependencies, and then, primarily, outputs them in a root directory and ensures their import paths have been updated to be relative to the root directory.

Once these files have been "compiled" and written to the root directory, any one of them can be loaded using native browser loading mechanisms: <script> tag, dynamic import(), <link>, etc.

The esb4esm binary also includes watch and serve functionallity to support additional workflows that are common with this setup. Run esb4esm --help to see options.

* web source files are native HTML, CSS, JavaScript files that have been authored against the latest (or emerging) standards; however, they may need a "compile" step to make sure they're runnable for all browsers and users. Additionally, it's possible to use non-web source files like TypeScript, JSX, SCSS, etc through plugins.

** the compilation step is performed by esbuild and handles standard build/compilation features like minification, DEC/tree shaking, polyfilling, etc; however, because of the nature of this package, it does not handle bundling.

Why ES Modules?

ES Modules is a well-supported standard for importing and exporting dependencies natively within the browser.

Utilizing this functionality is a huge step forward for a build-free web while still allowing for builds steps where they make sense.

A build-free web first and foremost, lowers the barrier to entry for developing on and for the web by inverting today's standard practice of first learning some arcane DSL or framework rote with propriety syntax and conventions. Instead, it allows one to focus on the core tenets of the web (like html, css, javascript) while still taking advantage of some a few standard practices (e.g., small, focused files, etc)

And, practically, a build-free web will also minimize maintenance costs and increase focus on what you're actually building/creating!

Why esbuild?

tl;dr it's very fast and its opinions pretty much align with this packages opinions.

Why not x?

// TODO: add other projects and approaches

Examples

Run esb4esm --help to see cli args.

esb4esm should be able to work with most existing setups; however, feel free to take a look at the layout of the fixtures for the tests.

// TODO: add more inline examples...

Example command:

esb4esm --watch --sources 'tests/fixtures/external-deps/src/**/*.{html,css,js}' --outdir tests/build/EXTERNAL_DEPS/