RFC: cssLoaderOption

[ghost]

Summary

How about allow cssOption like sassOptions?

Issues: #10584 #10339 (comment) #14295

Background

1. Optimizing className in production.
   Now we cannot cutomize className.
   But I wanna use shorter className in production.

2. I wanna transfer export name.
   As you know, css recommends to use kebab-case.
   But I cannot use hyphen in JS.
   Of course, I can use like this: styles['active-header'] (I think this syntax is ugly... 😞 )

Solution

Above two things are already supported in css-loader.

https://github.com/webpack-contrib/css-loader#localidentcontext

https://github.com/webpack-contrib/css-loader#namedexport

Conclusion

So I hope next.js supports cssOptions.
And then we can customize cssLoaderOptions in next.config.js:

// next.config.js
const path = require('path')

module.exports = {
  cssOptions: {
    esModule: true,
    modules: {
      localIdentName: '[hash:base64:5]',
      namedExport: true      
    },
  },
  sassOptions: {
    includePaths: [path.join(__dirname, 'styles')]
  }
}

[timneutkens]

Optimizing className in production. Now we cannot cutomize className. But I wanna use shorter className in production.

This is already being worked on: #14197 so it does not warrant having an extra configuration option.

Of course, I can use like this: styles['active-header'] (I think this syntax is ugly... 😞 )

This seems more like a personal preference than a reason to add an extra configuration option to Next.js which has to be maintained forever.

[ghost]

This seems more like a personal preference than a reason to add an extra configuration option to Next.js which has to be maintained forever.

Yes you're right! This is my preference.
So I don't wanna add namedexport option by default but I wanna allow external cssOptions.
As you know, nextjs already allow external sassOptions in next.config.js.

[Joozty]

I wouldn't call it a personal preference. I can also argue the same that style['class-name'] is a preference of yours. Anyway it's not about preferences it's about everyone needs something else for their projects. And enabling cssOptions gives freedom to devs. I like camelCase because my IDE is able to show me (highlight) if the class exists or not.

On the other hand, I understand that it may be hard to maintain. I would like to just know if this is going to be implemented or not since I am using "ugly" workaround for camelCases. If not I will migrate to styles['class-name'] syntax

Thanks a lot 🙂

[aegirokran]

It's great that Next.js includes solid default settings for build tools like css-loader. This helps developers have best practices out of the box with zero initial configuration. Including the new work on optimizing className in production.

However, what's even better, is if you allow developers full unobstructed access to the configuration of the build tools for when their individual organization's workflows are different than what Next.js defaults to (or has configuration abstractions for).

This is important to me to align a few Next.js projects with many other projects running on other JS/TS frameworks where we've already customized css-loader with an organization-wide standard. It is quite frustrating when a framework includes a front end build tool, but doesn't allow for full customization of that build tool.

I'd suggest building upon the recent work to allow customization of sass-loader with sassOptions in #12685. It would be very helpful to have full customization of css-loader. Ideally something like this:

// next.config.js

module.exports = {

  sassOptions: { 
    ...
  },

  cssLoaderOptions: {  
    modules: {
      mode: 'local',
      localIdentName: '[path][name]__[local]--[hash:base64:5]',
      ...
    },
  }

}

[limichange]

Nuxtjs can do it so easily, but nextjs can't do it. Optimizing className in production is a great feature, people need a config option to config it.

[murilomothsin]

Hello guys,
I'm removing withCSS from my project, but I have a cssLoaderOption with url: false. Do you have news about this change or a way to pass this option to nextJS built-in solution?

Thanks

[ghost]

No, now there is no way to configure it.
That's why I open this issue :)

[murilomothsin]

Got it.

If there is anything I can do to help you, please let me know.

[DmitrySkripunov]

While we all are waiting that feature, may be it would be useful for somebody -
I override localIndent function in next.conf.js

const path = require('path');

function getCustomLocalIdent(
  context,
  _,
  exportName,
  options
) {
  const relativePath = path
    .relative(context.rootContext, context.resourcePath)
    .replace(/\\+/g, '/');

  // Generate a hash to make the class name unique.
  const hash = loaderUtils.getHashDigest(
    Buffer.from(`filePath:${relativePath}#className:${exportName}`),
    'md5',
    'base64',
    5
  );

  // Have webpack interpolate the `[folder]` or `[name]` to its real value.
  return (
    loaderUtils
      .interpolateName(
        context,
        hash,
        options
      )
      .replace(
        // Webpack name interpolation returns `about.module_root__2oFM9` for
        // `.root {}` inside a file named `about.module.css`. Let's simplify
        // this.
        /\.module_/,
        '_'
      )
      // Replace invalid symbols with underscores instead of escaping
      // https://mathiasbynens.be/notes/css-escapes#identifiers-strings
      .replace(/[^a-zA-Z0-9-_]/g, '_')
      // "they cannot start with a digit, two hyphens, or a hyphen followed by a digit [sic]"
      // https://www.w3.org/TR/CSS21/syndata.html#characters
      .replace(/^(\d|--|-\d)/, '__$1')
  );
}

module.exports = {
  webpack(config, {dev, isServer}) {
    config.module.rules[1].oneOf.forEach((moduleLoader, i) => {
      Array.isArray(moduleLoader.use) && moduleLoader.use.forEach((l) => {
        if (l.loader.includes('css-loader')) {
          l.options.modules = {
            ...l.options.modules,
            getLocalIdent: getCustomLocalIdent
          };
          l.options = {
            ...l.options,
            esModule: true
          };
        }
      });
    });
    return config;
  }
};

It's awful, I know( but now it is the best solution I could invent.

[DmitrySkripunov]

sorry, guys, looks like there is some problem with global styles.

[pecoram]

Hi @DmitrySkripunov, your code conflicts with postcss-loader.
I think you should do something like this
l.loader.includes('css-loader') && !l.loader.includes('postcss-loader')

[Grawl]

loaderUtils is undefined. How should I define it?

[pecoram]

This code works fine for me!

webpack(config, options) {
      config.module.rules[1].oneOf.forEach((moduleLoader, i) => {
        Array.isArray(moduleLoader.use) &&
          moduleLoader.use.forEach((l) => {
            if (l.loader.includes('css-loader') && !l.loader.includes('postcss-loader')) {
              delete l.options.modules.getLocalIdent;
              l.options.modules = {
                ...l.options.modules,
                // Your custom css-modules options below.
                localIdentName: '[local]',
              };
            }
          });
      });
    return config;
  }
};

[mheras]

It works 👍
But it slows down compilation time A LOT.
We need a built-in solution.

[donovantc]

Thanks for the workaround @pecoram. I'm also concerned about the compilation time but I don't have anything better at the moment. Have you perhaps found any better workaround or optimization in the meantime?

[pecoram]

Currently I'm using this:

let rule;
      let moduleRules;
      let cssLoader;
      if ((rule = config.module.rules.find((rule) => Object.keys(rule).includes('oneOf')))) {
        if ((moduleRules = rule.oneOf.filter((r) => Array.isArray(r.use)))) {
          for (const moduleRule of moduleRules) {
            if ((cssLoader = moduleRule.use.find((u) => u.loader.match('css-loader')))) {
              delete cssLoader.options.modules.getLocalIdent;
              cssLoader.options = {
                ...cssLoader.options,
                modules: {
                  ...cssLoader.options.modules,
                  localIdentName: '[local]',
                },
              };
            }
          }
        }
      }

but a build-in solution would be better

[hostel]

Currently I'm using this:

let rule;
      let moduleRules;
      let cssLoader;
      if ((rule = config.module.rules.find((rule) => Object.keys(rule).includes('oneOf')))) {
        if ((moduleRules = rule.oneOf.filter((r) => Array.isArray(r.use)))) {
          for (const moduleRule of moduleRules) {
            if ((cssLoader = moduleRule.use.find((u) => u.loader.match('css-loader')))) {
              delete cssLoader.options.modules.getLocalIdent;
              cssLoader.options = {
                ...cssLoader.options,
                modules: {
                  ...cssLoader.options.modules,
                  localIdentName: '[local]',
                },
              };
            }
          }
        }
      }

but a build-in solution would be better

it works, but threre is some problems with global styles

[Grawl]

Not works in Next 13.

[parlay96]

I tried to change the source code in next and it worked

[timneutkens]

#22313 (comment)

At this point in time we're not planning to allow configuring css-loader and other loaders further as we're working on porting a lot of the underlying compiler to Rust to make Next.js compilation significantly faster. This option would increase the scope for that work a lot and push back releasing it severely given that we'd have to implement every single option css-loader has vs what Next.js has today. I'll post this on the RFC as well 👍 Once these parts of the compilation are ported we can revisit what options are useful to add to Next.js directly.

[vladmiller]

Any updates on that?

That comes as an issue in a monorepo environment. We have a separate package for all of the UI components that is built using css-module local convention for camelCase;

I can obviously use compiled version of components package in Next.js application, but that reduces developer's experience a lot.

[Grawl]

For Next 13, here's the config to change CSS Modules Scoped Name:

const path = require('node:path');
const { createHash } = require('node:crypto');

const getHash = (source, length) =>
    createHash('shake256', { outputLength: length }).update(source).digest('hex');

/**
 * @type {import('next').NextConfig}
 */
const nextConfig = {
    // ... your existing config here ...
    webpack: (config, { dev }) => {
        // https://github.com/vercel/next.js/discussions/15818
        let rule, moduleRules, cssLoader;
        if ((rule = config.module.rules.find((rule) => Object.keys(rule).includes('oneOf')))) {
            if (
                (moduleRules = rule.oneOf.filter(
                    (r) =>
                        ('test.module.scss'.match(r.test) || 'test.module.css'.match(r.test)) &&
                        Array.isArray(r.use),
                ))
            ) {
                for (const moduleRule of moduleRules) {
                    if ((cssLoader = moduleRule.use.find((u) => u.loader.match('css-loader')))) {
                        delete cssLoader.options.modules.getLocalIdent;
                        cssLoader.options = {
                            ...cssLoader.options,
                            modules: {
                                ...cssLoader.options.modules,
                                getLocalIdent: ({ resourcePath }, localIdentName, localName) => {
                                    const { name } = path.parse(resourcePath);
                                    const moduleName = name
                                        .replace(/\.module/g, '')
                                        .replace(/\./g, '-');
                                    return dev
                                        ? `${moduleName}--${localName}--${getHash(resourcePath, 2)}`
                                        : `_${getHash(`${resourcePath}${localName}`, 4)}`;
                                },
                            },
                        };
                    }
                }
            }
        }
        return config;
    },
};

module.exports = nextConfig;

This gives you class names like DefaultLayout--root--e220 for .root {} placed in DefaultLayout.module.scss, plus 4 chatacters length hash (8 chatacters in build) made of absolute full (S)CSS file path like '/Users/username/path/to/project/src/path/to/component/DefaultLayout/DefaultLayout.module.scss' (plus original class name for build).

[Grawl]

Still want to use localIdentName like "[path][name]__[local]--[hash:base64:5]" instead of getLocalIdent, but if I delete cssLoader.options.modules.getLocalIdent or set getLocalIdent: undefined or getLocalIdent: () => true I got compiler error

[Grawl]

Also, want to simplify all this if / for spaghetti with something like webpack-chain or craco utilities like this:

const { getLoaders, loaderByName } = require('@craco/craco');
const { hasFoundAny, matches } = getLoaders(config, loaderByName('css-loader'));
if (hasFoundAny) {
    matches.forEach((cssLoader) => {
        cssLoader.options = {
            // ...
        },
    };
    });
}

But if I do so, dev server just stops with exit code 0.

[awndrw]

This works up to 14.0.2 (the latest version when this comment was posted) but we have to change u.loader.match('css-loader') to u.loader.match('/css-loader') so it doesn't match postcss-loader too.

[K-Jean]

@timneutkens with next13 can we now revisit what options are useful to add to Next.js directly ?

[jlmosconi]

This works for me in Next.js 14.2.4:

import {createHash} from 'node:crypto'

/** @type {import('next').NextConfig} */

const getHash = (source, length) =>
  createHash('shake256', {outputLength: length}).update(source).digest('hex')

const updateCssLoader = rule => {
  rule.use.forEach(moduleLoader => {
    if (
      moduleLoader.loader?.includes('/css-loader') &&
      typeof moduleLoader.options.modules === 'object'
    ) {
      // Add a custom localIdentName to the css-loader options
      moduleLoader.options.modules.getLocalIdent = ({resourcePath}, _, localName) =>
        process.env.NODE_ENV === 'development'
          ? `${localName}--${getHash(resourcePath, 2)}`
          : `_${getHash(`${resourcePath}${localName}`, 3)}`
    }
  })
}

const nextConfig = {
  webpack: config => {
    const rules = config.module.rules
      .find(rule => typeof rule.oneOf === 'object')
      .oneOf.filter(rule => Array.isArray(rule.use))

    rules.forEach(updateCssLoader)

    return config
  },
}

export default nextConfig