Gatsby Plugin AppSync

A Gatsby plugin that makes working with AWS AppSync Client and React Apollo a breeze.

Quick Start

This plugin comes in two modes for Offline support and Apollo Hooks compatiblity respectively.

Install plugin

npm i gatsby-plugin-appsync

Configuration

Rename .env.example created by this plugin inside your root folder to your environment name. e.g .env.development if NODE_ENV is set to development. Also change the settings there

GATSBY_REGION=eu-west-2
GATSBY_COGNITO_USER_POOL_ID=
GATSBY_COGNITO_IDENTITY_POOL_ID=
GATSBY_COGNITO_APP_CLIENT_ID=
GATSBY_S3_BUCKET
GATSBY_S3_REGION
GATSBY_AUTH_API_KEY=da2-fakeApiId123456
GATSBY_AUTH_TYPE=API_KEY | AMAZON_COGNITO_USER_POOLS | AWS_IAM
GATSBY_APOLLO_CLIENT_VERSION=WITH_HOOKS | LEGACY

Plugin default options in node-config.js

module.exports = {
  plugins: [
    resolve: {
      "gatsby-plugin-appsync",
      options: {
        mandatorySignIn: false // true | false
        oauth: {}, // optional for cognito hosted UI
        cookieStorage: {} // optional if you intend to use cookies. Default is localstorage for aws amplify Auth
        clientMetadata: {} // optional for aws amplify Auth
      }
    }
    ...
  ]
};

Refer to https://aws-amplify.github.io/docs/js/authentication#manual-setup for setting oauth, cookieStorage and clientMetadata options.

Usage

GATSBY_APOLLO_CLIENT_VERSION = WITH_HOOKS

This version uses React Apollo ( v 3+), with hooks. No offline support.

For example, your imports will be,

import { useQuery, useLazyQuery } from "@apollo/react-hooks";

You can also use

import { Query, graphql } from "react-apollo";

GATSBY_APOLLO_CLIENT_VERSION = LEGACY

This version uses React Apollo ( v 2.6), without hooks. With offline support.

Since NPM drop in replacement was used to alias both apollo-client@2.6.4 and react-apollo@2.5.6 for offline support and cold install, Queries, Mutations or Subscriptions can then be imported using the hint below

For example, your imports will be

import { Query, Mutation, Subscription, graphql } from "react-apollo-legacy";

Next Steps

AppSync Client

This plugin exposes an AppSync client to be used anywhere based on the version set in environment variables

import { client } from "gatsby-plugin-appsync";

Custom Rehydrate component

This is only useful for offline support, legacy mode.

// Shadow copy ./src/gatsby-plugin-appsync/Rehydrate.js
 
import React from "react";
import { Rehydrated } from "aws-appsync-react";
 
export default function Rehydrate({ children }) {
  return <Rehydrated loading="loading...">{children}</Rehydrated>;
}

Features

• React Apollo with Hooks
• Offline support in legacy version of React Apollo client
• SSR ready
• One point configuration without additional npm installs
• Provides Amplify Auth and Storage configs out of the box
• Available everywhere on your component tree

TODO

• Offline support in React Hooks in React Apollo v3+