@todesktop/cli 1.18.0 → 1.18.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +341 -153
- package/dist/cli.js +118 -155
- package/dist/cli.js.map +3 -3
- package/dist/types.d.ts +4 -0
- package/package.json +9 -35
- package/schemas/schema.json +6 -0
package/README.md
CHANGED
|
@@ -1,14 +1,17 @@
|
|
|
1
1
|
# ToDesktop CLI
|
|
2
2
|
|
|
3
|
-
The ToDesktop CLI allows you to build and deploy your electron app with native
|
|
3
|
+
The ToDesktop CLI allows you to build and deploy your electron app with native
|
|
4
|
+
installers, auto-updates and code signing included.
|
|
4
5
|
|
|
5
|
-
For more information, visit the project
|
|
6
|
+
For more information, visit the project
|
|
7
|
+
[landing page](https://www.todesktop.com/cli).
|
|
6
8
|
|
|
7
9
|
## Table of contents
|
|
8
10
|
|
|
9
11
|
- [Installation](#installation)
|
|
10
12
|
- [Get started](#get-started)
|
|
11
13
|
- [CLI commands](#cli-commands)
|
|
14
|
+
- [Release Webhooks](#release-webhooks)
|
|
12
15
|
- [Automating your builds (CI)](#automating-your-builds-ci)
|
|
13
16
|
- [Project configuration (todesktop.json, todesktop.js, or todesktop.ts)](#project-configuration-todesktopjson-todesktopjs-or-todesktops)
|
|
14
17
|
- [Build lifecycle hooks (package.json scripts)](#build-lifecycle-hooks-packagejson-scripts)
|
|
@@ -32,7 +35,9 @@ You can use the ToDesktop CLI to work with an Electron application in 4 steps:
|
|
|
32
35
|
|
|
33
36
|
### Step 1: Create a ToDesktop application
|
|
34
37
|
|
|
35
|
-
Create a ToDesktop application to link to your Electron application. This is
|
|
38
|
+
Create a ToDesktop application to link to your Electron application. This is
|
|
39
|
+
currently done via the [web interface](http://app.todesktop.com/). Copy the
|
|
40
|
+
ToDesktop application ID to your clipboard:
|
|
36
41
|
|
|
37
42
|

|
|
38
43
|
|
|
@@ -42,7 +47,7 @@ Create a `todesktop.json` file in the root of your Electron project.
|
|
|
42
47
|
|
|
43
48
|
```json
|
|
44
49
|
{
|
|
45
|
-
"$schema": "https://unpkg.com/@todesktop/cli@1.18.
|
|
50
|
+
"$schema": "https://unpkg.com/@todesktop/cli@1.18.2/schemas/schema.json",
|
|
46
51
|
"schemaVersion": 1
|
|
47
52
|
"id": "your-todesktop-id",
|
|
48
53
|
"icon": "./desktop-icon.png",
|
|
@@ -50,42 +55,48 @@ Create a `todesktop.json` file in the root of your Electron project.
|
|
|
50
55
|
}
|
|
51
56
|
```
|
|
52
57
|
|
|
53
|
-
Alternatively, you can create a `todesktop.js` file. This allows you to use
|
|
58
|
+
Alternatively, you can create a `todesktop.js` file. This allows you to use
|
|
59
|
+
JavaScript to dynamically generate your configuration. For example:
|
|
54
60
|
|
|
55
61
|
```javascript
|
|
56
|
-
const path = require(
|
|
62
|
+
const path = require('path');
|
|
57
63
|
|
|
58
64
|
module.exports = {
|
|
59
|
-
id: process.env.TODESKTOP_APP_ID ||
|
|
60
|
-
icon: path.join(__dirname,
|
|
65
|
+
id: process.env.TODESKTOP_APP_ID || 'your-default-todesktop-id',
|
|
66
|
+
icon: path.join(__dirname, 'assets', 'desktop-icon.png'),
|
|
61
67
|
schemaVersion: 1,
|
|
62
68
|
};
|
|
63
69
|
```
|
|
64
70
|
|
|
65
|
-
You can also create a `todesktop.ts` file for TypeScript projects with full type
|
|
71
|
+
You can also create a `todesktop.ts` file for TypeScript projects with full type
|
|
72
|
+
checking and IntelliSense:
|
|
66
73
|
|
|
67
74
|
```typescript
|
|
68
|
-
import type { Schema } from
|
|
69
|
-
import path from
|
|
75
|
+
import type { Schema } from '@todesktop/cli';
|
|
76
|
+
import path from 'path';
|
|
70
77
|
|
|
71
78
|
const config: Schema = {
|
|
72
|
-
id: process.env.TODESKTOP_APP_ID ||
|
|
73
|
-
icon: path.join(__dirname,
|
|
79
|
+
id: process.env.TODESKTOP_APP_ID || 'your-default-todesktop-id',
|
|
80
|
+
icon: path.join(__dirname, 'assets', 'desktop-icon.png'),
|
|
74
81
|
schemaVersion: 1,
|
|
75
|
-
nodeVersion:
|
|
82
|
+
nodeVersion: '18.12.1',
|
|
76
83
|
mac: {
|
|
77
|
-
category:
|
|
84
|
+
category: 'public.app-category.productivity',
|
|
78
85
|
},
|
|
79
86
|
};
|
|
80
87
|
|
|
81
88
|
export default config;
|
|
82
89
|
```
|
|
83
90
|
|
|
84
|
-
See
|
|
91
|
+
See
|
|
92
|
+
[Project configuration](#project-configuration-todesktopjson-todesktopjs-or-todesktops)
|
|
93
|
+
for the full list of configuration options.
|
|
85
94
|
|
|
86
95
|
### Step 3: Add @todesktop/runtime as a dependency
|
|
87
96
|
|
|
88
|
-
The ToDesktop
|
|
97
|
+
The ToDesktop
|
|
98
|
+
[runtime package](https://www.npmjs.com/package/@todesktop/runtime) takes care
|
|
99
|
+
of auto-updating, crash reporting, and more.
|
|
89
100
|
|
|
90
101
|
```sh
|
|
91
102
|
npm install @todesktop/runtime
|
|
@@ -93,11 +104,12 @@ npm install @todesktop/runtime
|
|
|
93
104
|
yarn add @todesktop/runtime
|
|
94
105
|
```
|
|
95
106
|
|
|
96
|
-
In your main (background process) script, require the package and call the
|
|
107
|
+
In your main (background process) script, require the package and call the
|
|
108
|
+
`init` function. The key is to call it right at the beginning.
|
|
97
109
|
|
|
98
110
|
```javascript
|
|
99
|
-
const { app, BrowserWindow } = require(
|
|
100
|
-
const todesktop = require(
|
|
111
|
+
const { app, BrowserWindow } = require('electron');
|
|
112
|
+
const todesktop = require('@todesktop/runtime');
|
|
101
113
|
|
|
102
114
|
todesktop.init();
|
|
103
115
|
|
|
@@ -109,7 +121,7 @@ function createWindow() {
|
|
|
109
121
|
});
|
|
110
122
|
|
|
111
123
|
// and load the index.html of the app.
|
|
112
|
-
win.loadFile(
|
|
124
|
+
win.loadFile('index.html');
|
|
113
125
|
}
|
|
114
126
|
|
|
115
127
|
app.whenReady().then(createWindow);
|
|
@@ -117,13 +129,16 @@ app.whenReady().then(createWindow);
|
|
|
117
129
|
|
|
118
130
|
### Step 4: Build your app
|
|
119
131
|
|
|
120
|
-
To build your app, run the following command inside the root of your Electron
|
|
132
|
+
To build your app, run the following command inside the root of your Electron
|
|
133
|
+
project:
|
|
121
134
|
|
|
122
135
|
```sh
|
|
123
136
|
todesktop build
|
|
124
137
|
```
|
|
125
138
|
|
|
126
|
-
When prompted to login, use your email address and the accessToken from our
|
|
139
|
+
When prompted to login, use your email address and the accessToken from our
|
|
140
|
+
dashboard. You can retrieve your access token by clicking on your name in the
|
|
141
|
+
top right corner of the dashboard and selecting "Manage Access Token".
|
|
127
142
|
|
|
128
143
|
Once built, your app can then be downloaded and tested.
|
|
129
144
|
|
|
@@ -153,7 +168,9 @@ The main command:
|
|
|
153
168
|
todesktop build
|
|
154
169
|
```
|
|
155
170
|
|
|
156
|
-
This builds your Electron app with native installers, code signing, and so on
|
|
171
|
+
This builds your Electron app with native installers, code signing, and so on
|
|
172
|
+
baked-in. Once the build has succeeded, you should see the following output in
|
|
173
|
+
your terminal. These are links to the download binaries for each platform:
|
|
157
174
|
|
|
158
175
|
```sh
|
|
159
176
|
> ✅ ToDesktop Quick Start v1.0.0
|
|
@@ -166,47 +183,60 @@ This builds your Electron app with native installers, code signing, and so on ba
|
|
|
166
183
|
|
|
167
184
|
We also support:
|
|
168
185
|
|
|
169
|
-
- `todesktop build --code-sign=false`. Run a build with code-signing and
|
|
170
|
-
|
|
171
|
-
- `todesktop build --
|
|
172
|
-
|
|
173
|
-
- `todesktop build --
|
|
174
|
-
|
|
186
|
+
- `todesktop build --code-sign=false`. Run a build with code-signing and
|
|
187
|
+
notarization disabled. This is handy for testing builds quickly.
|
|
188
|
+
- `todesktop build --config=<path.to.config.file>`. Run a build with a different
|
|
189
|
+
configuration file (e.g., `todesktop.staging.json` or `todesktop.prod.js`).
|
|
190
|
+
- `todesktop build --async`. Run a build in the background. This is handy for CI
|
|
191
|
+
environments.
|
|
192
|
+
- `todesktop build --webhook URL`. Send a POST request to the webhook URL when
|
|
193
|
+
the build is finished. It's especially useful together with the `--async`
|
|
194
|
+
flag.
|
|
195
|
+
- `todesktop build --ignore-extends-errors`. Ignore `id` and `appId` validation
|
|
196
|
+
errors when extending another configuration file (`.json` or `.js`).
|
|
197
|
+
- `todesktop release`. Release a build. This will publish a new download and an
|
|
198
|
+
auto-update for existing users. By default it shows a list of builds for you
|
|
199
|
+
to choose from.
|
|
175
200
|
- Use `todesktop release <id>` to release a specific build by ID.
|
|
176
201
|
- `todesktop release --latest` will release the latest build.
|
|
177
202
|
- Append `--force` to skip the interactive confirmation step.
|
|
178
|
-
- Append `--config=<path.to.config.file>` to use a different configuration
|
|
203
|
+
- Append `--config=<path.to.config.file>` to use a different configuration
|
|
204
|
+
file.
|
|
205
|
+
- **Note:** By default, apps can not be released via the CLI. For security
|
|
206
|
+
reasons, you can only release apps through the
|
|
207
|
+
[web UI](https://app.todesktop.com) with security token authentication. If
|
|
208
|
+
you wish to enable CLI releases, please contact support with your app ID.
|
|
179
209
|
- `todesktop builds`. View your recent builds.
|
|
180
210
|
- Use `todesktop builds <id>` to view a specific build and its progress.
|
|
181
211
|
- `todesktop builds --latest` will show the latest build and it's progress.
|
|
182
212
|
- `todesktop builds --count=<number>` will show the last `<number>` builds.
|
|
183
213
|
- `todesktop builds --format=json` will output build data in JSON format.
|
|
184
|
-
- Append `--config=<path.to.config.file>` to use a different configuration
|
|
185
|
-
|
|
214
|
+
- Append `--config=<path.to.config.file>` to use a different configuration
|
|
215
|
+
file.
|
|
216
|
+
- Append `--exit` to disable dynamic pagination and exit the process once the
|
|
217
|
+
build data has been displayed.
|
|
186
218
|
- `todesktop logout`. Logs you out.
|
|
187
|
-
- `todesktop smoke-test` Check whether the build works and can be successfully
|
|
219
|
+
- `todesktop smoke-test` Check whether the build works and can be successfully
|
|
220
|
+
updated.
|
|
188
221
|
- Use `todesktop smoke-test <id>` to test a specific build by ID.
|
|
189
222
|
- `todesktop smoke-test --latest` will test the latest build.
|
|
190
|
-
- Append `--config=<path.to.config.file>` to use a different configuration
|
|
223
|
+
- Append `--config=<path.to.config.file>` to use a different configuration
|
|
224
|
+
file.
|
|
191
225
|
- `todesktop whoami`. Prints the email of the account you're signed into.
|
|
192
226
|
- `todesktop --help`. Shows the help documentation.
|
|
193
227
|
- `todesktop --version`. Shows the current version of the CLI.
|
|
194
228
|
|
|
195
229
|
## Automating your builds (CI)
|
|
196
230
|
|
|
197
|
-
You may want to automate builds with your Continuous Integration (CI) provider.
|
|
231
|
+
You may want to automate builds with your Continuous Integration (CI) provider.
|
|
232
|
+
To achieve this, simply set up environment variables for
|
|
233
|
+
`TODESKTOP_ACCESS_TOKEN` and `TODESKTOP_EMAIL` within your CI project.
|
|
198
234
|
|
|
199
235
|
```
|
|
200
236
|
TODESKTOP_ACCESS_TOKEN=accessToken
|
|
201
237
|
TODESKTOP_EMAIL=email
|
|
202
238
|
```
|
|
203
239
|
|
|
204
|
-
To build and release in one step, you can execute:
|
|
205
|
-
|
|
206
|
-
```sh
|
|
207
|
-
todesktop build && todesktop release --latest --force
|
|
208
|
-
```
|
|
209
|
-
|
|
210
240
|
If you need to run a build in the background, you can use the `--async` flag. To
|
|
211
241
|
get notified when the build is finished you can optionally specify a webhook URL
|
|
212
242
|
which will receive a POST request with the build data:
|
|
@@ -239,27 +269,44 @@ The webhook receives a POST request with the following JSON body:
|
|
|
239
269
|
}
|
|
240
270
|
```
|
|
241
271
|
|
|
272
|
+
## Release Webhooks
|
|
273
|
+
|
|
274
|
+
You can configure a webhook URL to receive notifications when a release is
|
|
275
|
+
published. This is useful for triggering downstream processes like deployment
|
|
276
|
+
pipelines or notifications.
|
|
277
|
+
|
|
278
|
+
You can read about how to do this in
|
|
279
|
+
[our release webhooks guide](https://www.todesktop.com/electron/docs/guides/release-webhooks).
|
|
280
|
+
|
|
242
281
|
## Project configuration (todesktop.json, todesktop.js, or todesktop.ts)
|
|
243
282
|
|
|
244
|
-
This describes all of the possible configuration options in your
|
|
283
|
+
This describes all of the possible configuration options in your
|
|
284
|
+
`todesktop.json`, `todesktop.js`, or `todesktop.ts` file.
|
|
245
285
|
|
|
246
286
|
You can use:
|
|
247
287
|
|
|
248
288
|
- A standard JSON file (`todesktop.json`) for static configuration
|
|
249
|
-
- A JavaScript file (`todesktop.js`) that exports a configuration object for
|
|
250
|
-
|
|
289
|
+
- A JavaScript file (`todesktop.js`) that exports a configuration object for
|
|
290
|
+
dynamic configuration
|
|
291
|
+
- A TypeScript file (`todesktop.ts`) that exports a configuration object with
|
|
292
|
+
full type checking and IntelliSense
|
|
251
293
|
|
|
252
|
-
Using `.js` or `.ts` files allows for dynamic configuration, such as setting
|
|
294
|
+
Using `.js` or `.ts` files allows for dynamic configuration, such as setting
|
|
295
|
+
values based on environment variables or computing paths.
|
|
253
296
|
|
|
254
297
|
**Note:**
|
|
255
298
|
|
|
256
|
-
- Schema validation and IntelliSense for `.json` files are available through the
|
|
257
|
-
|
|
258
|
-
- TypeScript
|
|
299
|
+
- Schema validation and IntelliSense for `.json` files are available through the
|
|
300
|
+
JSON schema (described under [Installation](#installation))
|
|
301
|
+
- TypeScript files (`.ts`) provide full type checking and IntelliSense when
|
|
302
|
+
using the exported `Schema` type from `@todesktop/cli`
|
|
303
|
+
- TypeScript compilation requires a local installation of TypeScript in your
|
|
304
|
+
project
|
|
259
305
|
|
|
260
306
|
To avoid confusion, the following terms will be used throughout this file:
|
|
261
307
|
|
|
262
|
-
- "Project root": this is the parent directory of your `todesktop.json`,
|
|
308
|
+
- "Project root": this is the parent directory of your `todesktop.json`,
|
|
309
|
+
`todesktop.js`, or `todesktop.ts`.
|
|
263
310
|
|
|
264
311
|
### `$schema` - (optional) string
|
|
265
312
|
|
|
@@ -272,7 +319,7 @@ To enable JSON validation and IntelliSense for your `todesktop.json` file in com
|
|
|
272
319
|
- For example, if using a hosted version of the schema:
|
|
273
320
|
```json
|
|
274
321
|
{
|
|
275
|
-
"$schema": "https://unpkg.com/@todesktop/cli@1.18.
|
|
322
|
+
"$schema": "https://unpkg.com/@todesktop/cli@1.18.2/schemas/schema.json",
|
|
276
323
|
"id": "your-todesktop-id"
|
|
277
324
|
}
|
|
278
325
|
```
|
|
@@ -292,7 +339,10 @@ Example: `["dist/**", "!static/**"]`
|
|
|
292
339
|
|
|
293
340
|
This option allows you to decide which files get uploaded to be built on the ToDesktop servers. By default, all files in your app path are included in your app, except for `node_modules` and `.git`. Dependencies are installed on our build servers as there could be platform-specific postinstall steps.
|
|
294
341
|
|
|
295
|
-
If you wish to include files for the build process but exclude them in the
|
|
342
|
+
If you wish to include files for the build process but exclude them in the
|
|
343
|
+
distribution version of your app then you should use the
|
|
344
|
+
[`filesForDistribution`](#filesForDistribution---optional-array-of-glob-patterns)
|
|
345
|
+
property
|
|
296
346
|
|
|
297
347
|
The files must be within your [`appPath`](#apppath---optional-string).
|
|
298
348
|
|
|
@@ -308,15 +358,20 @@ The following are always included if they exist:
|
|
|
308
358
|
|
|
309
359
|
- Asterisk (`*`) — matches everything except slashes (path separators).
|
|
310
360
|
- A double star or globstar (`**`) — matches zero or more directories.
|
|
311
|
-
- Question mark (`?`) – matches any single character except slashes (path
|
|
312
|
-
|
|
361
|
+
- Question mark (`?`) – matches any single character except slashes (path
|
|
362
|
+
separators).
|
|
363
|
+
- Exclamation mark (`!`) — a glob that starts with an exclamation mark will
|
|
364
|
+
result in any matched files being excluded.
|
|
313
365
|
|
|
314
366
|
Examples:
|
|
315
367
|
|
|
316
|
-
- `src/**/*.js` — matches all files in the src directory (any level of nesting)
|
|
317
|
-
|
|
368
|
+
- `src/**/*.js` — matches all files in the src directory (any level of nesting)
|
|
369
|
+
that have the `.js` extension.
|
|
370
|
+
- `src/*.??` — matches all files in the src directory (only first level of
|
|
371
|
+
nesting) that have a two-character extension.
|
|
318
372
|
|
|
319
|
-
We use the [fast-glob](https://www.npmjs.com/package/fast-glob) library under
|
|
373
|
+
We use the [fast-glob](https://www.npmjs.com/package/fast-glob) library under
|
|
374
|
+
the hood.
|
|
320
375
|
|
|
321
376
|
### `appId` - (optional) string
|
|
322
377
|
|
|
@@ -326,7 +381,8 @@ Example: `com.microsoft.word`
|
|
|
326
381
|
|
|
327
382
|
Your application ID. Omit this unless you know what you're doing. It's used as the [CFBundleIdentifier](https://developer.apple.com/library/ios/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html#//apple_ref/doc/uid/20001431-102070) for MacOS and as the [Application User Model ID](<https://msdn.microsoft.com/en-us/library/windows/desktop/dd378459(v=vs.85).aspx>) for Windows.
|
|
328
383
|
|
|
329
|
-
WARNING: if you have deployed an application with ToDesktop and would like to
|
|
384
|
+
WARNING: if you have deployed an application with ToDesktop and would like to
|
|
385
|
+
change this ID, talk to us first.
|
|
330
386
|
|
|
331
387
|
### `appPath` - (optional) string
|
|
332
388
|
|
|
@@ -336,13 +392,17 @@ Example: `./dist`
|
|
|
336
392
|
|
|
337
393
|
This is the path to your Electron application directory. Omit this unless your project setup is complicated. This is the directory that the CLI uploads.
|
|
338
394
|
|
|
339
|
-
The path can be absolute or a relative path from the project root. The directory
|
|
395
|
+
The path can be absolute or a relative path from the project root. The directory
|
|
396
|
+
it points to must be a valid Electron application directory; i.e.:
|
|
340
397
|
|
|
341
398
|
- It could be ran with the `electron` command; i.e. `npx electron {{appPath}}`.
|
|
342
399
|
- It needs to contain a valid `package.json`.
|
|
343
|
-
- The `package.json` must either have a `main` property pointing to a file in
|
|
400
|
+
- The `package.json` must either have a `main` property pointing to a file in
|
|
401
|
+
the directory or there must be an `index.js` at the root of the directory.
|
|
344
402
|
|
|
345
|
-
Side note: if your `package.json` contains a `postinstall` script which
|
|
403
|
+
Side note: if your `package.json` contains a `postinstall` script which
|
|
404
|
+
references scripts, these must be accessible within the `appPath` directory as
|
|
405
|
+
only the `appPath` is uploaded to our servers.
|
|
346
406
|
|
|
347
407
|
### `bundleWorkspacePackages` - (optional) object
|
|
348
408
|
|
|
@@ -401,7 +461,8 @@ Default: `["**/*.node"]`
|
|
|
401
461
|
|
|
402
462
|
This option allows you to decide which files get unpacked from the asar archive. By default we unpack all native `*.node` files.
|
|
403
463
|
|
|
404
|
-
If you want to unpack only files that are required to be unpacked, you can set
|
|
464
|
+
If you want to unpack only files that are required to be unpacked, you can set
|
|
465
|
+
this property to `false`.
|
|
405
466
|
|
|
406
467
|
You can also specify a list of glob patterns to unpack.
|
|
407
468
|
|
|
@@ -425,13 +486,15 @@ Options for customizing the macOS DMG (disk image) installer.
|
|
|
425
486
|
|
|
426
487
|
#### `dmg.background` - (optional) string
|
|
427
488
|
|
|
428
|
-
Default: `undefined` (if `undefined` then we
|
|
489
|
+
Default: `undefined` (if `undefined` then we
|
|
490
|
+
use [this template](https://i.imgur.com/PUQIhvv.png)).
|
|
429
491
|
|
|
430
492
|
Example: `./mac-dmg-background.tiff`
|
|
431
493
|
|
|
432
494
|
The path to the DMG installer's background image. It must be a `.tiff` file. The resolution of this file determines the resolution of the installer window. Typically, backgrounds are 540x380.
|
|
433
495
|
|
|
434
|
-
You can generate a retina tiff background from png files using the following
|
|
496
|
+
You can generate a retina tiff background from png files using the following
|
|
497
|
+
command:
|
|
435
498
|
|
|
436
499
|
```sh
|
|
437
500
|
tiffutil -cathidpicheck background.png background@2x.png -out background.tiff
|
|
@@ -465,8 +528,10 @@ The title of the produced DMG, which will be shown when mounted (volume name). M
|
|
|
465
528
|
|
|
466
529
|
Customize icon locations. The x and y coordinates refer to the position of the center of the icon (at 1x scale), and do not take the label into account.
|
|
467
530
|
|
|
468
|
-
- `x` number -
|
|
469
|
-
|
|
531
|
+
- `x` number -
|
|
532
|
+
The device-independent pixel offset from the left of the window to the center of the icon.
|
|
533
|
+
- `y` number -
|
|
534
|
+
The device-independent pixel offset from the top of the window to the center of the icon.
|
|
470
535
|
|
|
471
536
|
```
|
|
472
537
|
[
|
|
@@ -489,8 +554,10 @@ The DMG windows position and size. In most cases, you will only want to specify
|
|
|
489
554
|
|
|
490
555
|
- `x` number - The X position relative to left of the screen.
|
|
491
556
|
- `y` number - The Y position relative to top of the screen.
|
|
492
|
-
- `width` number -
|
|
493
|
-
|
|
557
|
+
- `width` number -
|
|
558
|
+
The width. Defaults to background image width or 540.
|
|
559
|
+
- `height` number -
|
|
560
|
+
The height. Defaults to background image height or 380.
|
|
494
561
|
|
|
495
562
|
```
|
|
496
563
|
{
|
|
@@ -505,9 +572,13 @@ Default: `null`.
|
|
|
505
572
|
|
|
506
573
|
Example: `./todesktop.base.json` or `./todesktop.base.js`.
|
|
507
574
|
|
|
508
|
-
This is the path to a base configuration file (`.json` or `.js`). This is
|
|
575
|
+
This is the path to a base configuration file (`.json` or `.js`). This is
|
|
576
|
+
especially useful for configuration sharing between different environments
|
|
577
|
+
(e.g., staging and production). The base configuration file can be a relative
|
|
578
|
+
path from the project root or an absolute path.
|
|
509
579
|
|
|
510
|
-
For more information about how to create a staging version of your app see:
|
|
580
|
+
For more information about how to create a staging version of your app see:
|
|
581
|
+
[How do I create a staging version of my app?](#how-do-i-create-a-staging-version-of-my-app).
|
|
511
582
|
|
|
512
583
|
### `extraContentFiles` - (optional) array of objects
|
|
513
584
|
|
|
@@ -515,9 +586,13 @@ Default: `[]`
|
|
|
515
586
|
|
|
516
587
|
This option allows you specify files to be copied into the application's content directory (`Contents` for MacOS, root directory for Linux and Windows).
|
|
517
588
|
|
|
518
|
-
Each item in the array must be an object, containing a `from` property which is
|
|
589
|
+
Each item in the array must be an object, containing a `from` property which is
|
|
590
|
+
a path to a file or directory. The path can be absolute or a relative path from
|
|
591
|
+
the project root. The files specified must be inside your project root. A
|
|
592
|
+
directory's contents are copied, not the directory itself (see example below).
|
|
519
593
|
|
|
520
|
-
The `to` property is optional. Use it to specify a directory inside the content
|
|
594
|
+
The `to` property is optional. Use it to specify a directory inside the content
|
|
595
|
+
directory to copy the file to.
|
|
521
596
|
|
|
522
597
|
Example:
|
|
523
598
|
|
|
@@ -529,7 +604,11 @@ Example:
|
|
|
529
604
|
]
|
|
530
605
|
```
|
|
531
606
|
|
|
532
|
-
In the example above, `image.png` would be copied to the root of the content
|
|
607
|
+
In the example above, `image.png` would be copied to the root of the content
|
|
608
|
+
directory, whereas `anotherImage.png` would be copied to an `images` directory
|
|
609
|
+
at the root of the content directory. The contents of the `./static` directory
|
|
610
|
+
would be copied to `assets` in the content directory (i.e.
|
|
611
|
+
`./static/example.txt` would be copied to `assets/example.txt`).
|
|
533
612
|
|
|
534
613
|
### `electronMirror` - (optional) string
|
|
535
614
|
|
|
@@ -578,14 +657,21 @@ Example:
|
|
|
578
657
|
]
|
|
579
658
|
```
|
|
580
659
|
|
|
581
|
-
- `ext` String | String[] -
|
|
582
|
-
|
|
583
|
-
- `
|
|
660
|
+
- `ext` String | String[] -
|
|
661
|
+
The extension (minus the leading period). e.g. png.
|
|
662
|
+
- `name` String -
|
|
663
|
+
The name. e.g. PNG. Defaults to value of `ext`.
|
|
664
|
+
- `description` String -
|
|
665
|
+
windows-only. The description.
|
|
584
666
|
- `icon` String - macOS and windows. Icon file name without extension. It points to ico file for Windows and icns for macOS. For example, if the `icon` value is `"icons/py"` then it will look for both `"icons/py.ico"` and `"icons/py.icns"` in your project directory.
|
|
585
|
-
- `mimeType` String -
|
|
586
|
-
-
|
|
587
|
-
- `
|
|
588
|
-
|
|
667
|
+
- `mimeType` String -
|
|
668
|
+
linux-only. The mime-type.
|
|
669
|
+
- `role` = `Default: `Editor`` String -
|
|
670
|
+
macOS-only. The app's role with respect to the type. The value can be `Editor`, `Viewer`, `Shell`, or `None`. Corresponds to `CFBundleTypeRole`.
|
|
671
|
+
- `isPackage` Boolean -
|
|
672
|
+
macOS-only. Whether the document is distributed as a bundle. If set to true, the bundle directory is treated as a file. Corresponds to `LSTypeIsPackage`.
|
|
673
|
+
- `rank` = `Default: `Default`` String -
|
|
674
|
+
macOS-only. Determines how Launch Services ranks this app among the apps that declare themselves editors or viewers of files of this type. The possible values are: `Owner` (this app is the primary creator of files of this type), `Default` (this app is an opener of files of this type; this value is also used if no rank is specified), `Alternate` (this app is a secondary viewer of files of this type), and `None` (this app is never selected to open files of this type, but it accepts drops of files of this type).
|
|
589
675
|
|
|
590
676
|
### `filesForDistribution` - (optional) array of glob patterns
|
|
591
677
|
|
|
@@ -593,7 +679,8 @@ Example: `["!**/node_modules/realm/android/**", "!**/design/**"]`
|
|
|
593
679
|
|
|
594
680
|
This option allows you to explicitly exclude or include certain files in the packaged version of your app. These files are filtered _after_ the build step which happens on the ToDesktop servers.
|
|
595
681
|
|
|
596
|
-
This is often useful for excluding large files which are installed during the
|
|
682
|
+
This is often useful for excluding large files which are installed during the
|
|
683
|
+
build step but are not needed at runtime by your applcation.
|
|
597
684
|
|
|
598
685
|
The following are always excluded if they exist:
|
|
599
686
|
|
|
@@ -615,7 +702,10 @@ Example: `./appIcon.png`
|
|
|
615
702
|
|
|
616
703
|
The path to your application's desktop icon. It must be an ICNS or PNG.
|
|
617
704
|
|
|
618
|
-
Note: to ensure the icon is never missing (e.g. this happens sometimes in
|
|
705
|
+
Note: to ensure the icon is never missing (e.g. this happens sometimes in
|
|
706
|
+
Ubuntu), set the
|
|
707
|
+
[`icon` option](https://www.electronjs.org/docs/api/browser-window#new-browserwindowoptions)
|
|
708
|
+
when creating your `BrowserWindow`s.
|
|
619
709
|
|
|
620
710
|
### `id` - string
|
|
621
711
|
|
|
@@ -649,7 +739,10 @@ The path to your application's Linux desktop icon. It must be an ICNS or PNG.
|
|
|
649
739
|
|
|
650
740
|
Default: The root [`icon`](#icon---string) is used.
|
|
651
741
|
|
|
652
|
-
Note: to ensure the icon is never missing (e.g. this happens sometimes in
|
|
742
|
+
Note: to ensure the icon is never missing (e.g. this happens sometimes in
|
|
743
|
+
Ubuntu), set the
|
|
744
|
+
[`icon` option](https://www.electronjs.org/docs/api/browser-window#new-browserwindowoptions)
|
|
745
|
+
when creating your `BrowserWindow`s.
|
|
653
746
|
|
|
654
747
|
#### `linux.imageVersion` - (optional) string
|
|
655
748
|
|
|
@@ -661,7 +754,10 @@ The version of the Linux image that ToDesktop should use to build your app.
|
|
|
661
754
|
|
|
662
755
|
Linux Changelog:
|
|
663
756
|
|
|
664
|
-
- `0.1.0`: Updated g++ → g++10, gcc → gcc10. WARNING: This compiler has been
|
|
757
|
+
- `0.1.0`: Updated g++ → g++10, gcc → gcc10. WARNING: This compiler has been
|
|
758
|
+
updated to a newer version that is not compatible with older versions of Linux
|
|
759
|
+
like Ubuntu 20.04. You should probably only use this version if you know what
|
|
760
|
+
you're doing.
|
|
665
761
|
- `0.0.11`: Updated git 2.25.1 → 2.47.1 node 18.18.2 → 18.20.5
|
|
666
762
|
|
|
667
763
|
### `linux.noSandbox` - (optional) boolean
|
|
@@ -670,7 +766,8 @@ Default: `true`
|
|
|
670
766
|
|
|
671
767
|
This option allows you to configure whether your app should run in a sandboxed environment.
|
|
672
768
|
|
|
673
|
-
We default this to `true` for compatibility reasons because some Linux
|
|
769
|
+
We default this to `true` for compatibility reasons because some Linux
|
|
770
|
+
distributions do not support unprivileged user namespaces.
|
|
674
771
|
|
|
675
772
|
### `includeSubNodeModules` - (optional) boolean
|
|
676
773
|
|
|
@@ -702,9 +799,11 @@ Example: `public.app-category.productivity`
|
|
|
702
799
|
|
|
703
800
|
The application category type, as shown in the Finder via _View -> Arrange by Application Category_ when viewing the Applications directory.
|
|
704
801
|
|
|
705
|
-
For example, `public.app-category.developer-tools` will set the application
|
|
802
|
+
For example, `public.app-category.developer-tools` will set the application
|
|
803
|
+
category to "Developer Tools".
|
|
706
804
|
|
|
707
|
-
Valid values are listed in
|
|
805
|
+
Valid values are listed in
|
|
806
|
+
[Apple's documentation](https://developer.apple.com/library/ios/documentation/General/Reference/InfoPlistKeyReference/Articles/LaunchServicesKeys.html#//apple_ref/doc/uid/TP40009250-SW8).
|
|
708
807
|
|
|
709
808
|
#### `mac.entitlements` - (optional) string
|
|
710
809
|
|
|
@@ -786,6 +885,12 @@ Example: `distribution`
|
|
|
786
885
|
|
|
787
886
|
Whether to sign app for development or for distribution.
|
|
788
887
|
|
|
888
|
+
#### `mas.minimumSystemVersion` - (optional) string
|
|
889
|
+
|
|
890
|
+
Example: `12.0`, `11.0`, `10.15`
|
|
891
|
+
|
|
892
|
+
The minimum macOS version required to run the app. Set to '12.0' or higher for arm64-only Mac App Store submissions.
|
|
893
|
+
|
|
789
894
|
### `mas.x64ArchFiles` - (optional) string
|
|
790
895
|
|
|
791
896
|
Default: not defined
|
|
@@ -825,7 +930,9 @@ Example:
|
|
|
825
930
|
}
|
|
826
931
|
```
|
|
827
932
|
|
|
828
|
-
You can also set the version of a `dependency` (or `devDependency`), such as
|
|
933
|
+
You can also set the version of a `dependency` (or `devDependency`), such as
|
|
934
|
+
Electron Builder, to `null`. This will remove Electron Builder from the
|
|
935
|
+
effective `package.json` that ToDesktop will use.
|
|
829
936
|
|
|
830
937
|
```js
|
|
831
938
|
"packageJson": {
|
|
@@ -956,7 +1063,8 @@ Example: `[ "default", { "browser-sandbox": { "interface": "browser-support", "a
|
|
|
956
1063
|
|
|
957
1064
|
The list of [plugs](https://snapcraft.io/docs/reference/interfaces). If list contains `default`, it will be replaced with the default list, so, `["default", "foo"]` can be used to add a custom plug `foo` in addition to the default list.
|
|
958
1065
|
|
|
959
|
-
Additional attributes can be specified using object instead of just name of
|
|
1066
|
+
Additional attributes can be specified using object instead of just name of
|
|
1067
|
+
plug:
|
|
960
1068
|
|
|
961
1069
|
```json
|
|
962
1070
|
[
|
|
@@ -1102,7 +1210,10 @@ Example:
|
|
|
1102
1210
|
}
|
|
1103
1211
|
```
|
|
1104
1212
|
|
|
1105
|
-
When a build is performed for a specific platform (e.g., Windows), the ToDesktop
|
|
1213
|
+
When a build is performed for a specific platform (e.g., Windows), the ToDesktop
|
|
1214
|
+
CLI will first take the global configuration value for a field. If that same
|
|
1215
|
+
field is defined within `platformOverrides.windows`, the platform-specific value
|
|
1216
|
+
will be used instead.
|
|
1106
1217
|
|
|
1107
1218
|
In the example above:
|
|
1108
1219
|
|
|
@@ -1115,23 +1226,32 @@ In the example above:
|
|
|
1115
1226
|
- For Linux builds:
|
|
1116
1227
|
- `appId` will remain `myapp.global.id` (as it's not overridden for Linux).
|
|
1117
1228
|
- `copyright` will be `Copyright © My Company (Linux)`.
|
|
1118
|
-
- For any other properties not specified in the platform override, the global
|
|
1229
|
+
- For any other properties not specified in the platform override, the global
|
|
1230
|
+
value will be used.
|
|
1119
1231
|
|
|
1120
|
-
This is particularly useful for settings like `appId`, `copyright`, or
|
|
1232
|
+
This is particularly useful for settings like `appId`, `copyright`, or
|
|
1233
|
+
platform-specific configurations within the `windows`, `mac`, or `linux` blocks
|
|
1234
|
+
(e.g., `mac.category`, `windows.icon`).
|
|
1121
1235
|
|
|
1122
1236
|
The fields that **cannot** be overridden using `platformOverrides` are:
|
|
1123
1237
|
|
|
1124
1238
|
- `id` (the ToDesktop application ID)
|
|
1125
|
-
- `icon` (the main application icon, though platform-specific icons like
|
|
1239
|
+
- `icon` (the main application icon, though platform-specific icons like
|
|
1240
|
+
`windows.icon` or `mac.icon` _can_ be overridden)
|
|
1126
1241
|
- `schemaVersion`
|
|
1127
1242
|
- `extends`
|
|
1128
1243
|
- `platformOverrides` itself
|
|
1129
1244
|
|
|
1130
1245
|
## Build lifecycle hooks (package.json scripts)
|
|
1131
1246
|
|
|
1132
|
-
Sometimes you want to do something before or during the build process. For
|
|
1247
|
+
Sometimes you want to do something before or during the build process. For
|
|
1248
|
+
example, you might want to run a script before the build starts, or you might
|
|
1249
|
+
want to run a script after the files have been packaged. Our lifecycle hooks
|
|
1250
|
+
provide a way to do this.
|
|
1133
1251
|
|
|
1134
|
-
To specify a script, add a `scripts` property to your `package.json` file. The
|
|
1252
|
+
To specify a script, add a `scripts` property to your `package.json` file. The
|
|
1253
|
+
key is the name of the script (prefixed by `todesktop:`), and the value is the
|
|
1254
|
+
path to the script.
|
|
1135
1255
|
|
|
1136
1256
|
```json
|
|
1137
1257
|
{
|
|
@@ -1160,7 +1280,8 @@ module.exports = async ({ pkgJsonPath, pkgJson, appDir, hookName }) => {
|
|
|
1160
1280
|
|
|
1161
1281
|
Example: `./scripts/beforeBuild.js`.
|
|
1162
1282
|
|
|
1163
|
-
The path to a script that will run before dependencies are rebuilt for target
|
|
1283
|
+
The path to a script that will run before dependencies are rebuilt for target
|
|
1284
|
+
architectures.
|
|
1164
1285
|
|
|
1165
1286
|
Example script:
|
|
1166
1287
|
|
|
@@ -1175,10 +1296,10 @@ module.exports = async ({
|
|
|
1175
1296
|
arch,
|
|
1176
1297
|
hookName,
|
|
1177
1298
|
}) => {
|
|
1178
|
-
if (arch ===
|
|
1179
|
-
process.env.VARIABLE =
|
|
1299
|
+
if (arch === 'arm64') {
|
|
1300
|
+
process.env.VARIABLE = 'value';
|
|
1180
1301
|
} else {
|
|
1181
|
-
process.env.VARIABLE =
|
|
1302
|
+
process.env.VARIABLE = 'alternative-value';
|
|
1182
1303
|
}
|
|
1183
1304
|
};
|
|
1184
1305
|
```
|
|
@@ -1192,11 +1313,11 @@ The path to a script that will be run before the build starts.
|
|
|
1192
1313
|
Example script:
|
|
1193
1314
|
|
|
1194
1315
|
```js
|
|
1195
|
-
const { writeFile } = require(
|
|
1316
|
+
const { writeFile } = require('fs/promises');
|
|
1196
1317
|
|
|
1197
1318
|
// Delete `internal` dependency from package.json
|
|
1198
1319
|
module.exports = async ({ pkgJsonPath, pkgJson, appDir, hookName }) => {
|
|
1199
|
-
delete pkgJson.dependencies[
|
|
1320
|
+
delete pkgJson.dependencies['internal'];
|
|
1200
1321
|
await writeFile(pkgJsonPath, JSON.stringify(pkgJson, null, 2));
|
|
1201
1322
|
};
|
|
1202
1323
|
```
|
|
@@ -1205,9 +1326,12 @@ module.exports = async ({ pkgJsonPath, pkgJson, appDir, hookName }) => {
|
|
|
1205
1326
|
|
|
1206
1327
|
Example: `./scripts/afterPack.js`.
|
|
1207
1328
|
|
|
1208
|
-
The path to a script that will be run after the app has been packed (but
|
|
1329
|
+
The path to a script that will be run after the app has been packed (but
|
|
1330
|
+
_before_ it has been transformed into a distributable installer format and
|
|
1331
|
+
signed).
|
|
1209
1332
|
|
|
1210
|
-
The `afterPack` function also has the following arguments added to it's
|
|
1333
|
+
The `afterPack` function also has the following arguments added to it's
|
|
1334
|
+
signature:
|
|
1211
1335
|
|
|
1212
1336
|
- appPkgName - string - the name of the app package
|
|
1213
1337
|
- appId - string - the app id
|
|
@@ -1215,21 +1339,22 @@ The `afterPack` function also has the following arguments added to it's signatur
|
|
|
1215
1339
|
- outDir - string - the path to the output directory
|
|
1216
1340
|
- appOutDir - string - the path to the app output directory
|
|
1217
1341
|
- packager - object - the packager object
|
|
1218
|
-
- arch - number - the architecture of the app. `ia32 = 0`, `x64 = 1`,
|
|
1342
|
+
- arch - number - the architecture of the app. `ia32 = 0`, `x64 = 1`,
|
|
1343
|
+
`armv7l = 2`, `arm64 = 3`, `universal = 4`.
|
|
1219
1344
|
|
|
1220
1345
|
Example script:
|
|
1221
1346
|
|
|
1222
1347
|
```js
|
|
1223
|
-
const { writeFile } = require(
|
|
1348
|
+
const { writeFile } = require('fs/promises');
|
|
1224
1349
|
|
|
1225
1350
|
// Add a copyright file inside of the app directory on Mac only
|
|
1226
1351
|
module.exports = async ({ appOutDir, packager }) => {
|
|
1227
|
-
if (os.platform() ===
|
|
1352
|
+
if (os.platform() === 'darwin') {
|
|
1228
1353
|
const appName = packager.appInfo.productFilename;
|
|
1229
1354
|
const appPath = path.join(`${appOutDir}`, `${appName}.app`);
|
|
1230
1355
|
await writeFile(
|
|
1231
|
-
path.join(appPath,
|
|
1232
|
-
`Copyright © ${new Date().getFullYear()} ${appName}
|
|
1356
|
+
path.join(appPath, 'copyright.txt'),
|
|
1357
|
+
`Copyright © ${new Date().getFullYear()} ${appName}`,
|
|
1233
1358
|
);
|
|
1234
1359
|
}
|
|
1235
1360
|
};
|
|
@@ -1237,59 +1362,86 @@ module.exports = async ({ appOutDir, packager }) => {
|
|
|
1237
1362
|
|
|
1238
1363
|
## App package.json requirements
|
|
1239
1364
|
|
|
1240
|
-
- Electron must be in your `devDependencies` and it must be a fixed version.
|
|
1241
|
-
|
|
1365
|
+
- Electron must be in your `devDependencies` and it must be a fixed version.
|
|
1366
|
+
I.e. it doesn't start with `^` or `~`.
|
|
1367
|
+
- You must set the
|
|
1368
|
+
[`author` property](https://docs.npmjs.com/files/package.json#people-fields-author-contributors).
|
|
1242
1369
|
|
|
1243
1370
|
### Recommendations for app package.json
|
|
1244
1371
|
|
|
1245
|
-
- You should set the `productName` property. Otherwise, your app name will
|
|
1372
|
+
- You should set the `productName` property. Otherwise, your app name will
|
|
1373
|
+
default to the value of the `name` property.
|
|
1246
1374
|
|
|
1247
1375
|
## FAQs
|
|
1248
1376
|
|
|
1249
1377
|
### One of my dependencies is a private package. How do I safely use it with ToDesktop CLI
|
|
1250
1378
|
|
|
1251
|
-
ToDesktop CLI is similar to Continuous Integration service so you can use the
|
|
1379
|
+
ToDesktop CLI is similar to Continuous Integration service so you can use the
|
|
1380
|
+
guide from here:
|
|
1381
|
+
https://docs.npmjs.com/using-private-packages-in-a-ci-cd-workflow/
|
|
1252
1382
|
|
|
1253
1383
|
To summarize:
|
|
1254
1384
|
|
|
1255
1385
|
1. Create a token using npm: `npm token create --read-only`.
|
|
1256
1386
|
2. In ToDesktop's web UI go to Settings -> Build and Deploy.
|
|
1257
|
-
3. Enter an environment variable key of `NPM_TOKEN` and value should be the
|
|
1258
|
-
|
|
1387
|
+
3. Enter an environment variable key of `NPM_TOKEN` and value should be the
|
|
1388
|
+
token entered above.
|
|
1389
|
+
4. Create an `.npmrc` file in the root of your project with the following
|
|
1390
|
+
contents:
|
|
1259
1391
|
|
|
1260
1392
|
```
|
|
1261
1393
|
//registry.npmjs.org/:_authToken=${NPM_TOKEN}
|
|
1262
1394
|
```
|
|
1263
1395
|
|
|
1264
|
-
Note: **Do not put a token in this file**. You are specifying a literal value of
|
|
1396
|
+
Note: **Do not put a token in this file**. You are specifying a literal value of
|
|
1397
|
+
`${NPM_TOKEN}`. NPM will replace the value for you. 5. Add `.npmrc` to your
|
|
1398
|
+
`appFiles` array `[".npmrc"]` in `todesktop.json`.
|
|
1265
1399
|
|
|
1266
1400
|
### How can I specify a specific yarnVersion for use with my app?
|
|
1267
1401
|
|
|
1268
|
-
By default, ToDesktop uses version `1.x.x` of `Yarn` if a `yarn.lock` file is
|
|
1402
|
+
By default, ToDesktop uses version `1.x.x` of `Yarn` if a `yarn.lock` file is
|
|
1403
|
+
present in your project. You can override this by creating a `.yarnrc.yml` file
|
|
1404
|
+
in your project directory and specifying the `yarnPath` property to point to
|
|
1405
|
+
your specified version of yarn:
|
|
1269
1406
|
|
|
1270
1407
|
```yml
|
|
1271
1408
|
yarnPath: .yarn/releases/yarn-3.1.1.cjs
|
|
1272
1409
|
```
|
|
1273
1410
|
|
|
1274
|
-
This can be done automatically by running `yarn set version x.x.x` from within
|
|
1411
|
+
This can be done automatically by running `yarn set version x.x.x` from within
|
|
1412
|
+
your project directory. This will create a `.yarnrc.yml` file and a
|
|
1413
|
+
corresponding `.yarn/releases/yarn-x.x.x.cjs` that the `yarnPath` property
|
|
1414
|
+
points to. This will also add a `packageManager` field in your `package.json`
|
|
1415
|
+
with a value of `yarn@x.x.x`
|
|
1275
1416
|
|
|
1276
|
-
It's important to ensure that the `.yarn` folder is included in your build. If
|
|
1417
|
+
It's important to ensure that the `.yarn` folder is included in your build. If
|
|
1418
|
+
you had previously changed your `todesktop.json`'s
|
|
1419
|
+
[`appFiles`](#appfiles---optional-array-of-glob-patterns) property from its
|
|
1420
|
+
default glob implementation of `**`, then please ensure that it includes the
|
|
1421
|
+
`.yarn` directory:
|
|
1277
1422
|
|
|
1278
1423
|
Example: `[".yarn/**", ".yarnrc.yml", "...include your other changes here..."]`
|
|
1279
1424
|
|
|
1280
|
-
You will want to exclude the `.yarn` directory in the distribution version of
|
|
1425
|
+
You will want to exclude the `.yarn` directory in the distribution version of
|
|
1426
|
+
your app. You can use the
|
|
1427
|
+
[`filesForDistribution`](#filesForDistribution---optional-array-of-glob-patterns)
|
|
1428
|
+
property to achieve this:
|
|
1281
1429
|
|
|
1282
1430
|
Example: `["!.yarn/**", "!.yarnrc.yml"]`
|
|
1283
1431
|
|
|
1284
1432
|
### How do I create a staging version of my app?
|
|
1285
1433
|
|
|
1286
|
-
ToDesktop CLI supports the concept of a staging version of your app. This is
|
|
1434
|
+
ToDesktop CLI supports the concept of a staging version of your app. This is
|
|
1435
|
+
useful if you want to test your app before releasing it to the public. To create
|
|
1436
|
+
a staging version of your app, you need to do the following:
|
|
1287
1437
|
|
|
1288
1438
|
1. Create a new app in ToDesktop's web UI.
|
|
1289
1439
|
|
|
1290
|
-
2. Create a new configuration file, for example `todesktop.staging.json` or
|
|
1440
|
+
2. Create a new configuration file, for example `todesktop.staging.json` or
|
|
1441
|
+
`todesktop.staging.js`.
|
|
1291
1442
|
|
|
1292
|
-
3. Add the following to your staging configuration file (e.g.,
|
|
1443
|
+
3. Add the following to your staging configuration file (e.g.,
|
|
1444
|
+
`todesktop.staging.json`):
|
|
1293
1445
|
|
|
1294
1446
|
```json
|
|
1295
1447
|
{
|
|
@@ -1317,22 +1469,29 @@ ToDesktop CLI supports the concept of a staging version of your app. This is use
|
|
|
1317
1469
|
}
|
|
1318
1470
|
```
|
|
1319
1471
|
|
|
1320
|
-
Now you can run `npm run todesktop-build` to build the production app. Or you
|
|
1472
|
+
Now you can run `npm run todesktop-build` to build the production app. Or you
|
|
1473
|
+
can run `npm run todesktop-staging-build` to build the staging app.
|
|
1321
1474
|
|
|
1322
1475
|
### I want ToDesktop to compile my typescript/react/whatever on ToDesktop Servers
|
|
1323
1476
|
|
|
1324
|
-
No problem, this can be achieved with a
|
|
1477
|
+
No problem, this can be achieved with a
|
|
1478
|
+
[`postInstall`](https://docs.npmjs.com/cli/v9/using-npm/scripts) script in
|
|
1479
|
+
combination with ToDesktop's `TODESKTOP_CI` and
|
|
1480
|
+
`TODESKTOP_INITIAL_INSTALL_PHASE` environment variables.
|
|
1325
1481
|
|
|
1326
1482
|
| Name | Description |
|
|
1327
1483
|
| --------------------------------- | ------------------------------------------------------------------------------------- |
|
|
1328
1484
|
| `TODESKTOP_CI` | Set to `true` when running on ToDesktop build servers |
|
|
1329
1485
|
| `TODESKTOP_INITIAL_INSTALL_PHASE` | Set to `true` when running the first npm/yarn/pnpm install on ToDesktop build servers |
|
|
1330
1486
|
|
|
1331
|
-
First, let's create a file called `todesktop-postinstall.js` or something
|
|
1487
|
+
First, let's create a file called `todesktop-postinstall.js` or something
|
|
1488
|
+
similar in the root of your app (alongside `pkckage.json`). This file is going
|
|
1489
|
+
to run a script to compile typescript after your dependencies have been
|
|
1490
|
+
installed. It could look something like this
|
|
1332
1491
|
|
|
1333
1492
|
```js
|
|
1334
|
-
const { exec } = require(
|
|
1335
|
-
const { promisify } = require(
|
|
1493
|
+
const { exec } = require('child_process');
|
|
1494
|
+
const { promisify } = require('util');
|
|
1336
1495
|
const execAsync = promisify(exec);
|
|
1337
1496
|
|
|
1338
1497
|
async function postInstall() {
|
|
@@ -1340,12 +1499,12 @@ async function postInstall() {
|
|
|
1340
1499
|
process.env.TODESKTOP_CI && process.env.TODESKTOP_INITIAL_INSTALL_PHASE;
|
|
1341
1500
|
|
|
1342
1501
|
if (firstInstallOnToDesktopServers) {
|
|
1343
|
-
console.log(
|
|
1344
|
-
await execAsync(
|
|
1345
|
-
stdio:
|
|
1502
|
+
console.log('➔ Building typescript on ToDesktop servers');
|
|
1503
|
+
await execAsync('npm run build', {
|
|
1504
|
+
stdio: 'inherit',
|
|
1346
1505
|
});
|
|
1347
1506
|
} else {
|
|
1348
|
-
console.log(
|
|
1507
|
+
console.log('➔ Not on ToDesktop servers... Do nothing.');
|
|
1349
1508
|
}
|
|
1350
1509
|
}
|
|
1351
1510
|
|
|
@@ -1367,10 +1526,17 @@ Next, add the following to your `package.json`:
|
|
|
1367
1526
|
}
|
|
1368
1527
|
```
|
|
1369
1528
|
|
|
1370
|
-
Now, when we build your app on ToDesktop servers, it will also run your custom
|
|
1529
|
+
Now, when we build your app on ToDesktop servers, it will also run your custom
|
|
1530
|
+
`build` script after all dependencies have been installed.
|
|
1371
1531
|
|
|
1372
1532
|
## Changelog
|
|
1373
1533
|
|
|
1534
|
+
### 1.18.2
|
|
1535
|
+
|
|
1536
|
+
#### Patch Changes
|
|
1537
|
+
|
|
1538
|
+
- 797f9cc: feat(mas): add `mas.minimumSystemVersion` config option
|
|
1539
|
+
|
|
1374
1540
|
### 1.18.0
|
|
1375
1541
|
|
|
1376
1542
|
#### Minor Changes
|
|
@@ -1380,11 +1546,13 @@ Now, when we build your app on ToDesktop servers, it will also run your custom `
|
|
|
1380
1546
|
|
|
1381
1547
|
### v1.17.1
|
|
1382
1548
|
|
|
1383
|
-
- Fix: `windows.icon` now accepts `.ico` files without triggering schema
|
|
1549
|
+
- Fix: `windows.icon` now accepts `.ico` files without triggering schema
|
|
1550
|
+
validation errors.
|
|
1384
1551
|
|
|
1385
1552
|
### v1.17.0
|
|
1386
1553
|
|
|
1387
|
-
- Add support for `bundleWorkspacePackages` in config to specify whether the CLI
|
|
1554
|
+
- Add support for `bundleWorkspacePackages` in config to specify whether the CLI
|
|
1555
|
+
bundles workspace packages alongside the app upload.
|
|
1388
1556
|
|
|
1389
1557
|
### v1.15.2
|
|
1390
1558
|
|
|
@@ -1396,9 +1564,11 @@ Now, when we build your app on ToDesktop servers, it will also run your custom `
|
|
|
1396
1564
|
|
|
1397
1565
|
### v1.15.0
|
|
1398
1566
|
|
|
1399
|
-
- Add support for `todesktop.ts` configuration file with full TypeScript type
|
|
1567
|
+
- Add support for `todesktop.ts` configuration file with full TypeScript type
|
|
1568
|
+
checking and IntelliSense.
|
|
1400
1569
|
- Export `Schema` type from `@todesktop/cli` for TypeScript configuration files.
|
|
1401
|
-
- TypeScript compilation uses user's local TypeScript installation (no
|
|
1570
|
+
- TypeScript compilation uses user's local TypeScript installation (no
|
|
1571
|
+
production dependencies added).
|
|
1402
1572
|
|
|
1403
1573
|
### v1.14.0
|
|
1404
1574
|
|
|
@@ -1408,8 +1578,10 @@ Now, when we build your app on ToDesktop servers, it will also run your custom `
|
|
|
1408
1578
|
|
|
1409
1579
|
### v1.13.0
|
|
1410
1580
|
|
|
1411
|
-
- Add support for `platformOverrides` in config to specify platform-specific
|
|
1412
|
-
|
|
1581
|
+
- Add support for `platformOverrides` in config to specify platform-specific
|
|
1582
|
+
overrides for app configuration
|
|
1583
|
+
- Add support for `$schema` in config to enable JSON schema validation and IDE
|
|
1584
|
+
intellisense
|
|
1413
1585
|
|
|
1414
1586
|
### v1.12.5
|
|
1415
1587
|
|
|
@@ -1417,11 +1589,13 @@ Now, when we build your app on ToDesktop servers, it will also run your custom `
|
|
|
1417
1589
|
|
|
1418
1590
|
### v1.12.3
|
|
1419
1591
|
|
|
1420
|
-
- Allow `catalog:` protocol (used by PNPM) for electron dependency version in
|
|
1592
|
+
- Allow `catalog:` protocol (used by PNPM) for electron dependency version in
|
|
1593
|
+
`package.json`.
|
|
1421
1594
|
|
|
1422
1595
|
### v1.12.2
|
|
1423
1596
|
|
|
1424
|
-
- Fix: Update `appFiles` to not error when no `*.js` files are found (but `*.ts`
|
|
1597
|
+
- Fix: Update `appFiles` to not error when no `*.js` files are found (but `*.ts`
|
|
1598
|
+
files are present)
|
|
1425
1599
|
|
|
1426
1600
|
### v1.12.1
|
|
1427
1601
|
|
|
@@ -1429,7 +1603,8 @@ Now, when we build your app on ToDesktop servers, it will also run your custom `
|
|
|
1429
1603
|
|
|
1430
1604
|
### v1.12.0
|
|
1431
1605
|
|
|
1432
|
-
- Add support for custom `updateUrlBase` in config to specify a custom
|
|
1606
|
+
- Add support for custom `updateUrlBase` in config to specify a custom
|
|
1607
|
+
auto-update URL
|
|
1433
1608
|
|
|
1434
1609
|
### v1.11.5
|
|
1435
1610
|
|
|
@@ -1445,15 +1620,19 @@ Now, when we build your app on ToDesktop servers, it will also run your custom `
|
|
|
1445
1620
|
|
|
1446
1621
|
### v1.11.2
|
|
1447
1622
|
|
|
1448
|
-
- Stop erroring in cases where `appId` is not defined in an extended
|
|
1623
|
+
- Stop erroring in cases where `appId` is not defined in an extended
|
|
1624
|
+
`todesktop.json`.
|
|
1449
1625
|
|
|
1450
1626
|
### v1.11.1
|
|
1451
1627
|
|
|
1452
|
-
- You can now specify `linux.imageVersion` to explicitly set the version of the
|
|
1628
|
+
- You can now specify `linux.imageVersion` to explicitly set the version of the
|
|
1629
|
+
Linux image that ToDesktop should use to build your app.
|
|
1453
1630
|
|
|
1454
1631
|
### v1.11.0
|
|
1455
1632
|
|
|
1456
|
-
- Add additional `id` and `appId` validation when extending another
|
|
1633
|
+
- Add additional `id` and `appId` validation when extending another
|
|
1634
|
+
`todesktop.json` file. Can be disabled with the `--ignore-extends-errors`
|
|
1635
|
+
flag.
|
|
1457
1636
|
|
|
1458
1637
|
### v1.10.5
|
|
1459
1638
|
|
|
@@ -1466,7 +1645,8 @@ Now, when we build your app on ToDesktop servers, it will also run your custom `
|
|
|
1466
1645
|
|
|
1467
1646
|
### v1.10.3
|
|
1468
1647
|
|
|
1469
|
-
- Update Readme to include instructions on `todesktop.json` VSCode/Cursor
|
|
1648
|
+
- Update Readme to include instructions on `todesktop.json` VSCode/Cursor
|
|
1649
|
+
validation
|
|
1470
1650
|
|
|
1471
1651
|
### v1.10.2
|
|
1472
1652
|
|
|
@@ -1493,7 +1673,8 @@ Now, when we build your app on ToDesktop servers, it will also run your custom `
|
|
|
1493
1673
|
### v1.9.6
|
|
1494
1674
|
|
|
1495
1675
|
- Add support for `mas.x64ArchFiles` in config.
|
|
1496
|
-
- Fix: Build is only recognised as ongoing if it was created in the last 24
|
|
1676
|
+
- Fix: Build is only recognised as ongoing if it was created in the last 24
|
|
1677
|
+
hours.
|
|
1497
1678
|
- Add support for `mac.entitlementsInherit` in config.
|
|
1498
1679
|
|
|
1499
1680
|
### v1.9.4
|
|
@@ -1504,7 +1685,8 @@ Now, when we build your app on ToDesktop servers, it will also run your custom `
|
|
|
1504
1685
|
|
|
1505
1686
|
- Add support for `mas.entitlements` in config.
|
|
1506
1687
|
- Add support for `mas.entitlementsInherit` in config.
|
|
1507
|
-
- Add support for `mas.provisioningProfile` in config. Removed
|
|
1688
|
+
- Add support for `mas.provisioningProfile` in config. Removed
|
|
1689
|
+
`mac.provisioningProfile` as a result.
|
|
1508
1690
|
|
|
1509
1691
|
### v1.9.2
|
|
1510
1692
|
|
|
@@ -1518,11 +1700,13 @@ Now, when we build your app on ToDesktop servers, it will also run your custom `
|
|
|
1518
1700
|
|
|
1519
1701
|
### v1.9.0
|
|
1520
1702
|
|
|
1521
|
-
- You can now specify `@electron/rebuild` as a custom `rebuildLibrary` in your
|
|
1703
|
+
- You can now specify `@electron/rebuild` as a custom `rebuildLibrary` in your
|
|
1704
|
+
configuration file.
|
|
1522
1705
|
|
|
1523
1706
|
### v1.8.1
|
|
1524
1707
|
|
|
1525
|
-
- Revert support for `yarnVersion` in config. Instead use `.yarnrc.yml` file to
|
|
1708
|
+
- Revert support for `yarnVersion` in config. Instead use `.yarnrc.yml` file to
|
|
1709
|
+
specify yarn version.
|
|
1526
1710
|
|
|
1527
1711
|
### v1.8.0
|
|
1528
1712
|
|
|
@@ -1546,7 +1730,8 @@ Now, when we build your app on ToDesktop servers, it will also run your custom `
|
|
|
1546
1730
|
|
|
1547
1731
|
### v1.7.4
|
|
1548
1732
|
|
|
1549
|
-
- Fix: Linux/Windows platform links no longer have mac/zip/[arch] added to the
|
|
1733
|
+
- Fix: Linux/Windows platform links no longer have mac/zip/[arch] added to the
|
|
1734
|
+
end of the download URL
|
|
1550
1735
|
|
|
1551
1736
|
### v1.7.3
|
|
1552
1737
|
|
|
@@ -1554,7 +1739,8 @@ Now, when we build your app on ToDesktop servers, it will also run your custom `
|
|
|
1554
1739
|
|
|
1555
1740
|
### v1.7.1
|
|
1556
1741
|
|
|
1557
|
-
- Add support for specifying custom `appBuilderLibVersion` in the configuration
|
|
1742
|
+
- Add support for specifying custom `appBuilderLibVersion` in the configuration
|
|
1743
|
+
file
|
|
1558
1744
|
- Show suggestion to run a Smoke Test when releasing an untested build
|
|
1559
1745
|
|
|
1560
1746
|
### v1.7.0
|
|
@@ -1563,7 +1749,8 @@ Now, when we build your app on ToDesktop servers, it will also run your custom `
|
|
|
1563
1749
|
|
|
1564
1750
|
### v1.6.3
|
|
1565
1751
|
|
|
1566
|
-
- Add support for specifying custom `windows.nsisCustomBinary` in the
|
|
1752
|
+
- Add support for specifying custom `windows.nsisCustomBinary` in the
|
|
1753
|
+
configuration file
|
|
1567
1754
|
|
|
1568
1755
|
### v1.6.2
|
|
1569
1756
|
|
|
@@ -1609,7 +1796,8 @@ Now, when we build your app on ToDesktop servers, it will also run your custom `
|
|
|
1609
1796
|
|
|
1610
1797
|
### v1.2.1
|
|
1611
1798
|
|
|
1612
|
-
- Fix: When the build is finished the download link is now an Apple Silicon link
|
|
1799
|
+
- Fix: When the build is finished the download link is now an Apple Silicon link
|
|
1800
|
+
if you are on an Apple Silicon Mac.
|
|
1613
1801
|
|
|
1614
1802
|
### v1.2.0
|
|
1615
1803
|
|