haml-transpiler-server-loader

4.0.0 verified Fri May 01 auth: no javascript

Webpack loader that uses the Ruby-based haml-transpiler-server gem to transpile HAML files to HTML. Version 4.0.0 requires a separate Ruby server process (start via `hamlts`), communicating over TCP/IP. Unlike pure JavaScript HAML transpilers, this leverages the original Ruby implementation for correctness, at the cost of architectural complexity and an external dependency on Ruby and the gem. Configuration allows custom IP, port, and module export style. Suitable for projects already using Ruby HAML tooling.

Common errors

error Error: connect ECONNREFUSED 127.0.0.1:5487 ↓

cause haml-transpiler-server not running or on different port

fix

Run 'hamlts' in terminal before starting webpack, or configure loader with correct port

error Module build failed: Error: Could not find Ruby gem haml-transpiler-server ↓

cause Ruby gem not installed

fix

Run 'gem install haml-transpiler-server'

Warnings

breaking Requires external Ruby haml-transpiler-server gem and running server process ↓

fix Install Ruby, run 'gem install haml-transpiler-server', then start server with 'hamlts' before webpack

gotcha No built-in watching; file changes do not trigger re-transpilation unless webpack's watch mode is enabled ↓

fix Use webpack --watch or integrate with watchman for automatic rebuilds

gotcha Connection errors if hamlts server not running or wrong IP/port ↓

fix Ensure hamlts is running on default localhost:5487 or match custom configuration

Install

npm install haml-transpiler-server-loader

yarn add haml-transpiler-server-loader

pnpm add haml-transpiler-server-loader

Imports

loader

wrong

const loader = require('haml-transpiler-server-loader'); // Loader is not a programmatic export; use in webpack rules only

correct

import 'haml-transpiler-server-loader'; // or use in webpack config as a string

This package is a webpack loader, not a library. It is referenced by name in webpack config, not imported as a module in application code.

hamlTranspilerServerLoader config

wrong

// Setting options via query string may conflict with webpack v2+ rules; prefer config object.

correct

// In webpack config: module.exports = { //...  hamlTranspilerServerLoader: { ip: '127.0.0.1', port: 5487, moduleExport: true } }

Since v3, webpack recommends using the config object over query parameters.

HAML file import

wrong

require('./template.html.haml'); // CommonJS style works but not recommended for ESM projects

correct

import template from './template.html.haml'; // With file-loader and this loader chained

Loader chains with file-loader emit separate HTML files; imports return the file path or module content depending on moduleExport.

Quickstart

Webpack rule that chains file-loader and haml-transpiler-server-loader to transpile .html.haml files into standalone HTML files.

{
  test: /\.html\.haml$/,
  use: [
    {
      loader: 'file-loader',
      options: { name: '[path][name].html' }
    },
    'haml-transpiler-server-loader'
  ],
  exclude: [/node_modules/]
}