From 99337a6e5447f3330e4f69dfb4c7807f4447429b Mon Sep 17 00:00:00 2001 From: Jack Mallers Date: Tue, 15 Aug 2017 14:15:54 -0500 Subject: [PATCH] feature(README): start README --- README.md | 336 +----------------------------------------------------- 1 file changed, 3 insertions(+), 333 deletions(-) diff --git a/README.md b/README.md index 0c8ee92f..72f0e715 100644 --- a/README.md +++ b/README.md @@ -1,334 +1,4 @@ -# electron-react-boilerplate +[zap](https://zap.jackmallers.com) +================================== -### A Boilerplate for Scalable Cross-Platform Desktop Apps - -
- -[![Build Status][travis-image]][travis-url] -[![Appveyor Build Status][appveyor-image]][appveyor-url] -[![Dependency Status][david_img]][david_site] -[![Github Tag][github-tag-image]][github-tag-url] -[![Join the chat at https://gitter.im/electron-react-boilerplate/Lobby](https://badges.gitter.im/electron-react-boilerplate/Lobby.svg)](https://gitter.im/electron-react-boilerplate/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) -[![OpenCollective](https://opencollective.com/electron-react-boilerplate/backers/badge.svg)](#backers) -[![OpenCollective](https://opencollective.com/electron-react-boilerplate/sponsors/badge.svg)](#sponsors) - -[![React](/internals/img/react-padded-90.png)](https://facebook.github.io/react/) -[![Webpack](/internals/img/webpack-padded-90.png)](https://webpack.github.io/) -[![Redux](/internals/img/redux-padded-90.png)](http://redux.js.org/) -[![React Router](/internals/img/react-router-padded-90.png)](https://github.com/ReactTraining/react-router) -[![Flow](/internals/img/flow-padded-90.png)](https://flowtype.org/) -[![ESLint](/internals/img/eslint-padded-90.png)](http://eslint.org/) -[![Jest](/internals/img/jest-padded-90.png)](https://facebook.github.io/jest/) -[![Yarn](/internals/img/yarn-padded-90.png)](https://yarnpkg.com/) - -[Electron](http://electron.atom.io/) application boilerplate based on [React](https://facebook.github.io/react/), [Redux](https://github.com/reactjs/redux), [React Router](https://github.com/reactjs/react-router), [Webpack](http://webpack.github.io/docs/), [React Transform HMR](https://github.com/gaearon/react-transform-hmr) for rapid application development. - -## Screenshot - -![Electron Boilerplate Demo](https://cloud.githubusercontent.com/assets/3382565/10557547/b1f07a4e-74e3-11e5-8d27-79ab6947d429.gif) - -## Install - -* **Note: requires a node version >= 7 and an npm version >= 4.** -* **If you have installation or compilation issues with this project, please see [our debugging guide](https://github.com/chentsulin/electron-react-boilerplate/issues/400)** - -First, clone the repo via git: - -```bash -git clone --depth=1 https://github.com/chentsulin/electron-react-boilerplate.git your-project-name -``` - -And then install dependencies with yarn. - -```bash -$ cd your-project-name -$ yarn -``` -**Note**: If you can't use [yarn](https://github.com/yarnpkg/yarn) for some reason, try `npm install`. - -## Run - -Start the app in the `dev` environment. This starts the renderer process in [**hot-module-replacement**](https://webpack.js.org/guides/hmr-react/) mode and starts a server that sends hot updates to the renderer process: - -```bash -$ npm run dev -``` - -You Run these two commands __simultaneously__ in different console tabs: - -```bash -$ npm run start-renderer-dev -$ npm run start-main-dev -``` - -## Editor Configuration -**Atom** -```bash -apm install editorconfig es6-javascript atom-ternjs javascript-snippets linter linter-eslint language-babel autocomplete-modules file-icons -``` - -**VSCode** -* [Editorconfig](https://github.com/editorconfig/editorconfig-vscode) -* [ESLint](https://github.com/Microsoft/vscode-eslint) -* [Flow](https://github.com/flowtype/flow-for-vscode) -* [Babel](https://github.com/dzannotti/vscode-babel) -* [Jest](https://github.com/orta/vscode-jest) -* [ES6 Snippets](https://marketplace.visualstudio.com/items?itemName=xabikos.JavaScriptSnippets) -* [React Snippets](https://marketplace.visualstudio.com/items?itemName=xabikos.ReactSnippets) -:bulb: *If you are using the `flow-for-vscode` plugin, make sure to disable the `flowtype-errors/show-errors` eslint rule in the `.eslintrc` by setting it to `0`* - -**Sublime** -* [Editorconfig Integration](https://github.com/sindresorhus/editorconfig-sublime#readme) -* [Linting](https://github.com/SublimeLinter/SublimeLinter3) -* [ESLint Integration](https://github.com/roadhump/SublimeLinter-eslint) -* [Syntax Highlighting](https://github.com/babel/babel-sublime) -* [Autocompletion](https://github.com/ternjs/tern_for_sublime) -* [Node Snippets](https://packagecontrol.io/packages/JavaScript%20%26%20NodeJS%20Snippets) -* [ES6 Snippets](https://packagecontrol.io/packages/ES6-Toolkit) - -**Others** -* [Editorconfig](http://editorconfig.org/#download) -* [ESLint](http://eslint.org/docs/user-guide/integrations#editors) -* Babel Syntax Plugin - -## DevTools - -#### Toggle Chrome DevTools - -- OS X: Cmd Alt I or F12 -- Linux: Ctrl Shift I or F12 -- Windows: Ctrl Shift I or F12 - -*See [electron-debug](https://github.com/sindresorhus/electron-debug) for more information.* - -#### DevTools extension - -This boilerplate includes the following DevTools extensions: - -* [Devtron](https://github.com/electron/devtron) - Install via [electron-debug](https://github.com/sindresorhus/electron-debug). -* [React Developer Tools](https://github.com/facebook/react-devtools) - Install via [electron-devtools-installer](https://github.com/GPMDP/electron-devtools-installer). -* [Redux DevTools](https://github.com/zalmoxisus/redux-devtools-extension) - Install via [electron-devtools-installer](https://github.com/GPMDP/electron-devtools-installer). - -You can find the tabs on Chrome DevTools. - -If you want to update extensions version, please set `UPGRADE_EXTENSIONS` env, just run: - -```bash -$ UPGRADE_EXTENSIONS=1 npm run dev - -# For Windows -$ set UPGRADE_EXTENSIONS=1 && npm run dev -``` - -:bulb: You can debug your production build with devtools by simply setting the `DEBUG_PROD` env variable: -``` -DEBUG_PROD=true npm run package -``` - - -## CSS Modules - -This boilerplate is configured to use [css-modules](https://github.com/css-modules/css-modules) out of the box. - -All `.css` file extensions will use css-modules unless it has `.global.css`. - -If you need global styles, stylesheets with `.global.css` will not go through the -css-modules loader. e.g. `app.global.css` - -If you want to import global css libraries (like `bootstrap`), you can just write the following code in `.global.css`: - -```css -@import "~bootstrap/dist/css/bootstrap.css"; -``` - -## Sass support - -If you want to use Sass in your app, you only need to import `.sass` files instead of `.css` once: -```js -import './app.global.scss'; -``` - -## Packaging - -To package apps for the local platform: - -```bash -$ npm run package -``` - -To package apps for all platforms: - -First, refer to [Multi Platform Build](https://github.com/electron-userland/electron-builder/wiki/Multi-Platform-Build) for dependencies. - -Then, -```bash -$ npm run package-all -``` - -To package apps with options: - -```bash -$ npm run package -- --[option] -``` - -## Further commands - -To run the application without packaging run - -```bash -$ npm run build -$ npm start -``` - -To run End-to-End Test - -```bash -$ npm run build -$ npm run test-e2e -``` - -#### Options - -See [electron-builder CLI Usage](https://github.com/electron-userland/electron-builder#cli-usage) - -## How to add modules to the project - -You will need to add other modules to this boilerplate, depending on the requirements of your project. For example, you may want to add [node-postgres](https://github.com/brianc/node-postgres) to communicate with PostgreSQL database, or -[material-ui](http://www.material-ui.com/) to reuse react UI components. - -⚠️ Please read following section before installing any dependencies ⚠️ - -### Module Structure - -This boilerplate uses a [two package.json structure](https://github.com/electron-userland/electron-builder/wiki/Two-package.json-Structure). This means, you will have two `package.json` files. - -1. `./package.json` in the root of your project -1. `./app/package.json` inside `app` folder - -### Which `package.json` file to use - -**Rule of thumb** is: all modules go into `./package.json` except native modules. Native modules go into `./app/package.json`. - -1. If the module is native to a platform (like node-postgres) or otherwise should be included with the published package (i.e. bcrypt, openbci), it should be listed under `dependencies` in `./app/package.json`. -2. If a module is `import`ed by another module, include it in `dependencies` in `./package.json`. See [this ESLint rule](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/no-extraneous-dependencies.md). Examples of such modules are `material-ui`, `redux-form`, and `moment`. -3. Otherwise, modules used for building, testing and debugging should be included in `devDependencies` in `./package.json`. - -### Further Readings - -See the wiki page, [Module Structure — Two package.json Structure](https://github.com/chentsulin/electron-react-boilerplate/wiki/Module-Structure----Two-package.json-Structure) to understand what is native module, the rationale behind two package.json structure and more. - -For an example app that uses this boilerplate and packages native dependencies, see [erb-sqlite-example](https://github.com/amilajack/erb-sqlite-example). - -## Static Type Checking -This project comes with Flow support out of the box! You can annotate your code with types, [get Flow errors as ESLint errors](https://github.com/amilajack/eslint-plugin-flowtype-errors), and get [type errors during runtime](https://github.com/codemix/flow-runtime) during development. Types are completely optional. - -## Native-like UI - -If you want to have native-like User Interface (OS X El Capitan and Windows 10), [react-desktop](https://github.com/gabrielbull/react-desktop) may perfect suit for you. - -## Dispatching redux actions from main process - -see discusses in [#118](https://github.com/chentsulin/electron-react-boilerplate/issues/118) and [#108](https://github.com/chentsulin/electron-react-boilerplate/issues/108) - -## How to keep the boilerplate updated - -If your application is a fork from this repo, you can add this repo to another git remote: - -```sh -git remote add upstream https://github.com/chentsulin/electron-react-boilerplate.git -``` - -Then, use git to merge some latest commits: - -```sh -git pull upstream master -``` - -## Maintainers - -- [C. T. Lin](https://github.com/chentsulin) -- [Jhen-Jie Hong](https://github.com/jhen0409) -- [Amila Welihinda](https://github.com/amilajack) - -## Backers - -Support us with a monthly donation and help us continue our activities. [[Become a backer](https://opencollective.com/electron-react-boilerplate#backer)] - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -## Sponsors - -Become a sponsor and get your logo on our README on Github with a link to your site. [[Become a sponsor](https://opencollective.com/electron-react-boilerplate#sponsor)] - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -## License -MIT © [C. T. Lin](https://github.com/chentsulin) - -[npm-image]: https://img.shields.io/npm/v/electron-react-boilerplate.svg?style=flat-square -[github-tag-image]: https://img.shields.io/github/tag/chentsulin/electron-react-boilerplate.svg -[github-tag-url]: https://github.com/chentsulin/electron-react-boilerplate/releases/latest -[travis-image]: https://travis-ci.org/chentsulin/electron-react-boilerplate.svg?branch=master -[travis-url]: https://travis-ci.org/chentsulin/electron-react-boilerplate -[appveyor-image]: https://ci.appveyor.com/api/projects/status/github/chentsulin/electron-react-boilerplate?svg=true -[appveyor-url]: https://ci.appveyor.com/project/chentsulin/electron-react-boilerplate/branch/master -[david_img]: https://img.shields.io/david/chentsulin/electron-react-boilerplate.svg -[david_site]: https://david-dm.org/chentsulin/electron-react-boilerplate + \ No newline at end of file