Skip to content

Commit 2b76b72

Browse files
piotrwitekpiotrwitek
committed
updated readme
1 parent ce9b083 commit 2b76b72

File tree

1 file changed

+58
-34
lines changed

1 file changed

+58
-34
lines changed

‎README.md‎

Lines changed: 58 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -5,41 +5,55 @@
55
66
### Demo: http://piotrwitek.github.io/react-redux-typescript-starter-kit/
77

8-
### Features
9-
- CLEAN - minimal dependencies, no clutter!
10-
- NO-SETUP - working out-of-the-box (more in [Usage](#usage) section...)
11-
- RELIABLE-HOT-RELOAD - dev server with hot-reload using [jspm-hmr](https://www.npmjs.com/package/jspm-hmr) - highly reliable and scalable with increasing modules count (more in [Notes](#notes) section...)
12-
- TYPESCRIPT-WORKFLOW - in browser (on-the-fly) loading / no transpilation step / no bundling step
13-
- BEST-INTELLISENSE - statically typed entire JavaScript and DOM API with autocompletion and docs right in your editor - no more silly typos and runtime exceptions
14-
- TYPESAFE-API-CALLS - type checking the contracts of REST Service API calls - forget checking for API docs again
15-
- REACT-BEST-PRACTICES - no mixins / no ref strings / no method binding - instead ES Class Fields / no function/objects creation in render methods / render lists in dedicated components / don't use array index as key / ES6 style PureRenderMixin with PureComponent
8+
Table of Contents
9+
1. [Innovations](#innovations)
10+
2. [Features](#features)
11+
3. [Roadmap](#roadmap)
12+
4. [JSPM integration](#jspm--systemjs--rollup)
13+
5. [Pros & Cons](#pros--cons)
14+
6. [Project Structure](#project-structure)
15+
7. [Installation](#installation)
16+
8. [Usage](#usage)
17+
9. [CLI Commands](#cli-commands)
18+
19+
20+
## Innovations
21+
- __TYPESCRIPT RAPID SPEED WORKFLOW WITH INCREMENTAL TYPE-CHECKING - loading TS files in browser (on-the-fly) -> no JS emit, it's OK to use only TS files, also for unit testing, it means no transpilation step & no bundling step during development__ _(bundling step is only necessary to create app & vendor bundle for production)_
22+
- RELIABLE-HOT-RELOAD - dev server with hot-reload using [jspm-hmr](https://www.npmjs.com/package/jspm-hmr) - highly reliable and scalable for speed with increasing modules count (more in [Pros & Cons](#pros--cons)...)
23+
- TYPESCRIPT-TESTING - complete testing solution with Tape (blue-tape) - write and run tests only in TS - no transpilation required!
24+
- NO-IDE-NO-PROBLEM - you can use Notepad, just run `tsc --watch` in command line for fast incremental type-checking or `tsc` for project-wide type-check, there is no emit so it never breaks reliable hot-reload :)
25+
26+
## Features
27+
- PRODUCTION-WORKFLOW - npm scripts for production bundling & deployment, github-hooks, linter, test runner etc.
28+
- TYPESAFE-API-CALLS - type checking contracts of REST API calls - forget constantly checking for API docs and let your IDE guide you
29+
- GREAT-TOOLING - type cheking for JavaScript and DOM API with autocompletion and docs right in your editor - no more silly typos and runtime exceptions
1630
- REACT-ROUTER - included `react-router-redux` to store your routing in state for Time-Travel capabilities
1731
- REDUX-DEV-TOOLS - installed Redux DevTools capabilities with [chrome-extension](https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd)
1832
- IMMUTABLE-STORE - using `seamless-immutable` for simplicity and backwards-compatibility with vanilla JS (no hassle with `toJS()`, `get()`, `getIn()` in your containers and components)
19-
- PRODUCTION-READY - npm scripts for bundling & deploy, github-hooks, linter, test runner etc.
20-
- EASY-TESTING - complete testing solution with Tape (blue-tape), Enzyme, JSDOM - functional approach makes it easy to test, you can even write and run test entirely in TypeScript - no transpilation step!
2133
- CSS-MODULES - simplest and reliable approach for local CSS styles using csjs - https://github.com/rtsao/csjs#faq
2234
- BEM & ITCSS - using BEM with Inverted Triangle conventions to give meaning and context to CSS classes
2335

24-
---
36+
#### React Best Practices & Optimizations
37+
- no mixins -> use ES6 style PureRenderMixin with PureComponent
38+
- no ref strings -> use ref callbacks
39+
- no method binding -> use ES Class Fields
40+
- no new function/objects creation in render methods -> declare them in outer scope and use a reference
41+
- render big collections in separate dedicated components -> omit re-renders invoked by other prop changes
42+
- don't use array index as key property -> use item unique id property to eliminate bugs
2543

26-
### Code Examples
27-
- React and Redux with TypeScript - production ready code samples
44+
#### React Patterns
2845
- Flux Standard Actions for Redux - https://github.com/acdlite/redux-actions
2946
- Redux Reducer Modules - https://github.com/erikras/ducks-modular-redux
3047

31-
### Testing Examples
32-
- Testing Redux Action Creators
33-
- Testing Redux Async Actions
34-
3548
---
3649

3750
## Roadmap
3851
- Redux async flow with redux-saga - https://github.com/yelouafi/redux-saga/
39-
- REDUX-INNOVATIVE-APPROACH - using TS 2.0 "Tagged Union Types" - for solid Redux integration
52+
- Testing async flow in redux sagas
53+
- REDUX INNOVATION - using TS 2.0 "Tagged Union Types" - for solid Redux integration
4054
(https://blogs.msdn.microsoft.com/typescript/2016/08/30/announcing-typescript-2-0-rc)
41-
4255
- CSS Modules using csjs - https://github.com/rtsao/csjs#faq
56+
- Reactive Programming with RxJS
4357
- Testing with Enzyme (JSDOM)
4458
- Testing Component markup (shallowRender)
4559
- Testing Component behaviour/interactions (renderIntoDocument, Simulate)
@@ -68,6 +82,23 @@ Check yourself using this easy test procedure:
6882

6983
---
7084

85+
## Pros / Cons
86+
87+
- If you are using TypeScript compiler built-in in the editor/IDE you can experience some quirks and limitations. You should always use a local npm TypeScript installation. For the best IDE experience I suggest to use Atom Editor with atom-typescript plugin (include single file compilation feature) or any other Editor with `npm run tsc:watch` starter-kit CLI Command for fast incremental type-checking.
88+
89+
- You should never emit intermediate JS files during development workflow, because you'll lose Hot-Reload capability (new files emitted after each change) and experience much slower workflow without any advantages.
90+
91+
- I've seen most boilerplates adding Babel transpilation into their dev workflow with TypeScript, which introduces additional and unnecessary costly full build step, my solution only adds async/generators transform (not a full transpilation) only when generating app bundle for production (not in development workflow so it stays fast)
92+
__It's worth to know that Babel is similarly using regenerator internally for async/generators transform https://babeljs.io/docs/usage/caveats/__
93+
94+
- Comparing to Webpack Hot Module Reload: SystemJS hot-reloading works differently from Webpack HMR, it loads module files separately so there is no need for bundling step. Then it deletes the module from module registry and re-imports it with the modules that depend on it ensuring to always load latest changes.
95+
Because of this approach it is highly scalable with increasing modules count in your project and is more reliable in contrary to Webpack/React-Hot-Reloader - __Webpack is breaking it's HMR flow occasionally thus requiring you to do a full page reload__.
96+
97+
- Ttemporarily using regenerator transform to transpile async/generators to ES5 only in production build step (it's necessary for compatibility with older browsers without generators support, you can opt-out if not necessary)
98+
__Soon with release of TypeScript 2.1 proper transpilation will be provided eliminating this step__
99+
100+
---
101+
71102
## Project Structure
72103

73104
```
@@ -96,19 +127,6 @@ Check yourself using this easy test procedure:
96127

97128
---
98129

99-
## Notes
100-
101-
- I'm temporarily using regenerator transform to transpile async/generators to ES5 only in production build step (it's necessary for compatibility with older browsers, you can opt-out if not necessary)
102-
__I'll get rid of this clunky step soon enough with release of TypeScript 2.1 which will natively support it__
103-
104-
- I've seen most boilerplates adding Babel transpilation into their dev workflow with TypeScript, which introduces additional and unnecessary costly full build step, my solution only adds async/generators transform (not a full transpilation) only when generating app bundle for production (not in development workflow so it stays fast)
105-
__It's worth to know that Babel is similarly using regenerator internally for async/generators transform https://babeljs.io/docs/usage/caveats/__
106-
107-
- Comparing to Webpack Hot Module Reload: SystemJS hot-reloading works differently from Webpack HMR, it loads module files separately so there is no need for bundling step. Then it deletes the module from module registry and re-imports it with the modules that depend on it ensuring to always load latest changes.
108-
Because of this approach it is highly scalable with increasing modules count in your project and is more reliable in contrary to Webpack/React-Hot-Reloader - __Webpack is breaking it's HMR flow occasionally thus requiring you to do a full page reload__.
109-
110-
---
111-
112130
## Installation
113131

114132
#### Prerequisites
@@ -133,6 +151,8 @@ Because of this approach it is highly scalable with increasing modules count in
133151
1. `npm run bundle-dev` - bundle vendor packages for development _(re-run only when app dependencies has changed)_
134152
2. `npm start` - browser will open automatically
135153

154+
No IDE Option: `npm run tsc:watch` - if you don't use IDE with typescript integration, run tsc in watch mode for fast incremental type-checking (NOTE: this will not emit any JS files, only type-checking - it's OK because you load ts file on-the-fly)
155+
136156
#### Build for Production Workflow
137157
1. `npm run build` - create app.js & vendor.js bundles in 'dist' folder
138158
- `npm run build:app` - build only app.js bundle _(run when app source code has changed)_
@@ -141,11 +161,15 @@ Because of this approach it is highly scalable with increasing modules count in
141161

142162
---
143163

144-
## All Npm Commands & Scripts
164+
## CLI Commands
165+
166+
#### Development
145167

146168
`npm start` - start local dev server with hot-reload [jspm-hmr](https://www.npmjs.com/package/jspm-hmr)
147169

148-
#### Development Bundling
170+
`npm run tsc` - run project-wide type-checking with TypeScript CLI (`/src` folder)
171+
172+
`npm run tsc:watch` - start TypeScript CLI in watch mode for fast incremental type-checking (`/src` folder)
149173

150174
`npm run bundle-dev` - build vendor packages in single file bundle for quick full-page reload __(app sources remain as seperate modules for on-the-fly HMR & transpilation)__
151175

0 commit comments

Comments
 (0)