DEV Community: Roy Derks

Build Tool Calling Agents with LangGraph and IBM watsonx.ai Flows Engine

Roy Derks — Tue, 03 Dec 2024 17:20:53 +0000

Generative AI is evolving quickly, and in the past couple of years, we’ve seen a few clear patterns developer can implement — starting with simple prompting, moving to Retrieval Augmented Generation (RAG), and now Tool Calling and Agents. Building applications around Agents often involves connecting different tools, models, and APIs.

In this tutorial, you’ll learn how to set up and run an AI agent using watsonx.ai Flows Engine and LangGraph, with help from models powered by IBM’s watsonx.ai platform. This guide will take you step by step through installing the tools you need, deploying your tools to Flows Engine, and running a chat application on your own machine.

Tool Calling & Agents

Tool calling allows Large Language Models (LLMs) to work with external tools by following user-defined instructions. The model figures out the needed inputs for a tool, and the tool does the actual work. This is great for turning existing data into structured information or linking tools into workflows. Flows Engine makes this process easier by offering ways to turn your existing data sources such as databases and APIs into tools, and connect to these tools from different frameworks for building AI applications such as LangChain and LangGraph.

Agents are like AI helpers built to handle specific tasks, and to complete these talks they rely on tool calling. This allows them to access external tools, process information, and expand the exsisting knowledge of the LLM to fit the user’s needs. There are several popular frameworks for building agents, either in JavaScript or Python. In this tuturial we'll be using LangGraph, which builds upon LangChain, to create an Agent that is able to call tools that can retrieve information from Google Books and Wikipedia. The tools will be defined in Flows Engine, and connected through the JavaScript SDK as you'll learn in the next section.

Build a Tool Calling Agent

In this section you'll learn how to set up and run an AI agent using watsonx.ai Flows Engine (wxflows) and LangGraph. The agent will be able to call several tools to answer questions about your favorite books or other popular media, using a set of prebuilt community tools. Of course, you can also convert your own data sources (such as databases and APIs) into tools. We'll cover everything you need to know, from installing the tools to deploying and running the app on your machine.

This example includes the following technologies:

LangGraph SDK (for the agent)
LangChain SDK watsonx.ai extension (for the models)
wxflows SDK (for the tools)
Carbon AI Chat (for the user interface)

We'll be using the watsonx.ai Chat Model from LangChain, but you can use any of the supported chat models.

Continue to the next section to start installing the wxflows CLI, set up your Flows Engine project, and run the agent via a chat application. We’ll use google_books and wikipedia as examples of tools that the agent can call.

Prerequisites

Before you begin, you should create an account for watsonx.ai Flows Engine for this tutorial:

Sign up for a free watsonx.ai Flows Engine account.
Sign up for the free watsonx.ai trial to access models. Alternatively, you can use Ollama to run a LLM locally.
You need to have Python (version 3.8 or higher) installed.

Step 1: Install the `wxflows` CLI

Start by installing the wxflows CLI, which needs Python (version 3.8 or higher) to be installed on our machine. Follow these steps:

Download the CLI from the installation page.

Create a new folder on your computer.

mkdir wxflows-project
cd wxflows-project

Inside this folder, run:

pip install wxflows_cli-1.0.0rc192-py3-none-any.whl --force-reinstall

Use the exact name of the .whl file you downloaded.

After setting up the CLI for watsonx.ai Flows Engine let's continue to the next section and create an endpoint with the Wikipedia and Google Books tools.

Step 2: Set up a watsonx.ai Flows Engine project

Now, set up a new wxflows project. This will include two tools:

google_books: Used to search and retrieve information from Google Books.
wikipedia: Used to query and retrieve information from Wikipedia.

Run the following command to initialize the project and import these tools:

wxflows init --endpoint-name api/wxflows-toolcalling \
--import-name google_books --import-package https://github.com/IBM/wxflows/raw/refs/heads/main/tools/google_books.zip \
--import-tool-name google_books --import-tool-description "Retrieve information from Google Books. Find books by search string, for example to search for Daniel Keyes 'Flowers for Algernon' use q: 'intitle:flowers+inauthor:keyes'" --import-tool-fields "books|book" \
--import-name wikipedia --import-package https://github.com/IBM/wxflows/raw/refs/heads/main/tools/wikipedia.zip \
--import-tool-name wikipedia --import-tool-description "Retrieve information from Wikipedia." --import-tool-fields "search|page"

Here’s what this command does:

Creates an endpoint: Defines an endpoint called api/wxflows-toolcalling.
Imports google_books: Adds a tool for retrieving books from Google Books with a description and specific fields like books|book.
Imports wikipedia: Adds a tool for searching Wikipedia with a description and fields like search|page.

After running the command, you can see a wxflows.toml file appear in the current directory. This file holds the configuration for your tools, which we'll deploy to an endpoint by running:

wxflows deploy

Deploying the endpoint should only take a couple of seconds, and the wxflows SDK will use this endpoint to retrieve and call tools as you'll learn in the next section.

Step 3: Use LangGraph to create an agent

Now that we have a Flows Engine endpoint, we need to create an agent that can use this endpoint for tool calling. We'll be using LangGraph for this, together with the wxflows SDK and the LangChain extension for watsonx.ai:

Create a new directory:
```
mkdir langgraph
cd langgraph
```
In this directory run the following command to set up a new TypeScript project and to install the needed dependencies:
```
npm init -y
npm i @langchain/langgraph @langchain/core @langchain/community dotenv typescript @wxflows/sdk@beta
```
This installs the following packages:

- `@langchain/langgraph`: Build agents, structured workflows and handle tool calling.
- `@langchain/core`: Provides core functionality for building and managing AI-driven workflows.
- `@langchain/community`: Provides access to experimental and community-contributed integrations and tools, such as models on the watsonx.ai platform.
- `dotenv`: Loads environment variables from a `.env` file, making it easier to manage API keys and configuration values.
- `typescript`: Sets up TypeScript, a superset of JavaScript, for type checking and better code quality.
- `@wxflows/sdk@beta`: Includes the SDK for working with watsonx.ai Flows Engine, which allows you to deploy and manage tools.

After running these commands, your project will be ready to start building an agent.

Create an .env file with the following values:

# You can get these credentials from https://dataplatform.cloud.ibm.com/developer-access?context=wx
WATSONX_AI_AUTH_TYPE=iam
WATSONX_AI_ENDPOINT=https://us-south.ml.cloud.ibm.com
WATSONX_AI_IDENTITY_SERVER=iam.cloud.ibm.com
WATSONX_AI_APIKEY=
WATSONX_AI_PROJECT_ID=

# run the command 'wxflows whoami --apikey'
WXFLOWS_APIKEY=

# endpoint shows in your terminal after running 'wxflows deploy'
WXFLOWS_ENDPOINT=

After creating the .env file, create a new file called index.ts and add the code for LangGraph:

import { AIMessage, BaseMessage, HumanMessage, SystemMessage } from "@langchain/core/messages";
import { ChatWatsonx } from "@langchain/community/chat_models/ibm";
import { StateGraph } from "@langchain/langgraph";
import { MemorySaver, Annotation } from "@langchain/langgraph";
import { ToolNode } from "@langchain/langgraph/prebuilt";
import wxflows from "@wxflows/sdk/langchain";
import "dotenv/config";

(async () => {
    // Define the graph state
    // See here for more info: https://langchain-ai.github.io/langgraphjs/how-tos/define-state/
    const StateAnnotation = Annotation.Root({
        messages: Annotation<BaseMessage[]>({
            reducer: (x, y) => x.concat(y),
        }),
    });

    const toolClient = new wxflows({
        endpoint: process.env.WXFLOWS_ENDPOINT,
        apikey: process.env.WXFLOWS_APIKEY,
        traceSession: '...'
    });

    const tools = await toolClient.lcTools;
    const toolNode = new ToolNode(tools);

    // Connect to the LLM provider 
    const model = new ChatWatsonx({
        model: "mistralai/mistral-large",
        projectId: process.env.WATSONX_AI_PROJECT_ID,
        serviceUrl: process.env.WATSONX_AI_ENDPOINT,
        version: '2024-05-31',
    }).bindTools(tools);

This first part of the code will import the needed dependencies, retrieves the tools from watsonx.ai Flows Engine and sets up the connection to Mistral Large running on the watsonx.ai platform. Let's add the second part of the code for the index.ts file which will handle the creation of the agent:

    // Define the function that determines whether to continue or not
    // We can extract the state typing via `StateAnnotation.State`
    function shouldContinue(state: typeof StateAnnotation.State) {
        const messages = state.messages;
        const lastMessage = messages[messages.length - 1] as AIMessage;

        // If the LLM makes a tool call, then we route to the "tools" node
        if (lastMessage.tool_calls?.length) {
        console.log('TOOL CALL', lastMessage.tool_calls)
        return "tools";
        }
        // Otherwise, we stop (reply to the user)
        return "__end__";
    }

    // Define the function that calls the model
    async function callModel(state: typeof StateAnnotation.State) {
        const messages = state.messages;
        const response = await model.invoke(messages);

        // We return a list, because this will get added to the existing list
        return { messages: [response] };
    }

    // Define a new graph
    const workflow = new StateGraph(StateAnnotation)
        .addNode("agent", callModel)
        .addNode("tools", toolNode)
        .addEdge("__start__", "agent")
        .addConditionalEdges("agent", shouldContinue)
        .addEdge("tools", "agent");

    // Initialize memory to persist state between graph runs
    const checkpointer = new MemorySaver();

    // Finally, we compile it!
    // This compiles it into a LangChain Runnable.
    // Note that we're (optionally) passing the memory when compiling the graph
    const app = workflow.compile({ checkpointer });

    // Use the Runnable
    const finalState = await app.invoke(
        {
        messages: [
            new SystemMessage(
            "Only use the tools available, don't answer the question based on pre-trained data"
            ),
            new HumanMessage(
            "Search information about the book escape from james patterson"
            ),
        ],
        },
        { configurable: { thread_id: "42" } }
    );

    console.log(finalState.messages[finalState.messages.length - 1].content);
    // You can use the `thread_id` to ask follow up questions, the conversation context is retained via the saved state (i.e. stored list of messages):
})();

In this second part of the code, the agent is created and we pass a message to the agent: "Search information about the book escape from james patterson". This will kick off a series of interactions between the tools running in Flows Engine and the LLM in watsonx.ai to provide you with an answer.

To run the above code, you need to add a start script to the package.json file:

"scripts": {
    "start": "npx tsx ./index.ts",
    "test": "echo \"Error: no test specified\" && exit 1"
}

To send the message to the agent you can now run npm start from the terminal, which should return more information about the book "Escape" by "James Patterson". Next to the information, the used tool calls will also be printed in your terminal.

The tool call will look like the following:

TOOL CALL [
  {
    name: 'google_books',
    args: {
      query: '{\n' +
        '  books(q: "intitle:escape+inauthor:patterson") {\n' +
        '    authors\n' +
        '    title\n' +
        '    volumeId\n' +
        '  }\n' +
        '}'
    },
    type: 'tool_call',
    id: 'Zg9jXPOR2'
  }
]

watsonx.ai Flows Engine is using GraphQL as the underlying technology to define and call tools.

And the final response something like this:

### Information about the book "Escape" by James Patterson

Here is the information about the book "Escape" by James Patterson:

- **Authors:** James Patterson, David Ellis
- **Title:** Escape
- **Volume ID:** EFtHEAAAQBAJ

The next step would be to implement a chat application that's using the Flows Engine endpoint and the LangGraph agent, as you'll learn in the next section.

Step 4: Use the agent in a chat application

The final step is to use the agent and the tools endpoint in a chat application, which you can find in this repository.

You can run this application in the browser using the free service StackBlitz:

You can either run the chat application in the browser via StackBlitz or use the "Download" button to download the source code for the application and run it locally.

This application will need the same credentials as in step 3.3, which you can store in a new .env file. Either directly in StackBlitz or locally:

# You can get these credentials from https://dataplatform.cloud.ibm.com/developer-access?context=wx
WATSONX_AI_AUTH_TYPE=iam
WATSONX_AI_ENDPOINT=https://us-south.ml.cloud.ibm.com
WATSONX_AI_IDENTITY_SERVER=iam.cloud.ibm.com
WATSONX_AI_APIKEY=
WATSONX_AI_PROJECT_ID=

# run the command 'wxflows whoami --apikey'
WXFLOWS_APIKEY=

# endpoint shows in your terminal after running 'wxflows deploy'
WXFLOWS_ENDPOINT=

If you want to run the application locally, don't forget to run npm i in the application's directory to install the dependencies. After installing these, you can run npm start to boot up the application.

The chat application is using IBM's Carbon Chat AI component library, and looks like this:

You can now ask any sort of question related to books or other popular media. The agent will use the Google Books or Wikipedia tool from watsonx.ai Flows Engine to answer your questions, as LangGraph keeps memory state you can also ask follow up questions. The next step would be turn your own (enterprise) data into a tool, for which you can have a look at these instructions.

Summary and Next Steps

This tutorial showed you how to set up and run an AI agent using IBM watsonx.ai Flows Engine and LangGraph. You learned how to configure tools for google_books and wikipedia, deploy a Flows Engine project, and run the application locally or in a browser. These tools enable your agent to retrieve real-time data and interact with external APIs.

With these new skills, you now have a strong foundation for building AI-powered applications using wxflows and watsonx.ai. Whether you’re creating simple workflows or more complex integrations, the CLI and SDK make it easy to bring your projects to life.

We’re excited to see what you create! Join our Discord community and share your projects with us!

Build AI Applications With LangChain, JavaScript, and React

Roy Derks — Tue, 20 Feb 2024 13:24:00 +0000

As a software developer seeking to accelerate development and incorporate AI into products, integrating tools like LangChain into your workflow is an exciting prospect. This post will provide a guide for developers on leveraging LangChain to execute prompting with OpenAI models.

We will walk through:

Setting up a React app with Vite
Installing and configuring LangChain
Connecting to the OpenAI API
Building a query function with LangChain
Handling form submission to interface with the AI

Click the image below to watch the YouTube video version of this blog post:

Setting up a React app with Vite

Vite is a rapid frontend build tool for modern web development. For this tutorial, we use a basic Vite app styled similarly to ChatGPT - with a query box against an empty background ready to display questions and answers.

I've already created a boilerplate for this tutorial, which you can find here.

You can check out the repository by running the following command in your terminal:

git clone https://github.com/royderks/ai-frontend-workshop.git

After cloning the repository, you'll need to move into the new directory and install the dependencies.

cd ai-frontend-workshop/my-gpt
npm install

Once you've got everything installed, open your project in whatever IDE you use – we're gonna go with Visual Studio Code here. The project folder is gonna look pretty familiar if you've ever dabbled with Create React App. You'll find static assets such as images in public and your React code in src. Plus, all the must-haves like package.json and vite.config.js are there. Oh, and TypeScript users, you haven’t been forgotten – there’s a tsconfig.json in there for you.

Ready to see your project live? Start your local development server with:

npm run dev

And just like that, your Vite app is up and running in your browser. Which will look something like the screenshot you can see below.

You get hot-reloading and all the modern features that make coding less of a chore.

Installing and configuring LangChain

LangChainJS is a JavaScript library designed to integrate language AI capabilities into web and Node.js applications. LangChain began as a Python SDK but now has JavaScript and TypeScript support. By offering developers an easy-to-use interface to leverage Large Language Models (LLMs) like GPT-4, LangChainJS simplifies the process of incorporating advanced natural language understanding and generation into projects.

Popular use cases for LangChainJS are chatbots, automating content creation, enhancing search functionalities, or crafting personalized user experiences. You can do all of this with a limited amount of knowledge about LLMs as LangChain offers a set of abstractions on top of popular LLM providers such as OpenAI and IBM Watson.

Before installing LangChain, let's stop the dev server and run:

npm install langchain @langchain/openai

This will install both the general LangChain library and the library needed to connect to OpenAI. In the next section, we'll be connecting to OpenAI for which we need to generate an API Key first.

Connecting to OpenAI API

OpenAI isn't only the creator of ChatGPT; it also has a platform where you can access the models used by ChatGPT. Developers can sign up for free, and often, will get a small credit of $5 to try out their APIs. On

the OpenAI dashboard, we will generate a new secret key to authenticate our app.

With our key secured, we create an environment file called .env to store it:

VITE_OPENAI_API_KEY=<your_key>

We're using VITE_ as a prefix so the environment variable gets picked up by Vite.

Now we can initialize the connection in a new file called langchain.ts:

import { OpenAI } from "@langchain/openai";

const llm = new OpenAI({
    openAIApiKey: import.meta.env.VITE_OPENAI_API_KEY,
});

After creating the connection to OpenAI, we can create a function to call the LLM and pass our question to retrieve the answer.

Building a query function with LangChain

There are multiple methods to query an LLM using LangChain, each of these methods will behave slightly differently. For this tutorial, we'll use the invoke method, one of the simplest and quickest available in LangChainJS.

With our connection configured, we can build out the query function in the same langchain.ts file:

import { OpenAI } from "@langchain/openai";

const llm = new OpenAI({
    openAIApiKey: import.meta.env.VITE_OPENAI_API_KEY,
});

export async function getAnswer(question: string) {
    let answer = ''

    try {
        answer = await llm.invoke(question);
    } catch (e) {
        console.error(e);
    }

    return answer;
}

This async function takes the question, queries the API using LangChain's invoke method, and returns the answer. There's a try/catch block around the function so we can catch errors, for example, when we run out of tokens.

Handling form submission to interface with the AI

The final step to completing this tutorial is to use the getAnswer function in the user interface that we built in the first section. As we're using client-side React, we need to create a few state variables in src/App.tsx and import the getAnswer function from langchain.ts. Also, the getAnswer function needs to be wrapped in a function that we can connect to the onSubmit function of the text input for typing the question:

import { useState } from "react";
import { getAnswer } from "./langchain";

export default function App() {
  const [question, setQuestion] = useState("");

  async function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
    e.preventDefault();
    const result = await getAnswer(question);
    console.log(result);
  }

  // ...

We can now handle the submission of the question by adding this function to the onSubmit in the form element:

<form
    className="stretch mx-2 flex flex-row gap-3 last:mb-2 md:mx-4 md:last:mb-6 lg:mx-auto lg:max-w-2xl xl:max-w-3xl"
    onSubmit={handleSubmit}
>

With that, our app can now interface with the AI! We can ask questions and see it return answers that are logged to the console. If you want to display the result in the user interface, you can create another state variable for the answer:

import { useState } from "react";
import { getAnswer } from "./langchain";

export default function App() {
  const [question, setQuestion] = useState("");
  const [answer, setAnswer] = useState("");

  async function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
    e.preventDefault();
    const result = await getAnswer(question);

    setAnswer(result);
  }

  // ...

The value for answer can be rendered anywhere in the user interface, for example, in a text balloon.

What's next?

Integrating LangChain opens up lots of possibilities for automating workflows, analyzing data, providing search functionality, and more. The contents of this tutorial should give you a good start in building your own AI integrations. Feel free to leave any questions below!

If you found this article useful, let me know on Twitter at @gethackteam. Please share it around the web or subscribe to my YouTube channel for more exciting content on web technologies.

GraphQL IDEs: GraphiQL vs Altair

Roy Derks — Wed, 21 Jun 2023 12:46:48 +0000

In the world of web development, GraphQL has revolutionized how we think about APIs. GraphQL enables developers to query data in a much more flexible and efficient way compared to traditional RESTful APIs. However, as with any technology, you need the right tools to make the most of it. Today, we will compare two GraphQL Integrated Development Environments (IDEs): GraphiQL and Altair.

Click the image below to watch the YouTube video version of this blog post:

Introduction to GraphQL IDEs

Before diving into our comparison, let's quickly understand what a GraphQL IDE is. A GraphQL IDE is a tool that helps developers interact with GraphQL APIs, very similar to how your text-editor (like VSCode or IntelliJ) helps you write code.

These IDEs provide several functionalities, such as auto-completion, error highlighting, and interactive documentation. They help developers to construct and test GraphQL queries and mutations, visualize the returned data, and understand the structure of the GraphQL schema.

Two popular GraphQL IDEs are GraphiQL and Altair. Let's take a closer look at each.

GraphiQL

GraphiQL is one of the most well-known GraphQL IDEs. Originally developed by Facebook, it is an in-browser tool that enables developers to write, validate, and test GraphQL queries. It is open-source and can be integrated into any project that uses GraphQL. Recently, GraphiQL has been revamped with a new UI and several new features as you can read in ths blog post I wrote earlier.

The most important features of GraphiQL are:

Schema introspection: GraphiQL offers a robust view of the schema, letting you examine types, fields, and overall structure.
Autocompletion: Based on the schema, GraphiQL provides autocompletion, making it easier to construct complex queries.
Syntax highlighting: This feature makes it easier to understand and navigate through the GraphQL queries and mutations. This includes errors. If you make a syntax mistake, GraphiQL will underline it immediately.
Interactive Documentation: GraphiQL builds an interactive GraphQL API documentation on-the-fly, making it easy to understand the API.
Query history: This feature lets you access your previous queries, so you don't have to rewrite them.

As mentioned, if you want to learn more about GraphiQL then check out this blog post I wrote earlier.

Altair

Altair GraphQL Client is another impressive GraphQL IDE. It is open-source and available as a desktop app for all major operating systems, as well as a web extension for Chrome and Firefox.

There's a lot of features that Altair offers that you can also find in GraphiQL, but here are some of the most important ones:

Multiple Windows: Altair allows you to open multiple windows at the same time, enabling you to work with different queries (and GraphQL APIs) simultaneously.
Autocompletion & Error Highlighting: Like GraphiQL, Altair also offers autocompletion and error highlighting.
Subscriptions: Altair supports GraphQL subscriptions, enabling real-time updates.
File Uploads: Altair supports GraphQL multipart request specification (Multipart request), allowing you to test file uploads.
Pre-request scripting: You can write scripts that run before the request is sent. This is useful for handling complex authentication flows.
Collections:: Perhaps the most powerful feature of Altair is the ability to create collections of queries and mutations. This allows you to organize your queries and mutations across multiple GraphQL APIs in a logical way.

Of course, there are many more features that Altair offers. If you want to learn more about Altair, then check out the official documentation.

So how do GraphiQL and Altair compare? Let's find out.

Comparing GraphiQL and Altair

GraphiQL and Altair share a common set of features like schema introspection, syntax highlighting, error highlighting, and auto-completion. However, they have some distinctive attributes as well.

While GraphiQL's interactive documentation and query history make API exploration and reiteration of queries more comfortable, it lacks some advanced features like pre-request scripting, file uploads, and subscriptions, which are provided by Altair.

On the other hand, Altair shines with its extensive feature set, providing advanced functionalities that make it more versatile for complex use-cases. The ability to handle file uploads and work with multiple GraphQL APIs simultaneously is a huge plus.

To see a side-by-side comparison of GraphiQL and Altair, check out the video on my YouTube channel.

Or find me on Twitter at @gethackteam. I'd love to hear from you!

This post was originally published on hackteam.io. Reposted automatically with Reposted.io.

How to Build Angular Search Functionality with GraphQL?

Roy Derks — Mon, 27 Mar 2023 12:46:11 +0000

In this tutorial, you will learn how to build a fullstack Angular application that uses GraphQL to fetch data from a server. The application we'll build together will display a list of blog posts fetched from a GraphQL API using Apollo Client, including search functionality. To create the GraphQL API, we will use StepZen, a GraphQL API platform that allows you to build and deploy a GraphQL API in minutes.

Do you prefer watching a video walkthrough instead? Check out the link below:

Introduction

Google has developed Angular, an open-source web application framework based on TypeScript. The initial release of Angular from angular.js involved a complete rewrite, enabling the creation of large-scale, cross-platform applications.

Angular has gained a reputation for its exceptional developer tooling, which includes built-in features such as TypeScript support, routing, and a command-line interface. Additionally, Angular's component-based architecture, remarkable speed and performance, and other powerful features make it a popular choice among developers.

Prerequisites

To follow this tutorial, you will need the following:

Node.js installed on your machine
Angular CLI installed on your machine (you can install it globally by running the following command using npm: npm install -g @angular/cli)
StepZen CLI installed on your machine (you can install it globally by running the following command using npm: npm install -g stepzen)

You can find the source code for this tutorial on GitHub.

Setting up a new Angular project

To build an Angular application, we will use the Angular CLI. The Angular CLI is a command-line interface that allows you to create, build, and test Angular applications.

If you don't have the Angular CLI already on your machine, you can install it globally by running the following command using npm:

`npm install -g @angular/cli`

Note: The Angular CLI requires a minimum Node.js version of either v14.20, v16.13, or v18.10. With the Angular CLI installed, we can now create a new Angular application by running the following command:

`ng new with-angular --directory ./with-angular`

This command will create a new Angular application named with-angular, and we specified the directory where the application will be created with the'-- directory' flag. The Angular CLI will create a new directory named with-angular if it doesn't exist and will create the application inside the directory.

After the Angular CLI has finished creating the application, we can now navigate to the application directory and start the development server by running the following commands:

cd with-angular
ng serve --open

The ng serve command will start the development server, and the --open flag will open the application in the default browser.

With the starter application running, we can now start building our application. But before we can start building the application, we need to create a GraphQL API that we can use to fetch data. In the next section, we'll create a GraphQL API using StepZen.

Creating a GraphQL API with StepZen

The Angular application we build in this blog post will fetch data from a GraphQL API. To create a GraphQL API, we will use StepZen, a GraphQL API platform that allows you to build and deploy a GraphQL API in minutes. One of the capabilities of StepZen is transforming REST APIs into GraphQL APIs, which will be demonstrated in this tutorial.

Before creating a GraphQL API, we need to create a StepZen account. You can create a free account by visiting the StepZen website. And once you've created an account, you can install the StepZen CLI (if you haven't already) by running the following command:

`npm install -g stepzen`

With the StepZen CLI installed, we can now create a new StepZen project in the with-angular directory by running the following command:

mkdir stepzen
stepzen init --endpoint=api/with-angular

The blog posts we want to show in our application are fetched from the DEV.to API. More specifically, we will fetch the posts from the DEV.to API's articles endpoint: https://dev.to/api/articles?username=gethackteam. The articles endpoint returns a list of articles, and you could provide a different username to fetch articles from another user.

To create a GraphQL API that fetches data from the DEV.to API, we can use the import command from the StepZen CLI. This command will create a GraphQL schema for this REST API:

`stepzen import curl 'https://dev.to/api/articles?username=gethackteam' --name=posts --query-type=Posts --query-name=posts`

Which generates a new GraphQL schema in a directory named posts, which has a query called posts that returns a list of posts. The --query-type flag specifies the name of the type that the query will return, and the --query-name flag specifies the query's name.

From a different DEV.to endpoint, we want to retrieve a single post by its ID to retrieve a list of posts. To do this, we can use the import command again, but this time we'll use the --query-type and --query-name flags with different values to specify the name of the type and query:

`stepzen import curl 'https://dev.to/api/articles/1366695' --name=post --query-type=Post --query-name=post`

There might be some overlap between type names when importing multiple REST APIs using stepzen import curl. The StepZen CLI will notify you of this, and you can manually delete the duplicated types from the GraphQL schemas. For this project, we can delete the User, and Organization types from the file post/index.graphql as these were already specified in the schema for the first import.

To deploy the GraphQL API, we can run the following command:

`stepzen start`

This command will deploy the GraphQL API to the StepZen cloud. Once the GraphQL API is deployed, you explore the GraphQL API from the Explorer in the StepZen dashboard by visiting the following URL: https://dashboard.stepzen.com/explorer?endpoint=api%2Fwith-angular%2F__graphql.

From the Explorer, you can run queries and mutations against the GraphQL API. For example, you can run the following query to retrieve a list of posts:

query GetPosts {
  posts {
    id
    title
    description
  }
}

You can also search for articles from a specific user by changing the username parameter in the query, as shown in the screenshot below.

With the GraphQL API deployed, we can now start building our Angular application. In the next section, we'll add Apollo Client to our Angular application.

Adding Apollo Client to our Angular application

Install Apollo Client for Angular

`ng add apollo-angular`

We're using the Angular CLI to add the library apollo-angular rather than npm, as this will autogenerate some of the boilerplate code to set up Apollo Client. The Angular CLI will prompt you for the endpoint of your GraphQL API, which you can answer with the endpoint of your GraphQL API that you deployed in the previous step. The endpoint of your GraphQL API is printed in the terminal after running stepzen start, and will look something like this: https://YOUR_USERNAME.stepzen.com/with-angular/__graphql.

Once entering your GraphQL API endpoint and the GraphQL version (you can use the suggested one), the Angular CLI will generate the setup files for Apollo Client and reference it in the entry point of your application:

CREATE src/app/graphql.module.ts (713 bytes)
UPDATE package.json (1128 bytes)
UPDATE tsconfig.json (895 bytes)
UPDATE src/app/app.module.ts (462 bytes)

These steps complete the installation of Apollo Client but don't handle the data fetching part yet. The next section will add a new Angular component and fetch data from the GraphQL API.

Fetching data with Apollo Client

The query we'll use to display the blog posts is the same one we created in the first part of this blog post. You need to create a new file called graphql.operations.ts in the app directory and add the following content:

import { gql } from 'apollo-angular'

const GET_POSTS = gql`
    query GetPosts {
        posts {
        id
        title
        description
        }
    }
`

export { GET_POSTS }

And use the Angular CLI to generate the boilerplate files for a new component called posts in the app directory:

`ng generate component posts --module app`

The Angular CLI will create a new directory called posts with the files for the business logic (*.ts), styling (*.css), markup (*.html), and testing (*.spec.ts).

To add the logic to fetch the data from the GraphQL API, you can replace the code in posts/posts.component.ts with the following:

import { Component, OnInit } from '@angular/core';
import { Apollo } from 'apollo-angular';
import { GET_POSTS } from '../graphql.operations';

@Component({
  selector: 'app-posts',
  templateUrl: './posts.component.html',
  styleUrls: ['./posts.component.css']
})

export class PostsComponent implements OnInit {
  posts: any[] = [];
  error: any;
  constructor(private apollo: Apollo) { }
  ngOnInit(): void {
    this.apollo.watchQuery({
      query: GET_POSTS
    }).valueChanges.subscribe(({ data, error }: any) => {
      this.posts = data.posts;
      this.error = error;
    }
    );
  }
}

But we also need to add the styling and markup to render the posts in the application. In posts.component.html and posts.component.css, let's add the following HTML and CSS:

Add the following HTML code in posts.component.html:

<div class="main">
    <div *ngIf="error">
        <p>Error: {{ error }}</p>
    </div>
    <div class="posts-container" *ngIf="posts">
        <ul>
            <li *ngFor= "let post of posts">
                <div class="post">
                    <span class="post-title">{{ post.title }}</span>
                    <span class="post-description">{{ post.description }}</span>
                </div>
            </li>
        </ul>
    </div>
</div>

And the following CSS in posts.component.css:

.main {
    margin-top: 60px;
}
.posts-container ul {
    list-style: none;
    display: grid;
    grid-template-columns: repeat(3, 1fr);
    grid-gap: 10px;
}
.posts-container ul li {
    padding: 10px;
    border-bottom: 1px solid #e0e0e0;
}
.post {
    display: flex;
    flex-direction: column;
    padding: 10px;
}
.post-title {
    font-size: 18px;
    font-weight: bold;
    padding-bottom: 10px;
}
.post-description {
    font-size: 14px;
}

To render the posts in the application, we need to add app-posts (the selector from PostsComponent) to the app.component.html file. In this file, replace the content with the following:

<header role="banner">
  <img src="https://stepzen.comdata:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNTAgMjUwIj4KICAgIDxwYXRoIGZpbGw9IiNERDAwMzEiIGQ9Ik0xMjUgMzBMMzEuOSA2My4ybDE0LjIgMTIzLjFMMTI1IDIzMGw3OC45LTQzLjcgMTQuMi0xMjMuMXoiIC8+CiAgICA8cGF0aCBmaWxsPSIjQzMwMDJGIiBkPSJNMTI1IDMwdjIyLjItLjFWMjMwbDc4LjktNDMuNyAxNC4yLTEyMy4xTDEyNSAzMHoiIC8+CiAgICA8cGF0aCAgZmlsbD0iI0ZGRkZGRiIgZD0iTTEyNSA1Mi4xTDY2LjggMTgyLjZoMjEuN2wxMS43LTI5LjJoNDkuNGwxMS43IDI5LjJIMTgzTDEyNSA1Mi4xem0xNyA4My4zaC0zNGwxNy00MC45IDE3IDQwLjl6IiAvPgogIDwvc3ZnPg==" />
  <span>My posts</span>
</header>

<app-posts></app-posts>

Finally, add styling to the app.component.css file:

* {
    font-family: Arial, Helvetica, sans-serif;
    padding: 0;
}
header {
    position: absolute;
    top: 0;
    left: 0;
    right: 0;
    height: 60px;
    display: flex;
    align-items: center;
    background-color: #1976d2;
    color: white;
    font-weight: 600;
}
header img {
    margin: 0 16px;
}

The application should now look like this; make sure to run npm start to start the development server:

But that's not all. You can also search posts by username. In the next section, we'll extend the functionality of this application by adding a search bar.

Adding search functionality

In this section, we'll add a search bar to the application to search for posts by username. With this functionality, we can search for posts by a specific user.

For starters, we will add a new query to the graphql.operations.ts file. This query will take a username as an argument and return the same fields as the GET_POSTS query:

// ...
const GET_POSTS_BY_USERNAME = gql`
    query GetPostsByUsername($username: String!) {
        posts(username: $username) {
            id
            title
            description
        }
  }
`

export { GET_POSTS, GET_POSTS_BY_USERNAME }

From the file posts/posts.component.ts, we first need to import the built-in forms library @angular/forms and the GET_POSTS_BY_USERNAME query:

import { Component, OnInit } from '@angular/core';
import { FormControl, FormGroup, Validators } from '@angular/forms';
import { Apollo } from 'apollo-angular';
import { GET_POSTS, GET_POSTS_BY_USERNAME } from '../graphql.operations';
// ...

In the same file, we will add a new method called searchPosts that will be called when the user submits the search form. This method will take the GET_POSTS_BY_USERNAME query and pass the username as an argument. The data for posts will be overwritten with the new data:

// ...
export class PostsComponent implements OnInit {
  posts: any[] = [];
  error: any;
  searchForm = new FormGroup({
    username: new FormControl('gethackteam', Validators.required),
  });
  searchPosts() {
    this.apollo.query({
      query: GET_POSTS_BY_USERNAME,
      variables: {
        username: this.searchForm.value.username,
      }
    }).subscribe(({ data }: any) => {
      this.posts = data.posts;
    });
  }

To add the search bar, we will add a form element to the markup file posts.component.html:

<div class="main">
    <div *ngIf="error">
        <p>Error: {{ error }}</p>
    </div>
    <form class="form" [formGroup]="searchForm" (ngSubmit)="searchPosts()">
        <input class="input" type="text" name="username" placeholder="Enter username" formControlName="username" />
        <br />
        <button class="submit-button" [disabled]="searchForm.invalid">SUBMIT</button>
    </form>
    <!-- ... -->

And to complete the search functionality, you can add the following styling rules to the bottom of the file posts.component.css:

form {
    display: flex;
    align-items: center;
    justify-content: center;
    padding: 10px;
}
form input[type="text"] {
    padding: 5px 10px;
    margin-right: 10px;
}
form button {
    padding: 7px 12px;
    border: 0px;
    border-radius: 3px;
    background: #E23237;
    color: #FFF;
}

If you go to the Angular application running in your browser on localhost you can now search by username. A placeholder username is already present, and you can press the "submit" button to search for posts written by this username. Or, replace this value with your own username.

Congrats on building a fullstack Angular application! The final application should look something like the screenshot above. You can add features like error and loading status or routing to display an individual post to continue learning.

Conclusion

This tutorial taught you to use GraphQL in an Angular application using Apollo Client. With Angular, you can build scalable frontend applications with native TypeScript support. On the other hand, Apollo Client is a library to help you fetish data from a GraphQL API. For example, the GraphQL API you created in this tutorial by transforming the DEV.to REST API into GraphQL using StepZen.

Head over to our examples repository for more examples of using GraphQL and frontend libraries. Or the StepZen docs to learn more about building GraphQL APIs? If you have questions about this tutorial, you can ask for help on our Discord channel.

This post was originally published on stepzen.com. Reposted automatically with Reposted.io.

Building a JWT Login Flow with Auth0, Next.js, and StepZen

Roy Derks — Wed, 15 Feb 2023 13:34:42 +0000

Almost every frontend application needs some form of authentication. This post will build a JWT login flow with Auth0, Next.js, and StepZen. Auth0 Next.js authentication library nextjs-auth0, a library maintained by Auth0 to make integrating with Next.js flawless, will handle the authentication flow. Auth0 is a popular authentication provider that supports many different authentication methods, including social login, passwordless login, and more.

TLDR; You can find the complete source code for this blog post on GitHub.

What does the login flow look like?

For this login flow, we will rely on OAuth 2.0 and more specifically the Authorization Code Grant flow. This flow involves both a frontend and a backend. The frontend application will handle the login flow and redirect the user to the backend. The backend will exchange the authorization code for a JSON Web Token (JWT) and return it to the frontend application. The frontend application will then use the JWT to make requests to the backend.

The frontend application will be a Next.js application that uses the nextjs-auth0 library to handle the login flow. In this application, users click a button that brings them to the Auth0 Universal Login page. From this page, they can log in using a combination of email address and password, or one of the many social providers that are available in Auth0. After logging in, the user is asked to grant access to their profile information to the authorization server. The backend StepZen GraphQL API references an Auth0 JSON Web Key Set to verify the JWT before returning sensitive data to the frontend application.

Setting up Auth0

In this section, we will configure our Auth0 account to integrate it into our application later. This involves creating an Auth0 account, creating an API in the Auth0 dashboard, and an application that will be used to generate access tokens for our StepZen GraphQL API.

First, you need to have an Auth0 account. If you don't have one yet, you can create one for free by following the instructions on the Auth0 website.

Second, we need to create an API in Auth0. This API will represent our StepZen GraphQL API and give it access to the Auth0 authorization server. To do this, we need to go to the Auth0 dashboard and:

Click the Applications link in the left navigation pane.
Click the APIs` link in the left navigation pane.
Click the + Create API button.
On this page you need to fill out the following fields:
- Enter a name in the Name field to help you identify this client. For example: "My StepZen API".
- For the Identifier field, enter a unique value. For example: "https://my-stepzen-api.com".
And click the Create button.

You should now see a page that contains the Identifier and Audience fields. The Identifier is the URL that will be used to identify your API; this is the value that will be used to identify your API when requesting an access token. We will need these values later on, so copy them somewhere.

Not setting up an API in this stage will lead to Auth0 creating an opaque access token. This token will not be able to be validated by StepZen, but only by Auth0. This is not what we want, so make sure to create an API.

Finally, we need to create an application in Auth0. This application is the authorization server that will be used to generate access tokens for our StepZen GraphQL API.

Go Back to the Applications page.
Click the + Create Application button.
Fill out the following fields:
- Enter a name in the Name field to help you identify this client. For example: "My StepZen App".
- For application type, select Single Page Web Applications (or Regular Web Applications).
Click the Create button.

Go the Settings tab to find the configuration needed to integrate with StepZen:

Domain
Client ID
Client Secret

Copy the values for the Domain, Client ID, and Client Secret fields. We will need these values in our frontend application later on.

We also need to configure the application to allow it to redirect to our frontend application. Scroll down to the Allowed Callback URLs field and add the following URL: "http://localhost:3000/api/auth/callback"

Great! We have now configured our Auth0 account and can move on to the next step.

Creating a Next.js application

In this section, we will create a Nextjs frontend application to handle the login flow with nextjs-auth0. This application will use the nextjs-auth0 library to handle the login flow. This library will take the redirect to the Auth0 Universal Login page and handle the callback from the Auth0 authorization server. It will also handle storing the JWT in the browser and, optionally, refreshing the JWT when it expires.

You can create a new Nextjs application by running the following command:

bashnpx create-next-app`

The Next.js setup will prompt you with a few questions, such as the name you want to give to the application, if you want to use TypeScript, and if you want to use experimental features. We will use the default settings for this post, so you can press enter to accept the default values.

Once you've finished the setup of the Next.js application, let's install the following dependency that is needed for authentication:

`bash
npm install @auth0/nextjs-auth0

or if you're using yarn

yarn add @auth0/nextjs-auth0
`

And add your Auth0 API and Application configuration to the .env file:

bash AUTH0_SECRET='LONG_RANDOM_VALUE' # A long, secret value used to encrypt the session cookie AUTH0_BASE_URL='http://localhost:3000' AUTH0_ISSUER_BASE_URL='https://YOUR_AUTH0_DOMAIN.auth0.com' AUTH0_CLIENT_ID='YOUR_AUTH0_CLIENT_ID' AUTH0_CLIENT_SECRET='YOUR_AUTH0_CLIENT_ID' AUTH0_AUDIENCE='YOUR_AUTH0_API_IDENTIFIER'

You can execute the following command to generate a suitable string for the AUTH0_SECRET value: node -e "console.log(crypto.randomBytes(32).toString('hex'))"

With the configuration in place, we can now add the code to the Next.js application to use the nextjs-auth0 library to handle the login flow.

Create a new file called pages/api/auth/[...auth0].ts (or create the file as .js if you prefer not to use TypeScript). The nextjs-auth0 library will use this file to handle the login flow and as the callback URL for the Auth0 authorization server.
Add the following code to the new pages/api/auth/[...auth0].ts file:

`ts
import { handleAuth, handleLogin } from '@auth0/nextjs-auth0';

export default handleAuth({
login: handleLogin({
authorizationParams: {
audience: process.env.AUTH0_AUDIENCE, // or AUTH0_IDENTIFIER
// Add the offline_access scope to also get a Refresh Token
scope: 'openid profile email', // or AUTH0_SCOPE
},
}),
});
`

We also need to wrap the application with the UserProvider component. This component will be used to store the user information in the React context. This will allow us to access the user information in any component in the application. For example, by using any of the Hooks provided by nextjs-auth0. To do this, we need to add the following code to the pages/_app.tsx file:

`ts
// pages/_app.tsx
import '@/styles/globals.css';
import type { AppProps } from 'next/app';
import { UserProvider } from '@auth0/nextjs-auth0/client';

export default function App({ Component, pageProps }: AppProps) {
return (

);
}
`

The last step is to add a login button to the application. To do this, we need to add the replace the contents in the pages/index.tsx file with the following code:

`tsx
// pages/index.tsx
import Head from 'next/head';
import Link from 'next/link';
import styles from '@/styles/Home.module.css';

export default function Home() {
return (
<>

My StepZen App

  <main className={styles.main}>
    <Link href='/api/auth/login' className={styles.loginButton}>
      <span className={styles.auth0Logo} />Login with Auth0
    </Link>
  </main>
</>

);
}
`

And finally, we need to add some styles to the application. Open the file called styles/Home.module.css and add the following code to the bottom of it:

`css
.loginButton {
display: flex;
align-items: center;
background: #eb5424;
padding: 10px 20px;
border-radius: 10px;
font-size: larger;
color: white;
}

.auth0Logo {
width: 32px;
height: 32px;
margin-right: 10px;
background: url('/auth0_icon.svg');
}
`

Now run the application by executing the following command:

`bash
npm run dev

or if you're using yarn

yarn dev
`

Open the application in your browser by navigating to http://localhost:3000. You should see a login button:

Once you press the login button, you should be redirected to the Auth0 Universal Login page. Sign up here for a new account that will be added to the linked Auth0 account.

After clicking the Continue button, you should be redirected back to the application. If you open the browser's developer tools and look at the cookies, you should see a new cookie added that includes your JWT. This cookie is used to authenticate you in the application.

We now have the first part of the login flow that uses Auth0 to get a JWT. Next, we want to use this JWT to authenticate the user in the StepZen GraphQL API, so we can fetch the user's profile information from the Auth0 API.

Creating a StepZen GraphQL API

With StepZen, you can create a GraphQL API for every data source, including REST APIs, databases, and more. In this section, we will create a GraphQL API that uses the Auth0 JWT to authenticate the user. The GraphQL API will fetch the user's profile information from the Auth0 API.

First, we need to create a new StepZen project. To do this, create a new directory called stepzen in the root of your project and run the following command in your terminal:

bashstepzen init api/jwt-login-flow`

This will create a new StepZen configuration file and set the endpoint name to api/jwt-login-flow. You can also choose to use a different name if you prefer.

To set up the StepZen GraphQL API, we need to complete the following steps:

Create a new schema file called api.graphql. This file will contain the GraphQL schema for the API, including a query to get user information from the Auth0 API. Replace the value for YOUR_AUTH0_DOMAIN with the domain of your Auth0 account:

`graphql
type User {
email: String
email_verified: Boolean
name: String
nickname: String
picture: String
sub: String
updated_at: DateTime
}

type Query {
me: User
@rest(
endpoint: "https://YOUR_AUTH0_DOMAIN/userinfo"
forwardheaders: ["Authorization"]
)
}
`

StepZen needs to have an index.graphql that references the api.graphql file. Create a new file called index.graphql and add the following code to it:

graphql schema @sdl(files: ["api.graphql"]) { query: Query }

To verify the Auth0 JWT, we need to create a new file called config.yaml. In this file, we'll add the configuration to valide the JWT using the JSON Web Key Set (JWKS) endpoint from Auth0 and the configuration to protect the GraphQL query me so authenticated users can only access it. Replace the value for YOUR_AUTH0_DOMAIN with the domain of your Auth0 account:

`yaml

Add the JWKS endpoint

deployment:
identity:
jwksendpoint: 'https://YOUR_AUTH0_DOMAIN/.well-known/jwks.json'

Set the policies

access:
policies:
- type: Query
policyDefault:
condition: true
rules:
- condition: '?$jwt' # Require JWT
fields: [me] # Define fields that require JWT
`

Now run the following command to deploy and run your StepZen project:

bashstepzen start`

In your terminal, you should see a message that includes the URL of your GraphQL API. Copy the URL (which starts with https://YOUR_USERNAME.stepzen.net/api/****** and paste it into the .env file:

`bash

Your StepZen endpoint

STEPZEN_ENDPOINT='YOUR_STEPZEN_ENDPOINT'
`

That's it! We now have a working GraphQL API that can be used to validate the Auth0 JWT and fetch user information from the Auth0 API.

In the next section, we'll use this GraphQL API to fetch the user's profile information in the Next.js application.

Fetching user information in the Next.js application

In this section, we will use the GraphQL API that we created in the previous section to fetch the user's profile information in the Next.js application. We'll take the token from Auth0 using the library nextjs-auth0 to authenticate the user in the GraphQL API.

To do this, we need to complete the following steps:

Create a new file called pages/api/graphql/index.ts. This file will be the API route to send requests to the StepZen GraphQL API. It uses the withApiAuthRequired function from the nextjs-auth0 library, so the JWT will be available in the request, which we can extract using the getAccessToken function. We're using an API route here as exectuting the data fetching server side is the recommended way to fetch data in Next.js. This JWT will then be forwarded to the GraphQL API together with the GraphQL query. You can add the following code to this file:

`ts
import type { NextApiRequest, NextApiResponse } from 'next';
import { withApiAuthRequired, getAccessToken } from '@auth0/nextjs-auth0';

export default withApiAuthRequired(async function handler(
req: NextApiRequest,
res: NextApiResponse,
) {
const { accessToken } = await getAccessToken(req, res);

const headers = {
Authorization: Bearer ${accessToken},
'Content-Type': 'application/json',
};

const body = req.body;

try {
const response = await fetch(process.env?.STEPZEN_ENDPOINT || '', {
method: 'POST',
headers,
body,
});

const json = await response.json();

res.status(200).json(json);

} catch (e: unknown) {
const message = (e as Error).message;

res.status(500).json({ error: message });

}
});
`

You can also generate a code snippet to connect to a StepZen GraphQL API from the StepZen dashboard. You can find this under the Explorer tab in the left pane of the dashboard by clicking on the Connect button in the top navigation.

In the pages/index.tsx file, we're using the new API route to fetch the user's profile information. When sending a request to this API route, we need to pass along the GraphQL query to get the user's name and picture. You can add the following code to this file:

`tsx
export default function Home() {
const [userData, setUserData] = useState name: string;
picture: string;
}>(null);

useEffect(() => {
async function fetchData() {
const res = await fetch('/api/graphql', {
method: 'POST',
body: JSON.stringify({
query: query { me { name picture } },
}),
});
const json = await res.json();

  if (json?.data?.me) setUserData(json.data.me);
}

fetchData();

}, [setUserData]);

return (
// ...
);
}
`

After retrieving the user's profile information, we can display it in the UI. You can add the following code to the pages/index.tsx file:

tsx return ( <main className={styles.main}> <div className={styles.center}> {userData ? ( <div className={styles.profile}> <img src={userData.picture} alt={${userData.name}'s profile picture} width={200} height={200} /> <p> <strong>Welcome {userData?.name}!</strong>{' '} <a href='/api/auth/logout'>Logout</a> </p> </div> ) : ( <Link href='/api/auth/login' className={styles.loginButton}> <span className={styles.auth0Logo} /> Login with Auth0 </Link> )} </div> </main> )

Next.js recommends using the Image component from next/image to render images. However, when rendering remote sources, you need to allow access to the remote URLs of these sources. Therefore, we're using the img tag instead.

Finally, we need to add the styling for the profile information. You can add the following code to the Home.module.css file:

`css
.profile {
display: flex;
justify-content: center;
align-items: center;
flex-direction: column;
margin-top: 20px;
}

.profile img {
border-radius: 50%;
margin-bottom: 20px;
}

.profile a {
color: #eb5424;
text-decoration: underline;
}
`

Now, if you open the application in the browser again and click on the Login with Auth0 button, you should be redirected to the Auth0 login page. After logging in, you should see the user's profile information in the UI.

As a finishing touch, we can show a loading indicator while the application checks if the user is authenticated and fetches the user's profile information. Therefore the useUser hook should be imported from @auth0/nextjs-auth0/client and the isLoading property should be used to check if the user is authenticated. You can add the following code to the pages/index.tsx file:

`tsx
import { useEffect, useState } from 'react';
import Head from 'next/head';
import Link from 'next/link';
import { useUser } from '@auth0/nextjs-auth0/client';
import styles from '@/styles/Home.module.css';

export default function Home() {
const { isLoading } = useUser();

// ...

return (

{isLoading ? (
Loading...
) : (

{
// ...
}

)}

);
}
`

Great! With this, we've implemented the login flow using Auth0 and StepZen. You can find the complete source code for this blog post on GitHub.

Next Steps?

The flow we've implemented in this blog post is a typical pattern for frontend applications that want to provide a secure way to authenticate users. The application uses the @auth0/nextjs-auth0 package to handle the authentication flow and a StepZen GraphQL API to verify the JWT on the server side. This way, the application can use the user's profile information on both the client side and in requests to the GraphQL API.

This post was originally published on stepzen.com. Reposted automatically with Reposted.io.

Comparing GraphQL Directives: Type System Vs. Executable Directive Locations

Roy Derks — Wed, 01 Feb 2023 16:12:17 +0000

Have you ever wondered why some directives have to be added to your GraphQL schemas while others you can only use in runtime? That's because there are two types of directive locations: type system directive locations and executable directive locations.

Earlier, we wrote about the different directives there are in GraphQL. This post will recapture what directives are and examine the difference between the different locations directives can be applied to.

Remind me, what is a GraphQL Directive?

Directives in GraphQL offer a means to change runtime execution and type validation in a GraphQL document. You can apply directives to many different locations in a GraphQL document, such as fields, fragments, and operations. They allow you to modify the behavior of GraphQL's execution by providing options that are not available through field arguments. For instance, you can conditionally include or exclude a field using directives, as you'll learn in this post.

You can use built-in or custom directives when building or consuming a GraphQL API. Built-in directives are defined by the GraphQL specification, while custom directives are defined by the GraphQL service or tool you use. Let's look at some of the built-in directives.

Built-in Directives

The GraphQL specification defines a set of built-in directives. Directives have a specific name and can accept values of any input type as arguments. They can be applied to, for example, types, fields, fragments, and operations.

The following list has all the built-in directives that are defined by the GraphQL specification:

@skip: This directive can be used to exclude fields from a query operation conditionally.
@include: Does the opposite of @skip and can be used to include fields in a query operation conditionally.
@deprecated: This directive can mark a field or an enum value as deprecated and can provide a reason for deprecation to the client.
@specifiedBy: This directive can be used to provide a URL for the specification of a custom scalar.

Note: As GraphQL evolves, new execution capabilities may be introduced and exposed through directives. The directives @defer and @stream have been announced by the GraphQL Working Group but aren't listed in the latest draft of the GraphQL specification.

GraphQL services and tools can also provide custom directives beyond those already mentioned. We'll learn more about custom directives in the next section.

Custom Directives

Custom directives can be used to extend the functionality of GraphQL and are the preferred way to add custom behavior to a GraphQL API. Different GraphQL server and client implementations are already using custom directives to add additional functionality to GraphQL.

For example, at StepZen, we have defined custom directives to connect with your data sources, such as the @rest, @dbquery, and @graphql directives. When using StepZen to develop your GraphQL API, you can use these directives to connect to REST APIs, databases, and other GraphQL APIs. Additionally, we have defined the @materializer and @sequence directives to mix and match data from multiple data sources in a single type.

But next to built-in and custom directives, there is another distinction to be made between directives: the location they are used in. In the next section, we'll examine the difference between directives applied to type system and executable locations in GraphQL.

Type System Directive Locations vs. Executable Directive Locations

Directives in GraphQL can be applied to different locations, where the GraphQL Specification makes a distinction between type system directive locations and executable directive locations. Directives applied to either of these locations have the same syntax; therefore, their location determines how a GraphQL implementation handles them. However, a directive may support both type system and executable locations, though typically, a single directive supports only one location. For example, @skip only supports executable directive locations.

Let's look at the locations where directives can be applied and see examples for both types.

Directives that apply to the type system

Directives that apply to the type system are used to annotate a schema, object type, or field definition written in GraphQL SDL (schema definition language) when building a GraphQL server. Both built-in and custom directives can be used in type system directive locations, and GraphQL server implementations can then use these annotations to take additional actions. Therefore, type system directive locations are also called "schema directives" as they only exist on the GraphQL schema itself.

The following locations in a GraphQL schema are valid type system directive locations:

SCHEMA
SCALAR
OBJECT
FIELD_DEFINITION
ARGUMENT_DEFINITION
INTERFACE
UNION
ENUM & ENUM_VALUE
INPUT_OBJECT & INPUT_FIELD_DEFINITION

Examples of directives that apply to the type system include @deprecated, a built-in directive that can mark a field as deprecated. Let's see what it looks like in a schema:

type User {
  id: ID!
  name: String! @deprecated(reason: "Use the firstName and lastName field instead")
  firstName: String!
  lastName: String!
  email: String!
}

In the example above, the @deprecated directive marks the name field as deprecated. The reason argument provides a reason for deprecation available to services that introspect the schema. The client could then, for example, warn the user that the field name is deprecated and shouldn't be used anymore.

When you would look up the User type in the documentation generated by GraphiQL, you should see warnings about using the field name:

Another example of a directive that can be applied to the type system is @rest, a custom directive only available in StepZen GraphQL implementations. The data for the User type in the example above is fetched from a REST API using the @rest directive, which is defined in the following way on a query field in a GraphQL schema:

type User {
  id: ID!
  name: String!
  email: String!
}

type Query {
  user(id: ID!): User
    @rest(url: "https://jsonplaceholder.typicode.com/users/$id")
}

When you run an operation that includes the user field, the StepZen GraphQL API fetches the data from the REST API and returns it to the client. The @rest directive is applied to a type system location because it annotates the user field in the schema. It lets you declaratively define how the data for the user field should be fetched, rather than having to write a resolver function, as you might expect from other GraphQL server implementations.

Directives that apply to execution

You can use directives that apply to execution to modify the behavior of an operation, field, or fragment in runtime execution. For example, directives that apply to execution can include or exclude fields or perform additional data processing before the response is returned.

Executable directive locations in GraphQL are:

QUERY
MUTATION
SUBSCRIPTION
FIELD
FRAGMENT_DEFINITION & FRAGMENT_SPREAD
INLINE_FRAGMENT
VARIABLE_DEFINITION

Similar to directives that apply to the type system directives, both built-in and custom directives can be applied to executable locations. Most built-in directives are executable, such as @skip and @include, which you can use to include or exclude fields in an operation conditionally.

Let's see what the @include directive looks like in a query operation:

query me($showName: Boolean!) {
  me {
    id
    firstName @include(if: $showName)
    lastName @include(if: $showName)
    email
  }
}

The @include directive conditionally includes the firstName and lastName fields in the response. The if argument specifies a boolean value determining whether to include the field in the response. In the example above, the if argument is set to a variable $showName, which is defined in the operation variables. The variable's value can be set to true or false to include or exclude the fields in the response.

When you'd pass this operation to a GraphQL API, the response should include the fields firstName and lastName in the response if the value of the variable $showName is set to true as you can see in the screenshot below:

Another example of an executable directive is @sort, a custom directive only available in StepZen GraphQL implementations.

With the @sort directive, you can sort the data returned by a field in a GraphQL operation. You can use the @sort directive on a field that returns either a list of leaf fields or a list of objects.

For example, let's say you have a products field that returns a list of tags. You can use the @sort directive to sort the tags by alphabetical order:

query {
  products {
    tags # ['c', 'b', 'a', null]
  }
}

Will be transformed to this when the @sort directive is used:

query {
  products {
    tags @sort # [null, 'a', 'b', 'c']
  }
}

Next to a list of leaf fields, the same @sort directive can be applied to a field that returns a list of objects. You can find more information on using the @sort directive in the documentation.

Summary

In this blog post, you learned about built-in and custom directives and how they can be applied to different locations in GraphQL. These locations are either type system or executable locations. Directives applied to the type system directives are used in GraphQL Schema Definition Language (SDL) only. At the same time, directives applied to executable locations are used to modify the response of GraphQL in runtime execution.

Want to learn more about building and consuming GraphQL APIs? Follow StepZen on Twitter or join our Discord community to stay updated about our latest developments.

This post was originally published on stepzen.com. Reposted automatically with Reposted.io.

Authenticating GraphQL APIs with OAuth 2.0

Roy Derks — Wed, 25 Jan 2023 17:33:58 +0000

There are many different ways to handle authentication in GraphQL, but one of the most common is to use OAuth 2.0 - and, more specifically, JSON Web Tokens (JWT) or Client Credentials.

In this blog post, we'll look at how to use OAuth 2.0 to authenticate GraphQL APIs using two different flows: the Authorization Code flow and the Client Credentials flow. We'll also look at how to use StepZen to manage authentication.

What is OAuth 2.0?

But first, what is OAuth 2.0? OAuth 2.0 is an open standard for authorization that allows one application to let another application access certain parts of a user's account without giving away the user's password. There are different ways to set up this type of authorization, called "flows", and it depends on the type of application you are building.

For example, if you're building a mobile app, you will use the "Authorization Code" flow. This flow will ask the user to permit the app to access their account, and then the app will receive a code to use to get an access token (JWT). The access token will allow the app to access the user's information on the website. You might have seen this flow when you log in to a website using a social media account, such as Facebook or Twitter.

Another example is if you're building a server-to-server application, you will use the "Client Credentials" flow. This flow involves sending the website's unique information, like a client ID and secret, to get an access token (JWT). The access token will allow the server to access the user's information on the website. This flow is quite common for APIs that need to access a user's data, such as a CRM or a marketing automation tool.

Let's have a look at these two flows in more detail.

Authorization Code Flow (using JWT)

The most common way to use OAuth 2.0 is with the Authorization Code flow, which involves using JSON Web Tokens (JWT). As mentioned above, this flow is used when you want to build a mobile or web application that needs to access a user's data from a different application.

For example, if you have a GraphQL API that allows users to access their data, you can use a JWT to verify that the user is authorized to access the data. The JWT could contain information about the user, such as the user's ID, and the server can use this ID to query the database and return the user's data.

You would need a frontend application that can redirect the user to the authorization server and then redirect the user back to the frontend application with the authorization code. The frontend application can then exchange the authorization code for an access token (JWT) and then use the JWT to make requests to the GraphQL API.

The JWT can be sent to the GraphQL API in the Authorization header:

curl https://USERNAME.stepzen.net/api/hello-world/__graphql \
   --header "Authorization: Bearer JWT_TOKEN" \
   --header "Content-Type: application/json" \
   --data-raw '{
     "query": "query { me { id username } }"
   }'

And the server can use the JWT to verify that the user is authorized to access the data.

The JWT can also contain information about the user's permissions, such as whether they can access a specific field or mutation. This is useful if you want to restrict access to specific fields or mutations or if you want to limit the number of requests a user can make. But we'll look at this in more detail after discussing the Client Credentials flow.

Client Credentials Flow

The Client Credentials flow is used when you want to build a server-to-server application, like an API, that needs to access information from a different application. It also relies on JWT.

As mentioned above, this flow involves sending the website's unique information, like a client ID and secret, to get an access token. The access token will allow the server to access the user's information on the website. Unlike the Authorization Code flow, the Client Credentials flow doesn't involve a (frontend) client. Instead, the authorization server will directly communicate with the server that needs to access the user's information.

Image from Auth0

The JWT can be sent to the GraphQL API in the Authorization header, in the same way as for the Authorization Code flow.

In the next section, we'll look at how to implement both the Authorization Code flow and the Client Credentials flow using StepZen.

Using StepZen to Manage Authentication

By default, StepZen uses API Keys to authenticate requests. This is a developer-friendly way to authenticate requests that don't require an external authorization server. But if you want to use OAuth 2.0 to authenticate requests, you can use StepZen to manage authentication. Similar to how you can use StepZen to build a GraphQL schema for all your data in a declarative way, you can also manage authentication declaratively.

Implement Authorization Code Flow (using JWT)

To implement the Authorization Code flow, you must set up both a (frontend) client and an authorization server. You can use an existing authorization server, such as Auth0, or build your own.

You can find a complete example of using StepZen to implement the Authorization Code flow in the StepZen GitHub repository.

StepZen can validate the JWTs generated by the authorization server and send them to the GraphQL API. You only need the authorization server to validate the user's credentials to generate a JWT and StepZen to validate the JWT.

Let's have another look at the flow we discussed above:

In this flow diagram, you can see that the frontend application redirects the user to the authorization server (from Auth0) and then turns the user back to the frontend application with the authorization code. The frontend application can then exchange the authorization code for a JWT and then use that JWT to make requests to the GraphQL API.

StepZen will validate the JWT that is sent to the GraphQL API in the Authorization header by configuring the JSON Web Key Set (JWKS) endpoint in the StepZen configuration in the config.yaml file in your project:

deployment:
  identity:
    jwksendpoint: 'YOUR_JWKS_ENDPOINT'

The JWKS endpoint is a read-only endpoint that contains the public keys to verify a JWT. The public keys can only be used to validate the tokens, as you would need the private keys to sign the tokens, which is why you need to set up an authorization server to generate the JWTs.

You can then limit the fields and mutations a user can access by adding Access Control rules to the GraphQL schema. For example, you can add a rule to the me query to only allow access when a valid JWT is sent to the GraphQL API:

deployment:
  identity:
    jwksendpoint: 'YOUR_JWKS_ENDPOINT'
access:
  policies:
    - type: Query
      rules:
        - condition: '?$jwt' # Require JWT
          fields: [me] # Define fields that require JWT

This rule only allows access to the me query when a valid JWT is sent to the GraphQL API. If the JWT is invalid, or if no JWT is sent, the me query will return an error.

Earlier, we mentioned that the JWT could contain information about the user's permissions, such as whether they can access a specific field or mutation. This is useful if you want to restrict access to specific fields or mutations or if you want to limit the number of requests a user can make.

You can add a rule to the me query to only allow access when a user has the admin role:

deployment:
  identity:
    jwksendpoint: 'YOUR_JWKS_ENDPOINT'
access:
  policies:
    - type: Query
      rules:
        - condition: '$jwt.roles:String has "admin"' # Require JWT
          fields: [me] # Define fields that require JWT

To learn more about implementing the Authorization Code Flow with StepZen, look at the Easy Attribute-based Access Control for any GraphQL API article on the StepZen blog.

Implement Client Credentials Flow

You will also need to set up an authorization server to implement the Client Credentials flow. But instead of redirecting the user to the authorization server, the server will directly communicate with the authorization server to get an access token (JWT).

You can find a complete example for implementing the Client Credentials flow in the StepZen GitHub repository.

First, you must set up the authorization server to generate the access token. You can use an existing authorization server, such as Auth0, or build your own.

In the config.yaml file in your StepZen project, you can configure the authorization server to generate the access token:

# Add the JWKS endpoint
deployment:
  identity:
    jwksendpoint: 'https://YOUR_AUTH0_DOMAIN/.well-known/jwks.json'

# Add the authorization server configuration
configurationset:
  - configuration:
      name: auth
      client_id: YOUR_CLIENT_ID
      client_secret: YOUR_CLIENT_SECRET
      audience: YOUR_AUDIENCE

The client_id, client_secret and audience are required parameters for the authorization server to generate the access token (JWT). The audience is the API's identifier for the JWT. The jwksendpoint is the same as the one we used for the Authorization Code flow.

In a .graphql file in your StepZen project, you can define a query to get the access token:

type Query {
  token: Token
    @rest(
      method: POST
      endpoint: "YOUR_AUTHORIZATION_SERVER/oauth/token"
      postbody: """
      {
        "client_id": "{{ .Get "client_id" }}",
        "client_secret": "{{ .Get "client_secret" }}",
        "audience": "{{ .Get "audience" }}",
        "grant_type": "client_credentials"
      }
      """
    )
}

The token mutation will request the authorization server to get the JWT. The postbody contains the parameters that are required by the authorization server to generate the access token.

You can then use the JWT from the response on the token mutation to request the GraphQL API, by sending the JWT in the Authorization header.

But we can do better than that. We can use the @sequence custom directive to pass the response of the token mutation to the query that needs authorization. This way, we don't need to send the JWT manually in the Authorization header on every request:

type Query {
  me(access_token: String!): User
    @rest(
      endpoint: "YOUR_API_ENDPOINT"
      headers: [{ name: "Authorization", value: "Bearer $access_token" }]
    )
  profile: User @sequence(steps: [{ query: "token" }, { query: "me" }])
}

The profile query will first request the token query to get the JWT. Then, it will send a request to the me query, passing along the JWT from the response of the token query as the access_token argument.

As you can see, all configuration is set up in a single file, and you can use the same configuration for both the Authorization Code flow and the Client Credentials flow. Both are written declarative, and both use the same JWKS endpoint to request the authorization server to verify the tokens.

What's next?

In this blog post, you learned about common OAuth 2.0 flows and how to implement them with StepZen. It's important to note that, as with any authentication mechanism, the details of the implementation will depend on the application's specific requirements and the security measures that need to be in place.

StepZen GraphQL APIs are default protected with an API key but can be configured to use any authentication mechanism. We'd love to hear what authentication mechanisms you use with StepZen and how you use them. Ping us on Twitter or join our Discord community to let us know.

This post was originally published on stepzen.com. Reposted automatically with Reposted.io.

Learn React in 5 minutes

Roy Derks — Mon, 23 Jan 2023 09:24:22 +0000

Can you learn React in five minutes? Well, it depends on what you mean by "learn React". In this blog post you will "learn the basics of React" in five minutes, by going over a few of the core concepts of React.

Click the image below to watch the YouTube video version of this blog post:

What is React?

React is a JavaScript library that is widely used for building user interfaces, particularly for single-page applications. It allows you to create reusable components that can be rendered on the web, mobile, or desktop. Today, it is one of the most popular tools for front-end web development.

So, if you're interested in learning React, where do you start?

JavaScript

First, it's important to have a solid understanding of JavaScript. React is built with JavaScript, so you'll need to be comfortable with the basics of the language before you dive into React.

Once you've got a handle on JavaScript, the next step is to familiarize yourself with the React syntax and concepts.

Components

One of the core principles of React is that a component should be a self-contained piece of code that is easy to understand and maintain.

This is what a component looks like:

function MyComponent() {
  return (
    <div>
      <h1>My Component</h1>
    </div>
  );
}

A component is a JavaScript function that returns a React element. It can be a simple function that returns a single element, or it can be a more complex component that returns multiple elements or has state.

Data flows

In React, data flows in a single direction from the parent component to the child component, following the unidirectional data flow principle. This helps make applications easier to reason about and debug.

Parent components can pass data to child components using props, below is an example of a child compoinent that receives data from a parent component:

function MyComponent() {
  return (
    <div>
      <Title title='My Component' />
    </div>
  );
}

function Title({ title }) {
  return <h1>{title}</h1>;
}

Props are used to keep track of data that is passed from a parent component to a child component. They are immutable, which means that they cannot be changed once they are passed to a child component.

State

State is a special type of data that is managed by a component. It is used to store data that is specific to a component and it can be passed on to other components lower in the tree. State is often used to store data that is used to render the UI, such as a list of items or a user's name.

State can be managed using the useState hook, which is a function that returns an array with two values: the current state and a function that can be used to update the state:

import React, { useState } from 'react';

function MyComponent() {
  const [count, setCount] = useState(0);

  return (
    <div>
      <Counter count={count} setCount={setCount} />
    </div>
  );
}

function Counter({ count, setCount }) {
  return (
    <div>
      <p>{count}</p>
      <button onClick={() => setCount(count + 1)}>Increment</button>
    </div>
  );
}

Virtual DOM

React uses a virtual DOM (Document Object Model) to optimize updates and minimize the number of DOM mutations. This makes applications built with React faster and more efficient.

The Virtual DOM is a virtual representation of a user interface, which is kept in memory and synchronized with the "real" DOM by for example ReactDOM.

Ecosystem

React also has a large ecosystem of tools and libraries that can be leveraged to build amazing applications. Some popular ones include Tanstack Query for data fetching, Tailwind for styling and Next.js or Remix for server-rendered React applications.

Building Projects

It's also a good idea to start building some small projects with React to get a feel for how it works in practice. There are plenty of resources available online that can help you get started with your first React project, including templates and starter kits.

Need inspiration for a project?

you might want to have a look at my book React Projects. Which walks you through all the React concepts in 10 chapters. You'll build 10 unique projects. These are a "movie list" (like IMDB), a developer portfolio website using Github, a mobile game application and much more.

Keep learning

Finally, keep in mind that learning React is an ongoing process. As you build more complex projects and encounter new challenges, you'll continue to learn and improve your skills.

The comings months I'll livestreams on building these projects - and the first ones are already uploaded. So if you're interested in learning React, make sure to subscribe to my YouTube channel.

> Subscribe to my YouTube channel

Or find me on Twitter at @gethackteam. I'd love to hear from you!

This post was originally published on hackteam.io. Reposted automatically with Reposted.io. A free tool to repost your content across all blogging platforms.

Bootstrap Is The Easiest Way To Style React Apps in 2023

Roy Derks — Sun, 15 Jan 2023 20:05:21 +0000

This blog post will teach you how to use Bootstrap 5 to style a React application. With Bootstrap, you don't have to write any stying rules yourself; instead, you can use class names to apply styles to HTML elements.

Click the image below to watch the YouTube video version of this blog post:

This blog post is extracted from my book React Projects, available on Packt and Amazon.

Why use Bootstrap?

IMO, Bootstrap is still the easiest way to style a React application. Bootstrap has been around for a long time and is widely used across web applications of all sorts and sizes. And build with different frameworks or tools, ranging from WordPress to React. There are a few reasons why you might want to use Bootstrap to style a React app:

Ease of use: Bootstrap is a well-documented and widely-used CSS framework, making it easy to start and learn.
Responsive design: Bootstrap includes a responsive grid system and predefined styles for common UI elements, which makes it easier to build a responsive app that looks good on multiple devices.
Time savings: Using a CSS framework like Bootstrap can save you time by providing a set of pre-styled UI components that you can use out-of-the-box, rather than style everything from scratch.
Consistency: By using a common CSS framework, you can ensure that your app has a consistent look and feel, which can improve the user experience.

Overall, Bootstrap (or any other CSS framework) can be useful for building a well-designed and responsive React app more efficiently.

Installing Bootstrap

You can install Bootstrap using npm or yarn. For this blog post, we will use npm:

`npm install --save-dev bootstrap`

This will install Bootstrap as a devDependency in your project, and it will only be used during development and will not be included in the production build. By installing Bootstrap you can now include the CSS in your project by importing it in the root of your React project, for example, your index.js file that contains the root component of your app:

import ReactDOM from 'react-dom/client';
import List from './containers/List';

import 'bootstrap/dist/css/bootstrap.min.css';

function App() {
  // ...
}

const container = document.getElementById('app');
const root = ReactDOM.createRoot(container);

root.render(<App />);

The important part in the code block above is the line import 'bootstrap/dist/css/bootstrap.min.css', which will import the Bootstrap CSS file from the node_modules directory. This will make the Bootstrap styles available to your app.

Using Bootstrap components

Bootstrap includes several pre-styled components that you can use in your React app. For example, you can use the NavBar component to add a header element to your application.

To use this component, you can copy-paste the following code block and use it in your app:

import React from 'react';
import 'bootstrap/dist/css/bootstrap.css';

export default function Header() {
  return (
    <nav class="navbar bg-body-tertiary">
      <div class="container-fluid">
        <a class="navbar-brand" href="#">
          <img src="https://hackteam.iohttps://getbootstrap.com/docs/5.3/assets/brand/bootstrap-logo.svg" alt="Logo" width="30" height="24" class="d-inline-block align-text-top">
          Bootstrap
        </a>
      </div>
    </nav>
  )
}

Which will render the following header:

By adding the correct class names to HTML elements, you will get a modern-looking header that you don't need to style.

Of course, there are much more Bootstrap components that you can use in your React app. For example, you can use the Card component to render a card with a title, image, and text:

import React from 'react';
import 'bootstrap/dist/css/bootstrap.css';

export default function Card() {
  return (
    <div class='card' style='width: 18rem;'>
      <img src='...' class='card-img-top' alt='...' />
      <div class='card-body'>
        <h5 class='card-title'>Card title</h5>
        <p class='card-text'>
          Some quick example text to build on the card title and make up the
          bulk of the card's content.
        </p>
        <a href='#' class='btn btn-primary'>
          Go somewhere
        </a>
      </div>
    </div>
  );
}

Which will render the following card:

With just a few lines of HTML you can render a card with a title, image, and text. And you can extend this further by using Bootstrap utilities or custom CSS to style the card even more.

Bootstrap utilities

Bootstrap includes a set of utility classes that can be used to apply common styles quickly and easily. These utility classes are designed to be used in conjunction with other Bootstrap styles and can be used to override or extend the default styles of certain elements.

Some of the Bootstrap utilities include:

.text-*: These classes can be used to apply different colors to text, depending on the context (e.g. .text-primary, .text-secondary, etc.).
.bg-*: These classes can be used to apply different background colors to elements (e.g. .bg-primary, .bg-secondary, etc.).

Let's look at an example:

import React from 'react';
import 'bootstrap/dist/css/bootstrap.css';

function App() {
  return (
    <div className="container mt-5">
      <div className="row">
        <div className="col-md-6">
          <div className="card bg-primary text-white">
            <div className="card-body">
              <h5 className="card-title">Primary Card</h5>
              <p className="card-text">Some quick example text to build on the card title and make up the bulk of the card's content.</p>
            </div>
          </div>
        </div>
        <div className="col-md-6">
          <div className="card bg-secondary text-white">
            <div className="card-body">
              <h5 className="card-title">Secondary Card</h5>
              <p className="card-text">Some quick example text to build on the card title and make up the bulk of the card's content.</p>
            </div>
          </div>
        </div>
      </div>
    </div>
  );
}

export default App;

In this example, we use Bootstrap's grid system to create a layout with two equal-width columns, and we use the .bg-primary and .bg-secondary classes to give the cards different background colors. We are also using the .text-white class to make the text white to be visible against the colored backgrounds.

These are just a few examples of Bootstrap utilities. Many others are available, and you can find more information in the Bootstrap documentation.

Conclusion

This blog post has shown how to use Bootstrap 5 to style a React application. With Bootstrap you don't have to write any stying rules yourself. Instead, you can use class names to apply styles to HTML elements. Of course, you can also use Bootstrap utilities to apply common styles quickly and easily.

This blog post is extracted from my book React Projects, available on Packt and Amazon.

I hope you learned some new things about styling in React! Any feedback? Let me know by connecting to me on Twitter. Or leave a comment on my YouTube channel.

This post was originally published on hackteam.io. Reposted automatically with Reposted.io. A free tool to repost your content across all blogging platforms.

Create a React Project From Scratch Without any Framework

Roy Derks — Fri, 06 Jan 2023 15:15:54 +0000

This blog post will guide you through the process of creating a new single-page React application from the ground up. We will begin by setting up a new project using Webpack and Babel. Building a React project from scratch will give you a strong foundation and understanding of the fundamental requirements of a project, which is essential for any project you may undertake before jumping into a framework like Next.js or Remix.

Click the image below to watch the YouTube video version of this blog post:

This blog post is extracted from my book React Projects, available on Packt and Amazon.

Setting up a new project

Before you can start building your new React project, you will need to create a new directory on your local machine. For this blog (which is based upon the book React Projects), you can name this directory 'chapter-1'.

To initiate the project, navigate to the directory you just created and enter the following command in the terminal:

`npm init -y`

This will create a package.json file with the minimum information required to run a JavaScript/React project. The -y flag allows you to bypass the prompts for setting project details such as the name, version, and description.

After running this command, you should see a package.json file created for your project similar to the following:

{
  "name": "chapter-1",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

Now that you have created the package.json file, the next step is to add Webpack to the project. This will be covered in the following section.

Adding Webpack to the project

In order to run the React application, we need to install Webpack 5 (the current stable version at the time of writing) and the Webpack CLI as devDependencies. Webpack is a tool that allows us to create a bundle of JavaScript/React code that can be used in a browser. Follow these steps to set up Webpack:

Install the necessary packages from npm using the following command:

`npm install --save-dev webpack webpack-cli`

After installation, these packages will be listed in the package.json file and can be run in our start and build scripts. But first, we need to add some files to the project:

chapter-1
|- node_modules
|- package.json
   |- src
      |- index.js

This will add an index.js file to a new directory called src. Later, we will configure Webpack so that this file is the starting point for our application.

Add the following code block to this file:

`console.log('Rick and Morty');`

To run the code above, we will add start and build scripts to our application using Webpack. The test script is not needed in this case, so it can be removed. Also, the main field can be changed to private with the value of true, as the code we are building is a local project:

{
  "name": "chapter-1",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "start": "webpack --mode=development",
    "build": "webpack --mode=production"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

The npm start command will run Webpack in development mode, while npm run build will create a production bundle using Webpack. The main difference is that running Webpack in production mode will minimize our code and reduce the size of the project bundle.

Run the start or build command from the command line; Webpack will start up and create a new directory called dist.

chapter-1
|- node_modules
|- package.json
   |- dist
      |- main.js
   |- src
      |- index.js

Inside this directory, there will be a file called main.js that includes our project code and is also known as our bundle. If successful, you should see the following output:

asset main.js 794 bytes [compared for emit] (name: main)
./src/index.js 31 bytes [built] [code generated]
webpack compiled successfully in 67 ms

The code in this file will be minimized if you run Webpack in production mode.

To test if your code is working, run the main.js file in your bundle from the command line:

`node dist/main.js`

This command runs the bundled version of our application and should return the following output:

> node dist/main.js
Rick and Morty

Now, we're able to run JavaScript code from the command line. In the next part of this blog post, we will learn how to configure Webpack so that it works with React.

Configuring Webpack for React

Now that we have set up a basic development environment with Webpack for a JavaScript application, we can begin installing the packages necessary to run a React application. These packages are react and react-dom, where the former is the core package for React and the latter provides access to the browser's DOM and allows for rendering of React. To install these packages, enter the following command in the terminal:

`npm install react react-dom`

However, simply installing the dependencies for React is not enough to run it, since by default, not all browsers can understand the format (such as ES2015+ or React) in which your JavaScript code is written. Therefore, we need to compile the JavaScript code into a format that can be read by all browsers.

To do this, we will use Babel and its related packages to create a toolchain that allows us to use React in the browser with Webpack. These packages can be installed as devDependencies by running the following command:

In addition to the Babel core package, we will also install babel-loader, which is a helper that allows Babel to run with Webpack, and two preset packages. These preset packages help determine which plugins will be used to compile our JavaScript code into a readable format for the browser (@babel/preset-env) and to compile React-specific code (@babel/preset-react).

Now that we have the packages for React and the necessary compilers installed, the next step is to configure them to work with Webpack so that they are used when we run our application.

`npm install --save-dev @babel/core babel-loader @babel/preset-env @babel/preset-react`

To do this, configuration files for both Webpack and Babel need to be created in the src directory of the project: webpack.config.js and babel.config.json, respectively. The webpack.config.js file is a JavaScript file that exports an object with the configuration for Webpack. The babel.config.json file is a JSON file that contains the configuration for Babel.

The configuration for Webpack is added to the webpack.config.js file to use babel-loader:

module.exports = {
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/,
        use: {
          loader: 'babel-loader',
        },
      },
    ],
  },
};

This configuration file tells Webpack to use babel-loader for every file with the .js extension and excludes files in the node_modules directory from the Babel compiler.

To utilize the Babel presets, the following configuration must be added to babel.config.json:

{
  "presets": [
    [
      "@babel/preset-env",
      {
        "targets": {
          "esmodules": true
        }
      }
    ],
    [
      "@babel/preset-react",
      {
        "runtime": "automatic"
      }
    ]
  ]
}

In the above @babel/preset-env must be set to target esmodules in order to use the latest Node modules. Additionally, defining the JSX runtime to automatic is necessary since React 18 has adopted the new JSX Transform functionality.

Now that we have set up Webpack and Babel, we can run JavaScript and React from the command line. In the next section, we will write our first React code and run it in the browser.

Rendering React components

Now that we have installed and configured the packages necessary to set up Babel and Webpack in the previous sections, we need to create a real React component that can be compiled and run. This process involves adding some new files to the project and making changes to the Webpack configuration:

Let's edit the index.js file that already exists in our src directory so that we can use react and react-dom. Replace the contents of this file with the following:

import ReactDOM from 'react-dom/client';

function App() {
  return <h1>Rick and Morty</h1>;
}

const container = document.getElementById('root');
const root = ReactDOM.createRoot(container);
root.render(<App />);

As you can see, this file imports the react and react-dom packages, defines a simple component that returns an h1 element containing the name of your application, and has this component rendered in the browser with react-dom. The last line of code mounts the App component to an element with the root ID selector in your document, which is the entry point of the application.

We can create a file that has this element in a new directory called public and name that file index.html. The document structure of this project should look like the following:

chapter-1
  |- node_modules
  |- package.json
  |- babel.config.json
  |- webpack.config.js
  |- dist
    |- main.js
  |- public
    |- index.html
  |- src
    |- index.js

After adding a new file called index.html to the new public directory, we add the following code inside it:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta
      name="viewport"
      content="width=device-width,
initial-scale=1.0"
    />
    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
    <title>Rick and Morty</title>
  </head>
  <body>
    <section id="root"></section>
  </body>
</html>

This adds an HTML heading and body. Within the head tag is the title of our application, and inside the body tag is a section with the "root" ID selector. This matches the element we have mounted the App component to in the src/index.js file.

The final step in rendering our React component is extending Webpack so that it adds the minified bundle code to the body tags as scripts when running. To do this, we should install the html-webpack-plugin package as a devDependency:

`npm install --save-dev html-webpack-plugin`

To use this new package to render our files with React, the Webpack configuration in the webpack.config.js file must be updated:

const HtmlWebpackPlugin = require('html-webpack-plugin');
module.exports = {
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/,
        use: {
          loader: 'babel-loader',
        },
      },
    ],
  },
  plugins: [
    new HtmlWebpackPlugin({
      template: './public/index.html',
      filename: './index.html',
    }),
  ],
};

Now, if we run npm start again, Webpack will start in development mode and add the index.html file to the dist directory. Inside this file, we'll see that a new scripts tag has been inserted inside the body tag that points to our application bundle – that is, the dist/main.js file.

If we open this file in the browser or run open dist/index.html from the command line, it will display the result directly in the browser. The same is true when running the npm run build command to start Webpack in production mode; the only difference is that our code will be minified:.

This process can be sped up by setting up a development server with Webpack. We'll do this in the final part of this blog post.

Setting up a Webpack development server

While working in development mode, every time we make changes to the files in our application, we need to rerun the npm start command. This can be tedious, so we will install another package called webpack-dev-server. This package allows us to force Webpack to restart every time we make changes to our project files and manages our application files in memory instead of building the dist directory.

The webpack-dev-server package can be installed with npm:

`npm install --save-dev webpack-dev-server`

Also, we need to edit the dev script in the package.json file so that it uses webpack- dev-server instead of Webpack. This way, you don't have to recompile and reopen the bundle in the browser after every code change:

{
  "name": "chapter-1",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "start": "webpack serve --mode=development",
    "build": "webpack --mode=production"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

The preceding configuration replaces Webpack in the start scripts with webpack-dev-server, which runs Webpack in development mode. This will create a local development server that runs the application and ensures that Webpack is restarted every time an update is made to any of your project files.

To start the local development server, just enter the following command in the terminal:

`npm start`

This will cause the local development server to be active at http://localhost:8080/ and refresh every time we make an update to any file in our project.

Now, we have created the basic development environment for our React application, which you can further develop and structure when you start building your application.

Conclusion

In this blog post, we learned how to set up a React project with Webpack and Babel. We also learned how to render a React component in the browser. I always like to learn a technology by building something with it from scratch before jumping into a framework like Next.js or Remix. This helps me understand the fundamentals of the technology and how it works.

This blog post is extracted from my book React Projects, available on Packt and Amazon.

I hope you learned some new things about React! Any feedback? Let me know by connecting to me on Twitter. Or leave a comment on my YouTube channel.

This post was originally published on hackteam.io. Reposted automatically with Reposted.io. A free tool to repost your content across all blogging platforms.

Why Do Developers Love GraphQL?

Roy Derks — Wed, 21 Dec 2022 10:25:02 +0000

GraphQL has changed how developers interact with data in their applications and has often been called the successor to REST. REST APIs have been the standard for a long time but lack certain features to make consuming them easy. GraphQL on the other is hand was created to make the lifes of developers easy. So why do developers love GraphQL so much? In this blog post, I'll give you three reasons why!

Click the image below to watch the YouTube video version of this blog post:

What is GraphQL?

If you haven't heard of GraphQL, it's a query language for APIs. It was created by Facebook in 2012 and open-sourced in 2015. GraphQL allows you to query data from an API in a structured way. It's a great alternative to REST, the most popular way to create APIs today.

I started using GraphQL in 2016 during a hackathon in Berlin and have been using it ever since. I'm using GraphQL in all my projects where I need access to an API, and I have been creating content about GraphQL for years. I've created a GraphQL book, Fullstack GraphQL, and multiple GraphQL tutorials on my YouTube channel.

Why do developers love GraphQL?

One single endpoint for all your data

One of the biggest advantages of GraphQL is that you only need one single endpoint to query all your data. In REST, you need multiple endpoints to query different data. Generally speaking, every data entity (like a database table) in REST API will have its own endpoint. For example, if you want to get a list of posts and a specific from a CMS API, you need to send requests to two endpoints:

GET /posts (list of posts)
GET /posts/1 (specific post)

In GraphQL, you can request both the list of posts and the specific post in one single query:

query {
  posts {
    id
    title
  }
  post(id: 1) {
    id
    title
  }
}

GraphQL would execute this query against a single endpoint, which is much easier to manage. You don't need to worry about creating multiple endpoints, and you don't need to worry about versioning them.

No more over- and under-fetching

In REST, you sometimes fetch more than the data you actually need, and this is called over-fetching. In the example from the previous section, you're fetching the list of posts from a REST API, and let's say we want to display them on an overview page. Therefore we need the id and title of each post, but this REST API is returning a lot more data than you need. Not only is it returning the id and title of the post, but also the body and userId. Getting more data than you need wastes bandwidth and processing power.

[
  {
    "id": 1,
    "userId": 1,
    "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
    "body": "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto"
  },
  {
    "id": 2,
    "userId": 1,
    "title": "qui est esse",
    "body": "est rerum tempore vitae\nsequi sint nihil reprehenderit dolor beatae ea dolores neque\nfugiat blanditiis voluptate porro vel nihil molestiae ut reiciendis\nqui aperiam non debitis possimus qui neque nisi nulla"
  }
  // Other posts...
]

In GraphQL, you can request exactly the data you need by specifying the fields you want to get in your query:

query {
  posts {
    id
    title
  }
}

Opposite to over-fetching, there's also under-fetching. Sometimes need to make multiple requests to REST API endpoints to get all the data you need. This is called under-fetching because you're not getting all the data you need at once. Let's have another look at the example from the previous section. Instead of just getting a specific post on a detail page, we also want the comments for this post. In REST, you need to make two requests as a different endpoint than the post returns the comments:

GET /posts/1 (specific post)
GET /posts/1/comments (comments for specific post)

In GraphQL, you can request exactly the data you need even when the data is spread across multiple entities. You can request the post and the comments in one single query:

{
  post(id: 1) {
    id
    title
    comments {
      id
      name
    }
  }
}

This query would return the post and comments in one single response, which is much easier to manage in your application and takes fewer data to transfer. Especially as you prevent over-fetching in this example and only receive the data you're using on your detail page.

GraphQL is self-documenting

Well, at least partially...

In REST, you need to document your API. This is a lot of work, and it's easy to forget to update the documentation when you make changes to your API. In GraphQL, you don't need to document your API, as the documentation is generated automatically. You can use the GraphiQL tool to explore your GraphQL API and see all the available queries and mutations. You can also see the fields you can request for each query and mutation. This is much easier to manage than documenting your API manually.

GraphQL APIs have built-in documentation, which can be generated from its GraphQL schema. Every GraphQL API has a schema for defining all the operations and data types. The schema is used to validate the queries and mutations you send to the API. You can use the GraphiQL tool (read more in this blog post) to explore your GraphQL API and see all the available queries and mutations. You can also see the fields you can request for each query and mutation. But also to generate the documentation, making using a GraphQL API a lot easier to manage than having to document your REST API manually.

Conclusion

There are many reasons developers love GraphQL, especially frontend developers. GraphQL is easier to manage than REST and is much easier to use in your application. You can use GraphQL in your frontend application to fetch all the data you need in one single request. It prevents over- and under-fetching, plus it's self-documenting.

I'd love to hear your thoughts on this topic. Do you love GraphQL? Why? Let me know by connecting to me on Twitter. Or leave a comment on my YouTube channel.

This post was originally published on hackteam.io. Reposted automatically with Reposted.io. A free tool to repost your content across all blogging platforms.

Exploring GraphiQL 2 Updates and New Features

Roy Derks — Mon, 12 Dec 2022 14:03:53 +0000

GraphiQL is a popular tool for GraphQL developers. It is a web-based IDE for GraphQL that lets you explore a GraphQL API. It's a great tool for developers to test their GraphQL queries and mutations, and find out what the schema of a GraphQL API looks like. For many developers it's the first tool they use to learn GraphQL.

But for many years, GraphiQL hasn't had a UI update. And it's been a while since it's been updated. But now since few months, GraphiQL 2 is here. It's a complete new version of GraphiQL with a new UI and a lot of new features. In this blog post, I'll explore the new features of GraphiQL 2 and show you how to use them.

Click the image below to watch the YouTube video version of this blog post:

Little bit of history

GraphiQL is a tool that was created to help developers explore GraphQL APIs, maintained by the GraphQL Foundation. But when GraphiQL became more and more popular, developers started to create additional GraphQL IDEs. A good example of this was GraphQL Playground, which quickly became the most popular GraphQL IDE. It was loosely based on GraphiQL, but had more features and a better UI.

After GraphQL Playground became part of the GraphQL Foundation, the need for having just one GraphQL IDE became more important. So the GraphQL Foundation decided to merge GraphiQL and GraphQL Playground into one tool. GraphiQL 1 relied on major tech debt and multiple dependencies that were outdated and hard to maintain. With the merge of GraphiQL and GraphQL Playground, the GraphQL Foundation decided to create a new version of GraphiQL, which is now called GraphiQL 2. The design and creation of GraphiQL 2 was all documented in Github.

First look at GraphiQL 2

For me personally, this is one of the biggest releases in GraphQL world this year. As for too many years we had to work with GraphiQL 1, which is looking like it's coming from the Stone Age. With GraphiQL 2, the theme behind GraphiQL has really outdone themselves as they've created a better version of GraphiQL that looks like it's actually from modern day.

As you can see in the above screenshot of GraphiQL 2, it looks way more modern than GraphiQL 1. It has a dark mode, a light mode, and a system mode. It has a new UI, and a lot of new features. Compared to GraphiQL 1, it's looks like a complete new version of GraphiQL with the same feel.

Let's look at the same page in GraphiQL 1:

This screenshot is from GraphiQL 1 and as you can see it just feels outdated, from the color scheme to the used font. As oppposed to GraphiQL 2 there's no way to change the theme from the UI itself.

Most features from GraphiQL 1 are also available in GraphiQL 2, such as the docs page, history, and the ability to pass variables and headers. But GraphiQL 2 has a lot of new features as well, which I'll explore in the next section.

New features in GraphiQL 2

I already mentioned GraphiQL 2 has a dark mode, which is a great addition and something most modern developer tools have today. OFcourse, you cna also switch to system mode, which will use the system theme so it changes to dark when sun sets.

But next to dark mode the biggest feature update is the tabs to switch between multiple queries. This is a great addition as it allows you to have multiple queries open at the same time. This is something I've been missing in GraphiQL 1 for a long time.

Having tabs is especially useful when you have a query to get a list of results and a query to get a specific item. You can now have both open at the same time and switch between them.

Conclusion

GraphiQL 2 is a great update to GraphiQL 1. It has a new UI, a lot of new features, and a dark mode. It's still the easiest tool to use for GraphQL developers to explore a GraphQL API. I'm really excited to see what the future of GraphiQL 2 will bring, especially as GraphiQL 2 is now maintained more activley than GraphiQL 1 used to be.

P.S. Follow Roy Derks on Twitter for more React, GraphQL and TypeScript tips & tricks. And subscribe to my YouTube channel for React, GraphQL and TypeScript tutorials.

This post was originally published on hackteam.io. Reposted automatically with Reposted.io. A free tool to repost your content across all blogging platforms.

DEV Community: Roy Derks

Build Tool Calling Agents with LangGraph and IBM watsonx.ai Flows Engine

Tool Calling & Agents

Build a Tool Calling Agent

Prerequisites

Step 1: Install the wxflows CLI

Step 2: Set up a watsonx.ai Flows Engine project

Step 3: Use LangGraph to create an agent

Step 4: Use the agent in a chat application

Summary and Next Steps

Build AI Applications With LangChain, JavaScript, and React

Setting up a React app with Vite

Installing and configuring LangChain

Connecting to OpenAI API

Building a query function with LangChain

Handling form submission to interface with the AI

What's next?

GraphQL IDEs: GraphiQL vs Altair

Introduction to GraphQL IDEs

GraphiQL

Altair

Comparing GraphiQL and Altair

How to Build Angular Search Functionality with GraphQL?

Introduction

Prerequisites

Setting up a new Angular project

Creating a GraphQL API with StepZen

Adding Apollo Client to our Angular application

Fetching data with Apollo Client

Adding search functionality

Conclusion

Building a JWT Login Flow with Auth0, Next.js, and StepZen

What does the login flow look like?

Setting up Auth0

Creating a Next.js application

or if you're using yarn

or if you're using yarn

Creating a StepZen GraphQL API

Add the JWKS endpoint

Set the policies

Your StepZen endpoint

Fetching user information in the Next.js application

Next Steps?

Comparing GraphQL Directives: Type System Vs. Executable Directive Locations

Remind me, what is a GraphQL Directive?

Built-in Directives

Custom Directives

Type System Directive Locations vs. Executable Directive Locations

Directives that apply to the type system

Directives that apply to execution

Summary

Authenticating GraphQL APIs with OAuth 2.0

What is OAuth 2.0?

Authorization Code Flow (using JWT)

Client Credentials Flow

Using StepZen to Manage Authentication

Implement Authorization Code Flow (using JWT)

Implement Client Credentials Flow

What's next?

Learn React in 5 minutes

What is React?

JavaScript

Components

Data flows

State

Virtual DOM

Ecosystem

Building Projects

Keep learning

Bootstrap Is The Easiest Way To Style React Apps in 2023

Why use Bootstrap?

Installing Bootstrap

Using Bootstrap components

Bootstrap utilities

Conclusion

Create a React Project From Scratch Without any Framework

Setting up a new project

Adding Webpack to the project

Configuring Webpack for React

Rendering React components

Step 1: Install the `wxflows` CLI