{"id":13446,"library":"liferay-npm-bundler-loader-css-loader","title":"Liferay npm Bundler CSS Loader","description":"The `liferay-npm-bundler-loader-css-loader` package (current version 2.32.2) is a specialized loader designed for the Liferay Portal ecosystem. Its core function is to transform traditional CSS files into JavaScript modules. When these JavaScript modules are 'required' or imported within a Liferay environment, they dynamically inject a `<link>` tag into the HTML document, enabling the application of the contained styles. This loader is tightly integrated with Liferay's frontend development tooling, inferring the necessary web context path for OSGi bundles directly from `.npmbundlerrc` or `bnd.bnd` configuration files. As part of the actively maintained `liferay-frontend-projects` monorepo, it receives continuous updates and bug fixes, ensuring compatibility and stability within Liferay Portal deployments. Its primary differentiator is its deep integration with Liferay's module and deployment mechanisms, ensuring proper handling of CSS assets in Liferay-specific projects.","status":"active","version":"2.32.2","language":"javascript","source_language":"en","source_url":"https://github.com/liferay/liferay-frontend-projects","tags":["javascript"],"install":[{"cmd":"npm install liferay-npm-bundler-loader-css-loader","lang":"bash","label":"npm"},{"cmd":"yarn add liferay-npm-bundler-loader-css-loader","lang":"bash","label":"yarn"},{"cmd":"pnpm add liferay-npm-bundler-loader-css-loader","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is a loader that operates within the liferay-npm-bundler ecosystem and requires it to function. It is a development dependency.","package":"liferay-npm-bundler","optional":false}],"imports":[{"note":"This loader is configured declaratively in the `liferay-npm-bundler`'s `.npmbundlerrc` file by referencing its string name, 'css-loader'. It does not expose JavaScript module exports for direct import into application code.","wrong":"import { cssLoader } from 'liferay-npm-bundler-loader-css-loader';\n// or\nconst cssLoader = require('liferay-npm-bundler-loader-css-loader');","symbol":"\"css-loader\"","correct":"{\n  \"rules\": [\n    {\n      \"test\": \"\\\\.css$\",\n      \"use\": [\"css-loader\"]\n    }\n  ]\n}"},{"note":"Direct ES module imports of the `liferay-npm-bundler-loader-css-loader` package are not applicable. It functions as a build-time loader, not a runtime library with code exports.","wrong":"import * as CssLoader from 'liferay-npm-bundler-loader-css-loader';","symbol":"liferay-npm-bundler-loader-css-loader","correct":"/* No direct ES module import syntax for this package. */"},{"note":"This package is a build-time loader and does not expose a CommonJS API for programmatic `require()` usage. Its functionality is activated exclusively through `.npmbundlerrc` configuration.","wrong":"const cssLoader = require('liferay-npm-bundler-loader-css-loader');","symbol":"liferay-npm-bundler-loader-css-loader (CommonJS)","correct":"/* No direct CommonJS require syntax for this package. */"}],"quickstart":{"code":"// .npmbundlerrc\n// This file configures the Liferay npm bundler to use the css-loader.\n// Place this file at the root of your Liferay OSGi module project.\n{\n  \"rules\": [\n    {\n      \"test\": \"\\\\.css$\", // Apply this rule to all files ending with .css\n      \"use\": [\"css-loader\"] // Use liferay-npm-bundler-loader-css-loader\n    }\n  ],\n  \"create-jar\": {\n    \"features\": {\n      \"web-context\": \"/my-custom-portlet-css-module\" // Define the web context path for the OSGi bundle\n    }\n  }\n}\n\n// src/main/resources/META-INF/resources/styles/main.css\n// Example CSS file within your Liferay OSGi module\n.my-custom-class {\n  background-color: #f0f8ff;\n  color: #333;\n  padding: 15px;\n  border-radius: 5px;\n  font-family: Arial, sans-serif;\n  text-align: center;\n}\n\n/* Another style for demonstration */\nbody {\n  margin: 0;\n  background-color: #eee;\n}\n\n// src/main/resources/META-INF/resources/index.js\n// Example JavaScript file. Requiring the CSS file will trigger the loader\n// and inject a <link> tag into the HTML when this module runs in the browser.\n// This is typically done in your main entry point for the Liferay portlet or module.\nconsole.log(\"Attempting to load CSS via Liferay npm bundler loader...\");\nrequire('./styles/main.css'); // This line is crucial for the loader to process and inject the CSS.\n\n// Further application logic for your Liferay module would go here.\n// For instance, rendering a component that uses the .my-custom-class.\ndocument.addEventListener('DOMContentLoaded', () => {\n  const rootDiv = document.createElement('div');\n  rootDiv.className = 'my-custom-class';\n  rootDiv.textContent = 'Hello from Liferay CSS Module!';\n  document.body.appendChild(rootDiv);\n  console.log(\"DOM content loaded and custom element appended.\");\n});\n\n// Note: This setup assumes a Liferay environment and proper build/deployment through Liferay's tooling.","lang":"javascript","description":"This quickstart demonstrates how to configure the `liferay-npm-bundler-loader-css-loader` in your `.npmbundlerrc` file and how to trigger CSS injection by `require`ing a CSS file within your JavaScript module, all within a Liferay Portal OSGi module context."},"warnings":[{"fix":"Ensure your project is a Liferay OSGi module, and correctly configure `create-jar.features.web-context` in `.npmbundlerrc` or `Web-ContextPath` in `bnd.bnd`. Adhere to Liferay's recommended project structure and build processes.","message":"This loader is specifically designed for Liferay Portal environments and expects projects to be configured as OSGi bundles. It infers the web context path from `.npmbundlerrc` or `bnd.bnd` files. Using it outside of this specific Liferay context or with incorrect bundle configuration may lead to CSS not being loaded or incorrect resource URLs.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For SSR or environments requiring static CSS with features like hashing, consider alternative bundling strategies or Liferay-specific solutions that explicitly support those paradigms. Consult Liferay's documentation for recommended approaches in such scenarios.","message":"The loader generates JavaScript modules that dynamically inject `<link>` tags into the HTML. This approach might not be suitable for server-side rendering (SSR) environments where the DOM is not available or for build pipelines that require static CSS asset compilation with advanced features like content hashing for caching.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Verify that the `create-jar.features.web-context` property in your `.npmbundlerrc` file or the `Web-ContextPath` in your `bnd.bnd` file accurately matches the deployed context path in Liferay. Ensure the OSGi bundle is correctly deployed and active.","cause":"The `web-context` path for the OSGi bundle is incorrectly configured in `.npmbundlerrc` or `bnd.bnd`, or the OSGi bundle containing the CSS is not properly deployed or accessible within the Liferay Portal.","error":"CSS file not loaded or 404 error for CSS link in the browser's network tab."},{"fix":"If using Webpack, ensure you have `css-loader` and `style-loader` (or `MiniCssExtractPlugin.loader`) configured in your Webpack rules for `.css` files. If relying solely on the Liferay bundler, confirm that your `.npmbundlerrc` configuration for `css-loader` is correct and that the module containing the `require('./my.css')` statement is being processed by the Liferay bundler.","cause":"This error typically occurs if you're using a standard bundler like Webpack alongside Liferay's npm bundler and have not configured Webpack to handle CSS files, or if you're attempting to import CSS in a context where the Liferay bundler's loader is not active.","error":"Module parse failed: Unexpected token. You may need an appropriate loader to handle this file type."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}