DOCSEARCHbyAlgolia
Submit Docs

esbuild-rails

repository·main·Indexed 41 days ago

https://github.com/excid3/esbuild-rails

An esbuild plugin for Rails applications, version 1.0.8, designed to simplify the import of Stimulus controllers, ActionCable channels, and other JavaScript assets using glob patterns. It is specifically built for use with jsbundling-rails and provides a railsPlugin function to resolve directories and convert filenames into Rails-style controller names.

Tokens
1.4K
Snippets
7
Records
8
Agent score
2%

What's inside esbuild-rails

  2. Setup jQuery with esbuild

    main

    Because Javascript import statements are hoisted (executed before other code), you should isolate the jQuery global assignment into its own file and import it at the top of your application entry point to ensure window.$ and window.jQuery are available to other modules.

    yarn add jquery
    // app/javascript/jquery.js
import jquery from 'jquery';
window.jQuery = jquery;
window.$ = jquery;
    // app/javascript/application.js
import "./jquery"

  3. Import Stimulus controllers from external folders (e.g., ViewComponents)

    main

    To import Stimulus controllers located in parent or external directories (like app/components), create an index.js file in that directory to handle the registration, then import that index.js file into your main Stimulus entry point.

    1. Create the index file in the target directory (e.g., 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)
})

    2. Import that index file in your main controller index (e.g., app/javascript/controllers/index.js):

    import { application } from "./application"

// Import the registration logic from the components directory
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)
})

  5. Configure the esbuild build script

    main

    To use esbuild-rails, you must copy examples/esbuild.config.mjs into your repository and set it as your build script in package.json.

    You can use npm to set this automatically (requires npm >= 7.1):

    npm pkg set scripts.build="node esbuild.config.mjs"

    Or add it manually to your package.json:

    "scripts": {
  "build": "node esbuild.config.mjs"
}

  6. Import Stimulus controllers using globs

    main

    You can use glob patterns to import multiple files at once. To register Stimulus controllers, import them using a glob and iterate over the resulting collection to register each one with your Stimulus application.

    import { Application } from "@hotwired/stimulus"
const application = Application.start()

// Import all controllers using a glob
import controllers from "./**/*_controller.js"

controllers.forEach((controller) => {
  application.register(controller.name, controller.module.default)
})

  8. Use railsPlugin to import directories via globs

    main

    The railsPlugin function is an esbuild plugin designed for Rails applications. It enables the use of glob patterns (e.g., ./**/*) in import statements to import an entire directory of files. This is particularly useful for bulk-importing Stimulus controllers or ActionCable channels.

    When a glob import is encountered, the plugin:

    1. Resolves all files in the directory matching a provided matcher regex.
    2. Converts filenames into Rails-style controller names (e.g., ./admin/hello_world_controller.js becomes admin--hello-world).
    3. Generates a virtual module that exports an array of objects. Each object contains the name (the converted controller name), the module (the imported content), and the filename.

    Configuration

    • options.matcher: A regular expression used to filter which files in the directory are included in the import. The default is /.+\..+/ (matches any file with an extension).
    const railsPlugin = require('esbuild-rails');

// Example esbuild configuration
require('esbuild').build({
  entryPoints: ['app/javascript/application.js'],
  bundle: true,
  plugins: [
    railsPlugin({ matcher: /_controller\.(j|t)s$/ }) // Only import Stimulus controllers
  ],
  outfile: 'app/assets/builds/application.js',
});