DEV Community: Michael Gustmann

Building Tailwind CSS in an Angular CLI project

Michael Gustmann — Fri, 04 Oct 2019 10:40:45 +0000

If you are wondering how to use Tailwind CSS in an Angular CLI project and automatically create an optimized CSS bundle during production builds, you've come to the right place!

You can check out a working minimal solution in this repo

Angular CLI

Ejecting out of the Angular CLI seems like a nightmare to me. Too much of a benefit of generating code, building and configuring quickly. Many tools like NX build on top of it. Since version 6 of Angular it is not even possible to eject out of the CLI anymore. Instead we've got an extensible builder system to include customization, in case we need it.

The Angular CLI uses webpack under the hood to build and bundle the web app. WebPack might be replaced by another build tool, like Bazel, if it proves to be better. Most cases don't need to customize specific build details, but in our case, it is beneficial to hook into the build system. Fortunately, we have the ability to customize the webpack build by using custom builders.

With the help of @angular-builders/custom-webpack we can add some logic to extend the underlying webpack build.

Tailwind CSS

Tailwind CSS is an awesome library to remove the headache of coming up with class names. Everything I need in CSS is defined in HTML and unused styles can be stripped away at build time. I remember those times where I was afraid to remove CSS classes, because these might be used somewhere else. No more! The machine can do it for me.

We will setup an Angular CLI project to compile Tailwind CSS with the help of @angular-builders/custom-webpack to include a build step into the default webpack config. PostCSS will load our Tailwind root file and process it with additional vendor prefixes and remove unused classes with the PurgeCSS plugin. You can find more information about this process in the official Tailwind Documentation about Controlling File Size.

To not slow us down during development, we will configure it to only run the PurgeCSS process during production builds.

Separating Tailwind CSS from the rest

I find it better to separate Tailwind into its own file ./src/tailwind.scss instead of putting the Tailwind's base, components, and utilities styles directly into our CSS. This way I can target the custom build to only this file and leave the rest as it is. Other component libraries like Angular Material can be added without worrying about the intermingled build process.

We can also use whatever style system we like (ie. CSS, SCSS, LESS ...) in our app. Tailwind will just work, can be used in any template and will only put the styles we actually use into our final bundle. I don't see a reason to write any CSS in any components with this setup.

If you want to change the default ng generate component component to NOT create the styles file, you can use this command to default to inline styles in your app:

ng config projects.<my-project>.schematics.@schematics/angular:component.inlineStyle true

Set it up

Create the Angular Project

Install the Angular CLI, if you haven't done so:

npm i -g @angular/cli

Create a new Angular CLI project:

ng new tailwindcss-angular
cd tailwindcss-angular

Install dependencies

Install the packages into the project:

npm i tailwindcss
npm i -D @angular-builders/custom-webpack @fullhuman/postcss-purgecss

Initialize Tailwind CSS

Create a tailwind.config.js file by running this command:

npx tailwind init

This can be used to customize Tailwind with themes, colors, breakpoints, spacing and many others.

Create a new file src/tailwind.scss with this content:

@tailwind base;
@tailwind components;
@tailwind utilities;

Customize the build process

Create another new file extra-webpack.config.js in the root folder of our project and add this content:

const purgecss = require('@fullhuman/postcss-purgecss')({
  // Specify the paths to all of the template files in your project
  content: ['./src/**/*.html', './src/**/*.component.ts'],
  // Include any special characters you're using in this regular expression
  defaultExtractor: content => content.match(/[\w-/:]+(?<!:)/g) || []
});

module.exports = (config, options) => {
  console.log(`Using '${config.mode}' mode`);
  config.module.rules.push({
    test: /tailwind\.scss$/,
    use: [
      {
        loader: 'postcss-loader',
        options: {
          plugins: [
            require('tailwindcss')('./tailwind.config.js'),
            require('autoprefixer'),
            ...(config.mode === 'production' ? [purgecss] : [])
          ]
        }
      }
    ]
  });
  return config;
};

Autoprefixer automatically adds vendor prefixes. Leave it out, if you don't need this.

Configure angular.json

Then, to use these files open up angular.json and look for the "architect" section. You need to customize the ng build and ng serve parts.

You can do it by editing the angular.json file directly or use the ng config command.

So you do this twice, once for build and once for serve:

Replace @angular-devkit/build-angular with @angular-builders/custom-webpack
Add the customWebpackConfig path to the options

Make changes to the build section

ng config projects.<my-project>.architect.build.builder @angular-builders/custom-webpack:browser

ng config projects.<my-project>.architect.build.options.customWebpackConfig.path extra-webpack.config.js

Make changes to the serve section

ng config projects.<my-project>.architect.serve.builder @angular-builders/custom-webpack:dev-server

ng config projects.<my-project>.architect.serve.options.customWebpackConfig.path extra-webpack.config.js

Add the tailwind.scss file to the styles array

Don't forget to add the tailwind.scss path to the styles array. This is probably best done directly in the angular.json file. In case you want to do it with a command, this will add the file to the second index of the array or replace anything that is configured in that slot. So be careful not to overwrite anything.

ng config projects.<my-project>.architect.build.options.styles[1] src/tailwind.scss

Summarized changes to angular.json

In total there are 9 lines affected. The final outcome of all our changes should look like this:

"architect": {
  "build": {
    "builder": "@angular-builders/custom-webpack:browser", // ←
    "options": {
      "customWebpackConfig": {            // ←
        "path": "extra-webpack.config.js" // ←
      },                                  // ←
      // ...
      "styles": [
        "src/tailwind.scss",              // ←
        "src/styles.css"
      ],
    // ...
    }
  },
  "serve": {
    "builder": "@angular-builders/custom-webpack:dev-server", // ←
    "options": {
      "customWebpackConfig": {            // ←
        "path": "extra-webpack.config.js" // ←
      },                                  // ←
    // ...
    }
  }
}

Test it out

Everything should be in place now. To see if if it worked correctly, replace the content of ./src/app.component.html with some HTML that uses Tailwind CSS classes or use this:

<div class="max-w-lg mx-auto bg-white shadow-lg rounded-lg overflow-hidden">
  <div class="sm:flex sm:items-center px-6 py-4">
    <div
      class="flex items-center justify-center sm:flex-col sm:w-24 sm:border sm:border-gray-500 sm:rounded-full"
    >
      <img
        class="block sm:mx-auto mx-0 flex-shrink-0 h-16 sm:h-12"
        src="https://angular.io/assets/images/logos/angular/angular.svg"
        alt="Angular Logo"
      />
      <img
        class="block sm:mx-auto mx-0 flex-shrink-0 h-16 sm:h-12"
        src="https://tailwindcss.com/android-chrome-512x512.png"
        alt="Tailwind CSS Logo"
      />
    </div>

    <div class="mt-4 sm:mt-0 sm:ml-4 text-center sm:text-left">
      <p class="text-xl leading-tight">Tailwind CSS & Angular CLI</p>
      <p class="text-sm leading-tight text-gray-600">
        With custom webpack configuration!
      </p>
      <div class="mt-4">
        <button
          class="text-purple-500 hover:text-white hover:bg-purple-500 border border-purple-500 text-xs font-semibold rounded-full px-4 py-1 leading-normal"
        >
          GO
        </button>
      </div>
    </div>
  </div>
</div>

To see the result in a web browser run ng serve. To see the build output run ng build --prod and take a look into the dist/tailwindcss-angular/styles.########.css file.

Tailwind CSS automatically adds normalize.css. You will see these styles in the beginning of the file.
It will also only contain the css classes used by your app. Everything else is stripped out.

Summary

We learned how to make changes to the build process of our Angular CLI project to compile Tailwind CSS with just a few simple steps.

Install the custom-webpack, purgecss and tailwindcss dependencies
Init tailwindcss and create a tailwind.scss file
Create a extra-webpack.config.js file with the build config
Adjust angular.json

Happy styling your Angular components without writing CSS!

AWS Amplify CLI, how to automatically add a user to a Cognito User Pool with a Lambda-Trigger

Michael Gustmann — Tue, 30 Apr 2019 13:47:23 +0000

Handling Cognito-UserPool-Groups in our AWS Amplify CLI project

AWS Amplify Transform provides an @auth directive. With it we have the possibility to grant access to certain parts of our API based on either static or dynamic groups. See the documentation for details.

Say we have task api and we want:

Each user to log in to use our app and grant read access to our API
To have managers, that can additionally create and update a task
To have admins, that can do everything

We will not cover the API nor the @auth directive, but tackle the problem, that upon Sign-Up, we expect all users to be in a group named 'Users'. Managers and Admins will be added to the groups by hand in the AWS Management Console, but each user will at least belong to the 'Users' group.

We want our code to handle the infrastructure as much as possible without leaving the Amplify CLI.

Let's see how to automate things in each o our environment stacks:

Create all user groups ('Users', 'Managers', 'Admins')
Add a trigger function to automatically add a user to a group
Allow the function to add a user to a group
Configure a trigger in the Cognito UserPool to run the function after Sign-Up

Custom CloudFormation templates

When adding or modifying categories with the Amplify CLI, some templates are not safe and will be overwritten. We can safely add custom resources to the amplify/backend/api/${api-name}/stacks/CustomResources.json file or add other json file to this directory. These stacks are part of the api category, but could be used to create anything that CloudFormation supports. The emphasis is on create! We can reference other parts of our backend templates, but we cannot change them (at least to our knowledge).

We need to change amplify/backend/auth/cognitoxxxx/cognitoxxxx-cloudformation-template.yml, which will get overwritten by operations like

amplify update auth
amplify add analytics

So, we need to be prepared to redo our changes multiple times. Checking in our code in source control will help us with that though.

Generate Groups

We want three groups to be added to our UserPools.

Admins
Managers
Users

If we don't care to redo the changes, when Amplify CLI updates this file, we can edit the 'auth' CloudFormation template.

In amplify/backend/auth/cognitoxxxx/cognitoxxxx-cloudformation-template.yml add at the end just before Outputs :

Resources:
  ## Other resources ...
  ## ...
  UserPoolGroupAdmins:
    Type: 'AWS::Cognito::UserPoolGroup'
    Properties:
      GroupName: Admins
      UserPoolId: !Ref UserPool

  UserPoolGroupManagers:
    Type: 'AWS::Cognito::UserPoolGroup'
    Properties:
      GroupName: Managers
      UserPoolId: !Ref UserPool

  UserPoolGroupUsers:
    Type: 'AWS::Cognito::UserPoolGroup'
    Properties:
      GroupName: Users
      UserPoolId: !Ref UserPool

Outputs:

Otherwise we can go the safe route and use the amplify/backend/api/${api-name}/stacks/CustomResources.json file to create these groups.

Add the following to the "Resources" section, right after "EmptyResource":

  "Resources": {
    "EmptyResource": {
      "Type": "Custom::EmptyResource",
      "Condition": "AlwaysFalse"
    },
    "UserPoolGroupAdmins": {
      "Type": "AWS::Cognito::UserPoolGroup",
      "Properties": {
        "GroupName": "Admins",
        "UserPoolId": {
          "Ref": "AuthCognitoUserPoolId"
        }
      }
    },
    "UserPoolGroupManagers": {
      "Type": "AWS::Cognito::UserPoolGroup",
      "Properties": {
        "GroupName": "Managers",
        "UserPoolId": {
          "Ref": "AuthCognitoUserPoolId"
        }
      }
    },
    "UserPoolGroupUsers": {
      "Type": "AWS::Cognito::UserPoolGroup",
      "Properties": {
        "GroupName": "Users",
        "UserPoolId": {
          "Ref": "AuthCognitoUserPoolId"
        }
      }
    }
  }

The downside to this is, that it will show up as if the api category changed and not the auth category.

Automatically add a User to a Cognito User Pool Group with a Lambda-Trigger on Sign-Up

Now that we automatically create Cognito-UserPool-Groups, we want to assign users to one of those groups upon Sign-Up.

Cognito offers triggers during certain life-cycle events. One of these triggers is 'PostConfirmation', which may run a Lambda function after a user was successfully confirmed.

Add a new Lambda Function

The AWS Amplify CLI offers the ability to add a function to our project:

amplify add function

Choose the name 'addUserToGroup', when asked for the friendly name and Lambda function name and as a template we want Hello world function.

Change the file index.js of our newly created function.

exports.handler = function afterConfirmationTrigger(event, context, callback) {
  const AWS = require('aws-sdk');
  const cognitoISP = new AWS.CognitoIdentityServiceProvider({
    apiVersion: '2016-04-18'
  });

  const params = {
    GroupName: 'Users',
    UserPoolId: event.userPoolId,
    Username: event.userName
  };

  cognitoISP
    .adminAddUserToGroup(params)
    .promise()
    .then(() => callback(null, event))
    .catch(err => callback(err, event));
};

In event.json we can change the payload content to our liking to test the function.

{
  "userPoolId": "the-user-pool-id",
  "userName": "user1",
  "userPoolGroupName": "Users"
}

To run a test use:

amplify invoke function addUserToGroup

This will not work yet. Since we need to give the function the permission to do what we want it to do.

Add IAM Policy to allow adding user to group

To allow our new function to actually add a user to a group, it needs a policy attached. This time we need to edit the CloudFormation template of the Lambda function. This should be pretty safe, since other categories usually don't have side effects on this template.

We need to specify the resource ARN of our UserPool target. We can resort to using a wildcard character or use parameters to get the exact ARN of our UserPool.

Without parameters

We edit the file amplify/backend/function/addUserToGroup/addUserToGroup-cloudformation-template.json and add to the array lambdaexecutionpolicy.Properties.PolicyDocument.Statement

{
  "Effect": "Allow",
  "Action": ["cognito-idp:AdminAddUserToGroup"],
  "Resource": {
    "Fn::Sub": [
      "arn:aws:cognito-idp:${region}:${account}:userpool/${region}*",
      {
        "region": {
          "Ref": "AWS::Region"
        },
        "account": {
          "Ref": "AWS::AccountId"
        }
      }
    ]
  }
}

This is simple and in one place but will give the function the permission to access all UserPools in our region.

With parameters and least privileges

To target a single UserPool istead, we need to know its ARN. To get access, we create a parameter and pass it to our CloudFormation template.

We create a new file amplify/backend/function/addUserToGroup/parameters.json and add the ARN of the UserPool to it. We can take a look at the authcognitoname in amplify/backend/api/${api-name}/parameters.json.

{
  "AuthCognitoUserPoolArn": {
    "Fn::Sub": [
      "arn:aws:cognito-idp:${AWS::Region}:${AWS::AccountId}:userpool/${id}",
      {
        "id": {
          "Fn::GetAtt": ["--authcognitoname--", "Outputs.UserPoolId"]
        }
      }
    ]
  }
}

To pass the parameters to the CloudFormation template, we need to edit amplify/backend/function/addUserToGroup/addUserToGroup-cloudformation-template.json.

First, we have to define the parameter. We do this by adding the following to the "Parameters" array:

{
  "Parameters": {
    // ... other parameters
    "AuthCognitoUserPoolArn": {
      "Type": "String"
    }
  }
}

Then we add a statement tolambdaexecutionpolicy.Properties.PolicyDocument.Statement which references the "AuthCognitoUserPoolArn" parameter and allows the action "cognito-idp:AdminAddUserToGroup":

{
  "Effect": "Allow",
  "Action": ["cognito-idp:AdminAddUserToGroup"],
  "Resource": { "Ref": "AuthCognitoUserPoolArn" }
}

We can run amplify push to deploy the function and check if the policy was added successfully by going to the Lambda Management Console and find our function. If we click on the 'Amazon Cognito User Pools' box, we can inspect the policy below it.

Add Lambda PostConfirmation-Trigger

To assign the Lambda function to a Cognito-UserPool-Trigger, we need to edit the 'auth' CloudFormation template.

This might get overwritten on certain Amplify CLI operations, but we don't see another choice.

In amplify/backend/auth/cognitoxxxx/cognitoxxxx-cloudformation-template.yml we add our trigger somewhere in that section:

# BEGIN USER POOL RESOURCES
UserPool:
  # Created upon user selection
  # Depends on SNS Role for Arn if MFA is enabled
  Type: AWS::Cognito::UserPool
  UpdateReplacePolicy: Retain
  Properties:
    # Other properties ...
    # Add this:
    LambdaConfig:
      PostConfirmation: !Sub
        - arn:aws:lambda:${region}:${account}:function:addUserToGroup-${env}
        - {
            region: !Ref 'AWS::Region',
            account: !Ref 'AWS::AccountId',
            env: !Ref env,
          }

To deploy the changes to our UserPool we run

amplify push

Checking our work

When everything worked, we can sign in to our AWS Management Console and check:

Cognito UserPool should have created our three groups
There is a PostConfirmation trigger pointing to our addUserToGroup Lambda function
The Lambda function was created in our environment
The function has the right policy attached, which allows it to add a user to a group in our UserPool

To see it in action, we sign up a new user in our Amplify CLI app of our choice and watch how this new user is automatically added to the 'Users' Cognito-UserPool-Group.

Recap

We created UserPool-Groups in CustomResources.json of the api category, added a Lambda function, attached a policy to it to access the UserPool and edited our Cognito CloudFormation template to define a PostConfirmation Trigger that executes our new Lambda function. Now each time a user signs up it will be assigned to a group.

As the development of Amplify CLI continues we should see help in this area. So this procedure might get irrelivant in a hopefully short while.

Personal Growth with Git Flow and AWS Amplify Console - Part 3

Michael Gustmann — Thu, 11 Apr 2019 09:17:13 +0000

Having built a personalized Todo App with a GraphQL API in Part 1 and Part 2 with the help of the AWS Amplify CLI using Angular and the tools of Nx we have actually quite a lot of time on our hands.
We didn't have to build Authentication and Authorization, we did not have to think about how to set up a workspace for additional future apps or team-mates in mind, we saved on writing lengthy GraphQL schemas with pagination, filtering, input objects, resolvers and ownership and we wrote everything in code to easily push an entire backend environment to the cloud.

Personal Growth with Git Flow and AWS Amplify Console - Part 3

We feel good about our life's choices! Free time to concentrate on our health and personal growth! So, we go to a seminar on the weekend to listen to a famous life coach. It is a great speech, were we learn how to be thankful and appreciate everything in life. He encourages everyone to tell the group about the things we are thankful for. So, as we are feeling good, we actually stand up and tell everyone about our achievements. About writing a personalized todo-app, thinking big about future plans and other team mates. We also shared our thoughts about our plans on publishing the app worldwide, adding git flow and continuous integration. Of course, we couldn't leave out the concept of "You build, you own it" and how we can iterate fast by easily spinning up service-full cloud environments by writing a few powerful Amplify and Angular commands.

Talking about "two-pizza-teams" crosses our minds, but we quickly dismiss the thought, not wanting to go down the rabbit-whole of healthy nourishment.

We're not sure how much we made sense to everyone in the room, but the coach was extremely excited! Setting personal goals for ourselves and checking them off, when completed is a great way to empower us for greater things. Building things and taking the responsibility for it, while continuously integrating that flow into our lives will connect us to our environment in the "here and now" and beyond the clouds. Staying service-full while giving commands will amplify our personal growth.

Wow, we did not expect this response at all! Being experienced in hallway chats on summits and conferences we stay to talk to the speaker afterwards. He lets us in on his plans to build an online life coaching platform to share videos, articles and documents. Chat groups between paying members and an app to track personal goals should also be a part of this offering.
He sais, he likes the way we are thinking ahead. Having a production ready todo-app with these wonderful tools in our belt, we are the perfect candidates to build up a small team to take up this endeavor.

After exchanging our social media contact information, we promise to send him a link to our web app. On our way home we start to think about how to quickly get our todo-app published worldwide. We could use the amplify hosting command to simply setup a static website, but since we feel like we will need to publish several staging environments and branches in the future, we decide on using the git-flow workflow.

Setting up a complete CI/CD pipeline is usually a non-trivial task, but since the introduction of Amplify Console it got cut down to a few minutes.

Preparing the repo

OK, let's start where we last left off. We have a GIT repository hosted at GitHub with a single master branch. We have a single Amplify environment called 'master', when we previously ran amplify init and amplify push.

We want to end up with two permanent git branches 'master' and 'develop'. These branches should be each connected to a similar named amplify stack in the cloud. The information about our cloud resources should be stored in each branch.

We can add a new cloud environment by typing amplify init and choosing No when asked, if we want to use an existing environment and develop as the new name. The next question will be about our AWS profile we want to use, so we choose the one we used for master as well.

Working in a non-open-source-team, we should revert the change we made in part one, where we put team-provider-info.json in .gitignore. Looking into this file, we will see our newly created develop environment added.

So far, we have

one 'master' git branch locally and on origin
two backend environments 'master' and 'develop' in team-provider-info.json
one 'master' backend environment stack pushed to the cloud ('develop' env only locally so far)

Creating another app in our workspace

We don't have a requirement for another app yet, but as we created a workspace, that supports multiple apps connected to one backend, we feel the urge in our belly to test this out anyways.

We make it quick (remembering that we covered the process quite thoroughly in part 1) by typing ng g app second-app and accepting all defaults. A few more adjustments are needed:

Adding 'global' to polyfills.ts
Importing the css theme in styles.css
Concatinating the AppsyncModule to the imports array in app.module.ts
Prepending the content of app.component.html with <amplify-authenticator></amplify-authenticator> on line one
Appending another build command to package.json's scripts section: "build:second": "npm run rename:aws:config || ng build second-app --prod; ng build second-app --prod"

Once we make sure this runs locally with ng serve second-app and npm run build:second, we commit and push the changes to the 'master' branch.

Adding Git-Flow

Since we decided to use git-flow and like to have an opinionated workflow, we agree to install a helper library for guidance on our Mac. We can come back to this cheat sheet at any point, if we run into unknown git-flow territory.

brew install git-flow-avh

and being on the root level of our workspace we run

git flow init

while keeping all defaults. Doing this, we end up on a new develop branch, which we can push to our source control provider by using this command

git push -u origin develop

Not much changed here. We simply have a new branch 'develop' without any new commits.

AWS Amplify Console

We are ready to start our CI/CD pipeline. We go to AWS Amplify Console and click on the CONNECT APP button.

Four simple steps to set up our build and deploy pipeline:

Step 1 - Add repository service

Selecting our GIT provider and giving Amplify Console read-only permission

Step 2 - Add repository branch

Picking our repository and the 'master' branch from the dropdown options

Step 3 - Configure build settings

As App name we like 'amplified'. Both backend environments from team-provider-info.json should be detected. We have an option to create a new environment right here, which we could reuse in Amplify CLI by importing it later on, but we set up our two environments earlier. So, we pick the 'master' environment in this step.

We need to select a service role in our AWS account. If we don't have existing one, we can create a new one so Amplify Console may access our resources.

We can edit the yaml build settings file and set custom Environment variables for any secrets, that don't belong in source control. AWS offers some variables for usage in our build scripts, like

AWS_JOB_ID
AWS_APP_ID
AWS_BRANCH

Step 4 - Review

Well, ... we review and click Save and deploy

Adding the 'develop' branch

Completing these four steps should have started our build for 'master'. And while waiting for it to finish, we can take a deep breath or two and behold the powers of our fingertips.

Feeling calm and refreshed we return to connect our second branch 'develop' to the equally named backend. This time only needing to go through two steps:

Step 1 - Add repository branch

Step 2 - Review

So far, our todo-app's branches master and develop are connected to Amplify Console. Anytime we git push to either of those branches, we will see our frontend update at the edge and our backend resources synced with our code from our repo.

Amplify Console region support

What if Amplify Console does not support our region yet? Depending on when we are trying this, the region we chose when we configured the Amplify CLI might not be supported by the Amplify Console yet. No Biggy, choosing a supported region of Amplify Console, we can add a line right before the amplify push command in the build script:

backend:
  phases:
    build:
      commands:
        # replace {our-region} with the previously used region
        - echo -e "[default]\nregion={our-region}" > ~/.aws/config
        - '# Execute Amplify CLI with the helper script'
        - amplifyPush --simple

This will set our region in the default AWS profile on the current build container instance.

Deploying a second app

Looking at the build script in Amplify Console, we see a way to specify a single frontend app and a single backend stack per git branch. The frontend app will end up at a URL unique to a specific branch, like https://master.ourappid.amplifyapp.com and the backend stack will create unique resources in a region with a similar naming schema. But we would like a URL for each app on the same branch, i.e.

https://master.app-one.ourappid.amplifyapp.com
https://master.app-two.ourappid.amplifyapp.com
https://master.app-x.ourappid.amplifyapp.com

Unfortunately, this is currently not possible.

Amplify Console seems to be designed so that we can connect an "Amplify Console"-App to a git repository very simply. Different frontends and backend stacks are configured or connected via git branches. This allows us to deploy our full stack app to various staging environments, like production, develop, test or feature sandboxes.

What about creating a new Amplify-Console-App-Connection to the same repo?

Trying to connect another app in Amplify Console, we will quickly see, that we can't choose the same repository again. Picking a different region and connecting an app from the same repo is a workaround, that would work, but we are not very happy with managing this in the future.

But there's another option to connect an app, which we can explore to see if it could help us:

One-Click Deploy Button

Very recently AWS added a new feature, the One-Click Deploy Button to deploy a GitHub repository to Amplify Console. A single click on a button and the repo is deployed in our AWS account. We can use it to share our open source project with the world or onboard a new team mate in minutes! Depending on how quickly our todo-app grows, this might come quite handy, when new recruitments arrive.

We can put it in README.md files or in blog posts, so here is our button to the corresponding repo:

Clicking this button opens a new browser tab with our region and GitHub link encoded in the URL:

https://{aws-region}.console.aws.amazon.com/amplify/home#/deploy?repo={github-url}

When clicking the Connect to GitHub button, we type the name 'amplified-again' and after reviewing almost nothing, we will have our GitHub repo's default branch connected to a new backend environment stack called 'amplify'. Indeed, very simple and quick!

Reusing the newly created 'amplify' backend

Once the connection and the build #1 completed, we could tell our Amplify CLI about this new backend environment, so we could reuse it. Or as in our case, since we want our existing backends, we want to delete the newly created stack.

Finding the Backend build step in the Build activity will reveal the needed information and instructions:

Selecting the 'More Info' button will give us an amplify cli command to run in the root of our project:

After we do this, the 'amplify' backend environment will end up in our team-provider-info.json file ready to be chosen on our command line.

$ amplify env list

| Environments |
| ------------ |
| amplify      |
| master       |
| *develop     |

The copied command includes the aws profile 'default', so we should remember to adjust this to our profile name, if needed

We could just use it and commit the changes to GitHub, but we want to delete this backend stack in the cloud and locally.

amplify env remove amplify

This looks a little bit weird, asking amplify to remove itself... Well, the result is in, nothing broke!

$ amplify env list

| Environments |
| ------------ |
| master       |
| *develop     |

Almost nothing, if we would run the build in the Amplify Console, we would see it fail, having removed the backend under its nose.

Reusing our previous 'master' backend

So where we're at right now? We have a second "Amplify Console"-App connected to the same repo. The default master branch uses the newly created (and secretly deleted) 'amplify' backend environment, but we want to reuse the same 'master' and 'develop' backend environments as in our original "Amplify Console"-App.

To do this, we have to disconnect the master branch in App settings: General:

Once done, we can connect our 'master' and 'develop' branches to the equally named environments.

One-Click Deploy the second app

The build-settings are still building our first app. To change this, we go to App settings: Build settings to see, that we have to grant access to our GitHub repository.

And this is where we realize that we can actually deploy repositories from others without the necessity to fork them first!

To build and deploy the second frontend app, we edit two lines in the yaml file:

version: 0.1
backend:
  phases:
    build:
      commands:
        - '# Execute Amplify CLI with the helper script'
        - amplifyPush --simple
frontend:
  phases:
    preBuild:
      commands:
        - npm ci
    build:
      commands:
        - npm run build:second # <-- Change to second app
  artifacts:
    baseDirectory: dist/apps/second-app # <-- Change to second app
    files:
      - '**/*'
  cache:
    paths:
      - node_modules/**/*

After saving the build settings and hitting the Redeploy this version button in both branches, we're all set!

Violà!

Adding another frontend app works with the help of the one-click-deploy-button! When we push new code to either our 'master' or 'develop' branch, both apps will build and deploy everything.

Playfully exploring new features of Amplify Console showed us a way we can add further frontend apps to our backend. Apps like admin-consoles, customer-views, support-tickets, manager-charts and so on are possible. Even if we might find this route too complicated or limiting in the future, we still have the means to use the build-settings in our first-app to install, build and deploy anything, like we were used to before Amplify Console came out.

Recap

We feel confident to pursue further development with AWS Amplify. We understand the connection between our repo, the branches and the backend environments. Onboarding new team mates will be a joy.

We could have used the pipeline functionality of our favorite git provider to continuously deploy our static websites to S3 and CloudFront and manually writing the commands to deploy the backends. We would still benefit from the typical AWS features like

Globally available CDN hosting
Free SSL certificates
Serverless backends

Having created and built several build pipelines in the past, we can appreciate the simplicity of using Amplify Console to host our serverless full stack app, but what else have we gained?

Easy custom domain setup with Route53
Atomic deployments
CDN invalidation
Password protected feature branches
Screenshots of the app on different mobile resolutions

Ok, we're getting excited - time to calm down, close our eyes, picture a big smile on our face and take a deep breath or two...

AWS Amplify Auth & Angular RxJS Simple State Management

Michael Gustmann — Tue, 02 Apr 2019 15:54:25 +0000

Recent updates to the aws-amplify hub make it easier to listen to (AWS Cognito) auth state changes without using the aws-amplify-angular package. If we are not using the prebuild UI-components of that package, we might save a few hundred KB by just importing the modules we need.

But even if we use aws-amplify-angular package, we can take a look at how we can manage our authentication and user state in a very Angular'esque way without any state management libraries, like Redux, NGRX, apollo-link-state, MobX, Akita or NGXS

One of the features of Angular is their dependency injection system. We can define tree-shakable injectables to use in any of our components or other injectables. It's a good place to store the state of feature modules in one or more services.

If our app grows more complex there might come a time, where we feel the need to use a single store to manage our state. We might be interested in better developer ergonomics with tools like Redux DevTools or reap the benefits of clearly defined patterns of the library of our choice.

But until this time comes or if we decide, that we want more than one store, this might be a good pattern to use in our Angular apps.

RxJS BehaviorSubject

Angular has a peer dependency on RxJS and uses it in some of their packages. Learning Angular usually entails learning RxJS as well. RxJS offers a Subject, which is an Observable and an Observer in one. The BehaviorSubject additionally stores the last state and can't be created without an initial state. This is pretty ideal for our state management needs, because the subscriber gets the last emitted value immediately after subscribing to the observable. Having an initial state is common to many state management libraries and removes the need to check against null or undefined.

If we want to protect the state against changes from outside, we have a way to make it private and only expose the observable to the public.

Auth-Service

To create a service using the Angular CLI type

$ ng g s auth

This will generate a service auth.service.ts in our app.

We need to import our service somewhere, so the bundler includes it. Since this is a app-wide service that should run all the time, we can simply inject the service in app.module.ts:

@NgModule({
  /*...*/
})
export class AppModule {
  constructor(_auth: AuthService) {
    console.log('starting AppModule');
  }
}

This will instantiate the AuthService as a singleton on the start of the app.

In a real-world app, we would probably want to move the service in a separate module (ie. auth.module.ts) and inject it in its constructor. Importing that module in app.module.ts would have the same effect.

This is our implementation of auth.service.ts:

import { Injectable } from '@angular/core';
import Auth from '@aws-amplify/auth';
import { Hub } from '@aws-amplify/core';
import { BehaviorSubject } from 'rxjs';
import { map } from 'rxjs/operators';

export interface AuthState {
  isLoggedIn: boolean;
  username: string | null;
  id: string | null;
  email: string | null;
}

const initialAuthState = {
  isLoggedIn: false,
  username: null,
  id: null,
  email: null
};

@Injectable({
  providedIn: 'root'
})
export class AuthService {
  private readonly _authState = new BehaviorSubject<AuthState>(
    initialAuthState
  );

  /** AuthState as an Observable */
  readonly auth$ = this._authState.asObservable();

  /** Observe the isLoggedIn slice of the auth state */
  readonly isLoggedIn$ = this.auth$.pipe(map(state => state.isLoggedIn));

  constructor() {
    // Get the user on creation of this service
    Auth.currentAuthenticatedUser().then(
      (user: any) => this.setUser(user),
      _err => this._authState.next(initialAuthState)
    );

    // Use Hub channel 'auth' to get notified on changes
    Hub.listen('auth', ({ payload: { event, data, message } }) => {
      if (event === 'signIn') {
        // On 'signIn' event, the data is a CognitoUser object
        this.setUser(data);
      } else {
        this._authState.next(initialAuthState);
      }
    });
  }

  private setUser(user: any) {
    if (!user) {
      return;
    }

    const {
      attributes: { sub: id, email },
      username
    } = user;

    this._authState.next({ isLoggedIn: true, id, username, email });
  }
}

We define our public interface of our state in AuthState and create an initial object initialAuthState.
We decided to use the default providedIn property to make this service tree-shakable (optional)
We define and initialize a private BehaviorSubject and expose it as an observable
We write a private function setUser(user: any) to take a cognito user object, desctructure it and create the next state out of it
We create an optional way of exposing a slice of the state, the isLoggedIn boolean value of our state object.
In the constructor we request the current user by writing Auth.currentAuthenticatedUser() on instantiation of this injectable and emitting either the user object or the initialAuthState
We start listening on the hub channel named 'auth' and construct the next state on whether the user is signed in or not

That's it! We can subscribe to state changes anywhere in our where we inject this service.

Using our auth state service

To access our state, we inject the service and subscribe to any of the exposed observables.

// ... imports
@Component({
  selector: 'my-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent implements OnInit {
  isLoggedIn = false;
  user: { id: string; username: string; email: string };

  constructor(private authService: AuthService) {}

  ngOnInit(): void {
    this.authService.isLoggedIn$.subscribe(
      isLoggedIn => (this.isLoggedIn = isLoggedIn)
    );

    this.authService.auth$.subscribe(({ id, username, email }) => {
      this.user = { id, username, email };
    });
  }
}

I hope this helps to see how to handle state in Angular in a modular and simple way by moving it into a service and informing anyone interested of changes with the help of a RxJS BehaviorSubject.

Creating Angular UI components and connecting them to the GraphQL AppSync API - Part 2

Michael Gustmann — Wed, 27 Mar 2019 17:43:08 +0000

In the first part of the series we setup a workspace, configured AWS cloud resources in a shared library, added Authentication to protect private data, generated typings for the GraphQL API, wrote a mutation helper wrapper function and discussed various topics around this.

Getting started with a Angular/NX workspace backed by an AWS Amplify GraphQL API - Part 1

Michael Gustmann ・ Mar 26 '19

#angular #graphql #awsamplify #awsappsync

We were busy, but until this point, we still haven't done much towards our UI. Let's create some components using the Angular CLI in this second part!

I will omit some styles for brevity reasons, but you can find them on GitHub.

BeaveArony / amplify-angular-nx-todo

Angular with NX multi-app setup powered by an AWS Amplify GraphQL Backend

Getting started

To deploy this project, hit this button ...

... or go through the following steps:

Clone this repo

git clone https://github.com/BeaveArony/amplify-angular-nx-todo.git

Change into the directory & install the dependencies

npm install

# or

yarn

Initialize the Amplify project

amplify init

Create the resources in your account

amplify push

Start the app

npm start

View on GitHub

Building the UI

The todo-page that wraps the whole UI. The component, that will be imported by app-component and is going to be the only container/smart component of this lib
The form to create new todos
The filter component to switch visibility on the completed property
The todo-list component with its todo-item components
A component to show error messages

ng g c --project=todo-ui --export  todo-page
ng g c --project=todo-ui -c=OnPush create-form
ng g c --project=todo-ui -c=OnPush todo-list
ng g c --project=todo-ui -c=OnPush todo-item
ng g c --project=todo-ui -c=OnPush filter-bar
ng g c --project=todo-ui -c=OnPush error-alert

I would like to style the app like the AWS authenticator component. To help with the styling, replace the content of apps/todo-app/src/styles.css with this:

/* You can add global styles to this file, and also import other style files */
@import '~aws-amplify-angular/theme.css';

html,
body {
  height: 100%;
}
body {
  margin: 0;
  background-color: var(--color-accent-brown);
}

/* Amplify UI fixes */
.amplify-form-input {
  width: calc(100% - 1em);
  box-sizing: border-box;
}
.amplify-alert {
  margin-top: 2em;
}
.amplify-greeting > * {
  white-space: nowrap;
}
.amplify-greeting-flex-spacer {
  width: 100%;
}

.card,
.amplify-authenticator {
  width: var(--component-width-desktop);
  margin: 1em auto;
  border-radius: 6px;
  background-color: var(--color-white);
  box-shadow: var(--box-shadow);
}
.card-container {
  width: 400px;
  margin: 0 auto;
  padding: 1em;
}

@media (min-width: 320px) and (max-width: 480px) {
  .card,
  .amplify-authenticator {
    width: var(--component-width-mobile);
    border-radius: 0;
    margin: 0.5em auto;
  }
  .card-container {
    width: auto;
  }
  .amplify-alert {
    left: 4%;
  }
}

We are setting up html / body and card classes that look very similar to the Amplify Components styles. We are reusing the CSS variables imported earlier. The amplify-authenticator has rounded corners in the mobile view, so we are changing this in the media-query as well.

We are also fixing the styling of the html input tags, because they are extending too far to the right in mobile.

There are still some styling issues with the amplify angular authenticator component, but I think it's good enough for a simple drop in UI component to support the general sign-up/sign-in procedure.

Todo-page

The todo-page component is the starting point of the todo-ui module. It is the only component exported, leaving all other components internal to this lib. We could introduce routing at a later stage and even lazy load this module for a snappier start of our app.

This component is also going to be the only container component handling the API communication and providing data to the other presentational components in this module. Since we haven't written any code in our components yet, we compose our view with what we got so far. All components were generated by the ng generate commands and can be referenced in our HTML markup.

Change libs/todo-ui/src/lib/todo-page/todo-page.component.html to this

<div class="card">
  <div class="card-container">
    <my-create-form></my-create-form>
    <my-filter-bar></my-filter-bar>
  </div>
</div>
<my-error-alert></my-error-alert>
<div class="card">
  <div class="card-container"><my-todo-list></my-todo-list></div>
</div>

and import the todo-ui module in our root app module apps/todo-app/src/app/app.module.ts like this

// ... other imports
import { TodoUiModule } from '@my/todo-ui';

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule, AppsyncModule, TodoUiModule],
  bootstrap: [AppComponent]
})
export class AppModule {}

To display the todo-page in the app change apps/todo-app/src/app/app.component.html to this

<my-todo-page></my-todo-page>

So far this is just the starting point for our UI. You can run the app with npm start and glance on a basic skeleton.

AWS Authenticator UI-Component

AWS Amplify provides several drop-in UI components for Angular/Ionic, React and Vue. We can choose between

Authenticator
Photo Picker
Album
Chatbot

To add the AWS Authenticator to our app change apps/todo-app/src/app/app.component.html to both include it and the todo-page component.

<amplify-authenticator></amplify-authenticator>
<my-todo-page *ngIf="hydrated && isLoggedIn"></my-todo-page>

And the content of apps/todo-app/src/app/app.component.ts

import { Component, OnInit } from '@angular/core';
import { AppSyncClient } from '@my/appsync';
import { AmplifyService } from 'aws-amplify-angular';

@Component({
  selector: 'my-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent implements OnInit {
  hydrated = false;
  isLoggedIn = false;

  constructor(private amplifyService: AmplifyService) {}

  ngOnInit(): void {
    AppSyncClient.hydrated().then(client => (this.hydrated = !!client));
    this.amplifyService.authStateChange$.subscribe(authState => {
      if (authState.state === 'signedOut' && this.isLoggedIn) {
        AppSyncClient.clearStore().then(() =>
          console.log('User signed out, store cleared!')
        );
      }
      this.isLoggedIn =
        authState.state === 'signedIn' || authState.state === 'confirmSignIn';
    });
  }
}

The AppSyncClient persists its redux store, so we should render the todo-ui only when the store is rehydrated. AppSyncClient offers a AppSyncClient.hydrated() function we can use for this.
The AmplifyService offers an Observable authStateChange$ we can subscribe to and only show the todo-ui when a user is logged In. To not leave any cached items around when a user signs out we clear the store on that event. The <my-todo-page> component is hidden while the client is not rehydrated or while no user is signed in with the *ngIf directive. The <amplify-authenticator> is showing a greeting message by default and a link to log out when a user is logged in, so we don't need to hide it.

We can configure this component by passing in a config-object

<amplify-authenticator [signUpConfig]="signUpConfig"></amplify-authenticator>

or change the framework to Ionic and hide certain parts, like the SignOut link

<amplify-authenticator
  framework="ionic"
  [hide]="['SignOut']"
></amplify-authenticator>

Creating the presentational UI

We start with the presentational components, that do not use any API and get their data only through @Input() and emit events through @Output() using Angular's EventEmitter. Later we
connect them in the todo-page component.

model

Create a file libs/todo-ui/src/lib/model.ts to keep types specific to this UI-Library. In our case we only type our Todo's visibility states.

export type TodoFilterType = 'SHOW_ALL' | 'SHOW_ACTIVE' | 'SHOW_COMPLETED';

create-form component

This create-form component emits a new todo name when the reactive form is submitted. We also disable the submit button, when the required text field is empty. Once we emitted a new todo, we clear the input field. Using the form tag together with the submit button gives us the advantage to just hit 'Enter' after typing our todo text.

libs/todo-ui/src/lib/create-form/create-form.component.html

<form [formGroup]="form" (ngSubmit)="createTodo()">
  <input type="text" formControlName="todoName" required />
  <button type="submit" [disabled]="!form.valid">+</button>
</form>

libs/todo-ui/src/lib/create-form/create-form.component.ts

import {
  ChangeDetectionStrategy,
  Component,
  EventEmitter,
  Output
} from '@angular/core';
import { FormControl, FormGroup } from '@angular/forms';

@Component({
  selector: 'my-create-form',
  templateUrl: './create-form.component.html',
  styleUrls: ['./create-form.component.css'],
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class CreateFormComponent {
  @Output() created = new EventEmitter<string>();
  form = new FormGroup({ todoName: new FormControl('') });

  createTodo() {
    const todoName = this.form.value.todoName.trim();
    if (todoName) {
      this.created.emit(todoName);
      this.form.setValue({ todoName: '' });
    }
  }
}

filter-bar component

The filter-bar component holds a bar of toggle buttons to change the visibility of the todo-list. The selected button will be disabled and styled so that it looks active. We can use CSS variables from the Amplify Angular Theme for that.

libs/todo-ui/src/lib/filter-bar/filter-bar.component.html

<nav>
  <button
    *ngFor="let btn of buttons"
    (click)="filter(btn.value)"
    [disabled]="currentFilter === btn.value"
  >
    {{ btn.name }}
  </button>
</nav>

libs/todo-ui/src/lib/filter-bar/filter-bar.component.css

nav {
  margin-top: 0.5em;
  display: flex;
  justify-content: space-between;
}
button {
  border: 1px solid var(--color-blue);
  height: var(--button-height);
  width: 128px;
  color: var(--color-blue);
  text-transform: uppercase;
  cursor: pointer;
}

button:hover {
  background-color: var(--color-accent-blue);
}

button:disabled {
  background-color: var(--color-blue);
  color: white;
  border: none;
  cursor: auto;
}

libs/todo-ui/src/lib/filter-bar/filter-bar.component.ts

import {
  ChangeDetectionStrategy,
  Component,
  EventEmitter,
  Output
} from '@angular/core';
import { TodoFilterType } from '../model';

@Component({
  selector: 'my-filter-bar',
  templateUrl: './filter-bar.component.html',
  styleUrls: ['./filter-bar.component.css'],
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class FilterBarComponent {
  @Output() filtered = new EventEmitter<TodoFilterType>();

  currentFilter: TodoFilterType = 'SHOW_ALL';
  buttons: { value: TodoFilterType; name: string }[] = [
    { value: 'SHOW_ALL', name: 'All' },
    { value: 'SHOW_ACTIVE', name: 'Active' },
    { value: 'SHOW_COMPLETED', name: 'Completed' }
  ];

  filter(query: TodoFilterType) {
    this.currentFilter = query;
    this.filtered.emit(this.currentFilter);
  }
}

We emit a filter query string depending on the selected button. The parent todo-page component will listen to this and pass the query to its child todo-list component as Input, so it can filter the list on the completed property.

todo-item component

The todo-list renders a list of todo-item components. These items are responsible to display the provided input values. We use HTML entities as icons. When clicking on the delete icon we emit the deleted event and when clicked on the rest of this item a toggled event is emitted to change the completed property of this todo item.

libs/todo-ui/src/lib/todo-item/todo-item.component.html

<div class="item" *ngIf="todo">
  <div
    class="checkmark"
    [class.checked]="todo.completed"
    (click)="toggled.emit()"
  >
    {{ todo.completed ? '✔' : '🗸' }}
  </div>
  <div
    class="content"
    [ngStyle]="{ textDecoration: todo.completed ? 'line-through' : 'none' }"
    (click)="toggled.emit()"
  >
    {{ todo.name }}
  </div>
  <div class="delete" (click)="deleted.emit()">✗</div>
</div>

libs/todo-ui/src/lib/todo-item/todo-item.component.ts

import {
  ChangeDetectionStrategy,
  Component,
  EventEmitter,
  Input,
  Output
} from '@angular/core';
import { ListTodos_listTodos_items } from '@my/appsync';

@Component({
  selector: 'my-todo-item',
  templateUrl: './todo-item.component.html',
  styleUrls: ['./todo-item.component.css'],
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class TodoItemComponent {
  @Input() todo: ListTodos_listTodos_items;
  @Output() toggled = new EventEmitter<boolean>();
  @Output() deleted = new EventEmitter<boolean>();
}

todo-list component

The todo-list component renders each todo item through the previously created todo-item component. To react on the Inputs to filter the todos we use getters and setters. Component life cycle hook ngOnChanges would also work here.

The visibility filter is the only client state in our app and is managed in our components. Apollo Client, which is used by AWSAppSyncClient under the hoods, keeps the data in a normalized redux store.

We have many choices here, when we think about our architecture:

Manage the state in an Angular provider using a Behavior Subject
Write actions and reducers to extend the underlying redux store
Use a separate state management library for our client state
Extend Apollo Client to use apollo-link-state, which offers querying and mutating our local state with GraphQL operations
Keep it in our components
...

Extending the underlying redux store is a little bit risky, since the AWSAppSyncClient can change the implementation internals at any time. We would get stuck with a certain version or need to refactor our client state.

For this simple app using a Behavior Subject is probably the easiest. For non-trivial apps I would use a state management library. Using apollo-link-state feels like the cleanest solution, having local and remote state in one place.

<!-- libs/todo-ui/src/lib/todo-list/todo-list.component.html -->
<my-todo-item
  *ngFor="let todo of visibleTodos"
  [todo]="todo"
  (toggled)="toggled.emit(todo)"
  (deleted)="deleted.emit(todo)"
></my-todo-item>
<div *ngIf="!visibleTodos || visibleTodos?.length === 0">No todos</div>

// libs/todo-ui/src/lib/todo-list/todo-list.component.ts
import {
  ChangeDetectionStrategy,
  Component,
  EventEmitter,
  Input,
  Output
} from '@angular/core';
import { ListTodos_listTodos_items } from '@my/appsync';
import { TodoFilterType } from '../model';

@Component({
  selector: 'my-todo-list',
  templateUrl: './todo-list.component.html',
  styleUrls: ['./todo-list.component.css'],
  changeDetection: ChangeDetectionStrategy.Default
})
export class TodoListComponent {
  @Output() toggled = new EventEmitter<ListTodos_listTodos_items>();
  @Output() deleted = new EventEmitter<ListTodos_listTodos_items>();

  private _filter: TodoFilterType;
  private _todos: ListTodos_listTodos_items[];

  @Input()
  public get filter(): TodoFilterType {
    return this._filter;
  }
  public set filter(value: TodoFilterType) {
    this._filter = value;
    this.visibleTodos = this.getVisibleTodos(this.todos, value);
  }

  @Input()
  public get todos(): ListTodos_listTodos_items[] {
    return this._todos;
  }
  public set todos(value: ListTodos_listTodos_items[]) {
    this._todos = value;
    this.visibleTodos = this.getVisibleTodos(value, this.filter);
  }

  visibleTodos: ListTodos_listTodos_items[];

  private getVisibleTodos(
    todos: ListTodos_listTodos_items[],
    filter: TodoFilterType
  ) {
    switch (filter) {
      case 'SHOW_ALL':
        return todos;
      case 'SHOW_COMPLETED':
        return todos.filter(t => t.completed);
      case 'SHOW_ACTIVE':
        return todos.filter(t => !t.completed);
      default:
        return todos;
    }
  }
}

Whenever either the filter query or the provided todos change, we calculate the visible todos and store them in visibleTodos.

error-alert component

This reusable component receives an error message and emits an event if the close button is clicked.

<div class="card" *ngIf="errorMessage">
  <div class="card-container">
    <div class="flex-row">
      <span class="icon">⚠</span>
      <div class="msg">{{ errorMessage }}</div>
      <a class="close" (click)="closed.emit()">×</a>
    </div>
  </div>
</div>

.flex-row {
  display: flex;
  justify-content: space-between;
}
.close {
  color: var(--color-gray);
  font-size: 32px;
  cursor: pointer;
}
.msg {
  width: 100%;
  margin: 10px 2em;
}
.icon {
  color: var(--red);
  font-size: 32px;
  width: 38px;
}

import {
  ChangeDetectionStrategy,
  Component,
  Input,
  Output,
  EventEmitter
} from '@angular/core';

@Component({
  selector: 'my-error-alert',
  templateUrl: './error-alert.component.html',
  styleUrls: ['./error-alert.component.css'],
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class ErrorAlertComponent {
  @Input() errorMessage: string | null = null;
  @Output() closed = new EventEmitter();
}

Watching todos

Now that we have build our presentational components, we can come back to our wrapping component, that handles all the events, interacts with our API and displays possible errors.

// imports ...
@Component({
  selector: 'my-todo-page',
  templateUrl: './todo-page.component.html',
  styleUrls: ['./todo-page.component.css'],
  changeDetection: ChangeDetectionStrategy.Default
})
export class TodoPageComponent implements OnInit {
  todos: ListTodos_listTodos_items[];
  errorMessage: string | null = null;

  ngOnInit() {
    AppSyncClient.watchQuery<ListTodos, ListTodosVariables>({
      query: LIST_TODOS
    }).subscribe(todoList => {
      this.todos = todoList.data
        ? todoList.data.listTodos.items.sort((a, b) =>
            a.createdOnClientAt.localeCompare(b.createdOnClientAt)
          )
        : [];
    }, this.handleError);
  }

  handleError = (err: ApolloError) => {
    this.errorMessage = err.message;
  };
}

We listen to any local changes of our todos in ngOnInit life cycle hook. Using watchQuery() for this, informs our component of local operations like adding or removing items. To listen to remote changes, we would need to set up a GraphQL subscription. Fortunately watchQuery() is generic so we can specify the previously generated query and variables types. This offers us complete IntelliSense in the subscribe block! If we receive data, we sort them on the client on the createdOnClientAt property.

watchQuery() returns a zen-observable, not one from rxjs! So, we can't use the async pipe here. We could write a converter or simply use apollo-angular to do this for us.

We have to think about change detection here. If this component would use the OnPush ChangeDetectionStragy, our UI would not react to changes coming from this observable. We can either change to the Default strategy like above or inject ChangeDetectorRef to invoke markForCheck() in the subscribe block.

Something like this, focussing on the changes:

import { ChangeDetectorRef } from '@angular/core';
// ...
@Component({
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class TodoPageComponent {
  constructor(private cd: ChangeDetectorRef) {}

  ngOnInit() {
    AppSyncClient.watchQuery<ListTodos, ListTodosVariables>({
      query: LIST_TODOS
    }).subscribe(todoList => {
      // ...
      this.cd.markForCheck();
    });
  }
}

Angular's async pipe would handle this automatically for us!

Change one line in the html file to pass our todos to the todo-list component:

<my-todo-list [todos]="todos"></my-todo-list>

Interact with the error-alert component by passing the error message and setting it to null when the closed event emits

<my-error-alert
  (closed)="errorMessage = null"
  [errorMessage]="errorMessage"
></my-error-alert>

Creating todos

To have items to display in our list, we need to be able to create a new todo. So, let's implement a handler in our component class and pass it the event payload of the created event of the create-form component.

<my-create-form (created)="create($event)"></my-create-form>

// ...
export class TodoPageComponent {
  // ...
  create(name: string) {
    executeMutation<CreateTodoVariables, CreateTodo_createTodo>({
      mutation: CREATE_TODO,
      variablesInfo: {
        input: {
          name,
          completed: false,
          createdOnClientAt: new Date().toISOString()
        }
      },
      cacheUpdateQuery: [LIST_TODOS],
      typename: 'Todo'
    }).catch(this.handleError);
  }
}

Here happens quite a lot in a single statement. Let's break it down!

We invoke our generic helper function executeMutation() and pass it an object. This object needs the following properties:

mutation: The graphql mutation operation
variablesInfo: The input object we want to send to our API
cacheUpdateQuery: A list of queries we would like to be updated in our cache
typename: The value of the __typename property

Since we add a new item to our list, we need to update the LIST_TODOS query in the cache. It's as simple as adding it to the cacheUpdateQuery's array. Doing this will invoke the watchQuery observable twice. First with an optimistic response using a temporary ID, like we would expect our API to respond if all goes well and finally with the actual result from the server.

If we would receive an error when trying to create the todo, the second call would not contain this new todo anymore, negating the optimistic UI update. Additionally, we are handling the error in the catch part of the returned promise and displaying it with our error-alert component. This way the user gets a hint of what just happened, even though the error message is quite technical.

Note, everything is type safe, even the typename string!

Updating a todo

To update the completed property of a todo, we listen to the toggled event of the todo-list component. We pass the payload to the toggle() function, destructuring it in the process.

<my-todo-list [todos]="todos" (toggled)="toggle($event)"></my-todo-list>

// ...
export class TodoPageComponent {
  // ...
  toggle({
    id,
    completed,
    createdOnClientAt,
    name
  }: ListTodos_listTodos_items) {
    executeMutation<UpdateTodoVariables, UpdateTodo_updateTodo>({
      mutation: UPDATE_TODO,
      variablesInfo: {
        input: {
          completed: !completed,
          id,
          createdOnClientAt,
          name
        }
      },
      cacheUpdateQuery: null,
      typename: 'Todo'
    }).catch(this.handleError);
  }
}

This looks very similar to the create mutation. We provide the updated item and this time we don't need to take care of updating the cache. Apollo Client is handling this automatically, so we can pass null or an empty array to cacheUpdateQuery.

ListTodos_listTodos_items looks pretty weird as an input type. It's the type of one item of the list, but I guess that's the price we have to pay when this gets generated automatically!

Deleting a todo

To delete a todo, we listen to the deleted event of the todo-list component. We pass the payload to the toggle() function, destructuring only the id.

<my-todo-list
  [todos]="todos"
  (toggled)="toggle($event)"
  (deleted)="delete($event)"
></my-todo-list>

// ...
export class TodoPageComponent {
  // ...
  delete({ id }: ListTodos_listTodos_items) {
    executeMutation<DeleteTodoVariables, DeleteTodo_deleteTodo>({
      mutation: DELETE_TODO,
      variablesInfo: {
        input: { id }
      },
      cacheUpdateQuery: [LIST_TODOS],
      typename: 'Todo'
    }).catch(this.handleError);
  }
}

Deleting an item from a list requires us to take care of the cache again.

Handling the filter

The only thing left is listening to the filter-bar component and passing the value to the todo-list component. We start with 'SHOW_ALL', but don't do anything else with the filter variable.

<my-filter-bar (filtered)="filter = $event"> </my-filter-bar>
<!-- ... -->
<my-todo-list
  [todos]="todos"
  [filter]="filter"
  (toggled)="toggle($event)"
  (deleted)="delete($event)"
></my-todo-list>

filter: TodoFilterType = 'SHOW_ALL';

That's it. Please take a look at this repo to see the complete source code.

Taking it for a spin

Let's run npm start to get a chance to admire our work. Here are a few things for you to play around with:

Create at least two users to see how each one has its own todos
Add new todos
Try out the responsive UI
Open the dev-tools and tick the offline checkbox, do a few operations and finally go online again.
Open the redux dev-tools (if installed) and inspect the outbox of redux-offline, the normalized entities of apollo client's InMemoryCache and the rehydration actions of redux-persist
Take a look at things stored in IndexedDB and the JWT in LocalStorage
Set a breakpoint in watchQuery() and observe the optimistic response in action
Change the name variable to null in create() and enjoy the Undo taking place in the list paired with the splendid error message displayed
Reload the app to appreciate the persisted cache
Login to the AWS management console and analyze the DynamoDB Table entries created

Recap

We created our UI with Angular components. The wrapping component orchestrates everything by connecting the presentational components, listening to changes in the cache and talking to the API using helpers we set up in Part 1.

In Part 3 we are going to explore how to add a CI/CD pipeline the easy way using the amplify console and even look at how to add a second frontend app.

Getting started with a Angular/NX workspace backed by an AWS Amplify GraphQL API - Part 1

Michael Gustmann — Tue, 26 Mar 2019 17:01:56 +0000

We are going to create a Todo app using Angular with the help of

Nx to help with a multi-app, multi-team project style
AWS Amplify CLI to create a fully featured backend, completely managed in code (infrastructure as code)
AWS AppSync JavaScript SDK An AppSync client using Apollo and featuring offline and persistence capabilities
AWS Amplify Angular Angular components and an Angular provider which helps integrate with the AWS-Amplify library

We are creating an offline-ready Todo-App backed by a GraphQL API and Authentication. We can expand on this app by adding further categories and features. But let's start simple.

You can take a look at the code in this repo.

Prerequisites

I'm assuming, that you have NodeJS version 8 or higher installed and that you have access to an AWS Account. The free tier is very generous during the first year and will probably cost you nothing.

Create a workspace

NX is a schematic on top of Angular CLI, that gives us tools to setup a workspace, where it is easy to share code between apps and to create boundaries to help working within a team or even multiple teams.

By separating out logic into modules these can be reused easily by just importing them like we are importing other npm packages. We don't need to publish any of those packages to some public or private repository. This saves us some headaches about running tests across different versions of each library and provides us a snapshot in our repo of all the parts working together.

With the AWS Amplify CLI we can even connect one or more cloud stacks to our workspace, so that we get 'Infrastructure as Code' of our backend going along with our frontend apps. It's not in the sense of having completely different products all put into the same repo. Rather thinking in terms of having a customer web- and separate mobile app, an admin portal, an electron desktop app for the support team, a manager reports app and so on... They all work with the same data in a way and would immensely profit from shared SDKs and public interfaces across libraries.

Even if you end up using just one app, where you include different domains or Lines of Businesses (LOB), it helps to structure the code base so that teams can work at the same time without worrying too much about the painful integration into production later.

We start by creating a workspace folder by executing the following command using npx, so that we don't have to globally install it

npx @nrwl/schematics amplify-graphql-angular-nx-todo

When asked, we answer some questions

? Which stylesheet format would you like to use? CSS

? What is the npm scope you would like to use for your Nx Workspace? my

? What to create in the new workspace (You can create other applications and libraries at any point using 'ng g') empty

We named our workspace 'my' and it should be usually named after your organization or project, ie. 'myorg'.

We create an empty workspace, so that we can name our first application however we want. Otherwise it would get the name 'amplify-graphql-angular-nx-todo'.

Create an app

We decide to call our first app 'todo-app' (and it will be the only one for this post).

ng g app todo-app

? What framework would you like to use for the application? Angular

? In which directory should the application be generated?

? Which stylesheet format would you like to use? CSS

? Which Unit Test Runner would you like to use for the application? Jest

? Which E2E Test Runner would you like to use for the application? Cypress

? Which tags would you like to add to the application? (used for linting) app

This created two apps

todo-app
todo-app-e2e

The second app is an end-to-end test. The app is our actual app and we will try to only use it for orchestrating other modules as much as possible. Most of our code we will put in libs to reuse it in possible further apps in the future.

Create libs

Where do we put our code then? NX makes it easy to create new libs! We compose our app out of possibly many libs.

We need a lib for our backend stuff, let's call this lib appsync
We put our UI components into the lib todo-ui

So let's run the following commands to generate our desired libs:

ng g lib appsync --tags=shared --framework=angular --unitTestRunner=jest --style=css
ng g lib todo-ui --tags=ui --framework=angular --unitTestRunner=jest --style=css

Create the AWS backend

The (AWS Amplify CLI)[https://github.com/aws-amplify/amplify-cli] makes it very easy to create a serverless backend in the AWS cloud. Everything is defined in code and can be checked in our source control. It elevates the need to write lengthy CloudFormation templates that describe our cloud resources. A few simple commands will spin up entire cloud stacks using team resources or creating one-of developer sand-boxes to try out new features.

Install the Amplify CLI globally (if haven't done so previously) by running those commands:

npm install -g @aws-amplify/cli
amplify configure

If you are completely new to AWS Amplify, you should check out the docs of how to configure the Amplify CLI

Here we actually install the AWS Amplify CLI globally instead of using npx! We will use the amplify command quite often.

Install the Amplify JavaScript dependencies

npm i aws-amplify aws-amplify-angular

Adjusting the angular app to Amplify's SDK

There are a few things we need to change in order for us to use the AWS Amplify SDK in an Angular environment:

Tell typescript about the window.global variable
Add 'node' to tsconfig
Write a script to rename aws-exports.js to aws-exports.ts.

Open apps/todo-app/src/polyfills.ts and add the following line at the top of the file

(window as any).global = window;

The node package needs to be included in apps/todo-app/tsconfig.app.json

{
  "compilerOptions": {
    "types": ["node"]
  }
}

AWS Amplify comes with an UI-Library. We might just as well reuse the styles from those components and build upon them. Add the following lines to apps/todo-app/src/styles.css:

/* You can add global styles to this file, and also import other style files */
@import '~aws-amplify-angular/theme.css';

We connect our project or branch to a cloud resource stack by running

amplify init

Using NX we need to change quite a few defaults:

? Enter a name for the project amplifynx
? Enter a name for the environment master
? Choose your default editor: Visual Studio Code
? Choose the type of app that you're building javascript
Please tell us about your project
? What javascript framework are you using angular
? Source Directory Path: libs/appsync/src/l
? Distribution Directory Path: dist/apps/todo-app
? Build Command: npm run-script build
? Start Command: npm run-script start
Using default provider awscloudformation

? Do you want to use an AWS profile? Yes
? Please choose the profile you want to use my.aws.profile
⠇ Initializing project in the cloud...

We named our cloud environment master, corresponding to our current git branch master. We can easily add further branches, like develop and create equally named environments (stacks) in the cloud.

We set the Source Directory Path to our previously created lib named appsync so that the automatically generated file aws_exports.js will land in this folder by default. This way we can share our cloud config with different apps by just importing this lib.

The Distribution Directory Path points to the dist output of a single app, which is only important, if we use the amplify CLI commands to build or serve the app or if we connect our app to Amplify Console. The latter makes it very easy to create a CI/CD Pipeline by just connecting a GIT branch to a deployment.

You will notice a new top-level folder named amplify. Most of the files created in this folder were added to .gitignore. The rest of the files can and should be added to version control and can be shared with your team. If you plan to make your repo public you should also add amplify/team-provider-info.json to .gitignore.

Let's add our first category `auth`!

amplify add auth

I like to change the default configuration to soften the password policy and provide a custom email subject text, but you can choose the defaults if you like and later change any of those settings by running

amplify auth update

To create these auth resources in the cloud run

amplify push

You will see

Current Environment: master

| Category | Resource name | Operation | Provider plugin   |
| -------- | ------------- | --------- | ----------------- |
| Auth     | cognitonxtodo | Create    | awscloudformation |
? Are you sure you want to continue? (Y/n)

And after a while you will find the newly created Cognito user pool when you log in to your AWS console.

This command will take you there:

amplify console auth

Rename aws-exports.js

The amplify push command should have generated a file: libs/appsync/src/lib/aws-exports.js, which we should rename to aws-exports.ts to easily import the config in other typescript files. To automate this we use the scripts section in package.json. Now each time we either serve or build our app the file is renamed.

{
  "start": "npm run rename:aws:config || ng serve; ng serve",
  "build": "npm run rename:aws:config || ng build --prod; ng build --prod",
  "rename:aws:config": "cd libs/appsync/src/lib && [ -f aws-exports.js ] && mv aws-exports.js aws-exports.ts || true"
}

We should also add this renamed file to .gitignore, so change aws-export.js to aws-exports.*s.

Adding a GraphQL API

If you have ever written a GraphQL API before you will appreciate the simplicity of creating one by just typing a few lines:

amplify add api

? Please select from one of the below mentioned services GraphQL

? Provide API name: amplifynx

? Choose an authorization type for the API Amazon Cognito User Pool

Use a Cognito user pool configured as a part of this project

? Do you have an annotated GraphQL schema? No

? Do you want a guided schema creation? Yes

? What best describes your project: Single object with fields (e.g., “Todo” with ID, name, description)

? Do you want to edit the schema now? Yes

This will open your previously configured editor with a sample Todo schema:

type Todo @model {
  id: ID!
  name: String!
  description: String
}

We don't want the description, but would like the completed status of our todos to be tracked.
At first to not worry too much about offline and sorting in the backend we can add a createdOnClientAt timestamp to sort the todos on the client. AppSync adds createdAt and updateAt timestamps by default, which we could use in the schema, but it will mess with our todo-list when we queue up several todos while we are offline and reconnect.

To explain this a little:

Say we only rely on the createdAt property to sort and we add todo-1 and todo-2 while offline. These get added to our outbox. They are sorted correctly, because we add a timestamp when we create each of those todos. Once we are online, todo-1 will be sent to the server and will receive a new createdAt timestamp on the server, since it was created there. This timestamp is at a later point in time than todo-2's timestamp. So todo-1 will jump to position 2 until todo-2 was transmitted. After todo-2 was sent to the server, getting a new timestamp, it will jump back to position 2 again. We will see a short reordering happen in our client.

The createdOnClientAt property is not touched on the server.

Change the schema to this and save:

type Todo @model @auth(rules: [{ allow: owner }]) {
  id: ID!
  name: String!
  completed: Boolean!
  createdOnClientAt: AWSDateTime!
}

We added @auth(rules: [{allow: owner}]) to the Todo type to only show the todos of each logged in user. This will automatically add an owner field to each todo in the underlying todo table in DynamoDB.

What happened behind the scenes?

When you look into the amplify/backend/api/{angularnx}/build directory, you will find an oppiniated and enhanced GraphQL schema by the AWS Amplify team. It generated all types of CRUD operations and Input objects with filtering and pagination automatically! By just writing six lines of annotated graphql we get 116 lines of graphql best practices out of the box! That's just dandy!

Upload the API

When we decide to push our API for the first time we get asked a few questions about generating code and where to place it. Choose angular as language target and leave the rest as default!

amplify push

Current Environment: master

| Category | Resource name | Operation | Provider plugin   |
| -------- | ------------- | --------- | ----------------- |
| Api      | amplifynx     | Create    | awscloudformation |
| Auth     | cognitonxtodo | No Change | awscloudformation |
? Are you sure you want to continue? Yes

? Do you want to generate code for your newly created GraphQL API Yes

? Choose the code generation language target angular

? Enter the file name pattern of graphql queries, mutations and subscriptions (src/graphql//_.graphql)

_? Enter the file name pattern of graphql queries, mutations and subscriptions*_ src/graphql/API.service.ts

_*? Do you want to generate/update all possible GraphQL operations - queries, mutations and subscriptions*** Yes

⠋ Updating resources in the cloud. This may take a few minutes...

There is a bug when trying to use another directory, like our lib folder, so just leave the default paths src/graphql/*! Otherwise the service or types will end up in our lib and be pretty much empty and all *.graphql files will be in the default location.

Amplify Code Generator

We get two choices when we decide to generate code:

angular
typescript

1. angular

If we choose angular as the target (which we do in our example), we get a single file with all the typescript types and an angular service. This service uses the amplify SDK to connect to the API. It's not really useful to us, since we decided to use the AppSync SDK as our client instead to connect to our cloud resources to get offline and persistance out of the box. We won't use the types nor the service directly, but the operations defined in the service can provide a good starting point to write our own queries and mutations.

When choosing angular also generates queries.graphql, mutations.graphql, subscriptions.graphql and an introspection schema schema.json. This is very useful as we will see later on.

2. typescript

This generates *.ts files with all queries, mutations and subscriptions exported as strings.

It also generates a file API.ts that defines all the types.

I don't like this option as much as the other generators we will explore later. Here is an example generated by the typescript option:

export type CreateTodoMutation = {
  createTodo: {
    __typename: 'Todo';
    id: string;
    name: string;
    completed: boolean;
    createdOnClientAt: string;
  } | null;
};

It's correct to have the nested createTodo property, but to type our Todo objects in code we need to do this:

const newTodo: CreateTodoMutation['createTodo'] = {
  /*...*/
};

My code editor will not help with the string part and it might introduce subtle errors in complex schemas.

Apollo Code Generator

Another possibility is to use the apollo client's code generator. I like its generated types. They are clean, short and the above code would look like this

const newTodo: CreateTodo_createTodo = {
  /*...*/
};

You can use it simply by executing

npx apollo-codegen generate src/graphql/*.graphql --schema src/graphql/schema.json --addTypename --target typescript --output libs/appsync/src/lib/api.types.ts

Installing it locally and running it gives me an error, because of a version mismatch of the dependency graphql used in aws-appsync. Using npx works great, though and I didn't worry about finding another solution for this. Using yarn might work better...

GraphQL Code Generator

One very important feature I am looking for in a code generator is the possibility to customize how the code is generated. { GraphQL } code generator is such a tool. It uses plugins to generate code for lots of different languages.

You could install it by running

npm i graphql-code-generator graphql-codegen-typescript-common graphql-codegen-typescript-client
graphql-codegen-fragment-matcher

Create a codegen.yml file:

overwrite: true
schema: src/graphql/schema.json
documents: src/graphql/*.graphql
generates:
  ./libs/appsync/src/lib/graphql.ts:
    plugins:
      - 'typescript-common'
      - 'typescript-client'
      - 'fragment-matcher'

and simply run

npm run gql-gen

This will generate a graphql.ts file in our lib providing all the types organized in namespaces. If we would add another plugin targeting angular we would also get a service for each operation, that we could simply inject in our components.

Note, we will NOT be using this tool in our app

Choosing the code generator

I think using the apollo code generator is probably the middle choice. It's easy enough to use when you add it the package.json's scripts section and hook it up to the amplify push command:

{
  "generate": "npx apollo-codegen generate src/graphql/*.graphql --schema src/graphql/schema.json --addTypename --target typescript --output libs/appsync/src/lib/api.types.ts",
  "push": "amplify push && npm run generate"
}

Make sure to use angular (not typescript) as the target in the previous step when configuring amplify's codegen, so that the src/graphql/*.graphql files are generated.

The src/graphql folder is only used for code generation and should not be imported anywhere in our app!

Since everything in src/graphql is generated, we can also put it in .gitignore together with .graphqlconfig.yml.

src/graphql
.graphqlconfig.yml;

Writing our GraphQL operations

Our app needs to

Fetch our list of todos
Create a new todo
Update the completed status of a todo
Delete a todo

To make our operations reusable in different components or services, we put them in a file libs/appsync/src/lib/gql-operations.ts.

import gql from 'graphql-tag';

export const CREATE_TODO = gql`
  mutation CreateTodo($input: CreateTodoInput!) {
    createTodo(input: $input) {
      __typename
      id
      name
      completed
      createdOnClientAt
    }
  }
`;

export const LIST_TODOS = gql`
  query ListTodos($filter: ModelTodoFilterInput, $nextToken: String) {
    listTodos(filter: $filter, limit: 999, nextToken: $nextToken) {
      __typename
      items {
        __typename
        id
        name
        completed
        createdOnClientAt
      }
    }
  }
`;

export const UPDATE_TODO = gql`
  mutation UpdateTodo($input: UpdateTodoInput!) {
    updateTodo(input: $input) {
      __typename
      id
      name
      completed
      createdOnClientAt
    }
  }
`;

export const DELETE_TODO = gql`
  mutation DeleteTodo($input: DeleteTodoInput!) {
    deleteTodo(input: $input) {
      __typename
      id
    }
  }
`;

To not worry about fetching more todos and simplifying apollo's caching, we hard code the limit in listTodos to 999

Don't forget, that we have auto-generated code in src/graphql/API.service.ts so we can simply copy some of those statement and use them as our starting point. In a more advanced app with a deeply nested schema the generated operations will need to be adjusted on a per component need.

From a software architecture's point of view it would be better to create a new library called todo-data or todo-model and place the file there naming it todo-operations.ts. Then we could also add a facade which will be the only thing we would expose to the other libs. This data layer lib could also hold our local state using redux for example. Going this route would make our components simpler. We might expand on this in the future.

Setup the AppSync Client

Install the client, graphql-tag and optionally localforage

npm i aws-appsync graphql-tag localforage

It's time to modify libs/appsync/src/lib/appsync.module.ts to instantiate and configure the AppSync client.

Change the content of the file to this:

import { NgModule } from '@angular/core';
import Amplify, { Auth } from 'aws-amplify';
import { AmplifyAngularModule, AmplifyService } from 'aws-amplify-angular';
import AWSAppSyncClient, { AUTH_TYPE } from 'aws-appsync';
import * as localForage from 'localforage';
import config from './aws-exports';

Amplify.configure(config);

export const AppSyncClient = new AWSAppSyncClient({
  url: config.aws_appsync_graphqlEndpoint,
  region: config.aws_appsync_region,
  auth: {
    type: AUTH_TYPE.AMAZON_COGNITO_USER_POOLS,
    jwtToken: async () =>
      (await Auth.currentSession()).getIdToken().getJwtToken()
  },
  complexObjectsCredentials: () => Auth.currentCredentials(),
  cacheOptions: { addTypename: true },
  offlineConfig: { storage: localForage }
});

@NgModule({
  exports: [AmplifyAngularModule],
  providers: [AmplifyService]
})
export class AppsyncModule {}

We are creating the AWSAppSyncClient and exporting the instance, so we can use it elsewhere.
AmplifyService needs to be added to the providers array, since it does not use @Injectable({providedIn: 'root'}).

To persist our the AppSync store in IndexedDB rather than LocalStorage, we use the library localforage.

To hook it up, don't forget to add AppsyncModule to the imports array of apps/todo-app/src/app/app.module.ts.

Note: We are not using the Apollo-Angular client here. This would give us an injectable service we could use throughout our app and which wraps the underlying zen-observables with rxjs. This is not necessary though, as we will see building this app in angular.

AWSAppSyncClient uses quite a few libraries under the hood, which makes it difficult to exchange or add some of them. I haven't found a way to use apollo-link-state and apollo-angular-link-http together with AWSAppSyncClient while retaining all TypScript typings.
This means NO Angular HttpClient and features like interceptors when working directly with the AWSAppSyncClient!

Offline helpers

The AWS AppSync SDK offers helpers to build mutation objects to use with apollo-client. This makes it quite easy to work with an optimistic UI in bad network conditions and update the local InMemoryCache when changes happen in our app.

There are higher level helpers available for react, but when using other libraries, we need to use the lower level function buildMutation. This function needs an apollo-client instance for example, which we can abstract away in our own typescript functions. Since we have generated types for our API we can also use these to give us additional type safety when providing __typename strings.

I also find it easier to use a config object instead of using a long parameter list. Here are my TypeScript Offline Mutation Builders which you can put in a file libs/appsync/src/lib/offline.helpers.ts:

import { OperationVariables } from 'apollo-client';
import {
  buildMutation,
  CacheOperationTypes,
  CacheUpdatesOptions,
  VariablesInfo
} from 'aws-appsync';
import { DocumentNode } from 'graphql';
import { AppSyncClient } from './appsync.module';

export interface TypeNameMutationType {
  __typename: string;
}

export interface GraphqlMutationInput<T, R extends TypeNameMutationType> {
  /** DocumentNode for the mutation */
  mutation: DocumentNode;
  /** An object with the mutation variables */
  variablesInfo: T | VariablesInfo<T>;
  /** The queries to update in the cache */
  cacheUpdateQuery: CacheUpdatesOptions;
  /** __typename from your schema */
  typename: R['__typename'];
  /** The name of the field with the ID (optional) */
  idField?: string;
  /** Override for the operation type (optional) */
  operationType?: CacheOperationTypes;
}

/**
 * Builds a MutationOptions object ready to be used by the ApolloClient to automatically update the cache according to the cacheUpdateQuery
 * parameter
 */
export function graphqlMutation<
  T = OperationVariables,
  R extends TypeNameMutationType = TypeNameMutationType
>({
  mutation,
  variablesInfo,
  cacheUpdateQuery,
  typename,
  idField,
  operationType
}: GraphqlMutationInput<T, R>) {
  return buildMutation<T>(
    AppSyncClient,
    mutation,
    variablesInfo,
    cacheUpdateQuery,
    typename,
    idField,
    operationType
  );
}

export function executeMutation<
  T = OperationVariables,
  R extends TypeNameMutationType = TypeNameMutationType
>(mutationInput: GraphqlMutationInput<T, R>) {
  return AppSyncClient.mutate(graphqlMutation<T, R>(mutationInput));
}

Note, this might break with future versions of the appsync sdk

Export everything from our lib

To make it possible to import our types, graphql operations, helpers, appsync-client and amplify from our barrel we need to export them in the libs/appsync/src/index.ts file.

export * from './lib/appsync.module';
export * from './lib/api.types';
export * from './lib/gql-operations';
export * from './lib/offline.helpers';

To import them in our components we can simply write

import { /* ... */ } from '@my/appsync';

Recap

So far, we have setup our Angular multi-app workspace with NX, initialized AWS Amplify to give us a managed authentication service using AWS Cognito and generated a serverless GraphQL API using AWS AppSync. Just with a few CLI commands!

To make it possible to reuse our backend in more than one app, we imported and configured everything in a separate custom library.

Since GraphQL works with a schema we could even generate all typings automatically and copy query and mutation operations as a starting point for our own operational needs.

We also wrote some utility functions to help with the Apollo client-side cache in offline scenarios.

What to expect in part 2

In part 2 we will create a UI and use the stuff we created here to connect to our backend.

Creating Angular UI components and connecting them to the GraphQL AppSync API - Part 2

Michael Gustmann ・ Mar 27 '19

#angular #graphql #awsamplify #awsappsync

DEV Community: Michael Gustmann

Building Tailwind CSS in an Angular CLI project

Angular CLI

Tailwind CSS

Separating Tailwind CSS from the rest

Set it up

Create the Angular Project

Install dependencies

Initialize Tailwind CSS

Customize the build process

Configure angular.json

Make changes to the build section

Make changes to the serve section

Add the tailwind.scss file to the styles array

Summarized changes to angular.json

Test it out

Summary

AWS Amplify CLI, how to automatically add a user to a Cognito User Pool with a Lambda-Trigger

Handling Cognito-UserPool-Groups in our AWS Amplify CLI project

Custom CloudFormation templates

Generate Groups

Automatically add a User to a Cognito User Pool Group with a Lambda-Trigger on Sign-Up

Add a new Lambda Function

Add IAM Policy to allow adding user to group

Without parameters

With parameters and least privileges

Add Lambda PostConfirmation-Trigger

Checking our work

Recap

Personal Growth with Git Flow and AWS Amplify Console - Part 3

Personal Growth with Git Flow and AWS Amplify Console - Part 3

Preparing the repo

Creating another app in our workspace

Adding Git-Flow

AWS Amplify Console

Step 1 - Add repository service

Step 2 - Add repository branch

Step 3 - Configure build settings

Step 4 - Review

Adding the 'develop' branch

Step 1 - Add repository branch

Step 2 - Review

Amplify Console region support

Deploying a second app

One-Click Deploy Button

Reusing the newly created 'amplify' backend

Reusing our previous 'master' backend

One-Click Deploy the second app

Recap

AWS Amplify Auth & Angular RxJS Simple State Management

RxJS BehaviorSubject

Auth-Service

Using our auth state service

Creating Angular UI components and connecting them to the GraphQL AppSync API - Part 2

Getting started with a Angular/NX workspace backed by an AWS Amplify GraphQL API - Part 1

Michael Gustmann ・ Mar 26 '19

BeaveArony / amplify-angular-nx-todo

Angular with NX multi-app setup powered by an AWS Amplify GraphQL Backend

Getting started

Building the UI

Todo-page

AWS Authenticator UI-Component

Creating the presentational UI

model

create-form component

filter-bar component

todo-item component

todo-list component

error-alert component

Watching todos

Creating todos

Updating a todo

Deleting a todo

Handling the filter

Taking it for a spin

Recap

Next

Getting started with a Angular/NX workspace backed by an AWS Amplify GraphQL API - Part 1

Prerequisites

Create a workspace

Let's add our first category `auth`!