docs: add back docs about asar archives

[zcbenz]

Description of Change

Lots of informations about ASAR archives had been lost after #26239, this PR adds them back.

Release Notes

Notes: Add back documentations about asar archives.

[malept]

I think the idea was to put that info into the asar readme.

[BlackHole1]

Content LGTM

[RaisinTen]

Thanks! This is going to be very helpful for https://github.com/nodejs/single-executable. :)

[Prinzhorn]

The word "issues" was originally linked to nodejs/node-v0.x-archive#6960 . But hasn't this been fixed years ago (npm doesn't nest node_modules any longer)?

Electron also recommends bundling your code (https://www.electronjs.org/de/docs/latest/tutorial/performance#7-bundle-your-code), which also speeds up require (they're mostly gone) and "conceals" the source (by means of minification and mangling).

The reason why I'm bringing this up is that when I started with Electron I read this paragraph and couldn't find a single compelling reason to use ASAR (and I didn't), only problems (e.g. the Worker constructor didn't seem to be patched to add ASAR support).

Is there actually a real benefit of using ASAR? I'm curious if I'm missing out.

Summary:

1. Long path names haven't been an issue since 2015 (?)
2. There's no evidence linked that ASAR is faster than bundling (which is recommended anyway), maybe include a benchmark somewhere?
3. "conceal your source code from cursory inspection" is a really weak argument, if at all

So maybe this could be rewritten for 2022?

[zcbenz]

Bundlers are not good at handling assets as far as I know. For example you can not bundle image files and then serve them via protocol module, or execute a bundled python script with child_process. Of course you can work around them if your app is designed to work with bundlers from start, but ASAR is designed to work with arbitrary apps and package them into one single file.

But still I agree ASAR does not provide a real benefit than bundling, and this documentation means to list the limitations of ASAR instead of promoting it.

Node.js is going to work on a similar thing https://github.com/nodejs/single-executable, and we might want to use it as the default format in the end.

[Prinzhorn]

Thanks for clarifying. It sounds like you brought up some good points that should belong into the docs (maybe we could explicitly mention bundling and the pros and cons).

you can not bundle image files and then serve them via protocol module

For me they are bundled as part of the client bundle and I point @fastify/static (which is bundled in the server bundle) to the client/dist folder. But I understand not everyone is running an HTTP server. This works as expected for me:

import chromeProxySettings from '~/images/getting-started-chrome-proxy.png';
<img src={chromeProxySettings} alt="Chrome proxy settings" />

I don't see why the protocol module couldn't serve files from my client/dist folder as well.

or execute a bundled python script with child_process

I think ASAR makes that harder, not easier? Because depending on the circumstances you'd have to explicitly do something like asarUnpack (for electron-builder) for it to even work. I'm shipping a Python binary (via PyInstaller) with additional Python scripts and I don't have any problems so far using child_process.spawn.

[zcbenz]

Yeah this document needs an update, and actually the original PR that removed it was planning to move the document to the asar repo but somehow the effort ended nowhere.

This PR means to bring back the deleted page since it contains important information that currently can not be found on Internet, we might delete it later after getting a renewed documentation in the asar repo.

[erickzhao]

I think the idea was to put that info into the asar readme.

As @malept mentioned, I do think this was the case. Do we feel like this belongs better in the Electron docs?

[erickzhao]

Note: we don't really use this README on the website anymore at all!

[zcbenz]

As @malept mentioned, I do think this was the case. Do we feel like this belongs better in the Electron docs?

I agreed the docs should be moved to the asar repo, but somehow the effort ended no where. I would like to recover the docs first since it contains important information that can not be found on Internet anymore. We can delete this doc after having all necessary information in the asar repo.

[ckerr]

I don't have an opinion on where the docs go, but if I'm understanding the discussion here the documentation currently isn't available at all! For that reason, whether or not e/e docs/ is the end goal, I'm 👍 on merging this to at least get it documented somewhere

[jkleinsc]

Merging as CI failure unrelated to PR change.

[release-clerk]

Release Notes Persisted

Add back documentations about asar archives.

[trop]

I have automatically backported this PR to "19-x-y", please check out #35665

[trop]

I have automatically backported this PR to "20-x-y", please check out #35666

[trop]

I have automatically backported this PR to "21-x-y", please check out #35667