Node Sass Middleware for Connect/Express

Common errors

• Cannot GET /styles/main.css (or similar 404 for CSS files)

  cause The `node-sass-middleware` is placed after `express.static` (or `connect.static`). The static middleware intercepts the request for the CSS file before `node-sass-middleware` can compile and serve it, leading to a 404.
  fix Move `app.use(sassMiddleware(...))` to occur *before* `app.use(express.static(...))` in your application's middleware chain.

• Node Sass does not yet support your current environment: OS X 64-bit with Node.js X. Run `npm rebuild node-sass` to try to fix this.

  cause The native bindings for `node-sass` are not compatible with your current Node.js version or operating system architecture. This is a common issue with `node-sass` due to its reliance on platform-specific compiled binaries.
  fix First, try running `npm rebuild node-sass`. If that doesn't work, ensure your Node.js version falls within the range explicitly supported by the `node-sass` version `node-sass-middleware` depends on. As a long-term solution, consider migrating to `sass` (Dart Sass) which does not have native binding dependencies.

Warnings

• breaking The underlying `node-sass` library, which `node-sass-middleware` critically depends on, is officially deprecated. `node-sass` has known issues with newer Node.js versions and platform-specific native bindings, and it is no longer actively developed. For new projects, it is strongly recommended to use `sass` (Dart Sass) with a build tool or a different middleware solution.
  Fix: For new projects, avoid `node-sass-middleware`. For existing projects, be prepared for potential installation and compatibility issues with newer Node.js versions. Consider migrating to `sass` (Dart Sass) and integrating it via a build process or a custom compilation step for long-term stability.
• gotcha Incorrect middleware order: `node-sass-middleware` *must* be placed before any static file serving middleware (like `express.static`). If `express.static` runs first, it will attempt to serve a non-existent CSS file directly, resulting in 404 errors and preventing `node-sass-middleware` from compiling and serving the SASS source.
  Fix: Always ensure your `app.use(sassMiddleware(...))` call comes *before* `app.use(express.static(...))` in your Express or Connect application setup.
• gotcha Potential race conditions or unexpected compilation issues might occur for users on older versions (pre-v0.9.7). A critical bugfix addressing a race condition issue was implemented in `v0.9.7`.
  Fix: Upgrade `node-sass-middleware` to `v0.9.7` or later to benefit from the race condition fix and other improvements for more reliable compilation.
• gotcha Binding compatibility issues for `node-sass`: Historically, `node-sass` has faced challenges with specific Node.js versions or operating systems regarding its native bindings. While `node-sass-middleware` updates its `node-sass` dependency, users might still encounter these issues, leading to compilation failures.
  Fix: Ensure your Node.js version is compatible with the `node-sass` version used by `node-sass-middleware`. Try running `npm rebuild node-sass` if compilation errors occur. If problems persist, consider containerized environments or migrating to Dart Sass for a more robust solution.

Install

• npm install node-sass-middleware npm
• yarn add node-sass-middleware yarn
• pnpm add node-sass-middleware pnpm

Imports

• sassMiddleware
  wrong:

  import sassMiddleware from 'node-sass-middleware';

  correct:

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

  This package is primarily designed for CommonJS (`require`). While Node.js supports ESM, the package's primary usage examples and likely internal structure point to CJS. Direct ESM `import` may not work without a transpiler or specific Node.js configuration.

Quickstart

Demonstrates setting up `node-sass-middleware` with an Express application to compile SASS files on the fly and serve them as static CSS, highlighting the correct middleware order. To run, create a 'sass' directory with a 'main.scss' file (e.g., `body { background-color: lightblue; h1 { color: darkblue; } }`) and an empty 'public' directory in the same location as your script.

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

// IMPORTANT: Place sassMiddleware *before* express.static
app.use(sassMiddleware({
    src: path.join(__dirname, 'sass'), // Source directory for .scss/.sass files
    dest: path.join(__dirname, 'public'), // Destination directory for .css files
    debug: true, // Output debugging info to console
    outputStyle: 'compressed', // Minify CSS output
    prefix: '/styles' // CSS will be served from /styles/your_file.css
}));

// Serve static files from the 'public' directory, including compiled CSS
app.use('/styles', express.static(path.join(__dirname, 'public')));

// Example route for demonstration
app.get('/', (req, res) => {
  res.send('<!DOCTYPE html><html><head><link rel="stylesheet" href="/styles/main.css"></head><body><h1>Hello from node-sass-middleware!</h1></body></html>');
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
    console.log(`Server listening on port ${PORT}`);
    console.log(`Open http://localhost:${PORT} in your browser.`);
    console.log(`Ensure you have a 'sass' directory with 'sass/main.scss' (e.g., body { h1 { color: darkblue; } }) and an empty 'public' directory.`);
});