
High velocity mobile development requires us to adopt continuous integration workflows. The most difficult part of automated testing on mobile is the tip of the testing pyramid, the **E2E (end to end) tests**.

E2E tests, when carried out manually, are **very time consuming and repeatedly boring**. Sometimes they can also be **non-deterministic**, depending on asynchronous operations that might take place in a different order inside your app. This is also known as flakiness. Another difficulty is, there are not many options for automated E2E tests using React Native.

In this post I will introduce [Detox](https://github.com/wix/Detox) as a tool for end-to-end testing for React Native. Detox helps us reduce our reliance on manual QA.

Detox tests your mobile app while it's running in a real device/simulator, interacting with it just like a real user.

Detox philosophy promotes gray box testing instead of black box testing:

- **Black Box Testing:** Software Testing technique in which the tester doesn’t know the internal structure, design and implementation of the software application that is being tested.
- **Gray Box Testing:** Software testing technique which is a combination of Black Box Testing technique and White Box Testing technique. The internal structure, design and implementation is partially known in Gray Box Testing.

Theoretically, it sounds better to test exactly what you ship as a black box. In practice, switching to gray box allows the test framework to monitor the app from the inside and delivers critical wins like fighting flakiness at the core.

Detox is built from the ground up to support React Native projects as well as pure native ones. It currently supports React Native versions <=0.64.

## Installation

The whole Detox setup is described in this link:

https://github.com/wix/Detox/blob/master/docs/Introduction.GettingStarted.md

We will go through the main steps that a developer should take to use Detox, in order to create and run the test descriptions. It can also configured to be used as part of the CI pipeline.

**Detox CLI** needs to be installed globally:

```sh
# Install detox globally
npm install -g detox-cli
```

Some libraries need to be added in `package.json` of our React Native app.

- Adding `detox` as a development dependency
- Adding or upgrading `jest` to jest@^27.0.0

```sh
# Add detox as dev dependency
yarn add detox --dev

# Upgrade jest
yarn add jest@^27.0.0 --dev
```

Then run the automated init script:

```
# Init detox
detox init -r jest
```

That script creates several files:

- A `.detoxrc.json` file.**(\*)**
- An `e2e/` folder in your project root
- An `e2e/config.json` file
- An `e2e/environment.js` file
- An `e2e/firstTest.e2e.js` file

**(\*) NOTE** The `build` and `binaryPath` for both iOS and Android apps in this file are not set.

Some parameters in `.detoxrc.json` need to be added or modified. Particularly the `build` and `binaryPath` properties are missing or filled with placeholders, and also the `avdName` and `testBinaryPath` in Android. These values work on iOS (they kind of work for Android but at the time of writing this article there are some issues that prevent it working):

```json
{
  "testRunner": "jest",
  "runnerConfig": "e2e/config.json",
  "skipLegacyWorkersInjection": true,
  "apps": {
    "ios": {
      "build": "xcodebuild -workspace ios/pushdemo.xcworkspace -scheme pushdemo -configuration Debug -sdk iphonesimulator -derivedDataPath ios/build",
      "type": "ios.app",
      "binaryPath": "ios/build/Build/Products/Debug-iphonesimulator/pushdemo.app"
    },
    "android": {
      "build": "cd android && ./gradlew assembleAndroidTest -DTestBuildType=debug && cd ..",
      "type": "android.apk",
      "binaryPath": "android/app/build/outputs/apk/debug/app-debug.apk",
      "testBinaryPath": "android/app/build/outputs/apk/androidTest/debug/app-debug-androidTest.apk"
    }
  },
  "devices": {
    "simulator": {
      "type": "ios.simulator",
      "device": {
        "type": "iPhone 11"
      }
    },
    "emulator": {
      "type": "android.emulator",
      "device": {
        "avdName": "Pixel_3a_API_30_x86"
      }
    }
  },
  "configurations": {
    "ios": {
      "device": "simulator",
      "app": "ios"
    },
    "android": {
      "device": "emulator",
      "app": "android"
    }
  }
```

### Android specific steps

Please follow this link in order to check that a proper environment with Java, Android SDK and AOSP emulators is available:

https://github.com/wix/Detox/blob/master/docs/Introduction.AndroidDevEnv.md

Android has currently some issues. The detox build works but the detox test does not. There are many open issues in the Detox project regarding Android so we will probably have to wait to see that working with the current version.

On the other hand, I was able to download the React Native example from Detox and run the Android tests. I couldn’t translate the exact steps needed to work on my sample project, nor I found those steps in the documentation, but I guess that could be achieved putting more work on it.

### iOS specific steps

Please follow this link in order to check that a proper environment with XCode command line tools and simulator utils is available:

https://github.com/wix/Detox/blob/master/docs/Introduction.iOSDevEnv.md

## Building and running tests

When using Detox with Jest as test runner, the tests are very similar to unit tests. We should configure them to have different extension than unit tests, i.e. `*.e2e.js` and `*.e2e.ts` would be a good choice.

Detox tests use a `testID` field in JSX templates to match a certain element by ID. For instance, we can write a test like this to assert that a certain View or text are shown.

```javascript
it('should show a title and a description', async () => {
  await expect(element(by.id('title'))).toBeVisible();
  await expect(element(by.id('description'))).toBeVisible();
});
```

Then the JSX should just include those `testID` attributes, just like this:

```javascript
<View>
  <View>
    <Text testID="title">E2E testing with Detox</Text>
    <Text testID="description">
      This app is testeable with Detox. Push the button to display a greeting
      message.
    </Text>
    {isMessageVisible && <Text testID="message">Hello world!</Text>}
  </View>

  <View>
    <Button testID="message_button" title="Say Hello" onPress={buttonHandler} />
  </View>
</View>
```

The test spec can trigger buttons, write text inside of input fields and so on. For instance, the following test asserts that a text appears on a container after clicking a button.

```javascript
it('should show a hello world message after tapping the button', async () => {
  await element(by.id('message_button')).tap();
  await expect(element(by.id('message'))).toBeVisible();
  await expect(element(by.text('Hello world!'))).toBeVisible();
});
```

To run the tests, we must build the tests with Detox and then run them. These commands can also be included in `package.json` for easier use with `npm` or `yarn`.

```sh
# build and test for ios
detox build -c ios
detox test -c ios

# build and test for android
detox build -c android
detox test -c android
```

After running the test, we get a list of passing or failing tests, as usual with jest test runner.

```sh
  App
    ✓ should show a title and a description (1029 ms)
    ✓ should show a hello world message after tapping the button (1377 ms)

  2 passing
```

This is how the E2E test runs on a simulator:

![E2E test run](/img/blog/2021-10-31_e2e-testing-in-rn-with-detox/detox_e2e_test.gif)

You can find the code for this post in:

https://github.com/jguix/detox-demo

## More on React Native testing

During the work on this post I found helpful the information contained in this site, besides the official Detox documentation:

https://reactnativetesting.io/e2e/intro.html

They cover unit tests, component tests, end to end tests and continuous integration for React Native projects, and the documentation is quite straightforward and fills some of the gaps of the Detox docs.

## Credits

Photo by [Joshua Mayo](https://unsplash.com/@mayofi) on [Unsplash](https://unsplash.com).


In this post I will introduce Detox as a tool for end-to-end testing for React Native. Detox helps us reduce our reliance on manual QA.

End-to-end testing in React Native with Detox


Today I am starting a new project. I will call it for now _"No Más Colas"_ -Spanish translation for _"No More Queues"_- but I might have second thoughts about that once I do some UX research.

The aim of the project is **putting into practice what I learned** in some Udemy tutorials that I recently completed, or I'm about to finish, devoted to NextJS and Flutter. I'm also trying **to come out with a solution for rapid prototyping apps**, creating MVPs that are simple but still scalable. And finally, I think I can **help others in the process**. Perhaps people that are already competent in JavaScript can follow my steps to create a different app, or even help me when I get stuck on something.

I'll blog about the process to help me reflect on those things I learned. I believe that **practice is completely necessary to actually learn stuff**. Thus, I'm not usually happy with watching the videos, but I also follow the steps myself. I consider that to be _"practice level 101"_, so to speak. The next level comes when you **try something different applying what you learned**. And if you are able to **summarize, sinthesize, write about the topic or teach other people**, then you get to learn the stuff deeper.

Someone might have instantly kringed when I said that my technical stack for this project will be NextJS + Flutter. If you are going to use React, why not using React Native for mobile, or why not creating a PWA? Or the other way around, why not creating everything in Flutter + Flutter web?

Truth is, I have had enough of pain with React Native, and I want to try something new. Hopefully, Flutter provides better developer experience -for the time I have been trying it, it does- and gives me enough to create a simple project. I don't want to use PWA because I want my app to live in the app stores. On the other hand, I don't trust much Flutter web for now. I don't know about it being used in production sites, and I wouldn't recommend my clients to use it, so for now I will leave it out of the equation.

That's the _why_, but the _what_ is still missing. **I'm going to create a website and a mobile app to manage queues**, not message queues or event queues, but **real life queues with people in a line**. Basically, the app will allow someone to put into place a queue system, where the user can get information through the app on how many people are before him, the estimated waiting time, and notifications when his turn comes close.

I think this can solve a problem that existed for a long time, but even got worse after COVID. **We never liked to wait long in a line**. Now, with COVID, **it's not even safe to do that**. Having a bunch of people in a closed space for a long time is no longer desirable, and whe might have restrictions or quotes for that. With this app, a user can pick his turn -something that could be even accomplished remotely- and then, if the estimated time is long, he can just go shopping for a while, wait home or have a coffee somewhere, while the queue advances.

The website will handle the backoffice for queue system and a frontend site to display in the place, where the users will be able to see on site the next queue IDs that will be served, and where they can get their queue ID.

The mobile app will be responsible to read this ID and inform the user about his position in the queue and estimated times.

**In the next post I will create the NextJS app with typescript support**. Stay tuned and see this app grow.

## Credits

Photo by [Zichao Zhang](https://unsplash.com/@shakusky) on [Unsplash](https://unsplash.com).


Today I am starting a new project. I will call it for now "No Más Colas" -Spanish translation for "No More Queues"- but I might have second thoughts about that once I do some UX research.

"No Más Colas" kick off


In this post I will present some tricks that I learned creating demo sites for blog posts and PoCs. You will learn how to configure a JSON-server API and deploy it on the same Heroku site than the frontend app. You will also learn how to use Faker to generate fake data for your JSON server.

Many times I have used [JSON-server](https://github.com/typicode/json-server) to quickly create a simple API as a backend for a simple demo or proof of concept. Don't make me wrong: I'm not encouraging anyone to use that as a production server, but just for those kind of small projects.

JSON server provides a full REST API from a single `db.json` file, including `GET`, `POST`, `PUT`, `PATCH` and `DELETE` routes to get and modify your entities.

In this scenario I usually find two problems:

1. Having enough data. If you create the JSON data manually, you will easily get tired after creating 10 entities. Imagine if you need hundreds of entities with different models.

2. Serving the data. If you want to deploy your demo on Heroku, you need a site to hold your application and a second one to hold the API.

Regarding the first problem, we will use Faker to programatically create the `db.json` file. This will also simplify modifying the models, i.e., if the model changes, we don't need to manually change several hundreds of entities.

As for the second, we will use `concurrently` to launch both the frontend and backend apps in different ports, and we will add specific configurations for Heroku.

## App initialization

For this post we will generate a sample react app. We could make similar configurations with other Javascript frameworks.

Let's create a new typescript react app:

```bash
npx create-react-app json-server-demo --template typescript
```

Let's add `json-server`, `concurrently` and `axios` as dependencies, and `faker` as dev dependency of the project:

```bash
yarn
yarn add json-server concurrently axios
yarn add --dev faker
```

Let's test our sample app:

```bash
yarn start
```

Open your browser at http://localhost:3000/ and the sample React app will show.

## Creating the API

Our sample app will list employees, with their name, email and country location.

We will create the `db.json` file with `faker` with not less than 1000 employees, because we think big 😏

Create a file in the folder `src/db/index.json` with the following contents:

```javascript
var fs = require('fs');
var faker = require('faker/locale/es');
faker.locale = 'es';

let employees = [];

for (let i = 1; i <= 1000; i++) {
  const firstName = faker.name.firstName();
  const lastName = faker.name.lastName();
  employees.push({
    address: `${faker.address.streetAddress()}, ${faker.address.zipCode()}, ${faker.address.city()}, ${faker.address.country()}`,
    email: faker.internet.email(firstName, lastName),
    id: i,
    name: faker.name.findName(firstName, lastName),
  });
}

const data = {
  employees,
};

fs.writeFile('src/db/db.json', JSON.stringify(data, null, 2), (err) => {
  if (err) return console.log(err);
  console.log('Created database at src/db/db.json');
});
```

The code is easily readable, this script will create a `src/db/db.json` file with 1000 employes, using random `name`, `address` and `email` for each employee. The locale used is `"es"`; this means that the names and emails will be created in Spanish. Pay attention how the `name` and `email` fields are created using the same `firstName` and `lastName`, so they will be coherent.

Now we'll add the following script to the `"scripts"` section in the `package.json`:

```json
  "create-db": "node src/db/index.js",
```

To run the script, just execute:

```bash
yarn create-db
```

And we are all set up to create the `json-server` API with our brand new JSON database of employees.

We can test it right now from the command line. We will use the `--port` option to set it on port 3001, so that it doesn't clash with our react app already running on port 3000:

```bash
json-server src/db/db.json --port 3001
```

If you open http://localhost:3001/employees in your browser you will see the full list of employees.

```json
[
  {
    "address": "92349 Hurtado Ramal, 88648, Fuengirola Alejandrotown, Gabón",
    "email": "JosEmilio57@gmail.com",
    "id": 21,
    "name": "José Emilio Pizarro"
  },
  {
    "address": "536 Margarita Ronda, 45257, Las Vegas, Eslovenia",
    "email": "Dorotea_Ocasio72@hotmail.com",
    "id": 22,
    "name": "Dorotea Ocasio"
  },
  {
    "address": "69354 Candelaria Chalet, 17110, Archuletaburgh, Sri Lanka",
    "email": "Benjamn_Menchaca65@yahoo.com",
    "id": 23,
    "name": "Sta. Benjamín Menchaca"
  },
  ...
]
```

You can also test some URLs with params, like pagination or full text search:

http://localhost:3001/employees/1

http://localhost:3001/employees?\_page=3&\_limit=10

http://localhost:3001/employees?q=Pedro

## Consuming the API

We'll create a simple app that presents a search box and a list of results. We will ommit the CSS file contents, which just adds some styling to the application. You can find it on the repository listed at the end of this post.

```typescript
import React, { useEffect, useState } from 'react';
import axios from 'axios';
import './App.css';

type Employee = {
  address: string;
  email: string;
  id: number;
  name: string;
};

const App = () => {
  const [query, setQuery] = useState('');
  const [employees, setEmployees] = useState<Employee[]>([]);

  useEffect(() => {
    loadEmployees(1, 20);
  }, []);

  useEffect(() => {
    loadEmployees(1, 20, query.length > 2 ? query : '');
  }, [query]);

  const loadEmployees = async (page: number, limit: number, query = '') => {
    const url = `http://localhost:3001/employees?_page=${page}&_limit=${limit}&q=${query}`;
    const _employees = await axios
      .get<Employee[]>(url)
      .then(({ data }) => data);

    setEmployees(_employees);
  };

  return (
    <div className="App">
      <div className="search_form">
        <label className="search_form--label">Search employees</label>
        <input
          className="search_form--input"
          type="text"
          value={query}
          onChange={(event) => setQuery(event.target.value)}
        ></input>
      </div>
      <div className="employee_list">
        {employees.map((employee) => {
          return (
            <div className="employee_list--item">
              <div className="employee_list--item-name">{employee.name}</div>
              <div className="employee_list--item-address">
                {employee.address}
              </div>
              <div className="employee_list--item-email">{employee.email}</div>
            </div>
          );
        })}
      </div>
    </div>
  );
};

export default App;
```

This is how the app looks.

![Demo application](/img/blog/2021-07_deploy-demo-with-api-heroku/demo_app.png)

## Enhancing the development configuration

Let's make some changes to simplify the development cycle. We will add the `proxy` configuration to `package.json`, so that the network calls are redirected to port 3001.

```json
  "proxy": "http://localhost:3001",
```

This way, we can simplify the URL in our `App.tsx`:

```typescript
const url = `/employees?_page=${page}&_limit=${limit}&q=${query}`;
```

We can now restart the app and it will still work.

Then, we will use concurrently to start both the backend and the frontend from a oneliner script. Replace the `start` from `package.json` script with the following:

```json
    "start": "concurrently \"react-scripts start\" \"json-server --watch src/db/db.json --port 3001\"",
```

You can now stop the terminal running `json-server src/db/db.json --port 3001`. Just run from the project folder:

```bash
yarn start
```

And you are good to go.

## Deploying to Heroku

Making both the `json-server` and your app to run on the same instance of a service like Heroku is trickier. You usually would need two sites, one for the frontend and one for the backend.

We are going to benefit of the static site generation of `json-server`.

First of all, let's build our `react` application.

```bash
yarn build
```

This will generate a static version of the app in `/build`. Then remove this lines from `.gitignore` in order to push the static site to our remote repository:

```bash
# production
/build
```

Create the file `server.js` in the root of the project with the following contents:

```javascript
const jsonServer = require('json-server');
const server = jsonServer.create();
const router = jsonServer.router('src/db/db.json');
const middlewares = jsonServer.defaults({ static: './build' });
const port = process.env.PORT || 3000;

server.use(middlewares);
server.use(router);

server.listen(port);
```

If you stop the `yarn start` script and run this script locally, your app will run from the static files in the `/build` directory, served by `json-server`.

```bash
node server.js
```

This is exactly what Heroku will use to serve your application using a single site.

Now, to tell Heroku to call this `node server.js` you need to create a `Procfile` file in the root of your repository with the contents:

```
web: node server.js
```

And that is all the configuration that you need.

I will skip the part where you create a Heroku account, add a new app and connect it to your Github repository. You can find many tutorials about that out there.

You can find the code for this demo in the following link:

[https://github.com/jguix/json-server-demo](https://github.com/jguix/json-server-demo)

And the deployed Heroku app:

[https://json-server-demo1.herokuapp.com](https://json-server-demo1.herokuapp.com)

## Netlify and Vercel

Unfortunately we can not do the same on Netlify or Vercel. The reason is that these services don't let us run node commands, but instead you would need to create your API using serverless functions. You can of course host there your app and have the API on another service, but that was not the point of this article.

## Conclusion

I wanted to put together all the steps that I learned building and hosting simple apps for demo purposes including an API. This can probably help you performing the first steps of your next project, hosting a demo for a blog post or impressing some company in a technical interview.

## Credits

Photo by Austin Neill on [Unsplash](https://unsplash.com/@arstyy).


In this post I will present some tricks that I learned creating demo sites for blog posts and PoCs. You will learn how to configure a JSON-server API and deploy it on the same Heroku site than the frontend app. You will also learn how to use Faker to generate fake data for your JSON server.

Deploy a demo site with a JSON API on Heroku


This post shows how to use git hooks, to prevent commit or push under certain circumstances, and particularly how to version those git hooks.

Git hooks are a collection of triggers that are bound to git commands, like checkout, commit or push. They let you run a script before/after the git command is actually executed, and return an exit code. For git hooks that are exectued before, if the exit code is not zero, the git command will not be executed.

Git hooks must be used in a git versioned project, since they are just bash scripts living in your `.git/hooks` folder. There are both client side and server side hooks. In this post we will talk about client side hooks.

Client git hooks include:

- **Committing-Workflow Hooks.** These are hooks that have to do with the committing process: `pre-commit`, `prepare-commit-msg`, `commit-msg` and `post-commit`.

- **Email Workflow Hooks.** Used for an email-based workflow: `applypatch-msg`, `pre-applypatch` and `post-applypatch`.

- **Other Client Hooks.** They include: `pre-rebase`, `post-rewrite`, `post-checkout`, `post-merge`, `pre-push`

I won't enter into details about what is the use of each hook. You can find more info on each individual hook purpose and triggering scenario on [Customizing-Git-Hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks).

I will just mention an example. Some projects require by convention that the commit message includes a JIRA task name, so that the team members can easily track what commits were bound to which tasks in JIRA. If your JIRA task names include all a prefix like `PROJ`, that can be achieved with a `pre-commit` hook like this one:

```sh
#!/bin/bash
MSG="$1"

if ! grep -qE "PROJ" "$MSG";then
    cat "$MSG"
    echo "Your commit message must contain the task name starting with 'PROJ'"
    exit 1
fi
```

The script above returns a `1` if the commit message doesn't include the word `PROJ` in it, and that will prevent the commit to run. If the commit message includes it, like in `"PROJ-202 - Refactored CSS styles"`, then the commit will take place.

You may be wondering, _"ok, but how can I actually store the hooks in my git versioned project if they sit inside the `.git` folder"_, and that is actually impossible. You can not commit files inside that directory. You would need to tell each developer in your project to copy them, or have a script that copies the hooks, then tell everyone to run it. Not practical, uh?

## Versioning git hooks in Javascript projects

In Javascript projects with a `package.json` we can use [Husky](https://typicode.github.io/husky) to take care of git hooks and their versioning inside the project.

First of all, we must install Husky in the project:

```sh
npx husky-init && yarn
```

This will add a couple of things in `package.json`:

- the husky dependency to our `devDependencies` section
- a `prepare` script to our `scripts` section

The `yarn` part will install the dependencies and execute the `prepare` script. After that, a `.husky` directory will be created in the root of the project which contains a sample `pre-commit` hook, a `.gitignore` file and a `_` folder with the `husky.sh` script.

With that configuration you don't need to manually copy your hooks to `.git/hooks` folder: the `husky.sh` script will take care of using the hooks sitting in the `.husky` folder.

You can now edit the sample `pre-commit` hook, delete it, or create new ones in the `.husky` folder, manually or via the bash `npx husky add` command. For instance, if we were to create a `pre-push` hook that runs `lint` and `test` we could just run:

```sh
npx husky add .husky/pre-push "yarn lint && yarn test"
```

The result will be something like:

```sh
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

yarn lint && yarn test

```

## Versioning hooks in Maven Java projects

Now for Java projects managed by Maven with a `pom.xml` file, I couldn't find anything like Husky.

The best approach here was using the `maven-resources-plugin` to copy the hooks from a `git-hooks` source directory to the `.git/hooks` destination folder.

This is what I added to my `build` section in the `pom.xml`:

```xml
<build>
  <plugins>
    <plugin>
      <artifactId>maven-resources-plugin</artifactId>
      <version>3.2.0</version>
      <executions>
        <execution>
          <id>copy-hooks</id>
          <phase>validate</phase>
          <goals>
            <goal>copy-resources</goal>
          </goals>
          <configuration>
            <outputDirectory>${basedir}/.git/hooks</outputDirectory>
            <resources>
              <resource>
                <directory>git-hooks</directory>
              </resource>
            </resources>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>
```

After that, calling the command `mvn validate` or any other maven command that calls `validate`, like `package`, will install the hooks in the first place.

## Bypassing git hooks

What if we have a git hook that takes a lot of time to execute and gets into our way for everyday programming tasks? For instance, if we had a `pre-commit` hook that launched our unit tests and those tests took 30 minutes to run, then everytime we committed we would have to wait that much long. We might want to just run the tests on the last commit before the push, and not on every commit, to save us some time.

On such cases, we can bypass the git hooks, if we know what we are doing:

```sh
git commit --no-verify -m "An unverifed commit"
```

## Conclussion

I hope this post helps you to integrate git hooks in your projects. They can help you enforce some policies and guidelines to improve quality standards on your team.

## Credits

Photo by Anne Nygard on [Unsplash](https://unsplash.com/).


This post shows how to use git hooks, to prevent commit or push under certain circumstances, and particularly how to version those git hooks.

Adding git hooks

In this series of posts we will create an application using react and redux, in which we will handle relational data. In this second part we will be implementing the store.

Using redux with relational data (2/3)


## Part 1. Modelling the redux store

In this series of posts we will create an application using **react** and **redux**, in which we will handle relational data. In this first part we will be modelling the store.

Often the redux tutorials are too simple and handle a flat data structure. This is the case of the typical TODO app (to-do list), or a shopping list, etc. In these cases we usually manage a few reducers, which are independent of each other.

For example:

- The list of TODOs, including the status of each task.
- The value of a show/hide filter, for example "hide complete".
- The value of a sort filter, for example "sort by ascending creation date".

In such a simple case, the store doesn't need to handle relationships, and it can be rendered in an object similar to the following:

```json
{
  "todos": [
    {
      "id": 1,
      "completed": true,
      "creationDate": "2020-08-07",
      "description": "Create github repo"
    },
    {
      "id": 2,
      "completed": false,
      "creationDate": "2020-08-11",
      "description": "Finish part 1 of this post"
    },
    {
      "id": 3,
      "completed": false,
      "creationDate": "2020-08-12",
      "description": "Create part 2"
    }
  ],
  "filterBy": "completed",
  "orderBy": "date-asc"
}
```

However, real applications are usually more complex. Some data is dependent on others, and there are hierarchies: one-to-one, one-to-many, and many-to-many relationships. This will present us with several challenges, both in the representation of the state in the store, and in the efficiency of communication with the backend.

To illustrate that, we will use the example of a social network. The main entities that we will handle are users, posts and comments. Users can create posts, and posts can contain comments from other users. Simple, isn't it?

In order to model this data, let's look first at some of the designs of our social network.

The home page of our social network will be **My Wall**, the page where my posts and those of all my friends are shown, with their respective comments.

![My Wall](/img/blog/2020-08_redux-normalized-store-part-1/my_wall.png)

There will also be a **Friends** page, where the users who are direct contacts of mine are listed.

![My Friends](/img/blog/2020-08_redux-normalized-store-part-1/my_friends.png)

From this page, if I click on one of my friends, I will visit the **Friend's wall**, that is, a page where their posts will appear, along with the comments of other users.

![Friend Page](/img/blog/2020-08_redux-normalized-store-part-1/friend.png)

Each post will include the avatar and name of the user, and the date. Each comment will also include the avatar, username and date.

![Posts and comments](/img/blog/2020-08_redux-normalized-store-part-1/post_and_comments.png)

Without going into the relationships or hierarchies, we can define the types of the entities as user (`User`), post (`Post`) and comment (`Comment`):

```typescript
// user.types.ts
export type User = {
  avatar: string;
  email: string;
  id: number;
  name: string;
};

// post.types.ts
export type Post = {
  body: string;
  date: Date;
  id: number;
};

// comment.types.ts
export type Comment = {
  body: string;
  date: Date;
  id: number;
};
```

An extremely simple representation, based on the TODO application, consists of having a reducer dedicated to each type of entity:

```json
{
  users: [
    { id: 1, name: "Josh", email: "josh@gmail.com", avatar: "josh.jpg" },
    { id: 2, name: "Anne", email: "anne@gmail.com", avatar: "anne.jpg" },
    { id: 3, name: "Mike", email: "mike@gmail.com", avatar: "mike.jpg" },
  ],
  posts: [
    {
      id: 1,
      body: "hi all",
      date: "2020-08-01",
      user: { id: 2, name: "Anne", email: "anne@gmail.com", avatar: "anne.jpg" },
    }
  ],
  comments: [
    {
      {
        id: 1,
        body: "hello!",
        date: "2020-08-02",
        user: { id: 1, name: "Josh", email: "josh@gmail.com", avatar: "josh.jpg" },
      },
      {
        id: 2,
        body: "hi there!",
        date: "2020-08-02",
        user: { id: 3, name: "Mike", email: "mike@gmail.com", avatar: "mike.jpg" },
      },
    }
  ],
}
```

If I visit the **Friends** page, the store holds the friends in `users`; if I enter a friend's page the store holds the posts in `posts`, and if I show a post, the comments are stored in `comments`.

This strategy will force me to retrieve all the posts from the backend every time I switch to the wall of a different friend. Moreover, it won't work as expected, because on the **Friend** and **My wall** pages I need to show several posts at the same time, where each post has different comments. According to the store designed above, all the posts displayed would always show the same comments.

To avoid this problem we could nest the comments within the posts, like this:

```json
{
  users: [
    { id: 1, name: "Josh", email: "josh@gmail.com", avatar: "josh.jpg" },
    { id: 2, name: "Anne", email: "anne@gmail.com", avatar: "anne.jpg" },
    { id: 3, name: "Mike", email: "mike@gmail.com", avatar: "mike.jpg" },
  ],
  posts: [
    {
      id: 1,
      body: "hi all",
      date: "2020-08-01",
      user: { id: 2, name: "Anne", email: "anne@gmail.com", avatar: "anne.jpg" },
      comments: [
        {
          {
            id: 1,
            body: "hello!",
            date: "2020-08-02",
            user: { id: 1, name: "Josh", email: "josh@gmail.com", avatar: "josh.jpg" },
          },
          {
            id: 2,
            body: "hi there!",
            date: "2020-08-02",
            user: { id: 3, name: "Mike", email: "mike@gmail.com", avatar: "mike.jpg" },
          },
        }
      ],
    }
  ],
}
```

However, we still have several problems. We are not caching any data, for instance, if I navigate from one friend to another and go back to the first one, I will have to reload all the posts and comments from the backend. There is also a lot of replicated data, such as users, taking up more space than necessary.

Ideally, you should normalize the store, as recommended in the [redux documentation](https://redux.js.org/recipes/structuring-reducers/normalizing-state-shape). We could think something like this, where to each entity we have added one or several ids (`userId`, `postId`) that point to the entities with which it is related:

```json
{
  users: [
    { id: 1, name: "Josh", email: "josh@gmail.com", avatar: "josh.jpg" },
    { id: 2, name: "Anne", email: "anne@gmail.com", avatar: "anne.jpg" },
    { id: 3, name: "Mike", email: "mike@gmail.com", avatar: "mike.jpg" },
  ],
  posts: [
    {
      id: 1,
      body: "hi all",
      date: "2020-08-01",
      userId: 2,
    }
  ],
  comments: [
    {
      {
        id: 1,
        body: "hello!",
        date: "2020-08-02",
        postId: 1,
        userId: 1,
      },
      {
        id: 2,
        body: "hi there!",
        date: "2020-08-02",
        postId: 1,
        userId: 3,
      },
    }
  ],
}
```

In this way we flatten the store and avoid replicated data. However, the search for the user id associated with each post or comment, and the search for all the comments associated with a post will not be optimal, since it will force us to go through all the users or comments and filter by id. When the store grows during a session, this process will become slower and slower and will impact the user experience.

We can improve this by indexing each data entity, as suggested in the redux documentation.

```json
{
  "users": {
    "byId": {
      "1": {
        "id": 1,
        "name": "Josh",
        "email": "josh@gmail.com",
        "avatar": "josh.jpg"
      },
      "2": {
        "id": 2,
        "name": "Anne",
        "email": "anne@gmail.com",
        "avatar": "anne.jpg"
      },
      "3": {
        "id": 3,
        "name": "Mike",
        "email": "mike@gmail.com",
        "avatar": "mike.jpg"
      }
    }
  },
  "posts": {
    "byId": {
      "1": {
        "id": 1,
        "body": "hi all",
        "date": "2020-08-01",
        "userId": 2
      }
    }
  },
  "comments": {
    "byId": {
      "1": {
        "id": 1,
        "body": "hello!",
        "date": "2020-08-02",
        "postId": 1,
        "userId": 1
      },
      "2": {
        "id": 2,
        "body": "hi there!",
        "date": "2020-08-02",
        "postId": 1,
        "userId": 3
      }
    }
  }
}
```

Now it is much easier and faster to search for the `user` associated with a `post` or a `comment`. However, it is still difficult to get the list of `posts` by `user`, or the list of `comments` by `post`. In fact, it is now more difficult and inefficient to filter this data.

We are going to create relational structures that tell us which posts belong to each user (one to many), and what comments belong to each post.

```json
{
  users: {
    byId: {
      1: { id: 1, name: "Josh", email: "josh@gmail.com", avatar: "josh.jpg" },
      2: { id: 2, name: "Anne", email: "anne@gmail.com", avatar: "anne.jpg" },
      3: { id: 3, name: "Mike", email: "mike@gmail.com", avatar: "mike.jpg" },
    },
    postIdsById: {
      2: [ 1 ],
    }
  },
  posts: {
    byId: {
      1: {
        id: 1,
        body: "hi all",
        date: "2020-08-01",
        userId: 2,
      }
    },
    commentIdsById: :{
      1:[ 1, 2],
    }
  },
  comments: {
    byId: {
      1: {
        id: 1,
        body: "hello!",
        date: "2020-08-02",
        postId: 1,
        userId: 1,
      },
      2: {
        id: 2,
        body: "hi there!",
        date: "2020-08-02",
        postId: 1,
        userId: 3,
      },
    }
  },
}
```

The meaning of the reducer `postIdsById` reads as _"the user with id 2 has the post with id 1"_. The reading of `commentIdsById` would be _"the post with id 1 has the comments with ids 1 and 2"_. Now we have everything indexed and the database structure is fully normalized.

We only lack structures that allow us to store the ids of the posts that will be visible on each wall, either the user's or the friends', as well as the ids of the users that should appear on the friends page. We will include on the friend page a filter to sort alphabetically in ascending or descending order.

To separate the structures that model entities that belong to the database from the structures that model elements of the user interface, we will create 2 higher-level reducers. One called `entities` where we will store **entities from the database**, and another called `ui` where we will store all the **elements of the user interface**.

This is finally the store model, which avoids data replication, facilitates the search thanks to indexing, and will allow us to cache the data already loaded, since the structures associated with the user interface only store ids, and any entity already downloaded from the backend will remain in the store until we clear the browser cache.

```json
{
  entities: {
    users: {
      byId: {
        1: { id: 1, name: "Josh", email: "josh@gmail.com", avatar: "josh.jpg" },
        2: { id: 2, name: "Anne", email: "anne@gmail.com", avatar: "anne.jpg" },
        3: { id: 3, name: "Mike", email: "mike@gmail.com", avatar: "mike.jpg" },
      },
      postIdsById: {
        2: [ 1 ],
      },
    },
    posts: {
      byId: {
        1: {
          id: 1,
          body: "hi all",
          date: "2020-08-01",
          userId: 2,
        },
      },
      commentIdsById: :{
        1: [ 1, 2 ],
      },
    },
    comments: {
      byId: {
        1: {
          id: 1,
          body: "hello!",
          date: "2020-08-02",
          postId: 1,
          userId: 1,
        },
        2: {
          id: 2,
          body: "hi there!",
          date: "2020-08-02",
          postId: 1,
          userId: 3,
        },
      },
    },
  },
  ui: {
    friends: {
      orderFilter: "asc",
      userIds: [ 2, 3 ],
    },
    friendWall: {
      postIdsById: {
        2: [ 1 ],
      },
    },
    wall: {
      postIds: [ 1 ],
    },
  },
}
```

In future posts we will go through the implementation of this store and the caching methods.

## Credits

Photo by [Jeremy Bishop](https://unsplash.com/@jeremybishop) on [Unsplash](https://unsplash.com/).


In this post, I will show you how to create a simple Chrome extension, using just JavaScript, HTML and CSS. I will also summarize all what a Chrome extension can do, and I will introduce how to create more complex extensions based on modern JavaScript frameworks like React, Angular or Vue.

Using redux with relational data (1/3)


In this post, I will show you how to create a simple [Chrome extension](https://chrome.google.com/webstore/category/extensions). I will also summarize what a Chrome extension can do, and I will introduce how to create more complex extensions based on modern JavaScript frameworks like React, Angular or Vue.

What is a Chrome extension? Google Chrome extensions are like small applications living in your browser, based on standard web technologies, such as HTML, CSS and JavaScript. They take advantage of some Chrome APIs, providing the foundations for building an app, like storage and messaging. Google Chrome extensions can interact with the web pages open in your browser tabs, but they are not really meant to. They can live on their own and provide any kind of functionality, separate from the browsing experience. You can build anything, from an agenda, to a pomodoro timer, to a web image scrapper. You can think of Chrome as the Electron platform, providing a basis for building JavaScript applications that can interact with the browsing experience.

Chrome extensions can stay dormant until some trigger awakes them, making some content or script to be injected, executed, or some popup shown. These scripts live in something called “Isolated Worlds” in relation with the web pages being browsed, which means that a Chrome extension can only share the DOM with a particular page, but not the script variables or functions. Chrome extensions can thus modify the DOM, inject additional CSS or JavaScript scripts which interact with the same DOM, but can not directly modify the original page CSS or JavaScript. On the other hand, the extensions can communicate with the page through messages, so you can create a page that gracefully interact with a Chrome extension.

## Extension capabilities

This is an incomplete summary of what an extension can do:

- **Show an icon**. The extension icon can be modified on runtime, or show a badge over it, with a colored background and a 4 letter text in it.
- **Show a popup**. Clicking on the extension icon can trigger a popup with content.
- **Show a secondary menu**. Right clicking on the extension icon can trigger a secondary menu.
- **Respond to shortcuts**. Keyboard shortcuts can be associated to extension actions (i.e. CTRL+SHIFT+V).
- **Respond to actions in the URL bar** (the so called omnibox). Text shortcuts can be used in the omnibox to trigger actions in the extension (i.e. “myext+<TAB>").
- **Respond to visiting some web page**. For instance, modifying the icon state or popup content.
  Modify the content of a web site. For instance, modifying the DOM by a content script or applying additional CSS files.
- **Have an Options page** for the extension configuration.
- **Replace the History page, Bookmarks page or New Tab page** of Google Chrome.
- **Exchanging messages** with a web site or with itself. A extension can use messaging to talk to some web page being browsed, or to communicate between parts of the extension itself.
- **Store information** in local storage, Chrome storage (storage which is synchronized across different devices where the user is logged in) or any storage native to JS, for instance sessionStorage.
- **Show notifications** as a toast.
- **Use several APIs provided by Google Chrome**.
- **Be free or paid**. When creating a paid extension, you can choose to use the Chrome store or your own payment means.

## The basics

The only mandatory file of a Chrome extension is the manifest. It has to be placed in the root directory, and it communicates the extension metadata, permissions and other files involved.

The manifest format has a lot of options, which can be ckecked in this page (https://developer.chrome.com/extensions/manifest), but we will focus on the most important ones. Let’s introduce the Cat detector extension manifest:​

```json
{
  "name": "Cat detector",
  "description": "Spots cats in the page you are browsing",
  "manifest_version": 2,
  "version": "1.0",
  "background": {
    "persistent": false,
    "scripts": ["background.js"]
  },
  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["content.js"]
    }
  ],
  "browser_action": {
    "default_popup": "popup.html"
  },
  "icons": {
    "16": "images/footprint-16.png",
    "32": "images/footprint-32.png",
    "48": "images/footprint-48.png",
    "128": "images/footprint-128.png"
  },
  "permissions": ["activeTab"]
}
```

The manifest declares some capabilities that will be used by the extension:

- It declares a background script. Background scripts can activate at any time, but don't have direct access to the tabs content.
- It declares a content script. Content scripts get injected in the same page that is being browsed and have access to the content. A matches expression is used to determine when the script is injected. In this case we chose `<all urls>`, meaning it will be injected in any web page.
- It declares a browser action, meaning a extension that is able to work independently of the current browsed page. If we wanted to create a extension that only activates when some conditions are met in the page you are browsing, we would use a "page action”. The reason we chose browser action is that cats can be seen almost everywhere on the internet. A second reason is that we want to display a badge over the extension icon, and that is only possible using a browser action.
- Inside the browser action, it declares a popup that will be open on clicking on the extension icon.
- It declares icons. The smaller ones used for the browser icon, depending on the display resolution, and the bigger ones used in the extensions menu of Chrome and the Chrome Store.

## Our sample extension

Now, getting to the point of this post. This page action uses a background script that, on page load, calls sends a message to the content script, which in turn counts the number of times the words “cat”, “kitten” or “kitty” appear in our page. After receiving a response, the background task displays a badge over the icon to communicate the number of kittens spot. On clicking on the extension icon, a popup will be shown showing a happy kitten image together with the counter.

Let’s present our extension file structure:

```
-audios
 |-meow_0.mp3
 |-meow_1.mp3
 |-meow_2.mp3
 |-meow_3.mp3
 |-meow_4.mp3
 |-meow_5.mp3
 |-meow_6.mp3
-images
 |-footprint-16.png
 |-footprint-32.png
 |-footprint-48.png
 |-footprint-128.png
-background.js
-content.js
-manifest.js
-popup.html
-popup.js
```

It includes the extension icons, some audio files, the manifest, the background script, the content script, and the popup html and js files.

This is how the background script looks like. Comments have been included to guide you through the important stuff:

```
const maxMeows = 6;

// The extension listens to the onUpdated event, and executes when the page is loaded
chrome.tabs.onUpdated.addListener((tabId, changeInfo, tab) => {
  if (changeInfo.status === "complete" && tab.active) {
    detectCats(tabId);
  }
});

// It executes the cat detection as well when we switch tabs on the active tab
chrome.tabs.onActivated.addListener((activeTab) => detectCats(activeTab.tabId));

const detectCats = (tabId) => {
  // Here we clear the badge
  chrome.browserAction.setBadgeText({ text: "" });
  // Then we send a message to the content script, together with a callback
  chrome.tabs.sendMessage(tabId, { text: "cat_count" }, onCatCount);
};

// This is the callback called by the content script
const onCatCount = (catNumber) => {
  if (!catNumber) {
    deactivateIcon();
  } else {
    // When cats are detected, show an animation on the badge
    animateBadge(catNumber);
  }
};

const deactivateIcon = () => {
  // Here we detect what the active tab is and disable the action
  chrome.tabs.query({ active: true, currentWindow: true }, (activeTab) => {
    chrome.browserAction.disable(activeTab[0].id);
  });
};

const animateBadge = (catNumber) => {
  // Limit meows, we don't want 1000 sounds to be played
  let i = catNumber - maxMeows > 0 ? catNumber - maxMeows : 1;
  let j = 0;
  // Cats will meow at random times
  for (; i <= catNumber - 1; i++, j++) {
    updateBadge(i, j * Math.random() * 400);
  }
  // Last cat should come last, let's give it the highest delay
  updateBadge(catNumber, j * 500);
};

const updateBadge = (catIndex, delay) => {
  // After some specified delay display a number on the badge and play a meow sound
  setTimeout(() => {
    (
      new Audio(chrome.runtime.getURL(`audios/meow_${catIndex % 7}.mp3`))
    ).play();
    chrome.browserAction.setBadgeText({ text: catIndex.toString() });
  }, delay);
};
```

The content script basically receives the `cat_count` message and responds to it. Some logic has been included to count the cats with a regex expression:

```
chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => {
  if (msg.text === "cat_count") {
    sendResponse(countCats());
  }
});

const countCats = () => {
  var content =
    document.body["innerText" in document.body ? "innerText" : "textContent"];
  content = removeScriptsFromContent(content);
  var regex = /(cat|cats|kitten|kittens|kitty|kitties)[\s.,]/gi;

  return content.match(regex)?.length || 0;
};

const removeScriptsFromContent = (strCode) => {
  return strCode.replace(/<script.*?>.*?<\/script>/gim, "");
};
```

The popup html file just displays an image and declares the javascript file:

```
<html>
  <body>
    <img id="cat_image" />
    <script src="popup.js"></script>
  </body>
</html>
```

The popup js file executes a function on load which in turn sends a message to the content script to count cats again. This is because popups do not live until they are open, so if some update on the popup needs to be done, it is the popup who needs to start the action:

```
window.onload = () => {
  chrome.tabs.query({ active: true, currentWindow: true }, (activeTab) => {
    const tabId = activeTab[0].id;
    chrome.tabs.sendMessage(tabId, { text: "cat_count" }, onCatCount);
  });
};

const onCatCount = (catNumber) => {
  document.getElementById(
    "cat_image"
  ).src = `https://cataas.com/c/s/${catNumber}%20happy%20cats%20detected?t=sq&width=350`;
};
```

Tadaaaa, this is the result of the cat detector extension in action:

![Cat extension](/img/blog/2020-05_creating-a-chrome-extension/cat_extension.png)

## Testing locally our extension

If you want to test your extension in your local machine, you just need to go to the menu item More Tools —> Extensions, then click on Load Unpacked, and select the folder where your manifest and the rest of the files are.

![Loading the extension for testing](/img/blog/2020-05_creating-a-chrome-extension/load_extension.png)

## Debugging

Debugging gets particularly complex since every bit of a extension has to be inspected in a different way.

Regarding the background scripts, they are inspected in the extensions. To open the dev tools you need to click on the background page link in the extension details.

![Opening the extension dev tools](/img/blog/2020-05_creating-a-chrome-extension/extension_info.png)

Content scripts are inspected in the web page that you are browsing, since they are injected to the page. They are shown in a **Content Scripts** tab.

![Debugging content scripts](/img/blog/2020-05_creating-a-chrome-extension/debugging_content_scripts.png)

I could not found the way to inspect popup scripts, even the console logs got lost somewhere, so showing an alert was the only way to check that the popup was alive and doing stuff.

## Publishing

To publish a Google Chrome extension you need to register as a Chrome developer, pay \$5 and fill in some information about your extension name, description and images or videos. The process is very similar than the one followed to publish an app in Google Play. After submitting your extension for approval, you need to wait for a response. Negative responses are quite fast -my first extension was rejected for no reason, and I had to send an email to ask for a human review-, positive ones can take a few hours or days.

## Going further

The Chrome developer site for extensions provides a great number of sample extensions. These are simple extensions tackling very specific features that can help you learn build extensions.

https://developer.chrome.com/extensions/samples

There are many boilerplate projects out there to help you develop more complex extensions using React, Angular or Vue. Take the following links as a starting point:

- https://github.com/lxieyang/chrome-extension-boilerplate-react
- https://github.com/larscom/ng-chrome-extension
- https://github.com/Kocal/vue-web-extension

## Recap

Creating Chrome extensions can be fun, and you can also find many productive scenarios for them. Developing extensions is easy if you know basic web technologies as HTML, CSS and JavaScript. We showed you the basics of a Chrome extension and guided you through the creation of a simple extension.

If you want to check the full extension code, please go to this [github repository](https://github.com/jguix/chrome-cat-detector).

Can you imagine something that could be delivered as a Chrome extension? We would like to hear about your thoughts.

## Credits

Photo by Markus Winkler on [Unsplash](https://unsplash.com/).


Creating a Chrome extension

In this post I tell you about the experience of participating in a Design Sprint, and how Ecoembes used the Design Sprint methodology to explore new ideas in the context of circular economy and recycling. In order to do that, they recruited through scholarships an eclectic group of professionals who, with the help of UXER School, applied Design Sprint to the world of recycling. In just 5 days we were able to propose and develop innovative ideas that solve problems, for a business that we initially did not know about.

Circular Design SPRINT


This post aims at providing clear instructions on how to use components created and compiled with Stencil on an Ionic application.
I will guide you in the process of making your web component available in your Ionic templates,
without the need of registering them in the npm registry or adding ugly script tags to your index file.

## Motivation

Being created by the [Ionic Framework team](http://ionicframework.com/),
one would expect that using Stencil web components in Ionic projects would be,
if not automatic and integrated in the framework by means of some CLI command,
at least well documented.

Well, that it not the case, since the Ionic guys provide [framework integration instructions](https://stenciljs.com/docs/framework-integration) for Angular,
React, Vue and Ember, but they do not provide them for Ionic.
Maybe I neglected some obvious thing, but I had to do some research to get my Stencil components working on an Ionic project,
and the effort was big enough to make me think about creating a post of it,
hoping that it may help someone.

## Requirements

As a requirement, you need to create a Stencil component, a task for which you can find proper documentation in the Stencil site. The Stencil component doesn't need either to be registered in the npm registry.

## Integration process

If we integrate web components that are registered in npm, the process is simpler. Let's face in this section the case in which we developed a custom component, but we are not publishing it in the npm register. We are aiming at a clean integration without script tags in the `index.html` file.

The process takes three steps.

- First we build the component and copy the distribution files to our project.
- Then we tell the Angular side of things how to use the component.
- Last, we tell the Ionic side of things to include the component when it builds the bundle. The way we talk to Angular (really Ionic-Angular) depends on whether we are _eagerly_ loading pages, or _lazily_ loading them.

### Step 1. Build and copy component

Build the component and copy the contents of the dist folder to a folder in our project.
In this example we chose the folder `@img/lib/components/my-google-maps`.

### Step 2. Import into app.module.ts

First, you need to import the `CUSTOM_ELEMENTS_SCHEMA`, and add it to the `schemas` section of the `@NgModule`. If you import `CUSTOM_ELEMENTS_SCHEMA` into one of your page modules, the Angular compiler will accept elements it does not recognize (otherwise, it will throw an error). If you are lazy loading, you need to import this schema into each page module where you want to use the web component. If you are eagerly loading, you only need to import the schema into `app.module.ts`.

Then, add an import to your `dist/mycomponent` folder. This import statement does not load the entire web component. It only loads a small piece of code that then allows Ionic to load the full web component later, when a template requests it.

When you've performed both steps, your `app.module.ts` should look like this if you are eagerly loading.

```typescript
import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'; // add this import
import '@img/lib/components/my-google-maps/dist/mycomponent'; // add this import

@NgModule({
  declarations: [],
  imports: [],
  bootstrap: [],
  entryComponents: [],
  providers: [],
  schemas: [CUSTOM_ELEMENTS_SCHEMA], // add this line
})
export class AppModule {}
```

If you are lazy loading, import just the web component in `app.module.ts`, and just the schema in the individual lazily loaded modules.

### Step 3. Tell ionic-app-scripts to include the component in the build

We will create a `copy.config.js` file that will define some rules to copy the web component to our final build. A good practice is to create it in a config folder, to separate it from other standard files like `package.json` or `ionic.config.json`.

This file can tell ionic app-scripts to include extra content when it builds an Ionic app. If you are creating the file, put it in a folder named `config` that is at the same directory level as your `src` folder. In the first place, let's declare the file in `package.json`. This will tell the app-scripts to use this file. Add the following field to your `package.json`:

```json
"config": {
    "ionic_copy": "./config/copy.config.js"
}
```

Then, put this inside `config\copy.config.js`:

```javascript
module.exports = {
  copyTimeAgoWebComponent: {
    src: [
      '{{ROOT}}/src/img/lib/components/my-google-maps/dist/mycomponent**/*',
    ],
    dest: '{{BUILD}}',
  },
};
```

Once you've made those changes, app-scripts will know how to include the web component in your builds.
You can now use your Stencil web components in your Ionic templates as any other web component.


This post aims at providing clear instructions on how to use components created and compiled with Stencil on an Ionic application. I will guide you in the process of making your web component available in your Ionic templates, without the need of registering them in the npm registry or adding ugly script tags to your index file.

Using Stencil Built Web Components with Ionic


Imagine a scenario where your app needs to show different versions of a component or services to different groups of users.
If it sounds a bit farfetched, take the following scenario that was proposed to our development team in some real project:

- The app is downloaded from **Google Play/App Store**, and will be deployed in different countries, using the same app ID.
- Different countries have different regulations as to whether the app can display user photographies, specific fields, and so on.
  Also, some features should be totally disabled in some countries.
- The app will keep growing in functionality, but not necessarily at the same time for all countries:
  some countries may decide not to upgrade some feature, or upgrade it later;
  some countries may take more time to review if some particular new feature follows their privacy regulations…

The naive approach of having `ngIf` directives all over the place can work for the simpler cases
but it would be hard to maintain and would also clutter our beautiful templates.
Also, components using different services when switching from one version to another would be very difficult to maintain.

So we came up to the following approach, to cope with all those situations:

- Create a directive to show/hide parts of a template depending on the country and version.
  That would be like an extension of `ngIf` with our `country` and `version` parameters,
  and would give an answer to simple problems like hiding a whole feature in some countries,
  or hiding a particular field for some countries/versions.
- Create a directive that returns a dynamic component, depending on the `country` and `version` parameters.
  This directive would be used for more general cases,
  where a component version can provide very different functionality from another version.

To illustrate this post, we created an app. Our app proudly shows some country data,
like a country flag, area and population.
We made contact with governments all over the world and kindly asked them to join our non-profit revolutionary app,
providing some basic data:

- Country name
- Area
- Population

Some of these countries have really severe regulations and wanted to join the app,
but without revealing their area and population initially,
until their lawyers would determine if this data could be displayed.
So we designed the first version of the app with a single screen,
where the user would select the country from a select combo box,
and a component with two subcomponents displaying the country data:

- A header component for the country name
- A content component for the data

The content component should be optional, and will display depending on the country’s regulations.

![Design of the first version of the components](/img/blog/2018-04_versioning-features-in-an-angular-app/features_v1.png)

These are some screenshots of the app at this point:

![Screenshots of the first version of the app](/img/blog/2018-04_versioning-features-in-an-angular-app/features_v1_screenshots.png)

After the kick off, some users were so excited that started to ask for some new features:

- They wanted to get the country flag displayed in the header
- Some more data like country capital and wait for it… the national anthem, of course

The development team agreed that, given that some countries still had not provided their area and population,
it was reasonable to think that some of them would not provide instantly their flag, capital and anthem.
So we decided to version the header and content components, so we could give them a smooth path to upgrade their data,
while still looking good in the app, showing the old components instead of new components with empty fields.

![Design of the final version of the components](/img/blog/2018-04_versioning-features-in-an-angular-app/features_v2.png)

These are some screenshots of the final version of the app:

![Screenshots of the final version of the app](/img/blog/2018-04_versioning-features-in-an-angular-app/features_v2_screenshots.png)

Our app builds on two directives, as we said.
The first one will show/hide an element depending on the feature availability for a certain country,
where the features will be `COUNTRY_HEADER` and `COUNTRY_CONTENT`.
This directive will get the feature availability from a service, the so called `CountryConfigService`.

```typescript
import {
  CountryConfigDictionary,
  DEFAULT_COUNTRY_CONFIG,
  FeatureVersionDictionary,
} from './country-config.model';

@Injectable()
export class CountryConfigService {
  private config: CountryConfigDictionary = DEFAULT_COUNTRY_CONFIG;
  getCountryFeatures(countryCode: string): FeatureVersionDictionary {
    return this.config[countryCode].features;
  }

  isFeatureEnabled(feature: string, countryCode: string): boolean {
    const countryFeatures = this.getCountryFeatures(countryCode);
    return countryFeatures.hasOwnProperty(feature);
  }

  getFeatureVersion(feature: string, countryCode: string): number {
    const countryFeatures = this.getCountryFeatures(countryCode);
    return countryFeatures[feature];
  }
}
```

The `config` is an object following a `CountryConfigDictionary` model
that lets us define which version of the `COUNTRY_HEADER` and `COUNTRY_CONTENT` components,
if any, is using each country:

```typescript
export const DEFAULT_COUNTRY_CONFIG: CountryConfigDictionary = {
  es: {
    features: {
      COUNTRY_HEADER: 2,
      COUNTRY_CONTENT: 2,
    },
  },
  fr: {
    features: {
      COUNTRY_HEADER: 2,
      COUNTRY_CONTENT: 2,
    },
  },
  it: {
    features: {
      COUNTRY_HEADER: 2,
      COUNTRY_CONTENT: 1,
    },
  },
  pt: {
    features: {
      COUNTRY_HEADER: 1,
      COUNTRY_CONTENT: 1,
    },
  },
  uk: {
    features: {
      COUNTRY_HEADER: 1,
    },
  },
};
```

## The FeatureIf directive

With that in mind, let’s see the `FeatureIf` directive.
It will display an element if the feature is enabled for the country.
Optionally, we can define the minimum version implemented by the country,
meaning that if the country uses a lower version, the element will be hidden.
I will skip the standard imports to save space in the listing:

```typescript
import { CountryConfigService } from '../../services/country-config/country-config.service';

@Directive({
  selector: '[appFeatureIf]',
})
export class FeatureIfDirective implements OnChanges {
  private _featureName: string;
  private _countryCode: string;
  private _minVersion = 0;
  private _else = false;
  private _hasView: boolean;

  @Input() set appFeatureIf(featureName: string) {
    this._featureName = featureName;
  }

  @Input() set appFeatureIfCountryCode(value: string) {
    this._countryCode = value;
  }

  @Input() set appFeatureIfVersion(value: number) {
    this._minVersion = value;
  }

  @Input() set appFeatureIfElse(value: boolean) {
    this._else = value;
  }

  constructor(
    private templateRef: TemplateRef<any>,
    private viewContainerRef: ViewContainerRef,
    private countryConfigService: CountryConfigService
  ) {}

  ngOnChanges(changes: SimpleChanges): void {
    if (changes) {
      this.applyChanges();
    }
  }

  private applyChanges(): void {
    const featureEnabled = this.countryConfigService.isFeatureEnabled(
      this._featureName,
      this._countryCode
    );
    const featureVersion =
      this.countryConfigService.getFeatureVersion(
        this._featureName,
        this._countryCode
      ) || 0;
    const enabled: boolean =
      featureEnabled && featureVersion >= this._minVersion;
    const displayed: boolean =
      (enabled && !this._else) || (!enabled && this._else);
    this.embedTemplate(displayed);
  }

  private embedTemplate(enabled): void {
    if (enabled && !this._hasView) {
      this.viewContainerRef.createEmbeddedView(this.templateRef);
      this._hasView = true;
    } else if (!enabled && this._hasView) {
      this.viewContainerRef.clear();
      this._hasView = false;
    }
  }
}
```

This structural directive makes use of 4 parameters: `featureName`, `countryCode`, `featureVersion` and `else`.
Pay attention on how we define input properties in a structural directive:

- The first input takes the name of the very same directive: `appFeatureIf`.
  We use a setter to internally save it as `_featureName`.
- The rest of the inputs take the name of the directive plus the name of the parameter.
  For instance, the input `appFeatureIfCountryCode` references the directive parameter `countryCode`.
  We also use here a setter to map the input to the private variable `_countryCode`.

Please remark below how the directive is used in a template.
The first parameter doesn’t need a key, while the rest is passed with `"key: value"` tuples, separated by a semicolon (`;`).

```html
<div *appFeatureIf="'COUNTRY_HEADER';countryCode:code;version:2">
  Show only for countries implementing the COUNTRY_HEADER feature with version
  >= 2
</div>

<div *appFeatureIf="'COUNTRY_HEADER';countryCode:code;version:2; else:'true'">
  Show otherwise
</div>
```

What the directive basically does is:

- Registers for changes in any of the inputs.
- When the directive is instantiated or any of the input changes, executes `applyChanges()`.
- Computes if the feature is enabled according to `featureName`, `countryCode` and `minVersion`.
- Computes if the element has to be displayed.
  If the `else` parameter is defined and `true`, then it will be displayed if the feature is disabled.
- Executes `embedTemplate()`, which creates the embedded view into the view container if the element should be displayed,
  or clears the view container otherwise.

We use this directive in two cases in our app.
In the header, we use it to hide the flag for countries implementing `COUNTRY_HEADER` version 1.

```html
<div
  *appFeatureIf="'COUNTRY_HEADER';countryCode:country.code;
  version:2"
  class="flag {{country.code}}"
></div>
```

In the parent component, we use the directive with the `else` parameter set to `true`,
to display an informative text when the content component is not available.

```html
<div
  class="no-feature"
  *appFeatureIf="'COUNTRY_CONTENT';
  countryCode:country.code;else:'true'"
>
  This feature is not yet available in {{country.name}}.
</div>
```

## The FeatureVersion directive

Our second directive will allow us to dynamically inject a component or another, depending on some parameters.

```typescript
import { CountryConfigService } from '../../services/country-config/country-config.service';
import { DynamicComponentService } from '../../services/dynamic-component/dynamic-component.service';
import { DynamicComponent } from '../../services/dynamic-component/dynamic-component.model';

@Directive({
  selector: '[appFeatureVersion]',
})
export class FeatureVersionDirective implements OnChanges {
  private _featureName: string;
  private _countryCode: string;
  private _data: any;
  private componentRef: ComponentRef<DynamicComponent>;

  @Input() set appFeatureVersion(featureName: string) {
    this._featureName = featureName;
  }

  @Input()
  set appFeatureVersionCountryCode(value: string) {
    this._countryCode = value;
  }

  @Input()
  set appFeatureVersionData(value: any) {
    this._data = value;
  }

  constructor(
    private viewContainerRef: ViewContainerRef,
    private countryConfigService: CountryConfigService,
    private dynamicComponentService: DynamicComponentService,
    private componentFactoryResolver: ComponentFactoryResolver
  ) {}

  ngOnChanges(changes: SimpleChanges): void {
    if (changes) {
      this.applyChanges();
    }
  }

  private applyChanges(): void {
    const featureEnabled = this.countryConfigService.isFeatureEnabled(
      this._featureName,
      this._countryCode
    );
    const featureVersion =
      this.countryConfigService.getFeatureVersion(
        this._featureName,
        this._countryCode
      ) || 0;
    const dynamicComponent = this.dynamicComponentService.getComponent(
      this._featureName,
      featureVersion
    );
    this.clearViewContainer();
    if (featureEnabled && dynamicComponent) {
      this.embedComponent(dynamicComponent);
      this.injectComponentData();
    }
  }

  private clearViewContainer(): void {
    this.viewContainerRef.clear();
  }

  private embedComponent(component: Type<DynamicComponent>): void {
    const componentFactory =
      this.componentFactoryResolver.resolveComponentFactory(component);
    this.componentRef = this.viewContainerRef.createComponent(componentFactory);
  }

  private injectComponentData(): void {
    this.componentRef.instance.data = this._data;
  }
}
```

This time, the directive takes three parameters: `featureName`, `countryCode` and `data`.
The `data` parameter will be used to pass data to our dynamic component.
Since different components may have different inputs,
we took the approach of receiving any external data through this `data` object.
Dynamic components may also receive external data through services, as we will see later.

So basically, what this directive does is:

- Registers for changes in any of the inputs.
- When the directive is instantiated or any of the input changes, executes `applyChanges()`.
- Computes if the feature is enabled according to feature name and country code.
- Gets the dynamic component type for the feature name and version from the `DynamicComponentService`.
- Clears the view container.
- If a dynamic component type was retrieved successfully, executes `embedTemplate()`,
  which resolves a factory for this type of component and creates the embedded view into the view container.
- Finally, it injects the data object into the dynamically instantiated component.

Let’s see the code for those `DynamicComponent` and `DynamicComponentService` classes.

The `DynamicComponent` is just a class with a public `data` property.
We will also create a dictionary interface and a constant with the current dynamic component classes
(country content version 1 and 2) that will be used by the service.

```typescript
import { CountryContentV1Component } from '../../../country/components/country-content/v1/country-content.v1.component';
import { CountryContentV2Component } from '../../../country/components/country-content/v2/country-content.v2.component';

export class DynamicComponent {
  data: any;
}

export interface DynamicComponentDictionary {
  [key: string]: {
    [key: number]: Type<DynamicComponent>;
  };
}

export const DEFAULT_DYNAMIC_COMPONENT_DICTIONARY: DynamicComponentDictionary =
  {
    COUNTRY_CONTENT: {
      1: CountryContentV1Component,
      2: CountryContentV2Component,
    },
  };
```

The `DynamicComponentService` simply returns the appropriate component class,
depending on the `featureName` and `version` parameters.

```typescript
import {
  DEFAULT_DYNAMIC_COMPONENT_DICTIONARY,
  DynamicComponent,
  DynamicComponentDictionary,
} from './dynamic-component.model';

@Injectable()
export class DynamicComponentService {
  private componentDictionary: DynamicComponentDictionary =
    DEFAULT_DYNAMIC_COMPONENT_DICTIONARY;

  getComponent(featureName: string, version: number): Type<DynamicComponent> {
    const selectedComponent = this.componentDictionary[featureName]
      ? this.componentDictionary[featureName][version]
      : undefined;
    return selectedComponent;
  }
}
```

Let’s see how this directive is used in the parent component.

```html
<ng-template
  *appFeatureVersion="'COUNTRY_CONTENT';
  countryCode:country.code;data:{country: country}"
>
</ng-template>
```

This is the code for the `CountryContentV1Component` class.

```typescript
import { DynamicComponent } from '../../../../shared/services/dynamic-component/dynamic-component.model';
import { Country } from '../../../services/country.model';

@Component({
  selector: 'app-country-content-v1',
  templateUrl: './country-content.v1.component.html',
  styleUrls: ['./country-content.v1.component.scss'],
})
export class CountryContentV1Component implements DynamicComponent {
  data: { country: Country };
}
```

And this is how the template uses the `data` property to display the country data.

```html
<div class="country-content">
  <div class="data-row">
    <span class="data-label"> Area: </span>
    <span class="data-value"> {{data.country.area | number}} </span>
  </div>
  <div class="data-row">
    <span class="data-label"> Population: </span>
    <span class="data-value"> {{data.country.population | number}} </span>
  </div>
</div>
```

You can see a demo of the application here:  
https://stackblitz.com/edit/component-version-demo

## Versioned services

The situation can get a bit more complicated if services are also versioned.
Let’s imagine that the first version of the service providing country data just included the country name,
area and population, and that a new version should be created to include the new data,
while still providing the old version for backward compatibility.

In this case we can inject the corresponding service version in the versioned components.
We won’t be using the `data` property from `DynamicComponent`, but will get the data from the service instead.
We could also use _injection tokens_ to dynamically inject the versioned service depending on certain conditions.

The following demo is a simple approach using versioned services:  
https://stackblitz.com/edit/component-version-demo-services

## Final considerations

The demo app is probably too simple for that kind of solution.
We could still smartly use some `ngIf` and `ngTemplate` stuff to get to the same solution.
But think of a case where the user doesn’t select the country from a combo box,
but the country gets auto detected from your device settings,
and think of a more complicated UI with a dashboard with several widgets that should be displayed or hidden,
or have different content according to the country, and then this approach will make much more sense.

This post is long enough to get into more details.
If you have suggestions to enhance it, please include them in your comments :)


Versioning components and instantiating the appropriate version dynamically is not only possible but also has some use cases. Check this post where I explain how to accomplish that using a ComponentFactoryResolver and structural directives.

Versioning features in an angular app


Can’t wait to show to the world your proof of concept, side project, idea…?
This 5-line bash recipe will put your work on the showcase in a matter of seconds.

So you just finished creating the coolest project with [Angular CLI](https://cli.angular.io/) and want to share it with your colleagues, or perhaps write a post about it, but you want to skip the pain to your colleagues of checking out the code, installing dependencies and launching the app — I know, it almost can’t get any easier nowadays — and you don’t own a web server, or perhaps you are as lazy as your colleagues and don’t feel like putting much effort on deploying your code anywhere.

Well, [Github Pages](https://pages.github.com/) to the rescue!

## GitHub Pages

I am assuming that you already created your project with Angular CLI, so your project is already versioned with git.
Let’s assume too that you already have a **GitHub account** with some `NICKNAME`.
Head yourself to GitHub and create a new project, let’s call it `MY_PROJECT`.
Don’t put any files in it, you can come back later and add the `README` and the desired license,
but for now it will be easier if you just leave it blank.

Then, connect your local git repository with the new remote repository and push the changes:

```bash
git remote add origin https://github.com/NICKNAME/MY_PROJECT.git
git push origin master
```

Now, if you already knew about GitHub Pages, you’d be tempted to manually activate them on the `index.html` file of your project.
**DON’T DO THAT! It won’t work!!**

Your project still needs to be built for production,
then a `dist` folder will be created from which you could serve your GitHub pages but **DON’T! It won’t work!!!**

It looks like GitHub Pages is not suited for SPAs, since it redirects any paths in your app to a 404 page.
But some really nice guys developed [angular-cli-ghpages](https://www.npmjs.com/package/angular-cli-ghpages).
This npm package will fill the gaps and make your app work in GitHub Pages.

Install it with:

```bash
npm install -g angular-cli-ghpages
```

Then execute these 2 commands:

```bash
ng build --prod --base-href "https://NICKNAME.github.io/MY_PROJECT/"
angular-cli-ghpages
```

The second command has a bunch of options, but they are all optional as the word `option` states,
and you don’t need much more to get your app up and running on GitHub Pages. Enjoy!

Well, certainly you’ll need the URL of your app to share it with the world.
This URL is exactly the one that we used on the `ng build` command:  
[https://NICKNAME.github.io/MY_PROJECT/](#)

### Deploying Ionic projects

Update: 2018-05-07

What about Ionic projects.
They are deployed to `www` instead of the `dist` folder, and they use Ionic CLI instead of Angular CLI,
so a couple of changes will need to be done.

```bash
ionic build --prod
```

The `--base-href` is not available in Ionic CLI (not that I'm aware of),
so you will need to open the `index.html` file and write the base tag on your own, after the build is finished.
You can put it after the title tag, for instance:

```html
<title>Ionic App</title>
<base href="https://NICKNAME.github.io/MY_PROJECT/" />
<meta
  name="viewport"
  content="viewport-fit=cover, width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no"
/>
```

Now, as I said, the output of the build is not the default for Angular CLI, which would be the `dist` folder.
Use the `--dir` flag to specify the `www` folder as the source for GitHub Pages.

```bash
angular-cli-ghpages --dir www
```

## Stackblitz

Now for the [Stackblitz](https://stackblitz.com/) part of the post… wouldn’t it be nice to enable our colleagues or followers, to actually interact with our code and see the impact of the modifications in almost-real-time?

The guys from Stackblitz have created this sort of online IDE where you can create projects and see the build at the same time.
It’s like **JSfiddler** on steroids!

![Stackblitz](/img/blog/2018-03_angular-cli-github-pages-stackblitz/stackblitz.png)

Even simpler than registering on Stackblitz, creating a project and uploading your project files,
this one line trick will load your GitHub project on the Stackblitz IDE.

Just share this URL, using again your GitHub nickname and project name:  
[https://stackblitz.com/github/NICKNAME/MY_PROJECT](#)

This is valid also for branches, tags or specific commits. Just use the following scheme for the URL:  
[https://stackblitz.com/github/NICKNAME/MY_PROJECT/tree/{TAG|BRANCH|COMMIT}](#)

I hope this post helped you to release your projects in a place where they can be seen, enjoyed and edited by others.


Learn how to easily deploy an angular CLI project on Github Pages, as well as sharing a live edit mode version with Stackblitz

Blog