Skip to content

Commit 83d13fd

Browse files
nklaymannklayman
committed
update README.md
1 parent 5589f46 commit 83d13fd

File tree

1 file changed

+82
-75
lines changed

1 file changed

+82
-75
lines changed

‎README.md

Lines changed: 82 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,12 @@
1+
12
# Vue CLI Plugin Electron Builder
23

3-
A Vue Cli 3 plugin for Electron with no required configuration that uses [Electron Builder](https://www.electron.build/) and [Electron Webpack](https://webpack.electron.build/).
4+
A Vue Cli 3 plugin for Electron with no required configuration that uses [Electron Builder](https://www.electron.build/).
45

56
**IMPORTANT: Your app must be created with Vue-CLI 3 (vue create my-app), will not work with Vue-CLI 2 (vue init webpack my-app)!**
67

8+
**IMPORTANT: This is the alpha version of vue-cli-plugin-electron-builder! It is only recommended that you use this if you want to test it out and report bugs, not in production. Check back soon for a beta release.**
9+
710
## Quick Start:
811

912
Open a terminal in the directory of your app created with Vue-CLI 3.
@@ -12,7 +15,7 @@ Then, install and invoke the generator of vue-cli-plugin-electron-builder by run
1215

1316
`vue add electron-builder`
1417

15-
That's It! Your ready to go!
18+
That's It! You're ready to go!
1619

1720
### To start a development server:
1821

@@ -26,7 +29,7 @@ or if you use NPM:
2629

2730
### To build your app:
2831

29-
With yarn:
32+
With Yarn:
3033

3134
`yarn build:electron`
3235

@@ -37,101 +40,105 @@ or with NPM:
3740
### Folder Structure:
3841

3942
```
40-
├── dist/ # where electron-webpack outputs compiled files (this will overwrite normal build files)
41-
42-
│ └── ...
43-
4443
├── dist_electron/
45-
46-
│ ├── [target platform]-unpacked # unpacked Electron app (main exe and supporting files)
47-
48-
│ ├── [application name] setup [version].[target binary (exe|dmg|rpm...)] # installer for Electron app
49-
44+
│ ├── bundled/.. # where webpack outputs compiled files
45+
│ ├── [target platform]-unpacked/.. # unpacked Electron app (main app and supporting files)
46+
│ ├── [application name] setup [version].[target binary (exe|dmg|rpm...)] # installer for Electron app
47+
│ ├── background.js # compiled background file used for serve:electron
5048
│ └── ...
51-
5249
├── src/
53-
54-
│ ├─── main/
55-
56-
│ │ └── [main|index].[js|ts] # Electron entry file (for Electron's main process)
57-
58-
│ ├── [main|index].[js|ts] # your app's entry file (for Electron's render process)
59-
50+
│ ├── background.[js|ts] # electron entry file (for Electron's main process)
51+
│ ├── [main|index].[js|ts] # your app's entry file (for Electron's render process)
6052
│ └── ...
61-
62-
├── electron-builder.[json|yml] # electron-builder configuration options (can also be placed in package.json under the "build" key)
63-
64-
├── electron-webpack.[json|yml] # electron-webpack configuration options (can also be placed in package.json under the "electronWebpack" key)
65-
66-
├── package.json # your app's package.json file
67-
53+
├── package.json # your app's package.json file
6854
├── ...
6955
```
7056

71-
## Further Configuration:
72-
73-
Initial configuration is already set for you in your app's package.json, but if you want to modify it:
57+
## Configuration:
7458

75-
### CLI Options:
76-
77-
When building your app, any arguments will be passed to electron-builder. To pass an argument/arguments to electron-webpack, place them after --webpack.
78-
79-
**Example:**
80-
81-
`yarn build:electron [electron-builder options] --webpack [electron-webpack options]`
82-
83-
### Electron Builder:
59+
### Configuring Electron Builder:
8460

8561
To see avalible options, check out [Electron Builder Configuration Options](https://www.electron.build/configuration/configuration)
8662

87-
As per Electron Builder's documentation, they can be applied:
88-
89-
> * in the `package.json` file of your project using the `build` key on the top level:
90-
>
91-
> ```
92-
> "build": {
93-
> "appId": "com.example.app"
94-
> }
95-
> ```
96-
>
97-
> * or through the `--config <path/to/yml-or-json5-or-toml>` option (defaults to `electron-builder.yml`(or `json`, or [json5](http://json5.org/), or [toml](https://github.com/toml-lang/toml))).
98-
>
99-
> ```
100-
> appId: "com.example.app"
101-
> ```
102-
>
103-
> If you want to use [toml](https://en.wikipedia.org/wiki/TOML), please install `yarn add toml --dev`.
104-
>
105-
> Most of the options accept `null` — for example, to explicitly set that DMG icon must be default volume icon from the OS and default rules must be not applied (i.e. use application icon as DMG icon), set `dmg.icon` to `null`
106-
107-
### Electron Webpack:
108-
109-
To see avalible options, check out [Electron Webpack Configuration Options](https://webpack.electron.build/configuration)
63+
They can be placed under the `builderOptions` key in vue-cli-plugin-electron-builder's plugin options in `vue.config.js`
64+
```javascript
65+
// vue.config.js
11066

111-
As per Electron Webpack's documentation, they can be applied:
67+
module.exports= {
68+
pluginOptions: {
69+
electronBuilder: {
70+
builderOptions: {
71+
// options placed here will be merged with default configuration and passed to electron-builder
72+
}
73+
}
74+
}
75+
}
76+
```
77+
### Webpack configuration:
78+
Your regular config is used for bundling the renderer process (your app). To modify the webpack config for the electron main process only, use the `chainWebpackMainProcess` function under vue-cli-plugin-electron-builder's plugin options in `vue.config.js`. To learn more about webpack chaining, see [webpack-chain](https://github.com/mozilla-neutrino/webpack-chain). The function should take a config argument, modify it through webpack-chain, and then return it.
79+
80+
**Note: Do NOT change the webpack output directory for the main process! See changing output directory below for more info. To change the entry point for the main process, use the `mainProcessFile` key, DO NOT modify it in through chaining.**
81+
82+
```javascript
83+
// vue.config.js
11284

113-
> in `package.json` at `electronWebpack` or in a separate `electron-webpack.(json|json5|yml)`.
85+
module.exports = {
86+
configureWebpack: {
87+
// Configuration applied to all builds
88+
},
89+
pluginOptions: {
90+
electronBuilder: {
91+
chainWebpackMainProcess: (config) => {
92+
// Chain webpack config for electron main process only
93+
},
94+
mainProcessFile: 'src/myBackgroundFile.js'
95+
}
96+
}
97+
};
98+
```
11499

115-
To modify the webpack config for electron builds only, use the webpackConfig object under vue-cli-plugin-electron-builder's plugin options in `vue.config.js`.
100+
### Changing the output directory:
101+
If you don't want your files outputted into dist_electron, you can choose a custom folder in vue-cli-plugin-electron-builder's plugin options.
102+
**Note: after changing this, you MUST update the main field of your `package.json` to `[new dir]/bundled/background.js`. It is also recommended to add the new directory to your .gitignore file.**
103+
```javascript
104+
// vue.config.js
116105

106+
module.exports = {
107+
pluginOptions: {
108+
electronBuilder: {
109+
outputDir: 'electron-builder-output-dir'
110+
}
111+
}
112+
};
117113
```
114+
### Adding TypeScript Support:
115+
Typescript support is automatic and requires no configuration, just add the `@vue/typescript` cli plugin. There are a few options for configuring typescript if necessary:
116+
117+
```javascript
118118
// vue.config.js
119119

120-
module.exports = {
121-
configureWebpack: {
122-
// Non-electron build/serve configuration
123-
// Aliases will be automatically copied from standard config to electron config
124-
},
120+
module.exports = {
125121
pluginOptions: {
126122
electronBuilder: {
127-
webpackConfig: {
128-
// your electron-only webpack config
129-
}
123+
disableMainProcessTypescript: false, // Manually disable typescript plugin for main process. Enable if you want to use regular js for the main process (src/background.js by default).
124+
mainProcessTypeChecking: false // Manually enable type checking during webpck bundling for background file.
130125
}
131126
}
132127
};
133128
```
129+
You may also want to set `mainWindow`'s type to `any` and change `process.env.WEBPACK_DEV_SERVER_URL` to `process.env.WEBPACK_DEV_SERVER_URL as string` to fix type errors.
130+
131+
## How it works:
132+
### Build command:
133+
The build command consists of three main phases: render build, main build, and electron-builder build:
134+
135+
1. Render build: This phase calls `vue-cli-service build` with some custom configuration so it works properly with electron. (The render process is your standard app.)
136+
2. Main build: This phase is where vue-cli-plugin-electron-builder bundles your background file for the main process (`src/background.js`).
137+
3. Electron-builder build: This phase uses [electron-builder](https://www.electron.build) to turn your web app code into an desktop app powered by [Electron](https://electronjs.org).
134138

135-
#### Adding TypeScript Support:
139+
### Serve command:
140+
The serve command also consists of 3 main phases: main build, dev server launch, and electron launch:
136141

137-
When you invoke/add vue-cli-plugin-electron-builder, it will ask you if you use TypeScript and configure accordingly. However, if you answered no and decide to add TypeScript later on, you must install electron-webpack-ts: `yarn add electron-webpack-ts --dev` (or with NPM: `npm install --save-dev electron-webpack-ts`).
142+
1. Main build: This phase, like in the build command, bundles your app's main process, but in development mode.
143+
2. Dev server launch: This phase starts the built in dev server with no special arguments, just hosting your app as normal.
144+
3. Electron launch: This phase launches electron and tells it to load the url of the above dev server.

0 commit comments

Comments
 (0)