Skip to content

Commit c2984f7

Browse files
shinxishinxi
committed
📚 Doc Update
1 parent 6c8ae70 commit c2984f7

16 files changed

+398
-148
lines changed

‎.gitignore

+1-1
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
/coverage
1313

1414
# production
15-
/build
15+
1616

1717
# misc
1818
.DS_Store

‎README.md

+50-45
Original file line numberDiff line numberDiff line change
@@ -1,55 +1,60 @@
1-
# React Boilerplate - A starter boilerplate for React based web app project, powered by Material UI.
1+
# React Sample - A starter boilerplate for React based web app project, powered by create-react-app.
22

3-
4-
JavaScript library boilerplate, a web project template using:
5-
> JavaScript Library - [React](https://facebook.github.io/react/);
6-
> Application Architecture - [Redux](http://redux.js.org/);
7-
> Declarative routing for React - [React Router](https://github.com/ReactTraining/react-router);
8-
> React Components that Implement Google's Material Design. - [Material UI](https://github.com/callemall/material-ui);
3+
Besides [Create React App](https://github.com/facebookincubator/create-react-app). This sample project also uses:
4+
> Data Flow Management - [Redux](http://redux.js.org/);
5+
> Redux Ducks Pattern - [Ducks](https://github.com/erikras/ducks-modular-redux);
6+
> Declarative routing - [React Router](https://github.com/ReactTraining/react-router);
7+
> React Components that Implement Google's Material Design. - [Material UI](https://github.com/callemall/material-ui);
98
> Mock Server based on Express - [Mock Server](https://shinxi.github.io/react/#/6/1);
10-
> Future ECMASCript Standards - [ES6+](http://babeljs.io/docs/learn-es2015/);
11-
> Javascript Compiler - [Babel](http://babeljs.io/);
12-
> Module Bundler - [webpack](http://webpack.github.io/docs/tutorials/getting-started/);
139
14-
### Features
10+
## Overview
1511

16-
### Getting Started
12+
* [Getting Started](#getting-started)
13+
* [Technology stack](#technology-stack)
14+
* [Separation of front-end and back-end](#separation-of-front-end-and-back-end)
15+
* [Code Standard](#code-standard)
1716

18-
* Follow the [getting started guide](./getting-started.md) to download and run the project
17+
## Getting Started
1918

20-
### Build & Deploy
21-
* Follow [Build Doc](./build.md) to build and deploy your project.
19+
* Quick start
2220

23-
### Directory Layout
21+
See [How to run react-sample at local](./docs/how_to_run.md) for more detail.
2422

23+
* IDE Guidance for increasing development experience
24+
25+
See [How to setup JavaScript Development Environment - VS Code](./docs/how_to_setup_ide.md) for more detail.
26+
27+
* Project folder introduction
28+
29+
```bash
30+
react-sample/
31+
├── .editorconfig - editor config file
32+
├── .env - for absolute import
33+
├── .eslintrc.js - eslint settings
34+
├── package.json - npm 3rd-lib configuration
35+
├── README.md
36+
├── node_modules - npm 3rd libraries
37+
├── public - assets that won't be processed by webpack
38+
│ └── oauth_callback - oauth callback
39+
│ └── index.html
40+
│ └── favicon.ico
41+
├── server - mock server
42+
└── src - source codes
43+
└── index.css - entry file css
44+
└── index.js - entry file
45+
└── redux/ - redux by ducks pattern
46+
└── components/ - Dumb components
47+
└── containers/ - Smart components that connected to redux
2548
```
26-
.
27-
├── /build/ # The folder for compiled output
28-
├── /node_modules/ # 3rd-party libraries and utilities
29-
├── /src/ # The source code of the application
30-
│ ├── /actions/ # Action creators that allow to trigger a dispatch to stores
31-
│ ├── /components/ # React components
32-
│ ├── /containers/ # React containers
33-
│ ├── /constants/ # Constants (action types etc.)
34-
│ ├── /core/ # Core framework and utility functions
35-
│ ├── /public/ # Static files which are copied into the /build/public folder
36-
│ ├── /reducers/ # Redux reducers
37-
│ ├── /index.js # Client-side startup script
38-
│ └── /server.js # Server-side startup script
39-
├── /test/ # test codes
40-
└── /karma.conf.js # Karma test runner configuration
41-
└── /webpack.config.js # configurations for client-side and server-side bundles
42-
└── package.json # The list of 3rd party libraries and utilities
43-
```
4449
45-
### Learn More
46-
47-
* [Getting Started with React.js](http://facebook.github.io/react/)
48-
* [Redux Intro](http://redux.js.org/)
49-
* [Getting Started with Webpack](https://webpack.github.io/docs/tutorials/getting-started/)
50-
* [Learn ES6](https://babeljs.io/docs/learn-es6/)
51-
* [ES6 Features](https://github.com/lukehoban/es6features#readme)
52-
* [React How to by Peter Hunt](https://github.com/petehunt/react-howto)
53-
* [Webpack How to by Peter Hunt](https://github.com/petehunt/webpack-howto)
54-
* [React.js Questions on StackOverflow](http://stackoverflow.com/questions/tagged/reactjs)
55-
* [The Future of React](https://github.com/reactjs/react-future)
50+
## Technology stack
51+
52+
![High Level Diagram](./docs/images/high_level_diagram.png)
53+
54+
## Separation of front-end and back-end
55+
56+
See why and how at [Separation of front-end and back-end](./docs/separation_of_fe_be.md).
57+
58+
## Code Standard
59+
60+
Follow [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript).

‎build.md

-12
This file was deleted.

‎docs/downgrade_node_version.md

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Downgrade your node version if meet npm EINTEGRITY issue
2+
3+
If you met some simlar issue like below when run ```npm install```.
4+
5+
```bash
6+
npm ERR! code EINTEGRITY
7+
npm ERR! sha1-Ppz8p24IMzIm82W8+HD3ffvVQs0= integrity checksum failed when using sha1: wanted sha1-Ppz8p24IMzIm82W8+HD3ffvVQs0= but got sha1-Aw5ElVYJsWBoK0sZbA2EUFuTz1k=.
8+
```
9+
10+
That's probably you are using latest node version, and there's a known issue for latest npm. See [Issue#16861](https://github.com/npm/npm/issues/16861) and [Issue#17146](https://github.com/npm/npm/issues/17146).
11+
You need to downgrade your node version to use the LTS version.
12+
One way is to use [nvm](https://github.com/creationix/nvm) to manage your node version.
13+
Just run below commands when you installed nvm.
14+
15+
```bash
16+
nvm install --lts
17+
nvm use --lts
18+
nvm alias default node
19+
```

‎docs/how_to_debug_code.md

+49
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# How to debug your code at VS Code
2+
3+
## Prerequisites
4+
5+
* [How to setup JavaScript Development Environment - VS Code](./how_to_setup_ide.md)
6+
7+
Make sure the extension ```Debugger for Chrome``` has installed.
8+
9+
* [How to run react-sample at local](./how_to_run.md)
10+
11+
## Why
12+
13+
This enables you as a developer to write and debug your React code without leaving the editor, and most importantly it enables you to have a continuous development workflow, where context switching is minimal, as you don’t have to switch between tools.
14+
15+
## Steps
16+
17+
1. Open ```react-sample``` with VS Code
18+
1. Open Command Palette (⇧⌘P), type ```Open launch.json```, and select ```Debug: Open launch.json```
19+
1. Copy below content into the opened launch.json.
20+
21+
```javascript
22+
{
23+
"version": "0.2.0",
24+
"configurations": [
25+
{
26+
"type": "chrome",
27+
"request": "launch",
28+
"name": "Chrome",
29+
"url": "http://localhost:3000",
30+
"webRoot": "${workspaceRoot}/src",
31+
"userDataDir": "${workspaceRoot}/.vscode/chrome",
32+
"sourceMapPathOverrides": {
33+
"webpack:///src/*": "${webRoot}/*"
34+
}
35+
}
36+
]
37+
}
38+
```
39+
40+
1. Open terminal, type and run ```npm start```
41+
1. You can now write code, set a breakpoints, make a changes to the code, and debug your newly modified code — all from your editor. Start debugging in VS Code by pressing F5or by clicking the green debug icon.
42+
43+
## Workflow
44+
45+
Before:
46+
Make Code change -> Switch to Chome DevTools -> Set breakpoint -> Debug -> Switch back to VS Code -> Make code change
47+
48+
After:
49+
Make Code change -> Press F5 -> Set breakpoint -> Debug -> Make code change

‎docs/how_to_run.md

+74
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# How to run neocore-react-ui at local
2+
3+
## Prerequisites
4+
5+
* Make sure you have installed [Node.js](https://nodejs.org/en/) v6.11+ (You have to [downgrade your node version](./downgrade_node_version.md) if you encounter npm EINTEGRITY issue)
6+
* [How to setup JavaScript Development Environment - VS Code](./how_to_setup_ide.md)
7+
8+
## Install
9+
10+
1. Open terminal, clone your forked repo.
11+
12+
```git clone https://github.com/euler-ui/react-sample```
13+
14+
1. ```cd react-sample```
15+
1. Install dependencies.
16+
17+
```npm install```
18+
19+
1. Run the mock server.
20+
21+
```npm run server```
22+
23+
1. Open another terminal
24+
1. Start application.
25+
26+
```npm start```
27+
28+
1. Enjoy at the url printed at terminal. E.g., `http://localhost:3000/`
29+
30+
## VS Code setup for auto-formatting/linting
31+
32+
1. Open ```react-sample``` with VS Code
33+
1. Open Command Palette (⇧⌘P), type ```Open Workspace Settings```, and select ```Preferences: Open Workspace Settings```
34+
35+
![Workspace Settings](./images/VS_Code_Workspace_Settings.png)
36+
37+
1. Copy below content into opened settings.json.
38+
39+
```javascript
40+
41+
// Place your settings in this file to overwrite default and user settings.
42+
{
43+
// Format a file on save. A formatter must be available, the file must not be auto-saved, and editor must not be shutting down.
44+
"editor.formatOnSave": true,
45+
"stylelint.enable": true,
46+
"css.validate": false,
47+
"scss.validate": false,
48+
// Enable/disable default JavaScript formatter (For Prettier)
49+
"javascript.format.enable": false,
50+
// Use 'prettier-eslint' instead of 'prettier'. Other settings will only be fallbacks in case they could not be inferred from eslint rules.
51+
"prettier.eslintIntegration": true,
52+
"prettier.singleQuote": true,
53+
"prettier.trailingComma": "all",
54+
"prettier.printWidth": 100,
55+
"search.exclude": {
56+
"**/node_modules": true,
57+
"src/routes":true,
58+
"*config.js":true,
59+
".eslintrc.js":true,
60+
"*config.prod.js":true
61+
}
62+
}
63+
64+
```
65+
66+
1. Enjoy live lintin and auto formatting with VS Code
67+
68+
## Next steps
69+
70+
You may need to find out:
71+
72+
* [How to test front-end requests](./how_to_test_request.md).
73+
* [Separation of front-end and back-end](./separation_of_fe_be.md).
74+
* [How to debug your code at VS Code](./how_to_debug_code.md).

‎docs/how_to_setup_ide.md

+95
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# How to setup JavaScript Development Environment - [VS Code](https://code.visualstudio.com/)
2+
3+
## Expectations for IDE
4+
5+
### Code auto formatting/fixing & linting
6+
7+
* When I save a file, I want codes be auto formattered/fixed by [Javascript Rules](https://github.com/ServiceMax-Engineering/javascript)
8+
9+
* And IDE can display hints for those rules can't auto formattered/fixed.
10+
11+
### Code Navigation
12+
13+
* I want to easily navigate through files/APIs/methods etc.
14+
15+
### Auto complete
16+
17+
* I can't remember all API and it takes time to look into API documents, so that it'll be great if IDE can give me API suggestions.
18+
19+
### VCS integration
20+
21+
* That'll be nice if I can pull/commit/push code at IDE, and it'll be great if I can also view history/blame annotations/diff files etc.
22+
23+
### Debugging
24+
25+
* We are used to debugging JS code at browser, that's good. But if we can also debug JS code like Java code at IDE, that'll be nice. This enables write and debug our code without leaving the editor, and most importantly it enables a continuous development workflow, where context switching is minimal, as you don’t have to switch between tools.
26+
* Before:
27+
28+
Make Code change -> Switch to Chome DevTools -> Set breakpoint -> Debug -> Switch back to VS Code -> Make code change
29+
30+
* After:
31+
32+
Make Code change -> Press F5 -> Set breakpoint -> Debug -> Make code change
33+
34+
## What is VS Code
35+
36+
> VS Code is a new type of tool that combines the simplicity of a code editor with what developers need for their core **edit-build-debug** cycle. Code provides comprehensive editing and debugging support, an extensibility model, and lightweight integration with existing tools.
37+
38+
### VS Code Features
39+
40+
* Meet IntelliSense.
41+
42+
VS Code provides smart code-completion/parameter-info/quick-info/member-lists/code-navigation based on variable types, function definitions, and imported modules.
43+
44+
* Print statement debugging is a thing of the past.
45+
46+
Debug code right from the editor. Launch or attach to your running apps and debug with break points, call stacks, and an interactive console.
47+
48+
* Git commands built-in.
49+
50+
Working with Git and other SCM providers has never been easier. Review diffs, stage files, and make commits right from the editor. Push and pull from any hosted SCM service.
51+
52+
* Extensible and customizable.
53+
54+
By install extensions, we are able to have more awesome features like auto-formatting/linting etc.
55+
56+
## Why just VS Code, not Atom/Sublime/Webstorm
57+
58+
* With same IDE, it can save time on IDE configuration, with same IDE, code can have same formatting.
59+
* And given by awesome VS Code features above, just choose VS Code as our primary IDE.
60+
* VS Code is good at auto-complete/auto-fomratting/git integration/code navigation/debugging etc.
61+
* VS code is friendly to React apps, create-react-app mentioned VS Code multiple times at its [User Guide](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md).
62+
* Other IDEs like Atom/Sublime/Webstorm they are all good, expectations can also be achieved by installing plugins/extensions on each of them, but, we have to take time to figure out what plugins/extension need to use, it may takes 2 days or even more on setting up these IDEs. So Atom/Sublime/Webstorm will be seconday choice, and we might add other guildlines on these IDE later.
63+
64+
## Install
65+
66+
### Install VS Code
67+
68+
Follow [Running VS Code on Mac](https://code.visualstudio.com/docs/setup/mac) to install VS Code.
69+
70+
### Install Extensions
71+
72+
![VS_Code_Extensions](./images/VS_Code_Extensions.png)
73+
74+
Extension Name | Description | Requirement
75+
------------ | ------------- | -------------
76+
EditorConfig for VS Code | [EditorConfig](http://editorconfig.org/) for Visual Studio Code. EditorConfig helps developers define and maintain consistent coding styles between different editors and IDEs | Required
77+
ESLint | VS Code [ESLint](http://eslint.org/) extension. ESLint is an open source project originally created by Nicholas C. Zakas in June 2013. Its goal is to provide a pluggable linting utility for JavaScript.| Required
78+
Prettier | VS Code package to format your Javascript / Typescript / CSS using Prettier. | Required
79+
Debugger for Chrome | Debug your JavaScript code running in Google Chrome from VS Code. | Required
80+
React Redux ES6 Snippets | React-Redux snippets for Visual Studio Code using ES6 and arrow functions. | Required
81+
Reactjs code snippets | This extension contains code snippets for Reactjs and is based on the awesome babel-sublime-snippets package. | Required
82+
Git History | View git log along with the graph and details. View the history of a file (Git log) or the history of a line in a file (Git Blame). View a previous copy of the file. Compare a previous version with the version in the workspace or another. View commit log details for a selected commit. Compare commits. | Optional
83+
Git Lens | GitLens supercharges the built-in Visual Studio Code Git capabilities. It helps you to visualize code authorship at a glance via Git blame annotations and code lens, seamlessly navigate and explore the history of a file or branch, gain valuable insights via powerful comparison commands, and so much more. | Optional
84+
Sublime Babel | When using your favorite theme, Visual Studio Code doesn't always display syntax highlight colors as expected. This extension tries to mimic Sublime Text's babel-sublime package as much as possible to address poor coloring. | Optional
85+
vscode-jest|A comprehensive experience when using Facebook's Jest within a project.|Optional
86+
npm | This extension supports running npm scripts defined in the package.json file and validating the installed modules against the dependencies defined in the package.json. | Optional
87+
Npm Intellisense | Visual Studio Code plugin that autocompletes npm modules in import statements. | Optional
88+
Sublime Text Keymap | Sublime Text Keymap for VS Code | Optional
89+
90+
## Next steps
91+
92+
You may need to find out:
93+
94+
* [How to run react-sample at local](./how_to_run.md)
95+
* [How to debug at VS Code](./how_to_debug_code.md)

0 commit comments

Comments
 (0)