Add x_google_ignoreList (Ignore-listing code) support to sourcemaps

[0xdevalias]

Introduce the x_google_ignoreList extension in the sourcemaps generated by this project. This will facilitate a more streamlined debugging experience in Chrome (and other supporting browsers) by automatically filtering out framework and dependency code.

Benefit

Implementing x_google_ignoreList in the sourcemaps will align this project with modern web development practices, offering a more focused and efficient debugging experience for developers using Chrome DevTools. This change will particularly benefit those who regularly engage in debugging complex applications with numerous dependencies.

Background Context

• https://developer.chrome.com/blog/devtools-modern-web-debugging/#just-my-code

  • The ignore-listing is enabled by populating an extra x_google_ignoreList field in the source map that Angular generates when compiling the project. The Chrome DevTools team encourages other framework authors to implement a similar change. Refer to the Case Study: Better Angular Debugging with DevTools post for more details.

• https://developer.chrome.com/blog/devtools-better-angular-debugging/#ignore-listing-code

  • Ignore-listing code
    When debugging applications using Chrome DevTools, authors generally only want to see just their code, not that of the framework underneath or some dependency tucked away in the node_modules folder.

    To achieve this, the DevTools team has introduced an extension to source maps, called x_google_ignoreList. This extension is used to identify third-party sources such as framework code or bundler-generated code. When a framework uses this extension, authors now automatically avoid code that they don't want to see or step through without having to manually configure this beforehand.

    The x_google_ignoreList source map extension is supported by Chrome DevTools starting with Chrome 106.

• https://developer.chrome.com/articles/x-google-ignore-list/

  • The ignoreList source map extension

    Improve debugging experience in Chrome DevTools with the ignoreList source map extension.

• https://developer.chrome.com/blog/new-in-devtools-120/#ignore-list-spec

  • The source maps specification has adopted the ignoreList field instead of x_google_ignoreList and DevTools now supports the new name with a fallback for the old one. Frameworks and bundlers can now use the new field name.

Originally posted by @0xdevalias in facebook/react#27774 (comment)

See Also

• Add x_google_ignoreList (Ignore-listing code) support to sourcemaps facebook/react#27774
• Add x_google_ignoreList (Ignore-listing code) support to sourcemaps markerikson/react-prod-sourcemaps#19
• Add x_google_ignorelist vercel/next.js#41370
  • Add `x_google_ignorelist` vercel/next.js#41371
• Add `x_google_ignoreList` (Ignore-listing code) support to sourcemaps vuejs/rfcs#607
• Add x_google_ignoreList (Ignore-listing code) support to sourcemaps sveltejs/svelte#9740
• Add x_google_ignoreList (Ignore-listing code) support to sourcemaps developit/microbundle#1066
• feat(@angular-devkit/build-angular): Identify third-party sources in sourcemaps angular/angular-cli#23545
• https://nuxt.com/blog/v3-3#better-logging-in-browser-devtools
  • feat(vite): add node_modules and buildDir to x_google_ignoreList nuxt/nuxt#19243
• https://vitejs.dev/config/server-options.html#server-sourcemapignorelist
  • feat: add sourcemapIgnoreList configuration option vitejs/vite#12174
  • fix: sourcemapIgnoreList for optimizedDeps vitejs/vite#12633
  • docs: update x_google_ignoreList documentation url vitejs/vite#12694
• https://rollupjs.org/configuration-options/#output-sourcemapignorelist
  • Add support for x_google_ignoreList rollup/rollup#4847
  • Update magic-string and adjust types. rollup/rollup#4846
  • Introduce sourcemapIgnoreList config predicate rollup/rollup#4848
  • docs: Update the x_google_ignorelist url rollup/rollup#4926

[rschristian]

This doesn't look relevant to Preact? If I'm understanding correctly, that is something that needs to be configured in build tooling, not in libraries used.

[0xdevalias]

This doesn't look relevant to Preact? If I'm understanding correctly, that is something that needs to be configured in build tooling, not in libraries used.

@rschristian My understanding was that when the framework (in this case Preact), distributes itself as a minimised bundle, this is something that should be enabled/used/included within it's sourcemaps.

I believe that would then flow on to 'downstream' web app code as well (though don't quote me on that).

[rschristian]

With this setting enabled, DevTools hides any file or folder that a framework or build tool has marked as to ignore.

https://developer.chrome.com/blog/devtools-modern-web-debugging/#just-my-code

This doesn't appear to be targetting libraries, no. This is something downstream users should be in control of.

Edit: As such, going to close this on out.

[0xdevalias]

that a framework or build tool has marked as to ignore

@rschristian Do you not consider preact a framework?

[rschristian]

It's not, no.

Nuxt, Next, Sveltekit, etc. are frameworks, Preact, Vue, React, Svelte, etc., are UI libraries.

[0xdevalias]

And Angular? Framework or 'UI library'? As they added support:

• feat(@angular-devkit/build-angular): Identify third-party sources in sourcemaps angular/angular-cli#23545

I've generally seen React/etc referred to colloquially as a framework as well; so I wouldn't be so quick to dismiss the relevance on semantic differences.

---

It looks like preact uses microbundle, which uses rollup, which supports x_google_ignoreList:

• https://github.com/preactjs/preact/blob/main/package.json#L109-L116
• https://github.com/developit/microbundle

  • The zero-configuration bundler for tiny modules, powered by Rollup

• https://rollupjs.org/configuration-options/#output-sourcemapignorelist

I'm not deeply familiar with microbundle and whether it allows passing through flags to rollup, or if it's something that would need to be enabled as part of their defaults.

[rschristian]

And Angular? Framework or 'UI library'? As they added support:

Take a look at where they added that change, it's in the Webpack config.

Angular is a framework as they have very specific underlying tooling -- you have to write Angular apps with Angular CLI (a Webpack-based tool, though I think that's changing?). This ties Angular to its framework rather tightly, compared to (say) React & Next, Vue and Nuxt, Svelte and SvelteKit, etc.

I've generally seen React/etc referred to colloquially as a framework as well; so I wouldn't be so quick to dismiss the relevance on semantic differences.

I'm not dismissing this due to semantic differences but due to actual intention. This is meant to be implemented in another layer of your tooling, a layer which UI libraries do not control.

I'm not deeply familiar with microbundle and whether it allows passing through flags to rollup, or if it's something that would need to be enabled as part of their defaults.

We maintain Microbundle.

[0xdevalias]

I'm not dismissing this due to semantic differences but due to actual intention.

Fair enough.

This is meant to be implemented in another layer of your tooling, a layer which UI libraries do not control.

I'm still not sure that that is correct. At the layer of preact, I believe it should mark itself to be ignored, so that shows in it's sourcemaps, so that then flows on to the sourcemaps of downstream projects that consume it's sourcemaps.

I may be wrong; and it seems that even if i'm not I'm unlikely to convince you otherwise, so I'll drop the point.

We maintain Microbundle

Fair enough. Well you may or may not find this issue relevant there then, since it's a bundler (though I'm not really sure how a thing like this that should be configurable would be exposed through a 'no config' tool):

• Add x_google_ignoreList (Ignore-listing code) support to sourcemaps developit/microbundle#1066

[rschristian]

At the layer of preact, I believe it should mark itself to be ignored, so that shows in it's sourcemaps, so that then flows on to the sourcemaps of downstream projects that consume it's sourcemaps.

Again, your Angular link is a great example here in usage:

for (const [index, path] of map.sources.entries()) {
    if (path.includes('/node_modules/') || path.startsWith('webpack/')) {
        ignoreList.push(index);
    }
}

As shown, this is happening in a Webpack plugin, during the user's app build. This isn't something that needs to flow on downstream, the consumer/framework can handle this perfectly well on their own.

Now, a good point of implementation could be create-preact, though it looks like Vite (which create-preact uses) might already implement this?

[0xdevalias]

Now, a good point of implementation could be create-preact, though it looks like Vite (which create-preact uses) might already implement this?

This is the relevant link on the vite docs, but that's seemingly for the dev server:

• https://vitejs.dev/config/server-options.html#server-sourcemapignorelist

  • server.sourcemapIgnoreList is the equivalent of build.rollupOptions.output.sourcemapIgnoreList for the dev server.

  • By default, it excludes all paths containing node_modules. You can pass false to disable this behavior, or, for full control, a function that takes the source path and sourcemap path and returns whether to ignore the source path.

  • Note: server.sourcemapIgnoreList and build.rollupOptions.output.sourcemapIgnoreList need to be set independently. server.sourcemapIgnoreList is a server only config and doesn't get its default value from the defined rollup options.

Looking at vite's rollup.config.ts, both envConfig and clientConfig seem to set sourcemapIgnoreList to true:

• https://github.com/vitejs/vite/blob/main/packages/vite/rollup.config.ts#L19-L56

Looking at rollup's docs for output.sourcemapIgnoreList, it seems this is a predicate for what to add to the ignore list, and can either be a boolean (that presumably globally enables/disables it), or a function returning a boolean:

• https://rollupjs.org/configuration-options/#output-sourcemapignorelist

So from that, it would seem that create-preact should already benefit from it, via the default specified in vite (which is the same sort of default that I thought/still think would make sense to set in microbundle; but at this stage I'm just accepting that I am potentially wrong and don't know what i'm talking about)

---

How about a case where the end-app isn't bundled/transpiled/etc, and thus has no chance to mark x_google_ignoreList for it's own dependencies; but is loading preact from a CDN. In that case, if preact directly set x_google_ignoreList in it's own sourcemap files, it would be correctly ignored listed; but since it doesn't, the end app can't benefit from that. Right?

And if that is true, then based on the above exploration, it seems that the solution for implementing the fix here would just be to set the output.sourcemapIgnoreList in the rollup config that is building the main preact outputs (via microbundle).

And then if that holds true, it also seems that it would probably similarly hold for many/most/all(?) libraries that use microbundle (that could be imported from a CDN/etc directly, and don't go through a transpilation/bundling step) as well?

It kind of feels like a case of "yes, implementing it at the bundler level is a nice 'catch-many' situation that avoids end libraries from having to do anything"; but I don't believe that negates it being a useful thing for an end library to implement directly? Again, could be wrong, and ultimately the decision is up to you and not something I'm going to push for/get upset if it's not done. Just trying to establish/understand/confirm if the assumptions that decision is based on are actually correct.

[0xdevalias]

How about a case where the end-app isn't bundled/transpiled/etc, and thus has no chance to mark x_google_ignoreList for it's own dependencies; but is loading preact from a CDN. In that case, if preact directly set x_google_ignoreList in it's own sourcemap files, it would be correctly ignored listed; but since it doesn't, the end app can't benefit from that. Right?

Rather than just throwing this out there as a question, I decided to test it. Creating a tiny test file that loads preact from https://unpkg.com/preact@latest/dist/preact.min.js:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Preact App</title>
  <script src="https://unpkg.com/preact@latest/dist/preact.min.js"></script>
</head>
<body>
  <div id="app"></div>
  <script>
    const { h, render, Component } = preact;

    class App extends Component {
      render() {
        return h('h1', null, 'Hello from Preact!');
      }
    }

    render(h(App), document.getElementById('app'));
  </script>
</body>
</html>

Looking at the 'Sources' tab, under 'Authored' -> 'unpkg.com', we can see that preact@latest/src is still shown, even when "Hide ignore-listed sources" is ticked:

Now if I edit that source to add a debugger statement in the render:

      class App extends Component {
        render() {
+         debugger;

          return h('h1', null, 'Hello from Preact!');
        }
      }
// ..snip..

We see that the full call stack is shown in the debugger, including all of the preact internals that aren't really relevant to my end-user app code:

Now I can work around this by manually configuring the ignore list in my Chrome DevTools and adding a rule such as this:

^https://unpkg\.com/preact@latest/src/

Which will 'dim' the preact@latest/src entry on the Sources tab when "Hide ignore-listed sources" is disabled:

And it won't show at all when "Hide ignore-listed sources" is ticked:

Now, repeating the debugger test from above with my manually added ignore rule, we can see that there is a new unchecked "show ignore-listed frames" checkbox, and all of the preact internals are no longer shown by default in the debugger call stack:

And then if I want to see the preact internals in this call stack for whatever reason, I can tick the "show ignore-listed frames" checkbox, and they will be visible to me (but dimmed to show that they're generally ignored):

Now while every developer who uses preact could go and manually configure those ignore rules in their individual DevTools each and every time, that's a lot of cumulative manual effort, which to my understanding, is why the x_google_ignoreList convention was added to sourcemaps, which allows 'frameworks' (in the general colloquial use of the term), or just 'libraries' in general, to emit this in their library sourcemaps, and have it automagically configured with no manual effort required for any downstream developers. At least, that is my understanding, which has been reinforced by the test I just did above.

Looking at the following page, they also specifically say "framework or library":

• https://developer.chrome.com/articles/x-google-ignore-list/#how-to-populate-ignorelist

  • If you are a framework or library maintainer, it's essential to understand how to implement these settings to improve your users debugging experience.

• https://developer.chrome.com/articles/x-google-ignore-list/#what-if-your-favorite-framework-and-build-tool-doesnt-support-it-yet

  • What if your favorite framework and build tool doesn’t support it yet?
    We actively work with frameworks and build tools to land these new settings. You can also help by notifying maintainers about this feature. For example, you can file an issue in their repository.

As I said earlier, if you still choose not to implement this here, that's fair enough; but I don't believe the reasoning you originally based that decision on holds true.