A JSX primer

When using React, you define your views using a special DSL called JavaScript XML (JSX) that you embed straight into your JavaScript code. It sort of looks like HTML in your JavaScript. You then run your JavaScript through a JSX compiler that rewrites that funky JSX syntax into regular JavaScript function calls.

The process looks something like this. Say you’re building a menu app for your friend’s restaurant, and you list out a few items on the brunch menu with the following JSX:

<ul class='list'>
  <li>Homemade granola with yogurt</li>
  <li>Fantastic french toast with fruit</li>
  <li>Tortilla Española with salad</li>
</ul>

After running that code through a JSX compiler like Babel’s transform-react-jsx plugin, you’ll get the following output:

React.createElement(
  'ul',
  {'class': 'list'},
  React.createElement(
    'li',
    null,
    'Homemade granola with yogurt'
  ),
  React.createElement(
    'li',
    null,
    'Fantastic French toast with fruit'
  ),
  React.createElement(
    'li',
    null,
    'Tortilla Española with salad'
  )
);

import React from 'react'

<ul /> // Error TS2304: Cannot find name 'React'.

import * as React from 'react'

The nice thing about JSX is you can write what looks a lot like normal HTML, then compile it automatically to a JavaScript engine–friendly format. As an engineer you only use a familiar, high-level, declarative DSL, and you don’t have to deal with the implementation details.

You don’t need JSX to work with React (you can write that compiled code directly and it’ll work fine), and you can use JSX without React (the specific function call that JSX tags compile to—React.createElement in the previous example—is configurable), but the combination of React with JSX is magical, and makes writing views really fun, and really, really safe.

TSX = JSX + TypeScript

Files that contain JSX use the file extension .jsx. And TypeScript files that contain JSX use the .tsx extension. TSX is to JSX what TypeScript is to JavaScript—a compile-time safety and assistance layer to help you be more productive and produce code with fewer mistakes. To enable TSX support for your project, add the following line to your tsconfig.json:

{
  "compilerOptions": {
    "jsx": "react"
  }
}

The jsx directive has three modes at the time of writing:

react

Compile JSX to a .js file using the JSX pragma (by default, React.createElement).

react-native

Preserve JSX without compiling it, but do emit a file with a .js extension.

preserve

Typecheck JSX but don’t compile it away, and emit a file with a .jsx extension.

Under the hood, TypeScript exposes a few hooks for typing TSX in a pluggable way. These are special types on the global.JSX namespace that TypeScript looks at as the source of truth for TSX types throughout your program. If you’re just using React, you don’t need to go that low-level; but if you’re building your own TypeScript library that uses TSX (and doesn’t use React)—or if you’re curious how the React type declarations do it—head over to Appendix G.

Using TSX with React

React lets us declare two kinds of components: function components and class components. Both kinds of components take some properties and render some TSX. From a consumer’s point of view, they are identical.

Declaring and rendering a function component looks like this:

import React from 'react' 

type Props = { 
  isDisabled?: boolean
  size: 'Big' | 'Small'
  text: string
  onClick(event: React.MouseEvent<HTMLButtonElement>): void 
}

export function FancyButton(props: Props) { 
  const [toggled, setToggled] = React.useState(false) 
  return <button
    className={'Size-' + props.size}
    disabled={props.isDisabled || false}
    onClick={event => {
      setToggled(!toggled)
      props.onClick(event)
    }}
  >{props.text}</button>
}

let button = <FancyButton 
  size='Big'
  text='Sign Up Now'
  onClick={() => console.log('Clicked!')}
/>

We have to bring the React variable into the current scope in order to use TSX with React. Since TSX is compiled to React.createElement function calls, that means we need to import React so that it’s defined at runtime.

We start by declaring the specific set of props we can pass to our FancyButton component. Props is always an object type, and is named Props by convention. For our FancyButton component, isDisabled is optional, while the rest of our props are required.

React has its own set of wrapper types for DOM events. When using React events, be sure to use React’s event types rather than regular DOM event types.

A function component is just a regular function that has up to one parameter (the props object) and returns a React-renderable type. React is permissive and can render a wide range of types: TSX, strings, numbers, booleans, null, and undefined.

We use React’s useState hook to declare local state for a function component. useState is one of a handful of hooks available in React, which you can combine to create your own custom hooks. Note that because we passed the initial value false to useState, TypeScript was able to infer that the piece of state is a boolean; if we’d instead used a type that TypeScript wasn’t able to infer—for example, an array—we would have bound the type explicitly (e.g., with useState<number[]>;([])).

We use TSX syntax to create an instance of FancyButton. The <FancyButton /> syntax is almost identical to calling FancyButton, but it lets React manage the lifecycle of FancyButton for us.

That’s it. TypeScript enforces that:

• JSX is well formed. Tags are closed and properly nested, and tag names aren’t misspelled.

• When we instantiate a <FancyButton /> we pass all required—plus any optional—props to FancyButton (size, text, and onClick), and that the props are all correctly typed.

• We don’t pass any extraneous props to FancyButton, just the ones that are required.

A class component is similar:

import React from 'react' 
import {FancyButton} from './FancyButton'

type Props = { 
  firstName: string
  userId: string
}

type State = { 
  isLoading: boolean
}

class SignupForm extends React.Component<Props, State> { 
  state = { 
    isLoading: false
  }
  render() { 
    return <> 
      <h2>Sign up for a 7-day supply of our tasty
          toothpaste now, {this.props.firstName}.</h2>
      <FancyButton
        isDisabled={this.state.isLoading}
        size='Big'
        text='Sign Up Now'
        onClick={this.signUp}
      />
    </>
  }
  private signUp = async () => { 
    this.setState({isLoading: true})
    try {
      await fetch('/api/signup?userId=' + this.props.userId)
    } finally {
      this.setState({isLoading: false})
    }
  }
}

let form = <SignupForm firstName='Albert' userId='13ab9g3' /> 

Like before, we import React to bring it into scope.

Like before, we declare a Props type to define what data we need to pass in when creating an instance of <SignupForm />.

We declare a State type to model our component’s local state.

To declare a class component, we extend the React.Component base class.

We use a property initializer to declare default values for local state.

Like with function components, a class component’s render method returns something renderable by React: TSX, a string, a number, a boolean, null, or undefined.

TSX supports fragments using the special <>...</> syntax. A fragment is a nameless TSX element that wraps other TSX, and is a way to avoid rendering extra DOM elements in places where you need to return a single TSX element. For example, a React component’s render method needs to return a single TSX element; to do that, we could have wrapped our code with a <div> or any other element, but that would have incurred unnecessary overhead during rendering.

We define signUp using an arrow function, to make sure that this in the function doesn’t get re-bound.

Finally, we instantiate our SignupForm. Like when instantiating function components, we could have directly new-ed it with new SignupForm({firstName: 'Albert', userId: '13ab9g3'}) instead, but that would mean that React couldn’t manage the SignupForm instance’s lifecycle for us.

Notice how we mix and match value-based (FancyButton, SignupForm) and intrinsic (section, h2) components in this example. We put TypeScript to work to verify things like:

• That all required state fields were defined either in the state initializer, or in the constructor

• That whatever we access on props and state actually exists, and is of the type we think it is

• That we don’t write to this.state directly, because in React, state updates have to go through the setState API

• That calling render really returns some JSX

With TypeScript you can make your React code safer, and become a better, happier person as a result.

Scaffolding

To initialize a new Angular project, start by globally installing Angular CLI using NPM:

npm install @angular/cli --global

Then, use Angular CLI to initialize a new Angular application:

ng new my-angular-app

Follow the prompts, and Angular CLI will set up a bare-bones Angular application for you.

In this book we won’t go into depth on how an Angular application is structured, or how to configure and run it. For detailed information, head over to the official Angular documentation.

Components

Let’s build an Angular component. Angular components are like React components, and include a way to describe a component’s DOM structure, styling, and controller. With Angular, you generate component boilerplate with Angular CLI, then fill in the details by hand. An Angular component consists of a few different files:

• A template, which describes the DOM a component renders

• A set of CSS styles

• A component class, which is a TypeScript class that dictates your components’ business logic

Let’s start with the component class:

import {Component, OnInit} from '@angular/core'

@Component({
  selector: 'simple-message',
  styleUrls: ['./simple-message.component.css'],
  templateUrl: './simple-message.component.html'
})
export class SimpleMessageComponent implements OnInit {
  message: string
  ngOnInit() {
    this.message = 'No messages, yet'
  }
}

For the most part, this is a pretty standard TypeScript class, with just a few differences that bring out how Angular leverages TypeScript. Namely:

• Angular’s lifecycle hooks are available as TypeScript interfaces—just declare which ones you implement (ngOnChanges, ngOnInit, etc.). TypeScript then enforces that you implement methods that comply with the lifecycle hooks you want. In this example we implemented the OnInit interface, which requires that we implement the ngOnInit method.

• Angular makes heavy use of TypeScript decorators (see “Decorators”) to declare metadata related to your Angular components, services, and modules. In this example, we used a selector to declare how people can consume our component, and we used templateUrls and styleUrl to link an HTML template and CSS stylesheet to our component.

{
  "angularCompilerOptions": {
    "fullTemplateTypeCheck": true
  }
}

Services

Angular comes with a built-in dependency injector (DI), which is a way for the framework to take care of instantiating services and passing them in as arguments to components and services that depend on them. This can make it easier to instantiate and test services and components.

Let’s update SimpleMessageComponent to inject a dependency, MessageService, responsible for fetching messages from the server:

import {Component, OnInit} from '@angular/core'
import {MessageService} from '../services/message.service'

@Component({
  selector: 'simple-message',
  templateUrl: './simple-message.component.html',
  styleUrls: ['./simple-message.component.css']
})
export class SimpleMessageComponent implements OnInit {
  message: string
  constructor(
    private messageService: MessageService
  ) {}
  ngOnInit() {
    this.messageService.getMessage().subscribe(response =>
      this.message = response.message
    )
  }
}

Angular’s AoT compiler looks at the parameters that your component’s constructor takes, plucks out their types (e.g., MessageService), and searches the relevant dependency injector’s dependency map for a dependency of that specific type. It then instantiates that dependency (new-ing it) if it hasn’t been instantiated yet, and passes it into the SimpleMessageComponent instance’s constructor. All of this DI stuff is pretty complicated, but it can be convenient as your application grows and you have multiple dependencies you might use depending on how the app is configured (e.g., ProductionAPIService versus DevelopmentAPIService) or when testing it (MockAPIService).

Now let’s take a quick look at how to define a service:

import {Injectable} from '@angular/core'
import {HttpClient} from '@angular/common/http'

@Injectable({
  providedIn: 'root'
})
export class MessageService {
  constructor(private http: HttpClient) {}
  getMessage() {
    return this.http.get('/api/message')
  }
}

Whenever we create a service in Angular, we again use TypeScript decorators to register it as something that is Injectable, and we define whether it is provided at the root level of the application or in a submodule. Here, we registered the service MessageService, allowing us to inject it anywhere in our application. In the constructor of any component or service, we can just ask for a MessageService and Angular will magically take care of passing it in.

With how to safely use these two popular frontend frameworks out of the way, let’s move on to typing the interface between your frontend and your backend.