Inconsistencies in classname between server and client builds

[ApurvBazari]

Describe the bug

Issue:

Our component library is built using @vanilla-extract/css, where we transpile style.ts files into style.js for both CommonJS (cjs) and ECMAScript Module (esm) environments. Consumer applications integrate @vanilla-extract/plugins (webpack/rollup, etc.) for style extraction on their end. The issue arises during server-side rendering (SSR) when the server uses the cjs file and the client uses the esm style file.

We are encountering inconsistencies in classnames between client-side and server-side builds while using vanilla-extract/css in our component library. Upon deployment, which supports both cjs and esm builds, we have noticed differences in generated classnames when used in client and server environments. This suggests that the file scoping defined by setFileScope is not consistently applied across different build outputs. Despite setting setFileScope in our build files, there are instances where scoping unexpectedly resets between client and server builds.

---

Testing:
We have developed a sample project that replicates the setup of the component library and consumer application. This project demonstrates scenarios where classnames differ between client and server.

Upon investigation, we found that the @vanilla-extract/integration package replaces the fileScope set on the transpiled styles file from the component library. Removing this the string replacement line for setFileScope results in consistent classnames between client and server as expected.

---

Results

• Default

• Modifiying @vanilla-extract/integration

Steps to run the sample application

git clone https://github.com/ApurvBazari/vanilla-extract-sample.git
cd vanilla-extract-sample/component-library
npm i
npm run build
cd ../consumer-app
npm i
npm run all
Goto localhost:3000 to visit the application

Reproduction

https://github.com/ApurvBazari/vanilla-extract-sample/tree/main

System Info

System:
    OS: macOS 14.5
    CPU: (10) arm64 Apple M1 Max
    Memory: 748.63 MB / 64.00 GB
    Shell: 5.9 - /bin/zsh
  Binaries:
    Node: 16.20.0 - ~/.nvm/versions/node/v16.20.0/bin/node
    Yarn: 1.22.19 - ~/.nvm/versions/node/v16.20.0/bin/yarn
    npm: 8.19.4 - ~/.nvm/versions/node/v16.20.0/bin/npm
  Browsers:
    Chrome: 126.0.6478.127
    Safari: 17.5
  npmPackages:
    @vanilla-extract/css: ^1.15.3 => 1.15.3 
    @vanilla-extract/webpack-plugin: ^2.3.10 => 2.3.11 
    webpack: ^5.92.0 => 5.92.1

Used Package Manager

npm

Logs

Prop `className` did not match. Server: "styles_divider_base__3ieluy0" Client: "styles_divider_base__n47q7r0"
    at hr
    at Divider (webpack://sample-consumer-app/../component-library/packages/divider/dist/esm/my-component-library-divider.js?:21:28)
    at div
    at ThemeWrapper (webpack://sample-consumer-app/../component-library/packages/theme/dist/esm/my-component-library-theme.js?:23:25)
    at Page

Validations

• Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.
• The provided reproduction is a minimal reproducible example of the bug.

[ApurvBazari]

I have opened a PR #1446 for discussion.
It works with the repo shared

[otaviosoares]

I have a similar issue using the vite plugin, only happens in dev mode. No SSR involved, but I traced the problem down to the same line
Any help would be appreciated.

[askoufis]

I have opened a PR #1446 for discussion. It works with the repo shared

There's a good reason why we update the filescope, but I don't exactly remember it. Regardless, I don't think removing that line is a valid solution anyway.

IMO running CJS on the server and ESM on the client is the issue here. Webpack/TSC can both output ESM, so why not just use ESM? I almost managed to get an ESM server running in your reproduction, but ran into issues with importing from the component library. This may be due to how the packages are built/configured.

I have a similar issue using the vite plugin, only happens in dev mode. No SSR involved, but I traced the problem down to the same line Any help would be appreciated.

Please raise a separate issue with a minimal reproduction if this is still affecting you.

[ApurvBazari]

I have a similar issue using the vite plugin, only happens in dev mode. No SSR involved, but I traced the problem down to the same line Any help would be appreciated.

Hi @otaviosoares
It might be because in dev, vite pre-bundles the dependencies using esbuild and has an open issue regarding deduping imports:- vitejs/vite#3910
I tried the following which seems to be working for me:-

export default defineConfig({
  optimizeDeps: {
    exclude: ['your-comp-library'],
  },
  plugins: [react(), vanillaExtractPlugin()],
})

[ApurvBazari]

Hi @askoufis

Thanks for the insight. Yeah the main issue stems from running CJS in server and ESM in client. Though, I agree that a fully ESM setup would be ideal, but in practice, migrating entirely to ESM isn’t always immediately feasible, especially for legacy systems that have long relied on CJS.
We also see how this can lead to unintended consequences for different build environments, as the above case of vite dev mode. That's why, I feel maintaining build parity between CJS and ESM builds should be prioritised.

But we first need to understand better why the fileScope gets updated. One scenario where this would be useful—specifically in a microfrontend architecture where multiple remote apps with independent builds might be using different versions of the same component library built with Vanilla Extract. In such cases, ensuring proper scope separation would help avoid classname conflicts. But there are ways to tackle that without breaking the build parity between for cjs and esm.

If we know what exactly updating the fileScope helps us to achieve/avoid, I can work on updating the PR accordingly.