From fdd358f5fe0b692f71203a30ca5ec956cde11e8e Mon Sep 17 00:00:00 2001 From: Sheng Di Date: Tue, 26 Jun 2018 21:19:20 -0700 Subject: [PATCH] [docs] add app archetype flow docs (#816) * add app archetype flow docs * add links to docs * add flow faq * include gist contents * add code blocks type & polish text --- docs/SUMMARY.md | 146 +++++++++--------- .../intermediate/app-archetype/README.md | 15 +- .../intermediate/app-archetype/flow-faq.md | 33 ++++ .../intermediate/app-archetype/flow.md | 75 +++++++++ 4 files changed, 190 insertions(+), 79 deletions(-) create mode 100644 docs/chapter1/intermediate/app-archetype/flow-faq.md create mode 100644 docs/chapter1/intermediate/app-archetype/flow.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index dac4b7c64..b8f6a4832 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -2,94 +2,96 @@ ### Introduction -- [Read Me](README.md) -- [Overview](overview.md) - - [What is Electrode](overview/what-is-electrode.md) - - [Why Use Electrode](overview/why-use-electrode.md) - - [Requirements](overview/requirements.md) - - [What are Archetypes](/overview/what-are-archetypes.md) +- [Read Me](README.md) +- [Overview](overview.md) + - [What is Electrode](overview/what-is-electrode.md) + - [Why Use Electrode](overview/why-use-electrode.md) + - [Requirements](overview/requirements.md) + - [What are Archetypes](/overview/what-are-archetypes.md) ### Quick Start -- [Getting Started With Electrode](/chapter1/quick-start/start-with-electrode.md) +- [Getting Started With Electrode](/chapter1/quick-start/start-with-electrode.md) - - [Start With Electrode Ignite](/chapter1/quick-start/start-with-ignite.md) - - [Create an Electrode App](/chapter1/quick-start/start-with-app.md) - - [Create an Electrode Component](/chapter1/quick-start/start-with-component.md) + - [Start With Electrode Ignite](/chapter1/quick-start/start-with-ignite.md) + - [Create an Electrode App](/chapter1/quick-start/start-with-app.md) + - [Create an Electrode Component](/chapter1/quick-start/start-with-component.md) -- [Developing Your Electrode App](chapter1/quick-start/further-develop-app.md) +- [Developing Your Electrode App](chapter1/quick-start/further-develop-app.md) - - [Build Your App](/chapter1/further-develop-app/build-app.md) - - [What's Inside](/chapter1/further-develop-app/whats-inside.md) - - [Deploy Your App](/chapter1/further-develop-app/deploy-your-app.md) + - [Build Your App](/chapter1/further-develop-app/build-app.md) + - [What's Inside](/chapter1/further-develop-app/whats-inside.md) + - [Deploy Your App](/chapter1/further-develop-app/deploy-your-app.md) -- [Developing Electrode Components](chapter1/quick-start/further-develop-component.md) - - [Low-Level Components](/chapter1/further-develop-component/low-level-components.md) - - [Component Helpers](/chapter1/further-develop-component/component-helpers.md) - - [Develop Styles](/chapter1/further-develop-component/develop-styles.md) - - [Develop Main Component](chapter1/further-develop-component/develop-main-component.md) - - [Add Components to Demo App](/chapter1/further-develop-component/add-to-demo-app.md) - - [Build and Demo](/chapter1/further-develop-component/build-and-demo.md) - - [Test Components](/chapter1/further-develop-component/test-components.md) +- [Developing Electrode Components](chapter1/quick-start/further-develop-component.md) + - [Low-Level Components](/chapter1/further-develop-component/low-level-components.md) + - [Component Helpers](/chapter1/further-develop-component/component-helpers.md) + - [Develop Styles](/chapter1/further-develop-component/develop-styles.md) + - [Develop Main Component](chapter1/further-develop-component/develop-main-component.md) + - [Add Components to Demo App](/chapter1/further-develop-component/add-to-demo-app.md) + - [Build and Demo](/chapter1/further-develop-component/build-and-demo.md) + - [Test Components](/chapter1/further-develop-component/test-components.md) ### Intermediate -- [Intermediate](chapter1/Intermediate.md) -- [Application Archetype](/chapter1/intermediate/app-archetype/README.md) - - - [Customize Config](/chapter1/intermediate/app-archetype/customize-config.md) - - [Eslint Config](/chapter1/intermediate/app-archetype/eslint.md) - - [Webpack Config](/chapter1/intermediate/app-archetype/webpack-config.md) - - [Environment Variables](/chapter1/intermediate/app-archetype/env-vars.md) - - [Extract Styles](/chapter1/intermediate/app-archetype/extract-styles.md) - - [Unit Tests](/chapter1/intermediate/app-archetype/unit-tests.md) - -- [Component Archetype](chapter1/intermediate/component-archetype/README.md) - - - [Structure](/chapter1/intermediate/component-archetype/component-archetype-structure.md) - - [Webpack Config](/chapter1/intermediate/component-archetype/webpack-config.md) - - [Extract Styles](/chapter1/intermediate/component-archetype/extract-styles.md) - - [Unit Tests](/chapter1/intermediate/component-archetype/unit-tests.md) - -- [Build a Server Plugin](chapter1/intermediate/build-a-server-plugin.md) -- [React App Routes](chapter1/intermediate/react-routes/react-routes.md) - - [Add your routes](chapter1/intermediate/react-routes/add-routes.md) - - [Component for a route](chapter1/intermediate/react-routes/route-component.md) - - [Route action on server side](chapter1/intermediate/react-routes/server-actions.md) -- [Server Config](chapter1/intermediate/server-config.md) -- [More Deployments](chapter1/intermediate/more-deployments.md) - - [Docker](chapter1/intermediate/more-deployments/docker.md) - - [Kubernetes](chapter1/intermediate/more-deployments/kubernetes.md) -- [Build with material-ui](chapter1/intermediate/build-with-material-ui.md) -- [Build a Progressive Web App](chapter1/intermediate/build-a-progressive-web-app.md) -- [Server Side Data Hydration](chapter1/intermediate/server-side-data-hydration.md) +- [Intermediate](chapter1/Intermediate.md) +- [Application Archetype](/chapter1/intermediate/app-archetype/README.md) + + - [Customize Config](/chapter1/intermediate/app-archetype/customize-config.md) + - [Eslint Config](/chapter1/intermediate/app-archetype/eslint.md) + - [Webpack Config](/chapter1/intermediate/app-archetype/webpack-config.md) + - [Environment Variables](/chapter1/intermediate/app-archetype/env-vars.md) + - [Extract Styles](/chapter1/intermediate/app-archetype/extract-styles.md) + - [Unit Tests](/chapter1/intermediate/app-archetype/unit-tests.md) + - [Flow](/chapter1/intermediate/app-archetype/flow.md) + - [Flow FAQ](/chapter1/intermediate/app-archetype/flow-faq.md) + +- [Component Archetype](chapter1/intermediate/component-archetype/flow.md) + + - [Structure](/chapter1/intermediate/component-archetype/component-archetype-structure.md) + - [Webpack Config](/chapter1/intermediate/component-archetype/webpack-config.md) + - [Extract Styles](/chapter1/intermediate/component-archetype/extract-styles.md) + - [Unit Tests](/chapter1/intermediate/component-archetype/unit-tests.md) + +- [Build a Server Plugin](chapter1/intermediate/build-a-server-plugin.md) +- [React App Routes](chapter1/intermediate/react-routes/react-routes.md) + - [Add your routes](chapter1/intermediate/react-routes/add-routes.md) + - [Component for a route](chapter1/intermediate/react-routes/route-component.md) + - [Route action on server side](chapter1/intermediate/react-routes/server-actions.md) +- [Server Config](chapter1/intermediate/server-config.md) +- [More Deployments](chapter1/intermediate/more-deployments.md) + - [Docker](chapter1/intermediate/more-deployments/docker.md) + - [Kubernetes](chapter1/intermediate/more-deployments/kubernetes.md) +- [Build with material-ui](chapter1/intermediate/build-with-material-ui.md) +- [Build a Progressive Web App](chapter1/intermediate/build-a-progressive-web-app.md) +- [Server Side Data Hydration](chapter1/intermediate/server-side-data-hydration.md) ### Advanced -- [Advanced](chapter1/advanced.md) -- [Stand Alone Modules](chapter1/advanced/stand-alone-modules.md) - - [Confippet](chapter1/advanced/stand-alone-modules/confippet.md) - - [Above The Fold Rendering](chapter1/advanced/stand-alone-modules/above-the-fold-rendering.md) - - [Server Side Render Caching + Profiling](chapter1/advanced/stand-alone-modules/server-side-render-caching-+-profiling.md) - - [Stateless CSRF Validation](chapter1/advanced/stand-alone-modules/stateless-csrf-validation.md) - - [Redux Router Engine](chapter1/advanced/stand-alone-modules/redux-router-engine.md) -- [Powerful Electrode Tools](chapter1/advanced/powerful-electrode-tools.md) - - [Electrify](chapter1/advanced/powerful-electrode-tools/electrify.md) - - [Electrode Explorer](chapter1/advanced/powerful-electrode-tools/electrode-explorer.md) - - [Bundle Analyzer](chapter1/advanced/powerful-electrode-tools/bundle-analyzer.md) -- [Electrode Boilerplate](chapter1/advanced/you-can-view-an-example-bundleanalyzetsv-output-using-the-electrode-boilerplate-code.md) -- [Over the air](chapter1/over-the-air.md) - - [React Native and Over the Air](chapter1/over-the-air/react-native-and-over-the-air.md) +- [Advanced](chapter1/advanced.md) +- [Stand Alone Modules](chapter1/advanced/stand-alone-modules.md) + - [Confippet](chapter1/advanced/stand-alone-modules/confippet.md) + - [Above The Fold Rendering](chapter1/advanced/stand-alone-modules/above-the-fold-rendering.md) + - [Server Side Render Caching + Profiling](chapter1/advanced/stand-alone-modules/server-side-render-caching-+-profiling.md) + - [Stateless CSRF Validation](chapter1/advanced/stand-alone-modules/stateless-csrf-validation.md) + - [Redux Router Engine](chapter1/advanced/stand-alone-modules/redux-router-engine.md) +- [Powerful Electrode Tools](chapter1/advanced/powerful-electrode-tools.md) + - [Electrify](chapter1/advanced/powerful-electrode-tools/electrify.md) + - [Electrode Explorer](chapter1/advanced/powerful-electrode-tools/electrode-explorer.md) + - [Bundle Analyzer](chapter1/advanced/powerful-electrode-tools/bundle-analyzer.md) +- [Electrode Boilerplate](chapter1/advanced/you-can-view-an-example-bundleanalyzetsv-output-using-the-electrode-boilerplate-code.md) +- [Over the air](chapter1/over-the-air.md) + - [React Native and Over the Air](chapter1/over-the-air/react-native-and-over-the-air.md) ### Contribute -- [Contributing](contributing.md) - - [Contribute](contribute.md) - - [Community](community.md) +- [Contributing](contributing.md) + - [Contribute](contribute.md) + - [Community](community.md) ### Resources -- [Resources](resources.md) - - [Further Reading](resources/further-reading.md) - - [Glossary](resources/glossary.md) - - [FAQs](resources/faqs.md) +- [Resources](resources.md) + - [Further Reading](resources/further-reading.md) + - [Glossary](resources/glossary.md) + - [FAQs](resources/faqs.md) diff --git a/docs/chapter1/intermediate/app-archetype/README.md b/docs/chapter1/intermediate/app-archetype/README.md index f96e5ee76..8f8d597c9 100644 --- a/docs/chapter1/intermediate/app-archetype/README.md +++ b/docs/chapter1/intermediate/app-archetype/README.md @@ -1,10 +1,11 @@ # Electrode React Application Archetype -The application archetype is a pair of npm modules that provide common patterns and configurations for developing a universal React application. With the application generator, you can quickly create and start developing a React application. The defaults generally are well suited for many applications, but it is possible to customize some features and enable more advanced features for your specific needs. +The application archetype is a pair of npm modules that provide common patterns and configurations for developing a universal React application. With the application generator, you can quickly create and start developing a React application. The defaults generally are well suited for many applications, but it is possible to customize some features and enable more advanced features for your specific needs. -- [Customize Config](/chapter1/intermediate/app-archetype/customize-config.md) -- [Eslint Config](/chapter1/intermediate/app-archetype/eslint.md) -- [Webpack Config](/chapter1/intermediate/app-archetype/webpack-config.md) -- [Environment Variables](/chapter1/intermediate/app-archetype/env-vars.md) -- [Extract Styles](/chapter1/intermediate/app-archetype/extract-styles.md) -- [Unit Tests](/chapter1/intermediate/app-archetype/unit-tests.md) \ No newline at end of file +- [Customize Config](/chapter1/intermediate/app-archetype/customize-config.md) +- [Eslint Config](/chapter1/intermediate/app-archetype/eslint.md) +- [Webpack Config](/chapter1/intermediate/app-archetype/webpack-config.md) +- [Environment Variables](/chapter1/intermediate/app-archetype/env-vars.md) +- [Extract Styles](/chapter1/intermediate/app-archetype/extract-styles.md) +- [Unit Tests](/chapter1/intermediate/app-archetype/unit-tests.md) +- [Flow](/chapter1/intermediate/app-archetype/flow.md) diff --git a/docs/chapter1/intermediate/app-archetype/flow-faq.md b/docs/chapter1/intermediate/app-archetype/flow-faq.md new file mode 100644 index 000000000..f8bd03558 --- /dev/null +++ b/docs/chapter1/intermediate/app-archetype/flow-faq.md @@ -0,0 +1,33 @@ +# Flow FAQs + +The following is a list of Frequently Asked Questions you may encounter when integrating with Flow. We put questions together to solve them in a more scalable way. + +### How to add type to handlerFunction? + +Issue Description: + +Cannot assign this.handlerFunction.bind(...) to this.handlerFunction because property handlerFunction is not writable. + +Resolution: + +Update `this.handlerFunction = this.handlerFunction.bind(this);` + +to `(this:any).handlerFunction = this.handlerFunction.bind(this);` + +### How to add type to EventTarget? + +```javascript +declare type ElementEventTemplate = { + target: E +} & Event; + +declare type InputEvent = ElementEventTemplate; +``` + +### How to add type to function callbacks? + +```javascript +function method(callback: (error: Error | null, value: string | null) => void) { + // ... +} +``` diff --git a/docs/chapter1/intermediate/app-archetype/flow.md b/docs/chapter1/intermediate/app-archetype/flow.md new file mode 100644 index 000000000..6bc903e59 --- /dev/null +++ b/docs/chapter1/intermediate/app-archetype/flow.md @@ -0,0 +1,75 @@ +# Flow + +[`Flow`](https://flow.org/en/) is a static type checker for Javascript and widely used by front-end developers nowadays. It helps us to code faster, smarter and more confidently. Since Electrode has already got Babel in place, we need to set up `Flow` with babel: use babel to compile the code and integrate `Flow` into Electrode application. + +### Flow with babel + +The Electrode app archetype adds [`babel-preset-flow`](https://babeljs.io/docs/en/babel-preset-flow/), which contains a [`babel-plugin-transform-flow-strip-types`](https://babeljs.io/docs/en/babel-plugin-transform-flow-strip-types/) plugin for stripping `Flow` types away so that the program can run. It also adds [`flow-bin`](https://github.com/flowtype/flow-bin) to run `Flow` and check if the type is valid. + +### Flow with eslint + +The Electrode app archetype uses the [`eslint-plugin-flowtype`](https://github.com/gajus/eslint-plugin-flowtype) plugin as the linting rules for ESLint `Flow` type. The rules are enabled via the `.eslintrc-react*` files located in the `electrode-archetype-react-app-dev` configuration folder. + +### Flow with Electrode app + +##### - configuration + +When we initiate `Flow` in our app, it creates `.flowconfig` file at the root level of your application. The `.flowconfig` file contains several sections: + +```markdown +[ignore] +ignore files matching the specified regular expressions when type checking your code. + +[include] +include the specified files or directories. + +[libs] +include the specified library definitions when type checking your code. +``` + +Checkout [here](https://flow.org/en/docs/config/) for more information. + +##### - Integrate existing App with Flow + +- prepare the code + + Please be sure your `electrode-archetype-react-app*` version is `5.3.0` or later. + + To initialize the `Flow`, you can run `clap initflow`. This will generate a default `.flowconfig` file to configure `Flow` for your app. + + `Flow` will only be checked when the user has flow code. To mark the flow files, you can place `// @flow` or `/* @flow */` before any code in the Javascript files. + + This flag is in the form of a normal JavaScript comment annotated with @flow. The Flow background process gathers all the files with this flag and uses the type information available from all of these files to ensure consistency and error free programming. + +- check the code + + If you want to run the Flow Background Process, you can start the process that allows `Flow` to check your code incrementally and with great speed by `flow status`. + + To stop the background process, run `flow stop`. + + You can also type flow to accomplish the same effect as status is the default flag to the flow binary. At any point that you want to check for errors, just run `flow`. + +- flow FAQs + + You may experience similar issues when integrating with `Flow`, please check [here](/chapter1/intermediate/app-archetype/flow-faq.md) for solutions. + +##### - Generate a new App with Flow + +A new Electrode React App can be generated by running with `electrode-ignite`: + +```bash +ignite generate-app +``` + +To enable `Flow`, you can reply `yes` to the following question: + +```bash +Would you like to generate .flowconfig for flow usage? +``` + +To know more about `electrode-ignite`, please read [here.](/chapter1/quick-start/start-with-ignite.md) + +### References + +- [Use Flow with Babel](https://medium.freecodecamp.org/using-flow-with-babel-c04fdca8d14d) +- [Flow installation](https://flow.org/en/docs/install/)