Mastering CSS Modules + Less: The Ultimate Styling Strategy for Micro‑Frontend Projects

In modern front‑end development, CSS preprocessing tools like Sass, Less, CSS‑in‑JS, TailWindCSS, and CSS Modules each have their own strengths. This guide presents a best‑practice combination—CSS Modules with Less—that delivers the best development experience for micro‑frontend and back‑office applications.

Why Choose CSS Modules

Style isolation is a major pain point in micro‑frontend architectures, where styles from child apps, the host app, or different pages can clash. Traditional solutions (namespacing, Shadow DOM) have limitations. CSS Modules provide a robust, automatic way to avoid conflicts without manual naming conventions.

Documentation is straightforward; developers can become proficient within ten minutes, and major tooling (Vite, CRA) supports it out of the box.

CSS Modules + Less

Because CSS Modules files follow standard CSS syntax, nesting isn’t allowed. Introducing Less (using .module.less files) enables nesting and other features. Less is chosen over Sass here because the project heavily uses Ant Design, which is built with Less and requires it for theme customization.

.container {
  .header {
    color: red;
  }
}

Variables Definition and Usage

Both Less and native CSS support variables. Below are examples of each approach.

// common.less
@width: 10px;
@height: @width + 10px;

// usage
@import './common.less';
.header {
  width: @width;
  height: @height;
}

// CSS Variables (MDN)
:root {
  --main-color: #fff;
}
.container {
  --main-color: #000;
}
.component {
  color: var(--main-color);
}

Native CSS variables are easy to distinguish (prefixed with --), require no imports, and are widely supported in modern browsers, especially in Chrome for enterprise environments.

Class Reuse with CSS Modules

CSS Modules offer a composes syntax for inheritance, which is simpler than Less @extend or mixins. Example:

// same file
.container { color: #fff; }
.component { composes: container; }

// different file
.component { composes: container from './index.module.less'; color: #000; }

The compiled output becomes something like <div class="_container_i32us _component_iw22a"/>, with the final color applied as defined.

Overriding Third‑Party Component Styles

To customize styles of third‑party components (e.g., Ant Design buttons), use the :global selector inside a module to prevent hash generation and allow scoped overrides.

.container {
  :global(.ant-button) {
    color: var(--main-color);
  }
}

Computing Class Names

When a component needs multiple or conditional classes, combine CSS Modules with the classnames library for clean, readable code.

// Multiple classes
<div className={classnames(style.container1, style.container2)} />

// Conditional class
<div className={classnames({ [style.container1]: true, [style.container2]: false })} />

// Mixed arguments
<div className={classnames('body', { [style.container1]: true, [style.container2]: false })} />

Enhanced Development Experience

With the VSCode CSS Modules extension, developers can Cmd‑click a className in JSX to jump directly to the corresponding style definition, streamlining debugging and navigation.

Additionally, CSS Modules eliminate the need for unique class prefixes across components, allowing identical class names (e.g., container, header) in different modules without conflict.

import style from './index.module.less';
const Login = () => (
  <div className={style.container}>
    <div className={style.header}>Login</div>
  </div>
);
const Register = () => (
  <div className={style.container}>
    <div className={style.header}>Register</div>
  </div>
);

Packaging CSS Modules for NPM

When publishing components as NPM packages, hashed class names can hinder style overrides. Solutions include providing a theming API (e.g., react-css-themr) that accepts a theme object, or exposing style hooks for consumers.

import React from 'react';
import { AppBar } from 'react-toolbox/lib/app_bar';
import theme from './PurpleAppBar.css';

const PurpleAppBar = (props) => (
  <AppBar {...props} theme={theme} />
);
export default PurpleAppBar;

Conclusion

The described best‑practice—using CSS Modules with Less—has been validated through extensive real‑world use. It offers reliable style isolation, flexible variable handling, easy class composition, and a smooth developer workflow, making it a compelling choice for modern front‑end projects.