Forem: Rakan Nimer

Client-Side Logging and Analytics with AWS

Rakan Nimer — Sun, 06 Jun 2021 23:22:47 +0000

This post goes through an example setup of client-side log and analytics collection from authenticated and guest clients, using AWS services.

The work will be split into two parts :

Infrastructure Setup : Creating the required infrastructure using the AWS CDK
Client-Side Integration : Interacting with AWS APIs from the client

The following AWS services will be used

The client will retrieve temporary AWS credentials using Amazon Cognito, and use these credentials to log events to CloudWatch and Pinpoint.

Notes :

If you are using / can use Amplify, you don't need any of this, the nice folks there have got you covered : just add Auth and Analytics categories and you're good to go. Amplify Docs
This post is just a wrap-up of my experience playing with these services for my future recollection. Please do not treat this as official advice in any way.

Just show me the code, please !

Here you go !

Infrastructure Setup

This solution doesn't add much infrastructure to maintain, here's what we need :

A Cognito Identity Pool (with unauthenticated guest access)
A Cognito User Pool
An IAM Role for authenticated users
An IAM Role for un-authenticated users

For this post, a similar IAM role will be provided for both.

The IAM role will be granted to all visitors so the permissions that will be granted need to be as minimal as possible.

The following permissions will be given :

logs:CreateLogStream - Each user needs to create their own log stream. The log group is created by the admin account.
logs:PutLogEvents - Allows user to send logs to cloudwatch
mobiletargeting:PutEvents - Allows user to send events to Amazon Pinpoint

This can be done using the AWS console but let's use the CDK to commit our infrastructure as code.

Example TypeScript code can be found here



// Create resources
const userPool = new cognito.UserPool(this, "user-pool", {});

const userPoolClient = new cognito.UserPoolClient(this, "UserPoolClient", {
  userPool,
  generateSecret: false, // Don't need to generate secret for web app running on browsers
});

const identityPool = new cognito.CfnIdentityPool(this, "IdentityPool", {
  allowUnauthenticatedIdentities: true, // Allow unathenticated users
  cognitoIdentityProviders: [
    {
      clientId: userPoolClient.userPoolClientId,
      providerName: userPool.userPoolProviderName,
    },
  ],
});

const pinpointApp = new pinpoint.CfnApp(this, "PinpointApp", {
  name: `pinpoint-${identityPool.ref}`,
});
// In next code block
createCognitoIamRoles(this, identityPool.ref);

// Export values
new CfnOutput(this, "PinPointAppId", {
  value: pinpointApp.ref,
});
new CfnOutput(this, "UserPoolId", {
  value: userPool.userPoolId,
});
new CfnOutput(this, "UserPoolClientId", {
  value: userPoolClient.userPoolClientId,
});
new CfnOutput(this, "IdentityPoolId", {
  value: identityPool.ref,
});

This sets up all the resources except creating the needed IAM Roles and attaching them to the existing identity pool



import * as cdk from "@aws-cdk/core";
import * as iam from "@aws-cdk/aws-iam";
import * as cognito from "@aws-cdk/aws-cognito";

const cloudwatchPermissionPolicy = new iam.PolicyStatement({
  effect: iam.Effect.ALLOW,
  actions: ["logs:PutLogEvents", "logs:CreateLogStream"],
  resources: ["arn:aws:logs:*:*:log-group:*:log-stream:*"],
});

const pinpointPutEventsPolicy = new iam.PolicyStatement({
  effect: iam.Effect.ALLOW,
  actions: ["mobiletargeting:PutEvents", "mobiletargeting:UpdateEndpoint"],
  resources: ["arn:aws:mobiletargeting:*:*:apps/*"],
});

const getRole = (identityPoolRef: string, authed: boolean) => ({
  assumedBy: new iam.FederatedPrincipal(
    "cognito-identity.amazonaws.com",
    {
      StringEquals: {
        "cognito-identity.amazonaws.com:aud": identityPoolRef,
      },
      "ForAnyValue:StringLike": {
        "cognito-identity.amazonaws.com:amr": authed
          ? "authenticated"
          : "unauthenticated",
      },
    },
    "sts:AssumeRoleWithWebIdentity"
  ),
});

export const createCognitoIamRoles = (
  scope: cdk.Construct,
  identityPoolRef: string
) => {
  const authedRole = new iam.Role(
    scope,
    "CognitoAuthenticatedRole",
    getRole(identityPoolRef, true)
  );
  const unAuthedRole = new iam.Role(
    scope,
    "CognitoUnAuthenticatedRole",
    getRole(identityPoolRef, false)
  );
  authedRole.addToPolicy(cloudwatchPermissionPolicy);
  authedRole.addToPolicy(pinpointPutEventsPolicy);

  unAuthedRole.addToPolicy(cloudwatchPermissionPolicy);
  unAuthedRole.addToPolicy(pinpointPutEventsPolicy);

  new cognito.CfnIdentityPoolRoleAttachment(
    scope,
    "IdentityPoolRoleAttachment",
    {
      identityPoolId: identityPoolRef,
      roles: {
        authenticated: authedRole.roleArn,
        unauthenticated: unAuthedRole.roleArn,
      },
    }
  );
};

To create the resources, run npm run deploy in the CDK repository. This will generate the needed resources and output some variable that will be needed in the next section.

Example output:



ClientSideLogTestCdkStack.IdentityPoolId = us-east-1:bc36bea5-5b0f-486a-8812-c68c2a5e4842

ClientSideLogTestCdkStack.PinPointAppId = a915587bb416449a8407fdd75bd6a0fe

ClientSideLogTestCdkStack.UserPoolClientId = 2sjihthbvodq1pos6m29mi6c2j

ClientSideLogTestCdkStack.UserPoolId = us-east-1_z4PrZ5N3Z

Client-Side Integration

Now that the needed infrastructure is ready we can start writing client code to interact with it.

To do that, let's create a Telemetry class ( or whatever you would like to call it ) and use that as our entry-point to the provisioned AWS infrastructure.

This class should:

Give access to Amplify's Analytics and Auth libraries

The Amplify team have done the heavy lifting to provide user-friendly APIs, this implementation should attempt to leverage that work.

Offer a simple abstraction over the CloudWatch client-logs API

The client doing the logging shouldn't care about CloudWatch APIs to be able to send logs. This telemetry client implementation provides three logging methods (info, warn and error)

On instantiation, the object : - Retrieves credentials from Cognito - Creates a cloudwatch client - Instantiates Amplify's Auth and Analytics - Sets up a recurring timer to send collected logs to cloudwatch every 2 seconds.

You can find an example implementation here

Usage

You can find how the telemetry class is used by this react app.



import React from "react";

// client-side-telemetry-js = https://github.com/rakannimer/client-side-aws-telemetry/blob/master/client-side-telemetry-js/index.js

import AwsTelemetry from "client-side-telemetry-js";

// Config values are logged after you finish deployment with the CDK

const telemetryConfig = {

  identityPoolId: "us-east-1:xxxxx-5b0f-486a-yzyz-c68c2a5ea2z2",

  userPoolWebClientId: "2sjihyyyyyyypos6m29mi6c2j",

  userPoolId: "us-east-1_z4PrZ5N3Z",

  region: "us-east-1",

  pinpointAppId: "d9ad53bad9d1qwe1w93d7de2499c7gf5",

};

const logger = new AwsTelemetry(telemetryConfig);

function App() {

  React.useEffect(() => {

    logger.info(Hello);

    setTimeout(() => {

      logger.info(Hello 2 seconds later);

    }, 2200);

  }, []);

  return (

    <div className="App">

      <header className="App-header">

        <img src={logo} className="App-logo" alt="logo" />

        <button

          onClick={() => {

            logger.warn("User clicked a button");

          }}

        >

          Send a message to cloudwatch

        </button>

      </header>

    </div>

  );

}

export default App;

End Result

This should enable you to collect logs from your clients to identify and resolve problems before your customers have to report them.

Bonus Amazon Pinpoint Dashboard Screenshot :

Emptying and Deleting Multiple S3 Buckets with the AWS JS SDK

Rakan Nimer — Wed, 01 Apr 2020 09:21:53 +0000

At the time of writing, to empty and delete an S3 bucket from the AWS console you would have to click through 2 confirmations and type the name of the bucket to confirm that you know you are doing a non-reversible operation.

I have a lot of buckets in my S3 (4 pages worth) and needed to delete most of them. Instead of doing that manually from the console, I opted to do it programmatically. This post walks the reader through the steps needed to write a helper node scripts with the AWS SDK.

Permissions Setup

Download/Update your AWS CLI here : https://aws.amazon.com/cli/
Tell the cli about the AWS credentials that you want to use.

You can do this in several ways but the quickest way is to use the aws configure command.

# You can omit the --profile s3 part 
# and configure the default usser
$ aws configure --profile s3
AWS Access Key ID: foo
AWS Secret Access Key: bar
Default region name [us-west-2]: us-west-2
Default output format [None]: json

To get an access key and a secret access key, go to the user section of IAM from your AWS console and then add a new user with programmatic access to S3 with full read and write permissions.

Set user details :

Set user permissions :

You can now click on next until the user is created and an access key and secret access key are shown.

We can use those keys with the configure command above to finish configuration

Using the AWS JS SDK

To do the operations we will be using the AWS JS SDK with NodeJS.

We want the tool to :

List all buckets.
Allow the user to pick the buckets they would like to delete.
On submit it would iterate through the selected buckets and delete them one by one.

If you'd like to use the tool without caring about how it's done, you can use this one-liner:

git clone https://github.com/rakannimer/s3-bucket-deleter && cd s3-bucket-deleter && npm i && npm run start

For the rest of us, let's start by creating a project :

mkdir s3-deleter
cd s3-deleter
npm init -y
# aws-sdk3 is in developer preview at time of writing 
# fixing it to version 2 is used to future-proof this article 
# in case it's not updated when aws-sdk@3 is released
npm install aws-sdk@2
# to display a nice looking prompt
npm install enquirer
touch s3.js
code s3.js

In package.json we'll add a start script that will run the code in s3.js

{
  "name": "s3-deleter",
  "version": "1.0.0",
  "description": "Empty and delete multiple S3 buckets",
  "main": "s3.js",
  "scripts": {
    "start": "node s3.js"
  },
  "dependencies": {
    "aws-sdk": "^2.649.0",
    "enquirer": "^2.3.4"
  }
}

And the main code with npm start :

// These 3 lines are not necessary if you're using the default aws profile
const AWS = require("aws-sdk");
var credentials = new AWS.SharedIniFileCredentials({ profile: "s3" });
AWS.config.credentials = credentials;

const S3 = require("aws-sdk/clients/s3");
const s3 = new S3();

const { MultiSelect } = require("enquirer");

const delay = ms => new Promise(resolve => setTimeout(resolve, ms));

const deleteBucket = async Bucket => {
  try {
    console.log(`Deleting ${Bucket}`);
    // We can't delete a bucket before emptying its contents
    const { Contents } = await s3.listObjects({ Bucket }).promise();
    if (Contents.length > 0) {
      await s3
        .deleteObjects({
          Bucket,
          Delete: {
            Objects: Contents.map(({ Key }) => ({ Key }))
          }
        })
        .promise();
    }
    await s3.deleteBucket({ Bucket }).promise();
    return true;
  } catch (err) {
    console.log("\n", err, "\n");
    return false;
  }
};

const main = async () => {
  const { Buckets } = await s3.listBuckets().promise();
  const choices = Buckets.map(({ Name }) => ({ name: Name, value: Name }));
  const prompt = new MultiSelect({
    name: "value",
    message: "Select the buckets you would like to delete",
    choices
  });

  const bucketsToDelete = await prompt.run();
  let deletedBuckets = 0;
  for (let bucket of bucketsToDelete) {
    await delay(200);
    const isDeleted = await deleteBucket(bucket);
    deletedBuckets += isDeleted ? 1 : 0;
  }
  console.log(
    `\nDeleted ${deletedBuckets}/${bucketsToDelete.length} buckets.\n`
  );
};

main();

And we're ready to run it :

👋

Testing your Amplify Application with Jest and Cypress

Rakan Nimer — Fri, 23 Aug 2019 11:07:14 +0000

In this post we will be writing static, unit, integration and end-to-end (e2e) tests for a web app deployed with Amplify Console and that uses an Amplify-generated AppSync GraphQL API to query, mutate and subscribe to data.

The app we're testing can be found here and the final code with tests here.

Introduction
Static tests
- Typescript
- ESLint
- Prettier
Setting up Jest with TypeScript and ESLint
- 1. Setup Jest with Babel
- 2. Add TypeScript support to Babel
- 3. Configure ESLint with Jest
Unit tests
- Testing the Reducer
Integration Tests
- Choosing what to mock
- Mocking useRouter from next/router
- Mocking react-intersection-observer
- Testing the App with Mocked Models
- Promise Returning Methods
- Observable Returning Methods
End to End Tests
- Preparing the test environment
- Adding Tests
Adding Test Scripts to package.json
Running Tests from the Amplify Console on Every Commit
Wrapping up

Introduction

Before we continue, if you're not sure what the differences are between the different types of tests, or what each type means then read this post by @kentcdodds (Honestly, you should read it even if you do).

Static tests are done not by executing the code, but by reading it, parsing it and trying to find problems in it. We will be using TypeScript, ESLint and Prettier for our static testing.

Unit tests make sure that individual units of code (functions, components, classes...) produce the right output (and effects) for a given input. We will be unit testing the app's React reducer, a pure function (deterministic and no side-effects).

Integration tests give us confidence that different units of code work together as we expect them to. We will test our routes component with React Testing Library

And finally, e2e tests interact with our app as our end users would.
We'll build our code then interact with it and run assertions on it with cypress and Cypress Testing Library.

Static tests

Typescript

The app we're testing uses Next.js. Starting from version 9, Next.js has TypeScript support out of the box with no configuration required (More info).

If you're starting from scratch run : npx create-next-app --example with-typescript

So we'll just write our code in TypeScript and run the TypeScript compiler to verify there are no errors before every push.

To do that we will need to add a git hook that runs the TypeScript compiler before every push and prevents us from pushing if the code compiles with errors.

Husky makes adding and configuring git hooks easy.

We start by adding husky as a development dependency :



npm i -D husky # Or yarn add -D husky

And then in package.json, add a husky section with git hooks configured



{
  "husky": {
    "pre-push": "tsc"
  }
}

And that's it for TypeScript, now any time we try to push code that doesn't compile, husky will throw and prevent us from doing it.

ESLint

Starting from 2019, ESLint has gotten full TypeScript support. TSLint will soon be deprecated in favor of ESLint so it might be wiser to use ESLint in new projects.

To do that we will start by setting up ESLint with JavaScript then add TypeScript support

Start by installing eslint, the eslint react plugin and the typescript parser



yarn add -D eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin eslint-plugin-react # npm i -D eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin eslint-plugin-react

And then initialize eslint with the config file .eslintrc.js in the root dir of the project:



module.exports = {
  extends: [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:react/recommended"
  ],
  parserOptions: {
    ecmaFeatures: {
      jsx: true,
      modules: true
    },
    ecmaVersion: 2018,
    sourceType: "module"
  },
  parser: "@typescript-eslint/parser",
  plugins: ["react"],
  rules: {
    // I usually turn off these rules out of personal, feel free to delete the rules section in your project
    "@typescript-eslint/explicit-function-return-type": "off",
    "react/prop-types": "off"
  }
};

To lint your code, run :



# Lint all ts or tsx files in src/ and src/{any}/
yarn eslint src/**/*.ts*  src/*.ts* # or $(npm bin)/eslint src/**/*.ts*  src/*.ts

or add a script in package.json to run the command :



{
  "scripts": {
    "lint": "eslint src/**/*.ts*  src/*.ts*"
  }
}

Since the project uses Amplify Codegen we'll need to tell eslint to ignore the generated code emitted by the cli using a .eslintignore file.

As made evident by the name, it behaves like .gitignore but for eslint.



# Path to code generated by Amplify
src/graphql/
src/API.ts

And finally download and install an eslint plugin for your editor to see warning and errors as you type the code. Link to plugin if you're using VSCode.

Prettier

Using prettier is a no-brainer and it also counts as a form of static testing because it parses the code and throws when it's not un-able to.



yarn add -D prettier # npm i -D prettier

Then add prettier to your code editor and never think about formatting again.

The final git hooks in package.json becomes :



{
  "husky": {
    "pre-commit": "prettier --write \"src/*.ts\" \"src/**/*.ts*\"",
    "pre-push": "tsc && yarn lint"
  }
}

Note that this lints and runs prettier on your whole codebase, if you're working on a large codebase then it might be a good idea to use lint-staged to verify changed files only.

Setting up Jest with TypeScript and ESLint

There are two ways to setup Jest and TypeScript, you can either use babel to strip the types before running the code (no type checks) or use the typescript compiler to compile the code before running it. The official docs seem to point the user towards Babel, and Jest is much faster with Babel vs ts-jest with tsc. So we'll go with Babel and use a pre-commit hook to handle type checks.

1. Setup Jest with Babel

Run



yarn add -D jest @types/jest babel-jest @babel/core @babel/preset-env @babel/preset-react

Create a babel.config.js file in the root directory and in it, add :



module.exports = {
  presets: [
    [
      "@babel/preset-env",
      {
        targets: {
          node: "current"
        }
      }
    ],
    "@babel/preset-react"
  ]
};

2. Add TypeScript support to Babel



yarn add -D @babel/preset-typescript

and in babel.config.js :



- "@babel/preset-react"
+ "@babel/preset-react",
+ "@babel/preset-typescript"

3. Configure ESLint with Jest

Install eslint-plugin-jest



yarn add -D eslint-plugin-jest # npm i -D eslint-plugin-jest

And in the .eslintrc.js file, add the jest plugin and jest globals (describe, test, expect...) :



module.exports = {
  env: {
    browser: true,
-    es6: true
+    es6: true,
+    "jest/globals": true
  },
-  plugins: ["@typescript-eslint", "react"],
+  plugins: ["@typescript-eslint", "react", "jest"],
}

At this point, Jest should be setup correctly with ESLint and TypeScript.

Running a test consists of adding a TS file in __tests__ directory and executing :




yarn jest # $(npm bin)/jest # npx jest

Unit tests

Unit tests make sure that functions behave as expected given some input.

Pure functions lend themselves well to unit testing.

The React reducer we use contains the main logic of the app and is a pure function. For every given combination of state and action the function returns a new state.

Jest is a testing framework that focuses on simplicity that will be used for unit and integration tests.

Testing the Reducer

Testing the reducer function consists of calling the reducer with different actions and states and running assertions on the output.

We define every test to be of the following type :



type ReducerTest = {
  state: State;
  action: Action;
  assertions: (newState: State, state: State, action: Action) => void;
};

For example, a simple test to make sure that adding a channel works, would look like the following :



import cases from "jest-in-case";

const reducerTest = {
  name: "Can append channel to empty state"
  state: getInitialState(),
  action: {
    type: "append-channels",
    payload: { items: [createChannel()], nextToken: null }
  },
  assertions: (newState, state, action) => {
    expect(newState.channels.items.length).toEqual(1);
  }
};

const tests = [reducerTest];

const runTest = reducerTest => {
  const newState = reducer(reducerTest.state, reducerTest.action);
  reducerTest.assertions(newState, reducerTest.state, reducerTest.action);
};

cases("works", runTest, tests);

and adding tests consists of adding items to your tests array.

jest-in-case is a "Jest utility for creating variations of the same test"

More tests can be found here.

Integration Tests

These will give us confidence that our components work as expected together. We will be testing and running assertions on route components.

But before doing that we need to setup mocking.

Choosing what to mock

Mocking consists of replacing a unit of code with another that has the same API but not the same effects.

For example, suppose we wanted to mock the API object from @aws-amplify/api.

The app only uses the graphql method of API, and the graphqlOperation method so it would be sufficient to mock it.

@aws-amplify/api is an npm module, in order to mock it, we need to add a __mocks__ folder to the root directory and inside it, create a folder @aws-amplify and file called api.ts.

__mocks__/@aws-amplify/api.ts would look like this :



const API = {
  graphql: operation => {
    if (isSubscription(operation)) return Observable;
    else return Promise;
  }
};
export const graphqlOperation = (query, variables) => ({ query, variables });
export default API;

But mocking at this low level will make it harder to test the right behavior.

For example, if on mount, a component calls API.graphql 3 times, once for a mutation once for a query and once for a subscription.

To test it we'd need to make the API.graphql mock relatively complex, it would need to parse the query on each call and return the appropriate type of data depending on it ) so we'll go one level higher.

Instead of mocking the @aws-amplify/api module, we will mock our models.

Models in this app are the only interfaces available to the UI to interact with the remote API. Components are not allowed to use @aws-amplify/api, they use models that talk with the API, massage the data when needed and return it back to the caller using an Observable or a Promise.

For example to get a promise that lists all channels we'd write something like this :

In App.tsx



import * as React from "react";
import { models } from "./models/ModelsContext";

const App = () => {
  const [channels, setChannels] = React.useState({ items: [], nextToken: "" });
  React.useEffect(() => {
    models.Channels.getChannels().then(chans => {
      setChannels(c => ({
        items: [...c.items, ...chans.items],
        nextToken: chans.nextToken
      }));
    });
  }, []);
  const loadMore = () => {
    models.Channels.getChannels(channels.nextToken).then(chans => {
      setChannels(c => ({
        items: [...c.items, ...chans.items],
        nextToken: chans.nextToken
      }));
    });
  };
  return (
    <Some>
      <ReactTree
        onEndReached={() => {
          loadMore();
        }}
      >
        {channels.items.map(chan => (
          <ChannelCard channel={chan} />
        ))}
      </ReactTree>
    </Some>
  );
};

And in models/Channels.tsx :



import API, { graphqlOperation } from "@aws-amplify/api";
import { queryToGetChannels } from "path/to/generated/graphql/queries";

const EMPTY_CHANNELS = { items: [], nextToken: "" }

export const getChannels = async () => {
  try {
    const channels = await API.graphql(graphqlOperation(queryToGetChannels));
    if (isValidChannelsData(channels))){
      return channels;
    }
    return EMPTY_CHANNELS;
  } catch (err) {
    return EMPTY_CHANNELS;
  }
};

If you're not sure what the deal is with nextToken and how to use it, please refer to my
earlier blog post on pagination and sorting with AWS Amplify.

Mocking models will give us confidence that the app works IF the Amplify API works as expected and that should be enough for the integration tests.

In addition to the models, dependencies that rely on browser features that are not available in JSDOM should also be mocked. The only dependencies of this kind is react-intersection-observer which relies on the IntersectionObserver API, and next/router which returns a null router in the JSDOM environment. Mocking the former should be simple as it's a simple React hook and the latter even simpler since it's just a useContext call.

Mocking useRouter from next/router

If you look at the code of useRouter, it's only a React.useContext call to the router context :



import { RouterContext } from "next-server/dist/lib/router-context";
export function useRouter() {
  return React.useContext(RouterContext);
}

So we won't need to mock the useRouter with Jest, we just have to wrap our tests in a new RouterContext.Provider and the children components will get a custom router injected per test.



import { RouterContext } from "next-server/dist/lib/router-context";

render(
  <RouterContext.Provider
    value={{
      pathname: "/",
      push: jest.fn()
      //...
    }}
  >
    <App />
  </RouterContext.Provider>
);

And now the App will get access to the context provided object above when calling useRouter().

Make sure to read the React docs on Context if you haven't worked with it before.

Mocking react-intersection-observer

Mocking npm dependencies with Jest is very straight-forward :

Create a folder called __mocks__ in the root directory.
Add a file called react-intersection-observer.ts.
Inside it mock the behavior of the module.

In __mocks__/react-intersection-observer.ts.



import * as React from "react";

export const useInView = jest.fn().mockImplementation(() => {
  return [React.useRef(), true];
});

export default {
  useInView
};

jest.fn() is a nice Jest utility function to create customizable, overridable and inspectable mock functions.

An example test for a component using useInView would look like this :

The component :



import * as React from "react";
// When running this code in our tests, the import will be replaced with the code from __mocks/react-intersection-observer
import { useInView } from "react-intersection-observer";

export const Comp = () => {
  const [ref, inView] = useInView();
  return <div ref={ref}>{inView ? "Visible" : "Hidden"}</div>;
};

The test :



import * as React from "react";
import { render } from "@testing-library/react";

import { useInView } from "../__mocks__/react-intersection-observer";
import { Comp } from "../components/Comp";

describe("Comp with use-in-view", () => {
  test("is displayed when inView true", () => {
    useInView.mockImplementation(() => {
      return [React.useRef(), true];
    });
    const { getByText } = render(<ComponentUsingInView />);
    getByText("Visible");
  });
  test("is hidden when inView false", () => {
    useInView.mockImplementation(() => {
      return [React.useRef(), false];
    });
    const { getByText } = render(<ComponentUsingInView />);
    getByText("Hidden");
  });
});

Read more about @testing-library/react here.

Testing the App with Mocked Models

Mocking user modules with Jest is similar to mocking node modules :

Create a folder called __mocks__ in the same directory of the file or directory you want to mock.
Inside __mocks__ add a file with the same name as the file you want to mock.
If the test code uses the mock too, then set it up before running the test by calling jest.mock('./path/to/module')

Models that interact with the Amplify API will return either a Promise (for queries and mutations) or an Observable (for subscriptions).

Once the promise resolves or the observable emits a value we'll update the state to reflect the changes. For example, when getChannels resolves, the app code will trigger a state update to show the new data.

The UI of an app will tend to look differently before and after these promises/observables resolve/emit. It would be nice to be able to run assertions before and after it happens.



const { getAllByLabelText } = render(<Component />);
const allChannels = getAllByLabelText("channel");

// before getChannels resolves
expect(allChannels.length).toEqual(0);
// Do something here 👇 to resolve getChannels
// ...
// after getChannels resolves
expect(allChannels.length).toEqual(4);

To do that we'll need to provide custom mocks per test or test suite to those promises and observables.

Promise Returning Methods

The models' mocks are simple jest mock functions. It is left to the test suite to provide the right implementation and data.

For example, the getChannels mock is a one-liner in src/models/__mocks__/Channels.ts :



export const getChannels = jest.fn();

In __tests__/channels.test.tsx we'll provide the right behavior for this mock before rendering our component :



import * as React from "react";
import { act } from "react-dom/test-utils";
import { render } from "@testing-library/react";
import { getChannels } from "../src/models/__mocks__/Channels.ts";

const dataBank = {
  channels: () => [
    {
      id: "channel-1"
      //,...otherFields
    }
  ]
};
type TestUtils = ReturnType<typeof render>

const selectors = {
  channelList: (testUtils:TestUtils) => testUtils.getAllByTestId("Channel Card");
}

describe("channels", () => {
  let resolveGetChannels;
  getChannels.mockImplementation(() => {
    return new Promise(resolve => {
      // Now a test can resolve getChannels whenever and with any data
      resolveGetChannels = resolve;
    });
  });
  test("works", async () => {
    const testUtils = render(<Channels />);

    // Expect getChannels to be called ( it's called on mount )
    expect(getChannels.toBeCalled());

    // And getChannels hasn't resolved yet because we haven't called resolveGetChannels
    expect(() => {
      selectors.channelList(testUtils)
    }).toThrow();

    // Wait for promise to resolve and ui to update
    await act(async () => {
      resolveGetChannels(dataBank.channels());
    });

    // Make sure that channels are visible
    expect(selectors.channelList(testUtils).length).toEqual(1);
  });
});

If you're not sure what act is, or what it's doing then read this excellent explainer by @threepointone

Observable Returning Methods

Like promise returning models we start out by defining the method as :



export const onCreateChannel = jest.fn();

And we'll define the right implementation in the test suite.

For GraphQL subscriptions, the AWS Amplify API library returns an Observable. The libary uses the zen-observable to create observables. But this is just an implementation detail, we can use RxJS or any other Observable implementation to mock the return type.

If you haven't worked with RxJS or Observables, you just need to think of an Observable as a Promise that

Can resolve more than once.
Can be listened to using subscribe instead of then.

This is a simplification based on what we need for this post only.
For a more in-depth explanation, check out Andre Staltz's The introduction to Reactive Programming you've been missing.



// Creating a promise that is invoked after {ms}ms
const delay = ms => {
  return new Promise(resolve => {
    setTimeout(resolve, ms);
  });
};
// Creating an observable that emits every {ms}ms
const interval = ms => {
  return new Observable(observer => {
    setInterval(() => observer.next(), ms);
  });
};

// Getting the resolved value from a promise
// Fires only once
delay(10).then(value => {});

// Getting the resolved value from a observable
// Fires indefinitely
interval(1000).subscribe(value => {});

In our tests we're going to want to hijack the observer.next method and give it to an individual test to invoke whenever they want :



import * as React from "react";
import { act } from "react-dom/test-utils";
import { Observable } from "rxjs"; // or 'zen-observable'
import { render } from "@testing-library/react";

import { onCreateChannel } from "../src/models/__mocks__/Channels.ts";

const dataBank = {
  channel: () => ({
    id: "channel-1"
    //,...otherFields
  })
};

describe("channels", () => {
  let emitOnCreateChannel;
  onCreateChannel.mockImplementation(() => {
    return new Observable(observer => {
      // Now a test can emit new channels whenever and with any data
      emitOnCreateChannel = v => observer.next(v);
    });
  });
  test("works", () => {
    const { getAllByTestId } = render(<Channels />);
    // Expect onCreateChannel to be called ( it's called on mount )
    expect(onCreateChannel.toBeCalled());
    // The list of channels should be empty before data is fetched with models, 
    expect(() => {
      getAllByTestId("Channel Card");
    }).toThrow();

    // Wait for the observer to emit and ui to update
    act(() => {
      emitOnCreateChannel(dataBank.channel());
    });

    // Make sure that the added channel is visible
    expect(getAllByTestId("Channel Card").length).toEqual(1);
  });
});

You can see a lot more of these tests here.

End to End Tests

We will be using Cypress for our E2E tests because of its relatively better development experience (in my opinion) but if you need to run your tests in multiple browsers or don't particularly like using Cypress than testcafe might be a better match for you.

Preparing the test environment

We'll mock the whole Amplify API using the Amplify cli's built in mock method.

Make sure the amplify version you have is >= 1.11.0 ( with amplify --version ) and that you java installed (DynamoDBLocal used by the api mock is a java application).

And in an initialized amplify project run : amplify mock api

This will create a replica of your app's cloud environment on your local machine and update the app configuration to point to it (by updating src/aws-exports.js).

After running this command we can start the app (npm run dev) and it will work exactly the same way it did before but will be connected to a local database instead of a remote one.

Installing Cypress with TypeScript support is straight-forward :

Install Cypress and initialize it : yarn add -D cypress && yarn cypress --init
Install add-typescript-to-cypress : yarn add -D @bahmutov/add-typescript-to-cypress
👍Add typescript tests to the cypress/integration/ directory

Adding Tests

E2E tests should behave like a user going through the app.
We will use @testing-library/cypress To share code (ui selectors) between the Cypress and Jest tests. An example of a cypress test suite making sure that a user can read and edit their profile information will look like this :




// Note that the code for our selectors is almost identical to the selectors used with Jest
// This is thanks to @testing-library/react & @testing-library/cypress 
// Profile selectors
const profile = {
  form: (cypress = cy) => cypress.getByLabelText("Profile Form"),
  submit: () => cy.getByLabelText("Profile Form Submit Button"),
  username: () => cy.getByLabelText("Username"),
  bio: () => cy.getByLabelText("Bio"),
  url: () => cy.getByLabelText("Url")
};

// Header selectors
const header = {
  root: () => cy.getByLabelText("Header Navigation").should("be.visible"),
  me: () =>
    header
      .root()
      .within(() => cy.getByText("My Profile"))
      .should("be.visible"),
  channels: () =>
    header
      .root()
      .within(() => cy.getByText("Channels"))
      .should("be.visible")
};

describe("My Profile", () => {
  beforeEach(() => {
    cy.visit(BASE_URL);
  });
  afterEach(() => {
    // For video to better capture what happened
    cy.wait(1000);
  });
  it("Can visit profile and set information", () => {
    const user = {
      name: "Test username",
      url: "https://test-url.test",
      bio: "Bio Test @ Test BIO"
    };
    header.me().click();
    cy.location("href").should("contain", "/me");
    profile.username().type(`${user.name}{enter}`);
    cy.title().should("contain", `${user.name}'s Profile`);
    profile.bio().type(`${user.bio}{enter}`);
    profile.url().type(`${user.url}`);
    profile.submit().click();

    // Make sure data is persisted between sessions
    cy.reload();
    profile.username().should("contain.value", user.name);
    profile.bio().should("contain.value", user.bio);
    profile.url().should("contain.value", user.url);
  });
});

You can see more TypeScript Cypress tests here.

Adding Test Scripts to `package.json`

Recap of the scripts used to run our different tests :



{

  "scripts": {

    "test:static": "yarn lint && yarn tsc",

    "test:jest": "yarn jest",

    "test:e2e": "(amplify mock api &) && wait-on http-get://localhost:20002 && kill-port 3000 && (yarn dev &) && wait-on http-get://localhost:3000 && cypress run --env PORT=3000",

    "test:e2e:dev": "(amplify mock api &) && wait-on http-get://localhost:20002 && kill-port 3000 && (yarn dev &) && wait-on http-get://localhost:3000 && cypress open --env PORT=3000",

    "test": "yarn test:static && yarn test:jest"

  },

  "hooks": {

    "pre-commit": "prettier --write \"src/.ts\" \"src//.ts*\"",

    "pre-push": "yarn test"

  }

}

Running Tests from the Amplify Console on Every Commit

We just need to tell Amplify Console to run our tests before deploying on every commit.

To do that we'll add the following amplify.yml



version: 0.1

frontend:

  phases:

    preBuild:

      commands:

        - yarn install

    build:

      commands:

        # This makes sure that the commit is not deployed if the tests fail.

        - yarn run test && yarn run build

  artifacts:

    baseDirectory: build

    files:

      - "/*"

  cache:

    paths:

      - node_modules//*

Wrapping up

We've added, static, unit, integration and end to end tests to an existing chat app that uses Amplify API and ran them using git hooks before committing and pushing our code and on the cloud before deploying with Amplify Console.

If you want to dive deeper make sure to clone the codebase and experiment with the Jest and Cypress tests locally.

Cheers !

Pagination & Sorting with AWS Amplify

Rakan Nimer — Fri, 09 Aug 2019 16:18:38 +0000

In my previous post, Server-Side Rendered Real-time Web App with Next.js, AWS Amplify & Next.js we went into the details of setting up a Next.js React app and connecting it to Amplify on both the server and client-side.

In this more high-level post we'll be going through how to build a channel-oriented group chat app with Amplify that needs to fetch, listen to, paginate and sort lists of data.

Feel free to skip the write-up and check the final code here and a demo here built and deployed with the AWS Amplify Console.

Project Requirements
Defining Local State
Defining the Data Model with GraphQL
- Mutations
- Creating our Custom Queries
- getChannelList
- getChannelMessages
- updateChannel
- Using our Custom Queries
- Subscriptions
Deploying
Wrapping it up

Project Requirements

The group chat app should consist of 3 routes :

channel?id={id} A chat room identified by an id. A user can send and receive messages in real-time. Messages are sorted by descending message creation data (newest at the bottom).

channels A list of channels sorted by descending last update date (newest always at the top). A user can add channels and see channels added in real-time.

me The current user's profile route, used to edit the user's basic information. A form with 3 fields username, url, bio

The color palette is taken from @dabit3's excellent conference-app-in-a-box

Defining Local State

We won't go much into the implementation details of the app's offline functionality but you can do that by trying it here, or by checking the final code here. If you have any questions about the code, please leave a comment here or ping me on twitter and I'll be happy to answer them !

A single state object is being used for the whole app.

Our state without pagination data looks like this :



export type State = {
  me: {
    id: string;
    name?: string;
    bio?: string;
    url?: string;
  };
  channels: Array<{
    id: string;
    messages: Array<{
      id: string;
      text: string;
      createdAt: string;
      senderId: string;
    }>;
    name: string;
    createdAt: string;
    updatedAt: string;
  }>;
};

To be able to paginate through the data we will be needing to store the list of elements and an additional piece of data, the nextToken string that our API returns when fetching a list of items.

We can store that token at the same level as the list (e.g. { channelsNextToken:string, messagesNextToken: { [channelId]: string } }).

However it's easier to follow the format our API uses and instead of having channels and messages as arrays we can define them as a custom List.

A list has 2 fields : items and nextToken.

The type of elements in the items array depends on the list we're querying.

So the state becomes :



type List<T = unknown> = { items: T[]; nextToken: string };

export type State = {
  me: {
    id: string;
    name?: string;
    bio?: string;
    url?: string;
  };
  channels: List<{
    id: string;
    messages: List<{
      id: string;
      text: string;
      createdAt: string;
      senderId: string;
    }>;
    name: string;
    createdAt: string;
    updatedAt: string;
  }>;
};

Defining the Data Model with GraphQL

We want the messages in a channel to be sorted by createdAt and the channels in our ChannelList to be sorted by updatedAt.

To do that we assign a sortField to our connection directive.



type Message @model {
  id: ID!
  text: String!
  createdAt: String
  senderId: String
  channel: Channel @connection(name: "SortedMessages")
  messageChannelId: String
  # Because every message belongs to a channel
  # a messageChannelId field is added when we create an instance
  # of Message to know to which channel this message belongs.
  # Note that when doing 1-to-n relations using connections with GraphQL Transformer 
  # between 2 types typeA & typeB where typeA has many typeB
  # then a field typeBtypeAId is added to typeB to link it to the right typeA instance
}

type Channel @model {
  id: ID!
  name: String!
  createdAt: String!
  updatedAt: String!
  messages: [Message]
    @connection(name: "SortedMessages", sortField: "createdAt")
  channelList: ChannelList @connection(name: "SortedChannels")
  channelChannelListId: String
  # Same as in message, channel will have the id of its owner (ChannelList)
}

type ChannelList @model {
  id: ID!
  channels: [Channel]
    @connection(name: "SortedChannels", sortField: "updatedAt")
}

type User @model {
  id: ID!
  name: String
  bio: String
  url: String
}

# Note here our custom subscriptions.
# Amplify will generate subscriptions by default but the generated ones are too "broad".
# For example we don't want to listen to every new message created if we're in a channel,
# we just need messages that belong to the current channel.

type Subscription {
  # Used when the user is in the channels route to see channels added by others in real-time
  onCreateChannelInList(channelChannelListId: ID!): Channel
    @aws_subscribe(mutations: ["createChannel"])

  # Used when the user is in the channels route to re-sort channels when their updatedAt timestamp changes
  onUpdateChannelInList(channelChannelListId: ID!): Channel
    @aws_subscribe(mutations: ["updateChannel"])

  # Used in 2 places :
  # 1. In the channels route to listen to new messages added to the channel (We need to display the latest message in every channel)
  # 2. In the channel route to receive new messages in real-time

  onCreateMessageInChannel(messageChannelId: ID!): Message
    @aws_subscribe(mutations: ["createMessage"])
}

With this GraphQL schema, Amplify will :

Setup all the cloud resources we need for our app to work on any scale.
Generate code to CRUD the data

For customizing our data pagination and sorting, we will need to do a bit of extra work ourselves but for the rest we will just be using code generated by Amplify.

Mutations

We won't need to write any query for our mutations, the ones Amplify created for us are all we need.

In src/graphql/mutations.ts we'll find all the different possible mutations we can do.

We will be using :

createUser
createMessage
createChannel
updateChannel
createChannelList

For example when a user sends a message :



import { API, graphqlOperation } from "aws-amplify";
import { createMessage as createMessageQuery } from "../graphql/mutations";
import { MessageType, Dispatcher } from "../types";

const addMessage = async (
  content: string,
  dispatch: Dispatcher,
  me: State["me"],
  channelId: string
) => {
  const message = {
    text: content,
    createdAt: `${Date.now()}`,
    id: nanoid(),
    senderId: me.id,
    messageChannelId: channelId
  };
  dispatch({
    type: "append-message",
    payload: message
  });
  setScrollDown(Date.now());
  try {
    await (API.graphql(
      graphqlOperation(createMessageQuery, { input: message })
    ) as Promise<unknown>);
  } catch (err) {
    console.warn("Failed to create message ", err);
  }
};

Creating our Custom Queries

`getChannelList`

Let's create a new file in src/models/ and call it custom-queries.ts.

Inside it, we will add functions that return a GraphQL query when called.

In custom-queries.ts:



export type GetChannelListInput = {
  channelLimit?: number;
  channelNextToken?: string;
  messageLimit?: number;
};

export const getChannelList = ({
  channelLimit = 5,
  channelNextToken = "",
  messageLimit = 1
}: GetChannelListInput) => `
query GetChannelList($id: ID!) {
  getChannelList(id: $id) {
    id
    channels(

      # Number of channels to fetch on each request

      limit: ${channelLimit},

      # sorting direction by the sortField we specified in our schema: updatedAt

      sortDirection: DESC,

      # nextToken is a long string that our API sends back that we can use to
      # retrieve the next batch of entries (older channels in this case)
      # When nextToken is null, then we reached the end of the list

      ${channelNextToken !== "" ? `nextToken:"${channelNextToken}"` : ``}
    ) {
      items {
        id
        name
        createdAt
        updatedAt
        messages(

          # How many messages per channel to retrieve, in our case 1
          limit: ${messageLimit},

          # To get the latest first

          sortDirection: DESC,
          # No need for nextToken here
        ) {
          items {
            id
            createdAt
            senderId
            text
          } 

        }
      }
      nextToken
    }
  }
}
`;

Looking more closely at our query we'll notice that we are using 3 optional arguments to the channels and messages list fields, limit, sortDirection & nextToken explained above in the comments.

`getChannelMessages`

This one should be straight-forward to understand, it also uses limit, sortDirection & nextToken



export type GetMessageListInput = {
  messageLimit?: number;
  messageNextToken?: string;
};

export const getMessageList = ({
  messageLimit = 10,
  messageNextToken = ""
}: GetMessageListInput) => `
query GetChannel($id: ID!) {
  getChannel(id: $id) {
    id
    name
    createdAt
    updatedAt
    messages(
      limit: ${messageLimit},
      sortDirection: DESC,
      ${messageNextToken !== "" ? `nextToken:"${messageNextToken}"` : ``}
    ) {
      items {
        id
        text
        createdAt
        senderId
      }
      nextToken
    }
  }
}
`;

`updateChannel`

The result of a GraphQL subscription with AppSync is the mutation selection set.

In our case, the mutation is updateChannel and the subscription onUpdateChannel

The generated updateChannel looks like this :



mutation UpdateChannel($input: UpdateChannelInput!) {
  updateChannel(input: $input) {
    id
    name
    createdAt
    updatedAt
    creatorId
    messages {
      items {
        id
        text
        createdAt
        senderId
        messageChannelId
      }
      nextToken
    }
    channelList {
      id
      channels {
        nextToken
      }
    }
    channelChannelListId
  }
}

When a conversation is updated we want to receive the last message and some information about the channel.
However, by default, lists are sorted in ascending order, so we need to tell our AppSync API that we want them in descending order, and we'll limit the messages in the set to just one, because we're only interested in the last one.

So we write a custom update query (in src/models/custom-queries.ts) based on how we want the data to look like when a subscription fires an event.



mutation UpdateChannel($input: UpdateChannelInput!) {
    updateChannel(input: $input) {
      id
      name
      createdAt
      updatedAt
      creatorId
      messages(limit: 1, sortDirection: DESC) {
        items {
          text
        }
        nextToken
      }
      channelChannelListId
    }
  }

Using our Custom Queries

The queries above should give us everything we need to fetch both our messages and channels as lists in chunks of 10 or whatever we specify above in the limit.

For example in the channel route, when the component receives a valid channelId we run our query for the first time :



import * as React from "react";
import { Flatlist, ActivityIndicator, View } from "react-native-web";
import { API, graphqlOperation } from "aws-amplify";

import { DispatcherContext } from "../state";

const getChannelMessages = (channelId: string, nextToken: string) => {
  try {
    const query = getMessageList({
      messageLimit: 10,
      messageNextToken: nextToken
    });
    const messages = await API.graphql(
      graphqlOperation(query, { id: channelId })
    );
    return {
      messages: messages.data.getChannel.messages,
      channel: messages.data.getChannel
    };
  } catch (err) {
    console.warn("Failed to get messages ", err);
    return { messages: { items: [], nextToken: "" }, channel: {} };
  }
};

const Channel = ({ channelId, messages }) => {
  const dispatch = React.use(DispatcherContext);
  const [isLoading, setIsLoading] = React.useState(false);
  React.useEffect(() => {
    let isMounted = true;
    if (!channelId) return;
    setIsLoading(true);
    // We start by sending an empty string as nextToken
    getChannelMessages(channelId, "")
      .then(({ messages, channel }) => {
        if (!isMounted) return;
        setIsLoading(false);
        // We store the new messages that contain the next batch of messages and update the nextToken giant string
        dispatch({ type: "append-messages", payload: { channelId, messages } });
        // And update the channel's updatedAt field
        dispatch({ type: "update-channel", payload: channel });
      })
      .catch(err => {
        console.warn(
          "Failed to retrieve channel messages for channel ",
          channelId
        );
        setIsLoading(false);
      });
    () => {
      isMounted = false;
    };
  }, [channelId]);
  return (
    <FlatList
      inverted={true}
      ref={flatlistRef}
      ListFooterComponent={() =>
        isLoading ? (
          <ActivityIndicator
            animating={true}
            color={colors.highlight}
            style={{ marginTop: 15, marginBottom: 15, height: 30 }}
          />
        ) : (
          <View style={{ height: 30 }} />
        )
      }
      keyExtractor={item => item.id}
      data={messages.items}
      renderItem={({ item }) => <Message key={item.id} message={item} />}
      onEndReached={() => {
        if (messages.nextToken === null) return;
        setIsLoading(true);
        // When the end is reached we fetch the next batch of messages if they exist
        getChannelMessages(channelId, messages.nextToken).then(
          ({ messages }) => {
            setIsLoading(false);
            dispatch({
              type: "append-messages",
              payload: { channelId, messages }
            });
          }
        );
      }}
      onEndReachedThreshold={0.01}
    />
  );
};

Subscriptions

For our subscriptions we won't need to write any GraphQL queries. Amplify will generate all the ones we need.

In the GraphQL Schema input for the GraphQL Transformer we defined some subscriptions:



type Subscription {
  # Used when the user is in the channels route to see channels added by others in real-time
  onCreateChannelInList(channelChannelListId: ID!): Channel
    @aws_subscribe(mutations: ["createChannel"])

  # Used when the user is in the channels route to re-sort channels when their updatedAt timestamp changes
  onUpdateChannelInList(channelChannelListId: ID!): Channel
    @aws_subscribe(mutations: ["updateChannel"])

  # Used in 2 places :
  # 1. In the channels route to listen to new messages added to the channel (We need to display latest message in every channel)
  # 2. In the channel route to receive new messages in real-time

  onCreateMessageInChannel(messageChannelId: ID!): Message
    @aws_subscribe(mutations: ["createMessage"])

This will generate the queries in src/graphql/subscriptions.ts and the types we need in src/API.ts

For example let's look at the code needed to listen to new messages on a channel :



import { API, graphqlOperation} from 'aws-amplify'
import {
  onCreateMessageInChannel,
} from "../graphql/subscriptions";

const Channel = () => {
  React.useEffect(() => {
    let isMounted = true;
    if (!channelId) return;
    API.graphql(
      graphqlOperation(
        onCreateMessageInChannel,
        { messageChannelId: channelId }
      )
    ).subscribe(message => {
      const newMessage = message.value.data.onCreateMessageInChannel;
      if (newMessage === null || newMessage.senderId === me.id || !isMounted) return;
      // prepend instead of append because they are sorted in descending order by createdAt 
      dispatch({ type: "prepend-message", payload: newMessage });
    });
    () => {
      isMounted = false;
      onCreateListener.unsubscribe();
    };
  }, [channelId]);

  // Rest of the code
}

Simple enough, listening to a graphql subscription and turning it off on unmount.

Deploying

The code is built and deployed by the AWS Amplify Console. To deploy your own, you can click on this button or just connect your repository to the Amplify Console and that's it.

As you can see in the picture below, Amplify builds and deploys every commit on the master branch.

Wrapping it up

Most applications will need to handle lists of data and fetch progressively from it (chat, comments, history, feed).

This post goes through the challenging parts of doing that with React & Amplify and provides a good starting point to build one yourself !

Add Offline-Caching to Your React Reducer with 5 Lines of Code

Rakan Nimer — Thu, 01 Aug 2019 10:56:12 +0000

When building web applications I often use this method to add local storage caching of my state.

Suppose we're starting with :


const [state, dispatch] = React.useReducer(
  reducer,
  initialState
)

as a first step we create a method that takes in a reducer and outputs another one, a higher-order function:

const withLocalStorageCache = reducer => { return (state, action) => {
  const newState = reducer(state, action);
  localStorage.setItem("my-state", JSON.stringify(newState));
  return newState;
}};

and we wrap our reducer with it before passing the result to the useReducer hook.


const [state, dispatch] = React.useReducer(
  withCache(reducer),
  initialState
)

And finally we replace initialState with the latest cached version of it :

const [state, dispatch] = React.useReducer(
  withCache(reducer),
  localStorage.getItem("my-state")
)

And that' s it !

One line of code modified and 5 new ones and our whole state is synced with localStorage.

We can, of course, limit our caching to only specific parts of the state instead of the whole state object. And limit our updates to the cache by action or state. But we'll leave that as an exercise to the user.

localStorage is supported by 97.62% of browsers.

Complete demo

Server-Side Rendered Real-time Web App with Next.js, AWS Amplify & GraphQL

Rakan Nimer — Thu, 25 Jul 2019 14:37:40 +0000

In this blog post we will go through building a server-rendered realtime collaborative todo list app with Next.js and AWS Amplify.

You can check out the final code here and a demo here.

Introduction
Creating our app skeleton
Adding offline functionality
Preparing the Graqhql Schema for Amplify GraphQL Transform
Setting up AWS Amplify on your computer
Creating the API
Editing the backend
Saving Todos in the cloud
Fetching initial todos on the server-side
Listening to todos being added by others
Listening to todos modified and deleted by others
Deploying our app with now

Introduction

The app will have dynamic and static routes to demonstrate how to load and render data from the server based on the incoming request url. And it has subscriptions to changes on the data to show how to use AWS Amplify to seamlessly listen to remote data from the client.

Next.js makes server-side rendering easy wherever your data is coming from.

AWS Amplify is a library and toolchain that makes it a breeze to setup, manage and use infinitely scale-able cloud infrastructure from AWS.

You don't need to be familiar with the rest of AWS services to use it, however, if you are, you'll notice that Amplify offers a layer of abstraction over popular and battle tested AWS cloud services like AppSync, DynamoDB, Cognito, Lambda, S3 and many others. Amplify packages these cloud services under categories such as Analytics, Auth, API, Storage, PubSub... If you would like to know more about it, make sure to check out their website.

Please note that you can deploy a production ready app without ever needing to know or manually manage any of these services. AWS Amplify can be your only contact point with the cloud.

With that said, let's get started !

Creating our app skeleton

First, let's set up a directory and initialize it with git

mkdir todo-list
cd todo-list
npm init -y
git init

By now we have a directory that contains only our package.json with the defaults specified.

We can now install our dependencies


npm i react react-dom next immer nanoid
# If you're using typescript
npm i -D typescript -@types/react @types/react-dom @types/node

Note that the immer and nanoid dependencies are not necessary

but immer will make it easier for us to manipulate React state and

nanoid is a tiny util to generate a unique id for each to do.

And add 3 scripts to our package.json

{
  "scripts": {
    "dev": "next",
    "build": "next build",
    "start": "next start"
  }
}

Next, we need to create a main page for the web application,
when using Next.js we just need to create a directory called pages and put in it our main file as index.js (or index.tsx)

mkdir pages
touch pages/index.js # or pages/index.tsx

Our main page will just return the app shell to confirm our setup is correct.

import * as React from "react";

const App = () => {
  return (
    <>
      <header>
        <h2>To Do List</h2>
      </header>
      <main>Hello World</main>
    </>
  );
};
export default App;

Let's run it now :

npm run dev

Next.js will setup a tsconfig for us (if we're using Typescript) and start a server on localhost:3000

Visiting that should give us something like this :

Adding offline functionality

We're now ready to add the functionality for our app.

It should have a text field with a button next to it and a list of edit-able and delete-able todos.

To manage the state we will use React.useReducer with initial state equal to :

{
  currentTodo:"",
  todos: []
}

and the reducer will support 4 actions add, update, set-current and delete

Looking at some code, our reducer :

import produce from "immer";

/*<IfTypescript>*/
type Todo = {
  id: string;
  name: string;
  createdAt: string;
  completed: boolean;
};
type State = { todos: Todo[]; currentTodo: string };
type Action =
  | { type: "add" | "update" | "delete"; payload: Todo }
  | { type: "set-current"; payload: string };
/*</IfTypescript>*/

const reducer /*: React.Reducer<State, Action>*/ = (state, action) => {
  switch (action.type) {
    case "set-current": {
      return produce(state, draft => {
        draft.currentTodo = action.payload;
      });
    }
    case "add": {
      return produce(state, draft => {
        draft.todos.push(action.payload);
      });
    }
    case "update": {
      const todoIndex = state.todos.findIndex(
        todo => todo.id === action.payload.id
      );
      if (todoIndex === -1) return state;
      return produce(state, draft => {
        draft.todos[todoIndex] = { ...action.payload };
      });
    }
    case "delete": {
      const todoIndex = state.todos.findIndex(
        todo => todo.id === action.payload.id
      );
      if (todoIndex === -1) return state;
      return produce(state, draft => {
        draft.todos.splice(todoIndex, 1);
      });
    }

    default: {
      throw new Error(`Unsupported action ${JSON.stringify(action)}`);
    }
  }
};

And the UI component :

const App = () => {
  // The reducer defined before
  const [state, dispatch] = React.useReducer(reducer, {
    currentTodo: "",
    todos: []
  });
  const add = () => {
    dispatch({
      type: "add",
      payload: {
        id: nanoid(),
        name: state.currentTodo,
        completed: false,
        createdAt: `${Date.now()}`
      }
    });
    dispatch({ type: "set-current", payload: "" });
  };
  const edit = (todo /*:Todo*/) => {
    dispatch({ type: "update", payload: todo });
  };
  const del = (todo /*:Todo*/) => {
    dispatch({ type: "delete", payload: todo });
  };
  return (
    <>
      <header>
        <h2>To Do List</h2>
      </header>
      <main>
        <form
          onSubmit={event => {
            event.preventDefault();
            add(state.currentTodo);
          }}
        >
          <input
            type="text"
            value={state.currentTodo}
            onChange={event => {
              dispatch({ type: "set-current", payload: event.target.value });
            }}
          />
          <button type="submit">Add</button>
        </form>
        <ul>
          {state.todos.map(todo => {
            return (
              <li key={todo.id}>
                <input
                  type={"text"}
                  value={todo.name}
                  onChange={event => {
                    edit({ ...todo, name: event.target.value });
                  }}
                />
                <button
                  onClick={() => {
                    del(todo);
                  }}
                >
                  Delete
                </button>
              </li>
            );
          })}
        </ul>
      </main>
    </>
  );
};

At this point we have a working to do list app that works offline.
If you're following along with code, now might be a good time to create a commit before jumping into integrating our app with AWS Amplify.

Before you commit make sure to add a .gitignore file

printf "node_modules\n.next" > .gitignore

Let's now sync our todos with the cloud to be able to share them and collaborate with others.

Preparing the Graqhql Schema for Amplify GraphQL Transform

Let's very quickly go through what Amplify GraphQL Transform is.

The GraphQL Transform provides a simple to use abstraction
that helps you quickly create backends for your web and mobile applications on AWS.

With it we define our data model using the GraphQL SDL and the amplify cli takes care of :

Provisioning/Updating required infrastructure for CRUDL operations.
Generating code for client-side CRUDL-ing

Input : GraphQL Data Shape.
Output: Elastic Infrastructure and code to seamless-ly interact with it.

CRUDL = Create Read Update Delete List

In our case the GraphQL schema is simple it consists of one Todo type and one TodoList type that contains a sorted list of todos :

type Todo @model {
  # ! means non-null GraphQL fields are allowed to be null by default
  id: ID!
  name: String!
  createdAt: String!
  completed: Boolean!
  todoList: TodoList! @connection(name: "SortedList")
  userId: String!
}

type TodoList @model {
  id: ID!
  createdAt: String!
  # Array of Todos sorted by Todo.createdAt
  todos: [Todo] @connection(name: "SortedList", sortField: "createdAt")
}

We store the schema as schema.graphql to be re-used later.

The @model directive in the GraphQL Transform schema tells Amplify to treat the to do as a model and store objects of that type in DynamoDB and automatically configure CRUDL queries and mutations using AppSync.

The @connection directive allows us to specify n-to-n relationships between our data types and sort it on the server-side.

Read more about GraphQL Transform and supported directives here.

If you've already used Amplify you can skip directly to Creating the API

Setting up AWS Amplify on your computer

Sign up for an AWS account
Install the AWS Amplify cli:

npm install -g @aws-amplify/cli

Configure the Amplify cli

amplify configure

Creating the API

We start by initializing amplify in our project.

npm i aws-amplify
amplify init
#<Interactive>
? Enter a name for the project (todolist) todolist
? Enter a name for the environment dev # or prod
? Choose your default editor: <MY_FAVORITE_EDITOR>
? Choose the type of app that you\'re building javascript # even if you're using typescript
? What javascript framework are you using react
? Source Directory Path: src
? Distribution Directory Path: out # Next.js exports to the out directory
? Build Command:  npm run-script build
? Start Command: npm run-script start
? Do you want to use an AWS profile? (Y/n) Y # Or use default
? Please choose the profile you want to use default
Your project has been successfully initialized and connected to the cloud!
# 🚀 Ready
#</Interactive>

At this point 2 new folders should have been created : src and amplify
It's safe to ignore them for now.

Now that amplify is initialized we can add any of its services (Auth, API, Analytics ...)
For our use-case we just need to use the API module. So we add it to the project using :

amplify add api
? Please select from one of the below mentioned services GraphQL
? Provide API name: todolist
? Choose an authorization type for the API (Use arrow keys)
❯ API key
  Amazon Cognito User Pool
? Do you have an annotated GraphQL schema? (y/N) y # The one we saved earlier to schema.graphql
? Provide your schema file path: ./schema.graphql

The API configuration is ready we need to push to sync our cloud resources with the current configuration :

amplify push
? Are you sure you want to continue? (Y/n) Y
? Do you want to generate code for your newly created GraphQL API (Y/n) Y # This code incredibly speeds up development
? Choose the code generation language target
❯ javascript
  typescript
  flow
? Enter the file name pattern of graphql queries, mutations and subscriptions src/graphql/**/*.js
? Do you want to generate/update all possible GraphQL operations - queries, mutations and subscriptions (Y/n) Y
? Enter maximum statement depth [increase from default if your schema is deeply nested] 2
⠼ Updating resources in the cloud. This may take a few minutes...
# Logs explaining what's happening
✔ Generated GraphQL operations successfully and saved at src/graphql
✔ All resources are updated in the cloud

GraphQL endpoint: https://tjefk2x675ex7gocplim46iriq.appsync-api.us-east-1.amazonaws.com/graphql
GraphQL API KEY: da2-d7hytqrbj5cwfgbbnxavvm7xry

And that's it 🎉 ! Our whole backend is ready and we have the client-side code to query it.

Editing the backend

Edit amplify/backend/api/apiname/schema.graphql.
Run amplify push
That's it 👍

Saving Todos in the cloud

In pages/index We start by importing API and graphqlOperation from aws-amplify
and configure our amplify application with src/aws-exports.js

import { API, graphqlOperation } from "aws-amplify";
import config from "../src/aws-exports";
API.configure(config);
// Should be a device id or a cognito user id but this will do
const MY_ID = nanoid();

Next, if you open src/graphql/mutations you'll see there's a createTodo string containing the GraphQL Mutation to create a new todo.

We import it and use it after dispatching the add action.

const add = async () => {
  const todo = {
    id: nanoid(),
    name: state.currentTodo,
    completed: false,
    createdAt: `${Date.now()}`
  };
  dispatch({
    type: "add",
    payload: todo
  });
  // Optimistic update
  dispatch({ type: "set-current", payload: "" });
  try {
    await API.graphql(
      graphqlOperation(createTodo, {
        input: { ...todo, todoTodoListId: "global", userId: MY_ID }
      })
    );
  } catch (err) {
    // With revert on error
    dispatch({ type: "set-current", payload: todo.name });
  }
};

And that's it our todos are now being saved to a highly available DynamoDB instance billed by request.

Fetching initial todos on the server-side

We want the list we're building and the data in it to be server-rendered and sent to the client.
So we can't use the React.useEffect hook to load the data and store it in state.

Using Next.js's getInitialProps async method we can fetch data from anywhere and pass it as props to our page component.

Adding one to our main page would look like this

import { getTodoList, createTodoList } from "../src/graphql/queries";

// <TypescriptOnly>
import { GetTodoListQuery } from "../src/API";
// </TypescriptOnly>

App.getInitialProps = async () => {
  let result; /*: { data: GetTodoListQuery; errors: {}[] };*/
  try {
    // Fetch our list from the server
    result = await API.graphql(graphqlOperation(getTodoList, { id: "global" }));
  } catch (err) {
    console.warn(err);
    return { todos: [] };
  }
  if (result.errors) {
    console.warn("Failed to fetch todolist. ", result.errors);
    return { todos: [] };
  }
  if (result.data.getTodoList !== null) {
    return { todos: result.data.getTodoList.todos.items };
  }

  try {
    // And if it doesn't exist, create it
    await API.graphql(
      graphqlOperation(createTodoList, {
        input: {
          id: "global",
          createdAt: `${Date.now()}`
        }
      })
    );
  } catch (err) {
    console.warn(err);
  }
  return { todos: [] };
};

And in our App component we initialize our state with the props we sent with getInitialProps

//<TypescriptOnly>
import { GetTodoListQuery } from '../src/API'
type Props = {
  todos: GetTodoListQuery["getTodoList"]["todos"]["items"];
}
//</TypescriptOnly>

const App = ({ todos }/*:Props */) => {
const [state, dispatch] = React.useReducer(reducer, {
  currentTodo: "",
  todos
});

If you try refreshing the page now, you should see that your todos are persisted between refreshs and they're sorted in the same order as they were before when they were added

Listening to todos being added by others

After we render the app on the client we want to listen to data changes that originated from other users so we can update our UI accordingly.

We will be using GraphQL subscriptions to listen to when a todo is added, updated or deleted.

Fortunately this won't take more than a couple of lines to setup.

import { onCreateTodo } from "../src/graphql/subscriptions";
/*
With TS we create an Observable type to describe the return type of a GraphQL subscription.
Hopefully in future releases of aws-amplify we will have generic types for API.graphql that will make this un-necessary.
*/
type Observable<Value = unknown, Error = {}> = {
  subscribe: (
    cb?: (v: Value) => void,
    errorCb?: (e: Error) => void,
    completeCallback?: () => void
  ) => void;
  unsubscribe: Function;
};

// In our function component
const App = props => {
  // bla
  React.useEffect(() => {
    const listener /*: Observable<{
      value: { data: OnCreateTodoSubscription };
    }> */ = API.graphql(graphqlOperation(onCreateTodo));
    const subscription = listener.subscribe(v => {
      if (v.value.data.onCreateTodo.userId === MY_ID) return;
      dispatch({ type: "add", payload: v.value.data.onCreateTodo });
    });
    return () => {
      subscription.unsubscribe();
    };
  }, []);
  // blabla
};

Listening to todos modified and deleted by others

We'll start by subscribing to two new subscriptions onUpdateTodo and onDeleteTodo

import {
  onCreateTodo,
  onUpdateTodo,
  onDeleteTodo
} from "../src/graphql/subscriptions";
// <ts>
import { OnUpdateTodoSubscription, OnDeleteTodoSubscription } from "../src/API";

type Listener<T> = Observable<{ value: { data: T } }>;
// </ts>
// In our function component
const App = props => {
  // bla
  React.useEffect(() => {
    const onCreateListener: Listener<OnCreateTodoSubscription> = API.graphql(
      graphqlOperation(onCreateTodo)
    );
    const onUpdateListener: Listener<OnUpdateTodoSubscription> = API.graphql(
      graphqlOperation(onUpdateTodo)
    );
    const onDeleteListener: Listener<OnDeleteTodoSubscription> = API.graphql(
      graphqlOperation(onDeleteTodo)
    );

    const onCreateSubscription = onCreateListener.subscribe(v => {
      if (v.value.data.onCreateTodo.userId === MY_ID) return;
      dispatch({ type: "add", payload: v.value.data.onCreateTodo });
    });
    const onUpdateSubscription = onUpdateListener.subscribe(v => {
      dispatch({ type: "update", payload: v.value.data.onUpdateTodo });
    });
    const onDeleteSubscription = onDeleteListener.subscribe(v => {
      dispatch({ type: "delete", payload: v.value.data.onDeleteTodo });
    });

    return () => {
      onCreateSubscription.unsubscribe();
      onUpdateSubscription.unsubscribe();
      onDeleteSubscription.unsubscribe();
    };
  }, []);
  // blabla
};

And here's what our end result, a collaborative real-time todo list looks like

Our first page is done but we still need to have our individual todo page and link to it from our list.

We need our individual todos to be indexed by search engines so we will need to server-render the data in the todo from the id in the url.

To do that, we create a new Next.js dynamic route in pages/todo/[id].(t|j)sx and use the getInitialProps async method to populate it with data from our AWS Amplify datasource.

import * as React from "react";
import { API, graphqlOperation } from "aws-amplify";

import { getTodo } from "../../src/graphql/queries";
import config from "../../src/aws-exports";
// <ts>
import { GetTodoQuery } from "../../src/API";
type Props = { todo: GetTodoQuery["getTodo"] };
// </ts>
API.configure(config);

const TodoPage = (props /*: Props*/) => {
  return (
    <div>
      <h2>Individual Todo {props.todo.id}</h2>
      <pre>{JSON.stringify(props.todo, null, 2)}</pre>
    </div>
  );
};

TodoPage.getInitialProps = async context => {
  const { id } = context.query;
  try {
    const todo = (await API.graphql({
      ...graphqlOperation(getTodo),
      variables: { id }
    })) as { data: GetTodoQuery; errors?: {}[] };
    if (todo.errors) {
      console.log("Failed to fetch todo. ", todo.errors);
      return { todo: {} };
    }
    return { todo: todo.data.getTodo };
  } catch (err) {
    console.warn(err);
    return { todo: {} };
  }
};

export default TodoPage;

And last, we add a link to every todo item

<a href={`/todo/${todo.id}`}>Visit</a>

Deploying our app with now

There are 2 ways of deploying a Next.js app :

Export it to html and static assets and serve it from anywhere
Run a node server that fetches the data on every request and serves pre-rendered pages

We can't export our project to a static html app because we have a dynamic route todo/[id] that fetches data on the fly before rendering based on the url and our main route needs the latest todos to pre-render.

Without these constraints, exporting would be as simple as running : next build && next export.

The other way, which we will be using, is to deploy it as we would any node server.

The fastest way to deploy a Node.js server is using now.

We add a now.json file with the following contents :

{
  "version": 2,
  "builds": [{ "src": "package.json", "use": "@now/next" }]
}

Read more about now.json.

And we can then deploy with

now

And that's it !

We have built and deployed an SEO friendly server-side rendered collaborative todo list using Next.js and AWS Amplify.

👋 If you have any questions feel free to comment here or ping me on twitter.

Introducing React Onscreen Keyboard

Rakan Nimer — Sat, 20 Oct 2018 12:33:00 +0000

I needed a customizable on-screen keyboard component for a music project I'm tinkering with.

So I built react-onscreen-keyboard

You can get a basic keyboard layout just by rendering Keyboard with no props

import OnscreenKeyboard from 'react-onscreen-keyboard'

const App = () => <OnscreenKeyboard />

But you can extend this component as much as you'd like !

Supported props :


export type KeyboardProps = {
  width?: number;
  height?: number;
  keyWidth?: number;
  rowHeightPercent?: number;
  rowWidthPercent?: number;
  verticalMargin?: number;
  horizontalMargin?: number;
  overrides?: Map<
    string,
    (
      props: {
        val: KeyboardKeyVal;
        rowHeight: number;
      }
    ) => any
  >;
  keyboardKeys?: KeyboardKeyVal[][];
  renderKey?: (p: KeyboardKeyProps) => any;
  rowStyle?: React.CSSProperties;
  keyStyle?: React.CSSProperties;
};

export type KeyboardKeyVal = {
  value: string | string[];
  id: string | string[];
  width: number;
  // https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code
  code: KeyboardEvent["code"] | KeyboardEvent["code"][];
};

If you need an on-screen keyboard make sure to check it out :

Cheers !

Declaratively Render Your Firebase Auth, Database & Firestore Data with @react-firebase.

Rakan Nimer — Sat, 13 Oct 2018 12:48:59 +0000

TLDR;

@react-firebase was released to make integrating Firebase in your React App fast & easy 🎉.

If you use React & Firebase, go check it out !

The longer version

I ❤️ Firebase & React but getting them to work together on relatively large codebases with other contributors tends to lead to :

🍝 Un-necessary complexity in your codebase
🐛 Subtle bugs with subscription management and inter-resource dependencies.
🎃 Zombie listeners sticking around when your UI doesn't need them.

@react-firebase offers small, typed, well-tested composable components that allow easy integration of Firebase Auth, Realtime Database and/or Firestore in your React or React Native app.

Overview

@react-firebase/auth, @react-firebase/database, @react-firebase/firestore export Provider and Consumer Components.

Providers

The Provider components take in firebase and firebase config options props and should be rendered once in your app as an ancestor to your Consumer components.

How do I get my Firebase config ?

Web or React Native with Expo

If you're using firebase

Change PROJECT_NAME to your project name and grab your firebase config here :

https://console.firebase.google.com/project/PROJECT_NAME/settings/general/

It should look something like this :

// Firebase Config
const config = {
  apiKey: "API_KEY",
  projectId: "PROJECT_ID",
  databaseURL: "DATABASE_URL",
  authDomain: "AUTH_DOMAIN",
  // OPTIONAL
  storageBucket: "STORAGE_BUCKET",
  messagingSenderId: "MESSAGING_SENDER_ID"
};

React Native Firebase

If you're using react-native-firebase then you only need to pass in your version of firebase as a prop (the firebase app is already initialized on the native side.)

Provider Examples

import * as firebase from "firebase/app";

import "firebase/auth";
import { FirebaseAuthProvider } from "@react-firebase/auth";

// And or
import { FirebaseDatabaseProvider } from "@react-firebase/database";
import "firebase/database";

// And or
import "firebase/firestore";
import { FirestoreProvider } from "@react-firebase/firestore";

<FirebaseAuthProvider firebase={firebase} {...config}>
  <MyApp1 />
  <MyApp2 />
</FirebaseAuthProvider>

Consumers

Every Module exports Consumer components that will consume and react (😅) to Firebase changes.

All Consumer Components expect their children prop to be a React Node or a sync function that returns a React Node. (library-specific examples below 👇)

Firebase Auth Consumers

`FirebaseAuthConsumer`

Anywhere inside your app component tree, add a FirebaseAuthConsumer to listen and update the ui when the user's auth status changes.

<FirebaseAuthConsumer>
  {({ isSignedIn, user, providerId }) => {
    return isSigned ? (
      <pre style={{ height: 300, overflow: "auto" }}>
        {JSON.stringify({ isSignedIn, user, providerId }, null, 2)}
      </pre>
    ) : <div>Not signed in.</div>;
  }}
</FirebaseAuthConsumer>

Auth API Reference

Firebase Database Consumers

Read Data

`FirebaseDatabaseNode`

Anywhere inside your app component tree, add a FirebaseDatabaseNode to listen and update the ui when the data changes at the provided path.

<FirebaseDatabaseNode path={"user_bookmarks/BOOKMARK_ID"}>
  {({ value, isLoading }) => {
    return (
      <pre>
        {JSON.stringify({ value, isLoading })}
      </pre>
    );
  }}
</FirebaseDatabaseNode>

You can also query your Firebase data by using all supported Firebase Realtime Database operators :

<FirebaseDatabaseNode path={"user_bookmarks/BOOKMARK_ID"} limitToFirst={10} orderByKey>
  {({ value, isLoading }) => {
    return (
      <pre>
        {JSON.stringify({ value, isLoading })}
      </pre>
    );
  }}
</FirebaseDatabaseNode>

All supported props.

Write Data

`FirebaseDatabaseMutation` & `FirebaseDatabaseTransaction`

The mutation API is inspired by apollo-graphql mutations.

The mutation components inject a runMutation or runTransaction prop, respectively to their children.

FirebaseDatabaseMutation, in addition to the path prop requires a mutation type prop that can be one of :

"set" | "update" | "push";

FirebaseDatabaseMutation Example.

<FirebaseDatabaseMutation path={collectionPath} type="push">
  {({ runMutation }) => (
    <button
      onClick={async () => {
        const { key } = await runMutation(testDocValue);
        if (key === null || typeof key === "undefined") return;
        this.setState(state => ({
          keys: [...state.keys, key]
        }));
      }}
    >
      add-node-with-generated-key
    </button>
  )}
</FirebaseDatabaseMutation>

FirebaseDatabaseTransaction Example.

<FirebaseDatabaseTransaction path={path}>
  {({ runTransaction }) => {
    return (
      <div>
        <button
          onClick={() => {
            runTransaction({
              reducer: val => {
                if (val === null) {
                  return 1;
                } else {
                  return val + 1;
                }
              }
            }).then(() => {
              console.log("Ran transaction");
            });
          }}
        >
          Click me to run a transaction
        </button>
      </div>
    );
  }}
</FirebaseDatabaseTransaction>

Firestore Database Consumers

Read Data with `FirestoreDocument` & `FirestoreCollection`

Anywhere inside your app component tree, add a FirestoreDocument or FirestoreCollection to listen to the data and update the ui when it changes.

`FirestoreDocument` Example.

const s = v => JSON.stringify(v, null, 2);
const App = () => (
  <FirestoreDocument path={`/user_bookmarks/id`}>
    {({ value, path, isLoading }) => {
      return (
        <div>
          {value && <pre>{s(value)}</pre>}
          {path && <div>{path}</div>}
          <div>{isLoading}</div>
        </div>
      );
    }}
  </FirestoreDocument>
);

`FirestoreDocument` API

FirestoreCollection Example

<FirestoreCollection path="/user_bookmarks/" limit={5}>
  {d => {
    return <pre>{s(d)}</pre>;
  }}
</FirestoreCollection>

`FirestoreCollection` API

Write Data with `FirestoreMutation` & `FirestoreTransaction` & `FirestoreBatchedWrite`

The mutation API is inspired by apollo-graphql mutations.

The mutation components FirestoreMutation & FirestoreTransaction inject a runMutation or runTransaction prop, respectively to their children.

FirestoreMutation in addition to the path prop requires a mutation type prop that can be one of :

"set" | "update" | "add";

The BatchedWrite exposes a different API because it behaves differently than writes and transactions, because it can run many updates before committing them.

It injects 2 props, addMutationToBatch and commit, to its children.

addMutationToBatch

type addMutationToBatch = (
  {
    path,
    value,
    type
  }: {
    path: string;
    value: any;
    type: "add" | "update" | "set" | "delete";
  }
) => void;

commit

type commit = () => Promise<void>;

`FirestoreMutation` Example

<FirestoreProvider firebase={firebase} {...config}>
  <FirestoreMutation type="set" path={path}>
    {({ runMutation }) => {
      return (
        <div>
          <h2> Mutate state </h2>
          <button
            onClick={async () => {
              const mutationResult = await runMutation({
                nowOnCli: Date.now(),
                nowOnServer: firebase.firestore.FieldValue.serverTimestamp()
              });
              console.log("Ran mutation ", mutationResult);
            }}
          >
            Mutate Set
          </button>
        </div>
      );
    }}
  </FirestoreMutation>
</FirestoreProvider>

`FirestoreTranasaction` Example

<FirestoreProvider firebase={firebase} {...config}>
  <FirestoreTransaction>
    {({ runTransaction }) => {
      return (
        <div>
          <button
            data-testid="test-set"
            onClick={async () => {
              await runTransaction(async ({ get, update }) => {
                const res = await get({
                  path
                });
                const data = res.data();
                if (typeof data === "undefined") return;
                await update(path, {
                  ...data,
                  a: isNaN(parseInt(data.a, 10)) ? 1 : data.a + 1
                });
              });
            }}
          >
            runTransaction
          </button>
        </div>
      );
    }}
  </FirestoreTransaction>
</FirestoreProvider>

`FirestoreBatchedWrite` Example

<FirestoreBatchedWrite>
  {({ addMutationToBatch, commit }) => {
    return (
      <div>
        <h2>Batched write</h2>
        <button
          onClick={() => {
            console.log("adding to batch");
            addMutationToBatch({
              path,
              value: { [`a-value-${Date.now()}`]: Date.now() },
              type: "set"
            });
          }}
        >
          Add to batch
        </button>
        <button
          onClick={() => {
            console.log("committing to batch");
            commit().then(() => {
              console.log("Committed");
            });
          }}
        >
          Commit batch
        </button>
      </div>
    );
  }}
</FirestoreBatchedWrite>

Resources

Related Work

re-base
redux-firebase
react-firestore
Your Library ? Send me a DM or comment here to add it.

Thanks for making it to the end of the post ❤️ !

Here are a couple of additional resources just for you :

Tame your Firebase Realtime Database with MobX

Rakan Nimer — Wed, 10 Oct 2018 16:20:38 +0000

While Firebase's Realtime Database enables you to build almost anything, manipulating realtime data in your app can lead to writing code that is hard to debug, understand and maintain.

Enter MobX and mobx-firebase-database.

MobX is a powerful state management library that works with all front-end frameworks.

MobX-firebase-database allows you to map your Firebase realtime data to MobX observables (box, array or map) with firebase, firebase-admin or react-native-firebase

Using it

mobx-firebase-database exports one function getMobxFire, call it with firebase and your firebase config to get access to your toolbox.

import getMobxFire from "mobx-firebase-database";
import firebase from "firebase/app";
import "firebase/database";

// Don't worry about calling it more than once.
const { toBox, toArray, toMap, getFirebaseRef, destroy } = getMobxFire({
  config,
  firebase
});

toBox : Turns a firebase ref to an observable box
toArray : Turns a firebase ref to an observable ordered array of {key,value} objects
toMap : Turns a firebase ref (with any query you can think of) to an observable map: Map<K,V> where K is the child key name and V is the child value

Now that we have access to this set of primitives to build on. We can easily use them to build UIs.

Using `mobx-firebase-database` with Vanilla JS

import { observe } from "mobx";
import getMobxFirebase from "mobx-firebase-database";
import firebase from "firebase/app";
import "firebase/database";
import { config } from "../config";

const PATH = `TEST_SANDBOX/posts/1`;
let counter = 0;
const pretty = obj =>
  `<pre>${JSON.stringify(obj, null, 2)}</pre>`;

const { toBox } = getMobxFirebase({
  config,
  firebase
});
const refToPost = firebase.database().ref(PATH);
const { value } = toBox(refToPost);

setInterval(() => {
  counter += 1;
  // Write data fo firebase here
  refToPost.set({
    title: `post title ${counter}`
  });
}, 500);
observe(value, () => {
  // see it update here
  document.getElementById("root").innerHTML = pretty(
    value.get()
  );
});

Using `mobx-firebase-database` with ReactJS


const App = observer(() => {
  // Render it here
  return <pre>{JSON.stringify(value.get())}</pre>;
});

render(<App />, document.getElementById("root"));

It's that simple :)

Want to know more :

Experiment with VanillaJS code
Experiment with React code
Read the docs

That's it folks !

Have any questions ?
Message me on @rakannimer or leave a comment here !

Forem: Rakan Nimer

Client-Side Logging and Analytics with AWS

Infrastructure Setup

Client-Side Integration

Usage

End Result

Emptying and Deleting Multiple S3 Buckets with the AWS JS SDK

Permissions Setup

Using the AWS JS SDK

Testing your Amplify Application with Jest and Cypress

Introduction

Static tests

Typescript

ESLint

Prettier

Setting up Jest with TypeScript and ESLint

1. Setup Jest with Babel

2. Add TypeScript support to Babel

3. Configure ESLint with Jest

Unit tests

Testing the Reducer

Integration Tests

Choosing what to mock

Mocking useRouter from next/router

Mocking react-intersection-observer

Testing the App with Mocked Models

Promise Returning Methods

Observable Returning Methods

End to End Tests

Preparing the test environment

Adding Tests

Adding Test Scripts to package.json

Running Tests from the Amplify Console on Every Commit

Wrapping up

Pagination & Sorting with AWS Amplify

Project Requirements

Defining Local State

Defining the Data Model with GraphQL

Mutations

Creating our Custom Queries

getChannelList

getChannelMessages

updateChannel

Using our Custom Queries

Subscriptions

Deploying

Wrapping it up

Add Offline-Caching to Your React Reducer with 5 Lines of Code

Server-Side Rendered Real-time Web App with Next.js, AWS Amplify & GraphQL

Introduction

Creating our app skeleton

Adding offline functionality

Preparing the Graqhql Schema for Amplify GraphQL Transform

Setting up AWS Amplify on your computer

Creating the API

Editing the backend

Saving Todos in the cloud

Fetching initial todos on the server-side

Listening to todos being added by others

Listening to todos modified and deleted by others

Deploying our app with now

Introducing React Onscreen Keyboard

Supported props :

Declaratively Render Your Firebase Auth, Database & Firestore Data with @react-firebase.

TLDR;

The longer version

Overview

Providers

How do I get my Firebase config ?

Web or React Native with Expo

React Native Firebase

Provider Examples

Consumers

Firebase Auth Consumers

FirebaseAuthConsumer

Auth API Reference

Firebase Database Consumers

Read Data

FirebaseDatabaseNode

Write Data

Adding Test Scripts to `package.json`

`getChannelList`

`getChannelMessages`

`updateChannel`

`FirebaseAuthConsumer`

`FirebaseDatabaseNode`

`FirebaseDatabaseMutation` & `FirebaseDatabaseTransaction`

Read Data with `FirestoreDocument` & `FirestoreCollection`

`FirestoreDocument` Example.

`FirestoreDocument` API

`FirestoreCollection` API

Write Data with `FirestoreMutation` & `FirestoreTransaction` & `FirestoreBatchedWrite`

`FirestoreMutation` Example

`FirestoreTranasaction` Example

`FirestoreBatchedWrite` Example

Using `mobx-firebase-database` with Vanilla JS

Using `mobx-firebase-database` with ReactJS