Improve debugging experience by publishing source files to npm

[justingrant]

immer doesn't publish its source code files to npm. This makes debugging harder because the pre-compilation source code isn't available (e.g. to set breakpoints) unless the app is running. It can also cause breakpoint locations to shift around from one debugging session to another. The original source is present in the inline sourcemaps (good!) but also having source files would definitely improve the debug experience.

Usually missing source is caused by the source folder being included in .npmignore, but I didn't see an .npmignore file in the immer repo so I'm not sure why the source isn't being published.

[justingrant]

Oops, meant to make this a feature request, not a bug report!

[mweststrate]

Can you explain how source files are going to help? they won't be picked up by the browser so you can't set breakpoints in them. Op zo 17 mrt. 2019 06:34 schreef Justin Grant <notifications@github.com>:

…

Oops, meant to make this a feature request, not a bug report! — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#335 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABvGhL7g3w_NAn2uC8Tk3hfgfLXrbV8gks5vXdP5gaJpZM4b4MUd> .

[aleclarson]

Usually missing source is caused by the source folder being included in .npmignore, but I didn't see an .npmignore file in the immer repo so I'm not sure why the source isn't being published.

See here:

https://github.com/mweststrate/immer/blob/8b33b9882e3c0981e04ee3cd1edd7a9d774612e7/package.json#L41-L43

This makes debugging harder because the pre-compilation source code isn't available (e.g. to set breakpoints) unless the app is running.

You can set the breakpoints in dist/immer.js and your debugger should carry those over to the virtual source files created from the source map. I've never had issues with this.

It can also cause breakpoint locations to shift around from one debugging session to another.

Not sure why that would happen, but I don't think I've ever experienced this.

[justingrant]

Can you explain how source files are going to help? they won't be picked up
by the browser so you can't set breakpoints in them.

@mweststrate - the main case where this matters is IDEs like VS Code which operate primarily with offline files. You can set a breakpoint in the original source and it will work at runtime... but only if the original source is there! Although I've never used it, I believe that Chrome also has a file-based mode too (this allows devs to edit their code directly in Chrome) which would be impacted too, but I don't think that mode is used much compared with the IDE case.

I'd be happy to send a PR for this if you think it'd be useful (now that @aleclarson showed me how to do it!)

It can also cause breakpoint locations to shift around from one debugging session to another.

Not sure why that would happen, but I don't think I've ever experienced this.

@aleclarson - I see this frequently. I think that the culprit may be hot reloading combined with limitations in Chrome DevTools and/or VS Code, but the impact is that breakpoints stick to the "old" locations which, if the breakpoint was in transpiled code, may not correspond to the same place in the original source after it's been modified and hot-reloaded. I suspect this is made worse by build pipelines that have multiple transpilation steps, but I have no proof of that theory. ;-)

I also see cases where there are ghost breakpoints that were removed from the original source earlier in the debug session but, again due to changes in transpilation and/or hot reloading, aren't removed from the transpiled code. The effect is annoying: execution stops in the IDE and some random line of code is highlighted, and then you have to go hunting through the breakpoints list to find the culprit.

These issues may be less common in library code (because it's not being changed alot if you're not actually building the library yourself), but I don't fully understand the problem so can't be sure.

You can set the breakpoints in dist/immer.js and your debugger should carry those over to the virtual source files created from the source map. I've never had issues with this.

Yep, this works as a backup but I do find it easier with transpiled libraries to work with the original source. That said, Immer is much less of a problem than libraries that use a lot of newer ES features like async/await where the transpiled code is really hard to follow.

[aleclarson]

... much less of a problem than libraries that use a lot of newer ES features like async/await where the transpiled code is really hard to follow.

😆 The transpiled async/await generators kill me every time..

I'd be happy to send a PR for this if you think it'd be useful

I say go for it. 🚀

Let's get sourcesContent removed if we can, to reduce impact on tarball size.

[mweststrate]

@justingrant when creating a PR, could you record a screencast on how it improves things? I'm pretty curious on how these tools would pick up arbitrary source files

[aleclarson]

@mweststrate In the case of VS Code, you would open the source file by navigating (via the file tree) into node_modules/immer/src and then set a breakpoint there.

[mweststrate]

really, how is that matched against the files that are actually being loaded from dist by the running program?! Sounds magical :)

…

On Mon, Mar 18, 2019 at 12:47 PM Alec Larson ***@***.***> wrote: @mweststrate <https://github.com/mweststrate> In the case of VS Code, you would open the source file by navigating (via the file tree) into node_modules/immer/src and setting a breakpoint there. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#335 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABvGhDz6OkuPZ0JsaZl-OeJblHG3UkLoks5vX3zIgaJpZM4b4MUd> .

[aleclarson]

The magic of source maps ;)

[mweststrate]

Aren't those self-containing atm?

…

On Mon, Mar 18, 2019 at 3:36 PM Alec Larson ***@***.***> wrote: The magic of source maps ;) — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#335 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABvGhDeWiYOnfFTHlBKXlGJu1oOasRvbks5vX6RegaJpZM4b4MUd> .

[aleclarson]

If by "self-containing" you mean the source maps contain the source code (via the sourcesContent array), then yes. The sources array also exists, which is used to find the external source files. The proposal here is to (1) publish the external source files and (2) remove the sourcesContent array from the source maps (to avoid increased tarball size).

[aleclarson]

@egoist How can we tell Bili to exclude sourcesContent from the generated source maps?

[egoist]

@aleclarson starting from bili 4.6.0 you can use --map-exclude-sources flag or set output: { sourceMapExcludeSources: true } in config file.

[justingrant]

Thanks @aleclarson you beat me to it! ;-)

[aleclarson]

🎉 This issue has been resolved in version 2.1.4 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀