DEV Community: Antoine

Let's make a stopwatch pwa !

Antoine — Thu, 16 Sep 2021 13:42:05 +0000

In this tutorial, we are going to transform a basic webapp into a Progressive Web App (PWA).
The webapp we are going to use is a stopwatch. I won't explain the stopwatch implementation in this tutorial.
The stopwatch doesn't use external libraries or framework in order to focus on the PWA aspect.
At the end of the tutorial, the stopwatch app will be installable on an android smartphone !

The source code of the project is available here: https://github.com/towaanu/stopwatch-pwa.
The final app is available here: stopwatch.towaanu.com.

For the rest of the article, I will refer to Progressive Web App as PWA.

Why PWA ?

Progressive Web Apps are webapps using a set of features in order to look like a native app. A PWA tries to reduce as much as it can the barrier between webapp and native app.

Here are some features used by PWA:

Reduce as much as possible loading/starting time of the app using caches.
A PWA can work even without network. It can be started in offline mode.
A PWA can be installed natively. For example, you can install a PWA on your mobile and open the app from your mobile homescreen, like you would for any other native app.

You can find feedbacks from projects using PWA on this site: https://www.pwastats.com/.
Of course, there is a little work to transform a webapp into a PWA !

Let's see, how we can transform our little stopwatch webapp into a PWA and install it on a mobile !

Stopwatch webapp

The Stopwatch webapp is a simple app. We can start, stop or reset a timer.
Here is an example of the app:

You can find the final version of the stopwatch here: stopwatch.towaanu.com.
It does not use any external framework or library.

The project

There are 3 files in the starting project :

index.html: The html of the stopwatch
main.js: The main javascript file handling click events and stopwatch
style.css: The css of the app

You can find the starting project on this repo: https://github.com/towaanu/stopwatch-pwa/tree/12addb23ab334b82c81bfd91c6b437cf5f013fdb.

Since I will focus on the PWA part in this tutorial, I won't explain in details the implementation of the stopwatch.

Start the app

When working with a PWA, it's better to serve the app using a server rather than opening directly files from your machine.
I will introduce how to serve files using docker, nodejs, python however you can use other techniques to serve the project locally.
Usually, the app should be served over localhost.

Docker

If you have docker installed, you can use the nginx image to serve any files using a http server.
You need to be at the root of the project, then you can do:

docker run -p 8080:80 -v `pwd`:/usr/share/nginx/html:ro nginx

Then the stopwatch webapp (index.html, main.js, style.css) should be accessible at http://localhost:8080.

Nodejs

If you have nodejs installed locally, you can use http-server to start the http server.
You need to be at the root of the project, then you can do:

npx http-server .

Then the stopwatch webapp (index.html, main.js, style.css) should be accessible at http://localhost:8080.

Python

If you have python installed locally, you can use the following command at the root of the project :

python3 -m http.server 8080

Then the stopwatch webapp (index.html, main.js, style.css) should be accessible at http://localhost:8080.

Great, the app is accessible at http://localhost:8080 !
Now let's transform the stopwatch webapp into a PWA !

Webapp => PWA

For the rest of the tutorial we are going to use the chrome dev tool and more specifically the lighthouse tool.
Lighthouse can provide some feedbacks about what we need to turn a webapp into a PWA.

Where to start ?

Let's see what lighthouse tells us about the app:

Wow ! There is a lots of things to do. This is normal, we didn't have done anything to add PWA features to the app.
At first, we are going to focus on the Installable part.

Installable

Installable means the PWA can be installed on a device like any other native app.
For example you can install it on a smartphone and launch it like any other app !
Lighthouse tells us : Web app manifest or service worker do not meet the installability requirements.
What is a Web app manifest and a service worker ? Let's see it now !

Web app manifest

The web app manifest is a json file, commonly named manifest.json. This file contains data to help device display additional information when the PWA is installed.
You can define a lots of information such as name, short name, description, colors etc...
All properties are not mandatory for an app to be installable.
Let's make a manifest.json for the stopwatch app:

{
  "short_name": "Stopwatch",
  "name": "A stopwatch pwa",
  "icons": [
    {
      "src": "/images/icon-192.png",
      "type": "image/png",
      "sizes": "192x192",
      "purpose": "any maskable"
    },
    {
      "src": "/images/icon-512.png",
      "type": "image/png",
      "sizes": "512x512"
    }
  ],
  "start_url": "/",
  "display": "standalone",
  "scope": "/",
  "theme_color": "#ff5500",
  "background_color":"#ff5500"
}

Let's analyze manifest.json fields:

name or short_name: The name of the app. This name is used by the device to display the name of the app on home screen for example.
icons: List of icons to be used when the app is installed. You can provide any numbers of icons with different sizes. However, you can only provide 2 sizes : 192x192 and 512x512 and devices should be able to scale icons if needed.
theme_color: The theme color of the app. It can be used to colorize the topbar (of a smartphone for example) or the browser UI when displaying the webapp.
background_color: The background_color can be used as a splashscreen when the app is loading on mobile.
start_url: The start url of the app. We need to specify the start_url, in order to know which url to load when you open an installed PWA app. ( most of the time it's / )
display: How the app should be display. Possible values are: fullscreen, standalone, minimal-ui, browser. standalone means that the app should be displayed like any other native apps.

There are more properties you can use in manifest.json. You can find more information about manifest's properties on mdn web doc.

Nice! We have our manifest.json file, but we still need to include it in our app.
We can add the manifest.json file by adding this line in index.html (inside head tag):

<head>
    <meta charset="utf-8">

    <title>Stopwatch</title>

    <link rel="apple-touch-icon" href="/images/icons-192.png">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <meta name="theme-color" content="#ff5500"/>

    <!-- Manifest is added here -->
    <link rel="manifest" href="/manifest.json">

    <script src="main.js"></script>
    <link href="/style.css" rel="stylesheet">

</head>

Note: manifest.json is assumed to be at the root of the project in this example.
You can find the updated project with manifest here: https://github.com/towaanu/stopwatch-pwa/tree/2193c3fa88d451c8842001b362e06a55d9b4041d

Our web app manifest is now configured ! If you try to run a test with lighthouse again, you should see that the app is not yet installable.

In fact, we also need a service worker to make the app installable. Let's see what is a service worker !

Service Worker

As I said, a PWA needs to be usable offline. This way, it can act as a native app. In order to be used offline, a PWA needs to cache a lots of assets ( images, html, css, js ...). This is where the service worker comes into play !

Service workers enable us to control how assets should be cached. Basically a service worker is between the app and the internet. The service worker can intercept every network request from the webapp and decide whether or not it should return cache data or let the request go over the network. The service worker is also responsible to handle how elements are cached.

The service worker can:

Intercept every request from the webapp.
Decide whether or not a request should go over the network.
Return cache values when cache values are available.
Precache assets when the app starts.
Cache value return from network requests.

Here is a schema showing how service worker works when the webapp wants to fetch an images:

Note: Service worker can intercept any requests, not only images.

Now that we've seen what the service worker can do, let's implement one !

Register the service worker

Before creating our service worker, we need to register it.
We are going to register it at the beginning of the main.js file:

// main.js

// Check if browsers support service worker
if ('serviceWorker' in navigator) {
  window.addEventListener('load', function() {
    // Register the service worker
    navigator.serviceWorker.register('/sw.js').then(function(registration) {
      // Registration was successful
      console.log('ServiceWorker registration successful ', registration);
    }, function(err) {
      // registration failed
      console.log('ServiceWorker registration failed: ', err);
    });
  });
}

// stopwatch code...

And that's it for registering the service worker. As you can see, we are trying to load a sw.js file.
Let's create the sw.js file.

Create the service worker

The sw.js file is our service worker file.
Let's create the sw.js file at the root of the project:

var CACHE_NAME = 'cache-v1';
var urlsToCache = [
  '/',
  '/main.js',
  '/style.css'
];

// Event triggered the first time service worker is installed
self.addEventListener('install', function(event) {
    /*
     * Here we are caching urls specified above
     * This way when the app needs it files will be cached
     * Even if we close the app, and open later, files will still be in cache
     */
  event.waitUntil(
    caches.open(CACHE_NAME)
      .then(function(cache) {
        // Cache url defined in urlsToCache
        return cache.addAll(urlsToCache);
      })
  );
});

// Event triggered when the service worker is activated
self.addEventListener('activate', function(event) {
    // We don't need to do anything special here for this project
    console.log("Service worker activated");
});

// Event triggered whenever webapp needs to fetch a resource
self.addEventListener('fetch', function(event) {
  event.respondWith(
      // Check if the request is in the cache
    caches.match(event.request)
      .then(function(response) {
        /*
         * Found the request in cache
         * We can return the response in cache
         * We don't need to process the request
         */
        if (response) {
          return response;
        }

        /*
         * Request not found in cache
         * The request is processed and the result is returned
         */
        return fetch(event.request);
      }
    )
  );
});

Note: To keep things simple, I decided not to cache requests after fetch.

As you can see we can listen to several events related to service worker.
Those events are called lifecycle events of a service worker. There are 3 events:

install: This event is fired only once, when the service worker is installed for the first time. We are using it to precache some assets from our stopwatch app
activate: This event is fired when the service worker is activated. It can be useful to use this event when you update your service worker and you want to clean up cache before activating a new service worker
fetch: This event is fired every time the app is trying to make a request. This is where we can decide whether to process or not the request. We can also return the cache if the request has already been cached

Now, when the app is launched for the first time it will cache /, /main.js and /style.css. Then whenever one of those paths is requested, the service worker will return the value in cache without making the request to the network.
Great ! We successfully created the service worker.

You can find the updated version with service worker of the project in this repo: https://github.com/towaanu/stopwatch-pwa.

Workbox

The service worker here is really basic. However, sometime you need a more complex service worker with special rules to cache specific files or request. There is library commonly used to deal with service worker.
This library is Workbox. With workbox you can easily configure strategies for your service worker :

Stale-While-Revalidate: Responds with the cache value if it exists, otherwise use the request result. Even if the cache value is returned, Stale While Revalidate strategies will fetch the request and update the cache for the next request.
Cache-First: Always return the cache value. If the request is not cached, requests will be processed and the cache will be updated.
Network-First: Always return the value returned by the request. If the request failed, fallback to the cache value.
Network-Only: Always return the value returned by the request. Cache is not used even if request failed.
Cache-Only: Always return the value from the cache. Network request is not used even if value is not in cache.

In a real world application you probably want to use a library like Workbox for service worker.
You can learn more about Workbox strategies on the Workbox documentation.

Install the app

Now that we have our manifest and service worker, let's run lighthouse again !

Note: The only point left is the redirection HTTP => HTTPS. This is something to be configured at the server level ( by using nginx for example ).

Lighthouse tells us that our app meet the requirements to be installed. However if you try to access the app, you can not install it.
For security reasons, a PWA can only be installed if it is served from an HTTPS endpoint.
Since we are testing the app in local, it's complicated to serve the app over https.

You can try and install the app using this url: https://stopwatch.towaanu.com.
On the above url, the app is served using https, you should be able to install it!

Nice ! We have successfully add PWA features to a webapp. The stopwatch app can now be installed and used like any other native app !

Conclusion

I hope this tutorial helps you understand how PWA works!
You can find a working version of the project here : https://stopwatch.towaanu.com/
The source code is available on this repo : https://github.com/towaanu/stopwatch-pwa

Most of popular frameworks such as react, vue, angular... provide tools to generate app with pwa features included. Usually, tools generate a service worker and a manifest.json that you can customize.
If you want to see a PWA app using React, I have an opensource pwa project here: memodogs.towaanu.com. (You can find the source on this repo : https://github.com/towaanu/memodogs).

I hope you enjoy this article :)

Introduction to typescript with React

Antoine — Thu, 16 Sep 2021 13:30:28 +0000

In this article, I would like to share with you how I use typescript to improve my react code.
First we are going to see what is typescript and why it is used ?
Then, how we can use typescript with react ( components, hooks, extern libs ).
Finally, I will sum up what is the pros and cons using typescript in a react app .

Typescript ?

A common critic about javascript is that javascript is untyped. It means that you can do:

    let a = "Hello";
    let b = 5;

    // Here we substract a number to a string
    // Javascript does not warn us even if we try to substract a number to a string
    let c = a - b;

    console.log(a) // Hello
    console.log(b) // 5
    console.log(c) // NaN

As you can see javascript is very permissive which can lead to unexpected behaviors and bugs.
Another recurrent critic is that, we don't know fields of objects in javascript.
Sometime we get an object and we are not sure what is the structure of this object.
For example:

const user = {
    firstName: "Eikichi",
    lastName: "Onizuka"
}

console.log(user.name)
// user.name does not exist.
// Javascript is unable to tell us field name does not exist

These 2 samples can potentially provide error at runtime. It would be great to have hints before trying the code about potential error like ones above.
Typescript tries to address those issues by adding types to javascript.
Typescript is a programming language. By adding types, typescript is able to give some hints before running the code.
Typescript is not executed in the browser directly, typescript is first transformed into javascript code.
In the end, only javascript is executed in the browser when using typescript.

Now, let's see how we can use typescript alongside React !

The project

I am going to use some code sample from a basic todo list app using react and typescript.
In the app, we can add todo and toggle todo to make them done.
Todos will have 3 fields:

id: a universally unique identifier (uuid)
label: label of the todo
isDone: a boolean, true if todo is done Here is an example of the app:

The project is created using create react app.
Create react app provides a template using react and typescript to get started quickly.
The goal of the project is to provide some react/typescript example in a little project. Styling is not important.
You can find the code of the project here.
Here is a screenshot of the todos app:

React with Typescript

In this part we will see how we can use typescript with:

components
hooks
external libs

Shared types

Usually, there are types you need in several parts of your application. For example, a Todo type might be used in several components.
I define these types in a types.ts file at the root of the project. This way, we can access shared types easily across the app.
To define types, we use the interface keyword in typescript. Let's analyze how it's done in the todo app!

Todo app

As I said in the previous section todos have the following fields :

id: uuid. A uuid is a 128 bit number.
label: The label corresponding to the todo. This is represented as a string in our app.
isDone: A boolean.

Let's see how we can define the Todo type to use it later in our react app.
As I said before, all shared types are in the types.ts file.
Here is a sample of types.ts:

interface Todo {
    id: string
    label: string
    isDone: boolean
}

We named this new type Todo.
Finaly we assign fields with their respective types:

id : string, uuid will be represented as a string (example: "123e4567-e89b-12d3-a456-426614174000")
label: string, the label will be represented as a string (example: "Cook")
isDone: boolean (example: true)

Great ! We have our Todo interface. We can now use it in the code like this:

let todo: Todo = {
    id: "123e4567-e89b-12d3-a456-426614174000",
    label: "Cook",
    isDone: false
}

As you can see, we can specify the type of a variable using : in typescript.
If we try to access or to add a non present field, typescript will display an error.

We also need a NewTodo type. This type will be used to add a new todo in the list.
It is the same type as the Todo above except it does not have an id yet.
Here is the code behind in types.ts:

export interface NewTodo {
    label: string
    isDone: boolean
}

We can now use our todos types inside components.
Let's see how we can organize our components!

React components

In React components, I like to define a Props interface before declaring the component.
This Props interface contains every property of the component.

In my opinion, here are the pros of writing the Props interface :

It forces us to think about what properties our component needs
If you open the file, you can quickly find out the parameters of the component ( you don't have to look at the component code to know what parameters it can take )
When we use the component in our App, typescript can warn us if we pass wrong parameters to our component.

Let's see a concrete example from the todo app!

Todo app

We are going to analyze the TodosList component. Its role is to display a list of todos.
It takes 2 parameters:

todos: This is the list of todos that will be displayed.
onTodoClick: A callback called when a todo is clicked. This callback takes a todo as a parameter.

Let's see how we can define this React component with typescript.

import { Todo } from './types'; // import the Todo type
import TodoItem from './TodoItem'; // TodoItem is the component used to display one todo on the screen

/*
 * We define our Props type
 * It is used to define the props our TodosList will take in parameter
 */
interface Props {
    todos: Array<Todo>,
    onTodoClick?: (todo: Todo) => void
}

/*
 * The TodosList component.
 * We are using our Props type to tell typescript "This component uses the Props type for its parameter".
 * This way, when we use our component, typescript is able to tell you if we try to use a non existing property. 
 * Or if we try to give a bad type to a props.
 */
function TodosList({todos, onTodoClick}: Props) {
    /* 
     * Now we can use todos and the onTodoClick
     * if we try to write : `todos.foo`, typescript can tell us that an array of todos has no "foo" property
     * Same things apply to onTodoClick. If we try to call onTodoClick like this : onTodoClick(10)
     * Typescript is able to say "10 is not a todo, onTodoClick takes a todo as a parameter not a number"
     */
    return (
        <ul>
            { todos.map(todo => <TodoItem key={todo.id} onTodoClick={onTodoClick} todo={todo} />) }
        </ul>
    )
}

export default TodosList

Note: You can notice we have added a "?" to onTodoClick. It means that onTodoClick is optional.

Let's see what happens now if we try to use our component in another file:

/* Typescript warns us, because hello does not exist as a parameter for our TodosList */
<TodosList hello={"world"} /> 

/* Typescript warns us, because badTodos are missing id and label. */
let badTodos = [{isDone: false}, {isDone: true}];
<TodosList todos={badTodos} />

As you can see, typescript can help us avoid bugs before running the code.
You can find another example of a component in the TodoItem.tsx file.

Now let's see how we can use typescript with hooks!

Hooks

There is several hooks. I will focus on useState for this article.
The useState hook enables us to keep a state in our component.
With typescript we can define what state we want to store with useState.
Typescript will then use this information to prevent us from setting a state with a wrong type.
Let's see an example :

/*
 * Typescript now knows that num is a number and setNum takes a number as a parameter.
 * Typescript will warn us if we try to call setNum("a"), for example.
 */
const [num, setNum] = useState<number>();

Let's see an example in the todo App!

Todo app

In the todo app, we need the useState hook to manage todos.

Let's see the App.tsx code :

import styles from './App.module.css';
import {v4 as uuidv4} from 'uuid';
import { Todo, NewTodo } from './types';
import { useState } from 'react';
import TodosList from './TodosList';
import AddTodo from './AddTodo';

function App() {

  /*
   * With useState<Todo[]>, typescript knows: 
   * - todos is an Array of todos 
   * - setTodos takes an array of todos as parameter
   */
  const [todos, setTodos] = useState<Todo[]>([
    {id: uuidv4(), label: "Cleaning", isDone: true},
    {id: uuidv4(), label: "Cooking", isDone: false}
  ])

  function toggleTodo(todo: Todo) {
      setTodos(todos.map(
          t => t.id === todo.id ? {...t, isDone: !t.isDone} : t
      ))
  }

  function addTodo(newTodo: NewTodo) {
    /*
     * If we try to pass a non todos array, typescript will tell us
     */
    setTodos([...todos, {
        ...newTodo,
        id: uuidv4()
    }])
  }

  return (
    <div className={styles['App']}>
    {/* Since useState is typed, typescript knows that we are passing a todos array in TodosList */}
        <TodosList onTodoClick={toggleTodo} todos={todos} />
        <AddTodo onNewTodoSubmit={addTodo} />
    </div>
  );
}

export default App;

Since useState is typed, typescript makes sure, we are not using todos and setTodos wrongfully.

Notice that we use an external library ( uuid ) for generating todo ids.
By default typescript does not know the v4 function returns a string.
Let's see how we can help typescript understand external libraries !

External libraries

For external libraries, there are usually 3 scenarios:

The library is written in typescript. When this is the case, most of the time we just need to npm install the library and we have types. It is the best case scenario.
The library does not ship directly with types. By default typescript does not know any types about the library. However, most of the time there is types written alongside the project. Usually, we can install those types using npm install @types/[LIB_NAME]. This is the case for react.For example, there is a @types/react package to add types with react.
The library is not written with typescript and there is no types. This is the worst case scenario. You have to either write types yourself or use the any types in typescript.

Note: As typescript is getting more and more popular, most of the time you will find types when using external libraries

Todo app

Let's get back to the uuid package. uuid package is not written in typescript.
However, there is a @types/uuid package for it. The package is installed using npm install --save-dev @types/uuid.
This way when we assign an uuid to a todo's id, typescript knows, we are assigning a string to id.

Conclusion

In my opinion, here are the pros and cons of using typescript with react.

Pros :

By writing types when we writing components it forces us to think a more about our components and how it should be used
If you have a compatible editor, typescript can give you error and autocompletion when you write code (even in JSX !)
When you use or open a component file, you can see easily its parameters. You don't have to ask yourself "what is the name of this property, or if this property takes a string or a number"

Cons :

It makes the code a bit more verbose. Since we need to specify types.
It adds some complexity to build the project. We now need to transform typescript to javascript before running the apps. Hopefully tools like cra provide a ready to use react/typescript template

As I said, you can find the code of the todo app in this repo.
I hope you like this little introduction to typescript with react! :)