diff --git a/docs/tutorial/quick-start.md b/docs/tutorial/quick-start.md index aa8a5408e208..3735ff28bec6 100644 --- a/docs/tutorial/quick-start.md +++ b/docs/tutorial/quick-start.md @@ -5,246 +5,18 @@ providing a runtime with rich native (operating system) APIs. You could see it as a variant of the Node.js runtime that is focused on desktop applications instead of web servers. -This doesn't mean Electron is a JavaScript binding to graphical user interface -(GUI) libraries. Instead, Electron uses web pages as its GUI, so you could also -see it as a minimal Chromium browser, controlled by JavaScript. +The old "Quick Start" document that used to live here has been split up into +two documents: -### Main Process +* To check out how a simple Electron app is built, see +[Writing Your First Electron App][first-app] +* To check out the process architecture, see +[Main and Renderer Processes][processes]. -In Electron, the process that runs `package.json`'s `main` script is called -__the main process__. The script that runs in the main process can display a GUI -by creating web pages. +If you just came here to learn about Electron, check out the +[official guides][readme]. -### Renderer Process +[first-app]: ./first-app.md +[processes]: ./electron-apis.md#main-and-renderer-processes +[readme]: ../README.md -Since Electron uses Chromium for displaying web pages, Chromium's -multi-process architecture is also used. Each web page in Electron runs in -its own process, which is called __the renderer process__. - -In normal browsers, web pages usually run in a sandboxed environment and are not -allowed access to native resources. Electron users, however, have the power to -use Node.js APIs in web pages allowing lower level operating system -interactions. - -### Differences Between Main Process and Renderer Process - -The main process creates web pages by creating `BrowserWindow` instances. Each -`BrowserWindow` instance runs the web page in its own renderer process. When a -`BrowserWindow` instance is destroyed, the corresponding renderer process -is also terminated. - -The main process manages all web pages and their corresponding renderer -processes. Each renderer process is isolated and only cares about the web page -running in it. - -In web pages, calling native GUI related APIs is not allowed because managing -native GUI resources in web pages is very dangerous and it is easy to leak -resources. If you want to perform GUI operations in a web page, the renderer -process of the web page must communicate with the main process to request that -the main process perform those operations. - -In Electron, we have several ways to communicate between the main process and -renderer processes. Like [`ipcRenderer`](../api/ipc-renderer.md) and -[`ipcMain`](../api/ipc-main.md) modules for sending messages, and the -[remote](../api/remote.md) module for RPC style communication. There is also -an FAQ entry on [how to share data between web pages][share-data]. - -## Write your First Electron App - -Generally, an Electron app is structured like this: - -```text -your-app/ -├── package.json -├── main.js -└── index.html -``` - -The format of `package.json` is exactly the same as that of Node's modules, and -the script specified by the `main` field is the startup script of your app, -which will run the main process. An example of your `package.json` might look -like this: - -```json -{ - "name" : "your-app", - "version" : "0.1.0", - "main" : "main.js" -} -``` - -__Note__: If the `main` field is not present in `package.json`, Electron will -attempt to load an `index.js`. - -The `main.js` should create windows and handle system events, a typical -example being: - -```javascript -const {app, BrowserWindow} = require('electron') -const path = require('path') -const url = require('url') - -// Keep a global reference of the window object, if you don't, the window will -// be closed automatically when the JavaScript object is garbage collected. -let win - -function createWindow () { - // Create the browser window. - win = new BrowserWindow({width: 800, height: 600}) - - // and load the index.html of the app. - win.loadURL(url.format({ - pathname: path.join(__dirname, 'index.html'), - protocol: 'file:', - slashes: true - })) - - // Open the DevTools. - win.webContents.openDevTools() - - // Emitted when the window is closed. - win.on('closed', () => { - // Dereference the window object, usually you would store windows - // in an array if your app supports multi windows, this is the time - // when you should delete the corresponding element. - win = null - }) -} - -// This method will be called when Electron has finished -// initialization and is ready to create browser windows. -// Some APIs can only be used after this event occurs. -app.on('ready', createWindow) - -// Quit when all windows are closed. -app.on('window-all-closed', () => { - // On macOS it is common for applications and their menu bar - // to stay active until the user quits explicitly with Cmd + Q - if (process.platform !== 'darwin') { - app.quit() - } -}) - -app.on('activate', () => { - // On macOS it's common to re-create a window in the app when the - // dock icon is clicked and there are no other windows open. - if (win === null) { - createWindow() - } -}) - -// In this file you can include the rest of your app's specific main process -// code. You can also put them in separate files and require them here. -``` - -Finally the `index.html` is the web page you want to show: - -```html - - - - - Hello World! - - -

Hello World!

- We are using node , - Chrome , - and Electron . - - -``` - -## Run your app - -Once you've created your initial `main.js`, `index.html`, and `package.json` files, -you'll probably want to try running your app locally to test it and make sure it's -working as expected. - -### `electron` - -[`electron`](https://github.com/electron-userland/electron-prebuilt) is -an `npm` module that contains pre-compiled versions of Electron. - -If you've installed it globally with `npm`, then you will only need to run the -following in your app's source directory: - -```sh -electron . -``` - -If you've installed it locally, then run: - -#### macOS / Linux - -```sh -$ ./node_modules/.bin/electron . -``` - -#### Windows - -```sh -$ .\node_modules\.bin\electron . -``` - -#### Node v8.2.0 and later - -```sh -$ npx electron . -``` - -### Manually Downloaded Electron Binary - -If you downloaded Electron manually, you can also use the included -binary to execute your app directly. - -#### macOS - -```sh -$ ./Electron.app/Contents/MacOS/Electron your-app/ -``` - -#### Linux - -```sh -$ ./electron/electron your-app/ -``` - -#### Windows - -```sh -$ .\electron\electron.exe your-app\ -``` - -`Electron.app` here is part of the Electron's release package, you can download -it from [here](https://github.com/electron/electron/releases). - -### Run as a distribution - -After you're done writing your app, you can create a distribution by -following the [Application Distribution](./application-distribution.md) guide -and then executing the packaged app. - -### Try this Example - -Clone and run the code in this tutorial by using the [`electron/electron-quick-start`](https://github.com/electron/electron-quick-start) -repository. - -**Note**: Running this requires [Git](https://git-scm.com) and [Node.js](https://nodejs.org/en/download/) (which includes [npm](https://npmjs.org)) on your system. - -```sh -# Clone the repository -$ git clone https://github.com/electron/electron-quick-start -# Go into the repository -$ cd electron-quick-start -# Install dependencies -$ npm install -# Run the app -$ npm start -``` - -For more example apps, see the -[list of boilerplates](https://electronjs.org/community#boilerplates) -created by the awesome electron community. - -[share-data]: ../faq.md#how-to-share-data-between-web-pages