Sourcemap Option Override In Rolldown Plugin DTS Bug And Solution

Aug 1, 2025 by Chloe Fitzgerald 66 views

Option `sourcemap` Overrides Rolldown's Source Map Setting: A Deep Dive

Guys, let's dive into a tricky bug that's been causing some headaches in the Rolldown and rolldown-plugin-dts ecosystem. This article will break down the issue where the sourcemap option in rolldown-plugin-dts unexpectedly overrides Rolldown's own source map settings. We'll explore the problem, its impact, a proposed solution, and even a way to reproduce it. So, buckle up and let's get started!

Understanding the Bug: How `sourcemap` Overrides Rolldown's Settings

The core of the issue lies in how rolldown-plugin-dts handles the sourcemap option. When you set sourcemap: true either directly in your configuration or indirectly through the declarationMap TypeScript compiler option, rolldown-plugin-dts steps in and overrides the sourcemap output option that you've passed to Rolldown. This is a big problem because it doesn't just affect the generated declaration files; it impacts all files in your project.

The Annoyance and Confusion

First off, this behavior is super annoying and confusing for developers. You might be scratching your head, wondering why your source maps aren't working as expected, only to realize that rolldown-plugin-dts is the culprit. It's not immediately obvious that a plugin primarily concerned with TypeScript declarations would have such a broad impact on source map generation.

Preventing Advanced Source Map Options

But the issue goes deeper. The override also prevents you from using more advanced source map options like "inline" and "hidden". This is because rolldown-plugin-dts forces the sourcemap option to be a simple boolean value (true or false), stripping away the flexibility to configure source maps in more nuanced ways. This limitation can be a significant roadblock for projects that require specific source map configurations for debugging or production deployments.

The Proposed Solution: A More Granular Approach

To address this, a more refined approach is needed. The proposed solution suggests decoupling the generation of source maps from the top-level sourcemap option in rolldown-plugin-dts.

Leaving Source Map Generation to Rolldown

The first key change is to let Rolldown handle the actual generation of source maps based on its own configuration. This means that the sourcemap option passed directly to Rolldown should be the definitive source of truth for how source maps are created.

Controlling Parser Source Map Creation

Instead of globally forcing source map generation on or off, the sourcemap option in rolldown-plugin-dts should control whether the underlying parsers (like Babel, tsc, and oxc) create source map objects. By default, this option would be set to true, ensuring that source map data is available to Rolldown when needed. This allows Rolldown to process and output source maps according to its own settings.

Performance Considerations and Disabling Source Maps

In scenarios where it's known that no source maps are needed, you could explicitly disable source map creation within rolldown-plugin-dts for performance reasons. This prevents the parsers from wasting time generating source map data that will ultimately be discarded. This provides a performance optimization for builds where source maps are not required.

Selective Source Map Removal

As an additional step, the plugin could be modified to remove any source maps generated by Rolldown when sourcemaps: false is set in rolldown-plugin-dts. This ensures that only the runtime code has source maps, preventing declaration files from inadvertently including them. This allows for fine-grained control over which parts of your output include source maps.

Challenges with Build Hooks

One challenge lies in disabling source maps on the parsers automatically when they won't be needed. Given that some hooks used in the plugin are build hooks, there isn't a straightforward way to universally disable source map generation across all parsers. This is an area that might require further investigation and potentially a more complex solution.

The Simplicity of the Fix: A Potential PR

The good news is that the core fix for this issue is surprisingly simple. In fact, it could involve removing just one line of code (excluding the optional removal of source maps when sourcemaps: false). This highlights how a small change can have a significant impact on the overall behavior and usability of a tool.

Reproducing the Bug: A StackBlitz Example

To better understand the bug and verify the fix, a reproduction case has been created on StackBlitz. This allows you to easily see the issue in action and experiment with different configurations. The StackBlitz example demonstrates how the sourcemap option in rolldown-plugin-dts overrides Rolldown's settings, preventing the use of advanced source map options.

Accessing the Reproduction

You can access the reproduction using this link: https://stackblitz.com/edit/rolldown-rolldown-starter-stackblitz-vapkvlvo

By exploring the StackBlitz example, you can gain a deeper understanding of the bug and how the proposed solution addresses it.

System Information: Understanding the Environment

To provide context, here's the system information where the bug was initially observed:

System:
    OS: Linux 5.0 undefined
    CPU: (8) x64 Intel(R) Core(TM) i9-9880H CPU @ 2.30GHz
    Memory: 0 Bytes / 0 Bytes
    Shell: 1.0 - /bin/jsh
  Binaries:
    Node: 20.19.1 - /usr/local/bin/node
    Yarn: 1.22.19 - /usr/local/bin/yarn
    npm: 10.8.2 - /usr/local/bin/npm
    pnpm: 8.15.6 - /usr/local/bin/pnpm

This information helps to understand the environment in which the bug was encountered and can be useful for debugging and testing.

Package Manager: npm

The package manager used in this case was npm. This is another piece of information that can be helpful for reproducing the bug and ensuring that the fix works across different package managers.

Validations: Ensuring Quality and Contribution

Before reporting the bug, several validations were performed to ensure quality and adherence to contribution guidelines. These validations include:

[x] Following the Code of Conduct
[x] Reading the Contributing Guide
[x] Checking that there isn't already an issue that reports the same bug to avoid creating a duplicate
[x] Checking that this is a concrete bug. For Q&A, please open a GitHub Discussion instead
[x] The provided reproduction is a minimal reproducible of the bug

These validations demonstrate a commitment to quality and responsible contribution to the project.

In Conclusion: A Path Towards Better Source Map Handling

The sourcemap override bug in rolldown-plugin-dts is a significant issue that can lead to confusion and prevent the use of advanced source map options. The proposed solution offers a more granular approach to source map handling, allowing Rolldown to manage source map generation while giving rolldown-plugin-dts control over parser source map creation. With a potentially simple fix and a clear reproduction case, the path towards better source map handling in the Rolldown ecosystem is within reach. Keep an eye out for a potential PR that addresses this issue, and happy coding, folks!