Custom Next.js CSS Modules Rendered ClassName or the LocalIdentName

[iamaliybi]

Summary

Hello everyone,

I'm working on a Next.js project using CSS Modules and SCSS Modules (*.module.css / *.module.scss).

By default, Next.js generates classNames like:

button_primary__3kG7a
layout_container__1x9Hd

In my case, these classNames become very long, especially in production, and I'd like to:

Either shorten them

Or generate short hash-based classNames (e.g. s0mTRRSk, lSI7qnOB)

Ideally keep readable names in dev and short hashes in production (if possible)

I've tried looking into Webpack config and css-loader options, but Next.js abstracts most of this away.

My questions:

Is it possible to customize the generated classNames in Next.js when using CSS/SCSS Modules?

Can this be controlled differently for development vs production?

Is there an officially supported way, or does it require overriding Webpack config?

Any guidance or best practice would be appreciated.

Thanks 🙏

Additional information

Development: using Turbopack
Production: using Webpack (default Next.js production build)

Operating System:
  Platform: win32
  Arch: x64
  Version: Windows 10 Enterprise
  Available memory (MB): 24456
  Available CPU cores: 4
Binaries:
  Node: 22.20.0
  npm: 11.6.2
  Yarn: N/A
  pnpm: N/A
Relevant Packages:
  next: 15.5.9 // An outdated version detected (latest is 16.1.0), upgrade is highly recommended!
  eslint-config-next: N/A
  react: 19.1.4
  react-dom: 19.1.4
  typescript: 5.9.3

[rdalfonso]

This solution generated by Claude sonnet worked for me using NextJs 15.3.9

Why it's safe:

• The hash is deterministic — same file path + class name always produces the same hash, so server-rendered HTML and client-side hydration agree.

• The hash space (base64url, 5 chars) gives ~1 billion unique values, so collisions are effectively impossible for unique class names.

• It runs inside the same webpack hook Next.js already uses, just swapping out the getLocalIdent function in the css-loader configuration before webpack starts compiling. The flow is:

  • Next.js builds the webpack config and sets modules.getLocalIdent = getCssModuleLocalIdent (the long-name generator)

  • The code in next.config.js's webpack() function runs, traverses the rules, and swaps that function reference with our short-hash version.

  • Webpack then compiles — css-loader calls the function (not the original) exactly once per class name.

// At the top of next.config.js, add:
//  The crypto module is a built-in core module included automatically with every Node.js installation
const crypto = require('crypto');

//.... After your existing code....

// Then inside the webpack() function, after the existing modifications:
webpack(webpackConfig, { dev }) {
    // ... existing code ...

    // Production-only: shorten CSS Module class names to reduce DOM/HTML size
    if (!dev) {
      const shortIdentCache = new Map();
      let shortIdentCounter = 0;

      function getShortCssModuleLocalIdent(context, _, exportName) {
        const relativePath = path
          .relative(context.rootContext, context.resourcePath)
          .replace(/\\+/g, '/');
        const key = `${relativePath}#${exportName}`;

        if (shortIdentCache.has(key)) {
          return shortIdentCache.get(key);
        }

        // Generate a short unique hash (5 chars base36 = 60M+ unique names)
        const hash = crypto
          .createHash('sha1')
          .update(key)
          .digest('base64url')
          .slice(0, 5);

        // Prefix with underscore to ensure valid CSS ident (can't start with digit)
        const ident = `_${hash}`;
        shortIdentCache.set(key, ident);
        return ident;
      }

      // Traverse all rules to find css-loader and override getLocalIdent
      function overrideCssModuleIdent(rules) {
        if (!rules) return;
        for (const rule of rules) {
          if (rule.oneOf) {
            overrideCssModuleIdent(rule.oneOf);
          }
          if (rule.use && Array.isArray(rule.use)) {
            for (const loader of rule.use) {
              if (
                typeof loader === 'object' &&
                loader.loader &&
                loader.loader.includes('css-loader') &&
                loader.options?.modules?.getLocalIdent
              ) {
                loader.options.modules.getLocalIdent = getShortCssModuleLocalIdent;
              }
            }
          }
        }
      }

      overrideCssModuleIdent(webpackConfig.module.rules);
    }

    return webpackConfig;
  },

[hanityx]

I'd be a bit careful with the 5-character hash here.
I tried the same function from the example and these two different inputs both end up as _K2ESg:

components/Button20805.module.css#root
components/Button22605.module.css#root

The Map doesn't seem to catch that, since it's keyed by the original input rather than the generated class name. A longer hash would at least make this less likely.

Also, for the setup in the question, this only affects the Webpack build. The webpack() config isn't used by Turbopack, so dev won't use the same naming logic.

So this looks like a Webpack-specific workaround, with the collision and Turbopack differences above.

[nhannm-vn]

_Yes, it is possible to customize the generated classNames for CSS/SCSS Modules in Next.js!
_Since you are using Turbopack in Development and Webpack in Production, you need to handle the configuration for both bundlers inside next.config.js.
_Solution for next.config.js
_You can customize localIdentName for Webpack (Production) and use experimental.turbo rules for Turbopack (Development):
/** @type {import('next').NextConfig} /
const nextConfig = {
// 1. Turbopack Configuration (Development)
experimental: {
turbo: {
rules: {
'.module.css': {
loaders: [
{
loader: 'css-loader',
options: {
modules: {
localIdentName: '[name]__[local]--[hash:base64:5]',
},
},
},
],
},
},
},
},

// 2. Webpack Configuration (Production)
webpack: (config, { dev, isServer }) => {
// Find css-loader rules inside Webpack
const rules = config.module.rules
.find((rule) => typeof rule.oneOf === 'object')
?.oneOf?.filter((rule) => Array.isArray(rule.use));

if (rules) {
  rules.forEach((rule) => {
    rule.use.forEach((moduleLoader) => {
      if (
        moduleLoader.loader?.includes('css-loader') &&
        !moduleLoader.loader?.includes('postcss-loader')
      ) {
        if (moduleLoader.options?.modules) {
          moduleLoader.options.modules.localIdentName = dev
            ? '[name]__[local]--[hash:base64:5]' // Readable in Dev
            : '[hash:base64:8]';               // Short hash in Prod (e.g. s0mTRRSk)
        }
      }
    });
  });
}

return config;

},
};

module.exports = nextConfig;

_Key Points to Note
+Official Support: Next.js abstracts css-loader settings, so overriding the Webpack config or using Turbopack rules in next.config.js is the standard and widely adopted community approach.
+Short Hashes in Production: Setting localIdentName to [hash:base64:6] or [hash:base64:8] for Production builds gives you ultra-short, collision-resistant classNames.
+SCSS Modules: If you use *.module.scss, the Webpack css-loader override above will automatically apply to SCSS Modules as well since Next.js processes them through css-loader.
+Hope this helps! Let me know if you run into any issues with your build.

[gilangabdian]

A possible approach is to customize the existing css-loader configuration through Next.js's webpack() hook, rather than adding a second CSS loader.

css-loader supports modules.getLocalIdent / localIdentName for controlling generated CSS Module identifiers:
https://github.com/webpack-contrib/css-loader#modules

Next.js exposes the underlying Webpack config through next.config.js:
https://nextjs.org/docs/pages/api-reference/config/next-config-js/webpack

One important detail for your setup is that development uses Turbopack. Turbopack handles CSS Modules natively, so a css-loader customization only applies to the Webpack build, not the default Turbopack dev server:
https://nextjs.org/docs/app/api-reference/config/next-config-js/turbopack

So a practical setup would be:

• Turbopack in development → keep readable/dev-friendly class names.
• Webpack in production → override getLocalIdent to generate shorter hash-based names.

If you also want the custom naming to apply during development, Next.js supports running the dev server with Webpack instead:

next dev --webpack

There is also a related Next.js discussion about changing CSS Module output (#76887), where the existing CSS loader rule is modified rather than adding a new CSS rule:
#76887

[Icyubahiro-Jay-P]

Yes you can customize the generated class names, but with the caveat that Turbopack in development ignores the webpack hook while the production Webpack build can be overridden. In next.config.js you can walk the css-loader rules and replace getLocalIdent with a short deterministic hash (for example a 6-character base64url SHA-1 of the relative file path plus the export name, prefixed with an underscore). This only affects the production build; if you also want short names in development run next dev --webpack. SCSS Modules are covered automatically because they still go through css-loader, and a 6-character hash is usually enough to avoid collisions while keeping the class names short.

[xNastouills]

Yes, you can customize CSS Module class names for both Turbopack (dev) and Webpack (production) via next.config.js.

next.config.ts / next.config.js
JavaScript
/** @type {import('next').NextConfig} /
const nextConfig = {
// 1. Turbopack (Development)
experimental: {
turbo: {
rules: {
'.module.css': {
loaders: [
{
loader: 'css-loader',
options: {
modules: {
localIdentName: '[name]__[local]--[hash:base64:5]',
},
},
},
],
},
},
},
},

// 2. Webpack (Production)
webpack: (config, { dev }) => {
if (!dev) {
const rules = config.module.rules
.find((rule) => typeof rule.oneOf === 'object')
?.oneOf?.filter((rule) => Array.isArray(rule.use));
if (rules) {
rules.forEach((rule) => {
rule.use.forEach((moduleLoader) => {
if (
moduleLoader.loader?.includes('css-loader') &&
!moduleLoader.loader?.includes('postcss-loader') &&
moduleLoader.options?.modules
) {
// Short hash for production (e.g., _s0mTRRSk)
moduleLoader.options.modules.localIdentName = '[hash:base64:6]';
}
});
});
}
}
return config;
},
};

module.exports = nextConfig;

Key details:

• Production (Webpack): Overriding localIdentName directly on Next.js's internal css-loader rules generates short, collision-resistant hashes (e.g., 6 chars) without breaking SCSS Modules.
• Development (Turbopack): Turbopack ignores webpack(), so configuring experimental.turbo.rules handles dev mode separately.