{"id":17451,"library":"less-middleware","title":"LESS.js Middleware for Connect/Express","description":"less-middleware is an HTTP middleware specifically designed to process LESS CSS files for web servers built with Connect.js or Express.js. It compiles .less files into .css on-the-fly when requested, or upon server restart with caching, and serves the resulting CSS. The current stable version, 3.1.0, is compatible with Less.js 3.9. While not on a strict schedule, releases typically follow major Less.js updates to maintain compatibility and leverage new features. Its key differentiators include robust caching mechanisms (including `cacheFile` for cross-restart caching), extensive preprocessing and postprocessing hooks (`preprocess.less`, `postprocess.css`), and fine-grained control over rendering options, making it suitable for both development and production environments by reducing disk I/O.","status":"maintenance","version":"3.1.0","language":"javascript","source_language":"en","source_url":"git://github.com/emberfeather/less.js-middleware","tags":["javascript"],"install":[{"cmd":"npm install less-middleware","lang":"bash","label":"npm"},{"cmd":"yarn add less-middleware","lang":"bash","label":"yarn"},{"cmd":"pnpm add less-middleware","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for LESS compilation. Middleware versions track Less.js major versions.","package":"less","optional":false}],"imports":[{"note":"While CommonJS `require` is shown in the README, modern Node.js projects often use ESM. The package itself likely provides a default export, so `import lessMiddleware from 'less-middleware';` is the correct ESM approach. For Node.js < 12 or CommonJS modules, use `const lessMiddleware = require('less-middleware');`.","wrong":"import { lessMiddleware } from 'less-middleware';","symbol":"lessMiddleware","correct":"import lessMiddleware from 'less-middleware'; // For ESM-compatible setups"},{"note":"This is the classic CommonJS import pattern shown in the official documentation and suitable for most Node.js applications that are not pure ESM.","symbol":"lessMiddleware","correct":"const lessMiddleware = require('less-middleware');"}],"quickstart":{"code":"import express from 'express';\nimport lessMiddleware from 'less-middleware';\nimport { fileURLToPath } from 'url';\nimport { dirname, join } from 'path';\n\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = dirname(__filename);\n\nconst app = express();\nconst publicPath = join(__dirname, 'public');\n\n// Imagine a 'public' directory containing 'styles.less'\n// app.use(lessMiddleware('/less', { source: join(publicPath, 'less'), dest: join(publicPath, 'css') }));\n\n// Basic usage: LESS files in /public will be compiled to /public\napp.use(lessMiddleware(publicPath, {\n  debug: process.env.NODE_ENV !== 'production',\n  force: process.env.NODE_ENV !== 'production', // Recompile on each request in dev\n  once: process.env.NODE_ENV === 'production', // Recompile once per server restart in prod\n  render: {\n    compress: process.env.NODE_ENV === 'production'\n  }\n}));\napp.use(express.static(publicPath));\n\nconst port = process.env.PORT || 3000;\napp.listen(port, () => {\n  console.log(`Server running at http://localhost:${port}`);\n  console.log(`LESS files in ${publicPath} will be compiled and served.`);\n  console.log(`Try creating a 'styles.less' in ${publicPath} and access '/styles.css'`);\n});\n","lang":"typescript","description":"This Express.js quickstart demonstrates how to integrate `less-middleware` to compile LESS files on the fly. It sets up the middleware to serve static files, enabling LESS compilation in a 'public' directory with different caching strategies for development and production environments, and basic Less rendering options like compression."},"warnings":[{"fix":"Review the Less.js 3.x changelog for any changes that might affect your .less files. Ensure your Less syntax is compatible with Less 3.","message":"Version 3.0.0 upgraded Less to version 3.x. This introduced potential breaking changes due to Less.js's own major version update, especially regarding syntax and features removed or altered in Less 3.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Replace any usage of `options.parser` with `options.render` for passing rendering-specific options. Consult the less-middleware 2.x README for the new options structure.","message":"Version 2.0.0 introduced significant breaking changes due to an update to Less 2.4. The `options.parser` property was removed, and rendering options are now passed directly via `options.render`.","severity":"breaking","affected_versions":">=2.0.0 <3.0.0"},{"fix":"Always explicitly define `dest` to a desired output directory, especially if source LESS files are not in the same directory where compiled CSS should reside. Ensure `pathRoot` is correctly set if your source and destination directories share a common, non-root parent.","message":"Incorrect configuration of `dest` or `pathRoot` can lead to compiled CSS files not being found or written to unexpected locations. If `dest` is not specified, it defaults to the `source` directory, which may not be desirable in production for separation of concerns.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For development, set `force: true` and `debug: true`. For production, set `once: true` and consider using `cacheFile` to persist import dependency information across server restarts. Ensure `process.env.NODE_ENV` is correctly set for conditional logic.","message":"Caching behavior (`force`, `once`, `cacheFile`) requires careful consideration for both development and production. In development, `force: true` is often desired for immediate feedback on style changes, but in production, `once: true` or `cacheFile` for faster startup is critical. Misconfiguration can lead to slow rebuilds or outdated CSS being served.","severity":"gotcha","affected_versions":">=1.0.4"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Verify the `source` option points to the correct directory containing your .less files. Check file paths, capitalization, and ensure read permissions. Use `debug: true` in options for more verbose logging about file resolution.","cause":"The middleware could not locate the specified .less source file or an imported .less file.","error":"Error: .less file could not be found or processed."},{"fix":"Ensure you have correctly initialized your Express or Connect application, e.g., `const express = require('express'); const app = express();` before calling `app.use(lessMiddleware(...));`.","cause":"This error indicates that `app` is not an Express/Connect application instance, or `app.use` is being called before `app` is properly initialized.","error":"TypeError: app.use is not a function"},{"fix":"Install the `less` package: `npm install less --save`. Ensure its version is compatible with your `less-middleware` version.","cause":"The `less` package, which is a peer/runtime dependency, is not installed in your project.","error":"Error: 'less' not found. Is it installed?"}],"ecosystem":"npm","meta_description":null}