Less Bundle Promise

Common errors

• ReferenceError: require is not defined

  cause Attempting to `import lessBundle from 'less-bundle-promise'` in a modern Node.js environment configured for ES Modules. This package is CommonJS-only.
  fix Change your import statement to `const lessBundle = require('less-bundle-promise');` to use its CommonJS interface. If your project is strictly ESM, you might need to use a wrapper or reconsider this package.

• Error: Unrecognised input or other Less compilation errors.

  cause Using modern Less syntax or features (e.g., advanced functions, new `@import` rules, or CSS features) that are not supported by the outdated Less compiler version likely used by `less-bundle-promise`.
  fix Simplify your Less code to older syntax, or, preferably, migrate to a current Less compilation pipeline that supports up-to-date Less and CSS standards.

• TypeError: Cannot read properties of undefined (reading 'then') or similar Promise-related errors.

  cause While `less-bundle-promise` uses Promises, an extremely old Node.js version (pre-ES6) or environment without a Promise polyfill might cause issues. However, given Node.js >=0.10.0 requirement, this is less likely to be the root cause than other factors like incorrect usage or deep incompatibility. A more probable cause is the underlying `less` compilation failing synchronously before a promise can be returned.
  fix Ensure a compatible Node.js version is used. Check Less input files for syntax errors that might prevent successful compilation and subsequent Promise resolution. Consult the internal `less` package for any specific polyfill requirements if running in highly constrained environments.

Warnings

• breaking This package is no longer maintained. It relies on older versions of Node.js (>=0.10.0) and the `less` compiler, which may not be compatible with modern Node.js runtimes (e.g., Node.js 16+ or 18+ which often mandates ESM) or the latest Less syntax and features.
  Fix: For new projects, consider modern Less build tools like Webpack with Less-loader, Rollup with appropriate plugins, or the official `less` package directly with its newer API which includes promise support.
• gotcha The package uses CommonJS `require` syntax exclusively and does not support ES Modules (ESM). Using `import` statements directly with this package in an ESM context will lead to runtime errors (e.g., `require is not defined` or module not found).
  Fix: Ensure your project uses CommonJS modules or transpile your code to CommonJS if integrating this package into an ESM environment. Alternatively, find a modern alternative that supports ESM.
• gotcha Given its age, `less-bundle-promise` might not support newer Less language features, `@import` syntax variations, or CSS specifications that have been introduced in recent years. This could lead to unexpected compilation errors or incorrect output for modern Less stylesheets.
  Fix: Test with your specific Less files. If issues arise, manually compile problematic sections with a modern Less compiler to identify incompatibilities or migrate to a more current bundling solution.
• deprecated The package lists '0 Dependencies' on npm, which is highly unlikely for a Less bundler. This suggests that the `less` compiler itself might be a transitive dependency or assumed to be globally available, or it bundles an older version internally. This lack of explicit dependency management is problematic for modern package ecosystems.
  Fix: Verify the actual runtime dependencies in your `node_modules`. Be aware that the `less` version it compiles against will be fixed to whatever was bundled or used during its development, potentially outdated. Explicitly installing `less` as a direct dependency in a compatible older version might be necessary if this tool relied on a peer dependency.

Install

• npm install less-bundle-promise npm
• yarn add less-bundle-promise yarn
• pnpm add less-bundle-promise pnpm

Imports

• bundle
  wrong:

  import bundle from 'less-bundle-promise';
  // or
  import { bundle } from 'less-bundle-promise';

  correct:

  const bundle = require('less-bundle-promise');

  This package exclusively uses CommonJS `require()` syntax. It does not support ES Modules (ESM) `import` syntax. Attempting to import it as an ESM module will result in a runtime error.

Quickstart

This quickstart demonstrates how to use `less-bundle-promise` to compile multiple Less files into a single output, either printed to the console or written to a specified destination file. It showcases both the basic usage and the `writeFile` option, including creation of a temporary file structure for a runnable example.

const bundle = require('less-bundle-promise');
const fs = require('fs');
const path = require('path');

// Create a dummy main.less file for demonstration
const mainLessContent = `
@import "./components/button.less";
@import "./theme/colors.less";

body {
  font-family: Arial, sans-serif;
  .button-style;
  background-color: @primary-color;
}
`;
const buttonLessContent = `
.button-style {
  padding: 10px 15px;
  border: 1px solid black;
  border-radius: 5px;
  color: white;
}
`;
const colorsLessContent = `
@primary-color: #3498db;
@secondary-color: #2ecc71;
`;

const tempDir = path.join(__dirname, 'temp_less_project');
const componentsDir = path.join(tempDir, 'components');
const themeDir = path.join(tempDir, 'theme');

fs.mkdirSync(componentsDir, { recursive: true });
fs.mkdirSync(themeDir, { recursive: true });
fs.writeFileSync(path.join(tempDir, 'main.less'), mainLessContent);
fs.writeFileSync(path.join(componentsDir, 'button.less'), buttonLessContent);
fs.writeFileSync(path.join(themeDir, 'colors.less'), colorsLessContent);

// Bundle Less files and print to console
bundle({
    src: path.join(tempDir, 'main.less')
}).then(output => {
  console.log('--- Bundled LESS Output (to console) ---');
  console.log(output);
  console.log('----------------------------------------');
})
.catch(error => {
  console.error('Error bundling LESS:', error);
});

// Bundle Less files and write to a destination file
const destPath = path.join(tempDir, 'bundle.less');
bundle({
    src: path.join(tempDir, 'main.less'),
    dest: destPath,
    writeFile: true
}).then(output => {
  console.log(`Bundle successfully written to ${destPath}`);
  console.log('--- Content of bundle.less ---');
  console.log(fs.readFileSync(destPath, 'utf8'));
  console.log('------------------------------');
})
.catch(error => {
  console.error('Error writing bundled LESS to file:', error);
});

// Clean up temporary files (optional, for a real quickstart you might omit cleanup for user inspection)
// setTimeout(() => {
//   fs.rmSync(tempDir, { recursive: true, force: true });
//   console.log('Cleaned up temporary directory.');
// }, 2000);