plain.esbuild
Build and bundle JavaScript files using esbuild.
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.
// 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. When you modify a .esbuild. file, it will automatically rebuild. If you delete a source 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 build?
The esbuild commands integrate with the Plain build system through entrypoints. When you run plain build, 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.*