What is the purpose of buildResources folder in electron-builder building process?

Question

I'm reading through electron and electron-builder docs, but I still do not quite understand what is the purpose of the buildResources folder?

Here's what a configuration doc for electron-builder says:

buildResources = build String - The path to build resources.

Kind of self-explanatory... But how or when they are involved in the build process, especially having that:

...build resources is not packed into the app. If you need to use some files, e.g. as tray icon, please include required files explicitly

Can we simply put those icon files in an arbitrary folder and then copy over into the app/ manually (since we need to include buildResources manually anyway)?

Answer 1

TL;DR:

As far as I can tell from a quick glance at the source code, the buildResources folder is used to hold additional scripts, plugins, etc. that can be used by the package building software. Electron-builder doesn't generate the packages itself, it uses tools like NSIS.

Explanation:

I've had the same question and unfortunately find an answer for this isn't very straight-forward. The docs entry is pretty useless. I found out that someone asked about it in the GitHub issues but never got an answer.

I decided to dig in the code a bit myself to find out what it does. In NsisTargets.ts, you can see that the buildResources folder can contain custom includes and plugins for NSIS.

// NsisTargets.ts
taskManager.add(async () => {
      const userPluginDir = path.join(packager.info.buildResourcesDir, pluginArch)
      const stat = await statOrNull(userPluginDir)
      if (stat != null && stat.isDirectory()) {
        scriptGenerator.addPluginDir(pluginArch, userPluginDir)
      }
    })

// [...]

taskManager.add(async () => {
        const customInclude = await packager.getResource(this.options.include, "installer.nsh")
        if (customInclude != null) {
          scriptGenerator.addIncludeDir(packager.info.buildResourcesDir)
          scriptGenerator.include(customInclude)
        }
      })

and in pkg.ts it's used to load additional scripts to the pkg builder:

// pkg.ts
if (options.scripts != null) {
      args.push("--scripts", path.resolve(this.packager.info.buildResourcesDir, options.scripts))
    }

It appears as though buildResources can contain assets/scripts specifically used for the build process. That also explains why the contents of buildResources aren't included in the resulting app.asar file.

Answer 2

So, I'm going to say straight away that the documentation for this option is just awful.

Files included in buildResources will appear in the asar file which you can find documentation about on electron's website.

The option files will include files such as pictures which are not accessible in the asar file.

I.E.

given I have a folder called assets in my build folder I want to include with my app.

"files": [
  "./build/**/*"
],
"directories": {
  "buildResources": "assets"
}

This will put all folders inside build into the asar file, which you can then unpack by including,

"asarUnpack": "**/assets/*"

This will put the folder assets into the build folder in the app directory.