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

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.

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.