Interface: FilesBuildOptions

Which files are copied into the packaged app, which file extensions are excluded from it, and which symlinks among them may lead outside it, set under fileOptions at the configuration root or per platform (e.g. mac.fileOptions). A platform's file lists are added to the root ones; a platform's excludedExts and allowExternalLinks replace the root ones. See file options.

Properties

allowExternalLinks?

optional allowExternalLinks?: boolean | string[] | null

Whether symlinks among the packaged files may lead outside the app, the workspace and the package-manager store.

Only the build configuration is trusted, not the files it packages: by default (false) electron-builder refuses

• a file of the app (app.asar or asar: false) that is a symlink, or is reached through one, whose real path is outside the workspace root, the project and app directories and the package-manager store (npm link, a file:../lib dependency outside the repository, a symlink into the home or temp directory),
• a copied symlink that resolves outside the app: one in extraResources / extraFiles (other than into the workspace or the store), one kept by an asar: false copy, and any symlink leaving the app in a target that stores what symlinks point to (Windows zip / 7z, the NSIS app package, AppX/MSIX, Squirrel.Windows).

Without these checks, a symlink planted in a dependency or a copied directory could package files from elsewhere on the build machine (SSH keys, credentials) into the artifact, which is why this is off by default.

• true allows any such symlink.
• A list of paths, relative to the project directory or absolute, allows a symlink only when the real path of what it points to is inside the real path of one of them (e.g. ["../shared-lib"]). A listed path that does not exist fails the build.

An allowed symlink is packaged: what it points to is copied (or stored by the archive), and a copied symlink is kept as it is. A warning is logged once when this allows a symlink.

Set it under fileOptions, at the configuration root or per platform; a platform's value (false included) replaces the root one rather than being added to it:

{ "fileOptions": { "allowExternalLinks": ["../shared-lib"] }, "linux": { "fileOptions": { "allowExternalLinks": true } } }

This does not allow writing through a symlink: a copy or a file written by electron-builder whose destination leads outside the output directory through a symlink is always refused, and a symlink at such a file name is replaced, never followed. See Symbolic links.

Default

false

---

excludedExts?

optional excludedExts?: string | string[] | null

File extensions (without the leading dot) excluded from the packaged app files and the copied node_modules.

• "default" expands to the built-in list of excluded extensions (see the table below).
• Any other entry adds that extension, e.g. "map".
• An entry starting with ! removes that extension from the others listed, e.g. ["default", "!pdb"] to keep .pdb (Program Database) symbol files for Windows crash-dump analysis. .pdb files contain symbol names and the source paths of the build machine: keep them only in internal builds or builds for a symbol server, or upload them to a symbol server instead of shipping them. A list of removals only, such as ["!pdb"], is rejected because it would exclude no extension at all: write ["default", "!pdb"]. A "!ext" in a list that does not otherwise list that extension (e.g. ["map", "!pdb"]) has no effect and logs a warning.

The built-in list ("default"):

Extension	Typically used for
.iml	IntelliJ IDEA / WebStorm module file
.hprof	Java heap dump
.orig	Original copy of a file, left behind by merge tools and patch
.pyc	Compiled Python bytecode
.pyo	Optimized compiled Python bytecode (Python 2)
.rbc	Compiled Ruby bytecode (Rubinius)
.swp	Vim swap file
.csproj	C# (MSBuild) project file
.sln	Visual Studio solution file
.slnx	Visual Studio XML solution file
.suo	Visual Studio solution user options
.xproj	.NET Core project file (Visual Studio 2015)
.cc	C++ source file, e.g. of a native module
.d.ts	TypeScript declaration file
.mk	Makefile fragment generated by node-gyp
.a	Static library archive from a native build
.o	Object file from a native build
.obj	Object file from an MSVC native build; also used for Wavefront 3D models, which a files pattern can re-include
.forge-meta	Metadata @electron/rebuild writes next to a rebuilt native module
.pdb	Program Database: Windows debug symbols, with symbol names and the build machine's source paths

The list replaces the defaults: list "default" to extend them rather than replace them. null (or omitting it) is ["default"], and an empty array [] excludes no extension.

An invalid list (an entry that is not a file extension, "!default", or removals only) fails the build when the configuration is validated, at the root and in every platform section, before anything is packed.

{ "fileOptions": { "excludedExts": ["default", "!pdb", "map"] } }

Set it under fileOptions, at the configuration root or per platform. Unlike the other lists, a later list replaces an earlier one rather than being merged with it. For the root and for each platform section, the last layer that sets the list wins: the extends parents in order, then the configuration file, then the programmatic or -c configuration. For the mas and mas-dev targets, a mas list then replaces the mac one, and a masDev list (for mas-dev) replaces both. A platform's list then replaces the root one, whichever layer set either. A null value keeps the earlier list.

A files pattern that names an excluded extension includes only the app files it matches: **/*.obj every .obj file outside node_modules and the build resources and output directories, models/teapot.obj only that file.

A single entry may be given as a string, e.g. on the command line: -c.fileOptions.excludedExts=default. For several entries, repeat the flag: -c.fileOptions.excludedExts=default -c.fileOptions.excludedExts=!pdb (in an interactive bash or zsh, write the second one as '-c.fileOptions.excludedExts=!pdb', single-quoted, so that !pdb is not expanded).

Default

["default"]

---

extraFiles?

optional extraFiles?: string | FileSet | (string | FileSet)[] | null

The same as extraResources but copy into the app's content directory (Contents for MacOS, root directory for Linux and Windows).

---

extraResources?

optional extraResources?: string | FileSet | (string | FileSet)[] | null

A glob patterns relative to the project directory, when specified, copy the file or directory with matching names directly into the app's resources directory (Contents/Resources for MacOS, resources for Linux and Windows).

File patterns (and support for from and to fields) the same as for files.

---

files?

optional files?: string | FileSet | (string | FileSet)[] | null

A glob patterns relative to the app directory, which specifies which files to include when copying files to create the package.

Defaults to:

[
"**/*",
"!**/node_modules/*/{CHANGELOG.md,README.md,README,readme.md,readme}",
"!**/node_modules/*/{test,__tests__,tests,powered-test,example,examples}",
"!**/node_modules/*.d.ts",
"!**/node_modules/.bin",
"!**/*.{iml,o,hprof,orig,pyc,pyo,rbc,swp,csproj,sln,slnx,xproj}",
"!.editorconfig",
"!**/._*",
"!**/{.DS_Store,.git,.hg,.svn,CVS,RCS,SCCS,.gitignore,.gitattributes}",
"!**/{__pycache__,thumbs.db,.flowconfig,.idea,.vs,.nyc_output}",
"!**/{appveyor.yml,.travis.yml,circle.yml}",
"!**/{npm-debug.log,yarn.lock,.yarn-integrity,.yarn-metadata.json}"
]

Development dependencies are never copied in any case. You don't need to ignore it explicitly. Hidden files are not ignored by default, but all files that should be ignored, are ignored by default.

Default pattern **/* is not added to your custom if some of your patterns is not ignore (i.e. not starts with !). package.json and **/node_modules/**/* (only production dependencies will be copied) is added to your custom in any case. All default ignores are added in any case — you don't need to repeat it if you configure own patterns.

May be specified in the platform options as well (e.g. mac.fileOptions.files, see mac).

You may also specify custom source and destination directories by using FileSet objects instead of simple glob patterns.

[
{
 "from": "path/to/source",
 "to": "path/to/destination",
 "filter": ["**/*", "!foo/*.js"]
}
]

You can use file macros in the from and to fields as well. from and to can be files and you can use this to rename a file while packaging.