Skip to content

Commit

Permalink
Update docs.
Browse files Browse the repository at this point in the history
  • Loading branch information
supnate committed Mar 26, 2018
1 parent 67de450 commit 0c3fdb0
Show file tree
Hide file tree
Showing 10 changed files with 25 additions and 150 deletions.
6 changes: 4 additions & 2 deletions README.md
@@ -1,8 +1,10 @@
# <img src="/images/logo_text.png?raw=true" width="260">

> 🎉🎉🎉 [Introducing Rekit Studio: a real IDE for React and Redux development](https://medium.com/@nate_wang/introducing-rekit-studio-a-real-ide-for-react-and-redux-development-baf0c99cb542)
> 🔥 [Rekit Now Creates Apps By Create-react-app](https://medium.com/@nate_wang/rekit-now-creates-apps-by-create-react-app-3f0d82fd64f3)
> 🎉🎉🎉 [Using Rekit Studio in an Existing React Project](https://medium.com/@nate_wang/using-rekit-studio-in-an-existing-react-project-39713d9667b)
> 🎉 [Introducing Rekit Studio: a real IDE for React and Redux development](https://medium.com/@nate_wang/introducing-rekit-studio-a-real-ide-for-react-and-redux-development-baf0c99cb542)
> 🎉 [Using Rekit Studio in an Existing React Project](https://medium.com/@nate_wang/using-rekit-studio-in-an-existing-react-project-39713d9667b)
Rekit is a toolkit for building scalable web applications with React, Redux and React-router. It's an all-in-one solution for creating modern React apps.

Expand Down
4 changes: 2 additions & 2 deletions docs/app.md
Expand Up @@ -32,11 +32,11 @@ As the above picture shows, Rekit creates an application with a special folder s
| | +-- styles
| --- tools
| | +-- plugins
| | |-- server.js
| --- scripts
| | |-- build.js
| | |-- start.js
| | |-- ...
|-- .eslintrc
|-- .gitignore
|-- webpack-config.js
|-- ...
```
49 changes: 0 additions & 49 deletions docs/cli.md
Expand Up @@ -27,55 +27,6 @@ rekit install <plugin-name>

This will execute `install.js` script of the plugin to do the initialization and added the plugin name to `rekit.plugins` section of package.json.

### Rekit tools

Rekit tools are pure scripts shipped with created applications. They are put in the `tools` folder of your app and are supposed to be edited to meet additional requirements of your project.

##### tools/server.js
This script is used to start dev servers, by default it starts all 3 servers include webpack dev server, Rekit Studio and the build result server. You can only start some of servers by arguments.

Usage:
```
node tools/server.js [-m, --mode] [--readonly]
```

- `mode`: if not provided, all 3 dev servers are started. Otherwise only the specified dev server is started. It could be:
- `dev`: webpack dev server
- `studio`: Rekit Studio
- `build`: start a static express server for build folder.
- `readonly`: start the Rekit Studio on readonly mode. It's useful to start a studio server only for explore the project structure. For example, the Rekit Studio [live demo](http://demo.rekit.org) is running on readonly mode.

It's also available as the npm script: `npm start`.

##### tools/run_test.js
This script is helpful to run one or multiple unit tests. It accepts argument what tests files should be run.

Usage:
```
node tools/run_test.js <file-pattern>
```

The file pattern is the same as what `mocha` accepts. If no `file-pattern` specified, it runs all tests and generates test coverage report. Otherwise run tests matches the pattern.

For example:
```
node tools/run_test.js features/home/redux/counterPlusOne.test.js // run test of a redux action
node tools/run_test.js features/home // run all tests of home feature
node tools/run_test.js // run all tests and generate test coverage report
```

It's also available as the npm script: `npm test`.

#### tools/build.js
This script is used to build the project.

Usage:
```
node tools/build.js
```

It's also available as the npm script: `npm run build`. It will build the project to the `build` folder.

### Manage features, components and actions.
This is the key part of daily Rekit development. You will use below commands to mange Rekit elements.

Expand Down
4 changes: 1 addition & 3 deletions docs/eslint.md
@@ -1,5 +1,3 @@
## Code Quality Check

Rekit uses ESlint for code quality check. And uses [airbnb javascript guide](https://github.com/airbnb/javascript) as the basic rules for all codes. There are slight changes defined in `.eslintrc` for different parts of a Rekit application.

Because it seems the rules suggested airbnb often change. There may be some eslint errors for a new created Rekit application. You need to either update the code or adding your own rules to clear those errors.
Rekit uses ESlint for code quality check. It's the sames create-react-app.
2 changes: 1 addition & 1 deletion docs/examples.md
@@ -1,6 +1,6 @@
## Examples
Below are real-world apps created with Rekit, you can look at them for reference:

1. [Rekit portal](https://github.com/supnate/rekit-portal): the Rekit dev tool shipped with Rekit 2.0, it's built with Rekit so it's also a good example.
1. [Rekit Studio](https://github.com/supnate/rekit): the Rekit IDE shipped with Rekit 2.2, it's built with Rekit so it's also a good example.
2. [Command pad](https://github.com/supnate/command-pad): a handy GUI tool for managing command line tasks, built with [Electron](http://electron.atom.io) and Rekit 1.0.
3. [Simple forum](https://github.com/supnate/rekit-example): a simple forum application built with Rekit 1.0. It connects to a real backend server powered by [Leancloud.cn](https://leancloud.cn)( a SaaS service).
2 changes: 1 addition & 1 deletion docs/feature-oriented-architecture.md
Expand Up @@ -4,7 +4,7 @@ Feature oriented web application architecture (in React)

Feature is a very nature concept for people to understand a system. It's also used to describe user requirements for software development. But when a feature comes to programmers side it's usually immediately converted to technical artifacts such as components, actions, models etc. This convention adds the difficulty for new comers or developers themselves serval weeks later to understand the system. So if we organize an software project by features rather than technique categories (like components, actions, models) it will help us always manage the project under control when the project grows because we construct the system with bigger units.

This architecture is also the key concept of [Rekit](https://github.com/supnate), a toolkit for building web applications with React, Redux and React router.)
This architecture is also the key concept of [Rekit](https://github.com/supnate/rekit), a toolkit for building web applications with React, Redux and React router.)

Unlike backend system, frontend web application is the direct interface for user to understand the capabilities of an application. So it's more suitable to be organized by features.

Expand Down
26 changes: 10 additions & 16 deletions docs/get-started.md
Expand Up @@ -19,22 +19,17 @@ $ npm install
$ npm start
```

### See the welcome page
### See the examples
The app should be started in a few seconds, then you can access it at: http://localhost:6075.

If everything is ok, you should be able to see the welcome page:
When a Rekit app is created, there will be an examples feature in it. You can see it at: http://localhost:6075/examples:

<img src="/images/welcome-page.png" width="700" alt="Rekit Welcome Page"/>
The examples feature has two examples:

The welcome page consists of 3 parts:

**1. A simple nav component**
It reads the route config of the whole application and generates links to different pages.

**2. A counter demo using sync actions.**
**1. A counter demo using sync actions.**
By the sample you can quickly see how component, actions and reducers work together.

**3. A demo to fetch latest topics of `reactjs` channel from Reddit**
**2. A demo to fetch latest topics of `reactjs` channel from Reddit**
This is just the same example from the official Redux site: [https://redux.js.org/docs/advanced/ExampleRedditAPI.html](https://redux.js.org/docs/advanced/ExampleRedditAPI.html). It demonstrates the [async actions](/docs/concepts#async-action) for a Redux application. But the Rekit version uses [one action one file pattern](/docs/one-action-one-file.md), and it adds error handling which is a common requirement for real-world apps.

### Using Rekit Studio
Expand All @@ -47,16 +42,15 @@ See a full introduction at: https://medium.com/@nate_wang/introducing-rekit-stud
### Where to start
Rekit creates a single page application by default. You may need to edit the root container first to define your own container layout. The source file is at `src/features/home/App.js`.

### Two quick tutorial videos
### See the quick tutorial videos
There are two samples on the welcome page, and they are also demos on Redux's official web site. Now let's see how to create them with Rekit.

1. [Create a counter with Rekit in 1 minute!](https://youtu.be/HT6YzZtbPKc)

<img src="/images/youtube.png" width="400" alt="Demo video" />
[<img src="/images/rekit-studio-youtube.png" width="500" alt="Rekit Demo"/>](https://youtu.be/i53XffYtWMc "Rekit Demo")

2. [Create a Reddit list viewer step by step (5 minutes).](https://youtu.be/edq5lWsxZMg)
The demo contains two parts, which are examples in Redux's official website:

<img src="/images/youtube.png" width="400" alt="Demo video" />
1. Create a simple counter in 1 minute!
2. Show the latest reactjs topics on Reddit using async actions.

### That's it!
You have already created your very first Rekit app and tried powerful Rekit tools! Now you can read more details about Rekit in the following pages.
67 changes: 2 additions & 65 deletions docs/testing.md
@@ -1,68 +1,5 @@
## Testing

Testing a React + Redux application is difficult, you need to know many libs/tools regarding React testing and learn their usage. But Rekit will setup everything for you. You just need to write test code in the auto generated test files, running test with Rekit Studio and reading the coverage report in a browser.
From version 2.3.0, Rekit starts to use jest for unit test since the boilerplate is created by create-react-app. You can see more introduction at: https://github.com/facebook/create-react-app/blob/master/packages/react-scripts/template/README.md#running-tests .

However here is the process of how React testing works. You can know how Rekit setups the testing process.

1. [Istanbul](https://github.com/gotwarlost/istanbul) instruments the source code for test coverage report. Istanbul itself doesn't support JSX, but there's a babel plugin [babel-plugin-istanbul](https://github.com/istanbuljs/babel-plugin-istanbul) then it works.
2. Webpack builds all testing files with [mocha-webpack](https://github.com/zinserjan/mocha-webpack) which auto finds test files to test.
3. [Mocha](https://github.com/mochajs/mocha) runs the built version of testing files.
4. [nyc](https://github.com/istanbuljs/nyc) generates the test coverage report.

All app testing files are saved in the folder `test/app`. And the folder structure is the same with the source code folder structure in `src` folder.

#### How Rekit generates testing files
When creating a new component or action, Rekit auto creates test cases for them. Even you don't add any code to to the generated test cases, they help you avoid simple errors. Such as:

1. It ensures a component is always rendered successfully by checking the existence of the root DOM node with correct css class.
2. It ensures reducer is immutable by checking equality of the previous and new states.

For example, when creating a new page, it generates below test case:
```javascript
it('renders node with correct class name', () => {
const pageProps = {
home: {},
actions: {},
};
const renderedComponent = shallow(
<TestPage1 {...pageProps} />
);

expect(
renderedComponent.find('.home-test-page-1').node
).to.exist;
});
```

When creating an action, it generates below reducer test case:
```javascript
it('reducer should handle MY_ACTION', () => {
const prevState = {};
const state = reducer(
prevState,
{ type: MY_ACTION }
);
expect(state).to.not.equal(prevState); // should be immutable
expect(state).to.deep.equal(prevState); // TODO: replace this line with real case.
});
```

#### Run tests
As you may have noticed, test cases also need to be built with webpack, then Mocha could run the test cases. So running a single test case file also needs the build. So `tools/run_test.js` is created to simplify this process. You can run any test case file just by the `run_test.js` tool. It's also exported as `npm test`. All arguments to it is just passed to the `run_test.js` script. The usage is as below:
```
npm test // run all tests of the project
npm test features/home // run tests under the `home` feature
npm test **/List.test.js // run all tests named list.test.js under app folder
```

The script is under your project, so you can edit it for free to meet your own requirements.

By default it does below things:

1. Istanbul instruments the source code.
2. Mocha runs the test cases.
3. nyc generates the test coverage report.


#### See the coverage report
If tests are are run for the whole project then test coverage report will be generated at `coverage` folder.
The only difference is Rekit save all test files under the folder `/tests` rather than along side with source files under `/src` folder.
12 changes: 1 addition & 11 deletions docs/webpack.md
@@ -1,15 +1,5 @@
## Bundling

Webpack is also considered one of the most difficult parts for building a React application. Luckily again Rekit setups everything for you. There are 2 webpack config files corresponding to different usage:

* `webpack.config.js`: it's a webpack config factory for dev, dll and dist bundling.
* `webpack.test.config.js`: the config for test build.

#### Boost the build performance by using webpack-dll-plugin
When a React application grows large, the build time in dev time takes long time. The `webpack-dll-plugin` could resolve the problem. There's very few docs about it but there's a great article introducing it: http://engineering.invisionapp.com/post/optimizing-webpack/ . Rekit takes use the approach mentioned in the article.

The basic idea is to build common libs such as React, Redux, React-router into a separate dll bundle. So that they don't need to be built every time your code is changed. By doing this the build time could be significantly reduced.

Rekit integrates the process in `tools/server.js` which is run when calling `npm start`. The script checks versions of all packages needed for the dll build. So that it auto builds a new dll when any dependency version is changed.
It's the same as create-react-app, see more info at: https://github.com/facebook/create-react-app/blob/master/packages/react-scripts/template/README.md#deployment .


3 changes: 3 additions & 0 deletions package.json
Expand Up @@ -16,5 +16,8 @@
"gitbook-plugin-edit-link": "^2.0.2",
"gitbook-plugin-github": "^2.0.0",
"gitbook-plugin-prism": "^2.3.0"
},
"dependencies": {
"gitbook-plugin-anchorjs": "^2.0.0"
}
}

0 comments on commit 0c3fdb0

Please sign in to comment.