esbuild-rails

🛤 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 set-script 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.