Make "onboarding" as easy as it is in the Debugger for Chrome

[jnachtigall]

This started as a bug report with the title: "Unverified Breakpoing" with webpack's 'eval-source-map' but after lots of time I could resolve the issue and hence renamed it...

I know this is OpenSource and I am grateful for this VSCode plugin. So really, Thank you so much :) Take this like kind of a user feedback.

old stuff:

I do not know if I am too stupid to set up vscode-firefox-debug correctly or if it is really a bug.

Anyway with Chrome and this config it works out-of-the-box:

    {
      "type": "chrome",
      "request": "attach",
      "name": "Attach to Chrome",
      "port": 9222,
      "webRoot": "${workspaceFolder}"
    },

But with Firefox (Nightly 59) it does not work:

    {
      "name": "Attach to Firefox",
      "type": "firefox",
      "request": "attach",
      "url": "http://localhost/",
      "webRoot": "${workspaceFolder}",
      "pathMappings": [
        {
          "url": "webpack:///",
          "path": "${webRoot}"
        }
      ],
      "sourceMaps": "client",
      "log": {
        "fileName": "${workspaceFolder}/ff-debugger-log.txt",
        "fileLevel": {
          "default": "Debug"
        }
        // "consoleLevel": {
        //   "PathConversion": "Debug",
        //   "default": "Error"
        // }
      }
    },

I looked into the log file but could not find an Error regarding the pathMapping. Here's some excerpt from the log:

DEBUG|001.061|DebugConnection: Received response/event {"from":"server1.conn1.child1/tab1","type":"newSource","source":{"actor":"server1.conn1.child1/source28","generatedUrl":null,"url":"http://localhost/js/app.bundle.js","isBlackBoxed":false,"isPrettyPrinted":false,"isSourceMapped":false,"sourceMapURL":null,"introductionUrl":null,"introductionType":"scriptElement"}}
DEBUG|001.061|TabActorProxy: Ignored newSource event from tab server1.conn1.child1/tab1
DEBUG|001.061|DebugConnection: Received response/event {"from":"server1.conn1.child1/context25","type":"newSource","source":{"actor":"server1.conn1.child1/source28","generatedUrl":null,"url":"http://localhost/js/app.bundle.js","isBlackBoxed":false,"isPrettyPrinted":false,"isSourceMapped":false,"sourceMapURL":null,"introductionUrl":null,"introductionType":"scriptElement"}}
DEBUG|001.061|ThreadActorProxy: New source http://localhost/js/app.bundle.js on thread server1.conn1.child1/context25
DEBUG|001.061|SourceMappingThreadActorProxy: Trying to sourcemap {"actor":"server1.conn1.child1/source28","generatedUrl":null,"url":"http://localhost/js/app.bundle.js","isBlackBoxed":false,"isPrettyPrinted":false,"isSourceMapped":false,"sourceMapURL":null,"introductionUrl":null,"introductionType":"scriptElement"}


DEBUG|001.061|PathConversion: Converted url http://localhost/js/app.bundle.js to path c:\Users\jnachtigall\Devel\BPA\dxp-blueprint\modules\frontend\themes\relaunch-theme\js\app.bundle.js
DEBUG|001.061|SkipFilesManager: skipFile is not set for c:\Users\jnachtigall\Devel\BPA\dxp-blueprint\modules\frontend\themes\relaunch-theme\js\app.bundle.js

DEBUG|001.284|PathConversion: Converted url webpack:///src/components/app.js?3ced to path c:\Users\jnachtigall\Devel\BPA\dxp-blueprint\modules\frontend\themes\relaunch-themesrc\components\app.js
DEBUG|001.284|SkipFilesManager: skipFile is not set for c:\Users\jnachtigall\Devel\BPA\dxp-blueprint\modules\frontend\themes\relaunch-themesrc\components\app.js

...5min later...

Damn it, the message shows me the error:

skipFile is not set for c:\Users\jnachtigall\Devel\BPA\dxp-blueprint\modules\frontend\themes\relaunch-themesrc\components\app.js

It should be \relaunch-theme\src\ and not \relaunch-themesrc\. So I changed the pathMapping's "path": "${webRoot}/" to including a trailing slash /.

Now it works. Long story short: I know this is an OpenSource project and I am very thankful for it, really.

In the end I think two things could be better here:

• Better error message like that the particular file cannot be found under the given path on the local filesystem. (the skipFile is actually for something else like a "Skipping this file" setting)
• Having a setup working more or less out-of-the-box like the Chrome Debugger does would help a lot.

[hbenl]

Yeah, I agree that configuring this adapter for webpack projects is error-prone. Since webpack has become so widely used I guess I should include the pathMappings for webpack by default (like the Chrome debug adapter does). I will add this to the next release. Perhaps I can also improve how path mapping errors are detected and reported.

Silghtly off-topic: I see that you use "sourceMaps": "client" in your configuration and would like to know why. I'm asking because I wonder if I should also make this the new default - I will probably have to do so at some point anyway (because I guess that the server-side implementation of sourcemaps will eventually be removed from Firefox), but so far I kept the old default because I don't trust my own implementation of sourcemaps support as much as that included in Firefox.

[jnachtigall]

Yeah, I agree that configuring this adapter for webpack projects is error-prone. Since webpack has become so widely used I guess I should include the pathMappings for webpack by default (like the Chrome debug adapter does). I will add this to the next release.

Thanks for considering! Yes, this would be awesome 👍 Most people use webpack without knowing. Either by using one of the zero-configuration starter kits or using build tools configured by someone else. For instance, I maintain our webpack+grunt based build tools and all my colleagues just do npm start or npm run build, so using webpack without knowing. For them it is really hard (even for me) to cope with webpack:/// and pathMappings.

In the end if the Firefox VSCode Adapter would work with webpack (and the above mentioned starter kits) this would work for 99% of use cases.

Maybe also supporting rollup ootb would be great since it is the second greatest option when it comes to building JS these days, at least when building js libaries: https://medium.com/webpack/webpack-and-rollup-the-same-but-different-a41ad427058c

Perhaps I can also improve how path mapping errors are detected and reported.

One idea I'd have is that a typical VSCode notification message on top of VSCode (like when there's a new release or something else) could pop up like SourceMapped JS files cannot be mapped from remote x/y/z to local a/b/c. Breakpoints probably will not work. Please read here on how to fix this. Something along these lines...

Silghtly off-topic: I see that you use "sourceMaps": "client" in your configuration and would like to know why. I'm asking because I wonder if I should also make this the new default - I will probably have to do so at some point anyway (because I guess that the server-side implementation of sourcemaps will eventually be removed from Firefox), but so far I kept the old default because I don't trust my own implementation of sourcemaps support as much as that included in Firefox.

Well, I was looking for a reason why the source mappings did not work and found your comment at #44 (comment) Since I am also using Firefox Nightly and the new Firefox Debugger.html frontend I thought that using client is probably the better option (without still knowing if this is really "better").

but so far I kept the old default because I don't trust my own implementation of sourcemaps support as much as that included in Firefox.

Can't you share/reuse code with Debugger.html on this? Totally agree, that having to maintain your own implementation here is really error-prone. As I see it Debugger.html was really setup to be built in a component based way and I'd guess that there community is really open for something like this.

[hbenl]

Maybe also supporting rollup ootb would be great

Thanks for pointing this out, I'll have a look at this (I've heard of rollup but have no experience with it, I'll have to find out what kind of pathMappings it needs, if any)

Concerning your suggestion that the debug adapter should warn the user whenever a source can't be mapped to a local file: the problem is that this situation occurs in many setups even if the pathMappings are correct - for example, webpack bundles contain several generated scripts that do not correspond to any local files...

But I've had another idea how to make configuring pathMappings easier and already wrote a prototype. Watch this:

Of course I will still add the pathMappings for webpack by default.

Can't you share/reuse code with Debugger.html on this?

I am using the source-map npm library which does almost all the work for me, so it's not like I had to write a lot of code for this. However, even something as seemingly simple as extracting the sourceMapURL from a script (which I have to do myself) is surprisingly error-prone: I've seen several examples of scripts that embed the sourceMapURL in a way that is similar to but different from what the standard proscribes. Apparently a lot of people don't read the standards, they just try it with the Chrome debugger and if it works there they assume that it has to work in every debugger... and that's just one example for the subtleties where things can go wrong...

[jnachtigall]

Thank you!

I've heard of rollup but have no experience with it, I'll have to find out what kind of pathMappings it needs, if any

For a minimal working example for rollup you could use the repo linked at firefox-devtools/debugger#4799 (comment) (I found a bug for this with the new debugger.html, so rollup is definitely doing something different). OTOH, this is grunt+rollup, so probably not the 99% defaults setup...

Then there's also https://github.com/rollup/rollup-starter-lib and https://github.com/rollup/rollup-starter-app (these are linked from https://rollupjs.org/#quick-start so I guess most developers will use these)

[hbenl]

I have now added the default pathMappings for webpack. I'm planning to do the feature shown above (adding pathMappings from the Loaded Scripts Explorer) next and will also look at rollup.