DEV Community: Novvum

How we used Gatsby Themes to build a suite of consistent websites for our company

Trevor Heath — Mon, 07 Oct 2019 18:07:14 +0000

Here at Novvum, we are a software development firm that specializes in React, GraphQL, TypeScript, Node and so much more. Therefore, we enjoy building with modern technologies like Gatsby. Sadly, up until now, our website did not follow this trend.

A few months ago we decided it was time to give our site a much-needed upgrade. We always take great pride in designing and architecting cutting-edge web applications for our clients, but we hadn’t given much thought to our site and were still using a drag and drop editor for simplicity. Why? We would love to say that we were just too busy building awesome software for our clients, which is partially true, but we were also reluctant to upgrade because we needed a site that could be edited and designed by non-technical members of our team while still providing great performance and features.

Our requirements and motivations

Finally, after hearing enough about how our site was not reflective of our work from our partners and friends, we decided it was time to take the plunge and upgrade all of our sites. As we set out on this multi-website rebuild, we had a few key requirements for the codebase and maintenance workflows for the project.

The components, configurations, and functionalities needed to be reusable across all our company’s sites and easily accessible for future sites.
Landing pages
Blog
Internal documentation
Client Portal / Auditing Platform
Each site needed to be deployable, editable and extendable on its own without affecting the other clients
Content like blogs, audits and case studies needed to be easily edited by non-technical team members without diving into the codebase
All site's code/logic should be available in a single monorepo, while content (markdown/MDX) files should be available on their own and abstracted from the core logic.

As you can tell, most of the requirements set out to simplify the experience of composing functionality across different sites while still maintaining a separation of concerns between each domain and its deployment. We also wanted to keep non-technical content editing separate from feature development. To handle this, we used a combination of the following tools and techniques. I won't dive into them all but it gives you a decent idea of our configurations.

Gatsby Themes
Yarn Workspaces
Git Submodules
CI/CD with Gitlab

In this article, I will dive into the composition of our Gatsby themes and how we were able to tackle these requirements while simplifying the development workflow for all our websites.

Gatsby Themes as building blocks

If you haven’t heard of Gatsby it is a super-fast static site generator that allows you to use GraphQL to query your site’s configuration, assets and markdown files. It is extremely performant and customizable. Gatsby is the perfect fit for websites, blogs, eCommerce and other content focused sites because the markdown files containing content can easily be edited by technical and non-technical team members. Besides, Gatsby offers Gatsby themes that allow site functionality to be packaged as a standalone module so functionality can easily be reused. Rather than using starters or templates for every website you build, all the default configuration lives in an NPM package, that can be updated and shared across independent projects. This helped us provide a consistent yet adaptable experience across our main website/blog, client portal, and documentation website. Any changes to the underlying theme(s) will update on all current and future sites. Providing a seamless development workflow.

Here is how the architecture maps out:

The diagram outlines how we are using Gatsby Themes to share components and functionality across our suite of websites.

base-theme : Holds many of the core pieces of functionality across all Novvum sites. This includes theming, presentational components, utilities and more. Think of this as the more fundamental building block.

blog-theme : The blog theme is what it sounds like, the theme for all blog-specific functionality. This includes the blog specific components and routing information.

wiki-theme : This theme is specific to our internal documentation site and handles the routing and components needed to display out internal documentation. There is more on this theme and the motivation for its abstraction below.

auth-theme : One of the more interesting themes, this theme includes all the necessary modules for authentication. Plug it in and your deployed website has auth.

Composing themes

Initially, it is easy to assume Gatsby Themes are best used for styling and components. However, with some creativity, Gatsby Themes can provide a great way to share configuration, functionality, and logic for almost anything. It is not to much different from just deploying individual NPM modules.

So, Rather than dive into the more fundamental use cases for themes like using them to share UI and components, I want to quickly review how our auth-theme (green block) is currently being used to extend our client portal and internal documentation sites. Also, dive into how themes can provide a great abstraction for content files written in markdown and mdx . These are two ways we tackled our requirements in a creative way and may provide you with some inspiration.

Sharing logic + ui

Sometimes sharing a site logic can be a pain and may even require redundant code across websites. However, by using the basic Gatsby Theme concepts, we can share our authentication module across all of our sites.

By simply adding the auth-theme to the Client Portal and Internal Documentation gatsby-configs, we can extend both sites to with our prepackaged, consistent authentication module. In this case, we are using Netlify Identity for simplicity but this idea would not change for other more custom implementations. In our case, the auth theme` includes helper functions for user management, sign in modals, private routes and other key authentication functionalities. Now, if we ever want to include auth on any other sites, we just add that theme to the config and we are off and running. This is the same with the styling theme and component found in the base Gatsby Theme.

Abstracting away content from code

Another powerful feature of Gatsby Themes is the ability to extend themes with themes. Above you may have noticed the blue block inside the blog-theme and wiki-theme modules. That blue block is our base-theme which provides fundamental theming and components to all of our websites including the internal documentation and blog. This may seem a bit like themeception, but let me explain our thought process:

If you remember from above, one of our requirements was the ability of non-technical team members to edit and add content like blog articles and documentation without needing access to the entire codebase.

Well, by creating a blog-theme or wiki-theme , we can abstract all of the blog and documentation logic away from the final deployed site. Here is a look at the final internal documentation site's file structure and gatsby-config file:

├── public ├── content (all .md & .mdx files) | ├── assets | ├── guides | ├── index.mdx | └── projects ├── gatsby-config.js ├── netlify.toml ├── package.json ├── README.md

Woah! There is no src directory, meaning there are no React components! This is made possible because all of that code lives in the separate wiki-theme. This leaves the repo simple while only exposing the markdown files found in the content folder. Now content creators and non-technical team members can quickly add and edit content without knowing much about how the site works. The themes even handle routing, so new markdown (mdx in our case) files and folders automatically create new routes that will display information properly. The only reference to the theme can be found in the gatsby-config file.

module.exports = { __experimentalThemes: [ { resolve: "@novvum/gatsby-theme-wiki" } ],

Of course, another option for reaching this level of abstraction may be to use a CMS like Contentful. However, for small and midsized teams, this works great.

Okay, how do you work on all these abstractions together?

Well, that's where the monorepo, submodules, and Gitlab CI/CD comes together. With the current setup, you can interact with the codebases in a few ways.

You can directly edit content in the individual repos blog, internal documentation
You can directly edit site functionality in the individual repos.
You can edit all codebases in unison through our master monorepo. This monorepo includes submodules for each of the deployed sites as well as all the themes . Here is the folder structure:

This monorepo provides a superuser workflow to add, edit and change each of the separate themes and sites while still maintaining a separation of concerns. If only editing one of the clients is preferred, one can just clone and work in the specific site's repository without access to the underlying themes. This offers a bunch of flexibility!

Great, so now what?

Now that we have a flexible, scalable and robust underlying architecture for the Novvum suite of sites our team is confident we will be able to easily iterate, collaborate and extend our online presence without losing consistency. Need a new website? Add it to the monorepo, extend a theme and you are off an running!

If you are interested in learning more about any of the underlying concepts in this article, I would love to dive into the details on my next blog. Or if you have thoughts on how to improve this, we would love to hear from you.

To check out our new home go to novvum.io

Using Artificial Intelligence to Understand Emotions in Tweets

Alli Colyer — Tue, 27 Aug 2019 19:01:22 +0000

Hello, internet! Yesterday I introduced Feelsbot. Today I'll discuss how Feelsbot uses artificial intelligence to analyze emotional sentiment in Tweets. Feelsbot can analyze Tweets of any geographical location or any public Twitter profile.

What is Artificial Intelligence and Machine Learning?

Artificial Intelligence (AI) seems to be all over the place these days, but what exactly is it? Feelsbot, which uses AI to understand tweets, is a great example to help answer this question.

AI is a field of computer science dedicated to creating machines that can make intelligent decisions. You can think of artificial intelligence as a goal. We can reach that goal through machine learning. Machine learning is a way to teach machines how to make predictions or decisions without being explicitly programmed.

Machine learning models are said to learn because instead of being programmed to do things, they are trained. A model is trained through being shown lots of example data points and looking for patterns in the examples. Once identified, these patterns will be used to make decisions about new pieces of data.

Feelsbot uses a machine learning model created by IBM that categorizes text as being either joyful, sad, angry, disgusted, or fearful. This model was trained to detect emotion by being shown lots of examples of joyful, sad, angry, disgusted and fearful text. The patterns the model detected may involve keywords, such as “cry” or “cheer”, or they may involve the number of words in each sentence. Whatever the patterns are, they all come together to form the machine learning model.

Natural language processing is a subset of AI that aims to understand human language. The machine learning model that powers Feelsbot can also be called natural language processing.

Inspiration for Creating Feelsbot

There are a few reasons why I decided to create Feelsbot. First off, I was inspired by how easy it is to hop in and use some of the machine learning APIs from IBM and Google. Additionally, I wanted to create a software project to help people better understand how AI works.

Feelsbot highlights a couple of important things about AI and natural language processing.

Many machine learning models have a rather simplistic view of emotion, and can’t pick up on subtle things, such as sarcasm.
Sometimes figures of speech can throw off the model, for example, "I'm so happy I could cry" is detected as sad with a 65% confidence.

Although Feelsbot is not perfect, it’s more accurate than you might expect! I am often surprised by how well it can categorize more ambiguous tweets. Try it out to see for yourself.

Note: Tweets are short and often use slang which doesn’t always work well with a machine learning model trained with regular text excerpts. For this project, I did not train my own model, but it would be interesting to create a machine learning model that is trained using only tweets.

How Feelsbot Finds and Categorizes Tweets

As mentioned before, Feelsbot is using a machine learning model from IBM to analyze emotions in tweets. Using this model, Feelsbot put tweets into five categories: joy, sadness, anger, fear, and disgust. This model only works in English, limiting the number of tweets Feelsbot can analyze. Each tweet receives a score, called a confidence score, of how strongly it matches one of those categories. Feelsbot puts tweets that have a confidence score higher than 65% into each category. Once the tweets have been categorized, the joy meter is calculated as the percentage of joyful tweets versus every other emotion.

When using the map, Feelsbot uses Twitter's API to fetch the last 100 tweets that are geotagged near the location entered. If there are not many recent geotagged tweets near that location, Twitter fetches tweets of users whose profile locations are nearby. When analyzing tweets by a specific Twitter account, Feelsbot fetches the last 150 tweets by that account. Twitter profiles need to be public for Feelsbot to work.

What’s next for Feelsbot?

Check out Feelsbot and let me know what you think! By request, a hashtag search is currently in the works, so keep your eyes peeled for that update.

Also, I only touched the surface of what machine learning and AI are, but if you enjoyed this post and would like a more in-depth explanation, please leave a comment below!

Contributors

Big thanks to Novvum for supporting the development of Feelsbot.
Feelsbot was created by Allison Colyer.
Robot drawings were created by Ruby Ríos.

Introducing Feelsbot: Artificially Intelligent & Emotional

Alli Colyer — Mon, 26 Aug 2019 19:18:43 +0000

Hello, internet! This is Feelsbot. Feelsbot tries to understand how humans are feeling by reading their tweets. Feelsbot can analyze Tweets of any geographical location or any public Twitter profile.

Feelsbot uses artificial intelligence to analyze emotional sentiment in Tweets. Play around with Feelsbot and let us know what you think. Did Feelsbot surprise you in any way?

Stay tuned for a post tomorrow about what machine learning is and how Feelsbot is using it.

GraphQL Code-First and SDL-First, the Current Landscape in Mid-2019

Rohit Ravikoti — Fri, 12 Jul 2019 15:39:35 +0000

There has been a lot of buzz in the GraphQL community around code-first or SDL-first schema development as of late. The purpose of this blog is to shed some light on the current state of the ecosystem and help teams make a decision on which approach would be best for them.

To understand where we are today, it helps to take a look at how we got here.

Code-first: the original way to build a graphql schema

Facebook originally released graphql-js as a reference implementation for the GraphQL specification. The schema is defined as a plain javascript object:

const { GraphQLSchema, GraphQLObjectType, GraphQLString } = require('graphql')

const schema = new GraphQLSchema({  
  query: new GraphQLObjectType({  
    name: 'Query',  
    fields: {  
      hello: {  
        type: GraphQLString,  
        args: {  
          name: { type: GraphQLString },  
        },  
        resolve: (_, args) =&gt; `Hello ${args.name || 'World!'}`,  
      },  
    },  
  }),  
})

Many people in the community felt that writing a schema in this way was very verbose, and it was challenging to have a mental model of the schema while implementing it.

Enter SDL

The Apollo team released graphql-tools, which popularized the Schema Definition Language (SDL). Here is what the same schema from above looks like defined in SDL:

type Query {  
  hello(name: String): String  
}

It was much easier to understand the structure of the schema with SDL and, ultimately made the schema design process much more intuitive. The Apollo team also came up with schema directives to accompany the SDL.

One significant tradeoff for the SDL-first approach is that resolvers need to be implemented separately from the schema definition. Consequently, various new challenges came about. Directives are also not a part of the core GraphQL specification.

The pendulum swings back to code-first

Tools like TypeGraphQL and GraphQL Nexus were released to reduce the verbosity of graphql-js and provide a much simpler way to develop schemas than the SDL approach. These tools are built with graphql-js at their core, so they do not have support for schema directives — here are issues requesting support for them in TypeGraphQL and GraphQL Nexus.

Federated schemas…

The Apollo team recently introduced the Schema Federation specification for building distributed graphs. It significantly improved on a lot of the pitfalls of schema stitching and enabled a truly distributed architecture. The specification utilizes schema directives, so individual schemas can provide hints to the gateway server on how they are related to one another.

The major problem here is that the code-first libraries are unable to support schema federation because they do not support directives. There have been issues submitted for TypeGraphQL and GraphQL Nexus requesting support, but there hasn’t been much progress as of yet.

So, code-first or SDL-first?

Innovation will come with its fair share of disruption, and the GraphQL ecosystem is no exception. There are risks and tradeoffs when selecting any toolset, and teams must carefully look at their circumstances to understand which approach suits their needs.

Here are a couple of suggestions:

If your team needs schema federation or directives, then it is best to go with the SDL-first approach until the ecosystem catches up.
If your team doesn’t need schema federation or directives, then it is best to go with code-first — especially if you have a large schema. It will help your team keep your codebases organized and moving quickly.

What if you made the wrong choice?

The silver lining here is that you are not necessarily stuck with the decision your team makes now. Because both approaches are fundamentally the same (you define a schema and resolvers), it is not difficult to reuse most if not all of the business logic when switching from one approach to the other. One thing to note is that it is currently much easier to start with code-first and then switch to SDL-first because of the lack of schema directive support in code-first.

I hope this proved helpful for teams struggling to stay on top of everything that is happening in the GraphQL ecosystem. You can always reach out to us at Novvum for help!

about us: Novvum is a modern software development agency specializing in engineering, strategy, & design.

GraphQL Subscriptions with Nexus and React Apollo

Novvum Dev Team — Fri, 28 Jun 2019 18:23:12 +0000

Introduction

Subscriptions are a very powerful feature of GraphQL. They allow you to have a real-time connection to your database, notifying and updating your data when there are changes. Subscriptions have tons of applications, such as real-time chat applications or live comment feeds on articles.

In this tutorial, we are going to create a minimal real-time chat application using GraphQL Nexus and React Apollo. Hopefully by the end of this, you’ll be a pro at using subscriptions.

Meat and Potatoes

Getting Set Up

To get started, download this repository: https://github.com/hkyang995/graphql-nexus-subscription-starter-backend

This project contains a schema with a single

Post type- Post has two fields, author and content. We will set up a subscription to update a live chat feed with every new post that is made.

If you take a peek at src/schema.ts, you’ll see two queries,

post and posts. The post query returns the single most recent post, while posts returns every post in the database. And as you might have guessed, the createPost mutation creates a post.

Let’s get started by installing our tools: GraphQL Yoga, GraphQL Nexus, and GraphQL. We’ll be using Prisma’s demo servers to help get things set up and conveniently host all of our information. The starter file uses yarn to tie our dependencies together, so all we need to do is:

yarn

To start the server at any time during the tutorial, use:

yarn dev

Now that we’ve installed everything, we can create a server with Prisma using:

prisma init

This command will walk us through the creation of the server. Feel free to choose whatever suits your needs, but for simplicity’s sake, these options will do just fine:

Demo server
Choose EU or US
Name your shiny new service
Choose a name for this stage (just the default is fine)
Choose Typescript for our language of choice

Your server will be good to go after running prisma generate.

Now we’re finally ready to dive into making our Subscription!

Creating the Subscription on the Backend

Now that we are set up, we are ready to create our Subscription. Since each Subscription needs to return a payload (the bundle of information sent back to you), we’ll add a payload type to our schema.

const PostSubscriptionPayload = objectType({
 name: "PostSubscriptionPayload",
 definition(t) {
   t.field("node", {
     type: Post,
     nullable: true
   });
   t.list.string("updatedFields", { nullable: true });
 }
});

Like mentioned above, this payload type is the object type that will be returned from our subscription. The key item that we’re going to be looking at is t.field(“node”). We set its type to Post so it’ll return exactly what we need, a Post!

const messageSubscription = subscriptionField("post", {
 type: PostSubscriptionPayload,
 subscribe: (root, args, context) => {
   return context.prisma.$subscribe.post({ mutation_in: "CREATED" }) as any;
 },
 resolve: payload => {
   return payload;
 }
});

Here’s the function that’s going to be doing most of the work. You might be thinking, “That’s it??” and yes, that is it! You don’t need anything else on the backend for this particular application.

Here’s how this code works. We set the type to PostSubscriptionPayload to return our post. You can see that we pass in an argument to the post mutation_in: ‘CREATED’, which means that we’re only going to subscribe to newly created posts (as opposed to posts that are edited or deleted). Finally, we return the payload which completes our Subscription!

You can test this out on your GraphQL Playground by starting it up with yarn dev. When you run the Subscription, it will start listening for new posts. When you create a new post using the createPost mutation, you’ll be able to see it in your Subscription’s tab.

You can check out and download the completed backend code here:

https://github.com/hkyang995/graphql-nexus-subscription-starter-backend/tree/completed

Creating the Subscription on the Frontend

We have our subscriptions working on the backend, but we’re not out of the woods yet. The next steps are to make subscriptions work on the frontend so we can see our shiny new Posts in real time.

To start out, let’s set up a simple UI and connect our frontend to the backend. To get started, download this repo of frontend code:

https://github.com/hkyang995/graphql-nexus-subscription-starter-frontend

To run the application at any time, use yarn start in the command line on the frontend folder.

const wsLink = new WebSocketLink({
 uri: `ws://localhost:4000/`,
 options: {
   reconnect: true
 }
});

const httpLink = createHttpLink({
 uri: "http://localhost:4000/"
});

const link = split(
 ({ query }) => {
   const { kind, operation } = getMainDefinition(query);
   return kind === "OperationDefinition" && operation === "subscription";
 },
 wsLink,
 httpLink
);

const client = new ApolloClient({
 link,
 cache: new InMemoryCache()
});

If you take a look at src/App.js, you’ll see that we’re using Apollo to connect our frontend with our backend. The backend server is set to localhost:4000, which can be changed if your server is being hosted elsewhere. We’re also connecting a WebSocket to all of this so we are able to get our subscriptions in real time.

Most of the legwork is being done in our components function, src/AppContents.js. In this file, there is a function that takes the input and does a mutation to push the Post to our server. In src/ChatBox.js, we query for the Posts that already exist and display them to the user.

For now, we can write out messages and submit them, but the chat box won’t update unless we refresh. To fix this, we will set up our Subscription on the frontend.

Using one of our imported packages, graphql-tag (gql), we can set up a subscription on the frontend like this:

const NEW_POST_SUBSCRIPTION = gql`
 subscription PostSubscription {
   post {
     node {
       content
       id
       author
     }
   }
 }
`;

Since we defined our subscription on the backend, we only need to specify what we want to grab from it on the frontend. Here we’re getting the content, id, and author.

<Query query={GET_EXISTING_POSTS}>
               {({ subscribeToMore, loading, error, data }) => {

The subscribeToMore function comes packaged in Apollo GraphQL, and is going to be our best friend on the frontend, as it’s going to get our Subscriptions to work. We can pass it through in our query function.

<ChatView
  data={data}
  subscribeToMore={() =>
    subscribeToMore({
      document: NEW_POST_SUBSCRIPTION,
      updateQuery: (prev, { subscriptionData }) => {
        if (!subscriptionData.data) return prev;
        const { node } = subscriptionData.data.post;
        return Object.assign({}, prev, {
          posts: [...prev.posts, node]
        });
      }
    })
   }
/>

Here, we’re passing the subscribeToMore function into our ChatView component. Let’s break down how this all works.

We’re passing the subscription into the document field, and updateQuery is a function that runs every time our query is updated.

const { node } = subscriptionData.data.post;

We can pull out the node from the subscription data, which contains all of the information about the post: the content, the post id, and the author of the post.

return Object.assign({}, prev, {
  posts: [...prev.posts, node]
});

At the very end, we’re updating our posts by setting it equal to its previous values, along with the new node we got from the subscription.

  componentDidMount() {
    this.props.subscribeToMore();
  }

The last thing we need to do is add the subscribeToMore function into the ChatView component’s componentDidMount function. This will allow it to update whenever it needs to.

And there you have it! Now whenever a message is sent, your subscription will update the frontend.

The completed code can be found here.

https://github.com/hkyang995/graphql-nexus-subscription-starter-frontend/tree/completed

Conclusion

In this tutorial, we built a real-time chat application using GraphQL subscriptions. With this under your belt, subscriptions will appear less daunting for more complex applications.

If you have any questions, comments, concerns, or just want to tell me about your day, feel free to leave a comment. For more content like this, feel free to follow Novvum on Twitter. Thank you!

JustGraphQL: Your One-Stop-Shop for GraphQL Resources, Tools, & Articles

Novvum Dev Team — Tue, 18 Jun 2019 19:29:21 +0000

As part of our mission to make GraphQL more accessible and easier to learn we a have created JustGraphQL: a website that will bring together the best of the GraphQL community in an easy to navigate way. If you would like to contribute or spotlight your projects or resources feel free to reach out.

about us: Novvum is a modern software development agency specializing in both engineering, strategy, & design.

36 GraphQL Concepts: An Easy Way to Learn GraphQL!

Kelsey Yim — Tue, 18 Jun 2019 19:28:52 +0000

We’ve compiled a list of the best articles and videos for learning the 36 most important concepts of GraphQL. With a few students on our team, we quickly realized it’s difficult for a beginner developer to distinguish what resources were accurate and actually helped them learn.

So our team decided that we wanted to make it easier for newcomers to understand GraphQL! We put together a list of helpful tutorials, examples, and articles explaining low-level and high-level concepts and tossed it on Github!

Github Repo:

https://github.com/Novvum/36-graphql-concepts

If you have any interesting and useful resources you’d like to add, feel free to make a pull request on our repository. We’d love to collaborate and create a reliable source of information for new or advanced developers.

about us: Novvum is a modern software development agency specializing in both engineering, strategy, & design.

Python + Marvel + GraphQL = PyMarvelQL

Jorge Carlos — Mon, 03 Jun 2019 17:08:01 +0000

Introduction 🌋

With the release of Avengers Endgame, there was no better time to build PyMarvelQL, a program that allows you to query the Marvel Database using GraphQL.

PyMarvelQL allows you to send GraphQL queries to Marvel’s REST API to get information about characters, comic series, stories, creators and much more.

Try it out 😲

Here is a query for characters with names starting with Captain. The query getCharacter() accepts the parameter nameStartsWith, which can be set to any value you want. Inside the query, you can include any fields that you want to fetch from the Marvel API. The available queries and parameters are based on the Marvel API documentation.

If you would like to download this tool head on over to this Github repository.

How it works 🏗

PyMarvelQL is built with 5 tools — Graphene 2.1, Python 3.7, Flask, flask-graphql, and Marvelous. Flask and Graphene are the main tools in this project. flask-graphQl is used to host a local GraphQL server, and Graphene is used to create the GraphQL resolvers and Object Types that allow the user to query the JSON data from the Marvel database.

Flask and Flask-GraphQL 🧪

“Flask is a web framework for python that provides you with tools, libraries, and technologies that allow you to build a web application.” This project relies on Flask to support running GraphiQL in the browser. It uses GraphQLView from the flask-graphql package to add a /graphql endpoint to the flask app. This is what the setup file looks like for flask-graphql.

Navigate to the /graphql endpoint to visit the GraphiQL playground to query comics, characters, creators and events.

Marvelous 🦸

“Marvelous is an Marvel API wrapper for python”. PyMarvelQL uses Marvelous to call a Marvel endpoint and retrieve a JSON object with all of the data needed for the resolvers. PyMarvelQL ships with our API key, but you can register for your own by visiting Marvel’s website. After getting an API key, you can fetch JSON objects like this:

The variable m contains an instance of the marvelous API that fetches data in the Marvel database data in the Marvel database. As shown above, the function accessData returns a JSON object depending on what the variable name is.

Graphene-Python 2.1 👌

“Graphene-Python is a library for building GraphQL APIs in Python easily, its main goal is to provide a simple but extendable API for making developers’ lives easier.” One of the main features of Graphene is that it allows us to create resolver methods and ObjectTypes. The resolver methods in PyGraphQL return JSON Data to the queries. For example, when fetching for Marvel characters the accessData function(mentioned above) is called and the JSON object is stored in the variable characters. Afterwards, the data is returned using these two functions:

These helper functions read the object as a string and return the query as an object. An ObjectType is also essential to returning the data that is being queried. As stated in Graphene documentation, “it is the single definitive source of information about your data. It contains the essential fields and behaviors of the data you’re querying.”

When creating an ObjectType, you must create the “fields and behaviors” exactly the same as how it is presented in the API’s documentation. This will ensure that the data will be returned correctly.

For instance, the Marvel API Documentation lists the fields that the Creator object has.. Most importantly, it shows what data type a field is. Using that information, you can create an ObjectType like this:

As shown above, the ObjectType is similar to the way Marvel creates their Creator class. The main difference is that the datatype of each field is declared with Graphene functions: String(), List(), and Field(). A detailed explanation of all the different Graphene functions can be found in its documentation.

Contact Us

If you like PyMarvelQL, please follow us on twitter (@novvumio) and give us a star 🌟 on Github! If you find any issues, we’d love to fix them! You can submit them here.

How to Query Enums with GraphQL using Introspection

Novvum Dev Team — Tue, 21 May 2019 18:36:40 +0000

Why use Introspection to Query Enums?

When you are working on a project that allows users to pick an option, such as a school name, it is best to query for these values from your database instead of storing them on a list. This is because if new options are added you won’t have to worry about updating a list on the frontend. Moreover, if you needed to use these values in another file you could simply call the enum query.

What’s Introspection?

Introspection allows you to ask a GraphQL schema for information about what queries it supports.

In the introspection system, there are 6 introspection types we can use __Schema, __Type, __TypeKind, __Field, __InputValue, __EnumValue, __Directive. To query the enums you need to use the __Type query resolver.

Using __Type

For this example, I will be using an enum that stores the names of 7 universities.

‍

‍

Here’s how to query this enum:

‍

‍

The __type query resolver requires the name parameter. This parameter allows you to search your schema for items such as objects and enums based on their name.

Once you run this query your result should look like this:

‍

‍

This returns the name of the enum with all of its values. To use these values, store them in a variable when querying the enums. The statement should look like this:

items = data.type.enumValues

Application on React Frontend

This example illustrates how to apply the enum query on a dropdown menu created withmaterial-ui components. The enum items are stored in the list menuItems and then passed to the dropdown component with the map method. Thus, every time the user interacts with the dropdown menu the query will be called and all the values stored in the menuItems will be displayed.

‍

‍

The end result should look like this

‍

‍

Conclusion

Using introspection is easy and it’s a great way to reduce the number of variables that store the same information in your database. The best thing about using introspection is that no changes need to be done to the frontend to update the list being displayed.

If you want to learn more about introspection, I found this article helpful, GraphQL Introspection and Introspection Queries

If you want to learn more about GraphQL, I found these helpful concepts, 36-GraphQL-concepts.

about us: Novvum is a modern software development agency specializing in both engineering, strategy, & design.

TypeGraphQL and GraphQL Nexus — A Look at Code-First APIs 👀

Novvum Dev Team — Tue, 07 May 2019 19:15:14 +0000

Ever since the Prisma team announced GraphQL Nexus, there has been much interest in code-first schema development. Here at Novvum, we think this is a massive step in the right direction, but there has been a lot of confusion over how Nexus differs from TypeGraphQL. This post aims to break down the differences and hopefully clarify the confusion.

Code-first: A programmatic API for constructing GraphQL schemas

Before we get started, let’s recap why code-first schema development came to be. A popular approach in the Node.js ecosystem for writing a GraphQL server is schema-first or SDL-first. In the schema-first convention, you first define a schema in a Schema Definition Language (SDL) and write resolvers separately. If you were using TypeScript, you would need to define the schema types a second time to be used in your code. Therefore, making a change in the schema requires changes in three different places — the SDL, the resolvers, and the TypeScript types.

In code-first, the schema is defined in the code, and the SDL gets generated as an artifact. You no longer need to keep track of schema changes in multiple locations! 🎊 Which brings us to Nexus and TypeGraphQL. Both libraries aim to help with code-first schema development, but they differ significantly in how they work.

Comparing APIs of GraphQL Nexus and TypeGraphQL 🗒

Types

When building a GraphQL schema, a lot of time is spent writing types. Because of this, both Nexus and TypeGraphQL try to make this process as simple as possible.

Given the following SDL type:

Here is how it would be defined in TypeGraphQL and GraphQL Nexus respectively:

TypeGraphQL | Top GraphQL Nexus | Bottom

As you can see, the APIs of the two libraries are very different. TypeGraphQL uses classes and relies on an experimental TypeScript feature called decorators (the lines of code that start with the @ symbol). GraphQL Nexus uses native JavaScript syntax.

With TypeGraphQL, the TypeScript type is simply the User class that we write. It also integrates well with other decorator-based libraries like TypeORM, sequelize-typescript or Typegoose.

On the other hand, Nexus auto-generates type-definitions as we develop, and infers them in our code, giving us IDE completion and type error catching out of the box. It also has seamless integration with various databases with the upcoming Yoga 2. UPDATE: Here is a blog post outlining how to integrate GraphQL Nexus with Prisma.

Resolvers

Okay, so both libraries are very straightforward when it comes to defining types and eliminating redundant code between the schema definition and TypeScript types. Now, how would we write the resolvers? This is where the two libraries take very different approaches.

Here is how we would add resolvers for our User type in both libraries:

TypeGraphQL | Top: GraphQL Nexus | Bottom

With TypeGraphQL, the resolvers live separately from the type definition, similar to the SDL-first paradigm (EDIT: I stand corrected. It is possible to define resolvers in the same location as the type definition). The resolver for the posts field is defined using the @FieldResolver() decorator. You would add fields for the root Query and Mutation by using the @Query(returns => User) and @Mutation(returns => User) decorators respectively.

With GraphQL Nexus, the resolvers are part of the type definition. Another bonus is that we get code completion as we write the resolvers since Nexus is auto-generating the TypeScript types for the resolvers.

A Closer Look at the API Design Decisions 🔭

I will let the two libraries speak for themselves from their docs.

TypeGraphQL:

To add a new field to our entity, we have to jump through all the files: modify the entity class, then modify the schema, and finally update the interface. The same goes with inputs or arguments: it’s easy to forget to update one of them or make a mistake with a type. Also, what if we’ve made a typo in a field name? The rename feature (F2) won’t work correctly.

TypeGraphQL comes to address these issues, based on experience from over a year of developing GraphQL APIs in TypeScript. The main idea is to have only one source of truth by defining the schema using classes and a bit of decorator help. Additional features like dependency injection, validation and auth guards help with common tasks that would normally have to be handled by ourselves.

GraphQL Nexus:

The core idea of GraphQL Nexus draws from basing the schema off the SDL — keeping things declarative and simple to understand. It allows you to reference the type names as string literals rather than always needing to import to reference types (you can do that too if you prefer).

By combining automatic type generation with some of the more powerful features of TypeScript — type merging, conditional types, and type inference, we can know exactly which type names we are referring to and able to use throughout our code. We can know both the parameters and the return type of resolvers without providing any type annotation. It takes a little getting used to, but it ends up leading to a great feedback loop of the types annotating themselves.

Summary: Which One to Choose?

I hope these examples helped you understand how different the two libraries are. Let’s take a look at some of the tradeoffs of each library.

TypeGraphQL

Pros:

Reduces the number of places to keep track of your schema from three to two or one. TypeScript types and schema types are combined, but resolvers can either be defined separately or alongside the type definition.
Has been around longer, so at the time of writing, it has more features like field validation and authorization.
What you see is what you get when it comes to TypeScript types.

Cons:

Works only with TypeScript since it relies on metadata reflection.
The way we annotate types feels redundant when defining fields and resolvers which could lead to silent mismatch errors. More details here.

NOTE: If you are currently using TypeGraphQL and it is providing value for you or your team, please donate to them!

GraphQL Nexus

Pros:

Reduces the number of places to keep track of your schema from three to one. The schema and TypeScript types and resolvers are in one place.
Sticks to using standard JavaScript syntax and generates TypeScript types, so it works with both languages.
Autocompletion and type-checking support for IDEs provide a great developer experience.

Cons:

The younger of the two libraries, so it is missing some useful features. Some are on the horizon.
Since it relies on type generation, the server has to be running while developing. More info here.

Which one we prefer 🙌

At Novvum, we have been using Nexus pretty extensively, and we migrated MarvelQL, a GraphQL wrapper around the Marvel API, to use it. After also trying TypeGraphQL, we feel that Nexus has been much friendlier to work with, given us more flexibility, and enabled us to move more quickly. However, this is what works well for us, and we understand that all teams operate differently.

Let us know what you think ✍️

I hope this post proved helpful for those who were not sure of what the differences were between the two libraries. If there is still confusion, please reach out to us!

about us: Novvum is a modern software development agency specializing in both engineering, strategy, & design.

Implementing Authentication using JWT, Bcrypt and GraphQL Nexus

Novvum Dev Team — Thu, 02 May 2019 21:13:55 +0000

You’ve finished coding the skeleton for your application, but it’s missing one thing — authentication. This can be added using JSON Web Tokens and Bcrypt. The basis of this tutorial should be similar for most schema construction frameworks, but we will be using GraphQL Nexus. We’re also using Prisma as our ORM, but any other ORM or database would work.

This tutorial assumes you have knowledge of GraphQL mutations, queries, resolvers, and context- If you don’t know GraphQL, How to GraphQL is a great place to start.

The final application will allow users to create an account and log in by storing and using a JSON Web Token. JWTs are strings that contain information to transfer between parties and are a great way to authenticate users because they can securely store user information and provide a digital signature.

Our application will allow users to log in and register using these JWTs. On the backend, we will create a payload, add a JWT secret, and set up login and signup mutations to properly generate authorization headers. On the frontend, we’ll pass an authorization token into our headers, and set up our queries to get the current logged in user.

Backend

1. Installing Our Tools 🛠

First thing’s first, we’ll need to install Bcrypt and JSON Web Tokens!

yarn add bcrypt jsonwebtoken

Now you’re ready to get started✨

2. Creating our JWT Secret 🗝️

We can set up our JWT secret- in our config.ts file, the following was added:

export default {  
  ...  
  jwt: {  
    JWT_SECRET: 'super-secret',  
  },  
}

3. Creating the Payload 🚚

For us to properly return the token and user information to the requester, we need to set up a payload.

export const UserLoginPayload = objectType({  
  name: 'UserLoginPayload',  
  definition: t =&gt; {  
    t.field('user', {  
      type: 'User',  
    })  
    t.string('token')  
  },  
})

What we’re doing here is creating an object type named userLoginPayload. We define the type as being able to return our User field, along with the token generated when the user registers or logs in.

4. Setting up the Login and Signup Mutations 🚪🚶

To set up user registration and login, we create two new mutation fields, userLogin and userRegister. We can set the return type to UserLoginPayload to return the User and a token, and our arguments are the username and password collected from a form in the frontend. Here is what the mutations would look like in GraphQL Nexus:

export const userLogin = mutationField('userLogin', {  
  type: UserLoginPayload,  
  args: {  
    username: stringArg({ required: true }),  
    password: stringArg({ required: true }),  
  },  
})

export const userRegister = mutationField('userRegister', {  
  type: UserLoginPayload,  
  args: {  
    username: stringArg({ required: true }),  
    password: stringArg({ required: true }),  
  },  
})

After this, a resolver is added to the mutations.

export const userLogin = mutationField('userLogin', {  
  type: UserLoginPayload,  
  args: {  
    username: stringArg({ required: true }),  
    password: stringArg({ required: true }),  
  },  
  resolve: async (root, args, context, info) =&gt; {  
    try {  
      const { password, ...user } = await context.prisma.user({  
        where: {  
          userName: args.username,  
        },  
      })  
      var validpass = await bcrypt.compareSync(args.password, password)  
      if (validpass) {  
        const token = jwt.sign(user, config.jwt.JWT_SECRET)  
        return {  
          user: user,  
          token,  
        }  
      }  
      return null  
    } catch (e) {  
      console.log(e)  
    }  
  },  
})

We’ve added our resolver. This might be a bit overwhelming, so let’s break it up into pieces.

const { password, ...user } = await context.prisma.user({  
        where: {  
          userName: args.username,  
        },  
      })

Here, we’re trying to get User data. await context.prisma.users({where: {userName: args.username} gets our User information from the database, storing the information in password, ...user. We've separated the password so it won't be included in our user variable or the JSON Web Token data, as shown in the next step.

var validpass = await bcrypt.compareSync(args.password, password)  
      if (validpass) {  
        const token = jwt.sign(user, config.jwt.JWT_SECRET)  
        return {  
          user: user,  
          token,  
        }  
      }  
      return null

We use Bcrypt to compare to see if our password values are equal. If the passwords match, a JWT is generated using our JWT secret from the config file and user. (If we didn't separate the password data beforehand, it would have been returned with the user data and stored in the JWT 😱!) Though at last, we're now returning our payload (the user data along with the JWT)!

The process for registration is relatively similar.

export const userRegister = mutationField('userRegister', {  
  type: UserLoginPayload,  
  args: {  
    username: stringArg({ required: true }),  
    password: stringArg({ required: true }),  
  },  
  resolve: async (root, args, context) =&gt; {  
    try {  
      const existingUser = await context.prisma.user({  
        where: {  
          userName: args.username,  
        },  
      })  
      if (existingUser) {  
        throw new Error('ERROR: Username already used.')  
      }  
      var hash = bcrypt.hashSync(args.password, 10)

      const { password, ...register } = await context.prisma.createUser({  
        userName: args.username,  
        password: hash,  
      })  
      const token = jwt.sign(register, config.jwt.JWT_SECRET)  
      return {  
        user: register,  
        token: token,  
      }  
    } catch (e) {  
      console.log(e)  
      return null  
    }  
  },  
})

Let’s break this up again.

const existingUser = await context.prisma.user({  
        where: {  
          userName: args.username,  
        },  
      })  
      if (existingUser) {  
        throw new Error('ERROR: Username already used.')  
      }

Previously, we queried to see if a username existed. This is relatively the same, only now we are throwing an error if something is returned because each username should be unique.

var hash = bcrypt.hashSync(args.password, 10)

      const { password, ...register } = await context.prisma.createUser({  
        userName: args.username,  
        password: hash,  
      })

We hash the password passed into the form using bcrypt, passing in the password and the salt length we want to generate. After that, the createUser mutation makes a new user with our username and newly hashed password.

const token = jwt.sign(register, config.jwt.JWT_SECRET)  
      return {  
        user: register,  
        token: token,  
      }

The payload is generated and returned in the same way as the user login.

5. Adding User to the Context 🧮

Our user can now log in and register! Now we can create a query and viewer field to return that information to the frontend.

Let’s start out by adding the current user to the context.

export interface Context {  
  prisma: Prisma  
  currentUser: User  
}

export default async ({ req }) =&gt; {  
  const currentUser = await getUser(  
    req.get('Authorization'),  
    config.jwt,  
    prisma,  
  )  
  return {  
    prisma,  
    currentUser  
  }  
}

Here, we’re adding the variable currentUser of type User to be exported from our Context. We can use a getUser function (we'll go over how to make this function in the next step- in summary, it returns our User type) to return our user's information by passing in our token with req.get('Authorization') (which fetches our token from our header), our JWT secret, and the Prisma client.

6. Creating a getUser Function 👶

Because we want to query for user information in our application, we need to get our user’s token from the headers.

export default async (authorization, secrets, prisma: Prisma) =&gt; {  
  const bearerLength = 'Bearer '.length  
  if (authorization && authorization.length &gt; bearerLength) {  
    const token = authorization.slice(bearerLength)  
    const { ok, result } = await new Promise(resolve =&gt;  
      jwt.verify(token, secrets.JWT_SECRET, (err, result) =&gt; {  
        if (err) {  
          resolve({  
            ok: false,  
            result: err,  
          })  
        } else {  
          resolve({  
            ok: true,  
            result,  
          })  
        }  
      }),  
    )  
    if (ok) {  
      const user = await prisma.user({  
        id: result.id,  
      })  
      return user  
    } else {  
      console.error(result)  
      return null  
    }  
  }  
  return null  
}

Let’s go through this step by step.

const bearerLength = 'Bearer '.length  
  if (authorization && authorization.length &gt; bearerLength) {  
    const token = authorization.slice(bearerLength)  
    ...  
  }  
  return null  
}

Here we have some basic error checking to see if the token is longer than our Bearer string- If it is, we can extract the token by slicing off the Bearer string.

const { ok, result } = await new Promise(resolve =&gt;  
      jwt.verify(token, secrets.JWT_SECRET, (err, result) =&gt; {  
        if (err) {  
          resolve({  
            ok: false,  
            result: err,  
          })  
        } else {  
          resolve({  
            ok: true,  
            result,  
          })  
        }  
      })  
    )

Now we are verifying the token with our secret, and resolving our promise with whether the passed in token was valid or not, along with the result from our JWT (which is our user type).

if (ok) {  
      const user = await prisma.user({  
        id: result.id,  
      })  
      return user  
    } else {  
      console.error(result)  
      return null  
    }  
  }

Lastly, if the token was valid, we query for the user with the ID we got from our token and return it!

7. Creating a User Query and Viewer Field 🔬

We can create a viewer field and user query so we are able to query for the currently logged in user’s information in our application.

t.string('getCurrentUser', {  
  resolve: async (root, args, context, info) =&gt; {  
    return context.prisma.user  
  },  
})

We can create a new query, getCurrentUser- this returns the value of what we got in our Context function, making it so we can now easily query for whatever user is currently logged in!

Lastly, we should add a viewer field to our query.

t.field('viewer', {  
      type: 'User',  
      nullable: true,  
      resolve: (root, args, context) =&gt; {  
        return context.currentUser  
      },  
    })

This simply returns the currentUser that we added to our context.

Frontend

1. Login and Registration 💎

Now that our backend is complete, we can implement a simple frontend solution using the resolvers we created in the backend.

const SIGNUP_MUTATION = gql`  
  mutation UserRegister($username: String!, $password: String!) {  
    userRegister(username: $username, password: $password) {  
      user {  
        id  
        userName  
      }  
      token  
    }  
  }  
`;

Here is a simple signup mutation that creates a new user when the form is submitted. We are using the userRegister function that we created on the backend, and simply passing in a username and password while returning any desired information.

&lt;Mutation  
    mutation={SIGNUP_MUTATION}  
    onCompleted={data =&gt; _confirm(data)}  
  &gt;  
...  
&lt;/Mutation&gt;

Next, we can add the signup mutation to our Mutation component provided by react-apollo. When the mutation is completed, we call the function _confirm.

_confirm = async data =&gt; {  
  const { token } = data.userLogin;  
  this._saveUserData(token);  
};

_saveUserData = async token =&gt; {  
  try {  
    await AsyncStorage.setItem(AUTH_TOKEN, token);  
  } catch (e) {  
    console.log("ERROR: ", e);  
  }  
};

What our _confirm function does is take the data we were returned from our mutation and extracts the token from it, passing it to _saveUserData. This function stores the token in AsyncStorage (if you're not developing using Native, the token would be stored in LocalStorage).

WARNING: As a side note, using localStorage to store our JWT isn’t the best practice in production- you can read more about that here.

The process for logging in is extremely similar, we would just swap out our SIGNUP_MUTATION with our LOGIN_MUTATION.

2. Inserting the token into the header 💯

const authLink = setContext(async (_, { headers }) =&gt; {  
  const token = await AsyncStorage.getItem(AUTH_TOKEN);  
  return {  
    headers: {  
      ...headers,  
      authorization: token ? `Bearer ${token}` : ""  
    }  
  };  
});

We are using apollo-link-context's setContext function to set the headers of our application. We are getting our authorization token from AsyncStorage and then storing it in our header.

3. Querying for User Info 🙆

Because of all of our hard work, we can query for the user’s information anywhere we want in the app- Yep, it’s that simple!

const GET_USER = gql`  
  query getUser {  
    viewer {  
      id  
    }  
  }  
`;

Conclusion

And with that, your authentication is now set up! We have now created resolvers to return the desired payload and can query for the current logged in user anywhere in the application. This tutorial was inspired by Spencer Carli’s great tutorial, GraphQL Authentication with React Native & Apollo — give it a look if you’d like a more in-depth look on the things we went over in this tutorial. If you have any questions or suggestions, feel free to leave a comment, reach out to us on Twitter, or over on our website. Thank you!

Introducing GraphQL Birdseye 🦅

Novvum Dev Team — Tue, 30 Apr 2019 19:06:52 +0000

We are proud to officially release graphql-birdseye! Birdseye allows you to view any GraphQL schema as a dynamic and interactive graph. Try it out on our demo site!

Birdseye uses a “fog of war” 🌁 navigation style which dynamically zooms to show a portion of the schema at a time. This significantly simplifies the process of finding related types when compared to displaying the entire schema at once.

Getting started

You can get started with birdseye by reading the instructions here. The library is currently available as a React component, but if we get requests for other frameworks like Angular or Vue, we would be happy to work on those as well 🙂.

Why we built it

We were inspired to make a GraphQL schema visualization tool that can you can add to other sites and packages. We have seen a couple of other excellent tools like graphql-rover, graphql-voyager and graphql editor. We originally planned to integrate voyager with graphql-playground, but it would have added 1.2 MB to the package. This bundle size made the library very difficult to integrate with any other tools.

To solve this problem we created Birdseye which is lightweight and works well with other tools. In this process, we also made some helpful changes to the user experience (📣 to Prisma for helping brainstorm the “fog of war” navigation).

How we built it

When we first started, we spent the first month trying out various diagramming libraries like WebCola, Cytoscape.js, dagre and many more. Some libraries supported a portion of the features while others supported a different subset. At this point, we considered building our own visualization library, and we quickly realized how crazy that would be 😅.

We decided to keep looking and finally came across JointJS 🎊. It gave us a nice API to be able to define custom shapes and provided excellent layout and link routing algorithms. It also gave us the ability to modify these algorithms according to our needs. Best of all, it added very little to the bundle size (~70kb).

Having settled on JointJS, the rest of the project focused on understanding the API in more detail and using it to build out the library. Some of the other tools we used to make this happen were:

TypeScript: our go-to language whenever we can use it. The type-safety saves us from a lot of trouble by catching simple issues early on.
Rollup: A bundler that specializes in packaging libraries.
svg-pan-zoom: Simple pan/zoom solution for SVGs in HTML. It adds events listeners for mouse scroll, double-click, and pan.

Where we go from here

We are committed to improving this library and make it the go-to for visualizing your schema. We would love to hear your feedback so we can make it even better and we always welcome contributions. Some things we are planning to work on are:

Improve performance for larger schemas
Option to toggle zoom navigation style
Smoother UI transitions and interactions

Tell us what you think 🤔

If you like Birdseye, please follow us on twitter (@novvumio) and give us a star 🌟 on GitHub! If you find any issues, we’d love to fix them! You can submit them here.