constelementOnly:React.ReactElement=<div/>||<MyComponent/>;

React.ReactNode

constelementOrPrimitive:React.ReactNode='string'||0||false||null||undefined||<div/>||<MyComponent/>;constComponent=({children:React.ReactNode})=> ...

React.CSSProperties

conststyles:React.CSSProperties={flexDirection:'row', ...constelement=<divstyle={styles}...

React.ReactEventHandler<E>

consthandleChange:React.ReactEventHandler<HTMLInputElement>=(ev)=>{ ...}<inputonChange={handleChange}.../>

React.MouseEvent<E> |React.KeyboardEvent<E> |React.TouchEvent<E> etc...

consthandleChange=(ev:React.MouseEvent<HTMLDivElement>)=>{ ...}<divonMouseMove={handleChange}.../>

Component Typing Patterns

Stateless Components - SFC

- stateless counter

import*asReactfrom'react';exportinterfaceSFCCounterProps{label:string;count:number;onIncrement:()=>any;}exportconstSFCCounter:React.SFC<SFCCounterProps>=(props)=>{const{ label, count, onIncrement}=props;consthandleIncrement=()=>{onIncrement();};return(<div><span>{label}:{count}</span><buttontype="button"onClick={handleIncrement}>{`Increment`}</button></div>);};

- spread attributeslink

import*asReactfrom'react';exportinterfaceSFCSpreadAttributesProps{className?:string;style?:React.CSSProperties;}exportconstSFCSpreadAttributes:React.SFC<SFCSpreadAttributesProps>=(props)=>{const{ children, ...restProps}=props;return(<div{...restProps}>{children}</div>);};

Stateful Components - Class

- stateful counter

import*asReactfrom'react';exportinterfaceStatefulCounterProps{label:string;}typeState={count:number;};exportclassStatefulCounterextendsReact.Component<StatefulCounterProps,State>{state:State={count:0,};handleIncrement=()=>{this.setState({count:this.state.count+1});}render(){const{ handleIncrement}=this;const{ label}=this.props;const{ count}=this.state;return(<div><span>{label}:{count}</span><buttontype="button"onClick={handleIncrement}>{`Increment`}</button></div>);}}

- with default props

import*asReactfrom'react';exportinterfaceStatefulCounterWithDefaultProps{label:string;initialCount?:number;}interfaceDefaultProps{initialCount:number;}interfaceState{count:number;}exportconstStatefulCounterWithDefault:React.ComponentClass<StatefulCounterWithDefaultProps>=classextendsReact.Component<StatefulCounterWithDefaultProps&DefaultProps>{// to make defaultProps strictly typed we need to explicitly declare their type//@see https://github.com/DefinitelyTyped/DefinitelyTyped/issues/11640staticdefaultProps:DefaultProps={initialCount:0,};state:State={count:this.props.initialCount,};componentWillReceiveProps({ initialCount}:StatefulCounterWithDefaultProps){if(initialCount!=null&&initialCount!==this.props.initialCount){this.setState({count:initialCount});}}handleIncrement=()=>{this.setState({count:this.state.count+1});}render(){const{ handleIncrement}=this;const{ label}=this.props;const{ count}=this.state;return(<div><span>{label}:{count}</span><buttontype="button"onClick={handleIncrement}>{`Increment`}</button></div>);}};

Generic Components

- generic list

import*asReactfrom'react';exportinterfaceGenericListProps<T>{items:T[];itemRenderer:(item:T)=>JSX.Element;}exportclassGenericList<T>extendsReact.Component<GenericListProps<T>,{}>{render(){const{ items, itemRenderer}=this.props;return(<div>{items.map(itemRenderer)}</div>);}}

Render Props

- name provider

import*asReactfrom'react';interfaceNameProviderProps{children:(state:NameProviderState)=>React.ReactNode;}interfaceNameProviderState{name:string;}exportclassNameProviderextendsReact.Component<NameProviderProps,NameProviderState>{state={name:'Piotr',};render(){returnthis.props.children(this.state);}}

- mouse provider

import*asReactfrom'react';exportinterfaceMouseProviderProps{render:(state:MouseProviderState)=>React.ReactNode;}interfaceMouseProviderState{x:number;y:number;}exportclassMouseProviderextendsReact.Component<MouseProviderProps,MouseProviderState>{state={x:0,y:0};handleMouseMove=(event:React.MouseEvent<HTMLDivElement>)=>{this.setState({x:event.clientX,y:event.clientY,});}render(){return(<divstyle={{height:'100%'}}onMouseMove={this.handleMouseMove}>{/*          Instead of providing a static representation of what <Mouse> renders,          use the `render` prop to dynamically determine what to render.        */}{this.props.render(this.state)}</div>);}}

Higher-Order Components

- withState

import*asReactfrom'react';import{Subtract}from'utility-types';// These props will be subtracted from original component typeinterfaceWrappedComponentProps{count:number;onIncrement:()=>any;}exportconstwithState=<PextendsWrappedComponentProps>(WrappedComponent:React.ComponentType<P>)=>{// These props will be added to original component typeinterfaceProps{initialCount?:number;}interfaceState{count:number;}returnclassWithStateextendsReact.Component<Subtract<P,WrappedComponentProps>&Props,State>{// Enhance component name for debugging and React-Dev-ToolsstaticdisplayName=`withState(${WrappedComponent.name})`;state:State={count:Number(this.props.initialCount)||0,};handleIncrement=()=>{this.setState({count:this.state.count+1});}render(){const{ ...remainingProps}=this.props;const{ count}=this.state;return(<WrappedComponent{...remainingProps}count={count}onIncrement={this.handleIncrement}/>);}};};

- withErrorBoundary

import*asReactfrom'react';import{Subtract}from'utility-types';constMISSING_ERROR='Error was swallowed during propagation.';interfaceWrappedComponentProps{onReset?:()=>any;}exportconstwithErrorBoundary=<PextendsWrappedComponentProps>(WrappedComponent:React.ComponentType<P>)=>{interfaceProps{}interfaceState{error:Error|null|undefined;}returnclassWithErrorBoundaryextendsReact.Component<Subtract<P,WrappedComponentProps>&Props,State>{staticdisplayName=`withErrorBoundary(${WrappedComponent.name})`;state:State={error:undefined,};componentDidCatch(error:Error|null,info:object){this.setState({error:error||newError(MISSING_ERROR)});this.logErrorToCloud(error,info);}logErrorToCloud=(error:Error|null,info:object)=>{// TODO: send error report to cloud}handleReset=()=>{this.setState({error:undefined});}render(){const{ children, ...remainingProps}=this.props;const{ error}=this.state;if(error){return(<WrappedComponent{...remainingProps}onReset={this.handleReset}/>);}returnchildren;}};};

Redux Connected Components

Caveat withbindActionCreators

const mapDispatchToProps = (dispatch: Dispatch) => ({  onIncrement: () => dispatch(actions.increment()),});

- redux connected counter

import{connect}from'react-redux';import{RootState}from'@src/redux';import{countersActions,countersSelectors}from'@src/redux/counters';import{SFCCounter}from'@src/components';constmapStateToProps=(state:RootState)=>({count:countersSelectors.getReduxCounter(state),});exportconstSFCCounterConnected=connect(mapStateToProps,{onIncrement:countersActions.increment,})(SFCCounter);

- redux connected counter (verbose)

import{bindActionCreators}from'redux';import{connect}from'react-redux';import{RootState,Dispatch}from'@src/redux';import{countersActions}from'@src/redux/counters';import{SFCCounter}from'@src/components';constmapStateToProps=(state:RootState)=>({count:state.counters.reduxCounter,});constmapDispatchToProps=(dispatch:Dispatch)=>bindActionCreators({onIncrement:countersActions.increment,},dispatch);exportconstSFCCounterConnectedVerbose=connect(mapStateToProps,mapDispatchToProps)(SFCCounter);

- with own props

import{connect}from'react-redux';import{RootState}from'@src/redux';import{countersActions,countersSelectors}from'@src/redux/counters';import{SFCCounter}from'@src/components';exportinterfaceSFCCounterConnectedExtended{initialCount:number;}constmapStateToProps=(state:RootState,ownProps:SFCCounterConnectedExtended)=>({count:countersSelectors.getReduxCounter(state)+ownProps.initialCount,});exportconstSFCCounterConnectedExtended=connect(mapStateToProps,{onIncrement:countersActions.increment,})(SFCCounter);

Redux

Action Creators

import{createAction}from'typesafe-actions';exportconstcountersActions={increment:createAction('INCREMENT'),add:createAction('ADD',(amount:number)=>({type:'ADD',payload:amount,})),};

Reducers

State with Type-level Immutability

exporttypeState={readonlycounter:number,};

exportconstinitialState:State={counter:0,};// OKinitialState.counter=3;// Error, cannot be mutated

Caveat: Readonly does not provide a recursive immutability on objects

exporttypeState={readonlycontainerObject:{readonlyimmutableProp:number,mutableProp:number,}};state.containerObject={mutableProp:1};// Error, cannot be mutatedstate.containerObject.immutableProp=1;// Error, cannot be mutatedstate.containerObject.mutableProp=1;// OK! No error, can be mutated

Best-practices for nested immutability

exporttypeState=Readonly<{counterPairs:ReadonlyArray<Readonly<{immutableCounter1:number,immutableCounter2:number,}>>,}>;state.counterPairs[0]={immutableCounter1:1,immutableCounter2:1};// Error, cannot be mutatedstate.counterPairs[0].immutableCounter1=1;// Error, cannot be mutatedstate.counterPairs[0].immutableCounter2=1;// Error, cannot be mutated

Typing reducer

import{combineReducers}from'redux';import{getType}from'typesafe-actions';import{ITodo,ITodosFilter}from'./types';import{addTodo,toggleTodo,changeFilter}from'./actions';exporttypeTodosState={readonlyisFetching:boolean;readonlyerrorMessage:string|null;readonlytodos:ITodo[];readonlytodosFilter:ITodosFilter;};exporttypeRootState={todos:TodosState;};exportconsttodosReducer=combineReducers<TodosState,TodosAction>({isFetching:(state=false,action)=>{switch(action.type){default:returnstate;}},errorMessage:(state='',action)=>{switch(action.type){default:returnstate;}},todos:(state=[],action)=>{switch(action.type){casegetType(addTodo):return[...state,action.payload];casegetType(toggleTodo):returnstate.map((item)=>item.id===action.payload          ?{ ...item,completed:!item.completed}          :item);default:returnstate;}},todosFilter:(state='',action)=>{switch(action.type){casegetType(changeFilter):returnaction.payload;default:returnstate;}},});// inferring union type of actionsimport{$call}from'utility-types';import*asactionsfrom'./actions';constreturnsOfActions=Object.values(actions).map($call);exporttypeTodosAction=typeofreturnsOfActions[number];

Testing reducer

import{todosReducer,TodosState,TodosAction}from'./reducer';import{addTodo,changeFilter,toggleTodo}from'./actions';/** * FIXTURES */constactiveTodo={id:'1',completed:false,title:'active todo'};constcompletedTodo={id:'2',completed:true,title:'completed todo'};constinitialState=todosReducer(undefined,{});/** * SCENARIOS */describe('Todos Logic',()=>{describe('initial state',()=>{it('should match a snapshot',()=>{expect(initialState).toMatchSnapshot();});});describe('adding todos',()=>{it('should add a new todo as the first active element',()=>{constaction=addTodo('new todo');conststate=todosReducer(initialState,action);expect(state.todos).toHaveLength(1);expect(state.todos[0].id).toEqual(action.payload.id);});});describe('toggling completion state',()=>{it('should mark as complete todo with id "1"',()=>{constaction=toggleTodo(activeTodo.id);conststate0={ ...initialState,todos:[activeTodo]};expect(state0.todos[0].completed).toBeFalsy();conststate1=todosReducer(state0,action);expect(state1.todos[0].completed).toBeTruthy();});});});

Store Configuration

Create Root State and Root Action Types

RootState - interface representing redux state tree

import{combineReducers}from'redux';import{routerReducer,RouterState}from'react-router-redux';import{countersReducer,CountersState}from'@src/redux/counters';import{todosReducer,TodosState}from'@src/redux/todos';interfaceStoreEnhancerState{}exportinterfaceRootStateextendsStoreEnhancerState{router:RouterState;counters:CountersState;todos:TodosState;}import{RootAction}from'@src/redux';exportconstrootReducer=combineReducers<RootState,RootAction>({router:routerReducer,counters:countersReducer,todos:todosReducer,});

RootAction - union type of all action objects

// RootActionsimport{RouterAction,LocationChangeAction}from'react-router-redux';import{$call}from'utility-types';import{countersActions}from'@src/redux/counters';import{todosActions}from'@src/redux/todos';import{toastsActions}from'@src/redux/toasts';constreturnsOfActions=[  ...Object.values(countersActions),  ...Object.values(todosActions),  ...Object.values(toastsActions),].map($call);typeAppAction=typeofreturnsOfActions[number];typeReactRouterAction=RouterAction|LocationChangeAction;exporttypeRootAction=|AppAction|ReactRouterAction;

Create Store

import{createStore,applyMiddleware,compose}from'redux';import{createEpicMiddleware}from'redux-observable';import{rootReducer,rootEpic,RootState}from'@src/redux';constcomposeEnhancers=(process.env.NODE_ENV==='development'&&window&&window.__REDUX_DEVTOOLS_EXTENSION_COMPOSE__)||compose;functionconfigureStore(initialState?:RootState){// configure middlewaresconstmiddlewares=[createEpicMiddleware(rootEpic),];// compose enhancersconstenhancer=composeEnhancers(applyMiddleware(...middlewares));// create storereturncreateStore(rootReducer,initialState!,enhancer);}// pass an optional param to rehydrate state on app startconststore=configureStore();// export store singleton instanceexportdefaultstore;

Async Flow

"redux-observable"

import{combineEpics,Epic}from'redux-observable';import{isActionOf}from'typesafe-actions';import{Observable}from'rxjs/Observable';importcuidfrom'cuid';import{RootAction,RootState}from'@src/redux';import{todosActions}from'@src/redux/todos';import{toastsActions}from'./';constTOAST_LIFETIME=2000;constaddTodoToast:Epic<RootAction,RootState>=(action$,store)=>action$.filter(isActionOf(todosActions.addTodo)).concatMap((action)=>{// action is type: { type: "ADD_TODO"; payload: string; }consttoast={id:cuid(),text:action.payload.title};constaddToast$=Observable.of(toastsActions.addToast(toast));constremoveToast$=Observable.of(toastsActions.removeToast(toast.id)).delay(TOAST_LIFETIME);returnaddToast$.concat(removeToast$);});exportconstepics=combineEpics(addTodoToast);

Selectors

"reselect"

import{createSelector}from'reselect';import{RootState}from'@src/redux';exportconstgetTodos=(state:RootState)=>state.todos.todos;exportconstgetTodosFilter=(state:RootState)=>state.todos.todosFilter;exportconstgetFilteredTodos=createSelector(getTodos,getTodosFilter,(todos,todosFilter)=>{switch(todosFilter){case'completed':returntodos.filter((t)=>t.completed);case'active':returntodos.filter((t)=>!t.completed);default:returntodos;}},);

Action Creators - Alternative Pattern

exportconstINCREMENT='INCREMENT';exportconstADD='ADD';exporttypeActions={INCREMENT:{type:typeofINCREMENT,},ADD:{type:typeofADD,payload:number,},};exporttypeRootAction=Actions[keyofActions];exportconstactions={increment:():Actions[typeofINCREMENT]=>({type:INCREMENT,}),add:(amount:number):Actions[typeofADD]=>({type:ADD,payload:amount,}),};

Tools

TSLint

tslint.json

{"extends":["tslint:recommended","tslint-react"],"rules":{"arrow-parens":false,"arrow-return-shorthand":[false],"comment-format":[true,"check-space"],"import-blacklist":[true,"rxjs"],"interface-over-type-literal":false,"interface-name":false,"max-line-length":[true,120],"member-access":false,"member-ordering":[true,{"order":"fields-first"}],"newline-before-return":false,"no-any":false,"no-empty-interface":false,"no-import-side-effect":[true],"no-inferrable-types":[true,"ignore-params","ignore-properties"],"no-invalid-this":[true,"check-function-in-method"],"no-null-keyword":false,"no-require-imports":false,"no-submodule-imports":[true,"@src","rxjs"],"no-this-assignment":[true,{"allow-destructuring":true}],"no-trailing-whitespace":true,"no-unused-variable":[true,"react"],"object-literal-sort-keys":false,"object-literal-shorthand":false,"one-variable-per-declaration":[false],"only-arrow-functions":[true,"allow-declarations"],"ordered-imports":[false],"prefer-method-signature":false,"prefer-template":[true,"allow-single-concat"],"quotemark":[true,"single","jsx-double"],"semicolon":[true,"always"],"trailing-comma":[true,{"singleline":"never","multiline":{"objects":"always","arrays":"always","functions":"never","typeLiterals":"ignore"},"esSpecCompliant":true}],"triple-equals":[true,"allow-null-check"],"type-literal-delimiter":true,"typedef":[true,"parameter","property-declaration"],"variable-name":[true,"ban-keywords","check-format","allow-pascal-case","allow-leading-underscore"],// tslint-react"jsx-no-lambda":false}}

Jest

jest.config.json

{"verbose":true,"transform": {".(ts|tsx)":"./node_modules/ts-jest/preprocessor.js"  },"testRegex":"(/spec/.*|\\.(test|spec))\\.(ts|tsx|js)$","moduleFileExtensions": ["ts","tsx","js"],"moduleNameMapper": {"^Components/(.*)":"./src/components/$1"  },"globals": {"window": {},"ts-jest": {"tsConfigFile":"./tsconfig.json"    }  },"setupFiles": ["./jest.stubs.js"  ],"setupTestFrameworkScriptFile":"./jest.tests.js"}

jest.stubs.js

// Global/Window object Stubs for Jestwindow.requestAnimationFrame=function(callback){setTimeout(callback);};window.localStorage={getItem:function(){},setItem:function(){},};Object.values=()=>[];

Enzyme

jest.tests.js

import{configure}from'enzyme';importAdapterfrom'enzyme-adapter-react-16';configure({adapter:newAdapter()});

Living Style Guide

"react-styleguidist"

Common Npm Scripts

"lint": "tslint -p ./","tsc": "tsc -p ./ --noEmit","tsc:watch": "tsc -p ./ --noEmit -w","pretest": "npm run lint & npm run tsc","test": "jest --config jest.config.json","test:watch": "jest --config jest.config.json --watch","test:update": "jest --config jest.config.json -u",

Recipes

tsconfig.json

{"compilerOptions":{"baseUrl":"./",// enables absolute path imports"paths":{// define absolute path mappings"@src/*":["src/*"]// will enable -> import { ... } from '@src/components'// in webpack you need to add -> resolve: { alias: { '@src': PATH_TO_SRC }}},"outDir":"dist/",// target for compiled files"allowSyntheticDefaultImports":true,// no errors on commonjs default import"allowJs":true,// include js files"checkJs":true,// typecheck js files"declaration":false,// don't emit declarations"emitDecoratorMetadata":true,"experimentalDecorators":true,"forceConsistentCasingInFileNames":true,"importHelpers":true,// importing helper functions from tslib"noEmitHelpers":true,// disable emitting inline helper functions"jsx":"react",// process JSX"lib":["dom","es2016","es2017.object"],"target":"es5",// "es2015" for ES6+ engines"module":"commonjs",// "es2015" for tree-shaking"moduleResolution":"node","noEmitOnError":true,"noFallthroughCasesInSwitch":true,"noImplicitAny":true,"noImplicitReturns":true,"noImplicitThis":true,"noUnusedLocals":true,"strict":true,"pretty":true,"removeComments":true,"sourceMap":true},"include":["src/**/*"],"exclude":["node_modules","src/**/*.spec.*"]}

Default and Named Module Exports

// 1. in `components/` folder create component file (`select.tsx`) with default export:// components/select.tsxconstSelect:React.SFC<Props>=(props)=>{...exportdefaultSelect;// 2. in `components/` folder create `index.ts` file handling named imports:// components/index.tsexport{ defaultasSelect}from'./select';...// 3. now you can import your components in both ways, with named export (better encapsulation) or using default export (internal access):// containers/container.tsximport{ Select}from'@src/components';orimportSelectfrom'@src/components/select';...

Vendor Types Augmentation

Augmenting library internal type declarations - using relative import resolution

// added missing autoFocus Prop on Input component in "antd@2.10.0" npm packagedeclare module'../node_modules/antd/lib/input/Input'{exportinterfaceInputProps{autoFocus?:boolean;}}

Augmenting library public type declarations - using node module import resolution

// fixed broken public type declaration in "rxjs@5.4.1" npm packageimport{Operator}from'rxjs/Operator';import{Observable}from'rxjs/Observable';declare module'rxjs/Subject'{interfaceSubject<T>{lift<R>(operator:Operator<T,R>):Observable<R>;}}

To quick-fix missing type declarations for vendor modules you can "assert" a module type withany usingShorthand Ambient Modules

//@src/types/modules.d.tsdeclare module'react-test-renderer';declare module'enzyme';

FAQ

- should I still use React.PropTypes in TS?

- when to useinterface declarations and whentype aliases?

- how to best initialize class instance or static properties?

classStatefulCounterWithInitialCountextendsReact.Component<Props,State>{// default props using Property InitializersstaticdefaultProps:DefaultProps={className:'default-class',initialCount:0,};// initial state using Property Initializersstate:State={count:this.props.initialCount,};  ...}

- how to best declare component handler functions?

classStatefulCounterextendsReact.Component<Props,State>{// handlers using Class Fields with arrow functionshandleIncrement=()=>{this.setState({count:this.state.count+1});};  ...}

Contribution Guide

# run linter in playgroundyarn run lint# run type-checking in playgroundyarn run tsc# re-generate `README.md` from repo rootsh ./generate.sh# ornode ./generator/bin/generate-readme.js

Project Examples

Tutorials