rails-erb-loader

5.5.2 verified Sat Apr 25 auth: no javascript

Webpack loader that compiles Embedded Ruby (.erb) template files in Ruby/Rails projects by running them through the Erbubis, Erubi, or ERB gem via a Ruby runner (default: bin/rails runner). Version 5.5.2 supports webpack 2–3 via peer dependency and requires Node >= 0.10.0. Configuration options include dependenciesRoot, engine selection, timeout, and environment variables. Dependencies can be declared via magic comments to enable webpack's watch mode. Suitable for mixed JS/Ruby asset pipelines, notably in Rails apps using Webpacker.

Common errors

error ERROR in ./app/assets/javascripts/application.js.erb Module build failed: Error: Cannot find module 'rails-erb-loader' ↓

cause Loader not installed as a devDependency.

fix

Run: npm install rails-erb-loader --save-dev

error ERROR in ./app/assets/javascripts/application.js.erb Module build failed: Error: Command failed: ./bin/rails runner ... /bin/sh: ./bin/rails: No such file or directory ↓

cause Runner path incorrect or missing binstub.

fix

Set runner option to correct path relative to webpack's working directory, or generate binstubs: bundle exec rails app:update:bin

error Child compilation failed: Module parse failed: ... Unexpected token (1:0) You may need an appropriate loader to handle this file type. ↓

cause Loader is not applied because test regex doesn't match, or enforce: 'pre' is missing.

fix

Ensure rule has test: /\.erb$/ and enforce: 'pre' in webpack config.

Warnings

breaking webpack 4+ not supported; requires webpack 2 or 3. This loader may not work with modern webpack versions. ↓

fix Use an alternative loader (e.g., erb-loader) or stick to webpack 2/3.

deprecated The 'dependenciesRoot' option defaults to 'app' which assumes Rails conventions; may not work in non-standard layouts. ↓

fix Explicitly set dependenciesRoot to the correct path relative to webpack's working directory.

gotcha Ruby runner must be installed and configured; default './bin/rails runner' requires a Rails app. Without Rails, set runner to 'ruby'. ↓

fix For non-Rails projects, set 'runner' option to 'ruby' and 'engine' to 'erb' in loader options.

gotcha Timeout of 0 (default) means no timeout; a hanging Ruby process can block build indefinitely. ↓

fix Set 'timeoutMs' to a reasonable value (e.g., 10000) to prevent hanging builds.

gotcha Dependency comments must start with 'rails-erb-loader-dependencies' or 'rails-erb-loader-dependency' exactly; misspelling will not work. ↓

fix Use correct comment format: /* rails-erb-loader-dependencies path/to/file */

Install

npm install rails-erb-loader

yarn add rails-erb-loader

pnpm add rails-erb-loader

Imports

default (loader)

wrong

import railsErbLoader from 'rails-erb-loader'

correct

module.exports = { module: { rules: [ { test: /\.erb$/, enforce: 'pre', loader: 'rails-erb-loader' } ] } }

Loader is used in webpack config, not imported as a JavaScript module. It is a CommonJS loader package.

rails-erb-loader (as string)
wrong
```
loader: require.resolve('rails-erb-loader')
```
correct
```
loader: 'rails-erb-loader'
```
Webpack resolves loaders from node_modules automatically. Use string, not require.resolve.

options

wrong

options: {erubis: true}

correct

const erbLoaderOptions = { runner: './bin/rails runner', dependenciesRoot: 'app', engine: 'erb' }

Options are plain object on the rule's use entry, not imported. Engine option string, not boolean.

Quickstart

Configure webpack to preprocess .erb files using rails-erb-loader with custom runner and engine options.

// webpack.config.js
const path = require('path');
module.exports = {
  entry: './src/index.js',
  output: { path: path.resolve(__dirname, 'dist'), filename: 'bundle.js' },
  module: {
    rules: [{
      test: /\.erb$/,
      enforce: 'pre',
      loader: 'rails-erb-loader',
      options: {
        runner: './bin/rails runner',
        dependenciesRoot: 'app',
        engine: 'erb'
      }
    }]
  }
};