From dd33c9d623d73ab43464356c88be82e84cf0e3dc Mon Sep 17 00:00:00 2001 From: Mark Lee Date: Wed, 12 Feb 2020 16:42:57 -0800 Subject: [PATCH 1/2] feat: add TypeScript definition (#1131) Based on `@types/electron-packager`, it's updated for 14.2.1. It replaces `docs/api.md` as the canonical API documentation. --- .circleci/config.yml | 4 +- .eslintrc.js | 32 +++ .eslintrc.typescript.js | 13 + CONTRIBUTING.md | 2 +- docs/api.md | 521 --------------------------------------- package.json | 50 ++-- src/index.d.ts | 527 ++++++++++++++++++++++++++++++++++++++++ test/index.test-d.ts | 185 ++++++++++++++ 8 files changed, 776 insertions(+), 558 deletions(-) create mode 100644 .eslintrc.js create mode 100644 .eslintrc.typescript.js delete mode 100644 docs/api.md create mode 100644 src/index.d.ts create mode 100644 test/index.test-d.ts diff --git a/.circleci/config.yml b/.circleci/config.yml index 2b83c6d7..4c5bf020 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -37,7 +37,9 @@ steps-ci: &steps-ci - *step-restore-electron-cache - run: test/ci/_before_script.js - *step-save-electron-cache - - run: npm test + - run: npm run lint + - run: npm run tsd + - run: npm run coverage - run: npm run codecov version: 2.1 diff --git a/.eslintrc.js b/.eslintrc.js new file mode 100644 index 00000000..e8586044 --- /dev/null +++ b/.eslintrc.js @@ -0,0 +1,32 @@ +module.exports = { + extends: [ + 'eslint:recommended', + 'plugin:ava/recommended', + 'plugin:import/errors', + 'plugin:import/warnings', + 'plugin:promise/recommended', + 'standard' + ], + parserOptions: { + sourceType: 'script' + }, + plugins: [ + 'ava' + ], + rules: { + 'ava/no-import-test-files': 0, + 'ava/no-ignored-test-files': 0, + indent: [ + 'error', + 2, + { + 'CallExpression': { + 'arguments': 'first' + }, + 'SwitchCase': 1 + } + ], + 'no-console': 0, + strict: 'error' + } +} diff --git a/.eslintrc.typescript.js b/.eslintrc.typescript.js new file mode 100644 index 00000000..64f5f083 --- /dev/null +++ b/.eslintrc.typescript.js @@ -0,0 +1,13 @@ +const eslintConfig = require('./.eslintrc') +eslintConfig.parser = '@typescript-eslint/parser' +eslintConfig.parserOptions.sourceType = 'module' +eslintConfig.extends.push( + 'plugin:@typescript-eslint/eslint-recommended', + 'plugin:@typescript-eslint/recommended' +) + +eslintConfig.rules['comma-dangle'] = ['error', 'only-multiline'] +eslintConfig.rules.semi = ['error', 'always'] +eslintConfig.rules['space-before-function-paren'] = ['error', 'never'] + +module.exports = eslintConfig diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5372c291..55411acd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -52,7 +52,7 @@ Here are some things to keep in mind as you file pull requests to fix bugs, add spot regressions much easier. * If your PR changes the behavior of an existing feature, or adds a new feature, please add/edit the package's documentation. Files that will likely need to be updated include `README.md`, - `docs/api.md`, and `usage.txt`. + `src/index.d.ts`, and `usage.txt`. * This project uses the [JavaScript Standard Style](https://standardjs.com/) as a coding convention. CI will fail if the PR does not conform to this standard. * One of the philosophies of the project is to keep the code base as small as possible. If you are diff --git a/docs/api.md b/docs/api.md deleted file mode 100644 index 542ca758..00000000 --- a/docs/api.md +++ /dev/null @@ -1,521 +0,0 @@ -# electron-packager API - -Short example: - -```javascript -const packager = require('electron-packager') - -async function bundleElectronApp(options) { - const appPaths = await packager(options) - console.log(`Electron app bundles created:\n${appPaths.join("\n")}`) -} -``` - -`appPaths` is described in the [return value](#return-value) section. - -## `options` - -### Required - -#### `dir` - -*String* - -The source directory. - -### Optional - -#### All Platforms - -##### `afterCopy` - -*Array of Functions* - -An array of functions to be called after your app directory has been copied to a temporary directory. Each function is called with five parameters: - -- `buildPath` (*String*): The path to the temporary folder where your app has been copied to -- `electronVersion` (*String*): The version of electron you are packaging for -- `platform` (*String*): The target platform you are packaging for -- `arch` (*String*): The target architecture you are packaging for -- `callback` (*Function*): Must be called once you have completed your actions - -By default, the functions are called in parallel (via -[`Promise.all`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/all)). -If you need the functions called serially, there is a utility function provided. Please note that -**callback-style functions are not supported by `serialHooks`.** For example: - -```javascript -const packager = require('electron-packager') -const { serialHooks } = require('electron-packager/src/hooks') - -packager({ - // ... - afterCopy: [serialHooks([ - (buildPath, electronVersion, platform, arch) => { - return new Promise((resolve, reject) => { - setTimeout(() => { - console.log('first function') - resolve() - }, 1000) - }) - }, - (buildPath, electronVersion, platform, arch) => { - console.log('second function') - } - ])], - // ... -}) -``` - -**Note:** `afterCopy` will not be called if [`prebuiltAsar`](#prebuiltasar) is set. - -##### `afterExtract` - -*Array of Functions* - -An array of functions to be called after Electron has been extracted to a temporary directory. Each function is called with five parameters: - -- `buildPath` (*String*): The path to the temporary folder where Electron has been extracted to -- `electronVersion` (*String*): The version of electron you are packaging for -- `platform` (*String*): The target platform you are packaging for -- `arch` (*String*): The target architecture you are packaging for -- `callback` (*Function*): Must be called once you have completed your actions - -By default, the functions are called in parallel (via -[`Promise.all`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/all)). -If you need the functions called serially, there is a utility function provided. Please note that -**callback-style functions are not supported by `serialHooks`.** For example: - -```javascript -const packager = require('electron-packager') -const { serialHooks } = require('electron-packager/src/hooks') - -packager({ - // ... - afterExtract: [serialHooks([ - (buildPath, electronVersion, platform, arch) => { - return new Promise((resolve, reject) => { - setTimeout(() => { - console.log('first function') - resolve() - }, 1000) - }) - }, - (buildPath, electronVersion, platform, arch) => { - console.log('second function') - } - ])], - // ... -}) -``` - -##### `afterPrune` - -*Array of Functions* - -An array of functions to be called after the prune command has been run -in the temporary directory. Each function is called with five parameters: - -- `buildPath` (*String*): The path to the temporary folder where your app has been copied to -- `electronVersion` (*String*): The version of electron you are packaging for -- `platform` (*String*): The target platform you are packaging for -- `arch` (*String*): The target architecture you are packaging for -- `callback` (*Function*): Must be called once you have completed your actions - -**Note:** None of these functions will be called if the `prune` option is `false` or `prebuiltAsar` is set. - -By default, the functions are called in parallel (via -[`Promise.all`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/all)). -If you need the functions called serially, there is a utility function provided. Please note that -**callback-style functions are not supported by `serialHooks`.** For example: - -```javascript -const packager = require('electron-packager') -const { serialHooks } = require('electron-packager/src/hooks') - -packager({ - // ... - afterPrune: [serialHooks([ - (buildPath, electronVersion, platform, arch) => { - return new Promise((resolve, reject) => { - setTimeout(() => { - console.log('first function') - resolve() - }, 1000) - }) - }, - (buildPath, electronVersion, platform, arch) => { - console.log('second function') - } - ])], - // ... -}) -``` - -##### `all` - -*Boolean* - -When `true`, sets both [`arch`](#arch) and [`platform`](#platform) to `all`. - -##### `appCopyright` - -*String* - -The human-readable copyright line for the app. Maps to the `LegalCopyright` metadata property on Windows, and `NSHumanReadableCopyright` on macOS. - -##### `appVersion` - -*String* - -The release version of the application. By default the `version` property in the `package.json` is used but it can be overridden with this argument. If neither are provided, the version of Electron will be used. Maps to the `ProductVersion` metadata property on Windows, and `CFBundleShortVersionString` on macOS. - -#### `arch` - -*String* (default: the arch of the host computer running Node) - -Allowed values: `ia32`, `x64`, `armv7l`, `arm64` _(Electron 1.8.0 and above)_, `mips64el` -_(Electron 1.8.2-beta.5 to 1.8.8)_, `all` - -The target system architecture(s) to build for. -Not required if the [`all`](#all) option is set. -If `arch` is set to `all`, all supported architectures for the target platforms specified by [`platform`](#platform) will be built. -Arbitrary combinations of individual architectures are also supported via a comma-delimited string or array of strings. -The non-`all` values correspond to the architecture names used by [Electron releases]. This value -is not restricted to the official set if [`download.mirrorOptions`](#download) is set. - -##### `asar` - -*Boolean* or *Object* (default: `false`) - -Whether to package the application's source code into an archive, using [Electron's archive format](https://github.com/electron/asar). Reasons why you may want to enable this feature are described in [an application packaging tutorial in Electron's documentation](https://electronjs.org/docs/tutorial/application-packaging/). When the value is `true`, pass default configuration to the `asar` module. The configuration values listed below can be customized when the value is an `Object`. Supported parameters include, but are not limited to: -- `ordering` (*String*): A path to an ordering file for packing files. An explanation can be found on the [Atom issue tracker](https://github.com/atom/atom/issues/10163). -- `unpack` (*String*): A [glob expression](https://github.com/isaacs/minimatch#features), when specified, unpacks the file with matching names to the `app.asar.unpacked` directory. -- `unpackDir` (*String*): Unpacks the dir to the `app.asar.unpacked` directory whose names exactly or pattern match this string. The `asar.unpackDir` is relative to `dir`. - - Some examples: - - - `asar.unpackDir = 'sub_dir'` will unpack the directory `//sub_dir` - - `asar.unpackDir = '**/{sub_dir1/sub_sub_dir,sub_dir2}/*'` will unpack the directories `//sub_dir1/sub_sub_dir` and `//sub_dir2`, but it will not include their subdirectories. - - `asar.unpackDir = '**/{sub_dir1/sub_sub_dir,sub_dir2}/**'` will unpack the subdirectories of the directories `//sub_dir1/sub_sub_dir` and `//sub_dir2`. - - `asar.unpackDir = '**/{sub_dir1/sub_sub_dir,sub_dir2}/**/*'` will unpack the directories `//sub_dir1/sub_sub_dir` and `//sub_dir2` and their subdirectories. - -**Note:** `asar` will have no effect if [`prebuiltAsar`](#prebuiltasar) is set. - -##### `buildVersion` - -*String* - -The build version of the application. Defaults to the value of [`appVersion`](#appversion). Maps to the `FileVersion` metadata property on Windows, and `CFBundleVersion` on macOS. - -##### `derefSymlinks` - -*Boolean* (default: `true`) - -Whether symlinks should be dereferenced during the copying of the application source. - -**Note:** `derefSymlinks` will have no effect if [`prebuiltAsar`](#prebuiltasar) is set. - -##### `download` - -*Object* - -If present, passes custom options to [`@electron/get`](https://npm.im/@electron/get) -(see the link for more detailed option descriptions, proxy support, and the defaults). Supported -parameters include, but are not limited to: -- `cacheRoot` (*String*): The directory where prebuilt, pre-packaged Electron downloads are cached. -- `mirrorOptions` (*Object*): Options to override the default Electron download location. -- `rejectUnauthorized` (*Boolean* - default: `true`): Whether SSL certificates are required to be - valid when downloading Electron. - -**Note:** `download` sub-options will have no effect if [`electronZipDir`](#electronzipdir) is set. - -##### `electronVersion` - -*String* - -The Electron version with which the app is built (without the leading 'v') - for example, -[`1.4.13`](https://github.com/electron/electron/releases/tag/v1.4.13). See [Electron releases] for -valid versions. If omitted, it will use the version of the nearest local installation of -`electron`, `electron-prebuilt-compile`, or `electron-prebuilt`, defined in `package.json` in either -`dependencies` or `devDependencies`. - -##### `electronZipDir` - -*String* - -The local path to a directory containing Electron ZIP files for Electron Packager to unzip, instead -of downloading them. The ZIP filenames should be in the same format as the ones downloaded from the -Electron releases site. - -**Note:** Setting this option prevents the [`download`](#download) sub-options from being used, as -the functionality gets skipped over. - -##### `extraResource` - -*String* or *Array* of *String*s - -One or more files to be copied directly into the app's `Contents/Resources` directory for macOS -target platforms, and the `resources` directory for other target platforms. - -##### `executableName` - -*String* - -The name of the executable file (sans file extension). Defaults to the value for the [`name`](#name) -parameter. For `darwin` or `mas` target platforms, this does not affect the name of the `.app` -folder - this will use [`name`](#name) parameter. - -##### `icon` - -*String* - -The local path to the icon file, if the target platform supports setting embedding an icon. - -Currently you must look for conversion tools in order to supply an icon in the format required by the platform: - -- macOS: `.icns` -- Windows: `.ico` ([See the readme](https://github.com/electron/electron-packager#building-windows-apps-from-non-windows-platforms) for details on non-Windows platforms) -- Linux: this option is not supported, as the dock/window list icon is set via - [the `icon` option in the `BrowserWindow` constructor](https://electronjs.org/docs/api/browser-window/#new-browserwindowoptions). - *Please note that you need to use a PNG, and not the macOS or Windows icon formats, in order for it - to show up in the dock/window list.* Setting the icon in the file manager is not currently supported. - -If the file extension is omitted, it is auto-completed to the correct extension based on the platform, including when [`platform: 'all'`](#platform) is in effect. - -##### `ignore` - -*RegExp*, *Array* of *RegExp*s, or *Function* - -One or more additional [regular expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions) -patterns which specify which files to ignore when copying files to create the app bundle(s). The -regular expressions are matched against the absolute path of a given file/directory to be copied. - -The following paths are always ignored (*when you aren't using the predicate function that is -described after the list*): - -* the directory specified by the [`out`](#out) parameter -* the temporary directory used to build the Electron app -* `node_modules/.bin` -* `node_modules/electron` -* `node_modules/electron-prebuilt` -* `node_modules/electron-prebuilt-compile` -* `.git` -* files and folders ending in `.o` and `.obj` - -**Please note that [glob patterns](https://en.wikipedia.org/wiki/Glob_%28programming%29) will not work.** - -**Note**: Node modules specified in `devDependencies` are ignored by default, via the -[`prune`](#prune) option. - -Alternatively, this can be a predicate function that, given an absolute file path, returns `true` if -the file should be ignored, or `false` if the file should be kept. *This does not use any of the -default ignored files/directories listed above.* - -**Note:** `ignore` will have no effect if [`prebuiltAsar`](#prebuiltasar) is set. - -##### `junk` - -*Boolean* (default: `true`) - -Ignores [system junk files](https://github.com/sindresorhus/junk) when copying the Electron app, -regardless of the [`ignore`](#ignore) option. - -**Note:** `junk` will have no effect if [`prebuiltAsar`](#prebuiltasar) is set. - -##### `name` - -*String* - -The application name. If omitted, it will use the `productName` or `name` value from the nearest `package.json`. - -**Regardless of source, characters in the Electron app name which are not allowed in all target -platforms' filenames (e.g., `/`), will be replaced by hyphens (`-`).** - -##### `out` - -*String* (default: current working directory) - -The base directory where the finished package(s) are created. - -##### `overwrite` - -*Boolean* (default: `false`) - -Whether to replace an already existing output directory for a given platform (`true`) or skip recreating it (`false`). - -##### `platform` - -*String* (default: the arch of the host computer running Node) - -Allowed values: `linux`, `win32`, `darwin`, `mas`, `all` - -The target platform(s) to build for. -Not required if the [`all`](#all) option is set. -If `platform` is set to `all`, all [supported target platforms](#supported-platforms) for the target architectures specified by [`arch`](#arch) will be built. -Arbitrary combinations of individual platforms are also supported via a comma-delimited string or array of strings. -The non-`all` values correspond to the platform names used by [Electron releases]. This value -is not restricted to the official set if [`download.mirrorOptions`](#download) is set. - -##### `prebuiltAsar` - -*String* - -The path to a prebuilt ASAR file. - -**Note:** Setting this option prevents the following options from being used, as the functionality -gets skipped over: - -* [`asar`](#asar) -* [`afterCopy`](#aftercopy) -* [`afterPrune`](#afterprune) -* [`derefSymlinks`](#derefsymlinks) -* [`ignore`](#ignore) -* [`junk`](#junk) -* [`prune`](#prune) - -##### `prune` - -*Boolean* (default: `true`) - -Walks the `node_modules` dependency tree to remove all of the packages specified in the -`devDependencies` section of `package.json` from the outputted Electron app. - -**Note:** `prune` will have no effect if [`prebuiltAsar`](#prebuiltasar) is set. - -##### `quiet` - -*Boolean* (default: `false`) - -If `true`, disables printing informational and warning messages to the console when packaging the -application. This does *not* disable errors. - -##### `tmpdir` - -*String* or *`false`* (default: system temp directory) - -The base directory to use as a temp directory. Set to `false` to disable use of a temporary directory. - -#### macOS/Mac App Store targets only - -##### `appBundleId` - -*String* - -The bundle identifier to use in the application's plist. - -##### `appCategoryType` - -*String* - -The application category type, as shown in the Finder via *View → Arrange by Application Category* when viewing the Applications directory. - -For example, `app-category-type=public.app-category.developer-tools` will set the application category to *Developer Tools*. - -Valid values are listed in [Apple's documentation](https://developer.apple.com/library/ios/documentation/General/Reference/InfoPlistKeyReference/Articles/LaunchServicesKeys.html#//apple_ref/doc/uid/TP40009250-SW8). - -##### `darwinDarkModeSupport` - -*Boolean* (default: `false`) - -Forces support for Mojave (macOS 10.14) dark mode in your packaged app. This sets the -`NSRequiresAquaSystemAppearance` key to `false` in your app's `Info.plist`. For more information, -see the [Electron documentation](https://www.electronjs.org/docs/tutorial/mojave-dark-mode-guide) -and the [Apple developer documentation](https://developer.apple.com/documentation/appkit/nsappearancecustomization/choosing_a_specific_appearance_for_your_app). - -##### `extendInfo` - -*String* or *Object* - -When the value is a `String`, the filename of a plist file. Its contents are added to the app's plist. When the value is an `Object`, an already-parsed plist data structure that is merged into the app's plist. - -Entries from `extend-info` override entries in the base plist file supplied by `electron`, `electron-prebuilt-compile`, or `electron-prebuilt`, but are overridden by other explicit arguments such as [`appVersion`](#appversion) or [`appBundleId`](#appbundleid). - -##### `helperBundleId` - -*String* - -The bundle identifier to use in the application helper's plist. - -##### `osxNotarize` - -*Object* - -**Requires [`osxSign`](#osxsign) to be set.** - -If present, notarizes macOS target apps when the host platform is macOS and XCode is installed. The configuration values listed below can be customized. See [`electron-notarize`](https://github.com/electron-userland/electron-notarize#method-notarizeopts-promisevoid) for more detailed option descriptions and how to use `appleIdPassword` safely. -- `appleId` (*String*, **required**): Your Apple ID username / email -- `appleIdPassword` (*String*, **required**): The password for your Apple ID, can be a keychain reference - -##### `osxSign` - -*Object* or *`true`* - -If present, signs macOS target apps when the host platform is macOS and XCode is installed. When the value is `true`, pass default configuration to the signing module. The configuration values listed below can be customized when the value is an `Object`. See [electron-osx-sign](https://www.npmjs.com/package/electron-osx-sign#opts) for more detailed option descriptions and the defaults. -- `identity` (*String*): The identity used when signing the package via `codesign`. -- `entitlements` (*String*): The path to the 'parent' entitlements. -- `entitlements-inherit` (*String*): The path to the 'child' entitlements. - -##### `protocols` - -*Array* of *Object*​s - -One or more URL protocols associated with the Electron app. - -Each *Object* is required to have the following properties: - -- `name` (*String*): The descriptive name. Maps to the `CFBundleURLName` metadata property. -- `schemes` (*Array* of *String*​s): One or more protocol schemes associated with the app. For - example, specifying `myapp` would cause URLs such as `myapp://path` to be opened with the app. - Maps to the `CFBundleURLSchemes` metadata property. - -##### `usageDescription` - -*Object* - -Human-readable descriptions of how the Electron app uses certain macOS features. These are displayed -in the App Store. A non-exhaustive list of available properties: - -* `Camera` - required for media access API usage in macOS Catalina -* `Microphone` - required for media access API usage in macOS Catalina - -Valid properties are the [Cocoa keys for MacOS](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html) -of the pattern `NS(.*)UsageDescription`, where the captured group is the key to use. - -Example: - -```javascript -{ - usageDescription: { - Camera: 'Needed for video calls', - Microphone: 'Needed for voice calls' - } -} -``` - -#### Windows targets only - -##### `win32metadata` - -*Object* - -Object (also known as a "hash") of application metadata to embed into the executable: -- `CompanyName` (defaults to `author` name from the nearest `package.json`) -- `FileDescription` (defaults to either `productName` or `name` from the nearest `package.json`) -- `OriginalFilename` (defaults to renamed `.exe` file) -- `ProductName` (defaults to either `productName` or `name` from the nearest `package.json`) -- `InternalName` (defaults to either `productName` or `name` from the nearest `package.json`) -- `requested-execution-level` -- `application-manifest` - -For more information, see the [`node-rcedit` module](https://github.com/electron/node-rcedit). - -## Return value - -### `appPaths` - -*Array* of *String*s - -Paths to the newly created application bundles. - -[Electron releases]: https://github.com/electron/electron/releases diff --git a/package.json b/package.json index dbbb0ed7..f84b8fb3 100644 --- a/package.json +++ b/package.json @@ -3,6 +3,7 @@ "version": "14.2.1", "description": "Customize and package your Electron app with OS-specific bundles (.app, .exe, etc.) via JS or CLI", "main": "src/index.js", + "types": "src/index.d.ts", "bin": { "electron-packager": "bin/electron-packager.js" }, @@ -22,11 +23,12 @@ "docs/*.md", "NEWS.md", "src", + "src/index.d.ts", "usage.txt" ], "dependencies": { "@electron/get": "^1.6.0", - "asar": "^2.0.1", + "asar": "^2.1.0", "cross-zip": "^3.0.0", "debug": "^4.0.1", "electron-notarize": "^0.2.0", @@ -44,6 +46,8 @@ "yargs-parser": "^17.0.0" }, "devDependencies": { + "@typescript-eslint/eslint-plugin": "^2.20.0", + "@typescript-eslint/parser": "^2.20.0", "ava": "^3.3.0", "buffer-equal": "^1.0.0", "codecov": "^3.0.0", @@ -56,7 +60,9 @@ "eslint-plugin-standard": "^4.0.0", "nyc": "^15.0.0", "pkg-up": "^3.0.1", - "sinon": "^9.0.0" + "sinon": "^9.0.0", + "tsd": "^0.11.0", + "typescript": "^3.7.5" }, "engines": { "node": ">= 10.0" @@ -65,8 +71,11 @@ "ava": "ava test/index.js", "codecov": "nyc report --reporter=text-lcov > coverage.lcov && codecov", "coverage": "nyc npm run ava", - "lint": "eslint .", - "test": "npm run lint && npm run coverage" + "lint": "npm run lint:js && npm run lint:ts", + "lint:js": "eslint .", + "lint:ts": "eslint --config .eslintrc.typescript.js --ext .ts .", + "test": "npm run lint && npm run tsd && npm run coverage", + "tsd": "tsd" }, "directories": { "test": "test" @@ -80,37 +89,8 @@ "ava": { "timeout": "60s" }, - "eslintConfig": { - "extends": [ - "eslint:recommended", - "plugin:ava/recommended", - "plugin:import/errors", - "plugin:import/warnings", - "plugin:promise/recommended", - "standard" - ], - "parserOptions": { - "sourceType": "script" - }, - "plugins": [ - "ava" - ], - "rules": { - "ava/no-import-test-files": 0, - "ava/no-ignored-test-files": 0, - "indent": [ - "error", - 2, - { - "CallExpression": { - "arguments": "first" - }, - "SwitchCase": 1 - } - ], - "no-console": 0, - "strict": "error" - } + "tsd": { + "directory": "test" }, "funding": { "url": "https://github.com/electron/electron-packager?sponsor=1" diff --git a/src/index.d.ts b/src/index.d.ts new file mode 100644 index 00000000..4c08ee8d --- /dev/null +++ b/src/index.d.ts @@ -0,0 +1,527 @@ +// Originally based on the type definitions for electron-packager 14.0 +// Project: https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/electron-packager +// Original Authors: +// * Maxime LUCE +// * Juan Jimenez-Anca +// * John Kleinschmidt +// * Brendan Forster +// * Mark Lee +// * Florian Keller + +import { CreateOptions as AsarOptions } from 'asar'; +import { ElectronDownloadRequestOptions as ElectronDownloadOptions } from '@electron/get'; +import { NotarizeOptions } from 'electron-notarize'; +import { SignOptions } from 'electron-osx-sign'; + +/** + * Bundles Electron-based application source code with a renamed/customized Electron executable and + * its supporting files into folders ready for distribution. + * + * Briefly, this function: + * - finds or downloads the correct release of Electron + * - uses that version of Electron to create a app in `/--` + * + * Short example: + * + * ```javascript + * const packager = require('electron-packager') + * + * async function bundleElectronApp(options) { + * const appPaths = await packager(options) + * console.log(`Electron app bundles created:\n${appPaths.join("\n")}`) + * } + * ``` + * + * @param opts - Options to configure packaging. + * + * @returns A Promise containing the paths to the newly created application bundles. + */ +declare function electronPackager(opts: electronPackager.Options): Promise; + +declare namespace electronPackager { + /** + * Architectures that have been supported by the official Electron prebuilt binaries, past + * and present. + */ + type OfficialArch = 'ia32' | 'x64' | 'armv7l' | 'arm64' | 'mips64el'; + /** + * Platforms that have been supported by the official Electron prebuilt binaries, past and present. + */ + type OfficialPlatform = 'linux' | 'win32' | 'darwin' | 'mas'; + type TargetArch = OfficialArch | string; + type TargetPlatform = OfficialPlatform | string; + type ArchOption = TargetArch | 'all'; + type PlatformOption = TargetPlatform | 'all'; + + /** + * A predicate function that, given an absolute file `path`, returns `true` if the file should be + * ignored, or `false` if the file should be kept. *This does not use any of the default ignored + * files/directories listed for the [[ignore]] option.* + */ + type IgnoreFunction = (path: string) => boolean; + /** + * A function that is called on the completion of a packaging stage. + * + * By default, the functions are called in parallel (via + * [`Promise.all`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/all)). + * If you need the functions called serially, there is a utility function provided. Please note that + * **callback-style functions are not supported by `serialHooks`.** For example: + * + * ```javascript + * const packager = require('electron-packager') + * const { serialHooks } = require('electron-packager/src/hooks') + * + * packager({ + * // ... + * afterCopy: [serialHooks([ + * (buildPath, electronVersion, platform, arch) => { + * return new Promise((resolve, reject) => { + * setTimeout(() => { + * console.log('first function') + * resolve() + * }, 1000) + * }) + * }, + * (buildPath, electronVersion, platform, arch) => { + * console.log('second function') + * } + * ])], + * // ... + * }) + * ``` + */ + type HookFunction = + /** + * @param buildPath - For [[afterExtract]], the path to the temporary folder where the prebuilt + * Electron binary has been extracted to. For [[afterCopy]] and [[afterPrune]], the path to the + * folder where the Electron app has been copied to. + * @param electronVersion - the version of Electron that is being bundled with the application. + * @param platform - The target platform you are packaging for. + * @param arch - The target architecture you are packaging for. + * @param callback - Must be called once you have completed your actions. + */ + ( + buildPath: string, + electronVersion: string, + platform: TargetArch, + arch: TargetArch, + callback: () => void + ) => void; + + /** See the documentation for [`electron-osx-sign`](https://npm.im/electron-osx-sign#opts) for details. */ + type OsxSignOptions = Omit; + + /** + * See the documentation for [`electron-notarize`](https://npm.im/electron-notarize#method-notarizeopts-promisevoid) + * for details. + */ + type OsxNotarizeOptions = Omit; + + /** + * Defines URL protocol schemes to be used on macOS. + */ + interface MacOSProtocol { + /** + * The descriptive name. Maps to the `CFBundleURLName` metadata property. + */ + name: string; + /** + * One or more protocol schemes associated with the app. For example, specifying `myapp` + * would cause URLs such as `myapp://path` to be opened with the app. Maps to the + * `CFBundleURLSchemes` metadata property. + */ + schemes: string[]; + } + + /** + * A collection of application metadata to embed into the Windows executable. + * + * For more information, read the [`rcedit` Node module documentation](https://github.com/electron/node-rcedit#docs). + */ + interface Win32MetadataOptions { + /** Defaults to the `author` name from the nearest `package.json`. */ + CompanyName?: string; + /** Defaults to either `productName` or `name` from the nearest `package.json`. */ + FileDescription?: string; + /** Defaults to the renamed Electron `.exe` file. */ + OriginalFilename?: string; + /** Defaults to either `productName` or `name` from the nearest `package.json`. */ + ProductName?: string; + /** Defaults to either `productName` or `name` from the nearest `package.json`. */ + InternalName?: string; + /** See [MSDN](https://msdn.microsoft.com/en-us/library/6ad1fshk.aspx#Anchor_9) for details. */ + 'requested-execution-level'?: 'asInvoker' | 'highestAvailable' | 'requireAdministrator'; + /** + * Path to a local manifest file. + * + * See [MSDN](https://msdn.microsoft.com/en-us/library/windows/desktop/aa374191.aspx) for more details. + */ + 'application-manifest'?: string; + } + + /** Options passed to the `packager()` function. */ + interface Options { + /** The source directory. */ + dir: string; + /** + * Functions to be called after your app directory has been copied to a temporary directory. + * + * **Note**: `afterCopy` will not be called if the [[prebuiltAsar]] option is set. + */ + afterCopy?: HookFunction[]; + /** Functions to be called after the prebuilt Electron binary has been extracted to a temporary directory. */ + afterExtract?: HookFunction[]; + /** + * Functions to be called after Node module pruning has been applied to the application. + * + * **Note**: None of these functions will be called if the [[prune]] option is `false` or + * the [[prebuiltAsar]] option is set. + */ + afterPrune?: HookFunction[]; + + /** When `true`, sets both [[arch]] and [[platform]] to `all`. */ + all?: boolean; + /* + * The bundle identifier to use in the application's `Info.plist`. + * + * @category macOS + */ + appBundleId?: string; + /** + * The application category type, as shown in the Finder via *View → Arrange by Application + * Category* when viewing the Applications directory. + * + * For example, `app-category-type=public.app-category.developer-tools` will set the + * application category to *Developer Tools*. + * + * Valid values are listed in [Apple's documentation](https://developer.apple.com/library/ios/documentation/General/Reference/InfoPlistKeyReference/Articles/LaunchServicesKeys.html#//apple_ref/doc/uid/TP40009250-SW8). + * + * @category macOS + */ + appCategoryType?: string; + /** + * The human-readable copyright line for the app. Maps to the `LegalCopyright` metadata + * property on Windows, and `NSHumanReadableCopyright` on macOS. + */ + appCopyright?: string; + /** + * The release version of the application. + * + * By default the `version` property in the `package.json` is used, but it can be overridden + * with this argument. If neither are provided, the version of Electron will be used. Maps + * to the `ProductVersion` metadata property on Windows, and `CFBundleShortVersionString` + * on macOS. + */ + appVersion?: string; + /** + * The target system architecture(s) to build for. + * + * Not required if the [[all]] option is set. If `arch` is set to `all`, all supported + * architectures for the target platforms specified by [[platform]] will be built. + * Arbitrary combinations of individual architectures are also supported via a comma-delimited + * string or array of strings. The non-`all` values correspond to the architecture names used + * by [Electron releases](https://github.com/electron/electron/releases). This value + * is not restricted to the official set if [[download|`download.mirrorOptions`]] is set. + * + * Defaults to the arch of the host computer running Electron Packager. + * + * Arch values for the official prebuilt Electron binaries: + * - `ia32` + * - `x64` + * - `armv7l` + * - `arm64` _(Electron 1.8.0 and above)_ + * - `mips64el` _(Electron 1.8.2-beta.5 to 1.8.8)_ + */ + arch?: ArchOption | ArchOption[]; + /** + * Whether to package the application's source code into an archive, using [Electron's + * archive format](https://github.com/electron/asar). Reasons why you may want to enable + * this feature are described in [an application packaging tutorial in Electron's + * documentation](https://electronjs.org/docs/tutorial/application-packaging/). When the value + * is `true`, it passes the default configuration to the `asar` module. The configuration + * values can be customized when the value is an `Object`. Supported sub-options include, but + * are not limited to: + * - `ordering` (*string*): A path to an ordering file for packing files. An explanation can be + * found on the [Atom issue tracker](https://github.com/atom/atom/issues/10163). + * - `unpack` (*string*): A [glob expression](https://github.com/isaacs/minimatch#features), + * when specified, unpacks the file with matching names to the `app.asar.unpacked` directory. + * - `unpackDir` (*string*): Unpacks the dir to the `app.asar.unpacked` directory whose names + * exactly or pattern match this string. The `asar.unpackDir` is relative to [[dir]]. + * + * Defaults to `false`. + * + * Some examples: + * + * - `asar.unpackDir = 'sub_dir'` will unpack the directory `//sub_dir` + * - `asar.unpackDir = path.join('**', '{sub_dir1/sub_sub_dir,sub_dir2}', '*')` will unpack the directories `//sub_dir1/sub_sub_dir` and `//sub_dir2`, but it will not include their subdirectories. + * - `asar.unpackDir = path.join('**', '{sub_dir1/sub_sub_dir,sub_dir2}', '**')` will unpack the subdirectories of the directories `//sub_dir1/sub_sub_dir` and `//sub_dir2`. + * - `asar.unpackDir = path.join('**', '{sub_dir1/sub_sub_dir,sub_dir2}', '**', '*')` will unpack the directories `//sub_dir1/sub_sub_dir` and `//sub_dir2` and their subdirectories. + * + * **Note:** `asar` will have no effect if the [[prebuiltAsar]] option is set. + */ + asar?: boolean | AsarOptions; + /** + * The build version of the application. Defaults to the value of the [[appVersion]] option. + * Maps to the `FileVersion` metadata property on Windows, and `CFBundleVersion` on macOS. + */ + buildVersion?: string; + /** + * Forces support for Mojave (macOS 10.14) dark mode in your packaged app. This sets the + * `NSRequiresAquaSystemAppearance` key to `false` in your app's `Info.plist`. For more information, + * see the [Electron documentation](https://www.electronjs.org/docs/tutorial/mojave-dark-mode-guide) + * and the [Apple developer documentation](https://developer.apple.com/documentation/appkit/nsappearancecustomization/choosing_a_specific_appearance_for_your_app). + * + * @category macOS + */ + darwinDarkModeSupport?: boolean; + /** + * Whether symlinks should be dereferenced during the copying of the application source. + * Defaults to `true`. + * + * **Note:** `derefSymlinks` will have no effect if the [[prebuiltAsar]] option is set. + */ + derefSymlinks?: boolean; + /** + * If present, passes custom options to [`@electron/get`](https://npm.im/@electron/get). See + * the module for option descriptions, proxy support, and defaults. Supported parameters + * include, but are not limited to: + * - `cacheRoot` (*string*): The directory where prebuilt, pre-packaged Electron downloads are cached. + * - `mirrorOptions` (*Object*): Options to override the default Electron download location. + * - `rejectUnauthorized` (*boolean* - default: `true`): Whether SSL certificates are required to be + * valid when downloading Electron. + * + * **Note:** `download` sub-options will have no effect if the [[electronZipDir]] option is set. + */ + download?: ElectronDownloadOptions; + /** + * The Electron version with which the app is built (without the leading 'v') - for example, + * [`1.4.13`](https://github.com/electron/electron/releases/tag/v1.4.13). See [Electron + * releases](https://github.com/electron/electron/releases) for valid versions. If omitted, it + * will use the version of the nearest local installation of `electron`, + * `electron-prebuilt-compile`, or `electron-prebuilt`, defined in `package.json` in either + * `devDependencies` or `dependencies`. + */ + electronVersion?: string; + /** + * The local path to a directory containing Electron ZIP files for Electron Packager to unzip, instead + * of downloading them. The ZIP filenames should be in the same format as the ones downloaded from the + * [Electron releases](https://github.com/electron/electron/releases) site. + * + * **Note:** Setting this option prevents the [[download]] sub-options from being used, as + * the functionality gets skipped over. + */ + electronZipDir?: string; + /** + * The name of the executable file, sans file extension. Defaults to the value for the [[name]] + * option. For `darwin` or `mas` target platforms, this does not affect the name of the + * `.app` folder - this will use the [[name]] option instead. + */ + executableName?: string; + /** + * When the value is a string, specifies the filename of a `plist` file. Its contents are merged + * into the app's `Info.plist`. + * When the value is an `Object`, it specifies an already-parsed `plist` data structure that is + * merged into the app's `Info.plist`. + * + * Entries from `extendInfo` override entries in the base `Info.plist` file supplied by + * `electron`, `electron-prebuilt-compile`, or `electron-prebuilt`, but are overridden by other + * options such as [[appVersion]] or [[appBundleId]]. + * + * @category macOS + */ + extendInfo?: string | { [property: string]: any }; // eslint-disable-line @typescript-eslint/no-explicit-any + /** + * One or more files to be copied directly into the app's `Contents/Resources` directory for + * macOS target platforms, and the `resources` directory for other target platforms. + */ + extraResource?: string | string[]; + /** + * The bundle identifier to use in the application helper's `Info.plist`. + * + * @category macOS + */ + helperBundleId?: string; + /** + * The local path to the icon file, if the target platform supports setting embedding an icon. + * + * Currently you must look for conversion tools in order to supply an icon in the format required by the platform: + * + * - macOS: `.icns` + * - Windows: `.ico` ([See the readme](https://github.com/electron/electron-packager#building-windows-apps-from-non-windows-platforms) for details on non-Windows platforms) + * - Linux: this option is not supported, as the dock/window list icon is set via + * [the `icon` option in the `BrowserWindow` constructor](https://electronjs.org/docs/api/browser-window/#new-browserwindowoptions). + * *Please note that you need to use a PNG, and not the macOS or Windows icon formats, in order for it + * to show up in the dock/window list.* Setting the icon in the file manager is not currently supported. + * + * If the file extension is omitted, it is auto-completed to the correct extension based on the + * platform, including when [[platform|`platform: 'all'`]] is in effect. + */ + icon?: string; + /** + * One or more additional [regular expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions) + * patterns which specify which files to ignore when copying files to create the app bundle(s). The + * regular expressions are matched against the absolute path of a given file/directory to be copied. + * + * **Please note that [glob patterns](https://en.wikipedia.org/wiki/Glob_%28programming%29) will not work.** + * + * The following paths are always ignored (*when you aren't using an [[IgnoreFunction]]*): + * + * - the directory specified by the [[out]] option + * - the temporary directory used to build the Electron app + * - `node_modules/.bin` + * - `node_modules/electron` + * - `node_modules/electron-prebuilt` + * - `node_modules/electron-prebuilt-compile` + * - `.git` + * - files and folders ending in `.o` and `.obj` + * + * **Note**: Node modules specified in `devDependencies` are ignored by default, via the + * [[prune]] option. + * + * **Note:** `ignore` will have no effect if the [[prebuiltAsar]] option is set. + */ + ignore?: RegExp | RegExp[] | IgnoreFunction; + /** + * Ignores [system junk files](https://github.com/sindresorhus/junk) when copying the Electron app, + * regardless of the [[ignore]] option. + * + * **Note:** `junk` will have no effect if the [[prebuiltAsar]] option is set. + */ + junk?: boolean; + /** + * The application name. If omitted, it will use the `productName` or `name` value from the + * nearest `package.json`. + * + * **Regardless of source, characters in the Electron app name which are not allowed in all target + * platforms' filenames (e.g., `/`), will be replaced by hyphens (`-`).** + */ + name?: string; + /** + * If present, notarizes macOS target apps when the host platform is macOS and XCode is + * installed. See [`electron-notarize`](https://github.com/electron/electron-notarize#method-notarizeopts-promisevoid) + * for sub-option descriptions and how to use the `appleIdPassword` sub-option safely. + * + * **Requires the [[osxSign]] option to be set.** + * + * @category macOS + */ + osxNotarize?: OsxNotarizeOptions; + /** + * If present, signs macOS target apps when the host platform is macOS and XCode is installed. + * When the value is `true`, pass default configuration to the signing module. See + * [electron-osx-sign](https://npm.im/electron-osx-sign#opts) for sub-option descriptions and + * their defaults. Options include, but are not limited to: + * - `identity` (*string*): The identity used when signing the package via `codesign`. + * - `entitlements` (*string*): The path to the 'parent' entitlements. + * - `entitlements-inherit` (*string*): The path to the 'child' entitlements. + * + * @category macOS + */ + osxSign?: true | OsxSignOptions; + /** + * The base directory where the finished package(s) are created. + * + * Defaults to the current working directory. + */ + out?: string; + /** + * Whether to replace an already existing output directory for a given platform (`true`) or + * skip recreating it (`false`). Defaults to `false`. + */ + overwrite?: boolean; + /** + * The target platform(s) to build for. + * + * Not required if the [[all]] option is set. If `platform` is set to `all`, all officially + * supported target platforms for the target architectures specified by the [[arch]] option + * will be built. Arbitrary combinations of individual platforms are also supported via a + * comma-delimited string or array of strings. + * + * The official non-`all` values correspond to the platform names used by [Electron + * releases](https://github.com/electron/electron/releases). This value is not restricted to + * the official set if [[download|`download.mirrorOptions]] is set. + * + * Defaults to the platform of the host computer running Electron Packager. + * + * Platform values for the official prebuilt Electron binaries: + * - `darwin` (macOS) + * - `linux` + * - `mas` (macOS, specifically for submitting to the Mac App Store) + * - `win32` + */ + platform?: PlatformOption | PlatformOption[]; + /** + * The path to a prebuilt ASAR file. + * + * **Note:** Setting this option prevents the following options from being used, as the functionality + * gets skipped over: + * + * - [[asar]] + * - [[afterCopy]] + * - [[afterPrune]] + * - [[derefSymlinks]] + * - [[ignore]] + * - [[junk]] + * - [[prune]] + */ + prebuiltAsar?: string; + /** + * The URL protocol schemes associated with the Electron app. + * + * @category macOS + */ + protocols?: MacOSProtocol[]; + /** + * Walks the `node_modules` dependency tree to remove all of the packages specified in the + * `devDependencies` section of `package.json` from the outputted Electron app. + * + * Defaults to `true`. + * + * **Note:** `prune` will have no effect if the [[prebuiltAsar]] option is set. + */ + prune?: boolean; + /** + * If `true`, disables printing informational and warning messages to the console when + * packaging the application. This does not disable errors. + * + * Defaults to `false`. + */ + quiet?: boolean; + /** + * The base directory to use as a temporary directory. Set to `false` to disable use of a + * temporary directory. Defaults to the system's temporary directory. + */ + tmpdir?: string | false; + /** + * Human-readable descriptions of how the Electron app uses certain macOS features. These are displayed + * in the App Store. A non-exhaustive list of available properties: + * + * * `Camera` - required for media access API usage in macOS Catalina + * * `Microphone` - required for media access API usage in macOS Catalina + * + * Valid properties are the [Cocoa keys for MacOS](https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html) + * of the pattern `NS(.*)UsageDescription`, where the captured group is the key to use. + * + * Example: + * + * ```javascript + * { + * usageDescription: { + * Camera: 'Needed for video calls', + * Microphone: 'Needed for voice calls' + * } + * } + * ``` + * + * @category macOS + */ + usageDescription?: { [property: string]: string }; + /** + * Application metadata to embed into the Windows executable. + * @category Windows + */ + win32metadata?: Win32MetadataOptions; + } +} + +export = electronPackager; diff --git a/test/index.test-d.ts b/test/index.test-d.ts new file mode 100644 index 00000000..2671cfef --- /dev/null +++ b/test/index.test-d.ts @@ -0,0 +1,185 @@ +import { expectType } from 'tsd'; +import * as packager from '..'; + +function completeFunction( + buildPath: string, + electronVersion: string, + platform: string, + arch: string, + callbackFn: () => void, +): void { + callbackFn(); +} + +// eslint-disable-next-line @typescript-eslint/no-unused-vars +function ignoreFunction(path: string): boolean { + return true; +} + +expectType>(packager({ + dir: '.', + name: 'myapplication', + platform: 'win32', + arch: 'all', + electronVersion: '0.34.0', + win32metadata: { + CompanyName: 'Acme CO', + FileDescription: 'My application', + OriginalFilename: 'myapp.exe', + ProductName: 'Application', + InternalName: 'roadrunner', + 'requested-execution-level': 'highestAvailable', + 'application-manifest': 'manifest.xml', + }, +})); + +await packager({ + dir: '.', + name: 'myapplication', + electronVersion: '0.34.0', + all: true, + win32metadata: { + CompanyName: 'Acme CO', + FileDescription: 'My application', + OriginalFilename: 'myapp.exe', + ProductName: 'Application', + InternalName: 'roadrunner', + 'requested-execution-level': 'requireAdministrator', + 'application-manifest': 'manifest.xml', + }, +}); + +await packager({ + dir: '.', + name: 'myapplication', + platform: 'all', + arch: 'all', + electronVersion: '0.34.0', +}); + +await packager({ + dir: '.', + name: 'myapplication', + electronVersion: '0.34.0', + all: true, +}); + +await packager({ + dir: '.', + name: 'myapplication', + electronVersion: '0.34.0', + arch: 'arm64', + executableName: 'myapp', +}); + +await packager({ + dir: '.', + afterCopy: [completeFunction], + afterExtract: [completeFunction], + afterPrune: [completeFunction], + appCopyright: 'Copyright', + appVersion: '1.0', + arch: 'ia32', + buildVersion: '1.2.3', + download: { + cacheRoot: './zips', + mirrorOptions: { + mirror: 'https://10.1.2.105/', + }, + }, + extraResource: 'foo.js', + icon: 'foo.ico', + ignore: /ab+c/, + out: 'out', + overwrite: true, + quiet: true, + tmpdir: '/tmp', + win32metadata: { + CompanyName: 'Acme CO', + FileDescription: 'My application', + OriginalFilename: 'myapp.exe', + ProductName: 'Application', + InternalName: 'roadrunner', + 'requested-execution-level': 'asInvoker', + 'application-manifest': 'manifest.xml', + }, +}); + +await packager({ + dir: '.', + arch: 'x64', + asar: true, + derefSymlinks: false, + download: { + cacheRoot: './zips', + mirrorOptions: { + mirror: 'https://10.1.2.105/', + }, + }, + extraResource: ['foo.js', 'bar.js'], + ignore: [/ab+c/, new RegExp('abc')], + platform: 'darwin', + prune: false, + tmpdir: 'false', + appBundleId: '123456', + appCategoryType: 'public.app-category.developer-tools', + extendInfo: 'plist.txt', + helperBundleId: '23223f', + osxSign: true, +}); + +await packager({ + dir: '.', + arch: 'armv7l', + asar: { + ordering: 'order.txt', + unpack: '*.js', + unpackDir: 'sub_dir', + }, + download: { + cacheRoot: './zips', + mirrorOptions: { + mirror: 'https://10.1.2.105/', + }, + }, + ignore: ignoreFunction, + platform: 'linux', +}); + +await packager({ + dir: '.', + arch: 'mips64el', + electronVersion: '1.8.8', + prebuiltAsar: 'prebuilt.asar', + platform: 'linux', +}); + +await packager({ + dir: '.', + arch: ['ia32', 'x64'], + download: { + cacheRoot: './zips', + mirrorOptions: { + mirror: 'https://10.1.2.105/', + }, + }, + platform: 'mas', + extendInfo: { + foo: 'bar', + }, + osxNotarize: { + appleId: 'My ID', + appleIdPassword: 'Bad Password', + } as packager.OsxNotarizeOptions, + osxSign: { + identity: 'myidentity', + entitlements: 'path/to/my.entitlements', + 'entitlements-inherit': 'path/to/inherit.entitlements', + }, + protocols: [ + { + name: 'myappproto', + schemes: ['myapp', 'myapp2'], + }, + ], +}); From ef72f4305ea105f730918188490fdc8629a39464 Mon Sep 17 00:00:00 2001 From: Mark Lee Date: Mon, 24 Feb 2020 12:13:38 -0800 Subject: [PATCH 2/2] build: publish TypeScript API docs to GitHub Pages --- .github/workflows/docs.yml | 28 ++++++++++++++++++++++++++ .gitignore | 1 + README.md | 6 +++--- docs/_config.yml | 1 - docs/api.md | 1 + docs/faq.md | 4 ++-- package.json | 2 ++ src/infer.js | 2 +- test/ci/build_docs.js | 41 ++++++++++++++++++++++++++++++++++++++ usage.txt | 2 +- 10 files changed, 80 insertions(+), 8 deletions(-) create mode 100644 .github/workflows/docs.yml delete mode 100644 docs/_config.yml create mode 100644 docs/api.md create mode 100755 test/ci/build_docs.js diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..a6b68f60 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,28 @@ +name: Publish documentation + +on: + push: + branches: + - master + tags: + - v[0-9]+.[0-9]+.[0-9]+* + +jobs: + docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: Fetch all git branches + run: git fetch --no-tags --prune --depth=1 origin +refs/heads/*:refs/remotes/origin/* + - uses: actions/setup-node@v1 + with: + node-version: 12.x + - run: npm install --engine-strict --no-lockfile + - run: npm run docs:build + - uses: docker://malept/gha-gh-pages:1.0.0 + with: + docsPath: typedoc + showUnderscoreFiles: true + versionDocs: true + env: + DOCS_SSH_DEPLOY_KEY: ${{ secrets.DOCS_SSH_DEPLOY_KEY }} diff --git a/.gitignore b/.gitignore index 9d0e5492..b5e54fc7 100644 --- a/.gitignore +++ b/.gitignore @@ -8,6 +8,7 @@ yarn.lock test/fixtures/basic/main-link.js !test/fixtures/prune-is-module/node_modules test/work +typedoc .DS_Store .nyc_output npm-debug.log diff --git a/README.md b/README.md index 1cdce638..1b41646e 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ Package your [Electron](https://electronjs.org) app into OS-specific bundles (`. [Supported Platforms](#supported-platforms) | [Installation](#installation) | [Usage](#usage) | -[API](https://github.com/electron/electron-packager/blob/master/docs/api.md) | +[API](https://electron.github.io/electron-packager/master/) | [Contributing](https://github.com/electron/electron-packager/blob/master/CONTRIBUTING.md) | [Support](https://github.com/electron/electron-packager/blob/master/SUPPORT.md) | [Related Apps/Libraries](#related) | @@ -72,7 +72,7 @@ later needs to be installed. On macOS, it is installable via [Homebrew](http://b ## Usage -JavaScript API usage can be found in the [API documentation](https://github.com/electron/electron-packager/blob/master/docs/api.md). +JavaScript API usage can be found in the [API documentation](https://electron.github.io/electron-packager/master/modules/electronpackager.html). ### From the Command Line @@ -95,7 +95,7 @@ This will: For an overview of the other optional flags, run `electron-packager --help` or see [usage.txt](https://github.com/electron/electron-packager/blob/master/usage.txt). For -detailed descriptions, see the [API documentation](https://github.com/electron/electron-packager/blob/master/docs/api.md). +detailed descriptions, see the [API documentation](https://electron.github.io/electron-packager/master/modules/electronpackager.html). If `appname` is omitted, this will use the name specified by "productName" or "name" in the nearest package.json. diff --git a/docs/_config.yml b/docs/_config.yml deleted file mode 100644 index c4192631..00000000 --- a/docs/_config.yml +++ /dev/null @@ -1 +0,0 @@ -theme: jekyll-theme-cayman \ No newline at end of file diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 00000000..01368854 --- /dev/null +++ b/docs/api.md @@ -0,0 +1 @@ +[API Documentation](https://electron.github.io/electron-packager/) has moved. diff --git a/docs/faq.md b/docs/faq.md index f399d3fc..4e4634f3 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -14,7 +14,7 @@ and packaged modes, you'll need to [define it yourself](https://electronjs.org/d ## Why isn't my `ignore` option working? -As stated in the documentation for [`ignore`](https://github.com/electron/electron-packager/blob/master/docs/api.md#ignore), it uses "[one] or more additional +As stated in the documentation for [`ignore`](https://electron.github.io/electron-packager/master/interfaces/electronpackager.options.html#ignore), it uses "[one] or more additional [regular expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions) patterns. […] Please note that [glob patterns](https://en.wikipedia.org/wiki/Glob_%28programming%29) will not work." @@ -44,7 +44,7 @@ console.log(require(jsonFilename)); ## How do I set an icon on Linux? -The docs for [`icon`](https://github.com/electron/electron-packager/blob/master/docs/api.md#icon) +The docs for [`icon`](https://electron.github.io/electron-packager/master/interfaces/electronpackager.options.html#icon) already show how to set an icon on your `BrowserWindow`, but your dock/taskbar may not use that and instead use the `Icon` value in your `.desktop` file. The [Linux distributable creators](https://github.com/electron/electron-packager#distributable-creators) can help you set/distribute the appropriate icon in that case. diff --git a/package.json b/package.json index f84b8fb3..e1ec6249 100644 --- a/package.json +++ b/package.json @@ -62,6 +62,7 @@ "pkg-up": "^3.0.1", "sinon": "^9.0.0", "tsd": "^0.11.0", + "typedoc": "^0.16.10", "typescript": "^3.7.5" }, "engines": { @@ -71,6 +72,7 @@ "ava": "ava test/index.js", "codecov": "nyc report --reporter=text-lcov > coverage.lcov && codecov", "coverage": "nyc npm run ava", + "docs:build": "node test/ci/build_docs.js", "lint": "npm run lint:js && npm run lint:ts", "lint:js": "eslint .", "lint:ts": "eslint --config .eslintrc.typescript.js --ext .ts .", diff --git a/src/infer.js b/src/infer.js index ae65808d..d97c34b4 100644 --- a/src/infer.js +++ b/src/infer.js @@ -34,7 +34,7 @@ function errorMessageForProperty (prop) { return `Unable to determine ${propDescription}. Please specify an ${propDescription}\n\n` + 'For more information, please see\n' + - `https://github.com/electron/electron-packager/blob/master/docs/api.md#${hash}\n` + `https://electron.github.io/electron-packager/master/interfaces/electronpackager.options.html#${hash}\n` } function resolvePromise (id, options) { diff --git a/test/ci/build_docs.js b/test/ci/build_docs.js new file mode 100755 index 00000000..36f277ef --- /dev/null +++ b/test/ci/build_docs.js @@ -0,0 +1,41 @@ +#!/usr/bin/env node +'use strict' + +const { Application } = require('typedoc') + +const config = { + excludeExternals: true, + excludePrivate: true, + excludeProtected: true, + includeDeclarations: true, + mode: 'file' +} + +const replaceRef = /^refs\/(head|tag)s\// + +function gitRevisionFromGitHubRef () { + const githubRef = process.env.GITHUB_REF + if (githubRef) { + return githubRef.replace(replaceRef, '') + } +} + +const gitRevision = process.argv[2] || gitRevisionFromGitHubRef() +if (gitRevision) { + if (/^[0-9a-f]+$/i.test(gitRevision)) { + config.gitRevision = gitRevision + } else if (gitRevision.startsWith('v')) { + config.includeVersion = true + } +} + +const app = new Application() +app.bootstrap(config) + +const project = app.convert(['src/index.d.ts']) +if (project) { + app.generateDocs(project, 'typedoc') +} else { + console.error('Could not generate API documentation from TypeScript definition!') + process.exit(1) +} diff --git a/usage.txt b/usage.txt index 4f1e28d8..200f3254 100644 --- a/usage.txt +++ b/usage.txt @@ -54,7 +54,7 @@ extra-resource a file to copy into the app's resources directory icon the local path to an icon file to use as the icon for the app. Note: Format depends on platform. ignore do not copy files into app whose filenames RegExp.match this string. See also: - https://github.com/electron/electron-packager/blob/master/docs/api.md#ignore + https://electron.github.io/electron-packager/master/interfaces/electronpackager.options.html#ignore and --no-prune. Can be specified multiple times no-deref-symlinks make sure symlinks are not dereferenced within the app source no-junk do not ignore system junk files from the packaged app