diff --git a/blueprints/ember-electron/index.js b/blueprints/ember-electron/index.js index f2cef28b..a6e8078f 100644 --- a/blueprints/ember-electron/index.js +++ b/blueprints/ember-electron/index.js @@ -14,7 +14,7 @@ const writeFile = denodeify(fs.writeFile); const YAWN = require('yawn-yaml/cjs'); const SilentError = require('silent-error'); const { - upgradeUrl, + upgradingUrl, ciUrl } = require('../../lib/utils/documentation-urls'); @@ -44,7 +44,7 @@ module.exports = class EmberElectronBlueprint extends Blueprint { this.ui.writeLine(chalk.yellow([ `\n'ember-electron' directory detected -- this looks like an ember-electron`, `v2 project. Setting up an updated project will not be destructive, but you`, - `should read the upgrade documentation at ${upgradeUrl}.\n` + `should read the upgrading documentation at ${upgradingUrl}.\n` ].join(' '))); } } diff --git a/lib/commands/base.js b/lib/commands/base.js index 3b1744cf..75663b27 100644 --- a/lib/commands/base.js +++ b/lib/commands/base.js @@ -8,7 +8,7 @@ const YarnOrNpmTask = require('../tasks/yarn-or-npm'); const Win = require('ember-cli/lib/utilities/windows-admin'); const fs = require('fs'); const { electronProjectPath } = require('../utils/build-paths'); -const { upgradeUrl } = require('../utils/documentation-urls'); +const { upgradingUrl } = require('../utils/documentation-urls'); const SilentError = require('silent-error'); module.exports = Command.extend({ @@ -30,7 +30,7 @@ module.exports = Command.extend({ `contain an electron-forge project. It should have been generated by`, `ember-electron's blueprint when you first ran 'ember install`, `ember-electron'. If you are upgrading from ember-electron v2, you`, - `should read the upgrade documentation at ${upgradeUrl}.`, + `should read the upgrading documentation at ${upgradingUrl}.`, ].join(' ')) ); } diff --git a/lib/utils/documentation-urls.js b/lib/utils/documentation-urls.js index 35ec60a8..5163c93b 100644 --- a/lib/utils/documentation-urls.js +++ b/lib/utils/documentation-urls.js @@ -1,9 +1,9 @@ const baseUrl = 'https://adopted-ember-addons.github.io/ember-electron/docs/'; const guidesUrl = `${baseUrl}guides/`; -const upgradeUrl = `${guidesUrl}upgrade`; +const upgradingUrl = `${guidesUrl}upgrading`; const ciUrl = `${guidesUrl}ci`; module.exports = { - upgradeUrl, + upgradingUrl, ciUrl }; \ No newline at end of file diff --git a/tests/dummy/app/router.js b/tests/dummy/app/router.js index 10a78562..78a7f5d8 100644 --- a/tests/dummy/app/router.js +++ b/tests/dummy/app/router.js @@ -11,18 +11,16 @@ Router.map(function() { this.route('faq', function() { this.route('common-issues'); this.route('security'); - this.route('structure'); - this.route('test-runner-deprecation'); }); this.route('guides', function() { - this.route('build-pipeline'); this.route('ci'); - this.route('configuration'); + this.route('common-issues'); + this.route('development-and-debugging'); this.route('installation'); - this.route('packaging'); - this.route('testing'); - this.route('upgrade'); + this.route('security'); + this.route('structure'); + this.route('upgrading'); this.route('usage'); }); }); diff --git a/tests/dummy/app/templates/docs.hbs b/tests/dummy/app/templates/docs.hbs index f5e4bfdd..20c441f4 100644 --- a/tests/dummy/app/templates/docs.hbs +++ b/tests/dummy/app/templates/docs.hbs @@ -5,18 +5,14 @@ {{nav.section "Guides"}} {{nav.item "Installation" "docs.guides.installation"}} {{nav.item "Usage" "docs.guides.usage"}} - {{nav.item "Configuration" "docs.guides.configuration"}} - {{nav.item "Packaging" "docs.guides.packaging"}} - {{nav.item "Testing" "docs.guides.testing"}} - {{nav.item "Upgrade" "docs.guides.upgrade"}} + {{nav.item "Structure" "docs.guides.structure"}} + {{nav.item "Upgrading" "docs.guides.upgrading"}} + {{nav.item "Development and Debugging" "docs.guides.development-and-debugging"}} {{nav.item "CI" "docs.guides.ci"}} - {{nav.item "Build Pipeline" "docs.guides.build-pipeline"}} {{nav.section "FAQ"}} {{nav.item "Common Issues" "docs.faq.common-issues"}} {{nav.item "Security" "docs.faq.security"}} - {{nav.item "Structure" "docs.faq.structure"}} - {{nav.item "Test Runner Deprecation" "docs.faq.test-runner-deprecation"}} {{/viewer.nav}} {{#viewer.main}} diff --git a/tests/dummy/app/templates/docs/faq/common-issues.md b/tests/dummy/app/templates/docs/faq/common-issues.md index 6ce9120d..229ea822 100644 --- a/tests/dummy/app/templates/docs/faq/common-issues.md +++ b/tests/dummy/app/templates/docs/faq/common-issues.md @@ -44,12 +44,3 @@ In your ember-electron/main.js file, find the `BrowserWindow` that is being used const myWindow = new BrowserWindow({}); myWindow.webContents.openDevTools(); ``` - - -## `ember-welcome-page` does not show in production mode - -If you try out Ember-Electron for the first time on a brand new Ember project generated with `ember init`, you may find that the welcome page you see when running `ember electron` does no longer show up when you run an application packaged with `ember electron:package`. - -While this might be a little confusing, it is the default behavior of the `ember-welcome-page` addon, which simply removes itself when run with the environment flag `--env=production`, which is our default while packaging applications. - -Since you probably don't need that page anyway, you can safely follow it's own instructions and remove it from your `package.json` as well as the template tag `{{welcome-page}}` from your `app/templates/application.hbs`. diff --git a/tests/dummy/app/templates/docs/faq/security.md b/tests/dummy/app/templates/docs/faq/security.md index 9b1bc8a6..7db70684 100644 --- a/tests/dummy/app/templates/docs/faq/security.md +++ b/tests/dummy/app/templates/docs/faq/security.md @@ -43,3 +43,20 @@ and the MDN [Web security landing page](https://developer.mozilla.org/en-US/docs e.g. `Refused to load...because it violates the following Content Security Policy directive:...` * If there are no problems then you are done. Otherwise, you'll need to examine the code in violation and either make it compliant or adjust the policy to allow it. + +## Why do I see "Electron Security Warning (Insecure Resources)" when running tests? + +To aid users in keeping their applications secure, Electron warns about any scripts +or other resources loaded out of `index.html` without encryption (using `http:` +rather than `https:`). When running tests, the renderer process has to load some +resources from the local express server to allow it to communicate with testem, which +manages the test run, and this cannot easily be done over `https:`. The expected list +of URLs is: + +``` +- http://testemserver/testem.js +- http://testemserver/testem/connection.html +``` + +We leave the security warnings enabled when running tests so you can see if it's warning +about any other insecure content, besides the URLs listed about, loaded during tests. \ No newline at end of file diff --git a/tests/dummy/app/templates/docs/faq/structure.md b/tests/dummy/app/templates/docs/faq/structure.md deleted file mode 100644 index e265cf17..00000000 --- a/tests/dummy/app/templates/docs/faq/structure.md +++ /dev/null @@ -1,42 +0,0 @@ -# File structure used and created by Ember-Electron - -The `ember-electron` folder created at the root of your project by `ember-electron`'s blueprint looks like this: - -``` - ember-electron - ├── .electron-forge - ├── main.js - ├── resources - ├── resources-darwin - ├── resources-linux - └── resources-win32 -``` - -The `resources` directories are meant for non-code resources, such as images, json files, etc. The `resources-` directories exist so you can supply resources that will only be included on certain platforms, augmenting or replacing your platform-independent resources in `resources`. When the `ember electron` assembles your Electron project, it will look like this: - -``` - ember-electron - ├── package.json - ├── ember - │ ├── - ├── ember-electron - │ ├── electron-forge-config.js - │ ├── main.js - │ ├── resources - │ ├── > - │ ├── > - ├── node_modules - ├── -``` - -- `package.json` is copied from the root of your project; -- `ember` contains the built Ember app; and -- `ember-electron` contains - - `resources`, assembled as described; and - - everything else in your ember-electron dir - -If you want to see your assembled project to poke around or debug, you can run `ember electron:assemble` to generate it. Once generated, you can run it using electron forge: - -``` -$ ./node_modules/.bin/forge -p electron-out/project start -``` diff --git a/tests/dummy/app/templates/docs/faq/test-runner-deprecation.md b/tests/dummy/app/templates/docs/faq/test-runner-deprecation.md deleted file mode 100644 index 0a1adad2..00000000 --- a/tests/dummy/app/templates/docs/faq/test-runner-deprecation.md +++ /dev/null @@ -1,39 +0,0 @@ -# This test-runner.js is deprecated... - -## TL;DR - -This deprecation is related to a change to the `ember electron:test` support -scripts to make them less brittle. TL;DR is you should rerun the blueprint to -regenerate `ember-electron/test-main.js` and `testem-electron.js`. If you have -made any custom changes to `ember-electron/test-main.js`, or if you just want to -know more about that change, keep reading... - -## Details - -`ember-electron/test-main.js` is generated by `ember-electron`'s blueprint, and -previously contained all of the test-mode main process code. `test-runner.js` -lives in the `ember-electron` and is run via `testem-electron.js`. It has to -pass a very specific set of command-line options when launching Electron that -`test-main.js` parses to be able to set up communication with `testem`. - -These two scripts are pretty tightly coupled together, but previously one lived -in `ember-electron` and one was generated in the consuming app via the -blueprint. So anytime we want to make an update affecting how those scripts -communicate, it would require apps to rerun the blueprint after updating -`ember-electron`, which is not a smooth upgrade experience. - -So we moved all the code that was in `ember-electron/test-main.js` into -`ember-electron` and modified the `ember-electron/test-main.js` in the blueprint -to do nothing but `require()` the script out of `ember-electron`. That puts all -of the tightly-coupled code in the `ember-electron` addon and frees us up to -make updates without requiring apps to rerun the blueprint. - -If you need to change the contents of `test-main.js` for some reason, there are -two options. Ideally you could just put your code in `test-main.js` before or -after the `require()` statement. If you need to modify some of the code that now -lives in the `require()`'d script in `ember-electron`, you'll need to copy the -code out of it back into your `ember-electron/test-main.js`, replacing the -`require()` statement, and then monitoring releases of `ember-electron` for -changes to `test-main.js`. We realize this is cumbersome, but we hope nobody -really has to do it, so if you find yourself doing so, please find is in the -\#electron channel in Ember Community Slack and tell us about your use case. diff --git a/tests/dummy/app/templates/docs/guides/build-pipeline.md b/tests/dummy/app/templates/docs/guides/build-pipeline.md deleted file mode 100644 index 45eb0b13..00000000 --- a/tests/dummy/app/templates/docs/guides/build-pipeline.md +++ /dev/null @@ -1,54 +0,0 @@ -# Build pipeline -Ember-Electron's build pipeline consists of the following steps: - -* Build Ember app (with Electron shimming/instrumentation) -* Assemble Electron project (compatible with [electron-forge](https://github.com/electron-userland/electron-forge)) -* Package application binaries -* Make application installers - -Each of these steps is broken into an Ember command and through its command-line -options can be configured to run all preceding pipeline steps, or to skip some -of the first steps, and use the output of a previous (partial) build. For -example the following would produce equivalent output: - -```bash -$ ember electron:build --output-path electron-out/ember -$ ember electron:assemble --build-path electron-out/ember --output-path electron-out/project -``` - -and - -```bash -$ ember electron:assemble --output-path electron-out/project -``` - -The only difference is that the latter command will build the Ember app into a -temp directory and delete it when it's done. - -A similar example of equivalent commands that illustrates the entire pipeline -is: - -```bash -$ ember electron:build --output-path electron-out/ember -$ ember electron:assemble --build-path electron-out/ember --output-path electron-out/project -$ ember electron:package --project-path electron-out/project -$ ember electron:make --skip-package -``` - -The `electron:make` command doesn't match the rest of them because -`electron-forge` handles reusing packaged output itself, so the semantics are a -little different. - -Each build step will also accept an input path valid for any of the previous -steps. For example, the following are equivalent: - -```bash -$ ember electron:build --output-path electron-out/ember -$ ember electron:make --build-path electron-out/ember -``` - -and - -```bash -$ ember electron:make -``` diff --git a/tests/dummy/app/templates/docs/guides/ci.md b/tests/dummy/app/templates/docs/guides/ci.md index 18f5924a..1a9cae33 100644 --- a/tests/dummy/app/templates/docs/guides/ci.md +++ b/tests/dummy/app/templates/docs/guides/ci.md @@ -4,28 +4,18 @@ You can test your application using Electron with the `ember electron:test` comm * Install [`xvfb`](https://en.wikipedia.org/wiki/Xvfb). It's a virtual framebuffer, implementing the X11 display server protocol - it performs all graphical operations in memory without showing any screen output, which is exactly what we need. A [Jenkins addon is available](https://wiki.jenkins-ci.org/display/JENKINS/Xvfb+Plugin). * Create a virtual `xvfb` screen and export an environment variable called `DISPLAY` that points to it. Electron will automatically pick it up. - * Install a recent C++ compiler (e.g. gcc). This is to enable the CI server to build native modules for Node.js. - * Finally, ensure that `npm test` actually calls `ember electron:test`. You can configure what command `npm test executes` by changing it in your `package.json`. + * Finally, ensure that `npm test` or `yarn test` actually calls `ember electron:test`. You can configure what command `npm test executes` by changing it in your `package.json`. -On Travis, the configuration should look like this: +When you first install `ember-electron`, the blueprint will update your .travis.yml, but if it fails or you need to do it manually for some reason, your configuration should include the following: ```yaml -env: - - CXX=g++-4.8 - addons: apt: - sources: - - ubuntu-toolchain-r-test packages: - xvfb - - g++-4.8 - -before_install: - - "npm config set spin false" install: - - npm install + - - export DISPLAY=':99.0' - Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 & ``` diff --git a/tests/dummy/app/templates/docs/guides/configuration.md b/tests/dummy/app/templates/docs/guides/configuration.md deleted file mode 100644 index e006f46e..00000000 --- a/tests/dummy/app/templates/docs/guides/configuration.md +++ /dev/null @@ -1,76 +0,0 @@ -# Configuration - -## electron-forge / electron-packager - -You can pass options to the packager by either putting configuration into `ember-electron/electron-forge-config.js`, or by passing a command line parameter to the `ember electron:package` command. In the case that an option is defined both on the command line and in the `electron-forge-config.js`, the command line option will be used. - -> :warning: The `electron-forge-config.js` file will be copied to a temporary folder during compilation, meaning that relative paths will be different. If you require resources from other folders (for intsance using a `require('../myscript')`, please do keep in mind that `electron-forge-config.js`. - -* `--app-copyright` - *String* The human-readable copyright line for the app. Maps to the LegalCopyright metadata property on Windows, and NSHumanReadableCopyright on OS X. -* `--app-version` - *String* The release version of the application. Maps to the `ProductVersion` metadata property on Windows, and `CFBundleShortVersionString` on OS X. -* `--arch` - *String* Allowed values: *ia32, x64, all* - -* `--asar` - *Boolean* Whether to package the application's source code into an archive, using [Electron's archive format](https://github.com/atom/asar). Reasons why you may want to enable this feature are described in [an application packaging tutorial in Electron's documentation](http://electron.atom.io/docs/v0.36.0/tutorial/application-packaging/). Defaults to `false`. - - - `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`. - - For example, `asar-unpack-dir=sub_dir` will unpack the directory `//sub_dir`. - -* `--build-version` - *String* The build version of the application. Maps to the `FileVersion` metadata property on Windows, and `CFBundleVersion` on OS X. -* `--copy-dev-modules` - *Boolean* Copy dependency node modules from local dev node_modules instead of installing them. - -* `--defer-symlinks` - *Boolean* Whether symlinks should be dereferenced during copying (defaults to true) -* `--download` - *Object* If present, passes custom options to [`electron-download`](https://www.npmjs.com/package/electron-download) -(see the link for more detailed option descriptions and the defaults). - - - `cache` *String*: The directory where prebuilt, pre-packaged Electron downloads are cached. - - `mirror` *String*: The URL to override the default Electron download location. - - `strictSSL` *Boolean*: Whether SSL certificates are required to be valid when downloading Electron. - -* `--dir` - *String* The source directory - -* `--icon` - *String* Currently you must look for conversion tools in order to supply an icon in the format required by the platform. If the file extension is omitted, it is auto-completed to the correct extension based on the platform. - - - OS X: `.icns` - - Windows: `.ico` ([See below](#building-windows-apps-from-non-windows-platforms) for details on non-Windows platforms) - - Linux: this option is not required, as the dock/window list icon is set via [the icon option in the BrowserWindow contructor](http://electron.atom.io/docs/v0.30.0/api/browser-window/#new-browserwindow-options). Setting the icon in the file manager is not currently supported. - -* `--ignore` - *RegExp* A pattern which specifies which files to ignore when copying files to create the package(s). Take note that Ember Electron creates a temp folder containing `electron.js`, `package.json`, and Ember Cli's `dist` output folder. Glob patterns will not work. -* `--name` - *String* The application name. -* `--out` - *String* The directory where electron builds are saved. Defaults to `electron-builds/`. -* `--overwrite` - *Boolean* Whether to replace an already existing output directory for a given platform (`true`) or skip recreating it (`false`). Defaults to `false`. -* `--platform` - *String* Target platform for build outputs. Allowed values: *linux, win32, darwin, mas, all* -* `--prune` - *Boolean* Runs [`npm prune --production`](https://docs.npmjs.com/cli/prune) before starting to package the app. -* `--version` - *String* Electron version (without the 'v') - for example, [`0.33.9`](https://github.com/atom/electron/releases/tag/v0.33.9), see [Electron releases](https://github.com/atom/electron/releases) for valid versions - - -### Used for macOS builds only - -* `--app-bundle-id` - *String* The bundle identifier to use in the application's plist -* `--app-category-type` - *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). -* `--extend-info` - *String* Filename of a plist file; the contents are added to the app's plist. Entries in `extend-info` override entries in the base plist file supplied by electron-prebuilt, but are overridden by other explicit arguments such as `app-version` or `app-bundle-id`. -* `--extra-resource` - *String* Filename of a file to be copied directly into the app's Contents/Resources directory. -* `--helper-bundle-id` - *String* The bundle identifier to use in the application helper's plist. -* `--osx-sign` - *Object* If present, signs OS X target apps when the host platform is OS X 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. -* `--protocol` - *Array of strings* The URL protocol scheme(s) to associate the app with. For example, specifying `myapp` would cause URLs such as `myapp://path` to be opened with the app. Maps to the `CFBundleURLSchemes` metadata property. This option requires a corresponding `protocol-name` option to be specified. -* `--protocol-name` - *Strings* The descriptive name of the URL protocol scheme(s) specified via the `protocol` option. Maps to the `CFBundleURLName` metadata property. - - -### Used for Windows builds only - -**Note:** Windows builds on non-Windows platforms require [Wine](https://www.winehq.org/) to be available on your PATH before the build/package step is executed. - -* `--win32metadata` - *Object* Object hash of application metadata to embed into the executable (Windows only): - - - `CompanyName` - *String* - - `LegalCopyright` - *String* - - `FileDescription` - *String* - - `OriginalFilename` - *String* - - `ProductName` - *String* - - `InternalName` - *String* diff --git a/tests/dummy/app/templates/docs/guides/development-and-debugging.md b/tests/dummy/app/templates/docs/guides/development-and-debugging.md new file mode 100644 index 00000000..6f6fd7d6 --- /dev/null +++ b/tests/dummy/app/templates/docs/guides/development-and-debugging.md @@ -0,0 +1,68 @@ +# Development and Debugging + +## require() and requireNode() + +TL;DR is to use `requireNode()` instead of `require()` when requiring node modules from your Ember application. + +Ember defines its own global `require` function for requiring transpiled Ember modules from the application bundle, which overwrites Electron's `require` function that is used to require Node.js modules out of `node_modules` or by relative path. + +`ember-electron` attempts to patch this up by implementing a `require()` function that tries both Ember's and Node.js's `require()` functions, but it's not perfect, so we recommend you use `requireNode()` when requiring Node.js modules. + +## Command-line arguments + +If your Electron app accepts command-line arguments that the main process handles via `process.argv`, then when running `ember electron` you need to precede them with `---`. This allows the `ember electron` to distinguish between its own arguments and arguments it should pass through when launching Electron: + +```sh +$ ember electron --- +``` + +e.g. + +```sh +$ ember electron --- --some-flags --that-my-app --handles-as="process.argv" +``` + +or + +```sh +$ ember electron --environment=production --- --some-flags --that-my-app --handles-as="process.argv" +``` + +## Ember Inspector and Devtron + +`ember electron` installs the Electron Inspector and Devtron directly into Electron, so they should be available if you open the dev tools. Note that if you're in a browser window without `nodeIntegration` enabled, they will not be installed. + +## Developing main process code + +`ember-electron` does not restart your Electron app when main process code changes, so after making a code change you need to quit and re-launch your application. If you just run `ember electron` each time and you aren't changing any Ember code, you'll have to unnecessarily wait through the Ember build process that `ember electron` automatically runs. To avoid this, you can + +```sh +ember build +``` + +which will build the Ember app and put the results inside the Electron app, making it a fully-built like `electron forge` expects. Then you can + +```sh +cd electron-app +yarn start # or npm run start +``` + +which will run Electron forge's start script (`electron-forge start`). When you need to quit and relaunch, you can just re-run the start script and skip the Ember build entirely. + +Note that once you've `ember build`ed, you can also run the `package`, `make`, or `start` scripts, or any [electron-forge commands](https://www.electronforge.io/cli#commands) you like, as you're in a fully set up `electron-forge` project. + +## Debugging the Main Process + +Unless you're on really old Electron (`<2`), you can [debug the main process](https://electron.atom.io/docs/tutorial/debugging-main-process/) using the `--inspect`/`inspect-brk` flags. The above syntax (`---`) can also be used to pass arguments to electron itself: + +```sh +$ ember electron --- --inspect-brk +``` + +or: + +```sh +$ ember electron --- --inspect-brk --some-flags --that-my-app --handles-as="process.argv" +``` + +Then, like when inspecting any Node.js process, open Chrome and navigate to `chrome://inspect`. \ No newline at end of file diff --git a/tests/dummy/app/templates/docs/guides/installation.md b/tests/dummy/app/templates/docs/guides/installation.md index a14afdc4..a8ede276 100644 --- a/tests/dummy/app/templates/docs/guides/installation.md +++ b/tests/dummy/app/templates/docs/guides/installation.md @@ -1,18 +1,15 @@ # Installation & Setup -> :warning: This addon needs at least Node 6. +> This addon requires at least Node 8 and `ember-cli` 3.4.0 -To install the addon, run: +## Installation ```sh ember install ember-electron ``` -Or, to install with npm - but please ensure (:warning:) that the blueprint generation runs - it creates necessary files and configuration for this addon to work. Please ensure that you have a populated `ember-electron` folder at the root of your project, and another one (only containing `lib/index.js`) in your `tests` directory. +This will install `ember-electron` and create and initialize an [electron-forge](https://www.electronforge.io/) project in the `electron-app` directory inside your Ember app. Then you can run `ember electron` to launch your app in Electron. -```sh -npm install ember-electron -ember g ember-electron -``` +## Upgrading -See [FAQ: Structure](../faq/structure.md) for more information on the layout of the `ember-electron` directory. +See [Guides: Upgrading](./upgrading) for information on how to upgrade from `ember-electron` 2.x. diff --git a/tests/dummy/app/templates/docs/guides/packaging.md b/tests/dummy/app/templates/docs/guides/packaging.md deleted file mode 100644 index 98c8e6eb..00000000 --- a/tests/dummy/app/templates/docs/guides/packaging.md +++ /dev/null @@ -1,11 +0,0 @@ -# Packaging - -Ember-Electron comes with an integrated packager to create binaries (.app, .exe etc), which can be run with `ember electron:package`. By default, the packager creates binaries for all platforms and architectures using your app's name and version as defined in `package.json`. Under the hood, it uses [electron-forge](https://github.com/electron-userland/electron-forge)). - -To create standalone binaries of your Ember App, simply run the following command: - -```sh -ember electron:package -``` - -and they will be created in a `electron-out` directory at the root of your project. diff --git a/tests/dummy/app/templates/docs/guides/structure.md b/tests/dummy/app/templates/docs/guides/structure.md new file mode 100644 index 00000000..70d13ae6 --- /dev/null +++ b/tests/dummy/app/templates/docs/guides/structure.md @@ -0,0 +1,65 @@ +# Structure of an ember-electron app + +## Electron apps + +Electron apps consist of a main Node.js process that can spawn Chromium windows, called rendered processes, and load content into them. Those windows can load remote web pages, or local ones bundled with the Electron application, and they can be granted access to Node.js APIs so the code running in the browser windows can, for example, access the filesystem directly. + +## Electron forge + +[electron-forge](https://www.electronforge.io/) is a command-line interface for creating and managing Electron projects, analagous to `ember-cli` in the Ember ecosystem. You will not need to run `electron-forge` commands directly (although you can -- see below), but since most of the `ember electron:*` commands are wrappers for `electron-forge` commands, and `electron-forge` supports a very large set of configuration objects, it may be valuable to familiarize yourself with the basics of how `electron-forge` works. + +## ember-electron apps + +A vanilla `electron-forge` project contains some main process code and some static web content -- html, css, and js files. `ember-electron` integrates Ember with Electron by creating an `electron-forge` project inside your Ember project with some boilerplate main process code, and dynamically generated web content. + +The boilerplate code is set up to load web content from a directory called `ember-dist` that doesn't (initially) exist. When you run the various `ember electron:*` commands, they build your Ember app, put the result inside the `ember-dist` directory, and then use the `electron-forge` API to launch your app with the now-populated web content. + +### Project layout + +When you first install `ember-electron`, the blueprint creates an `electron-forge` project in an `electron-app` folder. Here is layout of that project: + +``` + my-app + ├── app + ├── tests + ├── public + ├── etc. + └── electron-app + ├── package.json + ├── node_modules + ├── src + │ └── index.js + ├── tests + │ └── index.js + ├── ember-dist + │ └── + ├── ember-test + │ └── + └── out + └── +``` + +When you run your app, the working directory (`process.cwd()`) is `electron-app/`, and the Ember app's Node.js require location is `ember-dist`, meaning that if you add `src/some-lib.js` and want to require it from your Ember code, you would `requireNode('../src/some-lib.js')`. + +### Dependencies: a tale of two package.jsons + +Unlike `ember-electron` 2.x, the Electron app is a self-contained package, rather than being mixed in with the Ember app. + +`my-app/package.json` should contain the dependencies needed for the Ember build -- all the standard Ember libraries and addons plus any that you want bundled into your application bundle. The packages specified in `my-app/package.json` will not be Node.js-requireable when you run your Electron application, but can only be accessed if they were injected into your Ember build using `ember-auto-import` or `app.import()` or the like. + +`my-app/electron-app/package.json` should contain the dependencies needed for the Electron/`electron-forge` build plus any packages needed at runtime that you want to Node.js-require from the main process, or from your Ember app via `requireNode`. + +Generally speaking: + +* `my-app/package.json#devDependencies`: +** packages needed to perform the Ember build +** packages that contribute non-Node.js code used from the Ember app at runtime +** packages used for testing the Ember app +* `my-app/package.json#dependencies`: +** generally empty +* `my-app/electron-app/package.json#devDependencies`: +** `electron-forge` and related packages needed to perform the Electron build +** packages needed for testing the main process +* `my-app/electron-app/package.json#dependencies`: +** packages `require`ed by the main process at runtime +** packages `requireNode`ed by the Ember app (with `nodeIntegration: true`) at runtime diff --git a/tests/dummy/app/templates/docs/guides/testing.md b/tests/dummy/app/templates/docs/guides/testing.md deleted file mode 100644 index dd278ad4..00000000 --- a/tests/dummy/app/templates/docs/guides/testing.md +++ /dev/null @@ -1,12 +0,0 @@ -# Testing - -To test your app, run `ember electron:test`. If you prefer the live-reload mode, run `ember electron:test --server`. The usual parameters are supported: - -- `--server` - Run tests in interactive mode (default: false) -- `--protocol` - 'The protocol to use when running with --server (default: 'http') -- `--host` - The host to use when running with --server (default: 'localhost') -- `--port` - The port to use when running with --server (default: 7357) -- `--module` - The name of a test module to run -- `--filter` - A string to filter tests to run - -When running `ember electron:test`, testem is configured to use `/testem-electron.js` instead of `/testem.js` (to allow projects to run as traditional ember apps as well as electron apps). The blueprint will install this file, but if you want to modify it to change any testem configuration, make sure to modify the right file. diff --git a/tests/dummy/app/templates/docs/guides/upgrade.md b/tests/dummy/app/templates/docs/guides/upgrade.md deleted file mode 100644 index 6fe03eb5..00000000 --- a/tests/dummy/app/templates/docs/guides/upgrade.md +++ /dev/null @@ -1,35 +0,0 @@ -# Upgrades - -Ember-Electron grew larger over time, and while we try to make updating this dependency as easy as possible given the complex structure behind it there are still a few manual steps required. - - - -## Upgrading from 1.x to 2.x - -First of all: Thank you so much for giving ember-electron a try. As the Electron community grew bigger, more and more modules emerged that cover parts of the same operations done by ember-electron - and over time it became clear that this module should depend on other, more -popular utility modules than to take care of all possible operations itself. - -ember-electron v2 is almost a complete rewrite, utilizing electron-forge to build and package your desktop applications. It allows ember-electron to focus on the Ember parts of this module, while the whole Electron community can work together to polish the creation of installers, the compilation of small packages, and the developer experience around native modules. - -If you are upgrading to version 2.x from 1.x, you will need to make some updates to your application. The best way to do this is to re-run the blueprint after upgrading `ember-electron`: - -```sh -ember generate ember-electron -``` - - - -## Configuration Upgrade - -The biggest change is where your configuration lives - in the past, `ember-electron` managed your configuration, passing it on to internal tools that would take care of the actual creation of binaries. - -Now, `ember electron:package` and `ember electron:make` use `electron-forge` to join forces with the greater Electron community. All configuration is now done using an `electron-forge-config.js` file inside your `ember-electron` folder. For details, [check out the documentation][forge-config]. - - - -## Example Upgrade - -To see an upgrade in action, check out how Ghost Desktop [moved from ember-electron v1 to v2][ghost-pr]. - -[forge-config]: https://github.com/electron-userland/electron-forge#config -[ghost-pr]: https://github.com/TryGhost/Ghost-Desktop/pull/263 diff --git a/tests/dummy/app/templates/docs/guides/upgrading.md b/tests/dummy/app/templates/docs/guides/upgrading.md new file mode 100644 index 00000000..8b2455b7 --- /dev/null +++ b/tests/dummy/app/templates/docs/guides/upgrading.md @@ -0,0 +1,126 @@ +# Upgrading from ember-electron 2.x + +While upgrading from 2.x to 3.x should not be very time-consuming in most cases, quite a bit has changed, so you should follow these steps in order to be successful. Starting from a clean tree (so you can run a clean `git diff` afterwards to see what changed), the recommended steps are: + +## Upgrade ember electron + +```sh +yarn-or-npm remove ember-electron +ember install ember-electron +``` + +When prompted to overwrite `testem-electron.js`, choose `yes`. + +## Fix electron version + +Your `electron-app` project will initially have the most recent release of Electron installed. You were probably running an older version since it was very difficult to run newer than Electron 4.x with `ember-electron` 2.x. So if you don't want to deal with upgrading Electron in the middle of upgrading `ember-electron`, you should change your `electron-app/package.json`'s `electron` version to match the version of `electron-prebuilt-compile` (which would determine the Electron version you were running) that is in your root `package.json`. + +The good news is that now upgrading Electron just involves updating the version installed in the `electron-app` package -- no more waiting for `electron-prebuilt-compile` to release an update matching the latest Electron version! + +## Clean up package.json + +When installing `ember-electron` 2.x, a number of entries were added to your `package.json` that can now be safely removed: + +`devDependencies`: +* `babel-plugin-transform-async-to-generator` +* `babel-preset-env` +* `babel-preset-react` +* `devtron` +* `electron-forge` +* `electron-prebuilt-compile` + +`dependencies`: +* `electron-compile` +* `electron-protocol-serve` +* `electron-squirrel-startup` + +and also the old `electron-forge` configuration: + +``` +"config": { + "forge": "./ember-electron/electron-forge-config.js" +} +``` + +## Migrate Node.js packages + +As described in [Guides: Structure](./structure), `ember-electron` 3.x differs from 2.x in that it doesn't mix the Electron app's `package.json` with the Ember app's `package.json`. So you'll need to identify any packages in your root `package.json` that are either `require()`ed by your Electron main process code, or `requireNode`ed by your Ember app and move or copy them into `electron-app/package.json`. + +## Migrate main process/Node.js files + +You will now have an `electron-app` folder with default vanilla content side-by-side with your `ember-electron` folder that stored your main process/Node.js files. So your next step is to migrate the contents of `ember-electron` over to `electron-app`. + +### electron-forge-config.js + +By default `electron-forge` puts the configuration inline in `package.json`, but still supports the external configuration. So you can either migrate the content of your `electron-forge-config.js` into `package.json`: + +``` +"config": { + "forge": { + "config goes": "here" + } +} +``` + +or move your `electron-forge-config.js` from `ember-electron` to `electron-app` and then replace the `config` key in `electron-app/package.json` with + +``` +"config": { + "forge": "./electron-forge-config.js" +} +``` + +Either way, you will need to update the configuration since the format has changed somewhat since the version of `electron-forge` that `ember-electron` 2.x used. Comparing your old configuration with the vanilla generated configuration in `electron-app/package.json` should help, and `electron-forge`'s [configuration documentation](https://www.electronforge.io/configuration) will help you through the process. Note also that the version of `electron-packager` uses changed from v11 to v14, and various maker packages were also updated, so there may be other configuration changes needed to be able to package/make with `ember-electron` 3.x. + +### main.js + +The equivalent of `ember-electron/main.js` is `electron-app/src/index.js`, so you'll want to put the contents of your `main.js` there (note that `src/index.js` is specified by the `main` entry in `electron-app/package.json`, so you can name it whatever/put it wherever you want as long as you update the `main` entry accordingy). Because the Electron project structure differs a little from `ember-electron` 2.x's, you'll need to replace anywhere you reference the path to the Ember application directory (`../ember`) with the new path (`../ember-dist`). For example, `ember-electron` 2.x's default `main.js` contains: + +```javascript +protocolServe({ + cwd: join(__dirname || resolve(dirname('')), '..', 'ember'), + app, + protocol, +}); +``` + +while `ember-electron` 3.x's contains: + +``` +protocolServe({ + cwd: join(__dirname || resolve(dirname('')), '..', 'ember-dist'), + app, + protocol, +}); +``` + +### test-main.js + +Generally you should not need to migrate `test-main.js` at all. It's default content in 2.x was: + +```javascript +/* eslint-env node */ +require('ember-electron/lib/test-support/test-main'); +``` + +If yours still looks like that, then you don't need to do anything. If you've customized it, then you'll need to migrate the content to `electron-app/tests/index.js` + +### resources-* folders + +If you don't have any files in any of the `ember-electron/resources` or `ember-electron/resources-*` folders, you can skip this section. + +`ember-electron` 2.x managed the `resources-*` folders to allow you to specify platform-specific resources. `electron-forge` does not support this functionality, and it was one of the main factors contributing to the complexity and slowness of `ember-electron` 2.x's build pipeline, so it's been removed in 3.x. + +So if you only have content in `ember-electron/resources/`, you can just copy the folder into `electron-app`. Note that `src/index.js` is now in a subfolder, unlike `main.js` was in 2.x, so if you are accessing resources from your main process using, e.g., `path.join(__dirname, 'resources')`, you'll have to update it to `path.join(__dirname, '..', 'resources')` (or you could put the `resources` folder in the `src/` directory if you're some kind of monster). + +If you do have content in the platform-specific `resources-*` folders, you can between them at runtime, e.g. put your platform-specific resources in `resources/win32`, `resources/darwin`, and `resources-linux` and: + +```javascript +let resourcePath = path.join('..', 'resources', process.platform, 'thing.json.txt'); +``` + +If you need to exclude files for other platforms from your packaged build, you can use `electron-forge`'s hooks, such as [packageAfterCopy](https://www.electronforge.io/configuration#packageaftercopy) (but note that these will only run when running `ember electron:package` or `ember electron:make`, not `ember electron` which runs directly out of your source tree). + +### code/files/etc + +Anything else that was in the `ember-electron` in 2.x should be "just files" -- `.js` files `require`d from the main process or `requireNode`d from the Ember app, or other files accessed via the filesystem APIs. So these can be migrated into `electron-app` however seems best, updating the references to their paths in other source files as needed. \ No newline at end of file diff --git a/tests/dummy/app/templates/docs/guides/usage.md b/tests/dummy/app/templates/docs/guides/usage.md index 93a1d1b0..893777ca 100644 --- a/tests/dummy/app/templates/docs/guides/usage.md +++ b/tests/dummy/app/templates/docs/guides/usage.md @@ -2,45 +2,65 @@ ## Running Your App -To run your app together with a file watcher in development mode (similar to `ember serve`), you can run `ember electron`, which will use Electron to start `ember-electron/main.js`. Electron's main process runs roughly like a Node process, meaning that it does not immediately open a browser window. This addon's blueprint adds a default `main.js` file to your project, which will automatically open up a new browser window with your Ember application. +To run your app in development mode, run +```sh +ember electron +``` +This is the equivalent of `ember serve` -- it defaults to building for the development environment, and live reloads when you make changes to your Ember app (but not your `electron-forge` project files -- see [Common Issues](../faq/common-issues#why-doesnt-my-application-reload-when-i-change-electron-forge-project-files-)). It supports many of the same parameters as `ember serve` does -- run `ember help electron` to see them all. -## Ember Inspector +## Running Tests -If you're running a later version of Electron, you will notice that ember-electron installs ember-inspector directly into Electron. Simply open up the developer tools and choose the Ember-tab, just like you would in Chrome. +To test your app, run +```sh +ember electron:test +``` +or -## Debugging the Main Process +```sh +ember electron:test --server +``` -There are a variety of methods of debugging the main process. If you're on Electron 1.7.2 or newer, using the `--inspect`/`inspect-brk` flags is by far the best. You can read up on other methods [here](https://electron.atom.io/docs/tutorial/debugging-main-process/). Regardless of which method you use, you'll need to pass extra command-line options to Electron when launching. This can be done via the following syntax: +to run in live-reload mode. It supports many of the same parameters as `ember test` does -- run `ember help electron:test` to see them all. -``` -$ ember electron --- -``` +## Packaging Your App for Distribution -for example: +### Configuration + +The process of packaging an application for distribution involves quite a bit of configuration. `ember-electron`'s installation blueprint will set you up with some defaults to get you started, but you will likely want to customize the configuration at some point. In `electron-app/package.json` you'll see ``` -$ ember electron --- --inspect-brk +"config": { + "forge": { + "packagerConfig": {}, + "makers": [ + ... + ] + } +} ``` -or: +This configuration is read directly by `electron-forge`, so you should use its [documentation](https://www.electronforge.io/configuration) as reference. -``` -$ ember electron --environment=production --- --debug-brk=5858 +### Making + +To make installers for your application that you can distribute, run + +```sh +ember electron:make ``` -## Conflict between Ember and Electron: require() +This is a thin wrapper around [electron-forge make](https://www.electronforge.io/cli#make). It will build out the installers specified by the `makers` array in your forge config and place them in `electron-app/out`. Various command-line arguments can customize the platform you are building for, the make targets to build, and allow you to reuse already-built content to speed things up, e.g., in CI -- run `ember help electron:make` to see them all. -Both Ember Cli and Node.js use `require()`. Without ember-electron, Ember will start and overwrite Node's `require()` method, meaning that you're stuck without crucial tools such as `require('electron')`. +### Packaging -When using ember-electron, this conflict is automatically managed for you. We provide save alternatives for -the methods and objects provided by Electron. +To package your application into a platform specific executable format, run -- `require()` is wrapped to resolve both Ember and Node modules, but we recommend you to use `requireNode()` for your Node dependencies. -- `window.module` becomes `window.moduleNode` -- `window.process` becomes `window.processNode` +```sh +ember electron:package +``` -While this should make it okay to continue using the default names, we recommend using our alternative ones for code clarity. +This is a thin wrapper around [electron-forge package](https://www.electronforge.io/cli#package). It will produce the same result you would get by running `ember electron:make` and then installing one of the installers, so is a good way to run your application under the same conditions that end-users will run it, rather than in a development environment. It will place the result in `electron-app/out`. Various command-line arguments can customize the platform you are building for, and allow you to reuse an already-built Ember app to speed things up, e.g., in CI -- run `ember help electron:package` to see them all. diff --git a/tests/dummy/app/templates/docs/index.md b/tests/dummy/app/templates/docs/index.md index e67fa9e1..e2796595 100644 --- a/tests/dummy/app/templates/docs/index.md +++ b/tests/dummy/app/templates/docs/index.md @@ -14,31 +14,24 @@ An Ember addon to turn Ember apps into cross-platform desktop applications, taki * `ember electron:package` - Create binaries (.app, .exe, etc) * `ember electron:make` - Generate platform specific distributables (installers, distribution packages, etc) * `ember electron:build` - Build out Ember app with Electron instrumentation (useful for optimizing multi-platform builds) -* `ember electron:assemble` - Assemble Electron application project (useful for debugging builds) To see a real world example, check out [Ghost Desktop](https://github.com/tryghost/Ghost-Desktop). - - ## Documentation ### Basics -- [Installation](docs/guides/installation.md) -- [Usage](docs/guides/usage.md) -- [Configuration](docs/guides/configuration.md) -- [Testing](docs/guides/testing.md) -- [Packaging](docs/guides/packaging.md) +- [Installation](docs/guides/installation) +- [Usage](docs/guides/usage) +- [Structure](docs/guides/structure) ### Advanced Guides -- [Upgrading from ember-electron 1.x to 2.x](docs/guides/upgrade.md) -- [Testing on CI (Travis, AppVeyor, CircleCI, etc)](docs/guides/ci.md) -- [Build pipeline](docs/guides/build-pipeline.md) +- [Upgrading from ember-electron 2.x to 3.x](docs/guides/upgrading) +- [Development and Debugging](docs/guides/development-and-debugging) +- [Testing on CI (Travis, AppVeyor, CircleCI, etc)](docs/guides/ci) ### FAQ - -- [Common issues](docs/faq/common-issues.md) -- [File structure](docs/faq/structure.md) -- [Security concerns](docs/faq/security.md) +- [Common issues](docs/faq/common-issues) +- [Security concerns](docs/faq/security) Somethings missing? Contributions to our docs are welcome! @@ -47,7 +40,7 @@ Somethings missing? Contributions to our docs are welcome! Ember-Electron is a small open source project. Use [GitHub Issues](https://github.com/adopted-ember-addons/ember-electron/issues) to report bugs and errors within the addon. -If you need help *using* the addon with your application, may we recommend the excellent Ember community? You can the [various places to get help here](https://www.emberjs.com/community/). If you have questions regarding Electron, their [Slack and forum](https://electron.atom.io/contact/) will be helpful as well. +If you need help *using* the addon with your application, may we recommend the excellent Ember community? You can the [various places to get help here](https://www.emberjs.com/community/). In particular, the [Ember community Discord](https://discordapp.com/invite/emberjs) has a `#topic-desktop` channel which is a great place to ask questions about `ember-electron`. If you have questions regarding Electron, their [Slack and forum](https://electron.atom.io/contact/) will be helpful as well. ## Development