Liferay NPM Bundler Sass Loader

2.32.2 verified Thu Apr 23 auth: no javascript

The `liferay-npm-bundler-loader-sass-loader` is a specialized loader designed for the Liferay npm bundler ecosystem. Its primary function is to process Sass (`.scss` or `.sass`) source files, compiling them into standard CSS (`.css`) for deployment and browser consumption. The package, currently at version 2.32.2, is part of the actively maintained `liferay-frontend-projects` monorepo, which sees regular updates across its various components. This loader automatically changes file extensions during the build process to ensure correct serving. It prioritizes `node-sass` if available in the project, falling back to `sass` (Dart Sass), and finally using a bundled `sass` copy if neither is found. Its key role is to seamlessly integrate Sass pre-processing into Liferay's module bundling workflow.

Common errors

error Module not found: Error: Can't resolve 'sass-loader' in '<path-to-your-module>' ↓

cause The `liferay-npm-bundler-loader-sass-loader` package has not been installed as a project dependency.

fix

Run npm install --save-dev liferay-npm-bundler-loader-sass-loader in your project directory.

error Error: `node-sass` or `sass` not found. Please install a Sass compiler. ↓

cause The Sass loader requires an external Sass compiler (`sass` or `node-sass`) to be present in your project's `devDependencies` or `dependencies`, but neither was found or accessible.

fix

Install a Sass compiler: npm install --save-dev sass (recommended) or npm install --save-dev node-sass (legacy).

error SassError: Undefined variable. ↓

cause This error typically indicates a syntax issue within your `.scss` or `.sass` files, such as referencing an undeclared variable, a missing semicolon, or incorrect nesting.

fix

Carefully review your Sass source files, paying close attention to variable declarations, imports, syntax, and proper nesting to resolve the underlying compilation error.

Warnings

gotcha The loader attempts to resolve Sass compilers in a specific order: first `node-sass`, then `sass` (Dart Sass), and finally an internal bundled `sass` copy. This prioritization can lead to an older or unintended compiler being used if multiple are present in your project's dependencies. ↓

fix Explicitly install `sass` (Dart Sass) and ensure `node-sass` is not present in your `package.json` if you intend to exclusively use Dart Sass. Remove unwanted Sass compiler dependencies from your project.

deprecated `node-sass` is generally deprecated and may have compatibility issues with newer Node.js versions. While the loader can still utilize it, the modern and recommended approach is to use `sass` (Dart Sass). ↓

fix Migrate from `node-sass` to `sass` (Dart Sass) by uninstalling `node-sass` and installing `sass` (`npm install --save-dev sass`) in your project.

gotcha This package is part of the `liferay-frontend-projects` monorepo. Specific breaking changes or significant updates for `liferay-npm-bundler-loader-sass-loader` may not always have dedicated changelog entries but rather be part of broader monorepo releases, potentially affecting its behavior. ↓

fix Consult the `liferay-frontend-projects` monorepo's overall changelog and release notes for comprehensive information regarding updates, potential breaking changes, and cross-package impacts.

Install

npm install liferay-npm-bundler-loader-sass-loader

yarn add liferay-npm-bundler-loader-sass-loader

pnpm add liferay-npm-bundler-loader-sass-loader

Imports

sass-loader

wrong

import { SassLoader } from 'liferay-npm-bundler-loader-sass-loader'; // Incorrect: this is a build-time loader, not a JS module export
const SassLoader = require('liferay-npm-bundler-loader-sass-loader'); // Incorrect: this is a build-time loader, not a JS module export

correct

{
  "rules": [
    {
      "test": "\\.scss$",
      "exclude": "node_modules",
      "use": ["sass-loader"]
    }
  ]
}

This loader is configured via a string literal in the `use` array within your Liferay npm bundler `.npmbundlerrc` configuration file, not imported directly as a JavaScript module using `import` or `require` statements.

Quickstart

Installs the Sass loader and configures Liferay's npm bundler to process `.scss` and `.sass` files into CSS.

npm install --save-dev liferay-npm-bundler-loader-sass-loader sass

// Create or modify your .npmbundlerrc file at the root of your module
// Example .npmbundlerrc content:
{
  "rules": [
    {
      "test": "\\.scss$",
      "exclude": "node_modules",
      "use": ["sass-loader"]
    },
    {
      "test": "\\.sass$",
      "exclude": "node_modules",
      "use": ["sass-loader"]
    }
  ]
}