LESS.js Middleware for Connect/Express

Common errors

• Error: .less file could not be found or processed.

  cause The middleware could not locate the specified .less source file or an imported .less file.
  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.

• TypeError: app.use is not a function

  cause This error indicates that `app` is not an Express/Connect application instance, or `app.use` is being called before `app` is properly initialized.
  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(...));`.

• Error: 'less' not found. Is it installed?

  cause The `less` package, which is a peer/runtime dependency, is not installed in your project.
  fix Install the `less` package: `npm install less --save`. Ensure its version is compatible with your `less-middleware` version.

Warnings

• breaking 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.
  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.
• breaking 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`.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install less-middleware npm
• yarn add less-middleware yarn
• pnpm add less-middleware pnpm

Imports

• lessMiddleware
  wrong:

  import { lessMiddleware } from 'less-middleware';

  correct:

  import lessMiddleware from 'less-middleware'; // For ESM-compatible setups

  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');`.
• lessMiddleware

  const lessMiddleware = require('less-middleware');

  This is the classic CommonJS import pattern shown in the official documentation and suitable for most Node.js applications that are not pure ESM.

Quickstart

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.

import express from 'express';
import lessMiddleware from 'less-middleware';
import { fileURLToPath } from 'url';
import { dirname, join } from 'path';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

const app = express();
const publicPath = join(__dirname, 'public');

// Imagine a 'public' directory containing 'styles.less'
// app.use(lessMiddleware('/less', { source: join(publicPath, 'less'), dest: join(publicPath, 'css') }));

// Basic usage: LESS files in /public will be compiled to /public
app.use(lessMiddleware(publicPath, {
  debug: process.env.NODE_ENV !== 'production',
  force: process.env.NODE_ENV !== 'production', // Recompile on each request in dev
  once: process.env.NODE_ENV === 'production', // Recompile once per server restart in prod
  render: {
    compress: process.env.NODE_ENV === 'production'
  }
}));
app.use(express.static(publicPath));

const port = process.env.PORT || 3000;
app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
  console.log(`LESS files in ${publicPath} will be compiled and served.`);
  console.log(`Try creating a 'styles.less' in ${publicPath} and access '/styles.css'`);
});