How to Create a PWA Game using Preact in 5 steps (Tutorial)

Seif Ghezala

Updated 2023-11-13 · 12 min

#tutorial #javascript #preact #react #performance #css

Table of contents

In this article, we will create a Progressive Web Application! Don’t worry, we won’t make another todo list. Instead, we will build a fun game that satisfies Google’s checklist for building a PWA.

Final result

You can play it here and check the final source code on Github.

1- Requirements: what do we want to achieve?

Let’s first understand what we want to achieve.

Here are the game’s functional requirements:

There is a 4 x 3 (4 rows, 3 columns) grid of cards.
By default, each card shows its back and hides a certain emoji.
There are in total 6 unique emojis. Each emoji is duplicated, making the total number of emojis 12.
The player can flip any card that has not been matched yet, showing the emoji behind it.
If the player flips their second card and it does not match the previously flipped one (i.e. they don’t have the same emoji), then both cards are flipped back to their initial position.
If the player flips their second card and it matches the previously flipped one, then both cards are matched and the player’s score is incremented.
The maximum score is 6 (1 point per matched pair). Once the player reaches the maximum score, the game ends with a displayed winning message.

Our game should also satisfy the following items to be considered a PWA:

The game is served over HTTPS.
All pages are responsive on tablets and mobile devices.
The game can be added to the home screen of the user’s device and look like a native app.
Offline Loading: The game should be functional offline
Fast first load.
Page transitions don’t feel like they block on the network.
Each page has a URL.

2- Designing our pages

Before we jump into code, let’s grab a pen and paper and draw what our pages will look like.

To keep it simple, the home page will just have the game’s title and a button to start a new game:

The game page is basically a grid of cards and the score of the player above it:

The cards can be either in the default, flipped or matched state:

3- Bootstrapping the application with preact-cli

Now that we have our requirements in place, let’s kick off our application development. We can quickly bootstrap our application using preact-cli.

First, let’s install it globally:

npm i -g preact-cli

Then let’s use preact-cli to bootstrap our match-game:

preact create default match-game

The generated source code has the following structure:

 └── src
        ├── assets
        ├── components
        ├── index.js
        ├── manifest.json
        ├── routes
        └── style

assets will contain our assets (favicon and other icons)
components will have our preact components including the main App component
index.js is the entry point to our application
manifetst.json : will provide information about the icons of our game in Android devices.
routes will contain our routes.
style will have global CSS for the application.

Let’s empty both the components and routes directories since we will build our components and routes from scratch.

4- Setting up the routes

Our game will have 3 routes:

/ Home route: points to the homepage containing the game’s title and a button to start playing.
/game Game route: points to the game page containing the score and the grid of cards to be flipped.
/win Win route: points to the winning page showing a message to congratulate the user after winning.

Let’s first create these routes:

Home route:

// routes/home

const Home = () => (
  <div>
    <h1>Home</h1>
    <p>This is the Home route.</p>
  </div>
);

export default Home;

Game route:

// routes/game

const Game = () => (
  <div>
    <h1>Game</h1>
    <p>This is the Game route.</p>
  </div>
);

export default Game;

Win route:

// routes/win

const Win = () => (
  <div>
    <h1>Win</h1>
    <p>This is the Win route.</p>
  </div>
);

export default Win;

Let’s also configure our router in the App component:

import { Component } from "preact";
import { Router } from "preact-router";

import Home from "../routes/home";
import Game from "../routes/game";
import Win from "../routes/win";

export default class App extends Component {
  render() {
    return (
      <div id="app">
        <Router onChange={this.handleRoute}>
          <Home path="/" />
          <Game path="/game" />
          <Win path="/win" />
        </Router>
      </div>
    );
  }
}

5- Building the pages

Now that we have our routes ready, we can start building the pages.

First, let’s define some global styles in the styles/index.css file. We will use the “Press Start 2P” font, which is very common in games.

After downloading the font and placing it in assets/fonts , our final index.css should look like this:

/* src/style/index.css */

@import url("https://fonts.googleapis.com/css?family=Press+Start+2P");

html,
body {
  height: 100%;
  width: 100%;
  padding: 0;
  margin: 0;
  background: #fafafa;
  font-family: "Press Start 2P", cursive;
  font-size: 12px;
}

* {
  box-sizing: border-box;
}

button {
  font-family: "Press Start 2P", cursive;
  color: #000;
  cursor: pointer;
  -webkit-tap-highlight-color: rgba(0, 0, 0, 0);
}

The homepage

The homepage is quite simple since it’s just a header and a button to start a new game.

The button redirects to the /game route. Although we can either use a Link from preact-router (which acts as an anchor) or a button, a button, in this case, is more accessible due to its native styling.

// src/routes/home/index.js

import { Component } from "preact";
import { route } from "preact-router";
import style from "./style.css";

export default class Home extends Component {
  startGame = () => {
    route("/game");
  };

  render() {
    return (
      <div class={style.home}>
        <div class={style.head}>
          <h2>Match Game</h2>
        </div>
        <button class={style.button} onClick={this.startGame}>
          New Game
        </button>
      </div>
    );
  }
}

/* src/routes/home/style.css */

.home {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  display: flex;
  flex-direction: column;
  justify-content: center;
  align-items: center;
  text-align: center;
  line-height: 1.5;
}

.head {
  max-width: 300px;
  padding-bottom: 30px;
  font-size: 1.2rem;
}

.button {
  width: 200px;
  height: 50px;
  background-color: #e7a61a;
  -webkit-tap-highlight-color: rgba(0, 0, 0, 0);
  color: #000;
  border: 0;
  border-radius: 10px;
  -webkit-box-shadow: 0px 3px 6px 0px #000;
  -moz-box-shadow: 0px 3px 6px 0px #000;
  box-shadow: 0px 3px 6px 0px #000;
  outline: none;
  font-family: "Press Start 2P", cursive;
  font-size: 1.2rem;
  cursor: pointer;
}

Note: we are importing the home styles from ./style.css. This is because preact-cli provides out of the box support for CSS Modules! If you don’t know anything about CSS Modules and you don’t want to learn about them now, you can still continue the tutorial without a problem. All what you have to understand is that in order to map the styles of a JSX node in index.css to a CSS declaration in style.css , we just need set its class name to the corresponding declaration name (e.g. style.home is mapped to the CSS declaration with class name home ).

The winning page

The winning page is actually very similar to the home page, except that it will have the winning message instead of the game’s title.

// src/routes/win/index.js

import { Component } from "preact";
import { route } from "preact-router";
import style from "./style.css";

export default class Win extends Component {
  startGame = () => {
    route("/game");
  };

  render() {
    return (
      <div class={style.win}>
        <div class={style.head}>
          <div class={style.emoji}>🎉</div>
          <div>You won!</div>
        </div>
        <button class={style.button} onClick={this.startGame}>
          New Game
        </button>
      </div>
    );
  }
}

/* src/routes/win/style.css */

.win {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  display: flex;
  flex-direction: column;
  justify-content: center;
  align-items: center;
  text-align: center;
  line-height: 1.5;
}

.head {
  max-width: 300px;
  padding-bottom: 30px;
  font-size: 1.2rem;
}

.emoji {
  font-size: 6rem;
}

.button {
  width: 200px;
  height: 50px;
  background-color: #e7a61a;
  color: #000;
  border: 0;
  border-radius: 10px;
  -webkit-box-shadow: 0px 3px 6px 0px #000;
  -moz-box-shadow: 0px 3px 6px 0px #000;
  box-shadow: 0px 3px 6px 0px #000;
  outline: none;
  font-family: "Press Start 2P", cursive;
  font-size: 1.2rem;
  cursor: pointer;
}

The card component

Let’s first build the card component so that we can use it in the game’s grid.

The card component has a back and a front.

The component receives a value to hide, a flipStatus (whether it’s DEFAULT, FLIPPED or MATCHED), and onClick listener to control the click on the card.
The front of the card is by default a question mark to show that the card is hiding something.
The back has the hidden value.

// src/components/card/index.js

import style from "./style.css";

export default function Card({ hiddenValue, flipStatus, onClick }) {
  return (
    <div class={style.card} data-flipStatus={flipStatus}>
      <button class={style.front} onClick={onClick}>
        ?
      </button>
      <div class={style.back}>{hiddenValue}</div>
    </div>
  );
}

/* src/components/card/style.css */

.card {
  position: relative;
  transition: 0.3s;
  transform-style: preserve-3d;
}

.card .front,
.card .back {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  display: flex;
  align-items: center;
  justify-content: center;
  border-radius: 6px;
  font-size: 3rem;
  backface-visibility: hidden;
  border: 1px solid #864601;

  /* box shadow */
  box-shadow: 0px 6px 5px 0px #864601;
  -webkit-box-shadow: 0px 6px 5px 0px #864601;
  -moz-box-shadow: 0px 6px 5px 0px #864601;
}

.card .front {
  background: #e7a61a;
  color: #864601;
  z-index: 2;
  transform: rotateY(0deg);
}

.card .back {
  background: white;
}

.card[data-flipStatus="FLIPPED"],
.card[data-flipStatus="MATCHED"],
.back {
  transform: rotateY(180deg);
}

.card[data-flipStatus="MATCHED"] .back {
  opacity: 0.2;
  border: 3px dashed red;
}

Note: The CSS flip animation is inspired from here. The link is a really good source if you’re curious about how it works.

The final result looks like this:

The game page

Every time we start a game, we should shuffle the positions of our cards. Moreover, every card should have a unique key to identify it in the grid and an emoji value. To do so, we can create a shuffling function in the App component and pass down its resulting cards to the Game route:

// src/components/app.js

import { Component } from "preact";
import { Router } from "preact-router";

import Home from "../routes/home";
import Game from "../routes/game";
import Win from "../routes/win";

/**
 * helper function to generate a schuffled array of cards
 */
function generateGridCards() {
  const emojis = ["🚀", "😺", "🐶", "🏈", "📦", "🙊"];

  return [...emojis, ...emojis]
    .sort(() => Math.random() - Math.random())
    .map((emoji, idx) => ({ key: idx, emoji }));
}

export default class App extends Component {
  render() {
    return (
      <div id="app">
        <Router onChange={this.handleRoute}>
          <Home path="/" />
          <Game path="/game" cards={generateGridCards()} />
          <Win path="/win" />
        </Router>
      </div>
    );
  }
}

Note: the schuffling function generateGridCards by creating an array that has two duplications of the emojis array, sorting the array randomly, and then mapping each emoji to a card object containing a unique key (the index) and the emoji value.

We can represent the game’s state in a way that reflects exactly the requirements we discussed in the first section:

state.flippedCards = { first: {}, second: {} } : only 2 cards can be flipped at the same time before deciding whether the player has a match or not. Thus, state.flippedCards contains the currently first and second flipped cards.
state.isMatched = {} : is a map of emojis that were matched. Whenever the player matches a pair of cards, the corresponding emoji is set to true in this object. This helps us determine which cards were watched when rendering.
state.score = 0 : the score of the user, which is 0 initially.
To get a card’s flip status (‘DEFAULT’, ‘FLIPPED’, or ‘MATCHED’), we can do so based on state.flippedCards and state.isMatched objects:
If the card is one of the state.flippedCards, then the card is actually flipped.
If the card’s emoji is in the isMatched map, then the card is matched.
Otherwise, the card is just in its default flip status.

When the player flips a card, the following can be done:

If it’s the first flipped card, then we simply set it in the state.flippedCards
If it’s the second flipped card, then we simply set it in the state.flippedCards and check whether we got a match or not.
In case of a mismatch, we simply flip back the cards by resetting the state.flippedCards to its default value.
In case of a match, we wait 500 ms and then add the emoji of the card to the state.isMatched map (so that the user has enough time to see which cards are flipped before the match). We also increment the score and redirect the player to the winning page in case they reached the maximum score.

// src/routes/game/index.js

import { Component } from "preact";
import { route } from "preact-router";

import Card from "../../components/card";
import style from "./style";

export default class Game extends Component {
  state = {
    flippedCards: { first: {}, second: {} },
    isMatched: {},
    score: 0,
  };

  getCardFlipStatus = ({ key, emoji }) => {
    const { flippedCards, isMatched } = this.state;

    if (isMatched[emoji]) {
      return "MATCHED";
    }

    if ([flippedCards.first.key, flippedCards.second.key].includes(key)) {
      return "FLIPPED";
    }

    return "DEFAULT";
  };

  createCardClickListener = (card) => () => {
    this.flipCard(card);
  };

  flipCard = (card) => {
    const { flippedCards } = this.state;

    // if it's the first card to be flipped, we don't need
    // to worry about anything else
    const isFirstFlippedCard = Object.keys(flippedCards.first).length === 0;
    if (isFirstFlippedCard) {
      return this.setState({ flippedCards: { ...flippedCards, first: card } });
    }

    this.flipSecondCard(card);
  };

  flipSecondCard = (card) => {
    const { flippedCards, isMatched, score } = this.state;

    // Flip the second and then check after 500 ms whether it's a match
    // or mismatch and handle it
    this.setState({ flippedCards: { ...flippedCards, second: card } });
    setTimeout(() => {
      if (flippedCards.first.emoji === card.emoji) {
        // it's a match
        this.setState({
          score: score + 1,
          isMatched: { ...isMatched, [card.emoji]: true },
        });
        if (score === 5) {
          this.handleWin();
        }
      }

      // it's a mismatch, so flip the cards back
      this.setState({ flippedCards: { first: {}, second: {} } });
    }, 500);
  };

  handleWin = () => {
    setTimeout(() => {
      route("/win");
    }, 500);
  };

  render(props, state) {
    return (
      <div class={style.game}>
        <header class={style.score}>Score: {state.score}</header>
        <div class={style.grid}>
          {props.cards.map((card) => (
            <Card
              hiddenValue={card.emoji}
              flipStatus={this.getCardFlipStatus(card)}
              disabled={false}
              onClick={this.createCardClickListener(card)}
            />
          ))}
        </div>
      </div>
    );
  }
}

When it comes to styling the game’s grid, we have THE perfect case for CSS grid.

/* src/routes/game/style.css */

.game {
  position: absolute;
  top: 0;
  bottom: 0;
  left: 0;
  right: 0;
  width: 100%;
  height: 100%;
  display: flex;
  flex-direction: column;
  justify-content: space-between;
  align-items: center;
  padding-top: 15px;
  max-height: 568px;
}

.score {
  text-align: center;
  font-size: 2rem;
  position: relative;
  top: 30px;
}

.body {
  display: flex;
  align-items: center;
  flex-direction: column;
  width: 100%;
  height: 100%;
}

.grid {
  display: grid;
  grid-template-columns: repeat(3, 90px);
  grid-template-rows: repeat(4, 90px);
  grid-gap: 10px;
  position: absolute;
  bottom: 10px;
}

And… that’s it! The game should be complete by now! 👻

Final touches

To do so, we first need to generate icons for Android and iOS. To keep things simple, we can choose our Card component to be the icon of the game.

Once we have a screenshot of the Card component, we can use a tool like this to generate the different sizes of icons and place them in the assets/icons directory.

For iOS, we need to add special link tags pointing the apple-touch-icon . In order to achieve that, we can create a template index.html in the src directory that has the required link tags. The following template is basically the default template of preact-cli with our link tags added to it:

<!-- src/index.html -->

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title><%= htmlWebpackPlugin.options.title %></title>
    <meta name="viewport" content="width=device-width,initial-scale=1" />
    <meta name="mobile-web-app-capable" content="yes" />
    <meta name="apple-mobile-web-app-capable" content="yes" />
    <link
      rel="apple-touch-icon"
      href="<%= htmlWebpackPlugin.files.publicPath %>assets/icons/apple-touch-icon.png"
    />
    <link
      rel="apple-touch-icon"
      sizes="57x57"
      href="<%= htmlWebpackPlugin.files.publicPath %>assets/icons/apple-touch-icon-57x57.png"
    />
    <link
      rel="apple-touch-icon"
      sizes="72x72"
      href="<%= htmlWebpackPlugin.files.publicPath %>assets/icons/apple-touch-icon-72x72.png"
    />
    <link
      rel="apple-touch-icon"
      sizes="76x76"
      href="<%= htmlWebpackPlugin.files.publicPath %>assets/icons/apple-touch-icon-76x76.png"
    />
    <link
      rel="apple-touch-icon"
      sizes="114x114"
      href="<%= htmlWebpackPlugin.files.publicPath %>assets/icons/apple-touch-icon-114x114.png"
    />
    <link
      rel="apple-touch-icon"
      sizes="120x120"
      href="<%= htmlWebpackPlugin.files.publicPath %>assets/icons/apple-touch-icon-120x120.png"
    />
    <link
      rel="apple-touch-icon"
      sizes="144x144"
      href="<%= htmlWebpackPlugin.files.publicPath %>assets/icons/apple-touch-icon-144x144.png"
    />
    <link
      rel="apple-touch-icon"
      sizes="152x152"
      href="<%= htmlWebpackPlugin.files.publicPath %>assets/icons/apple-touch-icon-152x152.png"
    />
    <link
      rel="apple-touch-icon"
      sizes="180x180"
      href="<%= htmlWebpackPlugin.files.publicPath %>assets/icons/apple-touch-icon-180x180.png"
    />
    <link
      rel="manifest"
      href="<%= htmlWebpackPlugin.files.publicPath %>manifest.json"
    />
    <% if (htmlWebpackPlugin.options.manifest.theme_color) { %>
    <meta
      name="theme-color"
      content="<%= htmlWebpackPlugin.options.manifest.theme_color %>"
    />
    <% } %> <% for (var chunk of webpack.chunks) { %> <% if (chunk.names.length
    === 1 && chunk.names[0] === 'polyfills') continue; %> <% for (var file of
    chunk.files) { %> <% if (htmlWebpackPlugin.options.preload &&
    file.match(/\.(js|css)$/)) { %>
    <link
      rel="preload"
      href="<%= htmlWebpackPlugin.files.publicPath + file %>"
      as="<%= file.match(/\.css$/)?'style':'script' %>"
    />
    <% } else if (file.match(/manifest\.json$/)) { %>
    <link
      rel="manifest"
      href="<%= htmlWebpackPlugin.files.publicPath + file %>"
    />
    <% } %> <% } %> <% } %>
  </head>
  <body>
    <%= htmlWebpackPlugin.options.ssr({ url: '/' }) %>
    <script
      defer
      src="<%= htmlWebpackPlugin.files.chunks['bundle'].entry %>"
    ></script>
    <script>
      window.fetch ||
        document.write(
          '<script src="<%= htmlWebpackPlugin.files.chunks["polyfills"].entry %>"><\/script>'
        );
    </script>
  </body>
</html>

We can then modify our production NPM scripts in order to use the template:

"scripts": {
    "build": "preact build --template src/index.html",
    "serve": "npm run build && preact serve"
}

We also need to modify the src/manifest.json file in order to reflect our Android icons and game’s title:

{
  "name": "Match Game",
  "short_name": "Match Game",
  "start_url": "/",
  "display": "standalone",
  "orientation": "portrait",
  "background_color": "#fff",
  "theme_color": "#fff",
  "icons": [
    {
      "src": "/assets/icons/android-chrome-192x192.png",
      "type": "image/png",
      "sizes": "192x192"
    },
    {
      "src": "/assets/icons/android-chrome-256x256.png",
      "type": "image/png",
      "sizes": "512x512"
    }
  ]
}

We created a beast!

It’s time to evaluate our game based on the requirements we set at the beginning.

To build the game, we can use the build NPM script:

npm run build

The game‘s build result should be available in the /build directory. We can then easily deploy and host the build directory somewhere like ▲now.

Let’s then finally take a look at our game’s functional requirements and PWA checklist and see what we have achieved:

✅ The game’s functional requirements are met.
✅ The game is served over HTTPS: this is supported out of the box by preact-cli.
✅ All pages are responsive on tablets and mobile devices.
✅ The game can be added to the home screen of the user’s device and look like a native app.
✅ Offline Loading: The game can be totally functional offline! Once you add the game to the home screen, you can play it anytime without the need for Internet connection.
✅ Page transitions don’t feel like they block on the network: we literally have instant page transitions
✅ Each page has a URL: this was met by having a route for each page.

Running Google’s Lighthouse tool gives the following:

Results of running Lighthouse tool on the deployed game

Contact

hi@tinloof.com