🛤 esbuild-rails
Esbuild Rails plugin for easy imports of Stimulus controllers, ActionCable channels, and other Javascript.
This package is designed to be used with jsbundling-rails.
⚙️ Installation
Install with npm or yarn
yarn add esbuild-rails
npm i esbuild-rails
Copy examples/esbuild.config.mjs
to your git repository or use the following example config:
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))
Use npm to add it as the build script (requires npm >= 7.1
)
npm pkg set scripts.build="node esbuild.config.js"
or add it manually in package.json
"scripts": {
"build": "node esbuild.config.mjs"
}
🧑💻 Usage
Import a folder using globs:
import "./src/**/*"
Import Stimulus controllers and register them:
import { Application } from "@hotwired/stimulus"
const application = Application.start()
import controllers from "./**/*_controller.js"
controllers.forEach((controller) => {
application.register(controller.name, controller.module.default)
})
Importing Stimulus controllers from parent folders (ViewComponents, etc)
To import Stimulus controllers from parents in other locations, create an index.js
in the folder that registers controllers and import the index.js
location.
For example, we can import Stimulus controller for ViewComponents by creating an app/components/index.js
file and importing that in your main Stimulus controllers index.
// app/javascript/controllers/index.js
import { application } from "./application"
// Import app/components/index.js
import "../../components"
// app/components/index.js
import { application } from "../javascript/controllers/application"
import controllers from "./**/*_controller.js"
controllers.forEach((controller) => {
application.register(controller.name, controller.module.default)
})
Import ActionCable channels:
import "./channels/**/*_channel.js"
jQuery with esbuild:
yarn add jquery
// app/javascript/jquery.js
import jquery from 'jquery';
window.jQuery = jquery;
window.$ = jquery;
//app/javascript/application.js
import "./jquery"
Why does this work? import
in Javascript is hoisted, meaning that import
is run before the other code regardless of where in the file they are. By splitting the jQuery setup into a separate import
, we can guarantee that code runs first. Read more here.
jQuery UI with esbuild:
Follow the jQuery steps above.
Download jQuery UI custom build and add it to app/javascript/jquery-ui.js
import "./jquery-ui"
$(function() {
$(document).tooltip()
$("#dialog").dialog()
})
A custom build is required because jQueryUI does not support ESM.
🙏 Contributing
If you have an issue you'd like to submit, please do so using the issue tracker in GitHub. In order for us to help you in the best way possible, please be as detailed as you can.
📝 License
The gem is available as open source under the terms of the MIT License.