plain.esbuild

Build and bundle JavaScript files using esbuild.

• Overview
• CLI commands
  • Build
  • Dev
• FAQs
• Installation

Overview

Plain esbuild provides a simple way to bundle JavaScript files using esbuild. Any asset file with .esbuild. in its name will be automatically bundled into a corresponding .esbuilt. file.

For example, if you have app/assets/js/app.esbuild.js, running the build command will create app/assets/js/app.esbuilt.js alongside it.

TypeScript and JSX entries work too — app.esbuild.ts, app.esbuild.tsx, and app.esbuild.jsx all compile to a .esbuilt.js output. JSX uses the automatic runtime, so you don't need to import React in every file.

// app/assets/js/app.esbuild.js
import { someFunction } from "./utils.js";

someFunction();

After building, you can reference the bundled file in your templates:

<script src="{{ asset('js/app.esbuilt.js') }}"></script>

The bundler automatically:

• Bundles all imports into a single file
• Generates source maps
• Minifies the output (in production builds)
• Targets the browser platform

CLI commands

Build

Build all .esbuild. files in your asset directories:

plain esbuild build

This command finds all files containing .esbuild. in your asset directories and bundles them using esbuild. The output files are minified by default.

Dev

Watch for changes and rebuild automatically:

plain esbuild dev

The dev command performs an initial build (without minification) and then watches for file changes. Each build records which files were bundled into each entry, so when a JS/TS source file changes, only the entries that actually import it are rebuilt — you can split your code into modules and they'll be picked up. If you delete an entry file, the corresponding .esbuilt. output file is also removed.

FAQs

What files should I gitignore?

Add this pattern to your .gitignore to exclude the generated bundle files:

**/assets/**/*.esbuilt.*

Do I need to install esbuild separately?

Yes, esbuild must be available via npx. Make sure you have a package.json in your project with esbuild as a dependency:

npm install --save-dev esbuild

How do I use this with plain assets compile?

The esbuild commands integrate with the asset compile pipeline through entrypoints. When you run plain assets compile, it will automatically run esbuild first if you have configured it in your build pipeline.

Can I customize esbuild options?

The esbuild function accepts a minify option. For more advanced customization, you can call the function directly in your own build scripts.

Installation

Install the plain.esbuild package from PyPI:

uv add plain.esbuild

Make sure you have esbuild available in your project:

npm install --save-dev esbuild

Create a JavaScript file with .esbuild. in the name:

// app/assets/js/app.esbuild.js
console.log("Hello from esbuild!");

Run the build command:

plain esbuild build

Add the generated files to your .gitignore:

**/assets/**/*.esbuilt.*