Plugin development: I can't get addDependency to watch and reload on file change

[a-type]

I am attempting to build an Rsbuild plugin for UnoCSS. Their support for Rstack is pretty minimal, and I felt a handmade plugin would perform better than their suggested approach.

UnoCSS is like Tailwind, where a virtual CSS file is generated based on tokens scanned from user source files. I am building in the Virtual Module plugin to handle this, and so far that part is working.

However, another feature Uno supports is watching arbitrary files in the filesystem which are not packaged in the bundler. I am struggling to get Rsbuild/Rspack to actually monitor for changes which come from outside the bundler's source files.

My plugin source is here: https://github.com/a-type/rsbuild-plugin-unocss

Here is the approach I'm trying to use:

1. On plugin startup, create a filesystem watcher for the user's specified filesystem dependencies (this works)
2. This triggers the invalidation of the Uno CSS compilation, running a rebuild. When the rebuild is complete, I am writing a "trigger file" to the filesystem which contains a unique nonce value to indicate the build changed.. The file updates as expected when I change external files.
3. To ensure the virtual module is not cached, I intercept resolution and add this nonce value to the module's query during resolution.
4. When the virtual UnoCSS module is transformed, I await the latest triggered rebuild and write out the generated CSS..
5. I have attempted, in multiple ways, to mark this trigger file as a dependency of the main CSS build file. Both by explicitly using addDependency and by injecting an import of this file from the built CSS. This does not seem to work.

When I make changes to the source files included in the bundle, the Uno-generated CSS reloads and is applied as expected. I believe this is because the bundler source triggers the rebuild, and imports uno.css, which is intercepted and updated to uno.css?tokens=... due to the rebuild, bypassing cache and resolving the virtual module, etc, and it works as designed.

But changing external sources does not trigger a rebuild. It triggers invalidation, rebuilds UnoCSS, and writes a file to <virtualDir>/trigger.css in the filesystem. But despite adding this absolute path as a dependency to uno.css, nothing else happens.

To reproduce this issue in my repository, launch the playground and make edits to ./external/external.ts to change the value inside the ["external"] brackets (it must be syntactically valid to work, so just change the quoted text). You should see the file ./node_modules/.rsbuild-virtual-module/trigger.css update with a new --uno-nonce value, a log in the terminal about regenerating UnoCSS, but no change in the browser.

What I did appears to be in line with the documentation of the Virtual Modules plugin, so I'm not sure what I did wrong. Any tips?

Note: the reason I am using a "trigger" file instead of adding dependencies on the external files directly, is because these dependencies are defined using Regex and globs, and it would be difficult to reduce them to context directories and individual file references on demand. It would be much easier to rely on chokidar as I'm currently doing and manually invalidate the Rsbuild build, hence the workaround.

Note 2: I have also tried using sockWrite('static-changed') on rebuild, but this does not invalidate the cache, so the reloaded page still gets the old generated CSS. I assume this is because the entry file is not invalidated, so the bundler doesn't attempt to resolve uno.css and get the updated nonce. Once again, I assume if my addDependency had worked, it would have rebuilt the uno.css virtual module and picked up this new dependency...

[chenjiahan]

I'm excited to hear that you're building a UnoCSS plugin for Rsbuild! I've received feedback from users about some unresolved issues with @unocss/webpack. I believe a dedicated plugin for Rsbuild would provide a much better experience.

Regarding the addDependency issue you encountered, I did a quick investigation and found that addDependency is working correctly. The key issue is that Rspack doesn't watch files in node_modules by default. This can be changed by configuring the watchOptions.ignored option.

I think rsbuild-plugin-virtual-module should set the watchOptions.ignored option by default to enable watching of virtual modules in node_modules/.rsbuild-virtual-module. I'll talk to @SoonIter and get it fixed.

Before we release a new version of rsbuild-plugin-virtual-module, you can temporarily update the configuration in your rsbuild.config.ts to test this:

import { defineConfig } from "@rsbuild/core";
import { pluginUnoCss } from "../src/index.js";

export default defineConfig({
  plugins: [pluginUnoCss()],
  server: {
    port: 3001,
    strictPort: true,
  },
+ tools: {
+   rspack: {
+     watchOptions: {
+       // or set "ignored: /\.git/" to watch the entire node_modules
+       ignored: /[\\/](?:\.git|node_modules(?![\\/]\.rsbuild-virtual-module))[\\/]/,
+     },
+   },
+ },
});

[chenjiahan]

I also discovered two other issues when debugging:

1. If the node_modules/.rsbuild-virtual-module directory doesn't exist, index.ts#L31 will throw a no such file or directory error. Perhaps rsbuild-plugin-unocss could check whether node_modules/.rsbuild-virtual-module exists and create it before writing files.

2. With @rsbuild/core >= 1.4.4, import raw from 'uno.css?raw'; doesn't work as expected, which might be related to fix: ensure that raw query of styles can be accurately matched #5540. This should be fixed by fix: enhance raw query regex to support more patterns #5938

[a-type]

Thank you so much for looking into this so thoroughly! I'm excited to keep going, I was really stumped. For my own learning, are decisions like not watching in node_modules documented anywhere, or does knowing these details just require familiarity with the project internals? I haven't found very many in-depth docs about plugin development and have been mostly experimenting via trial and error.

As for the other issues, I'm still experimenting with approaches so I haven't bothered tying up loose ends like missing directories, etc. I'll be sure to follow up on these things when I'm settled on the approach and begin writing some tests.

I've definitely found the official UnoCSS options for Rsbuild are either buggy, slow (no cache) or with PostCSS, too limited (no source transforms). I love UnoCSS and have recently switched to Rsbuild for better Module Federation support. Hopefully I can get this plugin working well and achieve a first-class experience.

[a-type]

By the way, I'm not sure it's desirable for Virtual Modules to watch contents of its directory by default, even though it did cause me confusion. The files 'backing' virtual modules are not really meaningful and are empty by default. It's probably more typical for virtual modules to be derived from files outside node_modules which will be properly watched; the placement of my trigger file is more a particular accident of the needs of this plugin. Just knowing how to properly configure the exclusion is sufficient.

[a-type]

While I continue to figure this out, I may as well ask you, also:

Right now when I update the generated CSS virtual module, it always triggers a full page reload. Is this also due to a node_modules limitation, or am I missing some logic to enable HMR on the generated CSS? I've pushed my latest code to main.

Edit: forgot to preserve console logs... it appears that importing my virtual uno.css causes the root module to no longer by accepted by HMR.

Edit 2: This appears to be because of my ?tokens=... cache busting hack, which is disposing the module each time it changes, and I think this breaks HMR. But fortunately I just removed that and I don't think it was even necessary; the trigger file appears to be sufficient for forcing the regeneration of the CSS.

[chenjiahan]

For my own learning, are decisions like not watching in node_modules documented anywhere

Sure, here's the context for this decision: #4058

I'm not sure it's desirable for Virtual Modules to watch contents of its directory by default

Rspack v1.5 will have a built-in virtual modules plugin, it no longer needs to write files to disk, which I think can avoid the problem from the root: https://rspack.rs/plugins/rspack/virtual-modules-plugin