DEV Community: James Cote

How to Deploy a React application using AWS Amplify

James Cote — Thu, 19 Nov 2020 18:03:35 +0000

One of the very first challenges I took on in my new position at TimePlay was figuring out how to deploy a React application to AWS Amplify.

Amplify is one of the many services under the AWS umbrella that provides frontend developers with the ability to quickly spin up web hosting, GraphQL APIs, and more for their web applications. With all the backend components integrated and managed by AWS, frontend developers no longer need to worry about hassle of managing servers, and can instead focus on the frontend work at hand.

In this article, I will go over the steps needed to deploy a single-page application (SPA) written in React to AWS Amplify. I will be using the Amplify CLI, which you can install using the following command: (assuming you have Node.js and npm already installed)

npm install -g @aws-amplify/cli

Additionally, for simplicity and to keep the focus of this tutorial on Amplify itself, I will literally be deploying the output of the base create-react-app (CRA) creation command with TypeScript template:

npx create-react-app my-app --template typescript

Now let's begin!

Step 1 - Configuration

Run amplify configure. This will open up a AWS IAM account page, and you'll have the option to either create a new IAM user for Amplify, or use an existing IAM user. The CLI will prompt you for preferred region and name of the new user, but you can provide an existing user's credentials in the following steps if you already have a user.

Whether you create a new user or use an existing user, ensure that you have the following permissions set:

Also, add this IAM policy to your AWS organization and attach it to the user. (either using Visual Editor or this JSON below)

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": "amplify:*",
            "Resource": "*"
        }
    ]
}

Once you have configured your AWS user, the CLI will prompt you for the user's access key ID and secret access key. Enter those in, and leave AWS profile as default unless you would like it to be something else. Now Amplify has been configured.

⚠️ Important
For the purposes of this tutorial, these should be sufficient. However, I highly suggest setting only the minimum number of permissions necessary for the Amplify user. Take a look at this page on the Amplify CLI documentation for more information on the necessary permissions required for Amplify actions.

Step 2 - Initialization

Now that the user has been configured, on the root directory of the project, run amplify init. Follow the prompts as you setup your Amplify project on the cloud. For this tutorial, you will select React application and Amplify CLI will configure itself to run the appropriate build commands when it’s time to deploy the app.

ℹ️ Note
You should also be able to follow through these steps with little modification if you're deploying an app built with another framework such as Vue or Angular. Amplify CLI also has options for these frameworks. Additionally, you can also deploy static HTML/CSS/JS using Amplify, as long as you have `src` and `dist` directories and the final build "output" ends up in `dist`.

ℹ️ Note
When Amplify is initialized, it will have also generated an `amplify/` directory and updated your `.gitignore` to add ignore rules for Amplify-specific files. Push these to source control.

Step 3 - Add Hosting

Now that Amplify is initialized for your project, run amplify add hosting to add site hosting to your project. You can select "Hosting with Amplify Console" to let Amplify manage the full deployment pipeline for you. (ie. S3 buckets and CloudFront distributions will be created, but the CloudFront distributions will not be on your AWS account) You can also select "Amazon CloudFront and S3" to manage the S3 buckets and CloudFront distributions yourself.

At the time of this writing, the CLI will present the following options for your hosting based on your selection:

"Hosting with Amplify Console" Options

Amplify Console will allow you to use your Git repo hosted on a provider such as GitHub, GitLab, Bitbucket, or CodeCommit, and any push you make will trigger a CD pipeline that's managed by Amplify.
You can also select the manual option if you plan on deploying manually or as part of another CI/CD pipeline such as CircleCI or Jenkins. You can also drag'n'drop files using the browser if you use this method — useful for designers and non-technical people to publish their updates. For this tutorial, we will choose this option.

"Amazon CloudFront and S3" Options

Insecure HTTP (S3) option will allow you to only deploy the built site to an S3 bucket. This is useful if you plan on adding CDN using CloudFront or another CDN provider separately. We use this at TimePlay as our CloudFront distributions are handled using Terraform.
There's also a Secure HTTPS (S3+CloudFront) method if you would like to deploy to S3 and front it with CloudFront CDN in one step.

ℹ️ Note
You should invalidate CDN cache after every deploy so that your changes are propagated. If you use Amplify Console to manage your deployment, it will do this for you. If you deploy using `S3+CloudFront` option, you can pass `--invalidateCloudFront` to `amplify publish` to have the Amplify CLI perform an invalidation request.

Step 4 - Deploy

Now that we've added hosting, run amplify publish to build and deploy your application to Amplify.

Once it finishes deploying successfully, it will provide you with a link that you can access to view your deployment.

Now you have a React application successfully deployed to the Cloud in a few easy steps using Amplify! Hope you found this tutorial useful, and do not hesitate to leave a comment if there's anything I may have missed.

Cover Photo by Pixabay on Pexels

6 Continuous Integration tools you can use for an Open Source project

James Cote — Thu, 24 Sep 2020 16:56:40 +0000

I've made it a habit to setup Continuous Integration (CI) pipelines for each of my personal side projects. A CI pipeline can run all tests within a project automatically, and provide immediate feedback if there's any failures. This has given me more confidence in the software I write, and has resulted in better quality code written.

If you're building an open source project, there are a number of free solutions available to automatically build and test your code. These services also have Continuous Deployment (CD) built-in as well, so you can also automatically deploy your project to production after all tests pass. In no particular order, I list each of the services I have found below, and what they offer for free, open source, users.

1. CircleCI

Image Source: https://boards.greenhouse.io/circleci

CircleCI is one of the most well-known providers of CI and CD out there. Originally founded in 2011 and based in San Francisco, they provide solutions for open source developers and business alike.

They have a free plan that includes 1 concurrent job and 2,500 free credits per week for builds. Under the free usage plan, tests run on machines offering 2 CPUs and 4GB of memory. There is also no active user limit on the free usage plan. I have several side projects on CircleCI, and the free plan suits my needs.

edit (Oct. 12): CircleCI also provides a free, open-source plan for public repositories, which contains 400,000 free credits per month for Linux builds, and 25,000 credits per month for macOS builds (on request).

2. Travis CI

Image Source: https://docs.travis-ci.com/

Founded in 2011 and based in Berlin, Germany, Travis CI is also a popular solution for both public and private projects.

Travis CI states that there will be no explicit pricing plan for open source projects and that for these types of projects, they'll always be free. All open source projects get 5 concurrent jobs and unlimited builds for free.

edit (Nov. 2): Travis CI announced on November 2nd that open source projects will now only be given 10,000 credits, which allows for 1000 build minutes on a Linux environment. If you run out, you will need to file a request to Travis CI support with account name, VCS provider, and number of credits you'd like to request.

I have several of my older side projects on Travis, but have since switched over to CircleCI because I found them to be more reliable in my personal (anecdotal) experience.

3. AppVeyor

Image Source: https://status.appveyor.com/

AppVeyor is another CI service founded in 2011, and based in Vancouver, Canada. They specialize in CI solutions for Windows software — providing more Windows Server images than the other solutions mentioned in this article. However, they also provide macOS and Linux build options too.

Their free plan only allows you to run 1 concurrent job, but if you hook up your own machines to run your builds, you can get 5 concurrent jobs for free. They also have a build time restriction of 60 minutes for free plans.

4. Drone CI

Image Source: https://github.com/drone/drone

Founded in 2012, acquired in August 2020 by Harness, and based in San Francisco, Drone CI specializes in providing a simple, lightweight Docker image that can be deployed onto a server. Additional runners can then be installed that poll the server container for tasks to run.

They also provide a free service for open source repositories called Drone Cloud.

5. GitHub Actions

Image Source: https://technology.customink.com/blog/2019/09/02/from-travis-ci-to-github-actions/

GitHub also provides their own CI/CD solution called GitHub Actions. It can also be used for many other purposes such as issue creation and automatic comments in PRs. You can also utilize third-party plugins to automate workflows. This can be a good option if your repository is hosted on GitHub.

Free plans include 2,000 minutes per month, and they are used up at different rates depending on operating system. At the time of this writing, a minute used up in a Linux system uses 1 minute of the plan, a minute in Windows uses up 2 minutes, and a minute in macOS uses up 10 minutes. Read more here.

6. GitLab CI/CD

Image Source: https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/

Like GitHub, GitLab also provides their own CI/CD solution for their repositories. Also, like GitHub Actions, they provide third-party plugins and the ability to automate workflows besides building and testing.

Their free plan has sadly been reduced to 400 a month from 2,000 as of September 1. However, like with GitHub Actions, it's still an option to consider if your project is hosted on GitLab. You can learn more about the specs of the runners they use here.

edit (Sept. 26): @_garybell mentions in the comments that GitLab also has an Open Source Program that allows open source projects to have Gold status for free, which contains 50,000 CI minutes. If your open source project(s) are eligible you can apply here.

As someone just using CI for personal, open source, side projects, I can go with any of the options mentioned in this article. However, if I were to have an open source project with a large contributor base, I would have to consider the tradeoffs more carefully. I think it's great though that there are many options available to set up CI for a project. I wanted the focus of this article to be on highlighting the different solutions available and make it known for software developers what they can use for CI in their projects.

I personally recommend anyone working on side projects to practice using CI. I have worked at several workplaces now that use CI for their projects, and I realize it's great to have a system like this in place to ensure correctness of new features and bugfixes. Therefore, I believe it's important to get familiar with these types of tools and understand how they can help software developers write better code.

If there's another free CI solution out there that I did not mention in this article, do not hesitate to mention it in the comments. Cheers!

Cover Photo by Skitterphoto on Pexels.

Automating Automated Tests with Ponicode

James Cote — Fri, 11 Sep 2020 15:36:27 +0000

Last week, I heard about this nifty unit testing tool called Ponicode. It utilizes AI and context information from your code to automatically generate test cases for your functions. At the time of this writing, it is available as a Visual Studio Code extension.

As someone who's written a decent amount of test cases throughout my early career, whether it's been on my co-op work terms or my side projects, I wanted to give this a spin. Setting up automated tests and configuring runners can take up a lot of time and distract me from the main tasks at hand, so I wanted to see how a tool like this can improve my workflow.

The documentation provides a lot of useful information on how the tool works, which languages/syntax it currently supports, and information on how to install the tool, so I recommend checking it out to get started.

⚠️ Important
Code is sent to Ponicode's servers in order to be analyzed. Since the Ponicode team has not yet explicitly stated how they're handling data of program code sent to them, I have disabled Ponicode globally on my VS Code installation at this time, and only enabling it per workspace. I recommend you do the same, especially if you are working with confidential projects.

Once I installed Ponicode, I checked out the example project they included, which is a simple function that checks whether a provided string is an email, and it seems to work pretty well so far!

Another thing I enjoy so far is having a graphical interface to add and organize test cases for my code. You can add any of the test cases from the generated list to your project by clicking on the "+" button beside it. All added test cases will be written to a file named <file>.test.js, where <file> is the original name of the file you're generating tests for.

The tests will be designed for Jest, which is a downside for me because I prefer to use Mocha for testing my JavaScript-based applications. The Ponicode team explains on their blog that they chose to integrate with Jest first in order to get as many people as possible to try out the tool. [1] Completely understandable, but it still would be nice if they eventually provide support for other runners such as Mocha.

Let's see how Ponicode works outside of their sample project and on a more real-world project. I started opening up some of my open source side projects to see how well Ponicode would work for them. Ponicode only supports JavaScript at the time of this writing, so none of my React, TypeScript, Golang, or Python side projects will work. Also, only globally exported functions are supported at the moment, meaning no classes, static methods, getters/setters, or constructor methods. In addition, class instances, callbacks, and symbols aren't supported either. [2] This makes Ponicode pretty restrictive to just the JavaScript ecosystem at the moment, but hopefully support for other languages and frameworks will come soon.

Lately, I've been making updates to an open-source Atom extension that I created and currently maintain called syntaxdb-atom-plugin. One piece of functionality of the code, for percent encoding search terms sent to the SyntaxDB API, looks like this:

export default class PercentEncoder {
    static percentEncodeChar(char) {
        return '%' + char.charCodeAt(0).toString(16);
    }
    static percentEncodeStr(str) {
        var result = '';

        for (var i = 0; i < str.length; i++) {
            result += this.isReservedChar(str[i])
                ? this.percentEncodeChar(str[i])
                : str[i];
        }

        return result;
    }
    static isReservedChar(char) {
        return reservedMap.has(char);
    }
}

As mentioned above, static methods unfortunately do not work with Ponicode at the time of this writing. But, since this entire static class is better off as a single exported method anyway, I can refactor this and hopefully get a real-world example of Ponicode-generated tests for this article.

ℹ️ Note
During my refactor, I also noticed that whenever I make a syntax error, Ponicode would still notify me that it can't perform the test generation due to syntax error, even after fixing the error. I needed to switch to a different tab then switch back to fix this.

After performing the refactor, I was able to get Ponicode to generate some test cases for me:

Very nice! We can see here that some characters within the strings are URL encoded, and after double checking with the Wikipedia article on percent-encoding, I can safely use these as expectations within my tests.

Ponicode isn't perfect though — in one of my old projects back in 2015, hacka-news, I have a function that takes in an array of Hacker News article IDs, and only returns a slice of those ids up to the limit number that the user requested.

var pruneResults = function(ids, limit){
    var prunedIDs = ids.slice(0, limit);
    return prunedIDs;
}

Unfortunately, Ponicode does not seem to pick up on what ids and limit mean.

If I change the parameter names to arrayOfIDs and limitNum respectively, the results look more suitable:

I can also adjust the parameter name in the percent encode function from the earlier example to get Ponicode to generate better test coverage:

Ponicode also provides a feature where it invokes your program, observes the inputs and outputs of your functions, and uses those observations to improve test cases further. I decided not to use this as I don't believe it's very practical for real-world test development, especially if you're working with a library (such as hacka-news) or an extension (such as syntaxdb-atom-plugin), which are not normally invoked directly, and will require writing scaffolding code to get the Ponicode runner to execute code within these projects.

During my research, I also found an insightful article on Ponicode from Sylvain Leroy, who has much more experience than I do in this area. [3] I recommend checking out his article if you want to learn more about Ponicode, as he provides a more critical analysis of the tool and suggests some great ideas that can improve it further.

Overall, this addon has a lot of potential, even as just a nice GUI frontend that allows me to plop in test cases easily to get things rolling. However, where this addon falls short is the results of their AI-generated test cases, which seem to mostly provide irrelevant test cases and require a bit of tweaking of function parameters to improve. Despite this, I believe that the tool can have the potential to produce higher quality test cases in the future. Ultimately, I don't see myself using this tool for day-to-day developer work, but I am interested to see future developments of the tool — hopefully with more language support, more accessible features, and more effective test case generation.

[1] https://blog.ponicode.com/2020/08/14/jest-versus-mocha-which-testing-framework-for-you/

[2] https://ponicode.com/docs/using-ponicode/testable-functions

[3] https://sylvainleroy.com/2020/07/23/ponicode-my-feedback-and-a-mixed-overall-feeling-about-the-tool/

Cover Photo by Digital Buggu from Pexels

Power up create-react-app!

James Cote — Thu, 27 Aug 2020 16:50:52 +0000

create-react-app (CRA) provides developers with the ability to quickly spin up single-page web applications (SPA) using the React framework without wasting time with configuration or version upgrades. It is a powerful toolkit that has helped make React a dominant player in the web framework space.

There are times however when the out-of-the-box configuration provided by CRA is not enough. Perhaps you want to install a new tool, or you're behind a company firewall and need to use audited dependency versions. In situations like these, CRA provides you with the option to "eject" from the CRA setup. This will allow you to have full control over all dependencies and run scripts. However, this will also prevent you from receiving new upgrades to the React toolchain from CRA. It will also make the React setup much more difficult to manage for newcomers to the framework.

If you want to have more control over your dependencies, but still receive upgrades and support to your React setup from CRA, there are two options available:

Forking the react-scripts package from the official CRA repository, which is a core dependency of CRA applications that contains all the other dependencies. By forking this package, you can add your own dependencies in an encapsulated manner, and all projects using the latest version of your fork will get them automatically.
Introduced in CRA v3.3.0, a Custom Template can be used to define a set of dependencies and scripts that can be added directly to a React project upon creation. (ie. direct dependency instead of through react-scripts) Templates provide the benefit of adding dependencies to your project transparently and allows you to update them independently of other projects that use the template.

In this post, I will walk through creating both a custom react-scripts fork and a custom CRA template, and I will compare both of the solutions.

Forking `react-scripts`

To get started with forking react-scripts, perform the following steps:

1. Fork the official create-react-app repository on GitHub.

ℹ️ Note
You can also fork, or simply clone, the `packages/react-scripts` folder specifically if you like, since that's all we're touching for this tutorial.

2. Clone your newly forked repository to your local machine.

git clone https://github.com/<YOUR GITHUB USERNAME>/create-react-app.git

where <YOUR GITHUB USERNAME> is your GitHub username, assuming you have performed step 1.

3. Checkout the latest release branch of CRA rather than from master branch to ensure stability. At the time of this writing, 3.4.1 is the latest release. [1]

git checkout v3.4.1

4. Now, navigate to the react-scripts package, in packages/react-scripts. Here is where the core CRA dependencies come from. By modifying this package, you will be changing what gets included in your React installation by default.

In my case, I wanted to add jest-junit, which is an extension for Jest that exports test results in JUnit XML format, which can then be accepted by Continuous Integration (CI) tools such as CircleCI to provide readable test results on every build.

I wanted this package to be included with all my current React projects, and every new one I make in the future. Thus, I installed it to the react-scripts package in my fork. This will make it available in all my React apps, so long as it's pointing to my fork of react-scripts instead of the official.

ℹ️ Note
I also recommend making your changes in a new branch within your fork, so that when you pull in changes from upstream (ie. if CRA were to be updated) it's easy to merge in with your custom version.

Once you finish making your changes, you will want to use your fork of react-scripts instead of Facebook's. To do this, you will need to make some changes to its package.json:

{
-  "name": "react-scripts",
+  "name": "<custom>-react-scripts",
  "version": "3.4.1",
-  "description": "Configuration and scripts for Create React App.",
+  "description": "Custom configuration and scripts for Create React App.",
  "repository": {
    "type": "git",
-    "url": "https://github.com/facebook/create-react-app.git",
+    "url": "https://github.com/<YOUR GITHUB USERNAME>/create-react-app.git",
    "directory": "packages/react-scripts"
  },
  "license": "MIT",

Change <custom> to something identifiable to you, and <YOUR GITHUB USERNAME> to your GitHub username.

You can test your custom react-scripts with a new React project by running:

npx create-react-app my-app --scripts-version file:../path/to/your/react-scripts

where ../path/to/your/react-scripts can be either a relative or absolute path to your forked react-scripts.

The --scripts-version argument allows for a custom react-scripts to be installed in place of the official one. A name of an existing custom scripts from npm can be passed in, or a local copy can be passed in using the file: prefix, like we did above.

By making these changes, you will be able to publish it to the npm registry, making it available for your React apps to install as a dependency.

To publish your react-scripts to npm, simply run npm publish and login with your npm credentials when prompted.

ℹ️ Note
Ensure the name of your custom `react-scripts` package isn't already taken on npm.

Once your fork has been published, you can switch the dependency in your app like this:

 {
   "name": "my-app",
   "version": "0.1.0",
   "private": true,
   "dependencies": {
@@ -8,7 +8,7 @@
     "@testing-library/user-event": "^7.1.2",
     "react": "^16.13.1",
     "react-dom": "^16.13.1",
-    "react-scripts": "3.4.3"
+    "<custom>-react-scripts": "3.4.1"
   },
   "scripts": {
     "start": "react-scripts start",

<custom> is the identifiable name you gave to your forked react-scripts from the previous step.

You can also run yarn remove react-scripts then yarn add <custom>-react-scripts to install your fork.

Since the CRA team is continuously making new updates to react-scripts, you will need to keep your fork up-to-date as time goes on.

First, ensure your local repository is connected to the CRA team's version by adding an upstream remote, like this:

git remote add upstream https://github.com/facebook/create-react-app.git

Next, fetch upstream by running git fetch upstream

After that, apply changes from upstream to your local copy by running git checkout upstream/vX.X.X, where X.X.X is the newest version released, then switching into your custom branch and merging changes into it. git merge vX.X.X

There may be some conflicts, but should mostly just be simple version conflicts within package.json.

Also, to use your fork of react-scripts with new apps you make in the future, simply run:

npx create-react-app --scripts-version <custom>-react-scripts my-app

There is one slight caveat with this setup you will need to address manually if you also use a TypeScript template, see [2].

Custom Template

The CRA team also added a Custom Templates feature starting in v3.3.0, where you can simply have a template file containing your dependencies and scripts, and it'll add them to your project upon creation. This is an alternative to creating a custom fork of react-scripts, and it's useful when you only have a handful of dependencies and prefer to update them on a per-project basis.

There are many custom templates already published on the npm registry that you can plug-and-play, such as this heavily customized Redux template, a Tailwind CSS template, and a template containing Storybook.

If you'd like to create your own template with your own set of dependencies and scripts, perform the following steps:

1. Go to the official create-react-app repository and navigate to packages directory.

2. Copy and paste one of the default templates as a base for your template. As of this writing, there are two official templates, cra-template, which is the default, and cra-template-typescript, which is the default TypeScript template.

3. In package.json, add a new property called main and point it to template.json. At the time of this writing, this property is not present in the official templates and new projects will fail to be built if this property is not present in your template.

From the official webpage for Custom Templates, this is the directory structure for a template: [3]

cra-template-[template-name]/
  README.md (for npm)
  template.json
  package.json
  template/
    README.md (for projects created from this template)
    gitignore
    public/
      index.html
    src/
      index.js (or index.tsx)

The important bits:

template.json contains the dependencies, scripts, and other entries that will be copied over into the new React project's package.json file upon creation. They must be populated under a "package" field in this JSON file.
template/ directory contains files that will be copied over into the new project upon creation. gitignore will be renamed to .gitignore.

Update template.json with the dependencies you want to add to your project, add any files you will need to template/ directory, and update README.md and package.json with information about your template.

⚠️ Important
All custom templates must start with `cra-template-` so that CRA knows it's a custom template. Ensure the name of your template within `package.json` follows this convention.

Once all that's done, you can test your template by running:

npx create-react-app my-app --template file:../path/to/your/template/cra-template-[template-name]

where ../path/to/your/template/cra-template-[template-name] can be either a relative or absolute path to your CRA template project.

Now you can publish the template to the npm registry, making it available for new CRA apps to use as a template.

To publish your template to npm, simply run npm publish and login with your npm credentials when prompted.

ℹ️ Note
Ensure the name of your custom template package isn't already taken on npm.

You can create new React projects using your template by running:

npx create-react-app my-app --template cra-template-[YOUR TEMPLATE]

Comparison

In this section, I will compare each of these two solutions. You may want to use one or the other depending on your situation, and you can also use both of them together!

Forking react-scripts

👍 Benefits

Allows you to update dependencies and scripts for your projects in one go
Less dependency overhead in your projects' package.json
Useful for managing dependencies if behind company firewall and/or using a corporate npm registry

👎 Downsides

Not well suited for React projects that would need only a subset of the dependencies updated while keeping old versions of other dependencies (would need to start overriding dependency versions in package.json at this point)

Creating templates

👍 Benefits

Much simpler to use - simply specify the dependencies and scripts you need in the template.json file
Inserts dependencies directly into your app upon creation, sidestepping the need to fork react-scripts if you want to manage the dependencies on a per-project basis
Makes your dependencies visible, unlike the forked react-scripts, which encapsulates them (depending on the situation, this may be a pro or a con)

👎 Downsides

Will need to update dependencies and scripts for every new project you make manually

And that's it - You now have the ability to customize your CRA installation however you see fit! Let me know in the comments if there's something I missed, and heart and save it if you found this useful.

[1] The latest version of this writing is actually v3.4.3, but there were no commits between v3.4.1 and this version. The update was simply to bump up dependencies of some internal tools to satisfy audit requirements. You can learn more about this here. Because this minor change does not affect CRA itself, the maintainers felt there was no need to make a release entry for it on GitHub. Thus, v3.4.1 remains as the latest version for the purposes of this article.

[2] When creating a new project using a TypeScript template, there is a special file called react-app-env.d.ts that allows special objects such as images and CSS modules to be detected by TypeScript. It does this by referencing a file in react-scripts that provides these type definitions. This reference to react-scripts does not change even if a custom react-scripts is substituted in place of the official react-scripts. At the moment, a workaround is to change the reference in react-app-env.d.ts to the name of your custom react-scripts. See this issue for more information.

[3] https://create-react-app.dev/docs/custom-templates/#building-a-template

Dead Simple OAuth

James Cote — Tue, 18 Aug 2020 16:43:54 +0000

Recently, I started building a single-page web application (SPA) using the GitHub API as a side project, and along the way I came across a really cool and simple way to add GitHub OAuth authentication with minimal setup - using an OAuth proxy called Grant.

Quick overview of OAuth: OAuth allow applications to add third party "Sign-In" functionality without risk of your credentials getting leaked or applications accessing more data than you gave it permission to. It's a 3-step process that involves you (the end-user) granting consent to the application, then the application taking that consent (in the form of an authorization token) and exchanging it for an access token.

Simple OAuth 2.0 flow diagram - https://www.researchgate.net/figure/Interaction-between-the-four-roles-of-the-OAuth-protocol-flow_fig5_279063057

OAuth can provide integrations with third party services in a number of ways:

They can be used to create extensions or third party applications for a particular service. The type of application I made falls under this category - it's an application that utilizes GitHub API resources to extend functionality.
They can also be used as a way to handle user accounts and authorization for an entire application. Services such as Auth0 specialize in providing drop-in solutions for this type of flow.

I started work on a GitHub application that imports and exports issues as CSV after I noticed that there wasn't a feature on GitHub itself for exporting and importing issues to/from a spreadsheet. GitHub allows for developers to use personal access tokens with their API, but I wanted to build something that would only take the user a couple of clicks to get setup. I also wanted to learn more about OAuth and how to integrate with another service using it.

I originally started writing a backend with Golang to handle the authorization grant, but after discovering Grant I realized that it can be made simpler. In less than 50 lines, you can get a Node backend setup that will handle the entire OAuth flow.

const express = require('express');
const session = require('express-session');
const cors = require('cors');
const grant = require('grant-express');

var config = {
  defaults: {
    origin: process.env.ORIGIN,
    transport: 'session',
    state: true,
  },
  github: {
    key: process.env.GITHUB_CLIENT_ID,
    secret: process.env.GITHUB_CLIENT_SECRET,
    scope: ['repo'],
    response: ['tokens'],
  },
};

express()
  .use(
    session({
      secret: process.env.SESSION_SECRET || 'grant',
      resave: false,
      saveUninitialized: false,
    }),
  )
  .use(grant(config))
  .use(
    cors({
      origin: [process.env.REDIRECT_URI],
      credentials: true,
    }),
  )
  .use('/get_token', (req, res) => {
    res.send({
      accessToken: req.session.grant.response.access_token,
    });
  })
  .use('/connect/github/callback', (req, res) => {
    res.redirect(process.env.REDIRECT_URI);
  })
  .listen(process.env.PORT);

(features such as persistent session storage and error checking are omitted from this example for brevity)

After setting this up, it's just a matter of plugging in the environment variables:

ORIGIN: The URL of the grant server
REDIRECT_URI: The redirect URI back to your application. It does not have to match the one on your GitHub OAuth app, since you'll be plugging the special route generated by Grant instead.
SESSION_SECRET: Secret for express-session
GITHUB_CLIENT_ID|GITHUB_CLIENT_SECRET: GitHub client ID and secret respectively, both obtained from settings page for your GitHub OAuth app
PORT: port to run your Grant server on

...and setting up the "Authorization callback URL" in the GitHub OAuth app to point to the special callback generated by Grant which will go through the flow.

Once that's done, run the Grant server, point to its /connect/github route, and voilà!

Once it redirects back to your app, you can make an AJAX call to /get_token (passing the session ID cookie) to retrieve the access token.

Grant is a powerful tool. It abstracts away the entire process of issuing access tokens, and also provides built-in security features such as generating + checking of the state parameter, preventing attackers from injecting their own access tokens into your app. It's also extremely configurable, allowing for static configuration (from a config file or from an object) as well as dynamic configuration via HTTP GET/POST requests. Configuration can also be changed during runtime. It's very flexible.

Additionally, not only can you add multiple providers, but you can also add multiple OAuth apps for the same provider using overrides. This allows you to reuse the same OAuth grant server for many OAuth apps.

To learn more about Grant, check out the README.md on the Grant repository, it's very resourceful and contains information on how to easily setup the OAuth proxy for not just GitHub, but many other providers as well. (as a matter of fact, any OAuth-compatible server can be integrated into Grant)

If you're building OAuth integrations for your app, I recommend checking this out!

As an aside, if you want to check out my side project, github-issue-tools, it's located here.

Cover Photo by George Becker from Pexels