SASS (Ruby Gem) Connect/Express Middleware

0.0.3 verified Thu Apr 23 auth: no javascript abandoned

This package provides Connect/Express middleware for compiling SASS files on the fly. It is an extremely old package, with its last known release being version 0.0.3, published over a decade ago. Crucially, it relies on the `sass` Ruby gem for compilation, which is now considered deprecated and superseded by Dart Sass (the official `sass` npm package). Due to its age and dependency on an outdated, external compiler (Ruby Sass), `sass-middleware` is abandoned and incompatible with modern Node.js environments and contemporary Express/Connect applications. Developers should instead integrate modern build tools (e.g., Webpack, Vite, Gulp) with Dart Sass for static compilation, or explore direct usage of the `sass` npm package API for programmatic compilation within a build process. The `node-sass-middleware` package, while also deprecated due to its reliance on `node-sass` (LibSass), is a more recent alternative that still faced similar end-of-life issues. This package offers no current release cadence and no active development, making it unsuitable for any new or existing projects.

Common errors

error Error: `sass` executable not found. ↓

cause The middleware could not locate the `sass` command-line executable provided by the Ruby Sass gem in the system's PATH. This is a common issue because the package relies on an external, non-npm dependency.

fix

Ensure the Ruby sass gem is installed by running gem install sass and that your system's PATH variable includes the directory where RubyGems installs executables.

error TypeError: app.use() requires a middleware function but got a Object ↓

cause This error can occur if `require('sass-middleware')` is called without the `(options)` argument, as the module exports a function that expects to be invoked with options to return the actual middleware.

fix

Invoke the sass-middleware module with an options object, even if it's empty: app.use(require('sass-middleware')({}));

Warnings

breaking This package (`sass-middleware` version 0.0.3) is definitively abandoned and unmaintained. It relies on the Ruby Sass compiler, which is deprecated and has reached end-of-life. It is highly unlikely to function correctly with modern Node.js or Express/Connect versions and should not be used in production. ↓

fix Migrate to a modern SASS compilation workflow using Dart Sass (the `sass` npm package) as part of a build step (e.g., Webpack, Vite, Gulp) rather than on-the-fly middleware. Consider `node-sass-middleware` as a legacy alternative if `node-sass` is unavoidable, though `node-sass` itself is also deprecated.

gotcha The middleware explicitly requires the `sass` Ruby gem to be installed globally on the system. This introduces a non-JavaScript dependency managed by RubyGems, not npm, which can lead to complex setup and compatibility issues across different development environments. ↓

fix Verify `gem install sass` has been successfully executed and the `sass` executable is in your system's PATH. However, the recommended fix is to avoid this package entirely due to its abandoned status.

gotcha There is a separate, similarly named package `node-sass-middleware` (version 1.1.0) which relies on `node-sass` (LibSass). While newer, `node-sass` is also deprecated, and `node-sass-middleware` is also archived and unmaintained. Ensure you are not confusing the two, but neither is recommended for new development. ↓

fix Always check the package name and its dependencies carefully. For modern SASS compilation, use the official `sass` npm package (Dart Sass) directly in your build process.

Install

npm install sass-middleware

yarn add sass-middleware

pnpm add sass-middleware

Imports

middleware

wrong

import sassMiddleware from 'sass-middleware';

correct

const sassMiddleware = require('sass-middleware');

This package is CommonJS-only and does not support ES Modules due to its age.

options

wrong

app.use(sassMiddleware.default(...));

correct

app.use(require('sass-middleware')({
  src: path.join(__dirname, 'public'),
  dest: path.join(__dirname, 'public'),
  debug: true
}));

The module exports a function directly, not an object with a default property.

Quickstart

This quickstart demonstrates how to integrate `sass-middleware` into an Express application for on-the-fly SASS compilation, requiring the deprecated Ruby Sass gem.

const express = require('express');
const path = require('path');
const sassMiddleware = require('sass-middleware');
const app = express();

// Ensure `sass` Ruby gem is installed: `gem install sass`

app.use(sassMiddleware({
  src: path.join(__dirname, 'public'),
  dest: path.join(__dirname, 'public'),
  debug: true, // Output compilation errors to console
  outputStyle: 'expanded', // 'compressed', 'nested', 'compact', 'expanded'
  prefix: '/stylesheets' // Where .scss files are served from, e.g., /stylesheets/style.css
}));

app.use(express.static(path.join(__dirname, 'public')));

app.get('/', (req, res) => {
  res.send('<h1>Sass Middleware Example</h1><link rel="stylesheet" href="/stylesheets/style.css">');
});

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
  console.log('Ensure you have `gem install sass` run in your environment.');
  console.log('Create public/stylesheets/style.scss and refresh your browser.');
});

// Example public/stylesheets/style.scss content:
// $font-stack: Helvetica, sans-serif;
// $primary-color: #333;
//
// body {
//   font: 100% $font-stack;
//   color: $primary-color;
// }