patch-asar/README.md

Patch .asar archives

# Patch Asar
Using this library you can inject your own files into .asar archives.

## Breaking Change
I don't know if switching from CommonJS to ESModules will break this library for anyone. If this is an issue for you please open an issue and I'll try to figure out how to build for both (or make a pull request with a proper build system)

### Basic Usage
```js
import patchAsar from 'patch-asar'
import {join} from 'path'

const inputAsar = join(__dirname, "input.asar")
const patchFolder = join(__dirname, "patches")

await patchAsar(inputAsar, patchFolder)

console.log("Successfully Patched .asar archive in place")
```

### Passing Additional Options
You can supply an object as the third argument to supply additional options.
```js
...
await patchAsar(inputAsar, patchFolder, {outputFile: join(__dirname, 'output.asar')})
...
```

#### Available Options
##### outputFile
The output .asar file path. If this option is not provided it will overwrite the original .asar file.
##### workingDirectory
Allows you to specify the directory you would like the library to work in

##### beforeFinishPatching
This allows you to specify a function to be called after patch-asar is done patching an asar file, but has not written it to the final .asar file yet. You must return a promise (for patch-asar to wait on) or the literal value true (to designate it's a sync function). The input to the function is patch-asar's working directory so you can edit the files within your node.js runtime. This has the added benefit of being able to use your own dependencies compared to .patch-execute files which do not support dependencies.

### .patch-execute files
A file ending in .patch-execute will be evaluated as Javascript in order to generate it's contents. The .patch-execute extension will be removed automatically during the build process. It should either export a string, or a function returning a string, or a promise returning a string. If you return a function while theres another file with the same name except without .patch-execute then the contents of the file will be passed in as a string input to your function. This can be very useful in order to generate the contents of the patched file based on the contents of the unpatched file and the code you provide in your .patch-execute file.

### Command-line Interface

This library also provides a command-line executable alongside this package.

To use the CLI, install this package globally (e.g. using `npm install -g`). Then run:

```shell
patch-asar IN.asar PATCHDIR OUT.asar
```

The output .asar file is optional; omit it in order to overwrite the input .asar file:

```shell
patch-asar IN.asar PATCHDIR
```