DEV Community: Saswata Mukherjee

Build a chat app with GraphQL Subscriptions & TypeScript: Part 3

Saswata Mukherjee — Sun, 28 Feb 2021 09:09:01 +0000

Now that our server's ready let's start making our frontend! We won't be adding any CSS in this article, but you can definitely style it later on!

Initializing your frontend

At the root of your project run the following. We'll be using TypeScript here as well.

npx create-react-app chat-client --template typescript

Once that's done, add the dependencies we'll need. We'll be using Apollo Client for this tutorial, so run,

yarn add @apollo/client graphql subscriptions-transport-ws

As Apollo Client subscriptions communicate over the WebSocket protocol, we use the subscription-transport-ws library.

Apollo Client setup

Now let's add in our initial setup! Open up App.tsx and add the following,

import { ApolloClient, InMemoryCache } from "@apollo/client";
import { ApolloProvider } from "@apollo/client";
import { useState } from "react";

const client = new ApolloClient({
    uri: 'http://localhost:9000/graphql',
  cache: new InMemoryCache(),
});

const App = () => {
  const [name, setName] = useState<string>("");
  const [entered, setEntered] = useState<boolean>(false);

  return (
    <ApolloProvider client={client}>
      <div className="App">
        {!entered && (
          <div>
            <input
              type="text"
              id="name"
              value={name}
              onChange={(e) => setName(e.target.value)}
            ></input>
            <button onClick={() => setEntered(true)}>Enter chat</button>
          </div>
        )}

        {name !== "" && entered && (
          <div>
           Chats
          </div>
        )}
      </div>
    </ApolloProvider>
  );
};

export default App;

Alright, let's breakdown what we wrote!

First, we initialized an ApolloClient instance, client, with our GraphQL server endpoint and the InMemoryCache() class provided by apollo. We then connect our client to React, by passing it as a prop to ApolloProvider. This will wrap our React app and place our client in context which means that we can access our client from anywhere in our component tree and execute GraphQL operations.

Now, we would want a name from our user, so that the user can send chats in our chat app. So we declare a name state to store our user's name and an entered state so that we can figure when to show the chats and when to show an "enter chat" screen which would let the user enter their name. We use pretty simple conditional rendering to do this.

If the user hasn't entered the chat or provided their name, i.e, if entered is false, we show an input field to set the name state and an "Enter chat" button which sets entered to true. If entered is true and name isn't an empty string, we show chats (we'll be adding components for this soon). Also, we'll be using name as a local state and threading it through our components for now.

This is great up till now, but if you remember, our GraphQL API has a query, mutation, and a subscription. The query and mutation are resolved via our HTTP endpoint, but the subscription requires a separate WebSocket endpoint, which we haven't provided to our client yet. So let's go ahead and add that!

import { ApolloClient, InMemoryCache } from "@apollo/client";
import { ApolloProvider } from "@apollo/client";
import { WebSocketLink } from "@apollo/client/link/ws";
import { split, HttpLink } from "@apollo/client";
import { getMainDefinition } from "@apollo/client/utilities";
import { useState } from "react";

const wsLink = new WebSocketLink({
  uri: "ws://localhost:9000/subscriptions",
  options: {
    reconnect: true,
  },
});

const httpLink = new HttpLink({
  uri: "http://localhost:9000/graphql",
  credentials: "include",
});

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

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

const App = () => {
  const [name, setName] = useState<string>("");
  const [entered, setEntered] = useState<boolean>(false);

  return (
    <ApolloProvider client={client}>
      <div className="App">
        {!entered && (
          <div>
            <input
              type="text"
              id="name"
              value={name}
              onChange={(e) => setName(e.target.value)}
            ></input>
            <button onClick={() => setEntered(true)}>Enter chat</button>
          </div>
        )}

        {name !== "" && entered && (
          <div>
            Chats 
          </div>
        )}
      </div>
    </ApolloProvider>
  );
};

export default App;

Alright, so our client changed up quite a bit!

First, we initialize a WebSocketLink instance with our GraphQL API's subsciption endpoint. We also initialize a HttpLink instance with our GraphQL API's HTTP endpoint.

Now, since queries and mutations don't require a long-lasting real-time connection, http would be much more efficient for them. Thus, we could like to split our communication on the basis of the GraphQL operation required, i.e, we want to use HttpLink if it's a query or a mutation, but would switch over to WebSocketLink if it's a subscription.

We achieve this by using the split() function which assigns link based on a boolean check. It takes in three parameters, a function that's called for each operation to execute, a link if the function returns a "truthy" value, and a link if the function returns a "falsy" value. Here, we use the getMainDefinition() function to check if the operation in a subscription. If that returns true we use wsLink otherwise we use httpLink. link is later passed into our client.

Executing a mutation

Now that that's out of the way, let's figure out how to send a message in our chat app. We'll be using our createChat mutation in this case. Create a new file, SendMessage.tsx in the src directory and type the following,

import { useState, FC } from "react";
import { gql, useMutation } from "@apollo/client";

const SEND_MESSAGE = gql`
  mutation createChat($name: String!, $message: String!) {
    createChat(name: $name, message: $message) {
      id
      name
      message
    }
  }
`;

interface SendMessageProps {
  name: string;
}

const SendMessage: FC<SendMessageProps> = ({ name }) => {
  const [input, setInput] = useState<string>("");
  const [sendMessage, { data }] = useMutation(SEND_MESSAGE);

  const handleSend = () => {
    sendMessage({ variables: { name: name, message: input } })
      .then((data) => {
        console.log(data);
        setInput("");
      })
      .catch((err) => console.log(err));
  };

  return (
    <div>
      <input
        type="text"
        id="message"
        value={input}
        onChange={(e) => setInput(e.target.value)}
      ></input>
      <button onClick={handleSend}>Send message</button>
    </div>
  );
};

export default SendMessage;

Alright, we have a really simple component this time, with one input field to fill out the message the user wants to send, which is stored in our input state and a button that calls the handleSend() function when it's clicked. It also takes in the name of the user as a prop. The most important thing to note here is our mutation.

We use the useMutation hook from Apollo to call our mutation. We've defined our mutation query as a GraphQL string, SEND_MESSAGE which we pass into our hook. The useMutation hook in turn returns a tuple that has a mutate function (sendMessage() here) which we can call to execute the mutation and an object with fields that represent the current status of the mutation. We won't be using that object here for now.

We call the sendMessage() mutate function inside our handleSend method. Since our mutation has input variables, namely, name and message, we pass those in as the variables object, with values from our props and state. The mutate function returns a Promise so we use then() here to wait for the mutation to execute. Once the mutation is done we clear out the input state so that the user can type and send the next message. You can test this out now and view the messages you send in the console!

Executing a query

Now, we also need to be able to show our previous chats and update that whenever a new chat is sent. So let's define a new Chats.tsx component with the following code to accomplish this,

import { gql, useQuery } from "@apollo/client";

const ALL_CHATS = gql`
  query allChats {
    getChats {
      id
      name
      message
    }
  }
`;

const Chats = () => {
  const { loading, error, data } = useQuery(ALL_CHATS);

  if (loading) return <p>"Loading...";</p>;
  if (error) return <p>`Error! ${error.message}`</p>;

  return (
    <div>
      {data.getChats.map((chat: any) => (
        <div key={chat.id}>
          <p>
            {chat.name}: {chat.message}
          </p>
        </div>
      ))}
    </div>
  );
};

export default Chats;

Alright, let's understand what we wrote. We used the useQuery hook by Apollo, to execute our allChats query, which is defined as a GraphQL string, ALL_CHATS. When our component renders, the useQuery hook returns an object with loading, error, and data which we then use to render our UI.

When there's no error, and the data is done loading, we loop through our chats and display the name of the sender and the message. Keep in mind that Apollo Client automatically caches our query results locally, to make subsequent query results faster.

Use subscription to update query result

There's no real-time aspect in the Chat component yet. So sending in new chats won't update our UI unless we refresh. Let's fix this by adding in our subscription.

import { gql, useQuery } from "@apollo/client";
import { useEffect } from "react";

const ALL_CHATS = gql`
  query allChats {
    getChats {
      id
      name
      message
    }
  }
`;

const CHATS_SUBSCRIPTION = gql`
  subscription OnNewChat {
    messageSent {
      id
      name
      message
    }
  }
`;

const Chats = () => {
  const { loading, error, data, subscribeToMore } = useQuery(ALL_CHATS);

  useEffect(() => {
    subscribeToMore({
      document: CHATS_SUBSCRIPTION,
      updateQuery: (prev, { subscriptionData }) => {
        if (!subscriptionData.data) return prev;
        const newChat = subscriptionData.data.messageSent;

        return {
          getChats: [...prev.getChats, newChat],
        };
      },
    });
  }, []);

  if (loading) return <p>"Loading...";</p>;
  if (error) return <p>`Error! ${error.message}`</p>;

  return (
    <div>
      {data.getChats.map((chat: any) => (
        <div key={chat.id}>
          <p>
            {chat.name}: {chat.message}
          </p>
        </div>
      ))}
    </div>
  );
};

export default Chats;

We just changed a bunch of stuff so let's figure out what we did.

If you look closely, our UI logic hasn't changed one bit. However, our data fetching logic has.

The useQuery hook returns another function, subscribeToMore(). We can use this function to execute a followup GraphQL subscription that can push updates to our query's, i.e allChats, original results.

Now, we use the subscribeToMore() function inside a useEffect hook which has an empty dependency array, i.e, it fires when the component is mounted. We pass in two options to the subscribeToMore() function, document which indicates which subscription needs to be executed, and updateQuery which is a function that tells Apollo Client how to combine the query's currently cached result (prev here) with the subscriptionData that's pushed by our GraphQL subscription. The return value of this function completely replaces the current cached result for the query.

Thus, for document we pass in our subscription CHATS_SUBSCRIPTION defined as a GraphQL string, and for updateQuery, we pass in a function that appends the newChat received from our subscription to our previous chat data and returns that as an object that our UI can iterate over. The object is of the same type as the results of our allChats query but now has the latest chat at the last index of the getChats field array. Since this is a subscription, our cached chats will now get updated the moment a new chat arrives!

You might be wondering why we don't just execute the subscription using a useSubscription hook, eliminating the query altogether. We could, but this would result in the user getting only the messages after the user has entered the chat. We want to show previous chats as well which is why we chose this approach.

Test it out

Finally, let's use the Chats and SendMessage component in our App.tsx

import { ApolloClient, InMemoryCache } from "@apollo/client";
import { ApolloProvider } from "@apollo/client";
import { WebSocketLink } from "@apollo/client/link/ws";
import { split, HttpLink } from "@apollo/client";
import { getMainDefinition } from "@apollo/client/utilities";
import Chats from "./Chats";
import SendMessage from "./SendMessage";
import { useState } from "react";

const wsLink = new WebSocketLink({
  uri: "ws://localhost:9000/subscriptions",
  options: {
    reconnect: true,
  },
});

const httpLink = new HttpLink({
  uri: "http://localhost:9000/graphql",
  credentials: "include",
});

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

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

const App = () => {
  const [name, setName] = useState<string>("");
  const [entered, setEntered] = useState<boolean>(false);

  return (
    <ApolloProvider client={client}>
      <div className="App">
        {!entered && (
          <div>
            <input
              type="text"
              id="name"
              value={name}
              onChange={(e) => setName(e.target.value)}
            ></input>
            <button onClick={() => setEntered(true)}>Enter chat</button>
          </div>
        )}

        {name !== "" && entered && (
          <div>
            <Chats />
            <SendMessage name={name} />
          </div>
        )}
      </div>
    </ApolloProvider>
  );
};

export default App;

After saving, run yarn start and visit localhost:3000, enter the chat from 2 or 3 different browser tabs, and see the chats you send appear instantaneously in all tabs.

And voilà! We've successfully managed to make a full-stack chat application using GraphQL and TypeScript! You can now build on this even further and add in styles, a database, and even an authentication mechanism!

Conclusion

If you'd like to dig deeper into GraphQL, Apollo Client/Server, and TypeGraphQL and discover all the cool things you can make with it, read the official docs,

Also, here's an awesome list of resources to learn further!

If you get stuck here's the repo with all the code!

For any queries reach out to my socials or GitHub!

Build a chat app with GraphQL Subscriptions & TypeScript: Part 2

Saswata Mukherjee — Sun, 28 Feb 2021 09:08:29 +0000

In this part, we'll be adding our subscription to our GraphQL API.

What are subscriptions?

Subscriptions are long-lasting GraphQL read operations that can update their result whenever a particular server-side event occurs. Most commonly, updated results are pushed from the server to subscribing clients. For example, a chat application's server might use a subscription to push newly received messages to all clients in a particular chat room.

That's according to the official Apollo Server documentation. Essentially, it allows us to update our clients based on any server-side events. And since subscription updates are usually pushed by the server, they usually use the WebSocket protocol instead of HTTP.

Now that our GraphQL resolvers are working, we can send chats through our mutation and view all the chats which are presently there through our query! However, we also want to be alerted when a new chat arrives and that too in real-time(the exact moment the chat arrived! This is why we need a subscription operation as well!

So let's go ahead and add one! First, we need to set up our server, so that it can handle subscriptions since subscriptions use a completely different protocol from http! Apollo Server makes this setup relatively easy by allowing us to have a completely different endpoint only for our subscriptions.

Setting up our server to handle subscriptions

Open up index.ts and make the following changes

import "reflect-metadata";
import express from "express";
import { ApolloServer } from "apollo-server-express";
import { buildSchema } from "type-graphql";
import { ChatResolver } from "./resolvers/chat";
import http from "http";
import cors from "cors";
import dotenv from "dotenv";

dotenv.config();

const main = async () => {
  const app = express();
  const httpServer = http.createServer(app);

  app.use(cors({ origin: "http://localhost:3000", credentials: true }));

  const apolloServer = new ApolloServer({
    schema: await buildSchema({
      resolvers: [ChatResolver],
      validate: false,
    }),
    subscriptions: {
      path: "/subscriptions",
      onConnect: () => {
        console.log("Client connected for subscriptions");
      },
      onDisconnect: () => {
        console.log("Client disconnected from subscriptions");
      },
    },
  });

  apolloServer.applyMiddleware({
    app,
    cors: false,
  });
  apolloServer.installSubscriptionHandlers(httpServer);

  httpServer.listen(process.env.PORT, () => {
    console.log(
      `Server ready at http://localhost:${process.env.PORT}${apolloServer.graphqlPath}`
    );
    console.log(
      `Subscriptions ready at ws://localhost:${process.env.PORT}${apolloServer.subscriptionsPath}`
    );
  });
};

main().catch((err) => {
  console.log(err);
});

That's a ton of changes, so let's understand why we made them!

Firstly, we need to pass in a subscriptions object to our apolloServer instance with the endpoint path we want to reserve only for subscriptions as well as functions onConnect and onDisconnect, which will fire every time a client connects and disconnects from the endpoint we specified. And since we're using a middleware integration with Apollo Server and Express, we need to call the installSubscriptionHandlers() method defined by our apolloServer instance.

This leads to a limitation since we can only pass in an instance of http.Server to our installSubscriptionHandlers() method. We can't pass in an instance of express.Application or app as defined here. Thus, we need to define our own httpServer using the baked-in http Node library instead of using the one created for us by Express.

So we import the http module and create a http server based on our express application, i.e, app using the http.createServer(app) method. We call the installSubscriptionHandlers() method and pass in our httpServer.

Finally, instead of using app.listen() we use httpServer.listen(). Both of these methods achieve the exact same thing and return the same type(http.Server), but httpServer now has the required code to handle subscriptions, so we use that instead of app.

On saving and restarting the server, you should see your subscription url get logged in your console, i.e, ws://localhost:9000/subscription. Here ws signifies that the endpoint uses the WebSocket protocol!

Now, that our server can handle subscriptions let's actually add one!

Adding our subscription

Subscription resolvers are similar to queries and mutations but are slightly more complex. We'll be creating a class method as we did previously but with the @Subscription() decorator.

import { Mutation, Query, Subscription, Resolver, Arg } from "type-graphql";
import { Chat } from "../entities/Chat";

const chats: Chat[] = [];

@Resolver()
export class ChatResolver {
  @Query(() => [Chat])
  getChats(): Chat[] {
    return chats;
  }

  @Mutation(() => Chat)
  createChat(
    @Arg("name") name: string,
    @Arg("message") message: string
  ): Chat {
    const chat = { id: chats.length + 1, name, message };
    chats.push(chat);
    return chat;
  }
    @Subscription({ topics: "CHAT_CHANNEL" })
  messageSent(): Chat {}
}

We just created a messageSent() method in our ChatResolver class with a @Subscription() decorator. Thus our new method is now marked as a GraphQL subscription resolver. We have to pass in the name of the topic we wish to subscribe to, in our decorator as well. This can be a single topic, an array of topics, or even a dynamic topic. Since we will only be maintaining one chat channel in our app, we passed in the CHAT_CHANNEL string as our topic.

Triggering subscriptions and receiving payloads

Let's now add in the logic for triggering our subscription topic.

import {
  Mutation,
  Query,
  Resolver,
  Arg,
  Root,
  PubSub,
  PubSubEngine,
  Subscription,
} from "type-graphql";
import { Chat } from "../entities/Chat";

const chats: Chat[] = [];
const channel = "CHAT_CHANNEL";

@Resolver()
export class ChatResolver {
  @Query(() => [Chat])
  getChats(): Chat[] {
    return chats;
  }

  @Mutation(() => Chat)
  async createChat(
    @PubSub() pubSub: PubSubEngine,
    @Arg("name") name: string,
    @Arg("message") message: string
  ): Promise<Chat> {
    const chat = { id: chats.length + 1, name, message };
    chats.push(chat);
    const payload = chat;
    await pubSub.publish(channel, payload);
    return chat;
  }

  @Subscription({ topics: channel })
  messageSent(@Root() { id, name, message }: Chat): Chat {
    return { id, name, message };
  }
}

Again, that's a lot of new code to breakdown!

First, let's try to understand what PubSub is exactly. Apollo Server uses a publish-subscribe (pub/sub) model to track events that update subscriptions. The graphql-subscriptions library included in all apollo-server packages (including middleware integrations) provides a PubSub class as a basic in-memory event bus.

However, do keep in mind that this isn't suitable for production, since it only supports a single server instance. TypeGraphQL uses this PubSub system to define the @PubSub() decorator. For production, other implementations of such a pubsub system are recommended.

In this case, we want to trigger our CHAT_CHANNEL topic whenever a new chat is created, i.e, in our createChat() mutation. So we use the @PubSub() decorator to pass in pubSub as a method parameter, which is of type PubSubEngine. We can now use this to send a payload to all subscribers of the CHAT_CHANNEL topic.

Thus, we use pubSub.publish(channel, chat) method to publish the payload in our topic, in the pubsub system, by passing in our topic name ( channel now has the CHAT_CHANNEL string), and the chat object as arguments.

Since this returns a Promise, we need to use await. This also results in createChat() being an async method which now returns a Promise of type Chat.

Finally, in our subscription method, messageSent(), we use the @Root() decorator to receive the payload from the triggered topic in our pubsub system. For convenience, we made sure the payload is of type Chat which is again returned from our subscription method.

Run your subscription in GraphQL Playground

And that's pretty much it! We now have a complete GraphQL API, with a query, mutation, and a subscription! Let's test this out by heading over to our Playground at localhost:9000/graphql and try running the following.

subscription {
  messageSent {
    id
    name
    message
  }
}

While this is running, i.e the play button switches to red and you can see "Listening..." below, switch over to your createChat() mutation tab and create a new chat. You should be able to see the new chat pop up in the window where you left your subscriptions running!

Woohoo! Our subscription works!

Now that our backend is complete, we'll explore how to use all these GraphQL operations in the frontend using React. See you in the next part!

Conclusion

Visit the next post of this series to use your GraphQL server in React!

If you'd like to dig deeper into GraphQL, Apollo Server and TypeGraphQL and discover all the cool things you can make with it, read the official docs,

Apollo Server Docs

TypeGraphQL Docs

GraphQL Docs

Also, here's an awesome list of resources to learn further!

If you get stuck here's the repo with all the code! Visit the part-2 branch to get all the code covered in this post.

For any queries reach out to my socials or GitHub!

Build a chat app with GraphQL Subscriptions & TypeScript: Part 1

Saswata Mukherjee — Sun, 28 Feb 2021 09:07:53 +0000

Hey there!

If you're a little familiar with GraphQL, you've probably heard of subscriptions and how useful they are in building real-time applications. In this series of blogs, we're going to build a simple chat application using Node.js and React with GraphQL. We'll use TypeScript throughout this series and will be following a code-first approach!

Installing dependencies

We'll be using Apollo Server, Express and TypeGraphQL for this server.

Developing a GraphQL API in Node.js with TypeScript is always a bit of a pain since you'd have to manually create all your types, a lot of which will lead to redundancies later on, but TypeGraphQL really makes it easy using classes and decorator.

Let's start by running npm init -y in a fresh new directory to generate our package.json and install the required dependencies.

yarn add apollo-server-express class-validator cors dotenv express graphql reflect-metadata type-graphql
yarn add -D @types/cors @types/express @types/node typescript

We're basically using Express as a middleware integration for Apollo Server using the apollo-server-express package. Once all your dependencies are installed, create a src folder. This is where all our TS files will exist. That'll help us easily manage compilation.

We'll also need a tsconfig.json file to setup TypeScript to our liking. There's an awesome utility by Ben Awad which can automatically generate this for you. Run npx tsconfig.json and select node. Now we're all set to code up our GraphQL API!

We'll be following the file structure described below!

├── server
│     ├── src
│     │   ├── entities
│     |   |   ├── Chat.ts
│     │   ├── resolvers
│     |   |   ├── chat.ts
│     │   ├── index.ts
│     ├── package.json
│     ├── tsconfig.json
│     ├── .env

Building our server

Create an index.ts file and initialize our server using the code below,

import "reflect-metadata";
import { ApolloServer } from "apollo-server-express";
import express from "express";
import { buildSchema } from "type-graphql";
import cors from "cors";
import dotenv from "dotenv";

dotenv.config();

const main = async () => {
  const app = express();

  app.use(cors({ origin: "http://localhost:3000", credentials: true }));

  const apolloServer = new ApolloServer({
    schema: await buildSchema({
      resolvers: [ChatResolver],
      validate: false,
    }),
  });

  apolloServer.applyMiddleware({
    app,
    cors: false,
  });

  app.listen(process.env.PORT, () => {
    console.log(
      `Server ready at http://localhost:${process.env.PORT}${apolloServer.graphqlPath}`
    );
  });
};

main().catch((err) => {
  console.log(err);
});

Let's breakdown what we just wrote. We initialized our server inside an async main() function, just in case we need to await anything, and declared an express application, app. We also allowed cors from localhost:3000, which is where we'll run our React app later on. Also, do keep in mind to import the reflect-metadata shim package before importing type-graphql or any of your resolvers.

We then made a new instance of ApolloServer and applied our express middleware to that. Finally, we started our server, using app.listen(). We're also using dotenv to load env variables, namely PORT, from our .env file. For this example, we'll consider PORT=9000.

But as you've probably noticed by now, this won't run, since we don't have a ChatResolver yet. In fact, we don't have any resolvers for our GraphQL API yet, so let's go ahead and make a resolver.

But before that, we need to define our entity. Think of this as the universal type on which you'll write your GraphQL resolvers, i.e queries, mutations, and subscriptions as well as your database operations. This is exactly where TypeGraphQL comes in handy. We won't be using a database here, since our chat system will be ephemeral, but you get the idea!

Defining our entity

So create the entities/Chat.ts file and define our Chat entity using the following code!

import { ObjectType, Field } from "type-graphql";

@ObjectType()
export class Chat {
  @Field()
  id: number;

  @Field()
  message: string;

  @Field()
  name: string;
}

Alright, let's understand what we just wrote! We defined an exported TypeScript class Chat with multiple decorators. The class has three property members, id, message, and name, each with their own types. This is pretty straightforward, but let's understand what those decorators accomplish.

The main idea behind using TypeGraphQL decorators is to automatically create GraphQL schema definitions from TypeScript classes in SDL(schema definition language). This eliminates the need to make schema definition files and their equivalent interfaces in TypeScript.

Here, the first thing we did was decorate the Chat class with the @ObjectType decorator. It marks the class as type from the GraphQL SDL or GraphQLObjectType from graphql-js. Then we declared class properties that need to be mapped to the GraphQL fields. To do this, we use the @Field decorator, which is also used to collect metadata from the TypeScript type reflection system. By default all the fields in our entity here are non-nullable!

This entity will result in the generation of the following part of the GraphQL schema in the SDL.

type Chat {
  id: Float!
  message: String!
  name: String!
}

As you can see all fields are required(!) here, i.e non-nullable!

We've now successfully defined a GraphQL schema and its types for each of our chats! Now let's define a GraphQL resolver on our Chat entity.

Queries and Mutations

Create a resolvers/chat.ts file and type in the following,

import { Mutation, Query, Resolver, Arg } from "type-graphql";
import { Chat } from "../entities/Chat";

const chats: Chat[] = [];

@Resolver()
export class ChatResolver {
  @Query(() => [Chat])
  getChats(): Chat[] {
    return chats;
  }

  @Mutation(() => Chat)
  createChat(
    @Arg("name") name: string,
    @Arg("message") message: string
  ): Chat {
    const chat = { id: chats.length + 1, name, message };
    chats.push(chat);
    return chat;
  }
}

That's a lot of new code so let's understand what we're doing here. Aside from GraphQL object types, TypeGraphQL also allows us to create GraphQL queries, mutations, and subscriptions in a REST controller type fashion.

First, we define an array based on the Chat entity which will basically act as our database. Then we define an exported class ChatResolver with the methods, getChat(), which returns our entire chat array and createChat(), which appends a new chat object to the end of our array by taking the arguments, name and message. Now that we understand the normal functionality of this class, let's understand what those decorators add in.

The first decorator, @Resolver(), makes the class behave like a classic REST controller. Thus, the methods inside this class can now act like GraphQL query, mutation, and subscription handlers.

This brings us to the next decorators, which are @Query(() => [Chat]) and @Mutation(() => Chat), which lets us mark our resolver class methods as a GraphQL query or mutation resolver. We also need to explicitly declare the type that those methods resolve to, i.e, their return type, which here is an array of Chat objects for getChats() and a single object for createChat().

Finally, there's the inline @Arg() decorator, which lets us specify the arguments for a particular GraphQL query/mutation. We pass in the name of those arguments in this decorator.

Woohoo! Our resolver is now workable! Let's go ahead and try to run our server! But first, import the ChatResolver in index.ts and add the following scripts into package.json

"scripts": {
    "watch": "tsc -w",
    "dev": "nodemon dist/index.js",
    "build": "tsc",
    "start": "node dist/index.js"
},

Finally, fire up your terminal and run yarn watch in one and yarn dev in another! The watch command basically allows you to make changes in your TS files, which immediately get compiled into JS files inside a dist/ directory. Then we use nodemon, to run our compiled JS files and also restart on any changes. This results in a pretty near to prod dev environment!

Visit localhost:9000/graphql to view your GraphQL playground where you can run your queries!

Running GraphQL operations in GraphQL Playground

Now, visit localhost:9000/graphql to view your GraphQL Playground, and let's execute our queries and mutations.

To add a new chat, you'll run the following mutation:

mutation {
  createChat(name: "John", message: "first chat") {
    id
    name
    message
  }
}

and to get all chats, you'll run the following query

query {
  getChats {
    id
    name
    message
  }
}

As you can see, our class methods have turned into actual GraphQL operations which take in arguments and return Chat object fields! Do keep in mind that since we're storing our chats in an in-memory array, all your chats will disappear the moment you restart your server.

In the next part, we'll explore how to add a subscription to our new GraphQL API!

Conclusion

Visit the next post of this series to learn about GraphQL subscriptions and how to add them!

If you'd like to dig deeper into GraphQL, Apollo Server and TypeGraphQL and discover all the cool things you can make with it, read the official docs,

Apollo Server Docs

TypeGraphQL Docs

GraphQL Docs

Also, here's an awesome list of resources to learn further!

If you get stuck here's the repo with all the code! Visit the part-1 branch to get the code covered in this post.

For any queries reach out to my socials or GitHub!

Build a gRPC server in Go

Saswata Mukherjee — Sat, 05 Dec 2020 19:17:31 +0000

Hey there!

If you've dealt with microservices before, you've probably heard about gRPC.

In this blog, we'll be exploring the awesome world of gRPC and write our very own microservice with it. We'll also delve into why gRPC might be better than our traditional REST architectures as well the caveats associated with it.

What is gRPC?

gRPC is a modern open source high performance RPC framework that can run in any environment. It can efficiently connect services in and across data centers with pluggable support for load balancing, tracing, health checking and authentication. It is also applicable in last mile of distributed computing to connect devices, mobile applications and browsers to backend services.

That's according to the official documentation. Let's try to understand what an RPC framework is.

Remote Procedure Calls or RPC allow applications to communicate with each other in distributed systems. Simply put, it allows us to expose methods in our application that we want other applications to access.

It is sort of similar to REST in the sense that we are exposing functionality in our application over HTTP.

Differences between gRPC and REST

There are a few fundamental differences in how these two work:

gRPC utilizes HTTP/2 whereas REST utilizes HTTP/1.1. Using HTTP/2 enables certain capabilites such as server-side streaming, client-side streaming or even bidirectional-streaming. If you want to dig deeper into the difference between HTTP/2 and 1.1 you can refer to this article.
gRPC uses Protocol Buffers as opposed to the standard JSON data format typically used in REST. You can read about them here.

gRPC Caveats

While gRPC allows use you to use the latest and greatest stuff, there are certain challenges that it introduces. Traditional REST prototyping tools like Postman don't work easily with gRPC. There are workarounds to make it work but it isn't available natively. Howerver alternatives like BloomRPC and gRPCurl do exist.

There are even options to use tools such as envoy to reverse proxy standard JSON requests and transcode them into the right data format but this is an additional dependency that can be tricky to set up for simple projects.

Prerequisites

Before proceeding, make sure you have, atleast a high level understanding of protocol buffers. If you aren't familiar with them, I've written a tutorial which you can check out.

Also make sure you have the protoc tool installed on your system by running protoc --version.

Building our server

Let's start by initializing a new go module in a new directory. Run the following

go mod init grpc_using_go

Great! Now we'll start by defining a really simple server which our gRPC client will interact with.

First we'll listen on a a port for incoming TCP connections. We'll also be using logrus to generate structured logs. Create a main.go with the following code.

package main

import (
    "net"
    "os"

    log "github.com/sirupsen/logrus"
)

func main() {
    log.SetFormatter(&log.TextFormatter{
        FullTimestamp: true,
    })

    var port string
    var ok bool
    port, ok = os.LookupEnv("PORT")
    if ok {
        log.WithFields(log.Fields{
            "PORT": port,
        }).Info("PORT env var defined")

    } else {
        port = "9000"
        log.WithFields(log.Fields{
            "PORT": port,
        }).Warn("PORT env var not defined. Going with default")

    }

    _, err := net.Listen("tcp", ":"+port)
    if err != nil {
        log.WithFields(log.Fields{
            "Error": err.Error(),
        }).Fatal("Failed to listen")
    }
}

Here, I'm using os.LookupEnv which checks if a particular environment variable exists and returns the the value of the variable and a boolean. So if PORT is defined we'll use that or default to 9000. We're using logrus to generate nice structured color coded output with levels like Info, Warn, Error and Fatal.

Next, we'll import the official gRPC package from golang.org in order to create our gRPC server. We'll also register our endpoints and server over our TCP connection which we defined above.

package main

import (
    "net"
    "os"

    log "github.com/sirupsen/logrus"
    "google.golang.org/grpc"
)

func main() {
    log.SetFormatter(&log.TextFormatter{
        FullTimestamp: true,
    })

    var port string
    var ok bool
    port, ok = os.LookupEnv("PORT")
    if ok {
        log.WithFields(log.Fields{
            "PORT": port,
        }).Info("PORT env var defined")

    } else {
        port = "9000"
        log.WithFields(log.Fields{
            "PORT": port,
        }).Warn("PORT env var not defined. Going with default")

    }

    l, err := net.Listen("tcp", ":"+port)
    if err != nil {
        log.WithFields(log.Fields{
            "Error": err.Error(),
        }).Fatal("Failed to listen")
    }

    grpcServer := grpc.NewServer()

    log.Info("gRPC server started at ", port)
    if err := grpcServer.Serve(l); err != nil {
        log.WithFields(log.Fields{
            "Error": err.Error(),
        }).Fatal("Failed to serve")
    }

}

We just defined our grpcServer but currently it doesn't do a whole lot. So let's start adding some functionality to our server.

We'll start by defining our schema which will be a simple book structure with the properties of name and isbn number as well as an rpc service and method. Let's make our book.proto file like so.

syntax = "proto3";
package book;

message Book {
    string name = 1;
    int32 isbn = 2;
}

service BookService {
    rpc GetBook(Book) returns (Book) {}
}

This file defines the structure for Book protocol buffers and exposes a single service BookService. This service again has a single method GetBook which can now be called by any gRPC client written in any supported language.

These .proto files act as our "contracts" and typically can be shared across all clients. They can generate their own code and then communicate smoothly with our gRPC server.

Now, we'll generate the Go code for our .proto file using the protoc tool as mentioned above. Make a directory named book in the root of the project.

Now, run the following,

protoc --go_out=plugins=grpc:book book.proto

You should see that this generated a book/book.pb.go file. This file contains all the generated Go code which we can now use in our code to register our services and use our methods.

But as you can probably guess, this auto-generated code does not contain a definition for our service method GetBook. This is intentional since we would like to define what our gRPC service methods can do.

So let's go ahead and define our service method GetBook first. Create another file within the book directory book.go. This file will define the GetBook. For the sake of learning, we're just going to take a Book protocol buffer as argument, read the name and isbn, and then return a new Book.

package book

import (
    log "github.com/sirupsen/logrus"

    "golang.org/x/net/context"
)

// Server interface for our service methods
type Server struct {
}

// GetBook logs Book from client and returns new Book
func (s *Server) GetBook(ctx context.Context, input *Book) (*Book, error) {

    log.WithFields(log.Fields{
        "Name": input.Name,
        "Isbn": input.Isbn,
    }).Info("Book data received from client")

    return &Book{Name: "The Great Gatsby", Isbn: 90393}, nil
}

As you can see our method now has a definition. If we wanted to add more methods in our BookService we would simply need to add it to book.proto and define it off of our Server struct. Thus our application would be able to expose that method that gRPC clients can use.

Finally let's register this newly-defined method in main.go.

package main

import (
    "net"
    "os"

    "grpc_using_go/book"

    log "github.com/sirupsen/logrus"
    "google.golang.org/grpc"
)

func main() {
    log.SetFormatter(&log.TextFormatter{
        FullTimestamp: true,
    })

    var port string
    var ok bool
    port, ok = os.LookupEnv("PORT")
    if ok {
        log.WithFields(log.Fields{
            "PORT": port,
        }).Info("PORT env var defined")

    } else {
        port = "9000"
        log.WithFields(log.Fields{
            "PORT": port,
        }).Warn("PORT env var not defined. Going with default")

    }

    l, err := net.Listen("tcp", ":"+port)
    if err != nil {
        log.WithFields(log.Fields{
            "Error": err.Error(),
        }).Fatal("Failed to listen")
    }

    s := book.Server{}

    grpcServer := grpc.NewServer()

    book.RegisterBookServiceServer(grpcServer, &s)

    log.Info("gRPC server started at ", port)
    if err := grpcServer.Serve(l); err != nil {
        log.WithFields(log.Fields{
            "Error": err.Error(),
        }).Fatal("Failed to serve")
    }

}

Now, that it has been registered, it's finally time to run and test our code. Go ahead and run go run main.go. You should see the following logs pop up in your terminal.

WARN[2020-12-05T23:27:12+05:30] PORT env var not defined. Going with default  PORT=9000
INFO[2020-12-05T23:27:12+05:30] gRPC server started at 9000

Aside from the timestamp, it should be the same.

Yay! You're gRPC server is now running. You can make the WARN log go away by simply setting an environment variable using export PORT=9000.

Alright, now let's test this. Fire up a new terminal. We'll be using a tool known as gRPCurl to test our gRPC server. If you're on a Mac, simply install it using homebrew by running,

brew install grpcurl

For other platforms and package managers, refer to installation instructions in the linked repo.

Now, to test our server using this, we need to enable something known as gRPC Server Reflection. gRPC Server Reflection provides information about publicly-accessible gRPC services on a server, and assists clients at runtime to construct RPC requests and responses without precompiled service information. You can learn more about it here.

All we need to do is add the reflection package and simply add one line of code as shown below.

package main

import (
    "net"
    "os"

    "grpc_using_go/book"

    log "github.com/sirupsen/logrus"
    "google.golang.org/grpc"
    "google.golang.org/grpc/reflection"
)

func main() {
    log.SetFormatter(&log.TextFormatter{
        FullTimestamp: true,
    })

    var port string
    var ok bool
    port, ok = os.LookupEnv("PORT")
    if ok {
        log.WithFields(log.Fields{
            "PORT": port,
        }).Info("PORT env var defined")

    } else {
        port = "9000"
        log.WithFields(log.Fields{
            "PORT": port,
        }).Warn("PORT env var not defined. Going with default")

    }

    l, err := net.Listen("tcp", ":"+port)
    if err != nil {
        log.WithFields(log.Fields{
            "Error": err.Error(),
        }).Fatal("Failed to listen")
    }

    s := book.Server{}

    grpcServer := grpc.NewServer()

    reflection.Register(grpcServer)

    book.RegisterBookServiceServer(grpcServer, &s)

    log.Info("gRPC server started at ", port)
    if err := grpcServer.Serve(l); err != nil {
        log.WithFields(log.Fields{
            "Error": err.Error(),
        }).Fatal("Failed to serve")
    }

}

Simply restart your server again, open another terminal and run the following command,

grpcurl -plaintext localhost:9000 list

The -plaintext flag is due to the fact that our local server has no TLS certificate yet. list lists all our registered service on our server. Our gRPC server is [localhost:9000](http://localhost:9000) You should see the following output.

book.BookService
grpc.reflection.v1alpha.ServerReflection

Nice! Our gRPC service shows up. Let's see a bit more detail by running the following,

grpcurl -plaintext localhost:9000 describe

describe describes all our service and methods as you can see below,

book.BookService is a service:
service BookService {
  rpc GetBook ( .book.Book ) returns ( .book.Book );
}
grpc.reflection.v1alpha.ServerReflection is a service:
service ServerReflection {
  rpc ServerReflectionInfo ( stream .grpc.reflection.v1alpha.ServerReflectionRequest ) returns ( stream .grpc.reflection.v1alpha.ServerReflectionResponse );
}

Finally let's test our GetBook method by running the following,

grpcurl -d '{"name": "To Kill a Mockingbird", "isbn": 12345}' -plaintext localhost:9000 book.BookService/GetBook

The -d flag is used to send non-empty request body while invoking a RPC method. Here we specify the name and isbn of a book. All arguments must come before the server address. At the end we specify the service and method name in Service/Method format. You should see the following output as well as a new server log.

{
  "name": "The Great Gatsby",
  "isbn": 90393
}

INFO[2020-12-05T23:31:04+05:30] Book data received from client                Isbn=12345 Name="To Kill a Mockingbird"

Conclusion

If you'd like to dig deeper into gRPC and discover all the cool things you can make with it, read the official docs,

gRPC Docs

Also, here's an awesome list of resources to learn further!

If you get stuck here's the repo with all the code!

For any queries reach out to my socials or GitHub!

Protocol Buffers in Go

Saswata Mukherjee — Wed, 05 Aug 2020 13:17:57 +0000

Hey there! If you've explored the world of microservices, you've probably come across the term gRPC. It's a modern open source high performance Remote Procedure Call framework which can run in any environment. It's grown super popular recently with scalable distributed system architecture.

A major reason why gRPC has grown so popular, is due to the fact that it uses a special mechanism for data serialisation which makes payloads smaller, faster and simpler. This helps us save those precious milliseconds. But what is this special mechanism?

Enter Protocol Buffers.

What are Protocol Buffers?

Protocol buffers are Google's language-neutral, platform-neutral, extensible mechanism for serialising structured data – think XML, but smaller, faster, and simpler. You define how you want your data to be structured once, then you can use special generated source code to easily write and read your structured data to and from a variety of data streams and using a variety of languages.

That's according to the official documentation.

They are essentially a data format like JSON or XML i.e, they can store structured data which can then be serialised and de-serialised by a wide number of languages. Let's understand this with a few examples!

Imagine you're storing data about books. So a sample XML will look like this.

<book>
    <name>Animal Farm</name>
    <isbn>104</isbn>
</book>

We could represent the same structured data using a smaller footprint with JSON.

{
    "name": "Animal Farm",
    "isbn" : 104
}

And if we were to represent this using protocol buffers, it would look something like this.

[10 11 65 110 105 109 97 108 32 70 97 114 109 16 104]

If you observe the above wire encoded output closely, you might see that starting from position 2 of the array, the name of the book, "Animal Farm" is spelled out with 'A' = 65, 'n'=110 an so on. The last element is a byte representation of the isbn. While this looks simple there's much more to the encoding than what meets the eye. If you'd like to delve into the details of the encoding format you can read more here.

Now, at this scale the size of both the JSON and the Protocol Buffer seem to be quite similar. But as your data increases, a lot of the size and complexity gets shaved off which will lead to smaller and more efficient payloads for your application. Let's see how we can use Protocol Buffers in Go!

Setting Up Protocol Buffers

We're going to cook up a simple example to see how protocol buffers work in Go. Let's get started by initialising a new go module in a new directory. Run the following.

go mod init protobuf_using_go

Now, install the packages required.

go get -u github.com/golang/protobuf
go get -u github.com/golang/protobuf/proto
go install google.golang.org/protobuf/cmd/protoc-gen-go

Make sure your .bashrc or .zshrc file has the following environment variables.

export GOPATH=$HOME/go
export PATH=$PATH:$GOPATH/bin

You can even use a package manager like homebrew to install the protoc binary. Make sure you have the binary installed by running protoc --version. We're going to be using a version above 3.

For any issues related to installation you can refer to the official repo.

Now, we can go about defining our protobuf schema. We'll need to start with a .proto file. Let's define the book structure we saw earlier.

// book.proto
syntax="proto3";

package main;

message Book {
    string name = 1;
    int32 isbn = 2;
}

Let's understand what we just wrote. At first we specified the syntax we want to use which is "proto3" and specified that we want this to be a part of the main package.

Then we specify our schema. The definitions in a .proto file are simple: you add a message for each data structure you want to serialise, then specify a name and a type for each field in the message. Here Book is our data structure which will have two fields, name of type string and isbn of type int32. Keep in mind that the type comes before the variable name unlike Go.

Also each field is associated with a unique number. These numbers are used to identify our fields in the encoded message and shouldn't be changed once the message type is in use.

Now, let's go ahead and compile this with the protocol buffer compiler using the following command.

protoc --go_out=. *.proto

The --go_out flag specifies which directory the generated Go code for the .proto will be stored in. We're keeping it at the root of the project. The second argument specifies which file to compile. Here, we're compiling all files with a .proto extension. Running this should generate a book.pb.go file with the equivalent Go code that we'll require to use our book protocol buffer. Next, let's write code to read/write data using our protocol buffer.

Specifying Field Rules

We can specify certain rules for our message structure fields as well.

required: a message must have exactly one of this field
optional: a message can have zero or just one of this field
repeated: this field can be repeated any number of times in the message including zero

For example we can make the isbn field optional by writing

optional int32 isbn = 2;

For this tutorial we won't be using field rules outside of the default ones.

Working with Protocol Buffers

Let's create a new file main.go with the following code.

// main.go
package main

import (
    "fmt"
    "log"

    "github.com/golang/protobuf/proto"
)

func main() {

    myBook := &Book{
        Name: "Animal Farm",
        Isbn: 104,
    }

    data, err := proto.Marshal(myBook)
    if err != nil {
        log.Fatal("marshaling error: ", err)
    }

    fmt.Println(data)

    myNewBook := &Book{}
    err = proto.Unmarshal(data, myNewBook)
    if err != nil {
        log.Fatal("Unmarshaling error: ", err)
    }

    fmt.Println(myNewBook.GetName())
    fmt.Println(myNewBook.GetIsbn())
}

That's a lot of new code so let's break it down.

First we create a variable myBook , which is a pointer to the Book struct defined in book.pb.go. and we set the fields with our data. Notice that the fields start with a capital letter now. Then we use the Marshal function to serialise our protocol buffer data and store it in the data variable which we display. This will print our encoded data.

Now we want to de-serialise the encoded message, i.e, read a protocol buffer. So we declare a new pointer to the Book struct, myNewBook, with empty fields. Then, we use the Unmarshal function to de-serialise the encoded message stored in the data, and store it in myNewBook. Finally we use the getter methods, GetName() and GetIsbn(), provided in our generated code to retrieve and print the fields. Let's go ahead and run this. We need to pass in the generated code file as well.

go run main.go book.pb.go

You should see the following output,

[10 11 65 110 105 109 97 108 32 70 97 114 109 16 104]
Animal Farm
104

Nested Fields

Just like JSON, our Protocol Buffer might contain nested data. So let's go ahead and add nested elements in our book.proto file.

// book.proto
syntax="proto3";

package main;

message Author {
    string name = 1;
    int32 yearOfPublishing = 2;
}

message Book {
    string name = 1;
    int32 isbn = 2;
    Author author = 3;
}

Here, we've again defined a message structure, Author, with fields name and yearOfPublishing. Then in order to nest this inside Book, we've added a field of type Author and name author to it. Using this we have effectively created a nested structure.

Now we simply generate the equivalent Go code for this by running,

protoc --go_out=. *.proto

Now, let's make the changes in our main file!

// main.go
package main

import (
    "fmt"
    "log"

    "github.com/golang/protobuf/proto"
)

func main() {

    myBook := &Book{
        Name: "Animal Farm",
        Isbn: 104,
        Author: &Author{
            Name:             "George Orwell",
            YearOfPublishing: 1945,
        },
    }

    data, err := proto.Marshal(myBook)
    if err != nil {
        log.Fatal("marshaling error: ", err)
    }

    fmt.Println(data)

    myNewBook := &Book{}
    err = proto.Unmarshal(data, myNewBook)
    if err != nil {
        log.Fatal("Unmarshaling error: ", err)
    }

    fmt.Println(myNewBook.GetName())
    fmt.Println(myNewBook.GetIsbn())
    fmt.Println(myNewBook.Author.GetName())
    fmt.Println(myNewBook.Author.GetYearOfPublishing())
}

If you see the code above, you'll notice that we've added a new field, Author to myBook, which points to the Author type in our generated code. We set the fields in Author with the relevant data.

There's no change in our marshalling and un-marshalling methods. Finally, we access the newly set fields via getter functions, Author.GetName() and Author.GetYearOfPublishing(), of the nested message structure and display it. Run it with the command:

go run main.go book.pb.go

You should see the following output.

[10 11 65 110 105 109 97 108 32 70 97 114 109 16 104 26 18 10 13 71 101 111 114 103 101 32 79 114 119 101 108 108 16 153 15]
Animal Farm
104
George Orwell
1945

Conclusion

If you'd like to dig deeper into Protocol Buffers and discover all the cool stuff you can do with it, read the official docs,

Protocol Buffer Docs

If you get stuck here's the repo with all the code!

For any queries reach out to my socials or GitHub!

Dynamic Pages using React Router

Saswata Mukherjee — Fri, 03 Jul 2020 08:24:35 +0000

Hey there!

If you've ever visited a site with a bunch of different users with different content from each user such as a blogging site, social media or even dev.to, you've probably noticed that each page of a particular user has a route along the lines of /username or if you visit a particular article of the user on the site then a route like /username/article. You'll even notice that while all the pages have similar structure, their content is different.

This is what's known as dynamic pages and routes.

Let's see how we can implement this in React. We'll be using the Star Wars API to get a list of users and we'll generate separate pages and routes for all of them.

Keep in mind that this tutorial focusses on dynamic routing in React with React Router. For achieving the same results in Gatsby or Next.js the procedure will be different and will rely on their custom routing APIs.

Get Started

With that out of the way let's get started. Create a new React project using create-react-app. Also install React Router by running yarn add/npm i react-router-dom. The react-router-dom module brings over the core functionality of the React Router to browser based applications.

Now open up your App.js and remove the default code and add the following import statements.

import React, { useState, useEffect } from "react";
import { Link, BrowserRouter as Router, Route } from "react-router-dom";

const App = () => {
  return <></>;
};

export default App;

For this tutorial we'll be using React Hooks to make our code simpler. In the same App.js file let's add another component called HomePage . Like the name suggests this will be our homepage from where we'll call the Star Wars API to get person data. We'll also define a route for this component.

import React, { useState, useEffect } from "react";
import { Link, BrowserRouter as Router, Route } from "react-router-dom";

const HomePage = () => {
  return <>Home Page</>;
};

const App = () => {
  return (
    <>
      <Router>
        <Route exact path="/" component={HomePage} />
      </Router>
    </>
  );
};

export default App;

Great! So now if you run yarn start/npm start and visit [localhost:3000/](http://localhost:3000/) in your browser you should see "Home Page" written on your screen. Now let's go ahead and add in our API call.

import React, { useState, useEffect } from "react";
import { Link, BrowserRouter as Router, Route } from "react-router-dom";

const HomePage = () => {
  const [isLoading, setIsLoading] = useState(true);
  const [data, setData] = useState();

  useEffect(() => {
    fetch("https://swapi.dev/api/people/", {})
      .then((res) => res.json())
      .then((response) => {
        setData(response.results);
        setIsLoading(false);
      })
      .catch((error) => console.log(error));
  }, []);

  return (
    <>
      {!isLoading &&
        data.map((person, index) => {
          return <h5 key={index}>{person.name}</h5>;
        })}
    </>
  );
};

const App = () => {
  return (
    <>
      <Router>
        <Route exact path="/" component={HomePage} />
      </Router>
    </>
  );
};

export default App;

Now that's a lot of new code. Let's break down what we wrote.

We have two states, isLoading which is a boolean which tells us whether we have received data from our API or not and data which contains the JSON that we'll receive from the API call.

We use a useEffect hook to fetch data when the HomePage component loads. When we get data from the API we set the value of isLoading to false and data to whatever JSON we get.

Now, if you look at the jsx inside the HomePage component you'll see that we check the value of isLoading and if it's false, we map through data to render the names of the Star Wars characters.

If you run your app now you should see the names pop up one after the other.

You can check out the Swapi documentation here.

Making a dynamic component

But, we don't want a list of people, we also want separate pages at dynamic routes for each of them!

So let's create another component called PersonPage which will fetch data from an API getting the details of each person.

import React, { useState, useEffect } from "react";
import { Link, BrowserRouter as Router, Route } from "react-router-dom";

const PersonPage = () => {

  const [isLoading, setIsLoading] = useState(true);
  const [data, setData] = useState();

  useEffect(() => {
    fetch(`https://swapi.dev/api/people/${personId}`, {})
      .then((res) => res.json())
      .then((response) => {
        setData(response);
        setIsLoading(false);
        console.log(`https://swapi.dev/api/people/${personId}`)
      })
      .catch((error) => console.log(error));
  }, [personId]);

  return (
    <>
      {!isLoading && (
        <>
          <h1>Name: {data.name}</h1>
          <h2>Height: {data.height}</h2>
          <h2>Mass: {data.mass}</h2>
          <h2>Hair Color: {data.hair_color}</h2>
          <h2>Skin Color: {data.skin_color}</h2>
          <h2>Eye Color: {data.eye_color}</h2>
          <h2>Birth Year: {data.birth_year}</h2>
          <h2>Gender: {data.gender}</h2>
          <Link to="/">Back to homepage</Link>
        </>
      )}
    </>
  );
};

const HomePage = () => {
  const [isLoading, setIsLoading] = useState(true);
  const [data, setData] = useState();

  useEffect(() => {
    fetch("https://swapi.dev/api/people/", {})
      .then((res) => res.json())
      .then((response) => {
        setData(response.results);
        setIsLoading(false);
      })
      .catch((error) => console.log(error));
  }, []);

  return (
    <>
      {!isLoading &&
        data.map((person, index) => {
           return (
            <h5 key={index}>
              <Link to={`/person/${index + 1}`}>{person.name}'s Page</Link>
            </h5>
          );
        })}
    </>
  );
};

const App = () => {
  return (
    <>
      <Router>
        <Route exact path="/" component={HomePage} />
        <Route path="/person/:personId" component={PersonPage} />
      </Router>
    </>
  );
};

export default App;

Again that's a lot of changes to our code.

We have defined a PersonPage component which lists details about each person by getting data from the API in the same fashion as HomePage. We have also defined a new route for this component i.e, person/:personId. This is a bit different compared to our regular routes. Here we pass a parameter personId through the route. That way a single component at that route can be dynamic based on that parameter.

HomePage has also changed and now returns links to this dynamic route with index as the route parameter.

If you observe PersonPage closely, you'll realise that the while the structure of it stays the same, all the content on the page is dependent on personId i.e, the component is fully dynamic. But PersonPage hasn't accessed this parameter yet. This is where we'll use a little bit of React Router magic.

React Router magic

React Router passes two props to all of its routed components:

match props
location props

You can log them out in the console if you want to see them in their entirety. We'll be using the match prop to access the route parameters from the PersonPage component. The match prop has a property called params which will have the personId parameter. Let's modify our code!

import React, { useState, useEffect } from "react";
import { Link, BrowserRouter as Router, Route } from "react-router-dom";
import "./App.css";

const PersonPage = ({ match }) => {
  const {
    params: { personId },
  } = match;
  const [isLoading, setIsLoading] = useState(true);
  const [data, setData] = useState();

  useEffect(() => {
    fetch(`https://swapi.dev/api/people/${personId}`, {})
      .then((res) => res.json())
      .then((response) => {
        setData(response);
        setIsLoading(false);
        console.log(`https://swapi.dev/api/people/${personId}`);
      })
      .catch((error) => console.log(error));
  }, [personId]);

  return (
    <>
      {!isLoading && (
        <>
          <h1>Name: {data.name}</h1>
          <h2>Height: {data.height}</h2>
          <h2>Mass: {data.mass}</h2>
          <h2>Hair Color: {data.hair_color}</h2>
          <h2>Skin Color: {data.skin_color}</h2>
          <h2>Eye Color: {data.eye_color}</h2>
          <h2>Birth Year: {data.birth_year}</h2>
          <h2>Gender: {data.gender}</h2>
          <Link to="/">Back to homepage</Link>
        </>
      )}
    </>
  );
};

const HomePage = () => {
  const [isLoading, setIsLoading] = useState(true);
  const [data, setData] = useState();

  useEffect(() => {
    fetch("https://swapi.dev/api/people/", {})
      .then((res) => res.json())
      .then((response) => {
        setData(response.results);
        setIsLoading(false);
      })
      .catch((error) => console.log(error));
  }, []);

  return (
    <>
      {!isLoading &&
        data.map((person, index) => {
          return (
            <h5 key={index}>
              <Link to={`/person/${index + 1}`}>{person.name}'s Page</Link>
            </h5>
          );
        })}
    </>
  );
};

const App = () => {
  return (
    <>
      <Router>
        <Route exact path="/" component={HomePage} />
        <Route path="/person/:personId" component={PersonPage} />
      </Router>
    </>
  );
};

export default App;

There you go!

PersonPage now accesses the personId parameter via ES6 destructuring and uses it for the API call. Run your React app and you'll see HomePage populate itself with links and clicking on any person's link will lead you to a dynamic page consisting of all the details of that person. The route will also be dynamic in the form of /person/{number}.

Conclusion

If you'd like to dig deeper into React Router and discover all the cool stuff you can do with it, read the official docs,

React Router Docs

For any queries reach out to my socials or GitHub!

Discuss: What's your preferred way of creating a React app?

Saswata Mukherjee — Thu, 11 Jun 2020 05:52:31 +0000

Whenever I start a new React project I mostly use to create-react-app. But I've seen a lot of people default to Gatsby or Next.js.

If you do use something other than cra what is your motivation and what tools make your life easier? Any best practices you think React devs should follow while using them?

Write your first API with Deno

Saswata Mukherjee — Tue, 19 May 2020 11:05:00 +0000

ICYMI, Deno v1.0 has been released!

But what is Deno?

Deno is a simple, modern and secure runtime for JavaScript and TypeScript that uses V8 and is built in Rust.

That's according to the official website.

Ryan Dahl the original creator of Node.js (the popular server-side JavaScript runtime) announced Deno at JSConf EU 2018 in his talk "10 Things I Regret About Node.js". Deno is pretty similar to Node. Except that it's improved in many ways, since it was created to be a better implementation of Node.js. It has a ton of great features like security by default, TypeScript by default, ES modules and Golang-like package management.

If you're on twitter, you're probably already seen the influx of "x years of Deno experience" and "node, deno, oden, done..." jokes.

Getting Started

Alright, enough said, let's get playing with Deno.

We're going to be building a really simple REST API which lets us perform CRUD operations on a database of dogs!

Make sure you've installed deno correctly.

We're going to be using the Abc deno web framework along with MongoDB. We'll also be using Denv to manage our environment variables. Keep in mind, that there are a ton of other web frameworks like alosaur, oak, deno-express, pogo, servest that we can use but since deno is pretty new and I don't really have much of a preference yet, I'm using this one.

Make a new directory and create a file named server.ts. This will be our main file which will contain our router. We'll also import Denv and Abc and initialise an application.

import { Application, Context } from "https://deno.land/x/[email protected]/mod.ts";
import "https://deno.land/x/denv/mod.ts";

const app = new Application();

app
  .get("/hello", (c: Context) => {
    return "Hello, Abc!";
  })
  .start({ port: 8000 });

Now, if you've worked with node before, this'll look pretty familiar. Initially, we're importing Application and Context from the Abc module. We are basically initialising a new Abc application and then we're defining a route /hello with a callback function which will return "Hello, Abc!". The start method directs the application to start listening for requests at port 8000. Instead of request and response we have single argument c which is of type Context . Let's see this in action. To run our file we need to use the command deno run server.ts but if you run the file you're gonna get a bunch of errors. That's because deno is secure by default. It won't allow the application to access your system in any way. To allow it we need to add the --allow-read flag to allow Denv to read our .env file and --allow-net flag to give Abc access to our ports. Hence the command would be:

deno run --allow-read --allow-net server.ts

Now if you visit, localhost:8000 you should see "Hello, Abc!" printed on your screen.

Great! So let's add our database next.

Database(MongoDB)

We're going to be getting our database url and name from environment variables. So in your .env file add the following.

DB_NAME=deno_dogs
DB_HOST_URL=mongodb://localhost:27017

Now add the following in your config/db.ts file

import { init, MongoClient } from "https://deno.land/x/[email protected]/mod.ts";

// Initialize the plugin
await init();

class Database {
  public client: MongoClient;
  constructor(public dbName: string, public url: string) {
    this.dbName = dbName;
    this.url = url;
    this.client = {} as MongoClient;
  }
  connect() {
    const client = new MongoClient();
    client.connectWithUri(this.url);
    this.client = client;
  }
  get getDatabase() {
    return this.client.database(this.dbName);
  }
}

const dbName = Deno.env.get("DB_NAME") || "deno_dogs";
const dbHostUrl = Deno.env.get("DB_HOST_URL") || "mongodb://localhost:27017";
const db = new Database(dbName, dbHostUrl);
db.connect();

export default db;

Let's break down what we wrote. Fortunately deno works with mongoDB and thus we can import that module. This will download a mongoDB plugin. The init() method initialises the plugin and we define our Database class. The class has a constructor which takes in the url and name of the db. The connect() method connects to the mongoDB instance and the getDatabase() method is a getter function. At the bottom of the file we define an instance of the class, db, and initialise it with the dbName and dbHostUrl which we fetch from the .env file. We also call the connect() method and export db.

Cool! Now let's write the controllers which will let us perform CRUD operations on our db.

Controllers

Inside the controllers/dogs.ts file add the following.

import {
  HandlerFunc,
  Context,
} from "https://deno.land/x/[email protected]/mod.ts";
import db from "../config/db.ts";

// DB collection made
const database = db.getDatabase;
const dogs = database.collection("dogs");

// Dog type defined
interface Dog {
  _id: {
    $oid: string;
  };
  name: string;
  breed: string;
  age: string;
}

export const createDog: HandlerFunc = async (c: Context) => {
  try {
    const body = await (c.body());
    if (!Object.keys(body).length) {
      return c.string("Request can't be empty", 400);
    }
    const { name, breed, age } = body;

    const insertedDog = await dogs.insertOne({
      name,
      breed,
      age,
    });

    return c.json(insertedDog, 201);
  } catch (error) {
    return c.json(error, 500);
  }
};

export const fetchAllDogs: HandlerFunc = async (c: Context) => {
  try {
    const fetchedDogs: Dog[] = await dogs.find();

    if (fetchedDogs) {
      const fetchedDogsList = fetchedDogs.length
        ? fetchedDogs.map((dog) => {
          const { _id: { $oid }, name, breed, age } = dog;
          return { id: $oid, name, breed, age };
        })
        : [];
      return c.json(fetchedDogsList, 200);
    }
  } catch (error) {
    return c.json(error, 500);
  }
};

export const fetchOneDog: HandlerFunc = async (c: Context) => {
  try {
    const { id } = c.params as { id: string };

    const fetchedDog = await dogs.findOne({ _id: { "$oid": id } });

    if (fetchedDog) {
      const { _id: { $oid }, name, breed, age } = fetchedDog;
      return c.json({ id: $oid, name, breed, age }, 200);
    }
    return c.string("Dog not found", 404);
  } catch (error) {
    return c.json(error, 500);
  }
};

export const updateDog: HandlerFunc = async (c: Context) => {
  try {
    const { id } = c.params as { id: string };

    const body = await (c.body()) as {
      name?: string;
      breed?: string;
      age?: string;
    };

    if (!Object.keys(body).length) {
      return c.string("Request can't be empty", 400);
    }

    const fetchedDog = await dogs.findOne({ _id: { "$oid": id } });

    if (fetchedDog) {
      const { matchedCount } = await dogs.updateOne(
        { _id: { "$oid": id } },
        { $set: body },
      );
      if (matchedCount) {
        return c.string("Dog updated successfully!", 204);
      }
      return c.string("Unable to update dog");
    }

    return c.string("Dog not found", 404);
  } catch (error) {
    return c.json(error, 500);
  }
};

export const deleteDog: HandlerFunc = async (c: Context) => {
  try {
    const { id } = c.params as { id: string };

    const fetchedDog = await dogs.findOne({ _id: { "$oid": id } });

    if (fetchedDog) {
      const deleteCount = await dogs.deleteOne({ _id: { "$oid": id } });

      if (deleteCount) {
        return c.string("Dog deleted successfully!", 204);
      }
      return c.string("Unable to delete dog");
    }

    return c.string("Dog not found", 404);
  } catch (error) {
    return c.json(error, 500);
  }
};

Alright so there's a lot happening here. First we're importing HandlerFunc and Context from the Abc module and db from our config/db.ts file. Then we call getDatabase() to get our "deno_dogs" db and define a collection "dogs" inside it. Next we define an interface Dog which has the properties of name, breed and age. With all that out of the way, let's move on to the functions.

Each function has a type of HandlerFunc and argument c which is of type Context . This lets us use this function as a callback for our routes. All the functions are almost similar so there isn't much to explain. We use c.body() to access our request body in case of createDog and updateDog. We return a json object or string via c.json() or c.string() along with HTTP codes in our return statements in all the above methods. We access url parameters via c.params in case of fetchOneDog, updateDog and deleteDog.

We also use the dogs object in our functions to manipulate our collection via methods like .insertOne({}), .find({}), .findOne({}), .updateOne({}) and deleteOne({}). All of these methods are wrapped in try-catch blocks for error handling.

Now with our controllers defined we can proceed to defining our routes.

Routes

In your server.ts file write the following.

import { Application } from "https://deno.land/x/[email protected]/mod.ts";
import "https://deno.land/x/denv/mod.ts";
import {
  createDog,
  fetchAllDogs,
  fetchOneDog,
  updateDog,
  deleteDog,
} from "./controllers/dogs.ts";

const app = new Application();

app
  .get("/dogs", fetchAllDogs)
  .post("/dogs", createDog)
  .get("/dogs/:id", fetchOneDog)
  .put("/dogs/:id", updateDog)
  .delete("/dogs/:id", deleteDog)
  .start({ port: 8000 });

As you can see, we've imported all our controller functions and assigned each of them a route and an HTTP method. Plain and simple.

We are done writing our REST API. All that's left is to run it! To do that type in the following into your terminal:

deno run --allow-write --allow-read --allow-plugin --allow-net --allow-env --unstable server.ts

We have a few new flags this time. The --allow-read/write flags are for Denv and mongoDB, as they need read/write access to your filesystem. The --allow-plugin flag allows the use of the mongoDB plugin and the --allow-env is for allowing usage of environment variables.

A lot of Deno APIs are not stable yet so some of them are marked as unstable. To use these "unstable" APIs we need to add the --unstable flag.

Use a tool like Postman and send a POST request to localhost:8000/dogs with the body as

{
  "name": "Cheddar",
  "breed": "Corgi",
  "age": 11
}

Send a GET request to the same url to see your dogs! Similarly try out all the other routes.

So there you go! Now you know how to write a REST API with Deno.

Here's the GitHub repo of the code.

Conclusion

Since there are a few bugs and also no explicit Code of Conduct for the project yet, I don't recommend using it for production just now. A CoC is an essential part of any open source project. However development is moving forward pretty quickly and this is one project to definitely keep an eye on!

For any queries reach out to my socials or GitHub!

React Context+Hooks API=> Ideal State Management

Saswata Mukherjee — Thu, 07 May 2020 18:22:19 +0000

Hey there! React is pretty great with a ton of stuff. But sometimes we need global states, such as a UI theme or locale preferences. Now ordinarily, to pass states down to child components what we do is pass down props. But with global states, we have to pass down props several times down the component tree or the roots of a potato if you've seen Women Of React 2020. This creates a cumbersome phenomenon known as "prop drilling". This means that we are passing down the props from grandparent to parent to child and so on.

Now to solve this issue, you can use something like Redux, which is a completely fine solution, but restructures your entire code and necessitates a ton of boilerplate code. This makes it unsuitable for lightweight implementations. Keep in mind though that it doesn't affect performance.

So what do we do?

Enter React Context API.

Context provides a way to pass data through the component tree without having to pass props down manually at every level.

That's the official React docs intro. It was introduced in React 16.3. It solves the global state management problem. Context is often touted as a lightweight alternative to Redux and provides much cleaner and simpler code. So let's get started with it!

So let's make a simple React app. Use create-react-app to generate one. And write the following in App.js

function App() {
  return (
    <div className="App">
      <AppBar theme="white" />
    </div>
  );
}

function AppBar({theme}) {
  return(
    <div className="AppBar">
      <ThemedButton theme={theme}/>
    </div>
  );
}

function ThemedButton({theme}) {
  return(
    <div>
      <button style={{backgroundColor: theme}} />
    </div>
  )
}   
export default App;

Well, as you can see above, we have to thread the theme property through all the components, so that we can apply it to child elements. This is great for three components maybe, but imagine a full dynamic website, where the component tree might be huge and deep.

Let's try the same thing with React Context then. Now before you use Context you should keep in mind that this isn't meant for small number of props for a small number of components. For that, simple prop threading and component composition would be much simpler. So use it wisely.

const ThemeContext = React.createContext('white');

function App() {
  return (
    <div className="App">
      <ThemeContext.Provider value={"black"}>
        <AppBar />
      </ThemeContext.Provider>
    </div>
  );
}

function AppBar() {
  return(
    <div className="AppBar">
      <ThemedButton />
    </div>
  );
}

function ThemedButton() {
  return(
    <div>
      <ThemeContext.Consumer>
        {value => <button style={{backgroundColor: value}} />}
      </ThemeContext.Consumer>
    </div>
  )
}   
export default App;

Okay, that's a lot of new code and if you look closely you'll see that our props in the AppBar and ThemedButton component have disappeared. So what happened? Let's break it all down .

So notice at the top of the code snippet I have the line,

const ThemeContext = React.createContext('white');

This is what creates the React Context object. Now, every Context object comes with a Provider and a consumer. Again if you refer to the above code you'll see them.

Provider and Consumer

//Provider
      <ThemeContext.Provider value={"black"}>
      </ThemeContext.Provider>
//Consumer
      <ThemeContext.Consumer>
      </ThemeContext.Consumer>

The Provider component allows consuming components to subscribe to context changes.

It accepts a value prop to be passed to consuming components that are descendants of this Provider. Thus, one Provider can be connected to many consumers. Providers can even be nested to override values deeper within the component tree.

All consumers that are descendants of a Provider will re-render whenever the Provider’s value prop changes.

The Consumer component is the component which subscribes to the context changes. The Consumer component however requires a function as a child like render props. The function receives the current context value and returns a React node.

The value argument passed to the function will be equal to the value prop of the closest Provider for this context above in the tree. Thus, in the code above I have used the value to colour the button,

      <ThemeContext.Consumer>
        {value => <button style={{backgroundColor: value}} />}
      </ThemeContext.Consumer>

Get the value of the Context

So you know how to use the Context API now. But if you look at the Provider and think about the use cases, you'll quickly realise that it's a bit difficult to extract the context from our JSX code for implementing other functionality. Sure, there are workarounds but that isn't really ideal. You may see this somewhere, but it is usually legacy.

Now if ThemedButton was a class component we would be able to extract the context with contextType.

The contextType property on a class can be assigned a Context object. This lets you consume the nearest current value of that Context type using this.context. You can reference this in any of the lifecycle methods including the render function. So we could implement it like this.

static contextType = ThemeContext;
  render() {
    return <Button theme={this.context} />;
  }

However, we are using lightweight functional components and Hooks! So let's refactor our existing code a bit,

import React, { useContext } from 'react';

const ThemeContext = React.createContext('white');

function App() {
  return (
    <div className="App">
      <ThemeContext.Provider value={"black"}>
        <AppBar />
      </ThemeContext.Provider>
    </div>
  );
}

function AppBar() {
  return(
    <div className="AppBar">
      <ThemedButton />
    </div>
  );
}

function ThemedButton() {
  const theme = useContext(ThemeContext)
  return(
    <div>
        <button style={{backgroundColor: theme}} />
    </div>
  )
}   
export default App;

Over here, we've used the useContext hook which is the functional component equivalent contextType . With useContext we can do away with the provider, and get the current context value outside of our JSX code.

Updating Our Context

Updating our Context is as simple as updating a state. With functional components, we can use the useState hook to achieve this by passing down a function which will update out context,

import React, { useState, useContext } from "react";

const ThemeContext = React.createContext({ theme: "white", toggler: () => {} });

function App() {
  const [color, setColor] = useState("white");
  const toPass = {
    theme: color,
    toggler: () => {
      return color === "white" ? setColor("black") : setColor("white");
    },
  };
  return (
    <div className="App">
      <ThemeContext.Provider value={toPass}>
        <AppBar />
      </ThemeContext.Provider>
    </div>
  );
}

function AppBar() {
  return (
    <div className="AppBar">
      <ThemedButton />
    </div>
  );
}

function ThemedButton() {
  const context = useContext(ThemeContext);
  return (
    <div>
      <button
        style={{ backgroundColor: context.theme }}
        onClick={context.toggler}
      />
    </div>
  );
}
export default App;

As you see above the color state is manipulated by a toggle function which we passed down via our Context. The toggle function from the global Context is then called by the button in a child component, which thus updates the global Context.

So there you go! You now know how to use Context and Hooks to maintain a global state throughout your component tree.

If you'd like to dig deeper into Context, read the official docs,

Context - React

For any queries reach out to my socials or GitHub!