Application Packaging
To mitigate issues around long path names on Windows, slightly speed up require 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.
Generating asar Archive
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 asar archive:
1. Install the asar Utility
2. Package with asar pack
Using asar Archives
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 asar archives.
Node API
With special patches in Electron, Node APIs like fs.readFile and require treat asar archives as virtual directories, and the files in it as normal files in the filesystem.
For example, suppose we have an example.asar archive under /path/to :
Read a file in the asar 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 asar archive with BrowserWindow :
Web API
In a web page, files in an archive can be requested with the file: protocol. Like the Node API, asar archives are treated as directories.
For example, to get a file with $.get :
Treating an asar Archive as a Normal File
For some cases like verifying the asar archive’s checksum, we need to read the content of an asar archive as a file. For this purpose you can use the built-in original-fs module which provides original fs APIs without asar support:
You can also set process.noAsar to true to disable the support for asar in the fs module:
Limitations of the Node API
Even though we tried hard to make asar 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 asar archives.
Working Directory Can Not Be Set to Directories in Archive
Though asar archives are treated as directories, there are no actual directories in the filesystem, so you can never set the working directory to directories in asar archives. Passing them as the cwd option of some APIs will also cause errors.
Extra Unpacking on Some APIs
Most fs APIs can read a file or get a file’s information from asar 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:
- child_process.execFile
- child_process.execFileSync
- fs.open
- fs.openSync
- process.dlopen — Used by require on native modules
Fake Stat Information of fs.stat
The Stats object returned by fs.stat and its friends on files in asar archives is generated by guessing, because those files do not exist on the filesystem. So you should not trust the Stats object except for getting file size and checking file type.
Executing Binaries Inside asar Archive
There are Node APIs that can execute binaries like child_process.exec , child_process.spawn and child_process.execFile , but only execFile is supported to execute binaries inside asar archive.
This is because exec and spawn accept command instead of file as input, and command 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 in asar Archive
As stated above, some Node APIs will unpack the file to filesystem when calling, apart from the performance issues, it could also lead to false alerts of virus scanners.
To work around this, you can unpack some files creating archives by using the —unpack option, an example of excluding shared libraries of native modules is:
.ASAR File Extension
.ASAR file extension is created by GitHub. .ASAR has been classified as Developer Files. The format of .ASAR file is Binary.
.ASAR is Electron Archive
An ASAR file is an archive used to package source code for an application using Electron, an open source library used to build cross-platform programs. It is saved in a format similar to .TAR archives where files contained in the archive, such as .HTML, .JS, and .CSS files, are concatenated together without using compression.
ASAR files allow developers to package their apps in an archive instead of a folder, which protects the source code of the app from being exposed to other users. You can package the application into an archive using the asar utility included with Electron.
@electron/asar — Electron Archive
Asar is a simple extensive archive format, it works like tar that concatenates all files together without compression, while having random access support.
Features
- Support random access
- Use JSON to store files’ information
- Very easy to write a parser
Command line utility
Install
This module requires Node 10 or later.
Usage
Excluding multiple resources from being packed
Exclude: a, b, d, f
Exclude: a, b, d, f, h
Using programatically
Example
Please note that there is currently no error handling provided!
Transform
You can pass in a transform option, that is a function, which either returns nothing, or a stream.Transform . The latter will be used on files that will be in the .asar file to transform them (e.g. compress).
Using with grunt
There is also an unofficial grunt plugin to generate asar archives at bwin/grunt-asar.
Format
Asar uses Pickle to safely serialize binary value to file.
The format of asar is very flat:
The header_size and header are serialized with Pickle class, and header_size ‘s Pickle object is 8 bytes.
The header is a JSON string, and the header_size is the size of header ‘s Pickle object.
Structure of header is something like this:
offset and size records the information to read the file from archive, the offset starts from 0 so you have to manually add the size of header_size and header to the offset to get the real offset of the file.
The Simplest and Most Powerful Archive File Format Ever Made
.asar is a simple .tar-like archive format with impressive features.
When the file count is increasing, file management is a bit complex and time-consuming. Archive file formats are helping us to create a single file by merging multiple files and directories. Therefore, for users, they can make one file from a set of rarely accessed files. Whenever they need to access the files, they can extract them as typical files and directories. For developers, they can make a single file for storing resources rather than storing all resources separately on disk. That will make the particular software more portable and easy to share as well.
Last week, I was looking for an archive file format to store application resources. Application resources were just a bunch of JavaScript files and graphics. I had some strict requirements for the expected archive format: random access support, extracting data without a third-party library, and an uncompressed structure.
I found that the .asar archive format exactly matches my requirements. If you are looking for a simple but powerful archive format, .asar is indeed the option for you.
.asar internals
The entire structure is a piece of cake. .asar has the following internal format.
header_size is an 8-bit binary data segment that stores the size of the header segment. The header segment stores the directory tree of all stored files in JSON format. After that, it’s all about the content of the concatenated files like the .tar archive format.
The header’s JSON structure looks like shown below.
If the particular element is a directory, it has the files attribute with its child contents. If there is a file, it will contain two properties: offset for indexing, and size attribute for the size of the file.