{"id":11451,"library":"node-sass-middleware","title":"Node Sass Middleware for Connect/Express","description":"node-sass-middleware is a Connect/Express middleware designed to automatically recompile `.scss` or `.sass` files on demand for web servers. It leverages the `node-sass` library (which in turn uses LibSass) to provide on-the-fly compilation, caching, and debugging capabilities directly within a Node.js web application stack. The package's current stable version is 1.1.0, with its latest patch release (v1.1.0) occurring in 2024. While the package itself sees intermittent updates, its core dependency, `node-sass`, is officially deprecated and no longer actively maintained. This means `node-sass-middleware` is primarily suited for maintaining existing projects rather than new development, where modern Dart Sass solutions are generally preferred. It integrates seamlessly into existing Connect or Express applications, offering a convenient bridge between Sass source files and served CSS.","status":"maintenance","version":"1.1.0","language":"javascript","source_language":"en","source_url":"git://github.com/sass/node-sass-middleware","tags":["javascript","sass","css","libsass"],"install":[{"cmd":"npm install node-sass-middleware","lang":"bash","label":"npm"},{"cmd":"yarn add node-sass-middleware","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-sass-middleware","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for Sass compilation. This library is deprecated and may have compatibility issues with newer Node.js versions.","package":"node-sass","optional":false},{"reason":"Optional peer dependency for integration with the Connect framework.","package":"connect","optional":true},{"reason":"Optional peer dependency for integration with the Express framework.","package":"express","optional":true}],"imports":[{"note":"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.","wrong":"import sassMiddleware from 'node-sass-middleware';","symbol":"sassMiddleware","correct":"const sassMiddleware = require('node-sass-middleware');"}],"quickstart":{"code":"const express = require('express');\nconst sassMiddleware = require('node-sass-middleware');\nconst path = require('path');\nconst app = express();\n\n// IMPORTANT: Place sassMiddleware *before* express.static\napp.use(sassMiddleware({\n src: path.join(__dirname, 'sass'), // Source directory for .scss/.sass files\n dest: path.join(__dirname, 'public'), // Destination directory for .css files\n debug: true, // Output debugging info to console\n outputStyle: 'compressed', // Minify CSS output\n prefix: '/styles' // CSS will be served from /styles/your_file.css\n}));\n\n// Serve static files from the 'public' directory, including compiled CSS\napp.use('/styles', express.static(path.join(__dirname, 'public')));\n\n// Example route for demonstration\napp.get('/', (req, res) => {\n res.send('
Hello from node-sass-middleware!
');\n});\n\nconst PORT = process.env.PORT || 3000;\napp.listen(PORT, () => {\n console.log(`Server listening on port ${PORT}`);\n console.log(`Open http://localhost:${PORT} in your browser.`);\n console.log(`Ensure you have a 'sass' directory with 'sass/main.scss' (e.g., body { h1 { color: darkblue; } }) and an empty 'public' directory.`);\n});","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Always ensure your `app.use(sassMiddleware(...))` call comes *before* `app.use(express.static(...))` in your Express or Connect application setup.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"<0.9.7"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Move `app.use(sassMiddleware(...))` to occur *before* `app.use(express.static(...))` in your application's middleware chain.","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.","error":"Cannot GET /styles/main.css (or similar 404 for CSS files)"},{"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.","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.","error":"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."}],"ecosystem":"npm"}