Goals

Complementary Projects

Playground Project

Contributing Guide

Sponsor

Table of Contents

Type Definitions & Complementary Libraries

Type Definitions for React & Redux

npm i -D @types/react @types/react-dom @types/react-redux

Complementary Libraries

React Types Cheatsheet

React.StatelessComponent<P> orReact.SFC<P>

constMyComponent:React.SFC<MyComponentProps>= ...

React.Component<P, S>

classMyComponentextendsReact.Component<MyComponentProps,State>{ ...

React.ComponentType<P>

constwithState=<PextendsWrappedComponentProps>(WrappedComponent:React.ComponentType<P>,)=>{ ...

React.ReactElement<P> orJSX.Element

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;}interfaceState{readonlycount:number;}exportclassStatefulCounterextendsReact.Component<StatefulCounterProps,State>{readonlystate: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{readonlyinitialCount:number;}interfaceState{readonlycount: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,};readonlystate: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{readonlyname:string;}exportclassNameProviderextendsReact.Component<NameProviderProps,NameProviderState>{readonlystate:NameProviderState={name:'Piotr'};render(){returnthis.props.children(this.state);}}

- mouse provider

import*asReactfrom'react';exportinterfaceMouseProviderProps{render:(state:MouseProviderState)=>React.ReactNode;}interfaceMouseProviderState{readonlyx:number;readonlyy:number;}exportclassMouseProviderextendsReact.Component<MouseProviderProps,MouseProviderState>{readonlystate:MouseProviderState={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 typeinterfaceInjectedProps{count:number;onIncrement:()=>any;}exportconstwithState=<WrappedPropsextendsInjectedProps>(WrappedComponent:React.ComponentType<WrappedProps>)=>{// These props will be added to original component typetypeHocProps=Subtract<WrappedProps,InjectedProps>&{// here you can extend hoc propsinitialCount?:number;};typeHocState={readonlycount:number;};returnclassWithStateextendsReact.Component<HocProps,HocState>{// Enhance component name for debugging and React-Dev-ToolsstaticdisplayName=`withState(${WrappedComponent.name})`;// reference to original wrapped componentstaticreadonlyWrappedComponent=WrappedComponent;readonlystate:HocState={count:Number(this.props.initialCount)||0,};handleIncrement=()=>{this.setState({count:this.state.count+1});};render(){const{ ...restProps}=this.propsas{};const{ count}=this.state;return(<WrappedComponent{...restProps}count={count}// injectedonIncrement={this.handleIncrement}// injected/>);}};};

- withErrorBoundary

import*asReactfrom'react';import{Subtract}from'utility-types';constMISSING_ERROR='Error was swallowed during propagation.';interfaceInjectedProps{onReset:()=>any;}exportconstwithErrorBoundary=<WrappedPropsextendsInjectedProps>(WrappedComponent:React.ComponentType<WrappedProps>)=>{typeHocProps=Subtract<WrappedProps,InjectedProps>&{// here you can extend hoc props};typeHocState={readonlyerror:Error|null|undefined;};returnclassWithErrorBoundaryextendsReact.Component<HocProps,HocState>{staticdisplayName=`withErrorBoundary(${WrappedComponent.name})`;readonlystate:HocState={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, ...restProps}=this.propsas{children:React.ReactNode;};const{ error}=this.state;if(error){return(<WrappedComponent{...restProps}onReset={this.handleReset}// injected/>);}returnchildren;}};};

Redux Connected Components

Caveat withbindActionCreators

constmapDispatchToProps=(dispatch:Dispatch<ActionType>)=>({onIncrement:()=>dispatch(actions.increment()),});

- redux connected counter

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

- redux connected counter (verbose)

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

- with own props

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

Redux

Action Creators

You should readThe Mighty Tutorial to learn it all the easy way!

import{action}from'typesafe-actions';import{ADD,INCREMENT}from'./constants';// CLASSIC APIexportconstincrement=()=>action(INCREMENT);exportconstadd=(amount:number)=>action(ADD,amount);// ALTERNATIVE API - allow to use reference to "action-creator" function instead of "type constant"// e.g. case getType(increment): return { ... }// This will allow to completely eliminate need for "constants" in your application, more info here:// https://github.com/piotrwitek/typesafe-actions#behold-the-mighty-tutorial// OPTION 1 (with generics):// import { createStandardAction } from 'typesafe-actions';// export const increment = createStandardAction(INCREMENT)<void>();// export const add = createStandardAction(ADD)<number>();// OPTION 2 (with resolve callback):// import { createAction } from 'typesafe-actions';// export const increment = createAction(INCREMENT);// export const add = createAction(ADD, resolve => {//   return (amount: number) => resolve(amount);// });

Reducers

State with Type-level Immutability

exporttypeState={readonlycounter:number;readonlytodos:ReadonlyArray<string>;};

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

state.todos.push('Learn about tagged union types')// TS Error: Property 'push' does not exist on type 'ReadonlyArray<string>'constnewTodos=state.todos.concat('Learn about tagged union types')// OK

Caveat: Readonly is not recursive

import{DeepReadonly}from'utility-types';exporttypeState=DeepReadonly<{containerObject:{innerValue:number,numbers:number[],}}>;state.containerObject={innerValue:1};// TS Error: cannot be mutatedstate.containerObject.innerValue=1;// TS Error: cannot be mutatedstate.containerObject.numbers.push(1);// TS Error: cannot use mutator methods

Best-practices for nested immutability

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

Typing reducer

import{combineReducers}from'redux';import{ActionType}from'typesafe-actions';import{Todo,TodosFilter}from'./models';import*asactionsfrom'./actions';import{ADD,CHANGE_FILTER,TOGGLE}from'./constants';exporttypeTodosState={readonlytodos:Todo[];readonlytodosFilter:TodosFilter;};exporttypeTodosAction=ActionType<typeofactions>;exportdefaultcombineReducers<TodosState,TodosAction>({todos:(state=[],action)=>{switch(action.type){caseADD:return[...state,action.payload];caseTOGGLE:returnstate.map(item=>item.id===action.payload              ?{ ...item,completed:!item.completed}              :item);default:returnstate;}},todosFilter:(state=TodosFilter.All,action)=>{switch(action.type){caseCHANGE_FILTER:returnaction.payload;default:returnstate;}},});

Testing reducer

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

Store Configuration

Create Global RootState and RootAction Types

RootState - type representing root state-tree

RootAction - type representing union type of all action objects

import{StateType}from'typesafe-actions';import{RouterAction,LocationChangeAction}from'react-router-redux';typeReactRouterAction=RouterAction|LocationChangeAction;import{CountersAction}from'../features/counters';importrootReducerfrom'./root-reducer';declare module'Types'{exporttypeRootState=StateType<typeofrootReducer>;exporttypeRootAction=ReactRouterAction|CountersAction;}

Create Store

import{createStore,applyMiddleware}from'redux';import{createEpicMiddleware}from'redux-observable';import{composeEnhancers}from'./utils';importrootReducerfrom'./root-reducer';importrootEpicfrom'./root-epic';importservicesfrom'../services';exportconstepicMiddleware=createEpicMiddleware(rootEpic,{dependencies:services,});functionconfigureStore(initialState?:object){// configure middlewaresconstmiddlewares=[epicMiddleware];// 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"

For more examples and in-depth explanation you should readThe Mighty Tutorial to learn it all the easy way!

importTypesfrom'Types';import{combineEpics,Epic}from'redux-observable';import{tap,ignoreElements,filter}from'rxjs/operators';import{isOfType}from'typesafe-actions';import{todosConstants,TodosAction}from'../todos';// contrived example!!!constlogAddAction:Epic<TodosAction,Types.RootState,Types.Services>=(action$,store,{ logger})=>action$.pipe(filter(isOfType(todosConstants.ADD)),// action is narrowed to: { type: "ADD_TODO"; payload: string; }tap(action=>{logger.log(`action type must be equal:${todosConstants.ADD} ===${action.type}`);}),ignoreElements());exportdefaultcombineEpics(logAddAction);

Selectors

"reselect"

import{createSelector}from'reselect';import{TodosState}from'./reducer';exportconstgetTodos=(state:TodosState)=>state.todos;exportconstgetTodosFilter=(state:TodosState)=>state.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;}});

Typing connect

importTypesfrom'Types';import{bindActionCreators,Dispatch}from'redux';import{connect}from'react-redux';import{countersActions}from'../features/counters';import{SFCCounter,SFCCounterProps}from'../components';// `state` parameter needs a type annotation to type-check the correct shape of a state object but also it'll be used by "type inference" to infer the type of returned propsconstmapStateToProps=(state:Types.RootState,ownProps:SFCCounterProps)=>({count:state.counters.reduxCounter,});// `dispatch` parameter needs a type annotation to type-check the correct shape of an action object when using dispatch functionconstmapDispatchToProps=(dispatch:Dispatch<Types.RootAction>)=>bindActionCreators({onIncrement:countersActions.increment,// without using action creators, this will be validated using your RootAction union type// onIncrement: () => dispatch({ type: "counters/INCREMENT" }),},dispatch);// NOTE: We don't need to pass generic type arguments to neither connect nor mapping functions because type inference will do all this work automatically. So there's really no reason to increase the noise ratio in your codebase!exportconstSFCCounterConnectedVerbose=connect(mapStateToProps,mapDispatchToProps)(SFCCounter);

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 project relative paths config"paths":{// define paths 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 with commonjs modules interop"esModuleInterop":true,"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

// typings/modules.d.tsdeclare module'Types';declare 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});};  ...}

Tutorials

Contributors