This repo is now deprecated. In the time since it created TypeScript support is now a default feature of Create React App, Next.JS and Razzle.
This means you can get started with:
# Creates an app called my-app
npx create-react-app my-app --typescript
cd my-app
# Adds the type definitions
npm install --save typescript @types/node @types/react @types/react-dom @types/jest
echo "Good to go :tada:"
This repo offers some exmples on how to take that project into production and handle testing and state. However, you can
also use the official documentation in the Create React App website for that.
If you'd like to know more about how to effectively do React with TypeScript, we recommend looking at the following:
Below is the original README for this sample.
TypeScript React Starter
This quick start guide will teach you how to wire up TypeScript with React.
By the end, you'll have
- a project with React and TypeScript
- linting with TSLint
- testing with Jest and Enzyme, and
- state management with Redux
We'll use the create-react-app tool to quickly get set up.
We assume that you're already using Node.js with npm.
You may also want to get a sense of the basics with React.
Install create-react-app
We're going to use the create-react-app because it sets some useful tools and canonical defaults for React projects.
This is just a command-line utility to scaffold out new React projects.
npm install -g create-react-app
Create our new project
We'll create a new project called my-app:
create-react-app my-app --scripts-version=react-scripts-ts
react-scripts-ts is a set of adjustments to take the standard create-react-app project pipeline and bring TypeScript into the mix.
At this point, your project layout should look like the following:
my-app/
├─ .gitignore
├─ images.d.ts
├─ node_modules/
├─ public/
├─ src/
│ └─ ...
├─ package.json
├─ tsconfig.json
├─ tsconfig.prod.json
├─ tsconfig.test.json
└─ tslint.json
Of note:
tsconfig.json contains TypeScript-specific options for our project.
- We also have a
tsconfig.prod.json and a tsconfig.test.json in case we want to make any tweaks to our production builds, or our test builds.
tslint.json stores the settings that our linter, TSLint, will use.package.json contains our dependencies, as well as some shortcuts for commands we'd like to run for testing, previewing, and deploying our app.public contains static assets like the HTML page we're planning to deploy to, or images. You can delete any file in this folder apart from index.html.src contains our TypeScript and CSS code. index.tsx is the entry-point for our file, and is mandatory.images.d.ts will tell TypeScript that certain types of image files can be import-ed, which create-react-app supports.
Setting up source control
Our testing tool, Jest, expects some form of source control (such as Git or Mercurial) to be present.
For it to run correctly, we'll need to initialize a git repository.
git init
git add .
git commit -m "Initial commit."
Note: if you've cloned this repository, you won't have to run the above at all.
Overriding defaults
The TSLint configuration that react-scripts-ts sets us up with is a bit overzealous.
Let's fix that up.
{
- "extends": ["tslint:recommended", "tslint-react", "tslint-config-prettier"],
+ "extends": [],
+ "defaultSeverity": "warning",
"linterOptions": {
"exclude": [
"config/**/*.js",
"node_modules/**/*.ts"
]
}
}
Configuring TSLint is out of the scope of this starter, but you should feel free to experiment with something that works for you.
Running the project
Running the project is as simple as running
npm run start
This runs the start script specified in our package.json, and will spawn off a server which reloads the page as we save our files.
Typically the server runs at http://localhost:3000, but should be automatically opened for you.
This tightens the iteration loop by allowing us to quickly preview changes.
Testing the project
Testing is also just a command away:
npm run test
This command runs Jest, an incredibly useful testing utility, against all files whose extensions end in .test.ts or .spec.ts.
Like with the npm run start command, Jest will automatically run as soon as it detects changes.
If you'd like, you can run npm run start and npm run test side by side so that you can preview changes and test them simultaneously.
Creating a production build
When running the project with npm run start, we didn't end up with an optimized build.
Typically, we want the code we ship to users to be as fast and small as possible.
Certain optimizations like minification can accomplish this, but often take more time.
We call builds like this "production" builds (as opposed to development builds).
To run a production build, just run
npm run build
This will create an optimized JS and CSS build in ./build/static/js and ./build/static/css respectively.
You won't need to run a production build most of the time,
but it is useful if you need to measure things like the final size of your app.
Creating a component
We're going to write a Hello component.
The component will take the name of whoever we want to greet (which we'll call name), and optionally, the number of exclamation marks to trail with (enthusiasmLevel).
When we write something like <Hello name="Daniel" enthusiasmLevel={3} />, the component should render to something like <div>Hello Daniel!!!</div>.
If enthusiasmLevel isn't specified, the component should default to showing one exclamation mark.
If enthusiasmLevel is 0 or negative, it should throw an error.
We'll write a Hello.tsx:
// src/components/Hello.tsx
import * as React from 'react';
export interface Props {
name: string;
enthusiasmLevel?: number;
}
function Hello({ name, enthusiasmLevel = 1 }: Props) {
if (enthusiasmLevel <= 0) {
throw new Error('You could be a little more enthusiastic. :D');
}
return (
<div className="hello">
<div className="greeting">
Hello {name + getExclamationMarks(enthusiasmLevel)}
</div>
</div>
);
}
export default Hello;
// helpers
function getExclamationMarks(numChars: number) {
return Array(numChars + 1).join('!');
}
Notice that we defined a type named Props that specifies the properties our component will take.
name is a required string, and enthusiasmLevel is an optional number (which you can tell from the ? that we wrote out after its name).
We also wrote Hello as a stateless function component (an SFC).
To be specific, Hello is a function that takes a Props object, and picks apart (or "destructures") all the properties that it will be passed.
If enthusiasmLevel isn't given in our Props object, it will default to 1.
Writing functions is one of two primary ways React allows us to make components.
If we wanted, we could have written it out as a class as follows:
class Hello extends React.Component<Props, object> {
render() {
const { name, enthusiasmLevel = 1 } = this.props;
if (enthusiasmLevel <= 0) {
throw new Error('You could be a little more enthusiastic. :D');
}
return (
<div className="hello">
<div className="greeting">
Hello {name + getExclamationMarks(enthusiasmLevel)}
</div>
</div>
);
}
}
Classes are useful when our component instances have some state or need to handle lifecycle hooks.
But we don't really need to think about state in this specific example - in fact, we specified it as object in React.Component<Props, object>, so writing an SFC makes more sense here, but it's important to know how to write a class component.
Notice that the class extends React.Component<Props, object>.
The TypeScript-specific bit here are the type arguments we're passing to React.Component: Props and object.
Here, Props is the type of our class's this.props, and object is the type of this.state.
We'll return to component state in a bit.
Now that we've written our component, let's dive into index.tsx and replace our render of <App /> with a render of <Hello ... />.
First we'll import it at the top of the file:
import Hello from './components/Hello';
and then change up our render call:
ReactDOM.render(
<Hello name="TypeScript" enthusiasmLevel={10} />,
document.getElementById('root') as HTMLElement
);
Type assertions
One thing we'll point out in this section is the line document.getElementById('root') as HTMLElement.
This syntax is called a type assertion, sometimes also called a cast.
This is a useful way of telling TypeScript what the real type of an expression is when you know better than the type checker.
The reason we need to do so in this case is that getElementById's return type is HTMLElement | null.
Put simply, getElementById returns null when it can't find an element with a given id.
We're assuming that getElementById will actually succeed, so we need to convince TypeScript of that using the as syntax.
TypeScript also has a trailing "bang" syntax (!), which removes null and undefined from the prior expression.
So we could have written document.getElementById('root')!, but in this case we wanted to be a bit more explicit.
Stateful components
We mentioned earlier that our component didn't need state.
What if we wanted to be able to update our components based on user interaction over time?
At that point, state becomes more important.
Deeply understanding best practices around component state in React are out of the scope of this starter, but let's quickly peek at a stateful version of our Hello component to see what adding state looks like.
We're going to render two <button>s which update the number of exclamation marks that a Hello component displays.
To do that, we're going to
- Define a type for our state (i.e.
this.state)
- Initialize
this.state based on the props we're given in our constructor.
- Create two event handlers for our buttons (
onIncrement and onDecrement).
// src/components/StatefulHello.tsx
import * as React from "react";
export interface Props {
name: string;
enthusiasmLevel?: number;
}
interface State {
currentEnthusiasm: number;
}
class Hello extends React.Component<Props, State> {
constructor(props: Props) {
super(props);
this.state = { currentEnthusiasm: props.enthusiasmLevel || 1 };
}
onIncrement = () => this.updateEnthusiasm(this.state.currentEnthusiasm + 1);
onDecrement = () => this.updateEnthusiasm(this.state.currentEnthusiasm - 1);
render() {
const { name } = this.props;
if (this.state.currentEnthusiasm <= 0) {
throw new Error('You could be a little more enthusiastic. :D');
}
return (
<div className="hello">
<div className="greeting">
Hello {name + getExclamationMarks(this.state.currentEnthusiasm)}
</div>
<button onClick={this.onDecrement}>-</button>
<button onClick={this.onIncrement}>+</button>
</div>
);
}
updateEnthusiasm(currentEnthusiasm: number) {
this.setState({ currentEnthusiasm });
}
}
export default Hello;
function getExclamationMarks(numChars: number) {
return Array(numChars + 1).join('!');
}
Notice:
- Much like with
Props, we had to define a new type for our state: State.
- To update state in React, we use
this.setState - we don't set it directly except in the constructor. setState only takes the properties we're interested in updating and our component will re-render as appropriate.
- We're using class property initializers with arrow functions (e.g.
onIncrement = () => ...).
- Declaring these as arrow functions avoids issues with orphaned uses of
this.
- Setting them as instance properties creates them only once - a common mistake is to initialize them in the
render method which allocates closures one every call to render.
We won't use this stateful component any further in this starter.
Stateful components are great for creating components that focus solely on presenting content (as opposed to handling core application state).
In some contexts, it can be used for handling your entire application's state, with one central component passing down functions that can call setState appropriately; however, for much larger applications, a dedicated state manager might be preferable (as we'll discuss below).
Adding style 😎
Styling a component with our setup is easy.
To style our Hello component, we can create a CSS file at src/components/Hello.css.
.hello {
text-align: center;
margin: 20px;
font-size: 48px;
font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
}
.hello button {
margin-left: 25px;
margin-right: 25px;
font-size: 40px;
min-width: 50px;
}
The tools that create-react-app uses (namely, Webpack and various loaders) allow us to just import the stylesheets we're interested in.
When our build runs, any imported .css files will be concatenated into an output file.
So in src/components/Hello.tsx, we'll add the following import.
import './Hello.css';
Writing tests with Jest
We had a certain set of assumptions about our Hello component.
Let's reiterate what they were:
- When we write something like
<Hello name="Daniel" enthusiasmLevel={3} />, the component should render to something like <div>Hello Daniel!!!</div>.
- If
enthusiasmLevel isn't specified, the component should default to showing one exclamation mark.
- If
enthusiasmLevel is 0 or negative, it should throw an error.
We can use these requirements to write a few tests for our components.
But first, let's install Enzyme.
Enzyme is a common tool in the React ecosystem that makes it easier to write tests for how components will behave.
By default, our application includes a library called jsdom to allow us to simulate the DOM and test its runtime behavior without a browser.
Enzyme is similar, but builds on jsdom and makes it easier to make certain queries about our components.
Let's install it as a development-time dependency.
npm install -D enzyme @types/enzyme enzyme-adapter-react-16 @types/enzyme-adapter-react-16 react-test-renderer
Notice we installed packages enzyme as well as @types/enzyme.
The enzyme package refers to the package containing JavaScript code that actually gets run, while @types/enzyme is a package that contains declaration files (.d.ts files) so that TypeScript can understand how you can use Enzyme.
You can learn more about @types packages here.
We also had to install enzyme-adapter-react-16 and react-test-renderer.
This is something enzyme expects to be installed.
Before writing the first test, we have to configure Enzyme to use an adapter for React 16.
We'll create a file called src/setupTests.ts that is automatically loaded when running tests:
import * as enzyme from 'enzyme';
import * as Adapter from 'enzyme-adapter-react-16';
enzyme.configure({ adapter: new Adapter() });
Now that we've got Enzyme set up, let's start writing our test!
Let's create a file named src/components/Hello.test.tsx, adjacent to our Hello.tsx file from earlier.
// src/components/Hello.test.tsx
import * as React from 'react';
import * as enzyme from 'enzyme';
import Hello from './Hello';
it('renders the correct text when no enthusiasm level is given', () => {
const hello = enzyme.shallow(<Hello name='Daniel' />);
expect(hello.find(".greeting").text()).toEqual('Hello Daniel!')
});
it('renders the correct text with an explicit enthusiasm of 1', () => {
const hello = enzyme.shallow(<Hello name='Daniel' enthusiasmLevel={1}/>);
expect(hello.find(".greeting").text()).toEqual('Hello Daniel!')
});
it('renders the correct text with an explicit enthusiasm level of 5', () => {
const hello = enzyme.shallow(<Hello name='Daniel' enthusiasmLevel={5} />);
expect(hello.find(".greeting").text()).toEqual('Hello Daniel!!!!!');
});
it('throws when the enthusiasm level is 0', () => {
expect(() => {
enzyme.shallow(<Hello name='Daniel' enthusiasmLevel={0} />);
}).toThrow();
});
it('throws when the enthusiasm level is negative', () => {
expect(() => {
enzyme.shallow(<Hello name='Daniel' enthusiasmLevel={-1} />);
}).toThrow();
});
These tests are extremely basic, but you should be able to get the gist of things.
Adding state management
At this point, if all you're using React for is fetching data once and displaying it, you can consider yourself done.
But if you're developing an app that's more interactive, then you may need to add state management.
State management in general
On its own, React is a useful library for creating composable views.
However, React doesn't prescribe any specific way of synchronizing data throughout your application.
As far as a React component is concerned, data flows down through its children through the props you specify on each element.
Some of those props might be functions that update the state one way or another, but how that happens is an open question.
Because React on its own does not focus on application state management, the React community uses libraries like Redux and MobX.
Redux relies on synchronizing data through a centralized and immutable store of data, and updates to that data will trigger a re-render of our application.
State is updated in an immutable fashion by sending explicit action messages which must be handled by functions called reducers.
Because of the explicit nature, it is often easier to reason about how an action will affect the state of your program.
MobX relies on functional reactive patterns wher
Microsoft's starter template and step-by-step guide for wiring up TypeScript with React. By the end you have a project with TSLint linting, Jest and Enzyme testing, and Redux state management.