CSS Modules `composes [class] from [file]` isn't processed

[ArrayKnight]

What version of Tailwind CSS are you using?

v4.1.11

What build tool (or framework if it abstracts the build tool) are you using?

Vite 7.2.2

What version of Node.js are you using?

v22.21.0

What browser are you using?

Chrome

What operating system are you using?

macOS

Reproduction URL

https://codesandbox.io/p/devbox/4nqnrj

Describe your issue

When using Tailwind with CSS Modules and the composes property with the [class] from [file] syntax, the composed style isn't processed by Tailwind, which means that the styles are invalid CSS and don't work.

In the example above, you'll see that Bar doesn't carry over the styles of Foo even though the I believe all code to be correct and valid. You can inspect Bar and trace it back to the <style> block where you can see that Foo's styles were imported / duplicated, but not processed by Tailwind, showing the @apply syntax still instead of the application style properties.

[wongjn]

Not a direct answer to your issue but some things to bear in mind from the documentation:

Tailwind is compatible with CSS modules and can co-exist with them if you are introducing Tailwind into a project that already uses them, but we don't recommend using CSS modules and Tailwind together if you can avoid it.

And:

Alternatively, you can also just use CSS variables instead of @apply which has the added benefit of letting Tailwind skip processing those files and will improve your build performance:

button {  
 background: var(--color-blue-500);
}

Also, Adam Wathan (creator of Tailwind) does seem to advocate avoiding @apply:

• https://twitter.com/adamwathan/status/1226511611592085504
• https://twitter.com/adamwathan/status/1559250403547652097
• https://x.com/adamwathan/status/1890406016291938701

[ArrayKnight]

Thank you for the quick response. Our team took this into consideration when choosing this pattern and are finding they disagree and prefer this approach. Hopefully it's a relatively easy fix to support this combination despite being one that is not recommended. I'd go into reasoning but feel that is not within scope of this particular ticket, hopefully not an issue that deters consideration of addressing this bug

[thecrypticace]

I think this may come down to the fact that we do our CSS processing in the pre phase which we have to because we need to handle imports ourselves.

For example, with the reproduction above except replacing the files with this:

/* foo.module.css */
.foo {
  color: foo;
}

/* bar.module.css */
.bar {
  composes: foo from "./Foo.module.css";
}

and given the following config / plugins:

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    react(),
    {
      name: "css-pre",
      enforce: "pre",
      transform: {
        filter: { id: /\.module\.css$/ },
        handler: (code, id) => {
          console.log(`pre  [${id}]: code before ${JSON.stringify(code.replace(/\s+/g, " "))}`);
          code = code.replace("color: foo", "color: red");
          console.log(`pre  [${id}]: code after ${JSON.stringify(code.replace(/\s+/g, " "))}`);

          return { code };
        },
      },
    },
    {
      name: "css-norm",
      transform: {
        filter: { id: /\.module\.css$/ },
        handler: (code, id) => {
          console.log(`norm [${id}]: code before ${JSON.stringify(code.replace(/\s+/g, " "))}`);
          code = code.replace("color: foo", "color: blue");
          console.log(`norm [${id}]: code after ${JSON.stringify(code.replace(/\s+/g, " "))}`);

          return { code };
        },
      },
    },
  ],
});

The results are different. You see a red Foo and a blue Bar.

The console output here shows that both files are processed twice but the output from the pre pass for Foo.module.css doesn't affect what is inside Bar.module.css:

pre  [/sandbox/src/Bar.module.css]: code before ".bar { composes: foo from \"./Foo.module.css\"; } "
pre  [/sandbox/src/Bar.module.css]: code after ".bar { composes: foo from \"./Foo.module.css\"; } "
pre  [/sandbox/src/Foo.module.css]: code before ".foo { color: foo; } "
pre  [/sandbox/src/Foo.module.css]: code after ".foo { color: red; } "
norm [/sandbox/src/Foo.module.css]: code before "._foo_1829j_1 { color: red; } "
norm [/sandbox/src/Foo.module.css]: code after "._foo_1829j_1 { color: red; } "
norm [/sandbox/src/Bar.module.css]: code before "._foo_1p3ux_1 { color: foo; } ._bar_m4t94_1 { } "
norm [/sandbox/src/Bar.module.css]: code after "._foo_1p3ux_1 { color: blue; } ._bar_m4t94_1 { } "

My assumption is that composes: … either includes the file content directly or just runs it too late in the transform pipeline.

I'm gonna do a bit more investigation to validate what I'm seeing but I don't know that there's much we can do about this.

[thecrypticace]

I dug into the Vite implementation a bit:

1. Vite runs it's CSS processing with a plugin in the normal phase (i.e. after pre) here: https://github.com/vitejs/vite/blob/4f8171eb3046bd70c83964689897dab4c6b58bc0/packages/vite/src/node/plugins/css.ts#L315
2. This handles CSS modules here: https://github.com/vitejs/vite/blob/4f8171eb3046bd70c83964689897dab4c6b58bc0/packages/vite/src/node/plugins/css.ts#L1532-L1563

If you follow through the implementation of postcss-modules you'll see that composes loads directly from the filesystem (unless you pass a custom Loader option — which Vite does not do):

• https://github.com/madyankin/postcss-modules/blob/bfd40605f25a518feee5b62d69277b1f23c0e0e8/src/pluginFactory.js#L77
• https://github.com/madyankin/postcss-modules/blob/bfd40605f25a518feee5b62d69277b1f23c0e0e8/src/Parser.js#L20
• https://github.com/madyankin/postcss-modules/blob/bfd40605f25a518feee5b62d69277b1f23c0e0e8/src/Parser.js#L31
• https://github.com/madyankin/postcss-modules/blob/bfd40605f25a518feee5b62d69277b1f23c0e0e8/src/Parser.js#L63
• https://github.com/madyankin/postcss-modules/blob/bfd40605f25a518feee5b62d69277b1f23c0e0e8/src/FileSystemLoader.js#L101

This means any transforms on Foo.module.css won't be applied when it's loaded and included. The transform has to be able to operate on Bar.module.css in isolation during the normal processing phase.

So basically:

• We process CSS files in the pre phase to handle @import ourselves
• Then Vite does it's processing which includes processing composes and other syntax for CSS modules
• When the postcss-modules plugin encounters composes it doesn't go through the transform pipeline — just loads from disk directly.
• This is normally fine but doesn't work in this case because Tailwind CSS has already run by the time the file is inlined.

So, unfortunately, using composes in this way with Tailwind CSS isn't really possible.

If you're definitely set on using composes then making direct use of CSS variables is probably the option you're going to want to go with.

[ArrayKnight]

Alright, I really appreciate the deep dive and detailed breakdown. Unfortunately, not the answer I was hoping for.

I'd like to suggest an update to the Tailwind documentation to add in some caveats in regards to CSS Modules considering it reads as a blanket statement of compatibility currently.

Obviously the findings above, but there's another topic that I wanted to document with a workaround:

When using named groups, along with group selectors, CSS Modules incorrectly hashes the class name in the selector and it can't be undone with something like :global

// Foo.tsx
import styles from './Foo.module.css';

function Foo({ className, ...rest }) {
  return <div {...rest} className={clsx('group/foo', styles.foo, className)} />
}

// Bar.tsx
import styles from './Bar.module.css';

function Bar() {
  return <Foo><div className={styles.bar} /></Foo>
}

// Bar.module.css
@reference '../../index.css';

@layer components {
  .bar {
    /* Neither of these approaches work, without the fix */
    @variant group-hover/foo {
      @apply bg-red-300;
    }

    :global {
      @variant group-hover/foo {
        @apply bg-red-300;
      }
    }
  }
}

The fix:

import path from 'node:path';
import tailwindcss from '@tailwindcss/vite';
import stringHash from 'string-hash';
import { defineConfig } from 'vite';

function generateScopedNameDefault(
  name: string,
  _filename: string,
  css: string,
) {
  const i = css.indexOf(`.${name}`);
  const lineNumber = css.substr(0, i).split(/[\r\n]/).length;
  const hash = stringHash(css).toString(36).substr(0, 5);

  return `_${name}_${hash}_${lineNumber}`;
}

// https://vite.dev/config/
export default defineConfig({
  plugins: [tailwindcss()],
  css: {
    modules: {
      generateScopedName: (name, filename, css) =>
        name.startsWith('group\\/')
          ? name
          : generateScopedNameDefault(name, filename, css),
    },
  },
});

Notice that we're skipping over generating a scoped name whenever we run into a class that starts with group\\/, since these classes can't be added in via CSS Modules, and are global

[ArrayKnight]

If anything, these caveats may help you to deter more folks from using CSS Modules, per your recommendation