To mitigate issues around long path names on Windows, slightly speed up and conceal your source code from cursory inspection, you can choose to package your app into an asar archive with little changes to your source code.
Most users will get this feature for free, since it's supported out of the box by , , and . If you are not using any of these tools, read on.
An asar archive is a simple tar-like format that concatenates files into a single file. Electron can read arbitrary files from it without unpacking the whole file.
Steps to package your app into an archive:
In Electron there are two sets of APIs: Node APIs provided by Node.js and Web APIs provided by Chromium. Both APIs support reading files from archives.
With special patches in Electron, Node APIs like and treat archives as virtual directories, and the files in it as normal files in the filesystem.
For example, suppose we have an archive under :
Read a file in the archive:
List all files under the root of the archive:
Use a module from the archive:
You can also display a web page in an archive with :
In a web page, files in an archive can be requested with the protocol. Like the Node API, archives are treated as directories.
For example, to get a file with :
Treating an Archive as a Normal File
For some cases like verifying the archive's checksum, we need to read the content of an archive as a file. For this purpose you can use the built-in module which provides original APIs without support:
You can also set to to disable the support for in the module:
Limitations of the Node API
Even though we tried hard to make archives in the Node API work like directories as much as possible, there are still limitations due to the low-level nature of the Node API.
Archives Are Read-only
The archives can not be modified so all Node APIs that can modify files will not work with archives.
Working Directory Can Not Be Set to Directories in Archive
Though archives are treated as directories, there are no actual directories in the filesystem, so you can never set the working directory to directories in archives. Passing them as the option of some APIs will also cause errors.
Extra Unpacking on Some APIs
Most APIs can read a file or get a file's information from archives without unpacking, but for some APIs that rely on passing the real file path to underlying system calls, Electron will extract the needed file into a temporary file and pass the path of the temporary file to the APIs to make them work. This adds a little overhead for those APIs.
APIs that requires extra unpacking are:
- - Used by on native modules
Fake Stat Information of
The object returned by and its friends on files in archives is generated by guessing, because those files do not exist on the filesystem. So you should not trust the object except for getting file size and checking file type.
Executing Binaries Inside Archive
There are Node APIs that can execute binaries like , and , but only is supported to execute binaries inside archive.
This is because and accept instead of as input, and s are executed under shell. There is no reliable way to determine whether a command uses a file in asar archive, and even if we do, we can not be sure whether we can replace the path in command without side effects.
Adding Unpacked Files to Archives
As stated above, some Node APIs will unpack the file to the filesystem when called. Apart from the performance issues, various anti-virus scanners might be triggered by this behavior.
As a workaround, you can leave various files unpacked using the option. In the following example, shared libraries of native Node.js modules will not be packed:
After running the command, you will notice that a folder named was created together with the file. It contains the unpacked files and should be shipped together with the archive.