esbuild-rails

1.0.7 verified Mon Apr 27 auth: no javascript

Esbuild plugin for Rails applications that enables glob imports for Stimulus controllers, ActionCable channels, and other JavaScript files. Current stable version is 1.0.7, released with regular updates. It integrates with jsbundling-rails to replace Webpacker, providing a fast bundling experience for Rails asset pipelines. Differentiators include automatic glob resolution for importing multiple files, seamless integration with Hotwire/Stimulus, and support for jQuery via import hoisting. Requires esbuild as a peer dependency and offers both ESM and CJS configuration examples.

Common errors

error TypeError: rails is not a function ↓

cause Calling the plugin as a reference rather than invoking it: `plugins: [rails]` instead of `plugins: [rails()]`.

fix

Change to plugins: [rails()].

error Error: Could not resolve './src/**/*' ↓

cause Glob patterns require the esbuild-rails plugin to be active; missing plugin in esbuild config.

fix

Add plugins: [rails()] to your esbuild build options.

Warnings

gotcha The plugin function must be called: `rails()` not `rails`. Passing the function reference directly will cause a build error. ↓

fix Use `rails()` (call it) instead of just `rails` in the plugins array.

breaking ESM and CJS module systems are mixed in examples – using `import` statements in a CommonJS config file may cause syntax errors. ↓

fix Use `require` for CommonJS or ensure your config file has `.mjs` extension for ESM.

deprecated The `require('esbuild-rails')` pattern may be deprecated in future versions in favor of ESM imports. ↓

fix Switch to `import rails from 'esbuild-rails'` with an `.mjs` config file.

gotcha Importing jQuery via separate file relies on import hoisting; placing the import after other code may not work as expected. ↓

fix Create a separate file for jQuery setup and import it at the top of your entry point.

Install

npm install esbuild-rails

yarn add esbuild-rails

pnpm add esbuild-rails

Imports

default
wrong
```
const rails = require('esbuild-rails')
```
correct
```
import rails from 'esbuild-rails'
```
ESM syntax recommended; CJS via require also works but may be deprecated in future.
rails function
wrong
```
plugins: [rails]
```
correct
```
plugins: [rails()]
```
The plugin must be called as a function, not passed as a reference.

Path resolution

wrong

import path from 'path' in CJS context

correct

const path = require('path'); const rails = require('esbuild-rails')

Use CJS require for the example config file if not using ES modules.

Quickstart

Shows basic esbuild configuration with the rails plugin for bundling Rails JavaScript assets.

const path = require('path');
const rails = require('esbuild-rails');

require('esbuild').build({
  entryPoints: ['application.js'],
  bundle: true,
  outdir: path.join(process.cwd(), 'app/assets/builds'),
  absWorkingDir: path.join(process.cwd(), 'app/javascript'),
  plugins: [rails()],
}).catch(() => process.exit(1));