DEV Community: Jesse Martin

A Tutorial using Hasura with Draftbit, a low-code tool for building mobile apps

Jesse Martin — Thu, 05 Aug 2021 18:02:32 +0000

In this tutorial we will integrate Hasura with the low-code mobile app development tool Draftbit. We will scaffold a basic application with Draftbit, map the required data to a couple of GraphQL queries, and save those queries behind idiomatic REST endpoints in the Hasura console. As mobile-first development continues to lead many of today’s go-to-market strategies for new initiatives, tools like Draftbit allow teams to iterate on layouts visually, with native code running in the background.

The Hasura features we’ll use

We will be using Hasura’s ability to generate instant REST endpoints to integrate with the UI components that Draftbit makes available to us. The primary glue to integrate Hasura with Draftbit is creating idiomatic REST endpoints for GraphQL queries in the Hasura console. This will allow us to define a query for Draftbit (which doesn’t support GraphQL), on the Hasura side and save that behind a RESTful endpoint. More on that later.

Our data model

We’ll be re-using an existing API for our project from an auto-tagging image service. If you’d like to follow along you can find the original tutorial here. The concepts involved are universal, so you can feel free to simply adapt the use-case for your individual project.

As a point of reference, our model reflects the following pattern.

The exact models vary, and include an upload join table with both photo and tags associated with a user.

The interface

For the purposes of learning we won’t be creating anything detailed with the interface. We’ll be using stock components from Draftbit and create an interface that let us view all the photos in a list, then view the details (tags) for an individual photo.

The Tutorial

Prerequisites:

A working, accessible Hasura project (not running on localhost) with existing data.
A Draftbit account.

From Draftbit

Create a new project from the Dashboard view.

Provide some details about your application.

And for our demo we’ll be choosing “Posts / Content” and “Feed” as our template starters. Allow the project to finish initializing, then click “Start Building”.

The interface is quite intuitive with standard looking design and preview functionalities. You should be seeing an initial screen with a pre-filled feed of some data.

Let’s see how far we can get with these default settings by simply replacing the source content with our API.To do that, we need to select the data tab from the right-hand menu, and choose a custom API for “REST”.

Many tools including low-code tooling are optimized for REST consumption. This is exactly why Hasura has support for creating REST endpoints – for handling the widest range of use-cases possible.

And the best part is you still get to leverage your GraphQL experience!

We will be creating a base resource here that we can use throughout the application. In this case, I will simply name my resource “Hasura” – and for simplicity, I will provide my Hasura Admin Secret to authenticate the requests. You could use a user context for requests later on. If you would like to see user authentication with low-code, let us know!

Side note: You can create Global variables under the settings tab for the project to avoid pasting string values into the configuration here. These are loaded into the environment during runtime.

Returning to our REST API dashboard, we need to configure three critical parts of the resource definition.

We need to provide the base API path for REST requests to Hasura. This is the part of your API before the “v1/graphql” path segment. Then add “api/rest” at the end.

Secondly, we need to define the Hasura admin secret header (x-hasura-admin-secret) and the value - which I have defined in a global variable called “HAS”.

Once you have saved the resource, you need to define some endpoints which will be available to the application. But before we do that, we need to now turn to the Hasura console to define what those will be. Open your Hasura project in a new Tab so we can hop back-and-forth as needed.

The default UI from Draftbit’s feed component included a date, image URL, and title. Let’s fetch the equivalent data from our API. We won’t worry about pagination in this tutorial. I’ll create a named query operation that will request this data. It’s important for the next step that this be a named operation. It’s also a good best practice to name operations in general for tracking down performance leaks in our application.

With our query working, we’ll now navigate to the power feature available to us in Hasura which enables this entire integration.

From the REST interface, we can name our operation, choose our protocol, and create our endpoint. See the image below as a reference.

We’ll return to Draftbit and add an endpoint.

Skip step three.

Save that endpoint and click done on the API resource window. We’ve got our first resource from Hasura fetching data!

Now to iterate over our content, we need to tell our UI to use this new data source. Click on the “Fetch” component in our Layout tree on the left side of the screen.

From the data properties pane on the right side of the window, we’ll need to configure our new data source as the feed provider.

The blank screen means that it is working! Almost…

Now we need to choose the List component in the Layout tree on the left and ensure we’re still viewing the Data properties pane on the right. For “Data” we need to choose the response from our API that is of an Array type - in our case, it will be the first key in the response called “upload”.

You’ll see the list component update now to look as though it’s iterating over “items” - though they are all invisible at the moment. Now we’ll update which pieces of data will be fed into the UI and at which point.

Select the “image background” component in the Layout tree. From Data, we’ll choose the Source dropdown of the Setup section. We’ll look for “image.url” from the dropdown.

We have live art on the page!

Let’s move on to the date and title.

It seems that our date is coming back in an undesired format, let’s create a custom transformer to handle that.

Click on “custom” in the toolbar across the top. We’ll write a “low-code” transformer that runs on this bit of text.

Under the “Functions” menu item, click “+ Add” to create a new function.

Under the information for the function, provide a name and input parameters. For my date, I’ll do a simple Locale String parse. You can run any native Javascript and access some libraries if needed.

Select the new transformer and now we have nicely formatted date and time.

Let’s repeat these steps for our filename.

The code for the second transformer simply replaces some repetitive text in the titles.

    function niceFormat(text) {
        return text
            .replace("image-from-rawpixel-","")
            .replace("-jpeg.jpg","");
    }

Play around with some of the formatting options for the different components. In my case, I wanted the posters to be full-size. The end effect looks like this.

Now it’s time to handle individual details. We’ll tell our “Touchable” component to pass the id of this box to the detail view screen.

With that configured, we can now navigate to the Article View screen.

Looking at the top-level fetch for this view, under the Data panel, we can see that it passes “articleId” as a parameter to the URL structure of the request.

What this means is we will pass a variable with the value of the ID of an individual upload to a specified REST endpoint. Let’s create that endpoint in Draftbit now.

Note, we can provide a test variable that will be run in the case of a non-existing URL parameter, as is the case in development mode.

If we test that now, however, it will fail, since we have not defined the endpoint in Hasura. Let’s do that now. First, we test the query we’d like to persist to an endpoint.

Second, we need to save that as we did with our listing API call. Using the syntax :variable lets us define where we’ll accept inputs in the REST API parameters.

Back to Drafitbit, we can save that endpoint now that we have a successful Test case run.

Returning to our detailed view, we can select our top-level Fetch in the Layout browser, choose our saved Hasura service under the data tab, select the Get Single endpoint, and choose the articleId we passed in from our list-view (also defined in our test case).

We can see by the partial UI loading, that we are at least receiving some form of data. Let’s connect our pieces of data as we did in the previous screen.

With a little bit of cleanup on the components we need to display our data, re-applying some text transforms, and adjusting the styles, we end up with a rough shape of the following:

However, we’ve done nothing with our tags! Let’s add a way to loop over tag elements. Based on what we’ve seen so far, we can assume we’ll need some combination of another “View” box - typically as a container primitive, some form of a “List” component to iterate over an array of data, and the final form of our tag element.

Implementation details will vary, but with these primitives we were able to loop over our tags, and output them on the screen.

But we’ll notice that’s a lot of tags! And tags like “meat” don’t seem relevant to our pictures of fruit! Fortunately, our auto-tagging API includes the confidence level of these tags. Let’s adjust the response data from Hasura.

Here, we are limiting our tags to only those with a confidence greater than 50.

Once we save that data, we can fetch again from Draftbit to see what we get.

That’s a considerable improvement! It’s time to preview this app in context, and play with the different pages.

Pressing the play button gives us a scannable QR code to preview the app directly on our phones, you’ll need to download the Expo app, first.

With just a few functions, some powerful features from both Draftbit and Hasura, we’ve been able to create a native app from our API with very low coding, indeed.

Publishing this app is out of scope for this tutorial, but you can follow the guides at Draftbit and use the built-in UI to deliver your app to users around the world.

Build something with your API today and let us know what you made!

Hasura Fit: Setting up Hasura

Jesse Martin — Thu, 13 Aug 2020 17:16:08 +0000

In this step of our multi-part tutorial, we are going to configure Hasura as our application’s back-end. Hasura is an open-source, GraphQL flavored “back-end-as-a-service” which plays very well with GraphCMS given they both share the GraphQL underpinnings. The back-end-as-a-service simply means that we’ll get a thin UI sitting on top of our database and be offered some user-friendly features, such as taking advantage of Postgres’ hook system but with the convenience of a UI and some additional USPs from the BaaS provider.

Why Hasura?

Apart from the above-mentioned reason that Hasura has native support for GraphQL, Hasura also released a new feature called ‘remote joins’ which allows us to essentially federate our schemas without having to annotate the schemas. If you’re unfamiliar with the federation concept, it basically means that each “section” or “group of concerns” of our application would be split into multiple schemas. These schemas could be developed in isolation of each other since they are often maintained by different teams with a different set of concerns and stakeholders.

Typically, you’d need to provide some kind “decoration”, in GraphQL this is done with directives, to tell one schema when to look at another schema for the answers. In traditional database design, this would be identifying a foreign key when one table needs to look at another table.

In Hasura, we have the convenience of simply providing our API URL, and through the power of GraphQL’s introspection (the ability to understand everything an API makes available to us), the Hasura tooling lets us use a very convenient drop-down to identify which field needs to be connected to our schema. This will be covered a little more later.

Lastly, the reason we chose Hasura is that it has built-in support for authentication and user permissions, which will be important to this application since we have multiple users creating their own, private content.

Environment Variables in Heroku

To begin, we are going to use the newly released Hasura cloud to quickly set-up a new instance of Hasura. You could just as easily use their deployable solution on Heroku (our database will be hosted there, anyways) or any other server stack supported by them, but we’ll focus on the cloud version to keep things simple.

Create an account with Hasura Cloud.

Create the database on Heroku

You’ll need to authenticate (or create an account with Heroku first) after which the Hasura Cloud interface will do automated provisioning for you.

Once you create the project, the app will go through a number of installation steps (all automated) and then prompt you to launch the console (main application) of Hasura. When you launch the console, it will open in a new tab, return to the Hasura Cloud UI to add our environment variables.

Note various values available to you here.

We will need to create a few variables for this project:

GRAPHCMS_FULL_ACCESS_TOKEN
This is our access token from GraphCMS which we defined in our GraphCMS API. Note, you’ll need to use the format Bearer <TOKEN_VALUE> since we use the full string as Hasura’s env values don’t allow us to use string interpolation.

HASURA_GRAPHQL_ADMIN_SECRET
For protecting our console (if we aren’t using Hasura Cloud) and also for protecting synchronizing function from Auth0.

HASURA_GRAPHQL_JWT_SECRET
Our application will use tokens from Auth0 to authorize our requests to Hasura. We need to configure Hasura to recognize Auth0’s JWT format. To do this, provide the following value as the environment variable:

{
  "type": "RS256",
  "jwk_url": "https://<YOUR_AUTH0_DOMAIN>/.well-known/jwks.json",
  "claims_format": "json"
}

Replacing <YOUR_AUTH0_DOMAIN> with your actual Auth0 application domain.
HASURA_GRAPHQL_UNAUTHORIZED_ROLE
Define this as “public” - which means that users who attempt to access our API without authentication will be assigned the “public” role, which we can assign specific privileges for in our database.

Creating the Content Model

The majority of our product or editorial content was modeled in GraphCMS. We’ll simply use two models (or tables) in Hasura. Our user table, which is populated from Auth0 plus an additional array relationship called sessions to a table also called sessions.

An array relation simply means that we are defining a one-to-many or many-to-many relation. If we were creating a many-to-one or a one-to-one this would be an object relation.

Users Table

Sessions Table

Adding Remote Schema

You’ll note in the session table above, we defined a workout “slug” - this will serve as our foreign key for GraphCMS when we define a remote schema relationship. Defining and federating a remote schema couldn’t be easier in Hasura. To enable our Remote schema, go to the “remote schema” tab at the top of the window, and add in the values, your settings should be similar to the attached graphic.

Note that for the Authorization header, we are using a value from our environment, our GRAPHCMS_FULL_ACCESS_TOKEN.

Define the Relationship

Return to the relationship tab of the sessions table. At the bottom of the tab window, there’s a section called “Remote Relationships.”

Name the field “workout” and choose the Remote Schema of GraphCMS (or whatever you labeled the remote schema in the previous step).

The trick here is that we are passing the value to the slug input argument of our where input type. The slug value is coming from the slug column of our session.

That’s it.

Creating a Web-hook

We use a webhook in the project to perform a sort of “pre-calculated aggregation” of the popularity of our workouts. This allows us to sort by popularity without needing to touch our user database if we were to distribute our GraphCMS API to another location that was un-aware of our Hasura project. In Hasura, these are called “Events”.

We define the trigger to occur when the table sessions receive a new insert and then we send a payload to the Web-hook URL defined.

The gotchas

There are some limitations to the remote schema joins for now. One of which is that you cannot use secure roles in the fields of a remote join. That is, you can’t extend the access controls from Hasura to the fields of GraphCMS. Hasura is working to enable this as is GraphCMS.

There are also some notable gotchas:

No exposed ID Type

Their ID scalar is not exposed by Hasura so we wouldn’t be able to use the direct ID of the workout entry from GraphCMS since meshing them would cause a type incompatibility error (even though both read as a text string.) That means we needed to create a slug entry in our GraphCMS model to support matching a foreign key from Hasura.

Required Fields

Because the input argument type where is required by GraphCMS for filtering by workout, we have to pass this value in as an empty argument when querying content, even though it is dynamically inserted at run-time. It’s less elegant than it could be, but a small price to pay for the amazing flexibility of adding a meshed-in third-party API.

Next Steps

That's it! You've made it to the end. Now you have all the pieces you need to create elegant, composed, distributed, and iterative APIs and services. Tweet out your success or check out GraphCMS for even more great resources.

Hasura Fit: Setting up Vercel

Jesse Martin — Thu, 13 Aug 2020 17:15:57 +0000

Why Vercel?

Vercel is an incredibly straight-forward hosting environment for our code. It provides a number of runtimes so that the most popular code can simply be uploaded to a Vercel project and it will run. Since our project is Javascript based, it will run just fine.

We’ll be using two separate Vercel projects for our tutorial primarily for educational purposes and as a separation of concerns.

First, we’ll be deploying our NextJs framework code to Vercel to run our primary web application.

Second, we’ll be running a very simple server function that acts as webhook for our Hasura project to update our content in GraphCMS later-on.

To begin, create an account with Vercel.

Environment Variables in Vercel

Assuming you have forked and cloned both the Hasura-Fit and the Hasura-Fit-Hooks repos locally, you’ll now need to add them to your own version control account (ie. Github). If you only cloned and didn’t fork, you can see how to change the URL here.

Once you have your code, pushed to version control, you can import those projects into Vercel from your account console.

After you have imported your project, you will have the ability to define your variables under the Settings / Environment Variables page. It’s possible your project might error on the first build since the environment variables are not yet defined. Don’t worry about that yet.

VERCEL_URL in this case is a system default variable that will be dynamically populated by the Vercel environment with a special URL that is either referring to a branch from your repo or the master branch.

The remainder of the variables can be copied from the NextJs variables, with production urls being used where needed.

Next: Set up Hasura

Hasura Fit: Setting up Serverless Functions

Jesse Martin — Thu, 13 Aug 2020 17:15:44 +0000

Why Vercel Serverless Functions?

There are many serverless providers out there. Many of them are incredibly easy to set-up. Because we are hosting our NextJs web app on Vercel (the same company that made the framework) - it makes sense to stay in the same ecosystem.

It’s also incredibly easy to set up. If you inspect the code involved, it really is a matter of defining the function you want to handle a serverless request, use the CLI to publish and you have a “micro-service” ready to go.

Environment Variables

The Vercel CLI for local testing does not support the .env.[environemnt] pattern defined in our Nextjs guide, so we’ll simply use a .env file, being sure to avoid checking this file into version control. Begin by copying the template with cp ./.env.template ./.env.

We’ll add:

GRAPHCMS_MUTATION_TOKEN
GRAPHCMS_API

Both of which we can find in the GraphCMS API Settings.

Server Functions

Our code for the webhook handler is rather succinct.

Essentially, we perform three actions:

We inspect incoming requests to ensure that we have a successful payload that includes the slug of a workout performed by a user from Hasura.
We fetch the popularity field of that workout from our GraphCMS API directly.
We mutate the GraphCMS workout model by incrementing the popularity field by one.

Again, all the code is provided in the repository.

const axios = require("axios");

module.exports = async (req, res) => {
  const ax = axios.create({
    baseURL: process.env.GRAPHCMS_API,
    timeout: 1000,
    headers: { Authorization: `Bearer ${process.env.GRAPHCMS_MUTATION_TOKEN}` },
  });

  let message;

  const { body } = req;

  if (body) {
    const {
      trigger,
      event: {
        data: {
          new: { slug },
        },
      },
    } = body;

    let {
      data: {
        data: {
          workout: { popularity },
        },
      },
    } = await ax.post("/master", {
      query: `query GetWorkout($slug: String) {
            workout(where: {
              slug: $slug
            }) {
                title
                id
                slug
                popularity
            }
          }`,
      variables: { slug },
    });

    let mutationResponse = await ax.post("/master", {
      query: `mutation IncWorkout($slug: String!, $popularity: Int) {
            updateWorkout(where: {slug: $slug}, data: {popularity: $popularity}) {
              id
              popularity
            }
            publishWorkout(where: {slug: $slug}, to: PUBLISHED) {
              id
            }
          }
          `,
      variables: { slug, popularity: popularity + 0 + 1 },
    });

    console.log(popularity);

    let {
      data: {
        data: {
          updateWorkout: { id },
        },
      },
    } = mutationResponse;

    message = `ID ${id} popularity is now ${popularity + 0 + 1}`;
  }

  res.status(200).send({ message });
};

Next: Set up Vercel

Hasura Fit: Setting up NextJs

Jesse Martin — Thu, 13 Aug 2020 17:15:35 +0000

Why NextJS?

NextJs is a powerful framework that lets us combine the best of server-side execution and static site generation. Out of the box we get server-rendered content, static resource compilation and API routes ensuring a protected execution environment.

Why that’s important for us is that we are able to handle our user authentication and Auth0 code in server-side routes where our Auth0 Client secret is protected from our app’s users, while still getting access to really fast pages loading content that doesn’t need to check the server first.

All of the code has been written already in this example repo, but we’ll look at the different parts of the framework to get a better understanding of how it works.

To begin with, you’ll need to provide your own application variables. We’ll be assuming that our code is deployed to Vercel as that is what this tutorial recommends, but the choice is up to you.

Environment Variables

First, start by creating a copy of the .env.local.template file and rename it to .env.local

cp ./env.local.template .env.local

Returning to the Auth0 console and navigate to your application, you’ll need:

AUTH0_CLIENT_SECRET
AUTH0_CLIENT_ID
AUTH0_DOMAIN

Additionally, you’ll need to define a random secret for the SESSION_COOKIE_SECRET as well as the SESSION_COOKIE_LIFETIME

Lastly, you’ll need to define HASURA_ADMIN_SECRET which will be used to protect your login if you choose not to use Hasura Cloud.

We define all of these values in a file called “.env.local” because we will define all of the values again in our Vercel admin panel for our project. NextJs supports naming files .env.[environment] as a pattern for mapping specific environment variables to those Node environments. It looks for these files out of the box. The .local prefix is a reminder for us to not push this file into source control (ie. Github).

Creating the Required Pages in Next

All of the needed pages for the demo exist already in the project repository, but for an explanation, we’ll describe them here.

lib/config

Our config file declares various export values for use throughout our application. Because we are using sever side and client side authentication, we need to define different variables for different contexts. Because we are hosting in Vercel, we need to handle some work-around behaviour to handle our preview URLs (branch deploys) vs our aliased production URL.

if (typeof window === "undefined") {
  /**
   * Settings exposed to the server.
   */

  const url = (production, branch, local) => {
    switch (process.env.NODE_ENV) {
      case "production":
        return production;
        break;
      case "preview":
        return branch;
        break;
      case "development":
        return local;
        break;
      default:
        return local;
        break;
    }
  };

  const base = url(
    "YOUR_LIVE_VERCEL_APP_ALIAS",
    `https://${process.env.VERCEL_URL}`,
    "http://localhost:3000"
  );

  module.exports = {
    AUTH0_CLIENT_ID: process.env.AUTH0_CLIENT_ID,
    AUTH0_CLIENT_SECRET: process.env.AUTH0_CLIENT_SECRET,
    AUTH0_SCOPE: "openid profile",
    AUTH0_DOMAIN: process.env.AUTH0_DOMAIN,
    REDIRECT_URI: base + "/api/callback",
    POST_LOGOUT_REDIRECT_URI: base,
    SESSION_COOKIE_SECRET: process.env.SESSION_COOKIE_SECRET,
    SESSION_COOKIE_LIFETIME: process.env.SESSION_COOKIE_LIFETIME,
  };
} else {
  /**
   * Settings exposed to the client.
   */
  module.exports = {
    AUTH0_CLIENT_ID: process.env.AUTH0_CLIENT_ID,
    AUTH0_SCOPE: "openid profile",
    AUTH0_DOMAIN: process.env.AUTH0_DOMAIN,
    REDIRECT_URI: `${window.location.origin}/api/callback`,
    POST_LOGOUT_REDIRECT_URI: window.location.origin,
  };
}

The URL helper function simply allows us to define which base-url will be used in the various Node environments such as preview, development and local.

Note how we don’t expose our AUTH0_CLIENT_SECRET in our client context, but only in the server? This is part of what makes a framework like NextJS so powerful is the ability to mix contexts like this.

lib/auth0

The auth0 file in our lib creates a new configuration object for the Auth0 SDK. It creates all the required configurations and methods we’ll need to work directly with Auth0, and then exports it for use in other files.

import { initAuth0 } from "@auth0/nextjs-auth0";
import config from "./config";
const auth0Instance = initAuth0({
  clientId: config.AUTH0_CLIENT_ID,
  clientSecret: config.AUTH0_CLIENT_SECRET,
  scope: config.AUTH0_SCOPE,
  domain: config.AUTH0_DOMAIN,
  redirectUri: config.REDIRECT_URI,
  audience: "YOUR_HEROKU_APP_URL",
  postLogoutRedirectUri: config.POST_LOGOUT_REDIRECT_URI,
  session: {
    cookieSecret: config.SESSION_COOKIE_SECRET,
    cookieLifetime: config.SESSION_COOKIE_LIFETIME,
    storeIdToken: true,
    storeRefreshToken: true,
    storeAccessToken: true,
  },
});

export default auth0Instance;

lib/user

This is highly specific React code and will be covered in the NextJs tutorial. The basic gist of this code is that it implements a React hook to check our /api/me route if the user is still logged-in, if they are, it returns our user data, if not, it redirects a user to a login path and additionally includes some helper state to determine if the browser is still checking for our logged-in status.

pages/api/login

Our login function takes a request to the route /api/login from our website, which then in turn uses our Auth0 lib to send all the client ID and secret information we need to Auth0 along with a secondary parameter called “redirectTo” which is the url that should be called from Auth0’s servers after we succeed or fail to log-in to the app.

import auth0 from "../../lib/auth0";

export default async function login(req, res) {
  try {
    await auth0.handleLogin(req, res, {
      redirectTo: req.headers.referer + "api/callback",
    });
  } catch (error) {
    console.error(error);
    res.status(error.status || 500).end(error.message);
  }
}

pages/api/callback

Our callback URL handles a request coming FROM Auth0, more specifically, this is a callback that is invoked when a user tries to signup. See the diagram below.

Our application tries to login, which sends us to Auth0, Auth0 uses a form from their server (in our case) which then sends us back to our callback url that we defined in our login request above. If we had a successful login, that request has tokens corresponding the scopes we requested and whether or not we want to use refresher tokens. Because there can be any number of tokens depending on our settings, the Auth0 library is able to simply take the request coming back from the Auth0 servers, identify which parts are important for our authentication, and save them where they need to go in our browser.

That code looks like this:

import auth0 from "../../lib/auth0";

export default async function callback(req, res) {
  try {
    await auth0.handleCallback(req, res, { redirectTo: "/" });
  } catch (error) {
    console.error(error);
    res.status(error.status || 500).end(error.message);
  }
}

pages/api/me

This route is perhaps the most opaque in terms of understanding the inner workings of the code, but the concept is straight forward. The SDK checks to see if the user still has a valid token to access data from Auth0, if not, it uses the refresh token to generate a new one.

import auth0 from "../../lib/auth0";

export default async function me(req, res) {
  try {
    await auth0.handleProfile(req, res);
  } catch (error) {
    console.error(error);
    res.status(error.status || 500).end(error.message);
  }
}

pages/api/logout

In a near mirror of our callback code, the Auth0 SDK takes a the request to logout and simply removes all the cookies for logging in and ensures no protected content is accessible anymore.

import auth0 from "../../lib/auth0";

export default async function logout(req, res) {
  try {
    await auth0.handleLogout(req, res);
  } catch (error) {
    console.error(error);
    res.status(error.status || 500).end(error.message);
  }
}

We won’t bother outlining the remaining files in NextJs here as they pertain to the presentational layer and edge of out of the scope of this tutorial.

Generally speaking, the actual rendered pages will include a function that follows a similar pattern as the following code snippet.

export async function getServerSideProps({ req, res }) {
  // Here you can check authentication status directly before rendering the page,
  // however the page would be a serverless function, which is more expensive and
  // slower than a static page with client side authentication
  const session = await auth0.getSession(req);

  if (!session || !session.user) {
    res.writeHead(302, {
      Location: "/api/login",
    });
    res.end();
    return;
  }

  const resp = await fetch("https://hasura-fit.herokuapp.com/v1/graphql", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${session.accessToken}`,
    },
    body: JSON.stringify({
      query: `{
            sessions {
              created_at
              workout(stage: PUBLISHED, where: {}) {
                title
              }
            }
          }
          `,
    }),
  });

  const { data } = await resp.json();
  return { props: { sessions: data.sessions, user: session.user } };
}

The specific function here getServerSideProps allows us to guarantee a server-side execution which means privileged access. That’s why we are able to use our authorization header here in the same file as our rendered page because we know this part of the code only runs on the server. This is one of the hidden powers of NextJs.

In the above code, our server will look for a valid session rookie, if it doesn’t find one, it will return us to the login page, otherwise, it will execute a request with our auth token that originally came from Auth0 and is intended for use at Hasura. It will read all the data about my user’s workout session activity, and then, through the remotely joined schema, Hasura will also look up the workout data itself (the title) directly from GraphCMS but resolve it to us in one unified server.

One last “complex” query that deserves a special mention is the following code:

fragment Rep on RepMovement {
  title
  repetition
}

fragment Amrap on AmrapMovement {
  title
}

fragment Duration on DurationMovement {
  title
  duration
}

fragment Circuit on Circuit {
  repetitions
  movements {
    ... on RepMovement {
      ...Rep
    }
    ... on AmrapMovement {
      ...Amrap
    }
    ... on DurationMovement {
      ...Duration
    }
  }
}

query Premium($authed: Boolean!) {
  workouts(orderBy: popularity_DESC) {
    title
    description
    popularity
    slug
    image {
      url
    }
    warmup @include(if: $authed) {
      ... on RepMovement {
        ...Rep
      }
      ... on AmrapMovement {
        ...Amrap
      }
      ... on DurationMovement {
        ...Duration
      }
    }
    program @include(if: $authed) {
      ... on RepMovement {
        ...Rep
      }
      ... on AmrapMovement {
        ...Amrap
      }
      ... on DurationMovement {
        ...Duration
      }
      ... on Circuit {
        ...Circuit
      }
    }
    coolDown @include(if: $authed) {
      ... on RepMovement {
        ...Rep
      }
      ... on AmrapMovement {
        ...Amrap
      }
      ... on DurationMovement {
        ...Duration
      }
    }
  }
}

This code requests the content for our homepage. In this complex query we define re-usable pieces of query (fragments) to be used in multiple locations of our query body. We also pass in a variable called “authed” which has come from a check to see if the user has a valid session. If it does, it includes the workout data, if it doesn’t, it get’s skipped according to the rule defined in the @include directive’s if argument. This way a user can see the title and basic information about a workout program, but not the full “product” data in this case.

Next: Set up the Serverless Functions

Hasura Fit: Setting up the Auth Flow

Jesse Martin — Thu, 13 Aug 2020 17:15:29 +0000

Special thanks to Sam Bellen for helping me troubleshoot some tricky parts of the Auth0 ecosystem.

In this part of our tutorial, we’ll be adding the authentication layer to our web app which lets us leverage the power of Auth0 and their social sign-on ecosystem of tooling to let us, onboard users, quickly and easily.

A core tenant of modern web application architecture is “do not write your own authentication” - basically, it’s a problem that’s easy enough to get wrong and also easy enough to make you think you got it right. Find either an open-source platform where hundreds of developers contribute to the robustness of the code-base or a SaaS company for essentially the same reasons but when you need an SLA or a few convenience features behind it.

Prior Art:

https://hasura.io/docs/1.0/graphql/manual/guides/integrations/auth0-jwt.html
https://github.com/auth0/nextjs-auth0

Why Auth0?

Auth0 has been one of the mainstay players in the authentication space for a while, they support nearly every type of “single sign-on” - which just means re-using an account from something like your workplace or Facebook - and they have excellent developer tooling to help us integrate with our stack. They handle password resets/forgets, generating custom scope in our Auth tokens (we’ll cover this in a few moments) and more.

If you need an enterprise-grade Auth library (or a generous free tier with reasonable pricing for your side projects) - Auth0 is a great solution.

Creating an Account

The first thing you need to do is create an account with Auth0, after that, you need to create an Application. From the applications tab of your project, you can click on “Create Application”.

Note: It’s critical you choose “Regular Web Application” as we’ll be working with server-side authorization and the library we are using expects “Authorization Code

Understanding the different types of authentication flows

Choosing SPA would result in a PKCE flow, which returns a shape of data our library isn’t expecting and is also not needed since we are authorizing server side. PKCE simply adds an additional layer of indirection before the exchange of tokens occurs.

Account Settings

The “variables” will differ for production context, but all things held constant, your localhost will stay the same.

We only need to handle the settings for Allowed Callback URLs (where we return to after authentication) and the allowed Logout URLs (where we return to after logging out.)

Web origins is only for contexts where the Sign-On form is EMBEDDED in the application and by default, all our allowed URLs are included in CORS.

Allowed CallbackURL.
Localhost: http://localhost:3000/api/callback.
Vercel: https://gcms-hasura-fit-\*.vercel.app/api/callback.

Using an asterisk (*) in the URL is known as a wildcard and this allows you to match all urls that match the first-half before the asterisk and the last half after the asterisk and anything in the middle. This is done so that if you want to use continuous deployment (where you get a deploy every time you push code to a code repository like Github) you’ll get previews in both your master branch and any other branches where you might test out new features.

Allowed Logout URLs.
Localhost: http://localhost:3000.
Vercel: https://gcms-hasura-fit-\*.vercel.app.

Understanding our Auth Config

In our NextJS project we have abstracted the authentication service as a library under our /lib directory where we can call our auth service from multiple places in our application. To communicate with Auth0 - we will use their SDK (software development kit) to send requests to Auth0 in the correct shape.

The init method looks like this:

const auth0Instance = initAuth0({
  clientId: config.AUTH0_CLIENT_ID,
  clientSecret: config.AUTH0_CLIENT_SECRET,
  scope: config.AUTH0_SCOPE,
  domain: config.AUTH0_DOMAIN,
  redirectUri: config.REDIRECT_URI,
  audience: "https://hasura-fit.herokuapp.com",
  postLogoutRedirectUri: config.POST_LOGOUT_REDIRECT_URI,
  session: {
    cookieSecret: config.SESSION_COOKIE_SECRET,
    cookieLifetime: config.SESSION_COOKIE_LIFETIME,
    storeIdToken: true,
    storeRefreshToken: true,
    storeAccessToken: true,
  },
});

Client Secrets and IDs

Auth0 is a hosted application (SaaS) which has many different projects in their database. To tell Auth0 which one is yours, you need to use the ID and the Secret they gave you in your signup process to properly identify which project in their servers is yours.

Scopes

In our application, when we call our login service, we need to tell our Authorization service (Auth0) what kind of permissions the holder of the returned token should have. In our case - we are asking for the profile and opened information about the user. Different services around the web might have other scopes such as “reading e-mails” or “updating calendar” - it’s common for services to restrict the permissions available to the token key they give you based on these scopes you are asking for.

Audience

Because we will be using the access token provided to access a DIFFERENT service (our hosted Heroku app) we need to tell Auth0 that the token we are asking for will be used at a different site.

Redirects

See the information above about the redirect URLs.

Session

The session configuration allows us to define which tokens should be saved in the browser, if at all, when it should expire and a secret key to encrypt the data.

Custom Rules

Auth0 allows specific rules (or functions) to be executed when certain things happen in Auth0. We need to create a special function for when we send a token to our web app and we need to create a special rule for creating a copy of our Auth0 user in our Hasura database.

Modify Token: hasura-jwt-claim

To modify the token we send to our client which will in turn be used to access Hasura, we’ll use the following rule

    function (user, context, callback) {
      const namespace = "https://hasura.io/jwt/claims";
      context.idToken[namespace] =
        {
          'x-hasura-default-role': 'user',
          // do some custom logic to decide allowed roles
          'x-hasura-allowed-roles': ['user'],
          'x-hasura-user-id': user.user_id
        };
      callback(null, user, context);
    }

Synchronize Users: insert-user

To synchronize our users, we’ll need an additional rule which creates a mutation in Hasura every time a new user signs up.

    function (user, context, callback) {
      const userId = user.user_id;
      const hasuraAdminSecret = "xxxx";
      const url = "YOUR_HASURA_ENDPOINT";
      const upsertUserQuery = `
        mutation($userId: String!){
          insert_users(objects: [{ id: $userId }], on_conflict: { constraint: users_pkey, update_columns: [] }) {
            affected_rows
          }
        }`
      const graphqlReq = { "query": upsertUserQuery, "variables": { "userId": userId } }

      request.post({
          headers: {'content-type' : 'application/json', 'x-hasura-admin-secret': hasuraAdminSecret},
          url:   url,
          body:  JSON.stringify(graphqlReq)
      }, function(error, response, body){
           console.log(body);
           callback(null, user, context);
      });
    }

Next Steps

To continue this tutorial, our next step will be to configure NextJs to be up and running which will be needed to configure Auth0 to work with Hasura.

Next: Set up NextJs

Hasura Fit: Setting up GraphCMS

Jesse Martin — Thu, 13 Aug 2020 17:15:13 +0000

In this portion of the multi-part tutorial, we’ll be creating our data model that acts primarily as our product information manager. Since the product being offered is a complex content structure at the end of the day, GraphCMS is the perfect tool for this job.

Why GraphCMS?

The most important reason why we chose GraphCMS is because the author works there. Ok, full disclosures out of the way, GraphCMS is one of the fastest methods out there to create a hosted GraphQL API. By simply clicking together models and types you can create complex relationships, including the often verbose “many-to-many” relationships within seconds.

GraphCMS also lets us have a content editing backend where our theoretical marketing team would be able to update the product info (our product being workout programs) and be able to update our application’s content without needing the traditional heightened access controls like accessing a user database would entail.

This is our separation of concerns between Hasura and GraphCMS - Hasura handles our user data and GraphCMS handles our product data.

The last reason we are using GraphCMS, and one of the core USPs of GraphCMS, is that it supports GraphQL mutations as well! This means that we can write data back into our content model. This is helpful because from our application data hooks, whenever a user completes a workout, we are able to simply update an integer of “popularity” on one of our workout programs so that we have a pre-compiled analytics for sorting these workouts later without the need to worry about secure and costly aggregation of our entire user database when our front-end team simply wants to sort which workouts are the most popular.

Environment Variables in GraphCMS

GraphCMS doesn’t have environment variables per se but it does have permanent auth tokens which we’ll use to authorize access to our API. Particularly because of our mutation API, it’s important to separate who has access to mutate our content vs who has access to just read our content. We can also separate access to draft vs published content in the situation where you have a preview environment.

Creating the Content Model

We’ll be doing most of our fancy content modeling in GraphCMS. Our content model will be taking advantage of a number of content modeling concepts such as composition, extending base types and creating union relationships of one or more types.

I’d like to invent a term with you called “SCUR” - this idea is not new but let’s give it a name. SCUR stands for “smallest composable unit, reasonable”. What this means is that we should try to break our content model into the smallest entry we possible can within reason balancing the concerns of time, resource and maintainability.

My model has the following primitives: A base workout type, say, a pushup. We extend on that with composition to create different types of this workout, pushup exercises that are a function of time (5-second count), pushups that are a function of repetition (25 pushups) and pushups that are a function of endurance (AMRAP - as many reps as possible, usually within a minute). Later if I want to identify the average caloric value of an exercise or some kind of additional data to my base exercise type, I can do that without the need to update a bunch of locations.

Additionally, our base workout is also one of two types, either a body weight exercise which can be done with just your own body’s weight or an exercise dependent on equipment such as boxing or jump-roping.

Another type we have is a set, or a grouping of exercises together that require some kind of order. Since these could be a mixture of time exercises, repetition exercises or AMRAP exercises, and even sub-sets, we need to use a union type relation that lets us define the possibility of any of these valid inputs.

These sets, mixed with warmups (also a union type to our exercise matrix) and cool-downs (also a union type) along with some content description, images and more create the full exercise protocol or programming and a complete product in our system.

And now our content model from GraphCMS is complete!

Next: Set up Auth0

Hasura Fit: Complete Guide / Start Here

Jesse Martin — Thu, 13 Aug 2020 17:15:06 +0000

This is a multi-part tutorial on creating a fitness app with modern web-technologies. It utilises user accounts (Auth0), User data (Hasura), Editorial content (GraphCMS), serverless functions (Vercel) and the popular React framework NextJs (also hosted on Vercel).

The rough flow of our application is as follows.

A user comes to our application which shows content required no authentication. They decide to join the program and signup.

When signing up, they are redirected to Auth0 where a new user account is created, which in turn creates a new user account in Hasura for later reference, and then sends an authentication token back to our user in the web app with special permissions to be re-used with our Hasura API and a few modified parameters to help us confirm who our user is there.

The web application updates with this new information and then shows authenticated content, such as our workout programs, which comes from Hasura at the query level, but is resolved from GraphCMS through a federated API mesh which we configured in Hasura.

Once our user performs one of the workouts, this action will save a new session in our Hasura database and at the same time, trigger a web hook which increments the popularity of that workout in our GraphCMS content API.

Here’s a rough flow chart for the following steps.

If you find errors, typos, or updates to the functionality, pull requests are always welcome!

Next: Set up GraphCMS

Project Sketches

Jesse Martin — Fri, 08 May 2020 12:17:02 +0000

Like a good 100k+ of you out there, I follow the excellent “learn in public” advocate Emma Bostian. If you don’t follow her, go raise that number. She shared a Tweet that is more of a “meme” among developers than anything else at this point. The classic syndrome of the "project graveyard" of personal Github repos.

Emma Bostian 🐞

@emmabostian

My GitHub is more like a project graveyard of half-finished, half-assed projects than a set of project repositories that showcase my skills.

06:46 AM - 08 May 2020

If you haven't seen this actual meme that somewhat painfully describes the problem, well, here you go. It's one of my favorites.

To be honest, the vast majority of my projects never even make it to Github, to begin with. The new unlimited private repositories are starting to change that, thank you Github!

But why? Why do we feel this way? Why do we as developers hold on to this notion that our projects need to be world-changing endeavors that just need a pitch deck and cheesy .io domain to go on to greatness?

Let's stop even calling them full side-projects and just call them "project sketches."

Jesse Martin

@motleydev

@EmmaBostian Call them "project sketches". Not every two bits of code we put together need to become unicorn startups. You wouldn't call a sketchbook a collection of half-finished, half-assed masterpieces.

06:54 AM - 08 May 2020

Yes, I liked something I tweeted so I wrote an article about it. Even worse, it was just something I replied. 🤦🏻‍♂️

Be Bold

But the point is real. We don't call drawings in a sketchbook "masterpieces in progress", sometimes it's worth just coding something for the exercise. You will draw a lot of circles and triangles on paper before you finish drawing the owl.

So, feel free to explore. Make a blog with one page and one post if you want to, create buttons that don't actually do anything and simple exercise in this powerful medium that we have. Don't be afraid to share a sketch - and to be able to call it a sketch! Not everything needs to be a WIP.

Shameless Plug

Justifying writing this at work

I recently released a small CLI for bootstrapping projects AND sketches using the CMS that I work for. It's a great way to get pixels on the page, quickly.

I used npx create-gcms-app with-nextjs to build and deploy this in less than 10 minutes. Five minutes for a coffee and choosing the name, 'cause, naming things is hard. A few of those minutes to figure out why 100vh gave me overflow. Sketches.

So here you go, a project sketch, with cool developer domain and pitch deck all in one.

https://gobebold.now.sh/

Thanks for reading. If you like this, follow me on Twitter.

Also, PS, the company I work for is hiring!

Run your own conf, the serverless way

Jesse Martin — Wed, 29 Jan 2020 15:02:18 +0000

We’ve got another open source starter project for you built on production-grade serverless technologies. Today’s project is all about Headless CMS for events and conferences! If you’ve ever tried to put on a meetup, conference, or other type of event, you’ll know that there’s roughly two halves to the content flow of a conference: the speakers, and the talk submissions.

Useful links:

There are a number of services out there that let you manage conference agendas, and then there are a number of other services that let you accept talk submissions, but there are very few that give you the flexibility that your conference needs.

With the powerful backing of a headless content repo, the flexibility of serverless technologies, and the power of modern developer tooling, you can quickly build a system that lets you run multiple conferences all around the world with granular control over the content, submission flows, and more.

The Content Structure

Implied in the name of GraphCMS is the idea of graph structures. Graphs are incredibly powerful and expressive models to define relationships with. We’ve written more about graphs on this page.

If you notice the relationship between tracks, talk and person - we are able to provide semantic information on the RELATIONSHIP, defining how each node sees the other. The context changes depending on the relationship. In graph speak, this is called an edge.

The reason we break our nodes down into such granularity is that it affords us ultimate content composition. We can now re-use the same talk and even the same track at multiple events.

The Service Mesh

The Event Starter is powered by a handful of APIs, but only three service providers. First, GraphCMS houses the entire content structure. All submissions, events, schedules and more are housed within GraphCMS. Second, we utilize Postmark as a transactional email service to deliver confirmation and notification emails. Lastly, we use the powerful NextJs framework hosted in Now (both products of Zeit) that allow us to “repackage” our GraphCMS APIs as both triggers for our notification process (via GraphCMS webhooks) and as a processor of our email response - you can accept and approve of a talk directly from an email!

Here’s a guide to help us understand what’s happening in the service architecture.

GraphCMS
When looking at the content architecture above as well as the service architecture, GraphCMS hosts all the content, acts as the “submission database” and notifies our API endpoints when submissions have been added and when their acceptance status changes (via Webhook).

Next / Now
Next lets us build out our web application front-end as well as define our API functions that will run in the Now environment. Now hosts our web application as well as the lambda functions from our APIs and powers the connections between the different services.

Postmark
Postmark delivers all our transactional emails with a flexible but simple templating system and a “no-fuss” API.

Any of the above resources could be replaced by the services you already use, but hopefully, this gives you an idea of how to get started connecting the best of breed APIs together to architect any kind of submission/approval process – your way.

The code for the example can be found over on GitHub. There you will find instructions on how to set up, configure, and manage the project yourself.

Beyond Static, a Gatsby Tale

Jesse Martin — Wed, 29 Jan 2020 14:36:17 +0000

TLDR;
Here's the important stuff.

Jesse Martin

@motleydev

Big thanks to @bitgrip for inviting me to the Headlessons meetup last night! As promised, here's the repo for the project I showed, and the Demo:

🛠️ Repo: github.com/GraphCMS/examp…
⚡️ Demo: gatsby-static-dynamic-hotel.now.sh

Built with @gatsbyjs and @GraphCMS

16:15 PM - 23 Jan 2020

Follow me for ~~my personal vanity~~ engaging content about building software and stories about my kids.

Intro

In the world of static site generators, one rule remains constant - the build is the gospel. Whatever was at build time will be until a new build occurs. It's part of what makes them so fast, anything sourced from a database, flat-file, CMS, or what have you - becomes stamped into code in HTML, CSS, and JavaScript. Once that transformation occurs, there's no need for data fetching, transformation or template rendering - that part is done! Browsers can simply show you exactly what the server sends.

But sometimes our data, you know, changes. Imagine running a stock exchange on a static site?! Even modern ecommerce sites have pricing that can vary hundreds of times a day to reflect real-time ~~price manipulation~~ supply and demand forces.

So what's a JAMing developer to do? Well, the obvious solution is to build the parts that have a longer "TTL (time-to-live)" and fetch the changing bits from the client.

When dealing with Gatsby, however, that presents a challenge. One of my favorite things about Gatsby is the content mesh API that it creates. You can throw nearly any data source at it, even plain text files, and someone in the community will have created a plugin that parses the data and puts it into a flexible GraphQL API. From there, you can query all the data you want, and push the data through React templates. It's really a fantastic experience.

But it only works at build time. The API goes away, the data is stamped to a persistent state for rehydration, the clowns get back in the car and go home. If you want to query data from the browser, you'll need to reference back to the original data source that the Gatsby plugin you are using is sourcing from. Most external systems are still exposing a REST interface which means you now need to work with two different API protocols.

A Hero emerges

Thankfully, a growing number of online services are beginning to expose a native GraphQL interface, too! We at GraphCMS have been native GraphQL from the beginning, and when you source content from us, you can use the same knowledge base and experience you've gathered building the static site to now fetch content straight from the original source.

Let's look at the two places we fetch data in our demo example. Our domain, for context, is a hotel listing website, cleverly named "Gotell" that fetches available rooms dynamically.

I'm available for naming your Startup if you need me.

To generate this index page, we fetch our data in the gatsby-node.js file. As I generated multiple demos for this talk, you'll notice I fetch TWO batches of data and merge them together, this is not needed in most cases but I chose to do that since I used the separate data sources for other demos.

exports.createPages = async ({ graphql, actions }) => {
  const { createPage } = actions

  // import various templates needed...


  const minimalQuery = await graphql(
    `
      query {
        gcms {
          hotels {
            id
            slug
            name
          }
        }
      }
    `
  )

  if (minimalQuery.errors) {
    throw result.errors
  }

  const minHotels = minimalQuery.data.gcms.hotels

  const extendedQuery = await graphql(
    `
      query {
        gcms {
          hotels {
            id
            description
            photos {
              url
            }
          }
        }
      }
    `
  )

  if (extendedQuery.errors) {
    throw result.errors
  }

  const extendedHotels = extendedQuery.data.gcms.hotels

  // Create a merged data set, what would essentially be one large query"
  const hotels = merge(minHotels, extendedHotels)

  /*
   Demo One!
   Creating a single large index from the content
  */

  createPage({
    path: "/demo-one/hotels",
    component: hotelIndexPage,
    context: {
      hotels,
    },
  })

...

})

We pass that list of hotels to the pageContext where it will be converted to HTML at build time. From the template, we fetch our dynamic content.

const Hotels = ({ pageContext }) => {
  const [hotels, updateHotels] = useState(pageContext.hotels)
  const [roomsFetched, setRoomsFetched] = useState(false)

  useEffect(() => {
    let isCurrent = true
    ;(async () => {
      const { data } = await postData(process.env.GATSBY_GCMS_URL, {
        query: `query {
            hotels {
              id
              rooms
            }
          }`,
      })
      if (isCurrent) {
        updateHotels(hs => merge(hs, data.hotels))
        setRoomsFetched(true)
      }
    })()
    return () => (isCurrent = false)
  }, [])

  return (
    <Layout>
      <SEO title="Demo One" />
      <div className="flex flex-wrap">
        {hotels.map((hotel, key) => (
          <HotelBox hotel={hotel} key={key} roomsFetched={roomsFetched} />
        ))}
      </div>
    </Layout>
  )
}

An important detail here is that we push the pageContext data into the React state and iterate over that array instead of directly from pageContext. This allows us to update our state with the fetched data from our useEffect hook and update the entries where applicable.

Summary

There's nothing really more complex about this example. The basic process follows fetching data at build time, then fetching partial data at client load time and using an updater pattern to let us combine the data on the page. The key benefit here is being able to use GraphQl for both parts. If you examine the two code samples above we are writing nearly identical query syntax in both cases (our gatsby-source-graphql plugin adds a new top-level type which introduces an extra level of nesting for the build-time query.)

Removing the cognitively expensive context switching from any other API source to the data-mesh GraphQL API is a major win. The only catch is that you need a system that natively supports GraphQL - which is something we are happy to help you with!

The Secret Languages of Culture - and Slack

Jesse Martin — Wed, 06 Nov 2019 10:16:29 +0000

I’m guilty of a particular hand gesture that, for whatever reason, seems ingrained in my muscle memory though I have no remembrance of how it got there. The gesture has zero significance to me, and, interestingly enough, seems relatively common amongst various other Americans I’ve come to know since moving overseas as an expat.

The gesture involves, more or less, slapping of an open hand (usually the left) on to the closed fist of the right - or sort of bringing them together - with either the unintended or intended consequence of a slight popping sound happening in the hollow of the right hand. It’s used often to start a sentence, often if order needed to be called first, in a group of peers. Think of it as a gym class version of chiming a wine glass.

The gesture also happens to have incredibly crass and sometimes perverse meaning in foreign cultures. No doubt, the gesture I learned as an innate communication mechanism was simply borrowed from the cultures where its original meaning remains intact, but, like most things in the US, it simply lost its original flavor and now floats around in the stew we call American culture.

And culture is funny like that. A shared history of one community can quickly leave newcomers completely in the dark, if not entirely excluded. Yell “ABC” in the salesroom of a startup and you’ll likely get a handful of laughs. If you’re completely confused by that sentence, you’re not part of that culture. Look up Glengarry Glen Ross if you want in.

Culture imbues our identity and the subtexts in which we communicate with co-workers and friends. Order an espresso at lunch in the US and it means, “let’s keep the conversation going.” Order an espresso at lunch in Germany and it means, “we’re done here.”

Five years ago it was common to hear people make jokes about “nazis” in the US to mean anyone who was stingy. No soup for you (Seinfeld). You could never make that joke in Germany. Further, even in the US today, it’s been so co-opted by the “left” that it’s now meant to generally disparage anyone with a different opinion. In Germany, its true meaning and the horrors it implies remains prevalent and relevant.

A culture I’ve known primarily amongst my male friends is to communicate through quoting movies. Really, it’s amazing how much of the day-to-day has already been covered in the, er, “classics.” But even that communication, shared between people with familiar geo-contextual backgrounds, creates a culture of exclusion for those that didn’t see the same films. Access, availability, and opportunity become filters for an entire language that others may not have.

Prevalent in the tech industry (and many “knowledge worker” industries) is what has been called “the Slackification” of the modern office. A trend that encompasses many things, but non-the-least of which includes a predominance of text-based, emoji laden conversation.

Beyond just the normal, “standardized” set of emoji which has been blessed by the majority of tech companies, platforms such as Slack allow for custom emoji. It’s in particular with these custom emojis that we are exposed to a lot of cultural risk of both excluding others from the way we talk and even causing unintended offense.

A subset of developers I’ve worked with, being the meme-versed subculture that they (we) are, adore the “Pepe” meme for all forms of “reactions” to things people say. Coming from a US culture where Pepe has taken on a decidedly racist, misogynistic tone, it’s difficult to ignore. Further, being an old man in startup years (over 30) there’s a generation of meme usage (and emojified memes) that I simply don’t know. Not only myself but a class of us “older ones” where coworkers not even 10 years our junior have a subset of references that are lost on me. And the knife cuts both ways, there’s a wide range of 80's and 90's hit songs that I tend to quote with obnoxious regularity that are completely lost on a subculture that simply didn’t listen to the same music.

My children are now at the age where it’s amusing to create their own language as they play with the rules of what’s understood by the majority. The creation of custom Slack emojis is really no different. With a workforce that is diversifying at a rate never before seen, it’s important for all of us to not forget the standards of intercultural communication and to watch out for the pitfalls of creating “secret languages” that exclude and even accidentally harm others. The internet turned 50 this year and in many ways, we are more connected today than at nearly any other point in recorded history. With effort and an awareness of other’s cultural backgrounds, we can make sure the next 50 only bring us closer together.