From 0c3fdb0d76c25dde50a9ba073c566e93977ee76c Mon Sep 17 00:00:00 2001 From: Nate Wang Date: Mon, 26 Mar 2018 23:20:09 +0800 Subject: [PATCH] Update docs. --- README.md | 6 ++- docs/app.md | 4 +- docs/cli.md | 49 -------------------- docs/eslint.md | 4 +- docs/examples.md | 2 +- docs/feature-oriented-architecture.md | 2 +- docs/get-started.md | 26 ++++------- docs/testing.md | 67 +-------------------------- docs/webpack.md | 12 +---- package.json | 3 ++ 10 files changed, 25 insertions(+), 150 deletions(-) diff --git a/README.md b/README.md index 4c3fbde5..d408930d 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,10 @@ # -> 🎉🎉🎉 [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. diff --git a/docs/app.md b/docs/app.md index fb0b8a45..b47487f9 100644 --- a/docs/app.md +++ b/docs/app.md @@ -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 |-- ... ``` diff --git a/docs/cli.md b/docs/cli.md index 4eb6225a..5d20f281 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -27,55 +27,6 @@ rekit install 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 -``` - -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. diff --git a/docs/eslint.md b/docs/eslint.md index f6457981..deac001e 100644 --- a/docs/eslint.md +++ b/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. diff --git a/docs/examples.md b/docs/examples.md index de89280a..1321c7dc 100644 --- a/docs/examples.md +++ b/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). diff --git a/docs/feature-oriented-architecture.md b/docs/feature-oriented-architecture.md index 522ea590..ea3ae398 100644 --- a/docs/feature-oriented-architecture.md +++ b/docs/feature-oriented-architecture.md @@ -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. diff --git a/docs/get-started.md b/docs/get-started.md index c942a58b..26141606 100644 --- a/docs/get-started.md +++ b/docs/get-started.md @@ -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: -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 @@ -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) - -Demo video +[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: -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. diff --git a/docs/testing.md b/docs/testing.md index 29242236..85240a14 100644 --- a/docs/testing.md +++ b/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( - - ); - - 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. diff --git a/docs/webpack.md b/docs/webpack.md index 9bbf1ba2..c498b0a0 100644 --- a/docs/webpack.md +++ b/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 . diff --git a/package.json b/package.json index 5fa1d782..1ceecf49 100644 --- a/package.json +++ b/package.json @@ -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" } }