Rspack Plugins Not Resolving Imports In Bundleless Mode

Hey guys! So, I ran into a bit of a head-scratcher while working with rspack and rslib, and I figured I'd share it with you all. Basically, when you're using rslib in bundleless mode (that is, bundle: false), it seems like rspack plugins aren't calling the normalModuleFactory.hooks.resolve hook on import declarations within your source files. Let's dive into the nitty-gritty of what's happening and why it's a problem, especially if you're using plugins like unplugin-parcel-macros.

The Core Issue: resolve Hook Not Firing

The Problem: The crux of the issue is that in bundleless mode, rspack plugins don't trigger the resolve hook for import statements within your code. They do call the beforeResolve hook, which might lead you to think everything's working, but the subsequent resolve hook, which is crucial for many plugins, doesn't get called on these imports. This behavior is unexpected, especially because the beforeResolve hook is called. This inconsistency breaks the expected plugin lifecycle and prevents certain functionalities from working correctly.

What's Happening Under the Hood: When rslib is configured to output in bundleless mode, it seems to alter how rspack processes import declarations. Specifically, the normalModuleFactory.hooks.resolve hook, which is typically called during the module resolution process to determine the final path of an import, isn't being invoked for imports within your source files. Instead, the hook is called on the result of the source.entry glob, but it does not loop through the imports of each source file, which is the expected behavior. This means plugins that rely on this hook to modify or process import paths are left in the dark, unable to perform their intended tasks.

Why This Matters: This behavior can be a real pain, especially if you're using plugins that need to manipulate or generate assets based on your imports. For instance, in the case mentioned in the original report, the user is using unplugin-parcel-macros, which relies on the resolve hook to generate CSS files. Since the hook isn't being called, the plugin can't do its job, and the CSS files aren't created, leading to broken builds and a lot of head-scratching.

This behavior is counterintuitive because the beforeResolve hook is being called. One might reasonably expect that if beforeResolve is called, resolve would follow. This inconsistency is the core of the problem and the reason why certain plugins are not functioning correctly in bundleless mode.

Deep Dive into the Technical Details

Let's get a little technical and look at exactly what's going on. This will help you understand why this is happening. The issue revolves around how rspack handles module resolution in bundleless mode. In a nutshell, rspack needs to figure out where your imports are located, so it can bundle everything correctly. It does this using a series of hooks, including beforeResolve and resolve.

The Role of normalModuleFactory.hooks.resolve: The resolve hook is where the magic happens. This hook lets plugins intervene during the resolution process. Plugins can modify the import paths, redirect them, or even generate new files based on those imports. The hook receives information about the import, including its original path and other metadata. Plugins then use this information to resolve the import to its final location. It's an essential part of the plugin lifecycle.

Bundleless Mode Tweaks: When rslib is in bundleless mode, rspack's behavior changes. It seems that the part of rspack responsible for iterating through import declarations and calling the resolve hook is either skipped or implemented differently. This is why the plugin fails to write out the corresponding CSS file. This is where the issue comes from.

Implications for Plugin Developers: If you're building a plugin that relies on the resolve hook, you need to be aware of this behavior, especially if your plugin is designed to work in a bundleless environment. You might need to find alternative ways to detect and process imports, or you might have to adjust your plugin's approach to account for the missing resolve hook.

Understanding the Code (Simplified): Without diving too deep into rspack's source code, think of it this way: Rspack usually has a routine that loops through all the import statements in your files. For each one, it calls the beforeResolve hook, followed by the resolve hook. In bundleless mode, it appears that this loop isn't happening for imports within the source files. Instead, the resolve hook might only be called for entry points. This is why the plugin isn't working.

Practical Implications and Workarounds

So, what does this all mean for you, the developer? And, more importantly, are there any workarounds? Let's explore.

Impact on Development: The most immediate impact is that plugins that depend on the resolve hook won't work as expected. This can break your build process and lead to frustrating debugging sessions. The fact that the beforeResolve hook is called adds to the confusion. This subtle difference in behavior can be difficult to track down without a deep understanding of rspack's inner workings.

Specific Examples: As mentioned earlier, plugins like unplugin-parcel-macros are directly affected. This plugin relies on the resolve hook to generate CSS files. Since the hook isn't called, the CSS files aren't generated, and your styling will be missing. This can also affect other plugins that need to modify import paths, generate assets, or perform other build-time transformations.

Possible Workarounds and Solutions:

• Investigate Alternative Hooks:** Explore if there are alternative hooks that you can use. You may be able to use the beforeResolve hook and perform the necessary logic there. You might have to adjust your plugin's logic to fit the limited context provided by the beforeResolve hook.
• Modify the Rspack Configuration: It might be possible to adjust the rspack configuration to force the resolve hook to be called. However, this is likely to be a complex solution and could potentially break other parts of your build process.
• Look for Updates and Fixes: Keep an eye on the rslib and rspack repositories for updates. This might be a bug that can be resolved in a future version. Check the issue tracker for any existing reports and potential fixes. If there isn't one, consider creating one, providing as much detail as possible to help the maintainers understand and resolve the issue.
• Refactor the plugin (if possible): If you have the source code for the plugin, you might try refactoring the plugin to use an alternative mechanism or hook that is triggered in bundleless mode.
• *Post-Processing: Consider implementing a post-processing step to work around the issue. For example, your build process can parse the source code, identify import declarations, and then run your plugin logic. This approach is more complex and has its own issues, but it can be a temporary solution.

Reproducing the Issue

Fortunately, the issue is reproducible. The original report includes a link to a reproduction repository (https://github.com/davidferguson/rslib-bundle-noresolve). This repo provides a clear and concise way to replicate the problem. Guys, I encourage you to check out the repo to see the problem in action.

Steps to Reproduce:

1. Clone the repository.
2. Install the dependencies.
3. Run the build process.
4. Observe that the plugin isn't working as expected (e.g., the CSS files are not generated).

By following these steps, you can quickly verify the behavior and confirm that the resolve hook isn't being called for import declarations in bundleless mode.

Conclusion

In conclusion, the bug causes a real headache for developers using rspack plugins in bundleless mode, particularly those that rely on the normalModuleFactory.hooks.resolve hook. Understanding the issue and knowing possible workarounds can help you address this problem in your projects. Hopefully, with this info, the rspack team will provide a fix or workaround for this in the future.