Forem: Abhik Banerjee

Routing the Easy Way in Go

Abhik Banerjee — Wed, 06 Mar 2024 19:27:36 +0000

I have come across many developers who feel overwhelmed when trying to design a backend server in a language or a framework outside their comfort zone. Considering I was a fresher once who had similar problems, it is somewhat easy to empathize. One of my mentors Chirag Nayyar always said that if your fundamentals are clear, you will never be fazed. It is a belief I have come to share and it is precisely because of that belief that I will discuss the routing in web development when it comes to the backend.
We will be continuing with our little mini-project of Passwordless Auth in Go. In this article, we will discuss the essence of routing and then frame our routes and controller in Golang using Gorilla Mux. Before we start, I guess a few words of wisdom.

We will be using the utils package in this article. This Go package was discussed in the 3rd article.

and

We will be using the data package in this article. This Go package was discussed in the 4th article.

The code is hosted in the following GitHub Repo:
Embed GitHub Repo.

abhik-99 / Passwordless-Login-in-Go

This repo contains code for my article series on creating a Passwordless Login system in Go from scratch.

Fair Warning: This article will be a bit long.

Crash Course into Routing

So, before we had the whole REST paradigm, we used SOAP. At the time of writing, REST is the most widely accepted and used paradigm with a portion of GraphQL and a minor portion of tech arising out of HTTP 2.1.

REST comes with a few “verbs”. This is meant to convey meta-information about the HTTP request. These verbs are GET, POST, PUT, PATCH, and DELETE (with a few others that are not that often used by web developers most of the time). These verbs are attached as METHOD on the HTTP request. GET means you want to fetch some data from the web server. POST means you want to create a resource on the server. PUT and PATCH are for updating the data stored on the server. PUT is when you are sending the whole of the data object while PATCH is when you want to send only the portion of the data object on the server which needs a change. DELETE is obviously for deleting a resource on the server.

We also use a series of codes as responses from the server to denote the status of the request made to the server. These are registered with an entity called the Internet Assigned Numbers Authority. You can browse through the complete list here.

Now, there are other information encoded in the URL itself. The first one is the URL parameter. These are essentially identifiers that come between the front slashes. Next are the URL queries. These come after the parameters. They come in a key:value pair separated by “=” and are written after a “?” in the URL. For example, in the URL http://www.example.com/items/1?color=grey&size=6&unit=45” we have 1 as the URL parameter while color, size and unit are URL queries. These URL queries are separated by an &.

When we place a request to a web server, regardless of the tech stack used behind the scenes, the flow remains the same. The web server intercepts the request -> the request goes through a middleware or a series of middleware -> request is at last handled by a handler function or a controller.

What is a middleware? A middleware is a piece of code that runs after a process is started but before the actual handler for the process is used. It is an easy way to encapsulate logic which might be common in a group of functions. All frameworks in all languages will have a way to denote that middleware has completed execution and the request can be passed to the next middleware in the series or to the handler function. This comes in the form of a ”next” function. If the middleware does not complete successfully, it is meant to send back an error response to the client.

This more or less covers everything you need to know as a web developer to get down and dirty with development.

The `routes` package

Refer back to the 2nd article in the series for the file structure. We will place our routes in the routes package. Routes are separated by their concern. In our case, we have 2 concerns – authentication and user profile fetching. So, we will have 2 Go files in the package – auth_routes.go and user_routes.go in the project.

Authentication Routes

package routes

import (
    "github.com/abhik-99/passwordless-login/pkg/controllers"

    "github.com/gorilla/mux"
)

func RegisterAuthRoutes(r *mux.Router) {

    r.HandleFunc("/signup", controllers.Signup).Methods("POST")

    //This initiates the Email-based authentication,
    r.HandleFunc("/email/{emailId}", controllers.OTPViaEmail).Methods("GET")
    //the Email & OTP can be passed via REQ Body
    r.HandleFunc("/email", controllers.LoginViaEmail).Methods("POST")

    //This initiates the Phone-based authentication,
    r.HandleFunc("/phone/{phoneNo}", controllers.OTPViaPhone).Methods("GET")
    // the Phone number & OTP can be passed via REQ Body
    r.HandleFunc("/phone", controllers.LoginViaPhone).Methods("POST")

}

Given above is the code we will put inside the auth_routes.go file. As you can see, we are defining a function in the above code called RegisterAuthRoutes(). This function takes in a reference to a Gorilla Mux Router (or Subrouter) and then attaches to its controllers (also called handler functions) for each of the routes.
In our main.go we had created an authentication subrouter using Gorilla Mux. The subrouter was defined in such a way that any route that is defined upon it will have the /auth prefix. This allows for easy grouping of routes based on concern as discussed in previous articles in this series.

The HandleFunc() method on the subrouter takes in the path and the controller for that path. We also define the HTTP Method which needs to be used for the route for the controller to be invoked as shown in the code above. In our case, the authentication paths are as follows:

Route Name	HTTP Method	Controller Name	Concern
`/signup`	POST	`Signup`	Creates a User Profile
`/email/{emailId}`	GET	`OTPViaEmail`	Initiates Auth by sending OTP to email if the user with that email has signed up prior.
`/email`	POST	`LoginViaEmail`	Takes in the OTP and email and then returns JWT token if auth is successful.
`/phone/{phoneNo}`	GET	`OTPViaPhone`	Initiates Auth by sending OTP to phone if the user with that mobile has signed up prior.
`/phone`	POST	`LoginViaPhone`	Takes in the OTP and phone and then returns JWT token if auth is successful.

User Routes

Next, we have the user_routes.go file. This is where we will define all the routes relating to user action. The code below shows the contents of the user_routes.go file.

package routes

import (
    "github.com/abhik-99/passwordless-login/pkg/controllers"
    "github.com/abhik-99/passwordless-login/pkg/middleware"

    "github.com/gorilla/mux"
)

// Protected Routes
func RegisterUserRoutes(r *mux.Router) {
    r.Use(middleware.ValidateTokenMiddleware)
    r.HandleFunc("", controllers.GetPublicUsers).Methods("GET")
    r.HandleFunc("/{id}", controllers.GetPublicUserProfile).Methods("GET")
    r.HandleFunc("/profile", controllers.GetUserProfile).Methods("GET")
}

Like the previous file, we have a function that takes in a reference to a Gorilla Mux router (or subrouter) and then registers a few routes on it. However, these routes are slightly different from the above ones. Can you guess how? There are two points to consider here:

Firstly, in line number 12, we have also attached a middleware. We say that every time a request is made to these routes, run the ValidateTokenMiddleware() middleware function before actually passing the request to the handler functions. We will discuss what this middle does in the section below.
There is a route without any name at line 13. This essentially means that if the subrouter has a prefix of /user then the Router will consider the controller mentioned for any request coming to only the prefix /user. In our case, whenever someone makes a GET request to /user then the GetPublicUser handler function is used to resolve it.

We have two other routes that we attach to the subrouter passed to the RegisterUserRoutes() function. These are:

Route Name	HTTP Method	Controller Name	Concern
`/`	GET	`GetPublicUsers`	Fetches all the public profiles of users.
`/{id}`	GET	`GetPublicUserProfile`	Fetches a specific user profile whose ID is passed in as a parameter.
`/profile`	GET	`GetUserProfile`	Fetches the user profile of the user logged in (basically who JWT is passed in the auth header).

The `controllers` package

The controllers package is where the code for the handler functions will be kept. Keeping in line with our convention of dividing the files into packages based on their concern, we will be segregating the controllers into two files - auth_controllers.go and user_controllers.go. Needless to say, the former will host the code for authentication routes while the latter will have the code for the user-oriented protected routes

Thanks to our discussions of the utils package in the previous articles, the explanation in this section can be kept brief. Most of the heavy work is being done by the authentication-related route handlers so we will focus on them with a brief discussion on one of the more important user routes.

Authentication-oriented Controllers

The following is the code in the auth_controllers.go file.

package controllers

import (
    "fmt"
    "net/http"
    "net/mail"

    "github.com/abhik-99/passwordless-login/pkg/data"
    "github.com/abhik-99/passwordless-login/pkg/utils"
    "github.com/gorilla/mux"
)

func Signup(w http.ResponseWriter, r *http.Request) {
    var newUser data.CreateUserDTO
    err := utils.DecodeJSONRequest(r, &newUser)
    if err != nil {
        utils.EncodeJSONResponse(w, http.StatusBadRequest, struct {
            utils.GenericJsonResponseDTO
            Err string `json:"err"`
        }{
            GenericJsonResponseDTO: utils.GenericJsonResponseDTO{
                Message: "Invalid Request Body",
            },
            Err: err.Error(),
        })
        return
    }
    if _, err := data.CreateNewUser(newUser); err != nil {
        http.Error(w, "Error Occurred while Creating user", http.StatusInternalServerError)
        return
    } else {
        utils.EncodeJSONResponse(w, http.StatusOK, utils.GenericJsonResponseDTO{Message: "User Created Successfully"})
    }

}

func OTPViaEmail(w http.ResponseWriter, r *http.Request) {
    params := mux.Vars(r)
    if _, err := mail.ParseAddress(params["emailId"]); err != nil {
        http.Error(w, "Invalid Email", http.StatusBadRequest)
        return
    } else {
        if _, userID, lookUpErr := data.UserLookupViaEmail(params["emailId"]); lookUpErr != nil {
            http.Error(w, "User does not exist", http.StatusUnauthorized)
            return
        } else {
            otp, err := utils.OTPGenerator()
            if err != nil {
                http.Error(w, "Error Occurred while generating user OTP", http.StatusInternalServerError)
                fmt.Println("[ERROR] ", err)
                return
            }
            a := data.Auth{UserId: userID, Otp: otp}
            if err := a.SetOTPForUser(); err != nil {
                http.Error(w, "Error Occurred while setting user OTP", http.StatusInternalServerError)
                fmt.Println("[ERROR] ", err)
                return
            }
            if err := utils.SendOTPMail(params["emailId"], otp); err != nil {
                http.Error(w, "Error Occurred while setting user OTP", http.StatusInternalServerError)
                fmt.Println("[ERROR] ", err)
                return
            }

            utils.EncodeJSONResponse(w, http.StatusOK, utils.GenericJsonResponseDTO{Message: "User OTP sent"})

        }
    }
}

func OTPViaPhone(w http.ResponseWriter, r *http.Request) {
    params := mux.Vars(r)
    phoneNo := params["phoneNo"]
    if !utils.IsValidPhoneNumber(phoneNo) {
        http.Error(w, "Invalid Phone number", http.StatusBadRequest)
        return
    } else {
        if result, userID, lookUpErr := data.UserLookupViaPhone(phoneNo); lookUpErr != nil {
            http.Error(w, "Error Ocurred while Lookup", http.StatusInternalServerError)
            fmt.Println("[ERROR] ", lookUpErr)
            return
        } else if !result {
            http.Error(w, "User Not Found", http.StatusNotFound)
            return
        } else {
            otp, err := utils.OTPGenerator()
            if err != nil {
                http.Error(w, "Error Occurred while generating user OTP", http.StatusInternalServerError)
                fmt.Println("[ERROR] ", err)
                return
            }
            a := data.Auth{UserId: userID, Otp: otp}
            if err := a.SetOTPForUser(); err != nil {
                http.Error(w, "Error Occurred while setting user OTP", http.StatusInternalServerError)
                fmt.Println("[ERROR] ", err)
                return
            }
            if err := utils.SendOTPSms(phoneNo, otp); err != nil {
                http.Error(w, "Error Occurred while setting user OTP", http.StatusInternalServerError)
                fmt.Println("[ERROR] ", err)
                return
            }

            utils.EncodeJSONResponse(w, http.StatusOK, utils.GenericJsonResponseDTO{Message: "User OTP sent"})

        }
    }
}

func LoginViaEmail(w http.ResponseWriter, r *http.Request) {
    var dto data.LoginWithEmailDTO
    err := utils.DecodeJSONRequest(r, &dto)
    if err != nil {
        utils.EncodeJSONResponse(w, http.StatusBadRequest, struct {
            utils.GenericJsonResponseDTO
            Err string `json:"err"`
        }{
            GenericJsonResponseDTO: utils.GenericJsonResponseDTO{
                Message: "Invalid Request Body",
            },
            Err: err.Error(),
        })
        return
    }
    result, userID, lookUpErr := data.UserLookupViaEmail(dto.Email)

    if !result {
        http.Error(w, "User Does not Exist", http.StatusNotFound)
        return
    }
    if lookUpErr != nil {
        http.Error(w, "Error Ocurred while Lookup", http.StatusInternalServerError)
        fmt.Println("[ERROR] ", lookUpErr)
        return
    }
    a := data.Auth{UserId: userID, Otp: dto.Otp}
    if result, err := a.CheckOTP(); err != nil {
        http.Error(w, "Error Ocurred while verifying OTP", http.StatusInternalServerError)
        fmt.Println("[ERROR] ", err)
        return
    } else if !result {
        http.Error(w, "OTP Does not Match", http.StatusBadRequest)
        return
    }

    if result, err := utils.GenerateJWT(userID); err != nil {
        http.Error(w, "Error Occured during access token generation", http.StatusBadRequest)
        fmt.Println("[ERROR] ", err)
        return
    } else {
        utils.EncodeJSONResponse(w, http.StatusOK, data.AccessTokenDTO{AccessToken: result})
    }

}

func LoginViaPhone(w http.ResponseWriter, r *http.Request) {
    var dto data.LoginWithPhoneDTO
    err := utils.DecodeJSONRequest(r, &dto)
    if err != nil {
        utils.EncodeJSONResponse(w, http.StatusBadRequest, struct {
            utils.GenericJsonResponseDTO
            Err string `json:"err"`
        }{
            GenericJsonResponseDTO: utils.GenericJsonResponseDTO{
                Message: "Invalid Request Body",
            },
            Err: err.Error(),
        })
        return
    }
    _, userID, lookUpErr := data.UserLookupViaPhone(dto.Phone)

    if lookUpErr != nil {
        http.Error(w, "User Does not Exist", http.StatusUnauthorized)
        return
    }
    a := data.Auth{UserId: userID, Otp: dto.Otp}
    if result, err := a.CheckOTP(); err != nil {
        http.Error(w, "Error Ocurred while verifying OTP", http.StatusInternalServerError)
        fmt.Println("[ERROR] ", err)
        return
    } else if !result {
        http.Error(w, "OTP Does not Match", http.StatusBadRequest)
        return
    }

    if result, err := utils.GenerateJWT(userID); err != nil {
        http.Error(w, "Error Occured during access token generation", http.StatusBadRequest)
        fmt.Println("[ERROR] ", err)
        return
    } else {
        utils.EncodeJSONResponse(w, http.StatusOK, data.AccessTokenDTO{AccessToken: result})
    }
}

Let’s discuss the Signup() function first. In lines 14 and 15, we try to decode the request body into the CreateUserDTO. This simultaneously validates it. One of the upsides of using Go in backend web development as opposed to Express is that this validation comes super easy thanks to the Validator package. In case the request body cannot be decoded or unmarshaled into the DTO, we that the user is trying to be smart with us.

We check for any error during the JSON unmarshalling phase at line 16. Between lines 17 and 25, a few interesting things happen. First off, we use the EncodeJSONResponse() function to send in an HTTP Bad Request response to the client. We define an anonymous struct between lines 17 and 19 and then simultaneously initialize it in the next lines. Pay close attention to how we embed fields from GenericJsonResponseDTO. This syntax allows us to embed fields from other structs into new structs easily in Go. Notice the way we initialize it between lines 21 and 24.

Even though when initializing embedded struct fields in Go in such a way we need to initialize the embedded struct separately when encoded, the result has all the fields at the same level in a JSON and we won’t find a JSON property called GenericJsonResponseDTO in the response. Instead, we will find the message field at the same level as err. If there are no errors, we create the user and send back the successful response.

Next, we have the OTPViaEmail() function. Refer to the previous section to see the route it handles. You will notice a different syntax. We have used curly braces or second brackets. This signifies a route parameter. The name of the route parameter is defined within the curly braces. To retrieve the URL parameter, we need to mux.Vars() in Gorilla Mux. This returns a map. The value of the URL parameter will be stored with the name as the key in this map.

We retrieve the email from the URL parameter map and then verify if it is a valid email using the ParseAddress() of the mail module. The happy path here consists of looking up if any user with the email exists & retrieving the MongoDB ID of the collection at line 43. We then generate a pseudo-random OTP using the OTPGenerator() utility function, set the OTP in our Redis DB with the user ID as the key at line 54 with the SetOTPForUser() which we defined on the Auth struct (being used here as a model), send the mail at line 59 with the SendOTPMail() utility function, and tell the client that the OTP has been sent to the user’s email at line 65.

Let’s discuss LoginViaEmail(). It is the next logical step in the flow. In this function, we first decode the request body to the LoginWithEmailDTO struct having the Email and Otp fields. Again, the happy flow here will then consist of looking up a user with that Email at line 125 (kind of redundant but acts as another flimsy line of defence), retrieving the User’s MongoDB ID, and then verifying the OTP by querying our Redis DB at line 137 with the CheckOTP() function defined on the Auth data model struct. If the OTP checks out then at line 146 we generate a JWT for our user using the GenerateJWT() utility function. The JWT at line 151 by marshalling it using the AccessTokenDTO struct.

There are two other functions called OTPViaPhone() and LoginViaPhone() in the same file in the GitHub Repo. These have similar steps albeit with the user’s phone number.

User-oriented Controllers

Next, let’s head over to the user_controller.go file. We will discuss the GetUserProfile() controller here. In almost all web development scenarios, you will need one way or another to retrieve the authenticated user’s profile. That’s what we are doing in the code below.

package controllers

import (
    "log"
    "net/http"

    "github.com/abhik-99/passwordless-login/pkg/data"
    "github.com/abhik-99/passwordless-login/pkg/utils"
    "github.com/gorilla/mux"
)

func GetPublicUsers(w http.ResponseWriter, r *http.Request) {
    if userProfiles, err := data.GetAllPublicUserProfiles(); err != nil {
        http.Error(w, "Error Occurred while fetching users", http.StatusInternalServerError)
        log.Println("ERROR", err)
    } else {
        utils.EncodeJSONResponse(w, http.StatusOK, userProfiles)
    }
}

func GetPublicUserProfile(w http.ResponseWriter, r *http.Request) {
    params := mux.Vars(r)
    id := params["id"]
    if !utils.IsValidObjectID(id) {
        http.Error(w, "Invalid User ID", http.StatusBadRequest)
        return
    }
    user, err := data.GetUserProfileById(id)
    if err != nil {
        http.Error(w, "Invalid User ID", http.StatusBadRequest)
        log.Println("ERROR while user profile query", err)
        return
    }
    utils.EncodeJSONResponse(w, http.StatusOK, user)

}

func GetUserProfile(w http.ResponseWriter, r *http.Request) {
    userID := r.Header.Get("user")
    user, err := data.GetUserProfileById(userID)
    if err != nil {
        http.Error(w, "Invalid User ID", http.StatusBadRequest)
        log.Println("ERROR while user profile query", err)
        return
    }
    utils.EncodeJSONResponse(w, http.StatusOK, user)

}

At line 39, we have the get the MongoDB Collection ID for the authenticated user by retrieving the value of the user header. But where did we define any step for this? Where is it coming from? That’s going to be revealed in the next section. We then make a simple User ID-based lookup in our MongoDB user collection at line 40 and return the full user profile at line 46.

The other functions are simple so we will skip discussing them as well. But do glance over the code and try to understand what they do.

The `middlewares` package

Lastly, we arrive at the middlewares package. In our case, we only have one middleware. This we will place in the auth_middleware.go file. The code for the file is given below. Discussion follows.

package middleware

import (
    "net/http"
    "strings"

    "github.com/abhik-99/passwordless-login/pkg/utils"
)

func ValidateTokenMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {

        tokenString := r.Header.Get("Authorization")
        if tokenString == "" {
            http.Error(w, "Unauthorized", http.StatusUnauthorized)
            return
        }

        splitToken := strings.Split(tokenString, "Bearer ")
        if len(splitToken) != 2 {
            http.Error(w, "Invalid token format", http.StatusUnauthorized)
            return
        }

        tokenString = splitToken[1]

        tokenClaims, err := utils.ValidateJWT(tokenString)

        if err != nil {
            http.Error(w, "Unauthorized", http.StatusUnauthorized)
            return
        }
        userId, _ := tokenClaims.GetSubject()
        r.Header.Set("user", userId)

        next.ServeHTTP(w, r)
    })
}

Notice the special syntax of the middleware. Unlike the handler function, it does not take in a ResponseWriter and a reference to the Request. Instead, it takes in the “next” handler. As explained in an earlier section, this next function is invoked if the middleware has successfully completed the processing of the request.

Also, pay close attention to how the ValidateTokenMiddleware() returns a handler function in the form of a Golang closure. This is the syntax in Gorilla Mux in Go. In ExpressJS, you might need to follow such conventions. Inside the handler function, we split the auth header and then took the JWT. We check for its validity at line 27 with the ValidateJWT() utility. If the JWT is valid, then invoking the GetSubject() function on the returned claims will give us the user ID as that’s how we created the JWT in the first place.

At line 34 we mutate our HTTP request. Many new web developers miss this step, they might take an alternative approach. But we need to consider these two things:

Our HTTP request is like a car containing people (people being analogous to data) that passes through a pathway. This pathway is essentially the web server’s request-handling process up to the request handler function. So, it is not exposed to the outside world.
It will get discarded once the request is handled. So, we can easily use it as a carrier for some bytes of extra information to relieve us of extra computation. Here, setting the user header in the middleware helps us skip the JWT decoding step in the GetUserProfile handler function.

At last, the next.ServeHTTP(w, r) at line 36 passed this request to the next middleware/handler in the series or in our case, the router handler functions defined on the user route subrouter.

With this discussion, the whole mini-project discussion can be concluded as we have explored all the important aspects of it throughout 5 articles.

Conclusion

If you have stuck around till this part, then kudos to your patience and dedication. In this series, we explored the Go backend web development stack consisting of Gorilla Mux, MongoDB, and Redis by building a password-less authentication system in Go. While it is funny how the whole “passwordless” works in this paradigm of authentication, it is what it is. I guess I will go back to completing the Chainlink CCIP series which I had taken a hiatus from after this. So, until next time, keep building awesome things and WAGMI!

Modelling your Data Layer in Go

Abhik Banerjee — Tue, 27 Feb 2024 18:30:01 +0000

There are a few statements any Go dev would have heard like:

There is no perfect programming language.
Go is modular by design.
In Golang, pass-by-value is faster than the pass-by-reference.
Go is the perfect programming language

And so on…

In this article, we pick up the modelling aspect of our Go application. While we are trying to follow the MVC architecture, there are some Gopher quirks that we have observed previously. This article will show how those translate to coding when dealing with data models and DB business logic wrappers.

The `data` package

In our case, we will keep all the model-related data and data transfer objects (DTOs) inside the data package. This package will have 4 files as we will discuss below. This package is built on top of the config and utils packages which we discussed in the previous article.

User Profile Representation in Go

First, let’s have a look at the user_model.go file. This file contains the user model which we will store in our MongoDB collection. Between lines 12 and 18, we define the fields of our user profile. Our user will have an Id field which will be auto-generated by MongoDB. Unlike JS, JSON objects are not natively compatible with Go. Neither is MongoDB’s BSON. To facilitate interoperability, we need to tag the fields of our struct. The bson tag denotes what the struct field will be called in the MongoDB notation while the json tag says what the field will be called when the struct is marshaled into JSON.

package data

import (
    "github.com/abhik-99/passwordless-login/pkg/config"

    "go.mongodb.org/mongo-driver/bson"
    "go.mongodb.org/mongo-driver/bson/primitive"
    "go.mongodb.org/mongo-driver/mongo"
    "go.mongodb.org/mongo-driver/mongo/options"
)

type User struct {
    Id    primitive.ObjectID `bson:"_id" json:"id"`
    Pic   string             `bson:"profilePic" json:"profilePic"`
    Name  string             `bson:"name" json:"name"`
    Email string             `bson:"email" json:"email"`
    Phone string             `bson:"phone" json:"phone"`
}

var (
    userCollection = config.Db.Collection("user-collection")
    ctx            = config.MongoCtx
)

func CreateNewUser(user CreateUserDTO) (*mongo.InsertOneResult, error) {
    return userCollection.InsertOne(ctx, user)
}

func GetAllPublicUserProfiles() ([]PublicUserProfileDTO, error) {
    var users []PublicUserProfileDTO
    cursor, err := userCollection.Find(ctx, bson.M{})
    if err != nil {
        return users, err
    }

    if err = cursor.All(ctx, &users); err != nil {
        return users, nil
    } else {
        return users, err
    }
}

func GetUserProfileById(id string) (PublicFullUserProfileDTO, error) {
    var user PublicFullUserProfileDTO
    obId, err := primitive.ObjectIDFromHex(id)
    if err != nil {
        return user, err
    }

    err = userCollection.FindOne(ctx, bson.M{"_id": obId}).Decode(&user)
    return user, err
}

func UserLookupViaEmail(email string) (bool, string, error) {
    var result User
    filter := bson.D{{Key: "email", Value: email}}
    projection := bson.D{{Key: "_id", Value: 1}}

    if err := userCollection.FindOne(ctx, filter, options.FindOne().SetProjection(projection)).Decode(&result); err != nil {
        return false, "", err
    }
    return true, result.Id.Hex(), nil

}

func UserLookupViaPhone(phone string) (bool, string, error) {
    var result User
    filter := bson.D{{Key: "phone", Value: phone}}
    projection := bson.D{{Key: "secret", Value: 1}, {Key: "counter", Value: 1}, {Key: "_id", Value: 1}}

    if err := userCollection.FindOne(ctx, filter, options.FindOne().SetProjection(projection)).Decode(&result); err != nil {
        return false, "", err
    }
    return true, result.Id.Hex(), nil
}

func UpdateUserProfile(id string, u EditUserDTO) (*mongo.UpdateResult, error) {
    if obId, err := primitive.ObjectIDFromHex(id); err != nil {
        update := bson.D{{Key: "$set", Value: u}}
        return userCollection.UpdateByID(ctx, obId, update)
    } else {
        return nil, err
    }
}

func DeleteUserProfile(id string) (*mongo.DeleteResult, error) {
    if obId, err := primitive.ObjectIDFromHex(id); err != nil {
        return userCollection.DeleteOne(ctx, bson.M{"_id": obId})
    } else {
        return nil, err
    }
}

Next, between lines 20 and 23, we import Db from the config package. We then create a reference to the user-collection MongoDB collection which we had created during the initialization phase and store that in the userCollection variable. The mongo context is also imported and stored in the ctx variable.

The first method we have is the CreateNewUser() function which takes in a user, inserts the data, and then returns the insertion result. It is a light wrapper around the InsertOne() function. After that, we have the GetAllPublicUserProfiles() function. This function queries all the users in the user-collection. However, it does not return all the fields of every collection. It returns only those fields that are present in the PublicUserProfileDTO struct (struct shown below). This ensures that only a subset of fields is returned.

// Inside of user_dto.go
type PublicUserProfileDTO struct {
    Id   primitive.ObjectID `bson:"_id" json:"id"`
    Pic  string             `bson:"profilePic" json:"profilePic"`
    Name string             `bson:"name" json:"name"`
}

Keep in mind that we are going to keep all the concerned DTOs in one file. This means that all DTOs concerned with the Mongo User collection are going inside user_dto.go file including the struct above. This limits the fields returned in the response.

But that is not the only way. You can just tell which fields to filter by and then which ones to return in the query itself. The GetUserProfileById() is not that special – it just takes in an ID and then returns the full user profile which matches the ID. The DTO for the Full user profile is shown below.

// Inside user_dto.go
type PublicFullUserProfileDTO struct {
    Id    primitive.ObjectID `bson:"_id" json:"id"`
    Pic   string             `bson:"profilePic" json:"profilePic"`
    Name  string             `bson:"name" json:"name"`
    Email string             `bson:"email" json:"email"`
    Phone string             `bson:"phone" json:"phone"`
}

The UserLookupViaEmail() is a bit special though. You can probably guess where it can be used. It takes in an email ID and then returns the ID of the user to whom that Email ID belongs. Pay close attention to line number 57. That is where we define which fields the query should return. This is another way to limit the number of fields returned in the response. We specify this projection in the options we pass to the FindOne() query.

Keep in mind that the ID which will be returned will not be a string. Invoking the Hex() function on the returned MongoDB ID will turn it into a string which we can return.

The UserLookupViaPhone() does something similar albeit with the phone number of a user. Since it is similar, we won’t be discussing it.

As for the other functions in the user_model.go file, they are just present for completion’s sake and provide a full range of CRUD functionality. We will forego discussing them since they are fairly easy to understand if you have understood the function we discussed thus far.

Authentication-related modeling in Go

Next, we have the auth_model.go. In this section, we will focus on modeling the data layer so that we can interact with the Redis instance and save & check OTPs. Unlike MongoDB, we won’t have a struct decorator here since Redis is a key-value DB. That being said, there needs to be some structure to the model so that we can use it in our project with ease. The code given below is what we will have in our auth_model.go file.

package data

import (
    "time"

    "github.com/abhik-99/passwordless-login/pkg/config"
)

type Auth struct {
    UserId string
    Otp    string
}

var (
    redisDb = config.Rdb
    rCtx    = config.RedisCtx
)

func (a *Auth) SetOTPForUser() error {
    return redisDb.Set(rCtx, a.UserId, a.Otp, 30*time.Minute).Err()
}

func (a *Auth) CheckOTP() (bool, error) {
    if storedOtp, err := redisDb.Get(rCtx, a.UserId).Result(); err != nil {
        return false, err
    } else {
        if storedOtp == a.Otp {
            return true, nil
        }
    }
    return false, nil
}

First, we define the Auth struct between lines 9 and 12. UserId field will be the key while the Otp will represent the corresponding value. As you might have guessed, we will map Mongo DB Object IDs to OTPs and store that in Redis. In lines 14 to 17 we import the Redis connection and context from config package which we defined in the previous article.

We follow a different pattern in this kind of modelling. Unlike the previous user model, we define the methods with the struct as a receiver. So, when we initialize an Auth struct in our project, we can call the SetOTPForUser() function to set an auto-expiring OTP in Redis using the .Set() function or we may invoke the CheckOTP() function to find if OTP exists and matches the value in Otp field of the Auth struct we initialized. In the latter case, if OTP does not exist, then we can also assume that 30 minutes have passed and so the OTP has expired.

Next, we have the DTOs as shown in the code below. We will place them in the auth_dto.go file. As can be seen below, we have 3 DTO structs defined. LoginWithEmailDTO is used to decode the POST request body when email and OTP are sent. LoginWithPhoneDTO has similar usage but with a phone number. While the AccessTokenDTO is used for encoding the JWT access token in the response on successful authentication.

package data

type LoginWithEmailDTO struct {
    Email string `json:"email" validate:"required,email"`
    Otp   string `json:"otp" validate:"required"`
}

type LoginWithPhoneDTO struct {
    Phone string `json:"phone" validate:"required,e164"`
    Otp   string `json:"otp" validate:"required"`
}

type AccessTokenDTO struct {
    AccessToken string `json:"access_token"`
}

This completes the modeling phase of the project. We now have config, utils, and data packages ready. So, we can proceed to the routes and controller packages where the crux of our business logic will be implemented. We will explore this in the next articles.

Conclusion

As is apparent from this article, Golang is pretty unopinionated when it comes to how one should arrange their files and which conventions to choose from.

This freedom comes with a downside that can lead to poorly constructed applications. Sometimes, it can even lead to overengineering which can just needlessly increase codebase complexity. The quality in such a case, largely depends on the developer’s coding practices and the conventions being followed by a project. These help reduce the chaos in the codebase.

In this article, we went over the data modelling aspect of our mini-project. Hope to see you in the next one. Until then, keep building awesome things and WAGMI!

Password-less Auth in Go – Hands-on Part 1

Abhik Banerjee — Sat, 24 Feb 2024 10:55:45 +0000

Picking up right where we left off, we will start with the packages before we come to the main package. This will mean taking a bottom-up approach to coding our Go server. So, without further ado…

Utility Package

Why are we choosing this one first? For the simple reason that the utils package in a Go project contains most of the independent code. Other packages typically use this package. In our utils folder inside pkg folder, we will create a utils.go which will look like the code below:

package utils

import (
    "crypto/rand"
    "encoding/json"
    "fmt"
    "log"
    "net/http"
    "os"
    "regexp"
    "time"

    "github.com/go-playground/validator/v10"
    "github.com/golang-jwt/jwt/v5"
    "github.com/joho/godotenv"
    "github.com/sendgrid/sendgrid-go"
    "github.com/sendgrid/sendgrid-go/helpers/mail"
    "github.com/twilio/twilio-go"
    api "github.com/twilio/twilio-go/rest/api/v2010"
    "go.mongodb.org/mongo-driver/bson/primitive"
)

var validate = validator.New()

type GenericJsonResponseDTO struct {
    Message string `json:"message"`
}

// DecodeJSONRequest decodes the JSON request body into the provided interface and validates it.
func DecodeJSONRequest(r *http.Request, v interface{}) error {
    err := json.NewDecoder(r.Body).Decode(v)
    if err != nil {
        return err
    }

    // Validate the decoded struct
    return validate.Struct(v)
}

// EncodeJSONResponse encodes the provided interface as JSON and writes it to the response writer.
func EncodeJSONResponse(w http.ResponseWriter, status int, v interface{}) error {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(status)
    return json.NewEncoder(w).Encode(v)
}

func GetENV(name string) string {
    err := godotenv.Load(".env.local")
    if err != nil {
        log.Fatal("ERROR while loading the env file")
        log.Fatal(err)
    }
    return os.Getenv(name)
}

func IsValidPhoneNumber(phoneNo string) bool {
    e164Regex := `^\+[1-9]\d{1,14}$`
    re := regexp.MustCompile(e164Regex)

    return re.Find([]byte(phoneNo)) != nil
}

func GenerateJWT(id string) (string, error) {
    claims := jwt.RegisteredClaims{
        // Also fixed dates can be used for the NumericDate
        ExpiresAt: jwt.NewNumericDate(time.Now().Add(time.Hour * 2)),
        Issuer:    GetENV("JWT_ISSUER"),
        Subject:   id,
    }
    token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
    return token.SignedString([]byte(GetENV("JWT_SECRET")))
}

func ValidateJWT(tokenString string) (jwt.MapClaims, error) {
    token, err := jwt.Parse(tokenString, func(token *jwt.Token) (interface{}, error) {

        if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
            return nil, fmt.Errorf("Invalid Token Signing Method: %v", token.Header["alg"])
        }

        return []byte(GetENV("JWT_SECRET")), nil
    })
    if err != nil {
        return nil, err
    }

    if !token.Valid {
        return nil, fmt.Errorf("Invalid Token")
    }
    if claims, ok := token.Claims.(jwt.MapClaims); ok {
        return claims, nil
    } else {
        return nil, fmt.Errorf("Invalid Token Claim")
    }

}

func OTPGenerator() (string, error) {
    const otpChars = "0123456789"
    buffer := make([]byte, 8)
    _, err := rand.Read(buffer)
    if err != nil {
        return "", err
    }

    otpCharsLength := len(otpChars)
    for i := 0; i < 8; i++ {
        buffer[i] = otpChars[int(buffer[i])%otpCharsLength]
    }

    return string(buffer), nil
}

func SendOTPMail(receipientEmail string, otp string) error {
    from := mail.NewEmail(GetENV("SENDER_NAME"), GetENV("SENDER_EMAIL")) // Change to your verified sender
    subject := "Your Login OTP"
    to := mail.NewEmail(receipientEmail, receipientEmail)
    plainTextContent := fmt.Sprintf("Your OTP is %s", otp)
    htmlContent := fmt.Sprintf("Your OTP is <strong>%s</string>", otp)
    message := mail.NewSingleEmail(from, subject, to, plainTextContent, htmlContent)
    client := sendgrid.NewSendClient(os.Getenv("SENDGRID_API_KEY"))

    if _, err := client.Send(message); err != nil {
        log.Println("[ERROR]", err)
        return err
    }
    return nil

}

func SendOTPSms(receipientNo string, otp string) error {
    client := twilio.NewRestClient()

    params := &api.CreateMessageParams{}
    params.SetBody(fmt.Sprintf("Your OTP for Login is %s.", otp))
    params.SetFrom(GetENV("TWILLIO_PHONE_NO"))
    params.SetTo(receipientNo)

    _, err := client.Api.CreateMessage(params)
    return err
}

func IsValidObjectID(id string) bool {
    // Use a regular expression to check for the correct format (hexadecimal, 24 characters).
    objectIDRegex := regexp.MustCompile(`^[0-9a-fA-F]{24}$`)
    if !objectIDRegex.MatchString(id) {
        return false
    }

    // Use the MongoDB Go driver to try parsing the string as an ObjectID.
    _, err := primitive.ObjectIDFromHex(id)
    return err == nil
}

We will use the Go-Validator module to validate the type of our request body. We initialize the validator at line 23. The GenericJsonResponseDTO contains a generic structure of a response body. We can use it by itself or by embedding it inside another DTO as we will see later. The DecodeJSONRequest() function takes in the request and then unmarshals the request body into the struct passed in the second argument. Because we are going to use it with a variety of DTOs, we use the open-ended interface{} type in Go. This will allow us to pass any struct.

Next, we have the EncodeJSONRequest() function. This function takes the ResponseWriter interface that is used by a Go HTTP handler to construct an HTTP response, an HTTP response status code, and an interface (typically our response struct DTO) and marshals the data in the struct DTO to the response body.

The GetENV() function at line 47 is a wrapper to help us get any environment variable in a single line using the godotenv package. The point to note here is that we will pick our environment variables from the .env.local file as shown in line 48. After that we have a simple function which validates if a given string is a valid phone number using RegExp.

We need to generate JWT for access control. For this, we will use the golang-jwt module. At line 63, we create a wrapper called GenerateJWT() which takes the Mongo DB ID and then creates a JWT. We put the ID into the subject field of the JWT. This helps us in getting back the user ID easily using the getSubject() function of golang-jwt package. The GenerateJWT() function returns a signed JWT and an error. If everything is all right, then the error is nil.

At line 74, we have the ValidateJWT() function. This takes a JWT and then decodes the JWT using jwt.Parse(). The jwt.Parse() takes the encoded JWT token and a function that returns the secret used to sign the JWT. Inside the function, at line 77, we also check if the token is signed using the algorithm of our choice. If a token has expired, then even if the token is decoded for its data, it stands as invalid. At line 87, we check if the token is “valid”. We take out the JWT claims and return them with the error as nil at line 91. This completes the happy flow of JWT token validation.

The OTPGenerator() function returns a random 8-digit OTP for our use. It’s the SendOTPMail() that’s more interesting. It is a wrapper around SendGrid’s Mail SDK. It takes the email of the person to send the email to and the OTP. It then formats a mail and sends it to the recipient. It uses the API key obtained from SendGrid’s Dashboard. You also need to make sure that you have verified sender to complete this step.

You can start by having a Single Sender Verification done for SendGrid account by following the steps listed here.

The SendOTPSms() function uses Twilio’s REST Client for sending an SMS. This means you need to have a registered phone number beforehand on Twilio’s Dashboard. Note how, unlike the Mail SDK, this one does not need any API key. The helpers under the hood consume the API key you have kept in the .env file. It provides a better DevX.

Lastly, the IsValidObjectID() takes in a string and then returns if the string is a valid MongoDB object ID. This is used for request and JWT-related validation purposes. Because the subject of our JWT will have the user ID, this utility function will help us validate the JWT in more ways than one.

Config Package

The config package in our Golang web server, as you might have guessed, will contain the configuration files. More specifically, database connections and contexts will be exported from this file. But it won’t function quite the same way as you might have guessed if you are coming from another language. The code given below sums up what we will have in our app.go in our config package:

package config

import (
    "context"
    "fmt"
    "log"

    "github.com/abhik-99/passwordless-login/pkg/utils"

    "github.com/go-redis/redis/v8"
    "go.mongodb.org/mongo-driver/mongo"
    "go.mongodb.org/mongo-driver/mongo/options"
    "go.mongodb.org/mongo-driver/mongo/readpref"
)

var (
    Db       *mongo.Database
    MongoCtx context.Context

    client *mongo.Client

    Rdb      *redis.Client
    RedisCtx context.Context
)

func init() {
    MongoCtx = context.Background()
    client, err := mongo.Connect(MongoCtx, options.Client().ApplyURI(fmt.Sprintf("mongodb://%s:%s@localhost:27017/?retryWrites=true&w=majority", utils.GetENV("DBUSER"), utils.GetENV("DBPASS"))))
    if err != nil {
        // panic(err)
        log.Println(err)
    }

    if err = client.Ping(MongoCtx, readpref.Primary()); err == nil {
        log.Print("Connection to DB Successful")
    } else {
        log.Println("ERROR while pinging DB")
        log.Panic(err)
        return
    }

    Db = client.Database("passwordless-auth")
    Db.CreateCollection(MongoCtx, "user-collection")

    Rdb = redis.NewClient(&redis.Options{
        Addr:     utils.GetENV("REDISADDR"),
        Password: utils.GetENV("REDISPASS"),
        DB:       0, // use default DB
    })

    RedisCtx = context.Background()
}

func Disconnect() {
    client.Disconnect(MongoCtx)

    Rdb.Close()
}

Between lines 16 and 24, we define the variables we mean to export to other packages. As is apparent, we are exposing the Db and MongoCtx variables. The former is the connection to our specific Mongo database (which we will call passwordless-auth). We are not going to export our Mongo Client though. The last two variables are connection to our Redis Database instance and the respective context.

Notice how we are using the GetENV() function from the utility package to get the DB username and password for the connection string.

Next, we have a special function called init(). What makes the init() function special in Go? Well, the init() function in Golang is a lifecycle function which is called even before the main() function is called. It initializes the application. You can have an init() function in every package and be assured that those will be executed even before the main() function is. This assures that some states are set before the app runs.

Inside our init() function, we first create a context and assign it to MongoCtx. We then create a client with the connection URL which helps us connect to our Docker Container where Mongo is running (refer to the previous article in the series). At line 42, we create a pointer to the passwordless-auth database. A new DB will not be created in this case until we create a collection in it. So, we create a MongoDB collection called user-collection.

The createCollection() function will create our collection if it does not exist. Otherwise, it will quietly send an error. We won’t concern ourselves with the error in this case as this step ensures that our collection is created before we start using it and we don’t end up with a null pointer error.

Lastly, we initialize the connection to our Redis instance running in a Docker container (again, refer to the previous article in the series). The Rdb and RedisCtx are Redis equivalents of the Mongo connection and context.

The Disconnect() function being exported here is going to be invoked when the application is stopped. It is meant to close all the connections and gracefully shut down our application. It will be used in the main package.

Main Package

At this point, we have crossed the 1k-word limit. So, I am a bit wary. But I feel that this article will not be complete without a discussion of the main package. If you are new to Go, the main package is meant to house our main() function which is run right after any init() function by Go when the application starts execution. In our case, we will keep the main.go inside the cmd folder.

package main

import (
    "fmt"
    "log"
    "net/http"

    "github.com/abhik-99/passwordless-login/pkg/config"
    "github.com/abhik-99/passwordless-login/pkg/routes"

    "github.com/gorilla/mux"
)

func main() {
    defer config.Disconnect()
    router := mux.NewRouter()
    router.StrictSlash(true)

    authRouter := router.PathPrefix("/auth").Subrouter()
    routes.RegisterAuthRoutes(authRouter)

    userRouter := router.PathPrefix("/user").Subrouter()
    routes.RegisterUserRoutes(userRouter)

    fmt.Println("Started on PORT 3000")
    http.Handle("/", router)

    log.Fatal(http.ListenAndServe(":3000", router))
}

As shown in the code above, the first thing we do is start by deferring the execution of the Disconnect() function which we defined in the config package in the previous section. This is convenient as it ensures “we don’t forget about closing DB connections”.

Next, we create our main router. We set StrictSlash() to true on our router. To understand the effect of this with an example, this means that the paths trailing with /user and /user/ are evaluated to the same controller.

At line 19, we create our authentication subrouter called authRouter. Any routes registered to this router will have the prefix /auth in them. We then pass this Gorilla Mux subrouter to the RegisterAuthRoutes() function in the routes package.

We are yet to define the routes and controllers package.

Similarly, we create our user subrouter and pass it to RegisterUserRoutes() function which we will define in the next article. This shows the finesse of Gorilla Mux. It allows easy grouping of routes through this system. One can similarly group our protected and public routes in their project when using Gorilla Mux.

After this, we use the net/http module from the Standard Go library to start listening with our Gorilla Mux router which we created in line 16. This completes three of the packages of our application.

Conclusion

In this article, we took a hands-on approach to writing our Go web server in Gorilla Mux. I am way past the 1k-ish word limit so I am going to end this article at this point. In the next articles in this series, we will define our controllers and models for our specific routes. Until then, keep building awesome things and WAGMI!

Password-less Login in Go from Scratch

Abhik Banerjee — Wed, 21 Feb 2024 18:34:59 +0000

This article is a follow-up to its long-lost brother which discussed what a password-less login method in Go might look like. In this one, we actually make one. As discussed in the previous article, we will have a server written in Go communicating with a MongoDB instance and storing OTP in a Redis container.

Golang is one of those languages which I just seemingly keep encountering again and again. I must say that I like to use it and feel that it is one of the more productive languages currently in the industry. It’s easier as well. But all that is just me ranting about my preferences. In this article, we will mainly discuss the modules that we will use along with some house-keeping code and Golang Project Structure. I will try to impose a 1k-ish work limit on my articles from now on just like one of those devs who arbitrarily decided 100-lines as the mark for starting code segregation. I wonder how long I will be able to stick to this limit though…

Full Disclosure

Before we begin, there are some things that we need to get out of the way. These are:

We will be using Gorilla Mux. As per their last update, they have a new group of maintainers, and their repos have shown activity to confirm that. The tutorial can be easily replicated in any other framework or library as well. So, while we will be using Gorilla Mux, you can try to replicate it in Gin or Fiber as well.
At this time, Twillio has a verification service that provides an SDK and offloads the responsibility of creating, sending, and maintaining OTPs from the project to Twillio. Using this service would mean we won’t need Redis. So, we will not be using this service. We will be using two of Twillio’s other services – Phone SMS Sending and Email Sending services. This will be more work but then again, I find it to be fun. Perhaps we will explore the verification service when I do this mini-project again but in Rust.
We will have our Utility for encoding JSON response. We will be using this for all Success responses but only for those error responses that require custom communication with the user. For any other errors, we will be using Go’s standard library’s http.Error().
We will be using Docker Compose for MongoDB and Redis instances. So, make sure to have that installed beforehand.
It will be a beginner-oriented tutorial so if you have some expertise, it might seem slow-paced.
In this tutorial, we will not create a full-fledged system. The server will cover the authentication part and basic user profile-related read operations. The code has been open-sourced in the repo below and CRUD operation utilities are written so that readers can extend the functionality in terms of routes and controllers as an exercise.

abhik-99 / Passwordless-Login-in-Go

This repo contains code for my article series on creating a Passwordless Login system in Go from scratch.

Housekeeping

So, before we begin, let’s have the project setup done. If you are new to Go, then you need to run go mod init github.com/<your username>/passwordless-in-go. This initializes a Go Project and the go.mod file will be created after this. If you have any experience in Backend development in Node, then this is the Go counterpart of npm init.
We will be using the following Go modules for our little project:

Gorilla Mux as our Backend framework.
Godotenv for managing our environment variables
Mongo Driver for Go for communicating with Mongo DB Docker Container.
Go Playgroun’s Validator for validating our DTOs.
Go Redis’ Module for communicating with Redis. Please go ahead and add these to the project by using go get command. We will be having a project organization that reflects the purpose (as shown in the image below). I am not saying this is the “ideal” Go project structure. All I am saying that is this one makes a bit more sense to me. So please feel free to have your project structure if you feel like it.

The cmd folder contains our main.go. This is where the execution starts. The pkg folder contains packages associated with the project, namely, -

config - This folder will house our configuration-related code. This is mainly context and database connections. These DB connections will be used throughout the project.
controllers - This folder will have the code for our route controllers. It will not directly use anything from the above package. It will mainly interact with the model part of the project (residing in our folder below) and contain business logic.
data - This folder will contain the structure of our entities and data transfer objects. Both will be represented by struct. This package will utilize the config package and form a wrapper around the DB entities.
middlewares - This folder will harbour the logic for handling what comes from the user before it is passed onto our controllers. Mainly used to mutate the request and response bodies and have reusable route-related codes.
routes - We will define our Subrouters in this folder. This package will sit on top of the controllers package. The actual router will be defined in the main package and this package will register routes and route groups (groups of routes using similar logic for eg. protected routes which will use a JWT verification middleware fall under the same route group and will be defined on the same subrouter).
utils - Any reusable and shared code will be defined here. These range from wrapper for accessing Environment Variables to functions for JWT manipulation.

Last but not least, let’s have a moment to discuss the Docker Compose file that we will be using for this project. As mentioned before, we will not have hosted solutions for MongoDB and Redis. We will have our own Mongo and Redis instances running in docker containers.

version: '3'

services:
  redis:
    image: "redis:latest"
    environment:
      - REDIS_PASSWORD=${REDISPASS}
    ports:
      - "6379:6379"
    networks:
      - backend_network

  mongodb:
    image: "mongo:latest"
    environment:
      - MONGO_INITDB_ROOT_USERNAME=${DBUSER}
      - MONGO_INITDB_ROOT_PASSWORD=${DBPASS}
    ports:
      - "27017:27017"
    networks:
      - backend_network

networks:
  backend_network:

The docker-compose file above is really simple if you think about it. In the above docker compose file we defined two services – redis and mongodb. We tell docker to pick the latest Redis and Mongo images for the services respectively. After that, we define the Redis Password (REDIS_PASSWORD) to be picked automatically from the .env file’s REDISPASS environment variable. For MongoDB, we define the username and password that will be used to authenticate connection using the MONGO_INITDB_ROOT_USERNAME and MONGO_INITDB_ROOT_PASSWORD respectively. These will also be picked from the respective environment variables. For Redis, we expose port 6379 while for Mongo we expose port 27017. We create a network called backend_network and tell docker daemon that both services will be a part of this network.

You can look into the .env file in the repo above to get a full list of environment variables. I would recommend creating a .env.local file out of it by copying and renaming it. You can then run docker compose –env-file .env.local up to start the databases.

Conclusion

This concludes this short article. In this article, we mainly discussed the housekeeping aspects of our mini-project. In the next one, we will start to get down and dirty with Golang code and test out the server we create and then some. The second part in a series is almost always disappointing in some aspect so I guess I might have ticked the wrong box for some dev readers with this article. But I keep my promises and so this one was 1k-ish.

Until the next one, keep building awesome things and WAGMI!

Understanding Chainlink CCIP in 15 bullet points

Abhik Banerjee — Sun, 31 Dec 2023 17:55:49 +0000

So, it has been quite some while now that Chainlink has gone live on testnet with Chainlink CCIP – its offering for cross-chain communication. I have had my eyes on it for quite some while now. At EthIndia’23, I finally had the chance to build with it.

Considering I have had a hiatus of sorts with Web3 articles, this would be the perfect way to come back with another one. This is the first article in a series of architecture where we will build something with Chainlink CCIP and we will do it end-to-end.

But before we get on with the code and the mini-project, I feel some introduction is in order. I have always been a fan of concise articles (though my recent ones have been on the longer side). So, I thought why not try to explain Chainlink CCIP in 15 points.

Chainlink CCIP in 15 bullet points

Keep in mind that this is no substitute for the Chainlink Documentation. I would always refer my reader to it for an in-depth understanding. This is more of a Traversy Media-like Crash Course for Chainlink CCIP. So here goes…

Chainlink CCIP uses a library called Client on top of which the RouterClient is built using the IRouterClient interface.
Extra payment as gas fees for cross-chain transactions is graciously accepted. It offers no refund.
On-Ramp is sending message and/or token. Off-Ramp is receiving message and/or token.
For the on-ramp, IRouterClient needs to be implemented.
There is a specific on-ramp contract for EVM-to-EVM messages. It is a specialized version of CCIP’s EVM to Any and implements IEVM2AnyOnRamp. The IEVM2AnyOnRamp inherits from IEVM2AnyOnRampClient.
Similarly, there is a specific off-ramp contract for EVM-to-EVM messages. It is a specialized version of CCIP’s Any to EVM and implements IAny2EVMOffRamp.
The IEVM2AnyOnRampClient is similar to IRouterClient but with the difference that it is used only by the Router to route the message and spend the tokens while IRouterClient is called by the Initial sending contract.
Intuitively think of yourself as a passenger on a train with IRouterClient as the starting point, IEVM2AnyOnRamp as the first hop from where it goes to IAny2EVMOffRamp and then to the terminus IAny2EVMMessageReceiver. In between the IEVM2AnyOnRamp and IAny2EVMOffRamp there is an IRouter junction station. You, the passenger, are the message transported from the starting to the terminal station.
Chainlink provides an abstract contract called ChainlinkReceiver. This contract inherits but does not implement the IAny2EVMMessageReceiver interface. The idea is that the developer can override and implement the _ccipReceive() function with custom business logic. This is called by ccipReceive() external function defined in ChainlinkReceiver contract. Only the Router can call this external function (courtesy of the onlyRouter()) modifier defined in the contract.
A Contract inheriting ChainlinkReceiver needs to pass in the router address through constructor initialization. This address is defined as immutable in the ChainlinkReceiver contract. This means that once initialized, it cannot be changed. This is meant to provide gas optimization.
Where does the “Risk Management Network” come here? The RMN is a network of nodes that run parallel to the Chainlink CCIP infrastructure. It helps to make sure that the transactions arising from the source chain and terminating on the destination chain are valid.
I will not go too deep into it. But if one were to try to understand it, picture a DAO where every node is a network and a CCIP transaction is a proposal. Every node has a weight (or “voting power”). If the Nodes “bless” (or vote “for”) the transaction (or “proposal”) to reach a quorum, then the transaction is valid. Otherwise, it is “cursed”.
To be more precise, there is a Merkle root of transactions for each chain whose validity the RMN nodes need to decide. If a Merkle root is invalidated (or “cursed”), CCIP functions on that specific chain are paused. For most parts, Smart Contract Devs trying CCIP for applications won’t have to touch the RMN.
To know if a Cross-chain transaction is successful, one needs to browse the CCIP explorer. Once finality is achieved and indexed on the CCIP explorer, the destination smart contract will have received the intended message.
At this time, the token transfer is ERC20. It consists of the sender contract spending (or “burning”) the tokens on the source chain. The destination chain needs to mint the token independently.

What’s next?

Well, next is the New Year. Best wishes for the upcoming year and may 2024 be the year my readers achieve their dev dreams. On a serious note, in the next article, we will dive into the Code for Chainlink CCIP and demo it with NFT token transfer and more. Till then, keep building awesome things on Web3 and WAGMI!

Next x Nest – GraphQL for REST API developers – Part 2

Abhik Banerjee — Tue, 19 Dec 2023 18:17:52 +0000

It's been quite a while since I last published. Sorry for being absent. I decided to dedicate some time to personal development. But now I feel like I need to complete this series I had started. So I’m back with yet another article in the Next x Nest series. This one would be a continuation of the last article. In part 1 of the “GraphQL for REST API developers” there were a couple of topics and resolvers left out in favour of length. Let’s complete those. Compared to the last article, this one would be shorter and after this, the frontend side of things would begin.

Nuances of using a Code-first Approach

But before that, I feel it's important to discuss a few things that are relevant to taking a “code-first” approach to GraphQL API development. These become more significant in the context of NestJS. These are:

Code-first approach is easier to relate for a REST API developer but less intuitive than the original GraphQL model.
The use of the Code first approach allows us to easily place code sanitization (Nestjs transform and validation decorators) in the data transfer object layer. This is the layer that receives the input from the incoming traffic and processes it in objects which are passed to our handlers/controllers.
Circular dependency can catch you from behind if you are not careful designing in NestJS using this approach.
Contrary to popular belief or confusion of newbies, authentication and authorization can be easily implemented in GraphQL. It is easier still when using NestJS for GraphQL.

I am not advocating for NestJS here. I am always in favour of opinionated frameworks as they offer a way to reduce the “chaos in codebase”. I would prefer a framework that forces things to be done in a certain way rather than relying on “community-adopted” best practices. Because at the end of the day, while the latter seems natural, it is often laborious to ingrain in new learners. I have been part of projects where the “previous team” did things in a specific way which was not best practice and that had to be carried forward because it would have upset the timeline to do a refactor. This is why I would advocate for the use of frameworks rather than just libraries.

Remaining Resolvers

Returning to our little project, the modules that remain are the board and board user modules. So without further ado…

Board

Before we dive into the module, resolver, and service code, we need a moment to discuss the Entity. A board will be represented by a class which we will call Board (no surprises there). This class will be annotated by the @ObjectType() decorator which will tell GraphQL to use this class to generate the properties of a Board in the GraphQL schema.

import { ObjectType, Field, ID, GraphQLISODateTime } from '@nestjs/graphql';
import { BoardUser } from 'src/board-user/entities/board-user.entity';
import { Column } from 'src/column/entities/column.entity';
import { User } from 'src/user/entities/user.entity';

@ObjectType()
export class Board {
  @Field(() => ID)
  id: string;

  @Field(() => GraphQLISODateTime)
  createdAt: string;

  @Field(() => GraphQLISODateTime)
  updatedAt: string;

  @Field(() => String)
  boardName: string;

  @Field(() => String)
  boardDescription: string;

  @Field(() => User)
  createdByUser: User;

  @Field(() => [Column], { nullable: 'itemsAndList' })
  columns: Column[];

  @Field(() => [BoardUser], { nullable: 'itemsAndList' })
  boardUsers: BoardUser[];
}

Now, as can be seen from the above, albeit fields createdByUser, columns and boardUsers most of the properties are GraphQL scalars. These custom types will need to have resolvers. We will be needing resolvers as you will see in the later section. This is also where the need for importing other modules comes into play.

Module

Now the BoardModule will be using the BoardUserModule and ColumnModule. These would also be using BoardModule to provide a way for the frontend to query data about Board from the Columns and Board User resolvers. In the code below, we set up the BoardModule with forwardRef() to the aforementioned modules.

import { Module, forwardRef } from '@nestjs/common';
import { BoardService } from './board.service';
import { BoardResolver } from './board.resolver';
import { BoardUserModule } from 'src/board-user/board-user.module';
import { ColumnModule } from 'src/column/column.module';
import { UserModule } from 'src/user/user.module';

@Module({
  imports: [
    forwardRef(() => BoardUserModule),
    forwardRef(() => ColumnModule),
    forwardRef(() => UserModule),
  ],
  providers: [BoardResolver, BoardService],
  exports: [BoardService],
})
export class BoardModule {}

Resolver

Now, for the resolver, we will need the DTOs in place. These DTOs are for mutations. Specifically, a DTO for board creation and another for board updating. In the DTO below, we decorate the DTO class with the @InputType() tag. This tells NestJS to use it as a GraphQL input type in the schema.

Keep in mind that @InputType() and @ObjectType() cannot be placed on the same class.

import { InputType, Field } from '@nestjs/graphql';
import { IsNotEmpty, IsString } from 'class-validator';

@InputType()
export class CreateBoardInput {
  @IsNotEmpty()
  @IsString()
  @Field(() => String)
  boardName:string

  @IsNotEmpty()
  @IsString()
  @Field(() => String)
  boardDescription:string
}

In the above DTO, we place the validations that the mutation must have a board name and description. You might be wondering “What about the access controls?” – we design it in such a manner that the authenticated user sending the mutation is the board creator. The ID of the user is automatically decoded and picked up by the resolver as you will see in the code for the resolver. This creator is the first board user as well.

For updating a board, we design it in such a way that only the board name and/or board description may be changed. The mutation must provide the board ID. The actual logic for the update is in the service which we will discuss in the next section. The code for the update DTO is given below.

import { IsNotEmpty, IsUUID } from 'class-validator';
import { CreateBoardInput } from './create-board.input';
import { InputType, Field, Int, PartialType } from '@nestjs/graphql';

@InputType()
export class UpdateBoardInput extends PartialType(CreateBoardInput) {
  @IsNotEmpty()
  @IsUUID()
  @Field(() => String)
  id: string;
}

Finally, moving to the Resolver, we have 3 mutations – one to create called createBoard, another to update called updateBoard and one to remove the board given the id called removeBoard. These mutation names are automatically derived from the functions and as you can see by the @Mutation() annotations above their respective functions, they return the created, updated and deleted boards respectively. Pay close attention to how these mutations also pick up the authenticated user details using the @GraphQLUser() tag we discussed in the previous articles.

import {
  Resolver,
  Query,
  Mutation,
  Args,
  Int,
  ResolveField,
  Parent,
} from '@nestjs/graphql';
import { BoardService } from './board.service';
import { Board } from './entities/board.entity';
import { CreateBoardInput } from './dto/create-board.input';
import { UpdateBoardInput } from './dto/update-board.input';
import { GraphQLUser } from 'src/decorators';
import { UserJwt } from 'src/auth/dto/user-jwt.dto';
import { BoardUserService } from 'src/board-user/board-user.service';
import { BoardUser } from 'src/board-user/entities/board-user.entity';
import { Column } from 'src/column/entities/column.entity';
import { ColumnService } from 'src/column/column.service';
import { User } from 'src/user/entities/user.entity';
import { UserService } from 'src/user/user.service';

@Resolver(() => Board)
export class BoardResolver {
  constructor(
    private readonly userService: UserService,
    private readonly boardService: BoardService,
    private readonly boardUserService: BoardUserService,
    private readonly columnService: ColumnService
  ) {}

  @Mutation(() => Board)
  createBoard(
    @Args('createBoardInput') createBoardInput: CreateBoardInput,
    @GraphQLUser() user: UserJwt,
  ) {
    return this.boardService.create(createBoardInput, user.sub);
  }

  @Query(() => [Board], { name: 'boards' })
  findAll(@GraphQLUser() user: UserJwt) {
    return this.boardService.findAll({
      boardUsers: {
        some: {
          userId: user.sub,
        },
      },
    });
  }

  @Query(() => Board, { name: 'board' })
  findOne(
    @Args('id', { type: () => String }) id: string,
    @GraphQLUser() user: UserJwt,
  ) {
    return this.boardService.findOne(id, user.sub);
  }

  @Mutation(() => Board)
  updateBoard(
    @Args('updateBoardInput') updateBoardInput: UpdateBoardInput,
    @GraphQLUser() user: UserJwt,
  ) {
    return this.boardService.update(
      updateBoardInput.id,
      updateBoardInput,
      user.sub,
    );
  }

  @Mutation(() => Board)
  removeBoard(
    @Args('id', { type: () => String }) id: string,
    @GraphQLUser() user: UserJwt,
  ) {
    return this.boardService.remove(id, user.sub);
  }

  @ResolveField('boardUsers', (returns) => [BoardUser])
  async boardUsersResolver(@Parent() board) {
    const { id } = board;
    return this.boardUserService.findAll(undefined, id);
  }

  @ResolveField('columns', (returns) => [Column])
  async columnsResolver(@Parent() board) {
    const { id } = board;
    return this.columnService.findAll({boardId: id});
  }

  @ResolveField(undefined, (returns) => User)
  async createdByUser(@Parent() board) {
    const {createdBy} = board
    return this.userService.findOne(createdBy)
  }
}

As can be seen from above, we have two queries (analogous to get and get-all routes in REST API paradigm). We make sure to pick the authenticated user and utilize the board user details to only return board(s) details the current user is a part of.

Finally, we have the Field Resolvers. These are special functions which utilize the services of the imported modules to provide details about custom fields defined in the Entity. The first argument to @ResolveField() tag is the name of the field it is supposed to resolve. If not provided (i.e, passed undefined) then NestJS takes it that the name of the field and the name of the method are same. The second arg is the return type. The standard format is to write it that way ((returns) => <returned value>).

Whenever our board entity is getting resolved and the request asks for the custom fields, the specific board details will be passed via the argument decorated by @Parent(). This will help us resolve the field details particular the specific board. In the above resolvers, we utilize the service methods from the imported modules to resolve the fields.

Service

Last but not least, the BoardService. Keep in mind that in this application we are using two different databases. One is Supabase – which is used to maintain our user details. Another is a Postgres Instance hosted on Render. This is being used to maintain the rest of the entity details. In this service, we need to use the Prisma Client which points to our Render Postgres DB as shown by the PrismaRenderService below.

import { Injectable } from '@nestjs/common';
import { CreateBoardInput } from './dto/create-board.input';
import { UpdateBoardInput } from './dto/update-board.input';
import { PrismaRenderService } from 'src/prisma-render/prisma-render.service';
import { Prisma } from '@prisma/render';

@Injectable()
export class BoardService {
  constructor(private prisma: PrismaRenderService) {}
  create(createBoardInput: CreateBoardInput, userId: string) {
    return this.prisma.board.create({
      data: {
        ...createBoardInput,
        createdBy: userId,
        boardUsers: {
          create: {
            userId,
          },
        },
      },
    });
  }

  findAll(where: Prisma.BoardWhereInput) {
    return this.prisma.board.findMany({
      where
    });
  }

  findOne(id: string, userId?: string) {
    const filter: Prisma.BoardWhereUniqueInput = {id}
    if(userId) filter.boardUsers = { some: { userId } }
    return this.prisma.board.findUniqueOrThrow({
      where: filter,
    });
  }

  update(
    id: string,
    { id: _id, ...updateBoardInput }: UpdateBoardInput,
    createdBy: string,
  ) {
    return this.prisma.board.update({
      where: {
        id,
        createdBy,
      },
      data: updateBoardInput,
    });
  }

  remove(id: string, createdBy: string) {
    return this.prisma.board.delete({
      where: {
        id,
        createdBy,
      },
    });
  }
}

The code in the service file is pretty straightforward. This intuitively shows that under the hood, the business logic stays similar regardless of the data presentation layer. We have our methods which act as a wrapper over our Prisma methods to perform CRUD operations relating to the Board entity.

BoardUser

The reason BoardUser module is special is because, under the hood, we have a different DB instance for storing user profiles. So, in the DB instance storing info related to boards (including users allowed to access a board), we cannot establish a relationship to the user rows. In the second DB, we can only have a string type attribute which will have the UUIDs of the users.

It is at the business logic layer (NestJs resolver and service layers) that we will tie these together. This will give the user a seamless feel as if all the data is coming from a single DB instance. Between this module and the board and user modules, we would have covered almost all there is to GraphQL in NestJS and in general.

Before diving into the module code, let’s have a look at the BoardUser entity below. As you can see, we only have two custom fields – one denoting a user entity (User) called user and another denoting the board that the user has access to (Board entity type).

import { Field, ID, ObjectType } from "@nestjs/graphql";
import { Board } from "src/board/entities/board.entity";
import { User } from "src/user/entities/user.entity";

@ObjectType()
export class BoardUser {
  @Field(() => User)
  user: User;

  @Field(() => Board)
  board: Board
}

Now the design can vary. You might choose to have a design such that a BoardUser entity represents a one-to-many relationship (one user and all the boards the user has access to). But here, for simplicity’s sake, we go with the above design. Feel free to modify it yourself.

Module

import { Module, forwardRef } from '@nestjs/common';
import { BoardUserService } from './board-user.service';
import { BoardUserResolver } from './board-user.resolver';
import { BoardModule } from 'src/board/board.module';
import { UserModule } from 'src/user/user.module';

@Module({
  imports: [forwardRef(() => BoardModule), UserModule],
  providers: [BoardUserResolver, BoardUserService],
  exports: [BoardUserService]
})
export class BoardUserModule {}

The code for the BoardUserModule is pretty simple. We just need to use the BoardModule and the UserModule. From the usage of forwardRef(), you can easily guess that we have imported BoardUserModule in BoardModule but not in UserModule.

Resolver

The resolver is the more interesting part of it. This is where we will need to resolve the custom fields. But at the same time, we will need to have CRUD operations in form of mutations and queries for the BoardUser entity itself.

import {
  Resolver,
  Query,
  Mutation,
  Args,
  ResolveField,
  Parent,
} from '@nestjs/graphql';
import { BoardUserService } from './board-user.service';
import { AddBoardUserInput } from './dto/add-board-user.input';
import { RemoveBoardUserInput } from './dto/remove-board-user.input';
import { BoardService } from 'src/board/board.service';
import { BoardUser } from './entities/board-user.entity';
import { GraphQLUser } from 'src/decorators';
import { UserJwt } from 'src/auth/dto/user-jwt.dto';
import { UserService } from 'src/user/user.service';

@Resolver(() => BoardUser)
export class BoardUserResolver {
  constructor(
    private readonly boardUserService: BoardUserService,
    private readonly boardService: BoardService,
    private readonly userService: UserService,
  ) {}

  @Mutation(() => BoardUser, { name: 'addBoardUser' })
  create(
    @Args('addBoardUserInput') addBoardUserInput: AddBoardUserInput,
    @GraphQLUser() user: UserJwt,
  ) {
    return this.boardUserService.create(addBoardUserInput, user.sub);
  }

  @Query(() => [BoardUser], { name: 'boardUsers' })
  findAll() {
    return this.boardUserService.findAll();
  }

  @Mutation(() => BoardUser, { name: 'removeBoardUser' })
  remove(
    @Args('removeBoardUser') removeBoardUserInput: RemoveBoardUserInput,
    @GraphQLUser() user: UserJwt,
  ) {
    return this.boardUserService.remove(removeBoardUserInput, user.sub);
  }

  @ResolveField()
  async board(@Parent() boardUser) {
    const { boardId } = boardUser;
    console.log('Board User ID', boardUser);
    return this.boardService.findOne(boardId);
  }

  @ResolveField()
  async user(@Parent() boardUser) {
    const { userId } = boardUser;
    return this.userService.findOne(userId);
  }
}

In the above, we have 2 mutation resolvers for mutations called called addBoardUser and removeBoardUser. The mutation names should convey their function. Note how we are also taking in the authenticated user details for these mutations. These would be used in the actual business layer for authorization checks.

We have a query resolver for boardUsers query which returns all the BoardUser entities stored in the DB. Then we have the field resolvers annotated by @ResolveField() tag. In these field resolvers, note how we do not pass any names. So, the names of the functions are taken as the names of the fields they are supposed to resolve. We also extract boardId and userId to find the particular Board and User needed using the BoardService and the UserService.

As for the DTOs, we have two for adding and removing BoardUser entries as shown below. Note how in the AddBoardUserInput DTO, we take in userId and boardId. Everything else we do behind the scenes. So, between the resolver and service, we find the user and the board we need to add the user to.

import { Field, InputType } from "@nestjs/graphql";
import { IsNotEmpty, IsUUID } from "class-validator";

@InputType()
export class AddBoardUserInput {
  @IsNotEmpty()
  @IsUUID()
  @Field(() => String)
  userId: string;

  @IsNotEmpty()
  @IsUUID()
  @Field(() => String)
  boardId: string;
}

Lastly, for the RemoveBoardUserInput DTO, we need the same details as above. But for better semantics, we go ahead a step and create a separate DTO. As shown below, the DTO inherits from AddBoardUserInput DTO. Since we do not wrap the AddBoardUserInput DTO with PartialType() or OmitType(), you can understand that the GraphQL API user needs to mandatorily provide the userId and the boardId.

import { InputType } from '@nestjs/graphql';
import { AddBoardUserInput } from './add-board-user.input';

@InputType()
export class RemoveBoardUserInput extends AddBoardUserInput {
}

Service

Lastly, we need to take a look at the service. This design might seem a bit peculiar. When creating a new BoardUser using the create method, we first check if the user adding the new user is supposed to have access to the board. You can go ahead and have a finer access control. But this is the depth we are going to go to avoid making the whole thing complex.

import { ForbiddenException, Injectable } from '@nestjs/common';
import { RemoveBoardUserInput } from './dto/remove-board-user.input';
import { AddBoardUserInput } from './dto/add-board-user.input';
import { PrismaRenderService } from 'src/prisma-render/prisma-render.service';
import { Prisma } from '@prisma/render';

@Injectable()
export class BoardUserService {
  constructor(private prisma: PrismaRenderService) {}
  async create({ userId, boardId }: AddBoardUserInput, existingUserId: string) {
    try {
      await this.prisma.boardUser.findUniqueOrThrow({
        where: {
          userId_boardId: {
            userId: existingUserId,
            boardId,
          },
        },
      });
    } catch (error) {
      if (error.code === 'P2025')
        throw new ForbiddenException('User not authorized');
    }
    return this.prisma.boardUser.create({
      data: {
        userId,
        board: {
          connect: {
            id: boardId,
          },
        },
      },
    });
  }

  findAll(userId?: string, boardId?: string) {
    var filter: Prisma.BoardUserWhereInput = {}
    if (userId) filter = {...filter, userId}
    if(boardId) filter = {...filter, boardId}
    return this.prisma.boardUser.findMany({
        where: filter
    });
  }

  findAllUsingColumn(userId: string, columnId: string) {
    return this.prisma.boardUser.findMany({
      where: {
        userId,
        board: {
          is: {
            columns: {
              some: {
                id: columnId
              }
            }
          }
        }
      }
    })
  }

  findAllUsingCard(userId: string, cardId: string) {
    return this.prisma.boardUser.findMany({
      where: {
        userId,
        board: {
          is: {
            columns: {
              some: {
                cards: {
                  some: {
                    id: cardId
                  }
                }
              }
            }
          }
        }
      }
    })
  }

  async remove(
    { userId, boardId }: RemoveBoardUserInput,
    existingUserId: string,
  ) {
    try {
      await this.prisma.boardUser.findUniqueOrThrow({
        where: {
          userId_boardId: {
            userId: existingUserId,
            boardId,
          },
        },
      });
    } catch (error) {
      if (error.code === 'P2025')
        throw new ForbiddenException('User not authorized');
    }
    return this.prisma.boardUser.delete({
      where: { userId_boardId: { userId, boardId } },
    });
  }
}

After that, we have the findAll method which takes in optional arguments of userId and boardId and returns all the board users who match the filter. The interesting thing to note here is that this turns into a findOne when both arguments are specified.
After that, we have a couple of helper methods to find board users by resolving from Column and Card. These are needed in ColumnModule and CardModule respectively. Given the columnId and cardId respectively, these find if the user (denoted by userId) is supposed to have access to them.
Last but not least, we have the remove method. Here, we make sure that only an existing user can remove another user from the board. Again, you can go even finer-grained in your particular design. This concludes the BoardUserModule as a whole

What’s Next?

With this, we have covered the important modules that could have helped us understand how our backend would be working. Next up we will be delving into frontend design – so back to NextJS it is. I might take a couple of articles break before that because I would love to cover Chainlink CCIP before coming back into this.

So, until then, make sure to follow me to keep updated on the latest articles and WAGMI!

Next x Nest – GraphQL for REST API developers - Part 1

Abhik Banerjee — Fri, 06 Oct 2023 18:30:00 +0000

In the past articles in this series, we have explored the frontend and backend side of authentication. If you have been following those, then right about now you’d also have a fully functional frontend in NextJS which uses Next Auth to facilitate Authentication with Google OAuth 2.0 and communicates with a backend built using NestJS which also has a separate but interoperable authentication system using Passport and Google OAuth.

At this stage, we are ready to flesh out our backend. As informed previously, we will be building our backend in GraphQL. So, even though the authN was done with REST APIs, the remainder of the backend will be exposed as GraphQL API. Why was this design decision made? Well, GraphQL allows for flexibility and customization on the frontend. It is one of those things that almost every seasoned backend dev is aware of and likes but tries to sometimes avoid. Since I have a knack for article articles on such things which are often “avoided” and because the Kanban board we are building will require this level of flexibility, the choice of GraphQL with Nest was made.

Just to confirm again, we will be using NestJS to make our lives easier. This article will be aimed at devs who have a good understanding of REST APIs and a basic understanding of NestJS. Keep in mind that NestJS offers 2 ways of using GraphQL

Code-first Approach – Here you use the entities in NestJS to create the schema in a format that would be familiar to someone who has written DTOs in NestJS. NestJS takes these entities and stitches a GraphQL schema. The developer need not really worry about touch Schema Definition Language.
Schema-first Approach – Here you specify the Schema in individual modules first. NestJS then combines these schemas and creates a singular schema definition language file. From this file, NestJS then generates types and entities to be used in the project.

There is a third approach where you can use both paradigms at once in the same project but it is complicated and can lead to exposure of multiple GraphQL endpoints and redundancies in schema definition if not used in a microservice-based architecture. We will explore this paradigm as well once we have explored the above two.

In this article, we will explore the “Code-first Approach”. This is geared towards REST API devs and makes them feel more at home. Apart from this, we will also explore how to use 2 different databases with Prisma in the same NestJS project and manage things like migrations and Prisma Studio between them.

Housekeeping

Before we begin, you will need to provision a new PostgreSQL (different from the Supabase one we have been using thus far). For this tutorial, we will use Render. Render offers free managed PostgreSQL instances for a period of 90 days. If you haven’t created a Render account yet, head over and sign up. You will be redirected to your Render Dashboard. Click on “New” in the Appbar and select PostgreSQL DB. You will see something similar to the image shown below. Fill in the fields and click on Create.

Once the creation is complete, move over to the Info tab of your instance. Here you will get the External Connection URL. As expected, this will be used to connect from your NestJS project using Prisma. Also, make sure that the Access Control is set to 0.0.0.0/0 as shown in the below image. This means anyone on the internet with the Connection string will be able to access the DB instance. This is why it's paramount to keep your connection string a secret. Storing it in a .env file is a step in that direction.

To use GraphQL in a NestJs project we need to install NestJs’ Apollo and GraphQL packages. For these, run npx i @nestjs/apollo @nestjs/graphql. Once this finishes, move over to your app.module.ts. Here we will import the GraphQL config module and make it generally available. To do this, inside the imports array, add the following:

// Add the following to the imports array
    GraphQLModule.forRoot<ApolloDriverConfig>({
      driver: ApolloDriver,
      include: [CardModule, BoardModule, BoardUserModule, ColumnModule],
      autoSchemaFile: join(process.cwd(), 'src/graphql-schema/schema.gql'),
    }),

Using Multiple Prisma Schema in a single project

We have set up a Supabase instance and connected it to our NestJS project. That will be used only for Auth. For all other purposes, we will use another PostgreSQL instance. This also means we will have 2 separate schema.prisma files and Prisma clients.

This article by @micalevisk offers great insight into how to use different versions of the same module in a NestJS project. In our case, we will be using different Prisma Client Modules in the same Nest project. Remove traces of the Prisma module we developed in our last article from our project and then run the following commands:

nest new module prisma-render followed by nest new service prisma-render - This will create the first Prisma Module which we will use to connect to our Render Postgres DB instance.
nest new module prisma-supabase followed by nest new service prisma-supabase - This will create the Module which we will use to connect to our Supabase Postgres instance.

Prisma Supabase Module

Our PrismaSupabaseModule will be a global module and it will export the service of the module. This will enable other module like AuthModule and UserModule to utilize it with ease. The code below for our prisma-supabase.module.ts file does exactly that:

// prisma-supabase.module.ts
import { Global, Module } from '@nestjs/common';
import { PrismaSupabaseService } from './prisma-supabase.service';

@Global()
@Module({
  providers: [PrismaSupabaseService],
  exports: [PrismaSupabaseService]
})
export class PrismaSupabaseModule {}

Before moving to the service, we need to make certain changes to our schema file. Firstly, we need to rename it. As a good practice, we will call our Supabase schema file supabase.schema.prisma. We need not touch the schema definition in the file. Just a little change in the generator configuration and we are daisy!

Our dependencies are being taken care of by Turbo and the NestJS & NextJS dependencies are both stored globally. The client our Prisma will generate will also need to be put in that location for easy path resolution. For that reason, we will need to change the output path from default to inside a special folder in the node_modules as shown below.

// generator for supabase.schema.prisma
generator client {
  provider = "prisma-client-js"
  output = "../../../node_modules/@prisma/supabase"
}

Now with this change we need to run npx prisma generate –schema=./prisma/supabase.schema.prisma. Note how we specify the name of the schema file since there is no default schema.prisma file for Prisma to pick up automatically. This will generate our Supabase Prisma Client inside the Prisma dependency of the global node_modules. We can now move to create our Supabase service.

Inside our prisma-supabase.service.ts file of our prisma-supabase module, we will need to import the PrismaClient from @prisma/supabase instead of our default @prisma/client. This is because our Supabase-specific Prisma client is now generated inside our custom location. The remainder of the code will remain similar to the steps we took in our previous article when we created our Prisma module. So hopefully the code below for our prisma-supabase.service.ts needs no further explanations.

// prisma-supabase.service.ts
import { Injectable } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { PrismaClient } from '@prisma/supabase'; //NOTE HERE

@Injectable()
export class PrismaSupabaseService extends PrismaClient {
  constructor(configService: ConfigService) {
    super({
      datasources: {
        db: {
          url: configService.get('SUPABASE_DATABASE_URL'),
        },
      },
    });
  }

}

Finally, we will change the imports of our AuthModule which needs to use this PrismaSupabaseModule. Inside the auth.service.ts we will change to PrismaSupabaseService instead of our old PrismaService (which no longer exists). The minor changes are shown below:

import { Injectable, UnauthorizedException } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { JwtService } from '@nestjs/jwt';
import { GoogleLoginUserDto } from './dto/google-login.dto';
import { PrismaSupabaseService } from 'src/prisma-supabase/prisma-supabase.service'; // NOTE HERE

@Injectable()
export class AuthService {
  constructor(
    private jwtService: JwtService,
    private configService: ConfigService,
    private prisma: PrismaSupabaseService, // NOTE HERE
  ) {}

/*
*
* Remainder of the service remains same
*
/

}

Prisma Render Module

Next up, we will need modifications to our PrismaRenderModule. But before that, we need to discuss the Schema for our project. Given below is the Schema for our Kanban Board. These are the contents of our render.schema.prisma file that we need to create inside our prisma folder where our supabase.schema.prisma file is stored. Explanations follow.

generator client {
  provider = "prisma-client-js"
  output   = "../../../node_modules/@prisma/render"
}

datasource db {
  provider = "postgresql"
  url      = env("RENDER_DATABASE_URL")
}

model Board {
  id        String   @id @default(uuid())
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  boardName        String
  boardDescription String
  createdBy        String

  columns   Column[]
  boardUsers BoardUser[]
}

model BoardUser {
  userId String
  board  Board  @relation(fields: [boardId], references: [id], onDelete: Cascade)

  boardId String

  @@unique([userId, boardId])
}

model Column {
  id        String   @id @default(uuid())
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  columnName        String
  columnDescription String

  board   Board  @relation(fields: [boardId], references: [id])
  boardId String

  cards Card[]
}

model Card {
  id        String   @id @default(uuid())
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  cardNumber      Int
  cardName        String
  cardDescription String
  createdBy       String
  assignedTo      String
  storyPoints     Int
  priority        Priority
  status          Status
  startDate       DateTime
  endDate         DateTime

  comments Comment[]
  column   Column    @relation(fields: [columnId], references: [id])
  columnId String
}

model Comment {
  id        String   @id @default(uuid())
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  createdBy String
  body      String
  card      Card   @relation(fields: [cardId], references: [id])
  cardId    String
}

enum Priority {
  CRITICAL
  HIGH
  MEDIUM
  LOW
}

enum Status {
  TODO
  IN_PROGRESS
  DONE
}

Just like our Supabase client, we will generate our Render client in a custom location right alongside our Supabase client. For this, we change the output location of our generator. We will be connecting to our Render DB instance using the RENDER_DATABASE_URL env variable. So, keep in mind to include it in the .env file and in the Environment Variable Schema check inside ConfigModule imported in app.module.ts.

We have 5 models in our Kanban board project:

Board - Represents a Kanban board. Will have a name, description a list of users who have access to the board. We also record the creator of the board for admin functions.
BoardUser - Represents the table which records user access to a specific board. We are not having RBAC here. We assume all users in this table have equal rights and rank lower than the board creator.
Column - This model represents the columns inside our board. While the default ones a board might have are “Backlog”, “To-Do”, “Under Progress” and “Done”, we are not enforcing them. So, every new board has 0 columns. The users need to create these columns by themselves. A column will have a list of Cards.
Card - These represent the user stories or tasks. A card will have a globally unique ID, a number that will be unique in a board, name, description, story points, assigned to user ID, start & end date, a status (enum which can be TODO, IN_PROGRESS and DONE) and a priority (enum which can be CRITICAL, HIGH, MEDIUM and LOW). A card will have a list of comments.
Comment - Comments that a board user might leave on a card. This can range from a PR created for the tasks to any notes for other users. A Comment will always have a corresponding Card.

Keep in mind that we are not going full gaga over the functionality. The aim of this mini-project is to demonstrate the various moving parts in a Nest + Next project ecosystem. As such, if you want you may include your touches to the mini-project.

Now we will not be running the generate command for Prisma this time around. Here, we have created our schema but our Render Postgres Instance does not contain that. We are going to migrate it. To migrate to a specific DB when you are using multiple Prisma Schema files, we need to specify the schema file to use for the migration using the --schema flag. In our case, we need to run npx prisma migrate dev –schema=./prisma/render.schema.prisma. This will run the migration and generate the client in the custom location we have specified in the above schema.

Finally, inside prisma-render.service.ts, we need to follow the steps we have done for our Supabase client and import the newly generated Render Prisma Client. The code below exactly does that.

import { Injectable } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { PrismaClient } from '@prisma/render'; // NOTE HERE

@Injectable()
export class PrismaRenderService extends PrismaClient {
  constructor(configService: ConfigService) {
    super({
      datasources: {
        db: {
          url: configService.get('RENDER_DATABASE_URL'),
        },
      },
    });
  }

}

GraphQL Resolvers

Now with the schema above, you’d expect to create separate modules and write resolvers. In fact, that’s what we need to do. But for the sake of keeping the article short, I am going to cover the 3 more important types of resolvers. The remainder will be inside the GitHub repo on the main branch.

Resolvers in GraphQL are your REST API endpoint counterpart. There are no “GET”, “POST”, “PUT” or “DELETE” verbs to work with in GraphQL. You create “resolvers” for your data model (basically those tables or mongodb collections). These resolvers are then invoked from the frontend. Inside the resolvers, you specify which attributes (table column or document field in case of mongodb) of the model you want to return while coding. Typically, all the attributes that may be required are sent as response of a resolver. On the frontend, a query is written using the resolver which basically tells your GraphQL API which parts or attributes from the resolver response the frontend wants. Only those attributes are sent back. That’s how the whole system works.

We will cover the UserModule, BoardModule and BoardUserModule. Between these three, most of the important points can be covered. Before we get started, let’s generate the three modules. Consecutively run the following. Keep in mind that you need to tell NestJs to generate CRUD endpoints and when asked, select “GraphQL (Code First)”.

nest g resource user - This will generate our UserModule. This module will use the Supabase Prisma Client and act as common ground for resolving user info from other resolvers.
nest g resource board - This will generate our BoardModule. This module will use Render Prisma Client under the hood.
nest g resource board-user - This will generate our BoardUserModule. While this will primarily use the Render Prisma Client, it will use the UserModule to resolve user details of a board user.

Circular Dependency

Circular dependency is a dreaded problem in the programming world. But unfortunately (or fortunately), circular dependencies are quite common in GraphQL. This will be clear as we go on. For now, remember that NestJS offers an easy way out of it using forwardRef().

Basically, you take the imports arrays of the two modules having circular dependencies on one another. Inside the imports array, you wrap the imported module with forwardRef() as shown below. You do this on both modules. This solves the issue. NestJs will now use the ref of the module to solve the circular dependency.

// Inside board.module.ts
import { Module, forwardRef } from '@nestjs/common';
import { BoardService } from './board.service';
import { BoardResolver } from './board.resolver';
import { BoardUserModule } from 'src/board-user/board-user.module';
import { UserModule } from 'src/user/user.module';

@Module({
  imports: [
    forwardRef(() => BoardUserModule), //NOTE HERE
    forwardRef(() => UserModule) //NOTE HERE
  ],
  providers: [BoardResolver, BoardService],
  exports: [BoardService],
})
export class BoardModule {}

Likewise importing on the other side (import in the BoardUserModule as well):

import { Module, forwardRef } from '@nestjs/common';
import { UserService } from './user.service';
import { UserResolver } from './user.resolver';
import { BoardModule } from 'src/board/board.module';

@Module({
  imports: [forwardRef(() => BoardModule)], // NOTE HERE
  providers: [UserResolver, UserService],
  exports: [UserService],
})
export class UserModule {}

User Module

While you might think the first thing, we need to define in the module is the module file itself, the entity file is more important. There are also the DTOs we need to define in the module as we will see in the later modules. In this module, the User data is just read so we won’t need any DTOs here as there are no creation or updation happening.

User Entity

In NestJS, the entity has an @ObjectType() decorator. This tells the NestJS GraphQL engine that what it is reading needs to be provided when this entity is “resolved”. The entity itself is represented by a class and its properties closely mirror the DB model and parts of the DB model you want to expose (or how you want to expose them). Take for instance the below User Entity class:

import { ObjectType, Field, ID, GraphQLISODateTime } from '@nestjs/graphql';
import { Board } from 'src/board/entities/board.entity';

@ObjectType()
export class User {
  @Field(() => ID)
  id: string;

  @Field(() => String)
  name: string;

  @Field(() => String)
  email: string;

  @Field(() => GraphQLISODateTime)
  emailVerified: Date;

  @Field(() => String)
  image: string;

  @Field(() => [Board])
  boardsCreated: [Board]
}

In the above entity class, we say that User has an id. This id is of type string. In GraphQL, ID is actually a datatype. Every property in an entity needs to be decorated by the @Field() decorator. This @Field() decorator tells GraphQL the type of the property and whether it can be nullable or not. By default, nothing is nullable.

We say that the user will have a name, email, and an image link. These will be string type (denoted by their type inside the class and inside the @Field() decorator). The property will be a Date type. GraphQL has an inbuilt type of GraphQLISODateTime to represent such Date formats as shown by the corresponding field decorator.

Lastly, we say that when a user is resolved, it must also show the boards that the user has created with the boardsCreated property. Note how we specify another entity as the type inside the corresponding @Field() decorator. This is a very handy way to represent the Board inside other types.

Throwback to when I said that the entity object closely mirrors the DB and what/how you want to expose the data.

We don’t have a Board model in our User model. The User model is described in our Supabase instance while the Board model is in our Render instance. When we write our business logic using our resolver files and service files, we will create a resolver for the board inside our user module. On the frontend, anyone querying the API will not notice the difference in DB storage. Thus, we have two different Database instances’ data being exposed through GraphQL queries. This will also allow the frontend user to write complicated queries which involve both models.

We can go a few steps further and add fields like comments, cardCreated and cardsAssigned. But the main point here is to help you understand how resolving a field works. Once you understand that, feel free to go wild with it.

Module

Our Module here is plain and simple. Since we need to resolve the boards field in User entity, we need to include BoardService which comes from BoardModule. But we also need to make sure to avoid Circular dependency. So, forwardRef() comes in handy. In the code below, we do exactly that.

// user.module.ts

import { Module, forwardRef } from '@nestjs/common';
import { UserService } from './user.service';
import { UserResolver } from './user.resolver';
import { BoardModule } from 'src/board/board.module';

@Module({
  imports: [forwardRef(() => BoardModule)],
  providers: [UserResolver, UserService],
  exports: [UserService],
})
export class UserModule {}

Resolver

Now, a resolver is the REST controller counterpart in GraphQL. It stands to reason that it will invoke methods in the service file of the module to handle requests and send back responses. In GraphQL, a “query” is any read-type request, and a “mutation” is a write-type request. So, any creation, updation or deletion would be a “mutation”. We need to define these queries and mutation as shown in the code below. Explanations follow.

// user.resolver.ts

import {
  Resolver,
  Query,
  Mutation,
  Args,
  Int,
  ResolveField,
  Parent,
} from '@nestjs/graphql';
import { UserService } from './user.service';
import { User } from './entities/user.entity';
import { GraphQLUser } from 'src/decorators';
import { Board } from 'src/board/entities/board.entity';
import { BoardService } from 'src/board/board.service';

@Resolver(() => User)
export class UserResolver {
  constructor(
    private readonly userService: UserService,
    private readonly boardService: BoardService,
  ) {}

  @Query(() => [User], { name: 'users' })
  findAll() {
    return this.userService.findAll({});
  }

  @Query(() => User, { name: 'user' })
  findOne(@Args('id', { type: () => String }) id: string) {
    return this.userService.findOne(id);
  }

  @Mutation(() => User)
  removeUser(@GraphQLUser('sub') id: string) {
    return this.userService.remove(id);
  }

  @ResolveField('boardsCreated', (returns) => [Board])
  getBoardsCreatedByUser(@Parent() user: User) {
    const { id } = user;
    return this.boardService.findAll({createdBy: id});
  }
}

In the constructor at lines 19-20, we use the shorthand to define the services we are going to invoke. We are going to need the underlying UserService and the BoardService which comes from BoardModule which we imported into the module.

The first query that we define at line 23 is the counterpart of “GET all” route in a REST API. We say that it will return a list of User ’s. The second option to the @Query() decorator is the name of the query. So, to get a list of all users, the users query will be invoked and the fields required will be passed into it.

Second, we have the “GET by ID” REST counterpart GraphQL query at line 28. As you might have guessed, it is supposed to return a single User. To get the user, one would have to use the user(id) query and pass in the list of attributes required.

We won’t be needing a “PUT” or “PATCH” counterpart here. Will be exploring it in the next module. So, we jump to the first mutation at line 33. Note how we do not pass a {name: <mutation name>} here. Keep in mind that we do not have that, NestJS will use the function name as the name of the mutation. The same goes for the queries. This “DELETE by ID” REST API counterpart tells us that when this mutation is invoked, we will take the user ID (which is in the sub field of the JWT) and remove the user.

Lastly, we have the @ResolveField() decorator. This is used to resolve any outside fields which may exist in the entity. In our case, that’s the boardsCreated field in the User entity. This is a powerful feature because now, GraphQL can resolve the board and one can pass in the attributes needed from the boards and get back only those attributes. The @Parent() decorator is used to get the user whose created boards we want to access. The user argument in the parameter list of the getBoardsCreatedByUser() function receives the user details. We have defined a findAll() function inside BoardService which is then invoked to filter out boards by the createdBy field on the Board model.

Service

We will make short work of our user service. We just need three functions in the service that will invoke Prisma API functions for our models defined in the supabase.schema.prisma file. As shown in the code below, we just the findAll, findOne, and remove functions. Note how we import the PrismaSupabaseService. We didn’t need to import the PrismaSupabaseModule because we had declared it as a global module.

// user.service.ts

import { Injectable } from '@nestjs/common';
import { Prisma } from '@prisma/supabase';
import { PrismaSupabaseService } from 'src/prisma-supabase/prisma-supabase.service';

@Injectable()
export class UserService {
  constructor(private prisma: PrismaSupabaseService) {}
  findAll(where: Prisma.usersWhereInput) {
    return this.prisma.users.findMany({where});
  }

  findOne(id: string) {
    return this.prisma.users.findUniqueOrThrow({where: {id}});
  }

  remove(id: string) {
    return this.prisma.users.delete({where: {id}});
  }
}

In line 8, we define our findAll() function. This is a weak wrapper around Prisma’s model-specific findMany() function. This is more of a personal bias. This helps in importing this service and invoking the findAll with filters which would translate to the where clause of the Prisma API. It is a handy trick I like to use.

Next, we have the findOne() function which takes in an id and either returns the user with that ID or throws an exception. Of course, this translated to an Internal Server Error. So, it is always recommended to have NestJS Global Exception filters in place. I like to throw such an error from the service and have it handled in a custom Prisma Exception NestJS filter.

Lastly, we have the remove() function which takes in the id and returns the deleted user as a response.
This concludes our service.

What’s Next?

Now I wanted to cover the board and board user modules in this article itself but that would make it 5k + words. That’s way too long for developers with the attention span of a goldfish. Being someone who has a similar attention span, I would never want to inflict that on a fellow developer. So, we will cover those modules and then some in the next part.

That's why I have to bring this article to an abrupt end. Keep in mind that the code discussed here has been open-sourced at the following repo:

abhik-99 / Trivial-Kanban

This is a mini-project part of the series 'Next x Nest'. It uses NextJs 13+ to create a Kanban board and has NestJs on the backend.

Until then, keep building awesome stuff and WAGMI!

Next x Nest - Using Supabase & Google OAuth in NestJS

Abhik Banerjee — Sat, 02 Sep 2023 11:02:20 +0000

Shall we pick up right where we left off from? The last article in this series was cut short due to excess length. We covered how to use Next Auth and Supabase with Google OAuth provider in NextJS in the last article. In this article, we will:

Create a Backend in NestJS.
Integrate Supabase into it using Prisma.
Use a Passport to Integrate Google OAuth Strategy for Authentication (AuthN).
Explore how to simultaneously use JWT Strategy in NestJS for Authorization (AuthZ).
Make our NextJS frontend interact with the NestJS backend.

Before we proceed, I’d like to state that the Code for this mini-project is open-sourced in this Github Repo:

abhik-99 / Trivial-Kanban

This is a mini-project part of the series 'Next x Nest'. It uses NextJs 13+ to create a Kanban board and has NestJs on the backend.

Housekeeping

We first need to install Passport, Passport’s Google OAuth & JWT Strategy, and NestJS-specific Passport wrapper. For this reason, run the npm i passport passport-jwt passport-google-oauth20 @nestjs/jwt @nestjs/passport. This will install the dependencies. Next, we need to install the dev dependencies. Running npm i -D @types/passport-google-oauth20 @types/passport-jwt will take care of that.

Also, we will be using environment variables in our NestJS backend project. For this, we need to install @nestjs/config and its dependencies. Run npm i @nestjs/config joi. For good measure, we will also be adding health checks to our backend. For this, we will use @nestjs/terminus. Unfortunately, that does not come built-in so as to make things lighter. We need to run npm i @nestjs/terminus. We will cover adding health checks in the last section of this article once we are done integrating the DB.

Using Environment variables in NestJS

Just using environment variables is as easy as importing ConfigModule from @nestjs/config and adding it to our app.module.ts. But with NestJS, we can do so much more. NestJS allows us to check the environment file and make sure that certain env variables exist before we start the app. That’s where joi comes in.

While it might make more sense to some to create a new DynamicModule to wrap the ConfigModule, we are going to stick to the simpler solution and add our configuration to the ConfigModule all inside the AppModule. Our app.module.ts file would look something like this right about now.

import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { ConfigModule } from '@nestjs/config';
import * as Joi from 'joi';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      validationSchema: Joi.object({
        DATABASE_URL: Joi.string().required(),
        DIRECT_URL: Joi.string().required(),
        GOOGLE_CLIENT_ID: Joi.string().required(),
        GOOGLE_CLIENT_SECRET: Joi.string().required(),
        GOOGLE_CALLBACK_URL: Joi.string().required(),
        APP_JWT_SECRET: Joi.string().required()
      }),
    })
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

In the above code, we import ConfigModule inside AppModule. We tell NestJs that we want the ConfigModule (and in effect, the ConfigService) to be made available globally in the app using isGlobal: true. This will save us from adding the ConfigModule to every module in our NestJS backend app. Next, we define the schema of our env file. We tell NestJS that our ENV file should contain the variables with the conditions specified inside the validationSchema property. We use Joi to create a type-checker here. This is similar to Zod or Yup in the frontend.

DATABASE_URL & DIRECT_URL are for Supabase. GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, and GOOGLE_CALLBACK_URL can be obtained from the GCP console. This was covered in the previous article. These env variables will be used Google OAuth using Passport. APP_JWT-SECRET is the secret we will use for minting and managing the authZ JWT token. With this schema defined, our backend app won’t start unless we have a .env will all the values marked as required() in the validation schema.

This completes our housekeeping part. We will now dive into the major topics of this article.

Adding Passport and Google OAuth to NestJS

At this point, we already have a NestJS backend project setup in our Monorepo. We are able to run it in dev mode using Turborepo. We won’t directly get into the nitty-gritty details of creating a Backend for the Kanban Board. First, we will add AuthN and AuthZ to our backend app. The backend creation would come in the next article where we would build a GraphQL backend for our Kanban Board. By the time that article concludes, we would have a NestJS backend using GraphQL with authentication.

We need to import the PassportModule and JwtModule into our App Module. This will register them and tell NestJs that every time we use Passport or its corresponding functionality, NestJS can pick them up from here. Our app.module.ts file would now look like this:

import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { ConfigModule } from '@nestjs/config';
import * as Joi from 'joi';
import { PassportModule } from '@nestjs/passport';
import { JwtModule } from '@nestjs/jwt';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      validationSchema: Joi.object({
        DATABASE_URL: Joi.string().required(),
        DIRECT_URL: Joi.string().required(),
        GOOGLE_CLIENT_ID: Joi.string().required(),
        GOOGLE_CLIENT_SECRET: Joi.string().required(),
        GOOGLE_CALLBACK_URL: Joi.string().required(),
        APP_JWT_SECRET: Joi.string().required()
      }),
    }),
    PassportModule,
    JwtModule.register({
      global: true,
    }),
  ],
  controllers: [AppController],
  providers: [AppService, GoogleStrategy, JwtStrategy],
})
export class AppModule {}

Creating Google OAuth Strategy & Guard in Nest

Next, we move towards making a Google Login for our NestJS backend. The obvious question here could be “Why create a NestJS login if Login is already handled by NextJS & Next Auth” – Well the answer to that is to make sure someone can access our backend independent of the frontend. We will have Google OAuth-based Login on the backend and just as we did on the frontend, we will use the Authentication to get an id_token and an access_token from Google. This will complete the AuthN part. For the AuthZ part, we will mint a custom JWT (let’s call that auth_token, similar to what we did for the frontend. The auth_token is what we will check for in our other routes through the Guard we will make in the next section. This AuthZ token will be interoperable with the Frontend.

Firstly, we need to create a Strategy. The heavy lifting is really done by NestJs and Passport. We just to need to assemble the stuff. We will use the clientID, clientSecret values from what we got from the GCP console in the previous article. callbackURL in our case would be http://localhost:3001/auth/google-redirect. After authentication, google will redirect to this route on our backend with all the Google User profile data. We will need to create this route. It will be in our AuthModule covered below. The code below shows the contents of our strategy. We will call this file google.strategy.ts and place it in a new directory called strategies inside the src folder of the backend folder. Keep in mind that we need to pass the same names for the strategy and the guard for that strategy. So for instance, in the code, below at line 12 we tell Passport and Nest to use the Google Strategy and to call this whole strategy-guard collection as google.

import { PassportStrategy } from '@nestjs/passport';
import {
  GoogleCallbackParameters,
  Profile,
  Strategy,
  VerifyCallback,
} from 'passport-google-oauth20';
import { Injectable } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';

@Injectable()
export class GoogleStrategy extends PassportStrategy(Strategy, 'google') {
  constructor(configService: ConfigService) {
    super(
      {
        clientID: configService.get('GOOGLE_CLIENT_ID'),
        clientSecret: configService.get('GOOGLE_CLIENT_SECRET'),
        callbackURL: configService.get('GOOGLE_CALLBACK_URL'),
        scope: ['email', 'profile', 'openid'],
      },
      async (
        accessToken: string,
        refreshToken: string,
        params: GoogleCallbackParameters,
        profile: Profile,
        done: VerifyCallback,
      ) => {
        const { expires_in, id_token } = params;
        const {
          id,
          name,
          emails,
          photos,
          _json: { email_verified },
        } = profile;
        const user = {
          providerAccountId: id,
          email: emails[0].value,
          email_verified,
          firstName: name.givenName,
          lastName: name.familyName,
          picture: photos[0].value,
          accessToken,
          refreshToken,
          id_token,
          expires_in,
        };
        done(null, user);
      },
    );
  }
}

In the code above, apart from the values from GCP console, we tell Google OAuth that we want the email, profile, and conformance with the OpenID standard (and the related data). In the async() method, Google will send all the profile data. We need a select few things to create a user which would conform to the User table in our Supabase instance. We are picking the expires_in and id_token passed in params along with the id, name, emails, and photos from profile parameter. We also pick the emails_verified found in the _json property of the returned Google user profile. Between lines 36 and 47, we construct the user object with what we need on the Supabase table and invoke the done callback to signify that the first step of the authN is complete.

For the http-google-oauth.guard.ts file, we just need to add the below code to get it done. This guard below is where our user authentication starts. Keep in mind that we need to pass in the google key to the AuthGuard class at line 5.

import { Injectable } from '@nestjs/common';
import { AuthGuard } from '@nestjs/passport';

@Injectable()
export class HttpGoogleOAuthGuard extends AuthGuard('google') {
  constructor() {
    super({
      accessType: 'offline',
    });
  }
}

Our flow would, thus, consist of the user going to the login link. The auth controller from AuthModule will get invoked at this link. This controller will have this guard on it. The user would be re-directed to Google Login page. On completion, the user will be redirected to our app at the callbackURL specified. At the callbackURL, the controller from AuthModule will use the Google strategy defined above to get the data, check if a user with that email exists in our database. If such a user exists then mint the user a auth_token. If it’s a new user, then save the user in the DB and then mint a JWT. Put the above guard in a separate folder called guards at the same level as that of strategies.

We will need to import the GoogleStrategy in our app.module.ts file. This we will cover in the later sections.

Creating a JWT Auth Strategy & Guard in NestJs

After the Google Strategy, it's time for the JWT strategy. In the same strategies folder as above, create a file called jwt.strategy.ts and paste the code below. Explanations follow.

import { ExtractJwt, Strategy } from 'passport-jwt';
import { PassportStrategy } from '@nestjs/passport';
import { Injectable } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';

@Injectable()
export class JwtStrategy extends PassportStrategy(Strategy, 'jwt') {
  constructor(configService: ConfigService) {
    super({
      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
      ignoreExpiration: false,
      secretOrKey: configService.get("APP_JWT_SECRET"),
    });
  }

  async validate(payload: any) {
    return { userId: payload.sub, username: payload.username };
  }
}

Between lines 8 and 14, we define the constructor. Here we import the configService. We pick the APP_JWT_SECRET from our env variables and pass that on as the JWT encryption/decryption key through the secretOrKey arg to super(). We tell Passport that if the JWT has expired then it should not be allowed and also to extract the JWT from the headers at lines 11 and 10 respectively. This means that the JWT auth_token needs to be sent through the authorization header key and needs to be in a format like Bearer <JWT Token>.

The validate() function receives the decoded JWT details and we just restructure it a bit before returning. The return from this function gets populated into user object inside our HTTP request. This completes the Strategy. Note how we pass the ‘jwt` here.

Next, in the guards folder create a file called http-jwt-auth.guard.ts. This file will contain the code below. Note how similar to the strategy above, we pass the same jwt to AuthGuard class thereby telling NestJS to associate this guard to the strategy of the same name.

`typescript
import { ExecutionContext, Injectable } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { AuthGuard } from '@nestjs/passport';
import { IS_PUBLIC_KEY } from 'src/decorators';

@Injectable()
export class JwtAuthGuard extends AuthGuard('jwt') {
constructor(private reflector: Reflector) {
super();
}
canActivate(context: ExecutionContext) {
const isPublic = this.reflector.getAllAndOverride(IS_PUBLIC_KEY, [
context.getHandler(),
context.getClass(),
]);
const isGoogleLogin = this.reflector.getAllAndOverride("google-login", [
context.getHandler(),
context.getClass(),
]);
if (isPublic || isGoogleLogin) {
return true;
}
return super.canActivate(context);
}
}

We pass in a reflector because we need to access the request here. The return from canActivate() determines if a request to invoke a controller can actually activate the code controller code or be rejected. If this function returns true, then the request is allowed to pass through. Otherwise it is stopped.

We have used something new here. It’s the IS_PUBLIC_KEY. We will define this in the next section. Basically, for public routes, this key will be set to true in the request metadata for public routes through a controller decorator. Similarly, for the Google Login route, we will allow the function to return true. So, if we find that the incoming request is for a public route or for our login route then it is allowed otherwise it needs to go through the JWT Auth pipeline to find out if it's coming from an authenticated user who is authorized to access our routes.

Decorators for Routes in NestJS

If you have a basic knowledge of NestJS, you’d know what decorator tags are. We will need to define custom decorators to pick up the decoded JWT user object from requests and for public routes. Create a decorators folder on the same level as strategies and guards and then follow the explanations below.

Public Route Decorator

Public routes will have their controllers attached to this decorator so that the user can just pass through. The Code content for the public.decorator.ts is really simple for this as shown below. We just set the Metadata of the request so that the isPublic is set to true once the user request enters the NestJS pipeline.

`typescript
import { SetMetadata } from '@nestjs/common';

export const IS_PUBLIC_KEY = 'isPublic';
export const Public = () => SetMetadata(IS_PUBLIC_KEY, true);

HTTP Auth User Decorator

We need to create a @HttpUser decorator which will pick the user (coming from the decoded JWT) object from the HTTP request. This will be used for authenticated routes that require the logged-in user details. For this, create a file called http-user.decorator.ts and paste the code below.

`typescript
import { createParamDecorator, ExecutionContext } from '@nestjs/common';

export const HttpUser = createParamDecorator(
(_data: unknown, ctx: ExecutionContext) => {
const request = ctx.switchToHttp().getRequest();
return request.user;
},
);

In the above code, we get the ExecutionContext. This allows us access to the request and response objects in NestJS (though we only need to use the request part here). At line 5 we get the request and then at line 6 send the user. We could have used the data argument for custom operations. But that’s not needed here.

GraphQL Auth User Decorator

Similar to the decorator for extracting decoded user from HTTP requests, we need one for GraphQL requests. We need to put the code below inside graphql-user.decorator.ts. The code below does exactly what the decorator above does but for GraphQL requests.

`typescript
import { createParamDecorator, ExecutionContext } from '@nestjs/common';
import { GqlExecutionContext } from '@nestjs/graphql';

export const GraphQLUser = createParamDecorator(
(_data: unknown, context: ExecutionContext) => {
const ctx = GqlExecutionContext.create(context);
return ctx.getContext().req.user;
},
);

Adding Supabase to Nest

Now, we will add Supabase to our NestJS project. We will be using Prisma to connect to our Supabase Instance. At the heart of Supabase is a Postgres instance and Prisma can be used to connect to it and run queries with ease. Run npm i -D prisma to add it to our project and then run npx prisma init to initialize Prisma in our NestJS project. Additionally, we will also need the Prisma client to use Prisma in our project. So go ahead and run npm i @prisma/client.

Note how prisma is a dev dependency but @prisma/client is not a dev dependency.

Difference between DATABASE_URL and DIRECT_URL in Supabase

DIRECT_URL (1.) allows us to directly connect to the Supabase instance without our connection being pooled. It is like an admin link to connect to the underlying Postgres DB. It is good for migrations and introspections. It connects directly to Port 5432.

But DATABASE_URL (2.) is the more general link to connect to DB to run queries. The connections through this link are pooled. These are good for in-code usage. This does not connect to port 5432 but a mapped port and link which can be different for every Supabase user.

Creating a Prisma Module in NestJS

There is an NPM package called nestjs-prisma which can be used to provide connectivity between a NestJS and a DB using Prisma within a matter of seconds. It also comes with a Global Exception Filter to handle Prisma query-related errors. But I find creating a custom module to be a better way. So that’s what we are going to do here.

We don’t need controllers since the PrismaModule we are about to create won’t handle any endpoints. We just need a module and a service to encapsulate the business logic. So, we need to run two separate Nest CLI commands successively - nest g module prisma and nest g service prisma –no-spec. This will create a folder called prisma inside our src folder.

We just to slightly edit the prisma.module.ts file by adding the @Global() decorator to the PrismaModule we just created as shown below. Along with this, we will also add PrismaService to the list of exports. This will allow us to use the service in any module without importing it.

`typescript
import { Global, Module } from '@nestjs/common';
import { PrismaService } from './prisma.service';

@global()
@Module({
providers: [PrismaService],
exports: [PrismaService]
})
export class PrismaModule {}

For our PrismaService, we need it to inherit from PrismaClient (imported from @prisma/client) and then connect lazily to the DB. This can be done using the code below. Between lines 8 and 14, we provide the Database URL to Prisma for connection. This URL is available in the Supabase settings under Connection pooling custom configuration subsection in the Database tab (add the connection string with the password to our .env file). The code below shows our prisma.service.ts file.

`typescript
import { Injectable } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { PrismaClient } from '@prisma/client';

@Injectable()
export class PrismaService extends PrismaClient {
constructor(configService: ConfigService) {
super({
datasources: {
db: {
url: configService.get('DATABASE_URL'),
},
},
});
}

}

Schema Introspection with Prisma

We won’t be defining the Schema. We won’t be copy-pasting it either. We will be using this cool feature called DB Introspection. Prisma will connect to the Postgres DB inside Supabase and automatically fill the schema.prisma file with the Schema of the tables inside the DB instance.

But to connect to the DB instance and introspect, we will not be using the DATABASE_URL. We will be using the DIRECT_URL. This can also be found in the Supabase settings in the Database tab under the Connection String sub-section. Add this to our .env file and then inside the schema.prisma file at the base of our backend project, add it to the datasource. Our schema.prisma file will look like this.

`
generator client {
provider = "prisma-client-js"
}

datasource db {
provider = "postgresql"
url = env("DATABASE_URL")
directUrl = env("DIRECT_URL")
}
`

After this, we need to run npx prisma db pull and leave the rest to Prisma. When this command completes, our schema.prisma file will be populated with the schema of the tables already in our Supabase instance.

So now we have our schema ready and our project connected to the Supabase instance we created in the last article.

Authentication Endpoints (AuthModule)

After all of these steps, we will now move towards amalgamating what we have done in this sub-section. That starts with the creation of the AuthModule. In NestJs, you can easily create a set of controller endpoints, abstract the logic to a service, and create a complete module to use these through just a single line of code. Run nest g resource auth –no-spec to create the AuthModule. Keep in mind that our AuthModule will consist of REST API endpoints only and we only need 2 custom controllers which we will define ourselves below so no need to create the CRUD endpoints through this CLI.

On completion of the above command, an AuthModule will be created and imported into our main AppModule. Since we used the --no-spec file with the Nest CLI, no test files will be created. We will a Data Transfer Object or DTO to hold the Google User profile information. For this reason, create a dto folder inside the auth folder if you don’t have any, and then create a file called google-login.dto.ts. This file will contain our Google Profile info as given below.

`typescript
export class GoogleLoginUserDto {
providerAccountId: string;
email: string;
email_verified: string;
firstName: string;
lastName: string;
picture: string;
accessToken: string;
refreshToken: string;
id_token: string;
expires_in: number;
}

Next, move to the auth.controller.ts file and replace the contents of the file with the code below. In the code below, we define two endpoint routes at lines 15 and 18. Both of them will handle GET requests so they are annotated with the @Get() decorator. The AuthController will serve the base endpoint /auth. In line 9, we tell NestJS to set google-login metadata key as true for every request directed towards the AuthModule controller. This will allow the requests to by-pass the global JWT guard that we will set in a few moments.

At line 10, we are telling NestJS that any requests to this Controller are supposed to first pass through HttpGoogleOAuthGuard that we defined in the above sub-section. This can be observed from the @Controller(‘auth’) decorator at line 11 below.

`typescript
import { Controller, Get, Req, SetMetadata, UseGuards } from '@nestjs/common';
import { AuthService } from './auth.service';
import { Request } from 'express';
import { HttpUser } from 'src/decorators';
import { HttpGoogleOAuthGuard } from 'src/guards';
import { GoogleLoginUserDto } from './dto/google-login.dto';

@SetMetadata('google-login', true)
@UseGuards(HttpGoogleOAuthGuard)
@Controller('auth')
export class AuthController {
constructor(private readonly authService: AuthService) {}
@Get()
async googleAuth(@Req() _req: Request) {}

@Get('google-redirect')
googleAuthRedirect(@HttpUser() user: GoogleLoginUserDto) {
return this.authService.googleLogin(user);
}
}

Through the above code, we define the authN flow. Any login requests will come to /auth (GET) endpoint and be handled by the controller at line 15. Without any effort of ours, the user will be redirected to the Google Login page. After their login, they will be re-directed from Google to /auth/google-redirect endpoint which will be handled by the controller at line 18. This controller will receive the Google User profile data and will load that into the GoogleLoginUserDto for us with the help of @HttpUser() decorator which we defined before. We pass this user data to the googleLogin() method of the AuthService inside auth.service.ts file. The contents of the auth.service.ts are shown below.

`typescript
import { Injectable, UnauthorizedException } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { JwtService } from '@nestjs/jwt';
import { PrismaService } from 'src/prisma/prisma.service';
import { GoogleLoginUserDto } from './dto/google-login.dto';

@Injectable()
export class AuthService {
constructor(
private jwtService: JwtService,
private configService: ConfigService,
private prisma: PrismaService,
) {}
async googleLogin(user: GoogleLoginUserDto) {
if (!user) {
throw new UnauthorizedException('No user from google');
}
const {
firstName,
lastName,
email,
email_verified,
expires_in,
picture,
providerAccountId,
accessToken,
refreshToken,
id_token,
} = user;
const userData = await this.prisma.users.findFirst({
where: { email},
include: { accounts: true },
});
if (!userData) {
const newUserData = await this.prisma.users.create({
data: {
name: ${firstName} ${lastName},
email: email,
emailVerified: email_verified? (new Date()).toISOString(): null,
image: picture,
accounts: {
create: {
type: 'oauth',
provider: 'google',
providerAccountId: providerAccountId,
access_token: accessToken,
refresh_token: refreshToken,
id_token: id_token,
expires_at: expires_in,
},
},
},
});
const access_token = await this.signJwt(
newUserData.id,
id_token,
accessToken,
expires_in,
);
return { access_token };
}
const access_token = await this.signJwt(
userData.id,
id_token,
accessToken,
expires_in,
);
return { access_token };
}
signJwt(
userId: string,
id_token: string,
access_token: string,
expires_at: number,
expiresIn = '1d',
): Promise {
const payload = {
sub: userId,
id_token,
access_token,
expires_at,
};
return this.jwtService.signAsync(payload, {
expiresIn,
secret: this.configService.get('APP_JWT_SECRET'),
});
}
}

In the service above, we will need:

JwtService for minting a new auth_token (used for authZ) to the user.
PrismaService to query the Supabase DB to find if it’s a new user or not.
ConfigService to fetch the JWT secret (APP_JWT_SECRET env variables).

We define these in the constructor of the AuthService class. These will be injected by the NestJS runtime. We use the private shorthand to make it class-scoped. Inside the googleLogin() function, we check if Google has passed us a valid user or not at line 15. If not, then terminate the request.

If a valid user profile has been sent from Google, then at line 30 we query the Supabase DB’s User table to find if we have a user with the same email as sent by Google. If we don’t then it's safe to assume that it’s a new user. So, with the check at line 34, we insert the user into our User Table and create an entry in the Account table. We then create our auth_token called access_token and send it back as the response. If the user already exists, then we simply mint a authZ JWT and send it back regardless between lines 62 and 68.

Between lines 70 and 87, we define a wrapper for JWT minting. This wrapper, called signJwt(), takes the user ID from our User table, the opaque access_token, id_token & expires_at passed by Google to use and uses these as a payload to create a new JWT.

Importing Strategies and Attaching Guards

Now before we finish off the AuthModule, there are a couple of things still pending. We need to add the JWT Auth Guard we created Globally. We also need to import the Google OAuth Strategy and JWT Strategy in our AppModule so that it is recognized app-wide.

For registering our Auth guard globally, we can just register it locally in any of the modules as a provider. Since we have created an AuthModule, that’s where we are going to add it to. Our AuthModule would, thus, look something like this:

`typescript
import { Module } from '@nestjs/common';
import { AuthService } from './auth.service';
import { AuthController } from './auth.controller';
import { APP_GUARD } from '@nestjs/core';
import { JwtAuthGuard } from 'src/guards';

@Module({
controllers: [AuthController],
providers: [
AuthService,
{
provide: APP_GUARD,
useClass: JwtAuthGuard,
},
],
})
export class AuthModule {}

Finally, we can import our strategies into our main app module. With all the changes we have done above, our app module with the strategies would come to look something like the code given below:

`typescript
import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { ConfigModule } from '@nestjs/config';
import { AuthModule } from './auth/auth.module';
import * as Joi from 'joi';
import { GoogleStrategy } from './strategies';
import { PassportModule } from '@nestjs/passport';
import { JwtModule } from '@nestjs/jwt';
import { JwtStrategy } from './strategies/jwt.strategy';
import { PrismaModule } from './prisma/prisma.module';

@Module({
imports: [
ConfigModule.forRoot({
isGlobal: true,
validationSchema: Joi.object({
DATABASE_URL: Joi.string().required(),
DIRECT_URL: Joi.string().required(),
GOOGLE_CLIENT_ID: Joi.string().required(),
GOOGLE_CLIENT_SECRET: Joi.string().required(),
GOOGLE_CALLBACK_URL: Joi.string().required(),
APP_JWT_SECRET: Joi.string().required()
}),
}),
AuthModule,
PassportModule,
JwtModule.register({
global: true,
}),
PrismaModule,
],
controllers: [AppController],
providers: [AppService, GoogleStrategy, JwtStrategy],
})
export class AppModule {}

This completes our addition of Authentication and Authorization to our backend. It should be able to access the same Database as our frontend NextJS app does with Next Auth. This would mean all our user data is in one place and a user can independently login from the frontend and backend. This opens up avenues like using the backend for Mobile App (something that we won’t cover).

Testing out Backend

The coding part of creating an authentication and authorization flow is not complete. We will now begin testing our NestJS application to make sure everything works as we expect.

In the video demo below, we run npm run dev to start the Turbo dev server. Our NestJS backend starts at port 3001 of localhost. As per the design, we have 3 routes. Since the JWT Auth guard is being used globally, all route requests will pass through it unless the route controller is annotated with @Public() decorator. If you try to access http://localhost:3001/, it will give you an Unauthorized Message as shown in the video below.

{% embed https://youtu.be/dp8ZT_Wr_Mk %}

We first need to head over to http://localhost:3001/auth. From there, we will be redirected to Google Login as shown above. After Google login, we are redirected to http://localhost:3001/auth/google-redirect. This route controller takes in the Google OAuth profile sent back to our app and mints a JWT token. The access_token sent in our video is in fact the NextJS frontend app’s auth_token counterpart.

When we attach this as the bearer token in auth header, we see that we are shown the ”Hello World!” message on http://localhost:3001. This means our backend is working just as expected. You can try to head over to Supabase to verify if the user is created or not.

Frontend & Backend Interaction in a NextJS and NestJS app

The image above depicts the interaction diagram of our mini-project thus far. The Users come with their Authentication request and then

On the frontend, NextJS + Next-Auth handles it using the GoogleProvider.
On the backend, NestJS + Passport handles it using the GoogleStrategy. This provides two independent but co-operating avenues for AuthN.

Making the Next App Work with Nest Authentication

Now to make these interact, we will make a slight change to our SignoutButton component in the _components directory of our frontend NextJS project. We will make it so that the SignoutButton component logs the auth_token if the user is authenticated. We will take this auth_token JWT and use it as a bearer to access http://localhost:3001, i.e., the protected Nestjs backend route. If we receive a successful response then we can be sure that the auth_token is fulfilling its purpose as AuthZ token. Our SignoutButton component will look like this:

`typescript
"use client";
import { signIn, signOut, useSession } from "next-auth/react";
import React from "react";

const SignoutButton = () => {
const { data: session } = useSession();
console.log("Session data", session)
if (session?.user) {
return (

{session.user.name}

signOut()}>Sign Out

);
}
return signIn()}>Sign in;
};

export default SignoutButton;

While at it, we will also use a new Google User to sign in from our front end. This will make sure that Supabase creates a new record which will then be accessed independently from our backend as shown in the video demo below:

Conclusion

This concludes our long blog post. We finish what we had started in the first article of this series. With this, we have completed the Authentication and Authorization flow. We now have a NextJS app utilizing Next Auth and Google Provider which can interact with a NestJS backend app.

From the next article onwards, we will start building the core of our project. We will start with the backend and then move to the frontend. Until then keep building awesome things!

Next x Nest - Connecting your NextJs App to a NestJs Backend

Abhik Banerjee — Mon, 28 Aug 2023 19:11:30 +0000

As a Fullstack dev, there are plenty of times when you’d be involved in the creation of the backend while also helping out in the frontend. As a Web3 dev, that’s especially true since most frontend developers might know of react-query, swr and axios but not of ethersjs and viem. So, it tends to become a habit of sorts to help on the front-end side.

Quite recently, our company has been considering NestJs as a candidate for the backend stack. Having used it before, it’s really a no-brainer as to why someone would not want to utilize NestJs. There are other alternatives but when compared to barebones, from-scratch development using Express, I would always prefer a framework like Nest. It helps focus the development strategies while staying true to the underlying library (be it fastify or express). In short, it helps avoid chaos.

In my recent series, I have explored the usage of NextJS. But those were particularly Web3-focused. All things considered, it seemed like a next step – to explore how to use NextJS with Next Auth and combine that with a NestJS backend.

So, what to build & what would be the objectives?

But as with every series, a mini-project is needed. Seeing how creating a “Kanban Board App” is all the rage right now amongst frontend devs on Youtube using DND Kit, I thought why not give it a try ourselves? So, we will create an end-to-end sort of project in this series – A personal Kanban Board with:

NestJS in the backend
NextJs in the frontend
Next Auth handling the authentication on the frontend
Supabase for Auth DB on both ends
NoSQL DB for the backend

The objectives here would be to answer the following questions through the mini-project:

How to use NextAuth with Next Js and a Custom Backend?
How to configure Next Auth’s Google Provider to work with a custom Backend?
How to manage Authentication and Authorization when using Next Auth with Google or a similar provider and a custom Backend?
Can the Access Token and ID tokens from Next Auth providers be utilized with NestJS?
How to manage authentication on REST with a GraphQL backend in NestJs?
Can multiple Prisma providers be used in a single NestJS backend? If so, then how?

We won’t be answering all the questions outright in this article. In fact, along the way, there might be more questions added to the list. Rest assured, these questions will be answered by the time we reach the end of the series.

In this article, we will focus on how to use Next Auth with NextJs and make it talk securely with the NestJs Backend. Things become easier if we use CredentialsProviders of Next-Auth. If used with a NestJs Backend, one needs to utilize the authorize() method. Once the user enters the credentials on the frontend, this callback is invoked. The authorize() callback will send the credentials to the NestJs backend’s API. The NestJS Backend Auth API will receive the credentials (username and password or something similar) and if the user exists will send back an access token (JWT) or something. Back in the authorize() callback, when the access token is received, that will be included in the User’s session in the Next Auth through the session callback. Simple as that.

Things become a bit complicated with Next and Next Auth if you take into account Providers like Google, Gitlab, Github, and so on. These providers send back access_token and other similar tokens to next auth and are tied tightly to work seamlessly with NextJs and optionally a DB. The USP of NextJS (being a Fullstack framework aiming to provide completeness out of the box) also becomes a burden on some Devs trying to customize things to suit the use case.

What many devs fail to realize is that Next Auth, through these providers, is supposed to provide Authentication (authN). The Authorization (authZ) part of management still rests with us. It Must be configured by us. Say if the Google Provider provides access_token and id_token, should these be used for authZ? No. One should create their own methods of authZ. This can range from simple second JWTs in the session to LDAP.

But where to insert this mechanism? How do we insert it so that it can also function with a custom backend? One cannot simply leave the backend open to all requests. AuthN and AuthZ is needed there as well.

With these questions in mind, let’s get started with this series.

Housekeeping

Before we jump right into coding, there are some steps we need to take. This tutorial assumes basic familiarity with NestJS and NextJS. Knowledge of next auth is a plus but not mandatory. We would also need to use Supabase and Prisma. So, the reader should be familiar with the basics there as well.

Setting up Supabase

Just head over to supabase.com and signup if you haven’t already. Create a new project under the organization of your choice. In my case, I have selected the default org (called abhik-99). The project I have created is called “Next Fullstack” as shown in the image below. The image below shows the Supabase Dashboard after creating the project.

We will use the Next Auth quickstarts to get up and running fast. Click on your project, then click on the “SQL Editor” icon from the left panel (1.). Head over to “Quickstarts” as shown below (2.). After that click on “Next Auth Schema Setup” option as marked below (3.).

As shown in the image below, this will open the SQL Editor with the Statements to run (1.). Click on Run to execute those SQL statements (2.). Supabase will run those and create your tables for you. The schema name would be next_auth.

You might be tempted to think that this is it. But this is just half the process. Our schema is created. But by default, it is created as a private schema. So, while we can manipulate it from Supabase Dashboard, we will not be able to connect to the Supabase instance and query it. To make sure that the schema we created can be accessed using something like Prisma, we need to make it public. To make sure that queries can be run, we need to tell Supabase to insert a search_path for the schema. These two are separate steps which we will cover next.

As shown in the image above, to make our custom Supabase Schema accessible and query-able, we need to go to Settings (1.). After this, click on API (2.). This option will show you the essentials like the Service role key, anon key, and more. Scroll down to the API Settings. Here, we need to add our custom schema which in our case is next_auth (3.). This needs to be followed up with adding the same schema to the Extra Search Path option (4.). Click on Save to make sure these changes take effect.

This completes our Supabase setup. Next, we will move to setting up our NextJs and NestJs projects inside a mono repo.

Setting up NextxNest Project

Typically, one would first initialize the monorepo first and then add the required projects. But we won’t follow the general script of steps here.

We will first set up our sub-projects and then create a monorepo out of it all. This roundabout way of doing things will help answer the question “How do we create a Monorepo from an existing project?”. We will use Turborepo to handle the monorepo part of things and use NPM as the package manager.

Initializing NextJS

Setting up NextJs is really simple. All you need to run is npx create-next-app@latest. This will install create-next-app if you don’t have it already and then direct you through a series of questions. In our case, albeit the project name, everything else will be set to the default setting.

We will call our NextJS 13 project “frontend”. Following the prompts from the script, you should have a folder called frontend. This will be where we create (unsurprisingly) the frontend for our Kanban project. Integrating Next Auth and Supabase into NextJS will be covered in the later sections.

Initializing NestJS

The more convenient way of using NestJs is to install the NestJS CLI globally and use it again and again to create new projects, controllers, sub-apps, and microservices. Running npm I -g @nestjs/cli will do precisely that for you.

Assuming you have already done that, move to the parent folder of frontend and run nest new backend. If you get an error that the nest script cannot be found or something even after installing Nest CLI, try running npx nest new backend to see if it works.

This will create a Nest project called backend at the same level as our Next project called frontend. Make sure to remove the node_modules folders from both. Furthermore, move to the package.json inside backend NestJS project and rename the script start:dev to just dev. This will match the NestJs dev script with the dev script name in the NextJS project.

Additionally, find the main.ts file of your Nest project and change the PORT from the default 3000 to 3001. This will prevent a port collision between the NextJS project and our backend.

Creating a Monorepo

Lastly, we will create a Turborepo monorepo out of an already existing project. In the folder containing backend and frontend, run npm init. This will create the package.json we need. Once you have the package.json, we need to add turbo dependencies and the scripts along with denoting the workspaces.

Create a folder called apps and move the backend and frontend folders inside it. The apps folder is our workspace. The complete package.json will look something similar to the script below.

{
  "name": "your-jira",
  "version": "1.0.0",
  "description": "An end to end mini-project which explores using NextJs, Next Auth on the frontend and NestJs backend by making a lightweight Kanban board called \\\"Your Jira\\\".",
  "workspaces": [
    "apps/*"
  ],
  "keywords": [
    "nest",
    "next",
    "turborepo",
    "next-auth",
    "supabase"
  ],
  "author": "Abhik Banerjee",
  "packageManager": "npm@9.6.3",
  "devDependencies": {
    "eslint": "^8.47.0",
    "prettier": "^3.0.2",
    "tsconfig": "*",
    "turbo": "latest"
  },
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev",
    "lint": "turbo run lint",
    "format": "prettier --write \"**/*.{ts,tsx,md}\""
  },
  "license": "ISC"
}

Next, we need to create a Turbo script. This is done by creating a turbo.json file. This file contains the build, lint, test, and dev instructions. A simple turbo.json file might look like the script below. You may copy the turbo.json file below. The pipeline property is where we specify the instructions for build, lint, and test tasks. It also contains the instructions for running the project in Dev mode. In our case, we tell Turbo to not cache anything and every time something changes, rerun the script and refresh.

{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": ["**/.env.*local"],
  "pipeline": {
    "build": {
      "dependsOn": ["^build"]
    },
    "lint": {},
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

After all these steps, you may lastly add a .gitignore file. You can run npm i to install your dependencies globally. Following this, running npm run dev will start the dev server for both your backend and frontend simultaneously. Your directory structure should look something similar to the image given below.

Note: Normally, you’d have just one root tsconfig.json and have the individual apps inherit from this by the extends keyword. But I am choosing to be liberal here. So, we are going to have two separate tsconfig.json in this project for now. You may change that if you want.

Adding Next Auth and Supabase to Next

Now we move on to the first part of the integration. In this section, we will integrate Supabase with NextJS and use Next Auth for Authentication. You might be thinking “Well, where does NestJs fit into all of this?”. It doesn’t. All will be cleared as we go.

Adding Environment Variables to NextJs

Normally, you’d do something like just add a .env file and be done with it. But that’s not how we do things. If you have been following my previous articles, you’d know by now a better way to add Environment variables to Next.

First, head over to the root of the NextJS project. In our case, that is the root of the frontend folder (not the app folder mind you!). Next, create a file called additional-env.d.ts. This is where we will define the types of our environment variables. In our case, the file would look something similar to the Code file given below. The code file below contains all the env variables needed for this part of things.

declare global {
  namespace NodeJS {
    interface ProcessEnv {
      NODE_ENV: "development" | "production";
      NEXTAUTH_SECRET: string; //Session Secret
      APP_JWT_SECRET: string; //Authorization Token secret
      NEXTAUTH_URL: string;

      GOOGLE_CLIENT_ID: string;
      GOOGLE_CLIENT_SECRET: string;

      NEXT_PUBLIC_SUPABASE_URL: string;
      SUPABASE_SERVICE_ROLE_KEY: string;
    }
  }
}

// If this file has no import/export statements (i.e. is a script)
// convert it into a module by adding an empty export statement.
export {};

Add this file to be picked up by the TS server in this project. To do this, head over to the tsconfig.json of the frontend app, and in the include array add the name of this file. Lastly, create a .env at the same level and add the variable names to it.

The values for NEXT_PUBLIC_SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY can be obtained from the Supabase Settings. Head over to the API section in settings as shown in the Supabase section above and you will the respective values in the “Project URL” and “Project API Keys” section as shown below.

The remaining values will be discussed below.

Google Client Credentials

For using Google Sign-in, we will need Google API keys. These API keys will be used by the GoogleProvider of Next Auth. For these values, head over to the Credentials section of “API & Services” as shown below (1.). After this, click on Create Credentials as shown below. Then select ”OAuth client ID”.

In the next screen, you will need to select the ” Application Type” as “Web Application” (1.). This will prompt you for a name for the App (2.). In our case, I have named it “Your Jira” (pretty presumptuous). The ”Authorized Javascript Origins” records the URLs from where the OAuth requests can originate. In our mini-project, the Sign-in requests can independently originate from the frontend and backend (running on localhost:3000 and localhost:3001 respectively). So, we will need to add them both.

”Authorized redirect URIs” represent the locations where the user will be redirected to after the user selects which Google account to sign in from. Again, this will need to be 2 URIs – one for frontend and another for backend. Clicking on Create will create the OAuth Client and give you the client IDs as shown below. In the image below, you will see 2 client secrets. That’s because I have purposefully generated two different client secrets. But you can work with just one. This will be the GOOGLE_CLIENT_SECRET.

You will get the client ID in the first screen in this subsection after you create your OAuth. This will serve as the value for our GOOGLE_CLIENT_ID. With this, we have the Google bit of things with us.

Integrating Next Auth

All this time, it has been just setup and setup. And now, more so 😊

To get started with integrating Next Auth into our Next JS app, head over to the frontend repo. Create a folder called api. Inside this, create another folder called auth. Finally, create a folder called […nextauth] (the name is really important here). Inside this folder, create a file called route.ts. The directory structure should look something similar to the image shown below (do not pay attention to other folders starting with _, we will get to them).

Basically, we are defining a backend API route /auth which Next Auth will handle. The route controllers are defined inside the route.ts file and will look something similar to the code below. In the code below, we build the core of the NextJS Authentication system.

In line 7 below, we start to define our Next Auth handler. Inside the providers array is where we keep all our authentication providers. This shouldn’t be anything new if you have been following my past articles. The difference here is that instead of using CredentialsProvider as we have up till now, we are now using the GoogleProvider. Inside the GoogleProvider constructor, it’s mostly the default options. We are passing in our GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET which we obtained from the section above. We also tell the provider that we want a prompt for consent of the user everytime and we want the offline mode of authentication. This will make sure that we get a refresh_token.

import { signJwt } from "@/app/_lib/jwt";
import { SupabaseAdapter } from "@auth/supabase-adapter";
import { Adapter } from "next-auth/adapters";
import NextAuth from "next-auth/next";
import GoogleProvider from "next-auth/providers/google";

const handler = NextAuth({
  providers: [
    GoogleProvider({
      clientId: process.env.GOOGLE_CLIENT_ID,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
      authorization: {
        params: {
          prompt: "consent",
          access_type: "offline",
          response_type: "code",
        },
      },
    }),
  ],
  session: {
    strategy: "jwt",
  },
  adapter: SupabaseAdapter({
    url: process.env.NEXT_PUBLIC_SUPABASE_URL,
    secret: process.env.SUPABASE_SERVICE_ROLE_KEY,
  }) as Adapter,
  callbacks: {
    async jwt({ token, account }) {
      if (account) {
        token.auth_token = await signJwt({
          sub: token.sub,
          id_token: account.id_token,
          access_token: account.access_token,
          expires_at: account.expires_at,
        });
      }
      return token;
    },
    async session({ session, token }) {
      session.auth_token = token.auth_token as string;
      return session;
    },
  },
});

export { handler as GET, handler as POST };

Now, we need to explicitly set strategy to JWT here. Because we are using a DB in the form of Supabase, Next Auth will by default use the session strategy. But in our mini-project, we are going to use JWTs. We set the Supabase Adapter options at line 24. Mostly default options here.

PS: If you haven’t already, run npm i @auth/supabase-adapter.

The callbacks part is crucial. Normally, Next Auth and NextJS work seamlessly to manage sessions. This also includes encryption and decryption of session JWTs. But we want to use another custom JWT. This is where the jwt() callback comes in. This callback is invoked whenever JWT creation or updation is needed. Since we are using the jwt strategy, this callback will be invoked time and again. This callback receives the decrypted Next Auth JWT token. During Sign-in, this callback also receives another parameter called account which contains the details sent back by the provider.

In our case, GoogleProvider will send back the id_token, access_token and expires_at which we will use to create our own custom JWT token using the signJwt() method. This custom, encrypted JWT will be attached to the token through the auth_token property.

The Next Auth Token comes from the jwt() callback to the session() callback. In the session() callback, we will once again need to add the auth_token property taken from token into the session object. This will make sure that whenever we access the session on the frontend after sign in, we get the custom JWT token. This is how we should customize Next Auth when using it with Third Party providers like GitlabProvider, GithubProvider and in our case, GoogleProvider.

This custom JWT token will be used as an authorization token. Basically, this authZ token is our way of interacting with the NestJs backend while the access_token and id_token acts as the authN token and tells us we are interacting with a valid Google User. The code below is what we keep inside a separate jwt folder inside the _lib folder.

import jwt from "jsonwebtoken";

export const signJwt = async (payload: any, expiresIn = "1d") => {
  const token = await jwt.sign(payload, process.env.APP_JWT_SECRET, {
    algorithm: "HS512",
    expiresIn,
  });
  return token;
};

export const verifyJwt = (token: string) => {
  const data = jwt.verify(token, process.env.APP_JWT_SECRET, {
    algorithms: ["HS512"],
  });
  return data
};

As you can see, the above code is just a wrapper around JWT creation. The APP_JWT_SECRET serves as the secret key for our custom JWT. This secret needs to match the JWT secret on the Nest backend end for the whole thing to seamlessly work.

Lastly, create a types folder, and inside it, create a next-auth.d.ts file. Paste the following code inside it. This piece of code tells Next Auth that in addition to whatever Next Auth is sending inside the session of a signed-in user, we want to include our custom property called auth_token (which will hold our authZ JWT token).

import NextAuth from "next-auth"

declare module "next-auth" {
  interface Session extends Session {
    auth_token: string;
  }
}

With this, we have fully integrated Next Auth with Google OAuth Provider into our NextJS project and customized it to interact with a custom NestJS backend.

Adding an AuthContext, Appbar and Sign In button

Firstly, to use Next Auth client side, we need to wrap our app in a Context. Luckily, Next Auth provides us with that out of the box. We will follow the convention we have been using thus far in my articles and create a _providers folder which will contain all the providers (keep in mind the files inside this folder will have .tsx extension since they will be used on the frontend side). The Root provider will then be wrapped around the root layout (layout.tsx file at the root of the app folder inside frontend). The image below shows the intended code.

Next, create a _components folder and create a SignoutButton.tsx component. We will make this a client component. It will handle the authentication flow from the client side. Inside the component, we import the useSession() hook from Next Auth as shown below. This hook will provide the session data. The session object (renamed from the data property destructured from the returns of the hook) will contain a user property.

"use client";
import { signIn, signOut, useSession } from "next-auth/react";
import React from "react";

const SignoutButton = () => {
  const { data: session } = useSession();
  if (session?.user) {
    return (
      <div className="flex gap-4 ml-auto">
        <p className="text-sm tracking-tight text-sky-400">
          {session.user.name}
        </p>
        <button onClick={() => signOut()}>Sign Out</button>
      </div>
    );
  }
  return <button onClick={() => signIn()}>Sign in</button>;
};

export default SignoutButton;

This user property will contain the session details. Thanks to all the changes we did in the previous subsection, this user property will contain also the auth_token which can be used to interact with the Nest Backend. The absence of this user property will tell us that the user has not authenticated. We will display “Sign In” if so. Otherwise, we will display “Sign Out”.

NOTE: you have used multiple providers for authN and you would like to customize the Sign In page, then in the signOut() and signIn() functions you would need to also provide the ID of the providers. But here we will use the Sign In page provided automatically by Next Auth. So, we do not need to pass anything to these functions.

After this, we need to create a simple Appbar. For this, create a component called Appbar.tsx inside the _components folder. As shown in the code section below, it will be a server component. Since we are not using any hooks or client-side interaction, we can limit the interactivity provided by client components to the SignoutButton component only.

import React from "react";
import SignoutButton from "./SignoutButton";

const Appbar = () => {
  return (
    <header className="flex justify-end gap-4 p-4 bg-gradient-to-b from-blue-900 to-black shadow">
      <SignoutButton />
    </header>
  );
};

export default Appbar;

Lastly, add the above Appbar component to the root layout.tsx like done below and that’s it! We have completed our integration of Next Auth and Supabase into NextJS app. In the next section, we will just test out the functionality developed thus far.

import "./globals.css";
import type { Metadata } from "next";
import { Inter } from "next/font/google";
import Providers from "./_providers/Provders";
import Appbar from "./_components/Appbar";

const inter = Inter({ subsets: ["latin"] });

export const metadata: Metadata = {
  title: "Create Next App",
  description: "Generated by create next app",
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body className={inter.className}>
        <Providers>
          <Appbar />
          {children}
        </Providers>
      </body>
    </html>
  );
}

Testing out Frontend

The frontend NextJs app will interact with the Supabase instance that we have previously provisioned through Next Auth. Next Auth will use Google OAuth 2.0 through the GoogleProvider and the client credentials we picked up from the Google Cloud Console. To run our apps, just run npm run dev and Turbo will take care of the rest. Our backend and frontend will start parallelly.

If the user signing in is a new user, then a new entry is created in Supabase in the users table. Along with this, another related record is created in the accounts table. The former is for storing your user profiles while the latter stores all the providers that the users in your users table have used to sign in. The real magic of the accounts table becomes clear when using multiple OAuth providers. But here, for the sake of simplicity, we will just use Google OAuth 2.0.

Conclusion

This concludes the first article in the series. While I wanted to complete the integration Passport and NestJS and show a working demo, I realize that the article has become too long.

For this reason, I will conclude this article here abruptly and in the next article, we will cover the NestJS + Passport + Supabase part and use the auth_token JWT from frontend to interact with the backend.

Until next time, take care and continue to build awesome things!

NextJS 13 – Why You Should use Viem instead of Ethers?

Abhik Banerjee — Tue, 15 Aug 2023 13:58:52 +0000

Before I start, I would like to say a couple of things. First, is an apology. I am sorry for not being active and being so late with the last article (Sorry Sayantan and all those who have been waiting on this). Got entangled in some work.
Secondly, it has been rightly pointed out to me by one @johnwitcher about the bug in Next Auth version 4.21.1. This bug causes the getCsrfToken() to resolve to undefined. The solution to this is to send headers of your request instead of the whole request object. The code with getCsrfToken() would thus become:

await getCsrfToken({ req: {headers: req.headers })

We use this in our mini-project during authentication for getting a nonce value for SIWE. That’s where this change needs to be included. The full solution to this can be found on this recent GitHub Issue and I would like to extend my thanks to the community member who pointed it out and to the devs who provided the solution.

Great! So now that we have that out of the way, lets get the show on the road for one last time in this series.

Housekeeping

The code discussed in this tutorial and the mini-project for this series is available at this GitHub Repo:

abhik-99 / NextJS-Blog

This repo contains code for the "NextJS - How to Web3?" blog series. It contains a Next 13 App styled with Tailwind. The app uses WalletConenctV2, Wagmi and Viem.

Now, when we last left off, we had created a hidden page, integrated Wagmi, WalletConnect v2 and sparingly used Viem. We had also integrated Next Auth with our NextJs 13 project in such manner that that Next Auth was being used in conjunction with WalletConnect v2 and SIWE (Sign-in with Ethereum). This is the last article in series and in this one we take the final step towards completing this mini-project.

In this article, we will modify our Authenticated/Hidden page and make it so that it can be used to interact with Smart contract. For the purpose of this tutorial, I have deployed a simple Greeting Smart contract (which will serve as a simple example) and an NFT smart contract (example 2) beforehand on Polygon Mumbai Testnet. We will use Wagmi hooks to interact with these two contracts on Mumbai Testnet. The smart contracts are also available in the aforementioned repo. Towards the end of the tutorial, the hidden page will look something like the page shown below.

To that end, we will need to create a components directory inside app directory of our NextJs project. Now we will try to make sure that we can render on the server as much as possible. For the client-side rendered components, we will use Dynamic Modules in NextJs 13 to have lazy loading. Inside the components directory folder, create three more folders -example1, example2 and ui.

We will store our reusable UI components in the ui folder. While the code for interacting with smart contracts will be in example1 and example2. Additionally, we will also need to create a folder called blockchain in the project root (at the same level as app folder). This is the folder where we will keep the ABIs of the deployed contracts.

The addresses of the deployed contracts will be stored in Environment variables called NEXT_PUBLIC_GREETING_CONTRACT and NEXT_PUBLIC_NFT_CONTRACT. These will be of type 0x${string}. This is the type of string that Wagmi and Viem accept. We can have this conversion done while we use these variables in the Wagmi and Viem-related codes but because of our usage of additional-env.d.ts file, we can easily do it in one-step. This means we won’t have to use something like process.env. NEXT_PUBLIC_GREETING_CONTRACT as 0x${string} in our actual code. Our additional-env.d.ts file would thus look like this:

declare global {
  namespace NodeJS {
    interface ProcessEnv {
      NODE_ENV: "development" | "production";
      NEXT_PUBLIC_W3C_PID: string;
      NEXT_PUBLIC_SIGNIN_MESSAGE: string;
      NEXTAUTH_SECRET: string;
      SIWE_DOMAIN: string;
      NEXT_PUBLIC_GREETING_CONTRACT: `0x${string}`;
      NEXT_PUBLIC_NFT_CONTRACT: `0x${string}`;
    }
  }
}

// If this file has no import/export statements (i.e. is a script)
// convert it into a module by adding an empty export statement.
export {};

Make sure to add the env variables in your .env file as well. In our case, we need to place the .env file in the root of our frontend folder of the repo (GitHub repo mentioned above).
We will take a bottom-up approach to building our project. We will create a layout for your card component, an encapsulated button component with our custom style, a sign-out button and then the examples. The final step would be putting it all together on the hidden page of our NextJs 13 project. This completes the housekeeping part and now we move to creating the UI parts.

Reusable UI Components

A Styled Button with Tailwind CSS

Since we are using a lot of many buttons in our mini-project, it is a good idea to create single-styled button components which would aggregate the CSS properties and allow us to customize them as well. This would prevent the use of overly long and repetitive class names. In our case, we use the code below to create a styled button.

'use client'
import React, { ButtonHTMLAttributes, ReactNode } from "react";
import cx from "classnames";

type StyledButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
  color: "red" | "green" | "blue" | "pink" | "yellow" | "violet";
  children: ReactNode;
};
const StyledButton = ({
  children,
  color,
  ...otherProps
}: StyledButtonProps) => {
  const colorClass =
    color === "red"
      ? "bg-red-700 hover:border hover:border-red-700"
      : color === "yellow"
      ? "bg-yellow-400 hover:border hover:border-orange-700"
      : color === "violet"
      ? "bg-violet-700 hover:border hover:border-violet-700"
      : color === "blue"
      ? "bg-blue-700 hover:border hover:border-blue-700"
      : color === "green"
      ? "bg-green-500 hover:bg-green-800 hover:shadow-[0px_0px_15px_5px_green]"
      : "bg-pink-700 hover:bg-pink-900 hover:border-none hover:shadow-[0px_0px_15px_5px_pink]";
  return (
    <button
      className={cx("rounded-lg py-2 px-4 hover:bg-transparent", colorClass)}
      {...otherProps}
    >
      {children}
    </button>
  );
};

export default StyledButton;

This code needs to go inside StyledButton.tsx inside ui folder. Most of the code above is React-specific. You shouldn’t have any problem understanding the above. But just for the sake of completeness let’s go over it once.

We make our button a client-component. Now in a production-grade project, I really prefer to have separate styled buttons – one for the server and another for the client. The Server rendered button components are for things like Form Submission actions and Links in NextJS 13. While the client-rendered ones I would use wherever a state-based interaction is needed.

Since this is a mini-project, I have just stuck with a single client-rendered button. Between lines 5-8, we define the props this button can expect. To make our lives easier, we merge this with the ButtonHTMLAttributes<HTMLButtonElement> props. This basically says – “expect anything a simple button component might take and also take in the props I define after the &”. Between lines 14 and 25, we just create a conditional class. This applies the color which is passed as props to this component. The classnames package is mighty helpful at line 28. It allows us to first define a class name which will be applied by default followed by the conditional ones.

Card Layout

Next Up, the card component. The code below goes inside Card.tsx in the ui folder. Again, its not any voodoo. It’s just plain React Code. We just make a container to house our examples. Notice that this component is server rendered unlike our button above. This helps us minimize the client-rendered parts and provides us with “Islands of Interactivity” – a term you would hear a lot with NextJs13 and frameworks like Astro.

import React, { ReactNode } from "react";

type CardPropsType = {
  children: ReactNode;
};

const Card = ({ children }: CardPropsType) => {
  return (
    <div className=" mt-5 bg-gray-800 border-2 border-gray-600 p-4 rounded-lg w-1/3 min-w-max text-gray-200">
      {children}
    </div>
  );
};

export default Card;

Non-Reusable UI Components

Sign-out Button

We abstract away the details of our sign out logic to the SignoutButton placed inside the components directory. The logic itself is explained in the previous article. This allows for the button to be used wherever we want a way for the user to exit. In our case, we put it in the App bar discussed next.

"use client";
import { useDisconnect } from "wagmi";
import { signOut } from "next-auth/react";
import React from "react";
import StyledButton from "./ui/StyledButton";

const SignoutButton = () => {
  const { disconnectAsync } = useDisconnect();
  const handleSignout = async () => {
    disconnectAsync();
    signOut({ callbackUrl: "/" });
  };
  return (
    <StyledButton color="red" onClick={handleSignout}>
      Sign Out
    </StyledButton>
  );
};

export default SignoutButton;

The Code above contains the logic which uses Wagmi hook useDisconnect() and redirects the user back to the homepage. Since we need the on-click interaction here, we make this component a client component.

Simple Appbar with Tailwind

The Code below contains the styled appbar we are going to use in our project.

import React from "react";
import Image from "next/image";
import logo from "@/public/logo192.png"
import SignoutButton from "./SignoutButton";

const CustomAppbar = () => {

  return (
    <nav className="bg-none">
      <div className="max-w-screen-xl flex flex-wrap items-center justify-between mx-auto p-4">
        <a href="https://abhikbanerjee.com/" className="flex items-center">
          <Image
            src={logo}
            className="h-12 w-12 mr-3 rounded-xl hover:shadow-[0px_0px_15px_5px_green]"
            alt="Abhik Banerjee Logo"
          />
        </a>

        <div className="hidden w-full md:block md:w-auto" id="navbar-default">
          <ul className="font-medium flex flex-col p-4 md:p-0 mt-4 border border-gray-100 rounded-lg bg-gray-50 md:flex-row md:space-x-8 md:mt-0 md:border-0 md:bg-white dark:bg-gray-800 md:dark:bg-gray-900 dark:border-gray-700">
            <li>
              <SignoutButton />
            </li>
          </ul>
        </div>
      </div>
    </nav>
  );
};

export default CustomAppbar;

Note that this is not a client component. We are basically telling NextJs that it can be rendered on the server side since we have encapsulated the signout logic to the SignoutButton component. This provides us with an island (the signout button) where users can interact with the site. While the rest of the component can be crawled since its server is rendered.

I have to credit Flowbite for the Appbar above. If you haven’t used them before, I’d highly encourage you check them out.

Example 1

In the first example, we will interact with the Greeting Contract which has been deployed on the Polygon Mumbai Testnet. The code for this is inside the example1 folder inside components. The overall look of it will be similar to the image below.
We will abstract away the logic into smaller, focused client components. These components (called GreetingGetter and GreetingSetter) will be lazily loaded into the GreetingCard component. The Code for the GreetingCard component is shown below.

import React from "react";
import Card from "../ui/Card";
import dynamic from "next/dynamic";

const GreetingGetter = dynamic(
  () => import("./GreetingGetter"),
  { ssr: false }
)

const GreetingSetter = dynamic(
  () => import("./GreetingSetter"),
  { ssr: false }
)

export const GreetingCard = () => {
  return (
    <Card>
      <h3 className="text-xl font-bold text-gray-400">Example 1:</h3>
      <GreetingGetter />
      <GreetingSetter />
    </Card>
  );
};

Lines 5-13 are of interest in the above code section. This is where we use the dynamic imports for the components. We tell NextJs to not load these components on the server (ssr:false). This is why, these components will be loaded when the page is first loaded on the client. This is why there would be some delay.

Get Greeting

First up, let’s have the getter component. Here, we will use the long way to do contract reads. We will fetch the Public Client from Viem and then make a contract read call. Normally, you’d do this with one step using the useContractRead() hook from Wagmi. But this method will allow you to find some similarities between Ethers and Viem. The code for the component is shown below:

"use client";
import React from "react";
import { usePublicClient } from "wagmi";
import greeterAbi from "@/blockchain/greeter_abi.json";
import StyledButton from "../ui/StyledButton";

const GreetingGetter = () => {
  const [greeting, setGreeting] = React.useState<string>();
  const publicClient = usePublicClient();
  const greetingGet = async () => {
    const data = await publicClient.readContract({
      address: process.env.NEXT_PUBLIC_GREETING_CONTRACT,
      abi: greeterAbi,
      functionName: "greeting",
    });
    setGreeting(data  as string);
  };
  return (
    <div className="flex flex-col justify-center items-center bg-black p-4 rounded-lg border-2 border-gray-600 my-4">
      <h4 className="text-xl font-semibold text-gray-400">Get Greeting</h4>
      <p className="block w-full my-4 text-gray-200">
        <b>Greeting:</b> {greeting}
      </p>
      <StyledButton onClick={greetingGet} color="green">
        Get
      </StyledButton>
    </div>
  );
};

export default GreetingGetter;

At line 8 we declare a state variable which will contain the Greeting. Now we could have easily created a custom hook which would have used useState, useEffect from React and usePublicClient() hook from Wagmi but that would defeat the purpose.

We fetch the pubic client using the usePublicClient() hook. Since we have made our config “chain-aware” and also because we are only using Polygon Mumbai Testnet, we do not need to pass in the chainId to force the Public Client to connect to a specific chain.

We have the greetingGet function which helps us fetch the value of the greeting variable in the smart contract. We pass in the address, the ABI and the function name to invoke to the readContract() method of the public client.

Keep in mind, the data returned here will be a Big Number if its integer. However, in our case, data is just a string. We need to additionally typecast it to string using data as string while setting the greeting state variable in our component.

Once something clicks on the Get Button, we fetch the greeting.

Set Greeting

GreetingSetter component is a bit more interesting. When WalletConnect connects to our wallet, it fetches a list of accounts from it. We can use the account with which we have signed the message with useAccount() hook of Wagmi. This is needed when invoking a write function on the smart contract.
Similar to the code above, we could have used a wallet client (Viem counterpart of signer from Ethers) and invoked the setter. But as shown in the code below, we use Idiomatic React.

"use client";
import React from "react";
import { useAccount, useContractWrite } from "wagmi";
import greeterAbi from "@/blockchain/greeter_abi.json";
import StyledButton from "../ui/StyledButton";

const GreetingSetter = () => {
  const { address: account } = useAccount();
  const { write } = useContractWrite({
    address: process.env.NEXT_PUBLIC_GREETING_CONTRACT,
    abi: greeterAbi,
    functionName: "setGreetings",
    account,
  });

  const greeting = React.useRef<HTMLInputElement | null>(null);
  const [value, setValue] = React.useState<string>("");
  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    setValue(e.target.value);
  };

  const handleSet = async () => {
    write({
      args: [greeting.current?.value],
    });
  };
  return (
    <div className="flex flex-col justify-center items-center bg-black p-4 rounded-lg border-2 border-gray-600 my-4">
      <h4 className="text-xl font-semibold text-gray-400">Set Greeting</h4>
      <input
        className=" block w-full p-2.5 bg-black rounded-lg border border-gray-600 placeholder-gray-400 text-gray-500 focus:ring-blue-500 focus:border-blue-500 my-4"
        ref={greeting}
        value={value}
        onChange={handleChange}
      />
      <StyledButton color="pink" onClick={handleSet}>
        Set
      </StyledButton>
    </div>
  );
};

export default GreetingSetter;

In the code above, at line 8, we fetch the address which is connected to our NextJs App (renaming it to account). Next we use the useContractWrite() hook from Wagmi. This hook is a wrapper around the WalletClient’s writeContract() method in Viem.

You might be confused here. How can we pass in the data beforehand and invoke the write method when we don’t have the greeting to set? Well that a natural way to think. The thing is, we pass in the bare minimum to initialize the hook between lines 9 and 14. The setGreetings on our smart contract is not invoked until we pass in our new greeting using the write method which the useContractWrite() Wagmi hook returns.

Lines 16 to 20 are just simple React way to handle User Input. When the use clicks on the Set Button, the handleSet() method is invoked which in turn creates a transaction by passing in the arguments to the function on the smart contract we had mentioned when initializing the contract write hook.

This will create a Metamask transaction. When the transaction succeeds, the user will have to click on Get button in the GreetingGetter component to fetch the new greeting.

This completes the first example. You might be thinking at this point, why not have the greeting automatically be updated inside our NextJs 13 app when the transaction succeeds? That would mean a smoother UI flow as well. In the next section, we will look into that. We will cover how to listen to a submitted transaction using Wagmi and Viem and based on transaction status, act inside our application.

Example 2

Now example 2 is a bit more complicated than the example above. In this example, we will interact with an NFT contract. We will fetch the balance of the address we are using to connect to our Next app and also use Wagmi and Viem hooks to mint a new NFT. I have already deployed a smart contract for this on Polygon Mumbai Testnet just like the example above. You can find the addresses of both the contract in the README.md inside the smart_contract directory.
The code for the NFTCard.tsx is simple enough as shown below.


import dynamic from "next/dynamic";
import React from "react";
import Card from "../ui/Card";

const MintSection = dynamic(
  () => import("./MintSection"),
  { ssr: false }
)

export const NFTCard = () => {
  return (
    <Card>
      <h3 className="text-xl font-bold text-gray-400">Example 2:</h3>
      <MintSection />
    </Card>
  );
};

In the code above, we just import the Client component MintSection as a dynamic import. That’s all really.

Fetch Balance

In the first part, we need to fetch the user balance. This is something that will be done as the component loads in. The code below does precisely that:

  const { address } = useAccount();
  const { data, isSuccess, isLoading, refetch } = useContractRead({
    address: process.env.NEXT_PUBLIC_NFT_CONTRACT,
    abi: nftAbi,
    functionName: "balanceOf",
    args: [address],
  });

We use the useAccount() hook from Wagmi to get the wallet address connected to our Next App. Then we use the useContractRead() hook to invoke the balanceOf function on our smart contract. Notice how we provide the arguments (our wallet address) in the args array. There are two things to note here:

If you want to invoke multiple read-type functions on a smart contract all at once, you would use the useContractReads() hooks. This is different from the useContractInifiteReads() which allows for fetching repeatedly kind of thing (ideal for fetching total value locked or any other live data).
The useContractReact() hook provides a refetch() method as shown above. This can be invoked to refresh the value of data manually.

The data will be a bignumber-ish value in our case. We will have to typecast it to string when using in our component to show the balance.

Mint an NFT

Next, we move on to minting a new NFT. This is interesting because it showcases how versatile using Wagmi hooks is. The code below contains the logic for minting an NFT using Wagmi hooks.

const { data: writeData, write } = useContractWrite({
    address: process.env.NEXT_PUBLIC_NFT_CONTRACT,
    abi: nftAbi,
    functionName: "safeMint",
    account: address,
  });
  useWaitForTransaction({
    hash: writeData?.hash,
    onSuccess() {
      refetch();
    },
  });
  const handleMint = async () => {
    write({
      args: [address],
    });
  };

As in example 1, we use useContractWrite() hook from Wagmi. But here we go a step further and watch the transaction. The data returned from useContractWrite() will contain the hash of the generated transaction. We pass that onto useWaitForTransaction() hook. This hook returns the Transaction Receipt as data. Since we do not need that here we do not consider the return values.

We provide the generated transaction hash to the useWaitForTransaction() Wagmi Hook. Then we use the onSuccess() callback to specify what to do if the transaction succeeds. A general doubt here can be “how can we pass the transaction hash in the hook until the transaction is created inside the handleMint() method?”. This is a very good doubt. Turns out, this hook does not run till it gets a valid hash. So, when we submit our transaction and generate a hash, this hook will automatically run and monitor the transaction.

It may also be noted that this hook also has callbacks relating to other transaction states as well. One can utilize the onError() callback in the useWaitForTransaction() hook to act to transaction failure. Alternatively, there is also the onSettled() callback. This callback is used when the transaction has either failed or succeeded (but in all form, has been settled). I would really encourage you to refer to the hook’s documentation for more information.

In our case, we make sure that if the transaction we are watching succeeds, then the refetch() method provided by useContractRead() hook is run. This will update the balance shown in our component. The flow thus becomes –

User clicks on the Mint button which invokes the handleMint() function. This function generates an transaction to invoke the safeMint() function in our smart contract.
The useWaitForTransaction() hook watches the transaction.
When the transaction succeeds, the refetch() method is invoked.
The new balance is updated in our component.

Assembling into MintCard Component

Now, we need to put the above 2 subsections together. The following code section shows the contents of the MintSection.tsx in entirety.

"use client";
import React from "react";

import {
  useAccount,
  useContractRead,
  useContractWrite,
  useWaitForTransaction,
} from "wagmi";
import nftAbi from "@/blockchain/nft_abi.json";
import StyledButton from "../ui/StyledButton";

const MintSection = () => {
  const { address } = useAccount();
  const { data, isSuccess, isLoading, refetch } = useContractRead({
    address: process.env.NEXT_PUBLIC_NFT_CONTRACT,
    abi: nftAbi,
    functionName: "balanceOf",
    args: [address],
  });
  const { data: writeData, write } = useContractWrite({
    address: process.env.NEXT_PUBLIC_NFT_CONTRACT,
    abi: nftAbi,
    functionName: "safeMint",
    account: address,
  });
  useWaitForTransaction({
    hash: writeData?.hash,
    onSuccess() {
      refetch();
    },
  });
  const handleMint = async () => {
    write({
      args: [address],
    });
  };
  return (
    <div className="h-full mt-4 lg:flex lg:flex-col lg:justify-evenly lg:items-center">
      <p>
        You are signed in as{" "}
        <span className="font-bold tracking-tight">
          {address?.slice(0, 5)}...
          {address?.slice(address.length - 5, address.length)}
        </span>
        .
      </p>
      <p>
        Your Balance:{" "}
        {isLoading && <span className="font-semibold">loading...</span>}
        {isSuccess && (data as any).toString()}
      </p>
      <div className="flex justify-center items-center mt-3">
        <StyledButton color="pink" onClick={handleMint}>
          Mint
        </StyledButton>
      </div>
    </div>
  );
};

export default MintSection;

Apart from the codes discussed in the above 2 sub sections, nothing else is worthy of discussion in the code above. This MintCard component handles the entire minting logic. It might have been better to split this in a manner we had split the Greeting components. In fact, I would recommend you to do that in your case. Would help adherence to SOLID principles.

Mecha is Assembled

In this section, we put all the components into the hidden page. Our page.tsx inside the hidden directory should look something just like the code below.

import React from "react";
import CustomAppbar from "../components/CustomAppbar";
import { GreetingCard } from "../components/example1";
import { NFTCard } from "../components/example2";

const HiddenPage = () => {
  return (
    <div className="min-h-screen">
      <CustomAppbar />

      <main className="container mx-auto flex flex-col justify-center items-center">
        <h1 className="text-5xl tracking-tight font-extrabold text-gray-300">
          Yohoo!!
        </h1>
        <h2 className="text-3xl text-gray-500">
          You have <span className="font-bold">Started</span>.
        </h2>
        <p className="">
          You have been signed in{" "}
          <span className="font-semibold text-green-400 text-xl">
            successfully
          </span>
          !
        </p>
        <div className="grid grid-cols-1 lg:grid-cols-2 gap-4">
          <GreetingCard />
          <NFTCard />
        </div>
      </main>
    </div>
  );
};

export default HiddenPage;

We have our custom App bar followed by the main section (line 11-29). This section shows some information to the user. We use the grid layout of Tailwind to make things a little responsive between lines 25 and 28. And that’s it!
Our mini-project is ready. Run npm run dev and you should see the culmination of our three-part series on Next Auth and NextJS 13 in Web3.

Conclusion

This brings us to the end of our Three-Part series. In this series, we tried to answer the following questions:

How to use NextJs 13 in a Web3 project?
How to use WalletConnect, Wagmi and Viem in NextJs 13?
How to integrate WalletConnect with Next Auth? Hope this helped you understand the concepts. If you have anything to share, feel free to open a discussion below. Until next time, don’t stop building awesome things in Web3 and WAGMI!

NextJS 13 – Using Next Auth the Web3 way.

Abhik Banerjee — Wed, 28 Jun 2023 12:51:10 +0000

In the previous article, we built a barebones NextJS 13 App which used WalletConnectV2, Wagmi, and Viem to tape together a Login of “sorts” in Next. That was very basic, now we take it up a notch. In real-world NextJS 13 apps, you won’t have that kind of structure. You will always be encouraged to use another library called Next Auth (next-auth). Next Auth is currently rebranding to Auth.js but the fundamentals remain the same and the latest version of Next auth is what we will use in this article.

This article will answer the following questions:

How to use Next Auth or Auth JS in Next 13?
How to Integrate Web3 (WalletConnect and Wagmi) with Next Auth?
How to Sign Messages using SIWE and use that with Next Auth in Next 13?
How do the API routes work in the context of Web3 and Next 13?

We will touch briefly on topics relating to “Sign-in with Ethereum”, API Routes in Next 13, and how JWT works in Next 13 with Next Auth. That’s a lot of topics to cover in a mere 2000-word article so let’s get started!

Housekeeping – Route and Component Structure in Next 13

abhik-99 / NextJS-Blog

This repo contains code for the "NextJS - How to Web3?" blog series. It contains a Next 13 App styled with Tailwind. The app uses WalletConenctV2, Wagmi and Viem.

We will be using the same GitHub Repo as the previous article. This time however it contains a couple of more pages. We will not be using the default <Web3Button/> from Wallet Connect. We will create three new routes:

/ - The Landing page of our Next App. Open to All and just contains a styled tailwind button that leads to the Login Page.
/auth - A Custom Login Page in NextJs 13 App where we will connect our wallet and ask the user to sign a message using Web3 Wallet using WalletConnect, SIWE, and Wagmi.
/hidden - A Protected Route in our app which the user will be redirected to after login. This route will contain the Sign Out logic for the app.
/api/auth - Authentication Route where Next Auth will work its magic. It will be a backend route where the message will be verified, JWT will be created and sent to the client side.

We will need siwe and next-auth for creating the authentication flow so open a terminal in your project and run npm i siwe next-auth. Next Auth at the time of writing does not provide any connectors for Wagmi or WalletConnnect so we will have to use Credentials Provider and customize that to our flow.

Behind the scenes, Next Auth handles all the JWT logic and session maintenance both on the client and server sides. On the Client side, we can use useSession() hook of Next Auth imported from next-auth/react. While on the server side, we can use the getSession() action from the same import. These return the data object which is conveniently renamed to session. It is this session object that contains a property called user where all the user details reside. We will need this to contain the user’s wallet address and signature.

What is SIWE?

SIWE stands for “Sign-In With Ethereum”. It is basically an RFC (think of it as a rule) which specifies how should authentication take place off-chain eg. Web Apps and Mobile Apps. I would say it’s a long time coming considering how scattered things feel sometimes when you are developing a frontend for a Dapp.

SIWE specifies that a message must have domain and origin along with details like the chain on which the message is meant to be used. This, I would say, helps make things easy. We can avoid a lot of discussion on how to format a message to be signed or concerns of interoperability.

A typical SIWE Signing Request looks like:

At the moment, SIWE can be used in Typescript, Rust, Elixir, Python, Go, and Ruby. So, one can say they are targeting Web app-intensive languages. The code for Typescript SDK is open sourced here:

spruceid / siwe

Sign-In with Ethereum library

Sign-In with Ethereum describes how Ethereum accounts authenticate with off-chain services by signing a standard message format parameterized by scope session details, and security mechanisms (e.g., a nonce). The goals of this specification are to provide a self-custodied alternative to centralized identity providers, improve interoperability across off-chain services for Ethereum-based authentication, and provide wallet vendors a consistent machine-readable message format to achieve improved user experiences and consent management.

Quickstart Examples

To try it out locally, check out these examples:

Motivation

When signing in to popular non-blockchain services today, users will typically use identity providers (IdPs) that are centralized entities with ultimate control over users' identifiers, for example, large internet companies and email providers. Incentives are often misaligned between these parties. Sign-In with Ethereum offers a new self-custodial option for users who wish to assume more control and responsibility over their…

View on GitHub

Currently, the documentation for usage of SIWE with Next JS is not up to date with Next 13 and so this article aims to help on that front as well.

Components and Pages

So as an upgrade from the previous article, we need to include a few more pages in our Next app.

Home Page

The home page of our NextJs 13 Web3 site will be created inside the root page.tsx file inside the app directory. The following is the code for the component. Explanations follow.

import Link from "next/link";
import React from "react";

export default function Home() {
  return (
    <main className="flex min-h-screen flex-col items-center justify-center">
      <h1 className="text-5xl font-bold tracking-tight text-gray-400">
        Welcome
      </h1>
      <h2 className="text-3xl tracking-tight text-gray-500">
        Let's get started, shall we?
      </h2>
      <Link href="/auth">
        <button className="bg-green-500 border-4 border-green-400 hover:border-green-800 hover:bg-transparent mt-5 rounded-lg py-2 px-4">Get Started</button>
      </Link>
    </main>
  );
}

Firstly, note that unlike the previous article, the home page has been converted to a server component by removal of the ”use client” tag. It doesn’t really matter what you call this component. As long as its the default import, it gets rendered at the route. This is true for all routes and page.tsx files in NextJS 13.

In our case, it is a simple component styled with Tailwind CSS and contains a button that links to the /auth page route. Notice the <Link /> component which wraps the <button />. In NextJS 13, the link component is not imported from next/navigation. It is imported from next/link.

I am not the best UI designer so that’s about it when it comes to the design and the page as a whole. The Home page is open to all.

Authentication Page

Next, create a directory called auth inside the app directory and put a page.tsx file inside it. Notice how we continue on the convention of directory naming in NextJS 13 from our previous article. The absence of the underscore prefix and the presence of page.tsx in the auth directory tells NextJS 13 it’s a frontend route. The Code for the authentication is as follows. Explanations follow.

"use client";
import React from "react";
import { SiweMessage } from "siwe";
import { polygonMumbai } from "viem/chains";
import { useAccount, useSignMessage } from "wagmi";
import { useWeb3Modal } from "@web3modal/react";
import { getCsrfToken, signIn } from "next-auth/react";

const AuthPage = () => {
  const [mounted, setMounted] = React.useState(false);
  const { address, isConnected } = useAccount();
  const { open } = useWeb3Modal();
  const { signMessageAsync } = useSignMessage();
  const [hasSigned, setHasSigned] = React.useState(false);

  React.useEffect(() => setMounted(true), []);
  if(!mounted) return <></>

  const handleSign = async () => {
    if (!isConnected) open();
    try {
      const message = new SiweMessage({
        domain: window.location.host,
        uri: window.location.origin,
        version: "1",
        address: address,
        statement: process.env.NEXT_PUBLIC_SIGNIN_MESSAGE,
        nonce: await getCsrfToken(),
        chainId: polygonMumbai.id,
      });

      const signedMessage = await signMessageAsync({
        message: message.prepareMessage(),
      });

      setHasSigned(true);

      const response = await signIn("web3", {
        message: JSON.stringify(message),
        signedMessage,
        redirect: true,
        callbackUrl: '/hidden'
      });
      if (response?.error) {
        console.log("Error occured:", response.error);
      }

    } catch (error) {
      console.log("Error Occured", error);
    }
  };

  return (
    <main className="flex min-h-screen flex-col items-center justify-center">
      {!isConnected && (
        <>
        <h2 className="text-5xl font-semibold text-gray-400">Firstly,</h2>
        <p className="text-xl text-gray-500 mt-2 mb-6">you <span className="font-extrabold text-gray-300">need</span> to</p>
        <button
          className="rounded-lg py-2 px-4 bg-blue-700 hover:border hover:border-blue-700 hover:bg-transparent"
          onClick={() => open()}
        >
          Connect Wallet
        </button>
        </>
      )}
      {isConnected && !hasSigned && (
        <>
          <p className="text-xl font-semibold text-gray-400">
            Welcome {address?.slice(0, 8)}...
          </p>
          <button
            className="rounded-lg py-2 px-4 mt-2 bg-violet-700 hover:border hover:border-violet-700 hover:bg-transparent"
            onClick={handleSign}
          >
            Sign Message to Login
          </button>
          <button
            className="rounded-lg py-2 px-4 mt-2 bg-yellow-400 hover:border hover:border-orange-700 hover:bg-transparent"
            onClick={() => open()}
          >
            Disconnect Wallet
          </button>
        </>
      )}
      {isConnected && hasSigned && (
        <p>You are being authenticated. Please wait...</p>
      )}
    </main>
  );
};

export default AuthPage;

Notice that it is a client-side component. Inside the <AuthPage /> component we have a state variable called mounted. The idea is this state variable is used to track if the component is being rendered client side or server side. Confusing, right? The thing is there will be a hydration error in our page when it is rendered on the client side. NextJS 13 needs to send a skeletal DOM of the page and because we are checking only on the client side purely if the user has connected the wallet first and then asking the user to sign a message, the server-side rendered component in DOM will differ from the client side one and you will get a Hydration Error in NextJS.

To avoid the Hydration Error in NextJS 13, we use the mounted state variable and set it to true first thing in the component using the useEffect hook. Immediately following that we check if the component is mounted on the client side otherwise, we send empty React Fragments. This solves the problem.

We utilize the useAccount() hook from wagmi to check if the user has already connected (with the isConnected value). If the user has not connected the wallet, then we display the user the Connect Wallet button at line 59 and on that button, we attach an onClick handler for the open function from useWeb3Modal() hook imported at line 12 from the @web3modal/react library of Wallet Connect.

Now If the user has connected the wallet but has not signed our message, the hasSigned React state variable initialized as false helps us display the Sign Message button at line 72. The button has handleSign() as the onClick handler. That’s where the main magic happens.

When the user clicks on the Singing button at line 72, handleSign() at line 19 is invoked. As a precaution we check if the user is still connected to the wallet and if not open the WalletConnect Web3 Modal for connection. After that, create a new message to sign using new SiweMessage(). We specify the domain and origin as window.location.host and window.location.origin respectively while the version is specified as “1”. No brainer there.

After that, the address is the wallet address with which the user is connected. The statement property is where you specify the message to be signed. I like to place that message as a public env variable so that it is accessible on the client and server side. That helps during verification. Now we could have used a custom nonce but the CSRF token serves that purpose. We fetch the CSRF token using the getCsrfToken() function from next-auth/react. chainId in our is the Polygon Mumbai Testnet Chain ID since that’s where our smart contract is deployed.

This creates a message to be signed. The signMessage() function from the useSignMessage() hook (wagmi import) helps us sign the message at line 32. Using the prepareMessage() function helps us generate a nice-to-look Message with all the params we have specified during Message Generation. It shows those at the wallet signing prompt.

This message is then stringified and sent through the signIn() method from next-auth/react to Next Auth’s authentication routes which we will create in the later section. We say that we want to redirect to the route /hidden on successfully authentication. Next Auth takes care of that. This is specified using the redirect and callbackUrl values. If you do not want to redirect to any route, you can set redirect as false in which case, after successful authentication, you will still stay on the /auth route on this same page.

If the authentication is successful, Next Auth’s signIn() response will contain an ok value set to true. If response.ok is returned as false then that means there was an error on the server. You can access the error using response.error. In our case, we just to redirect using Next Auth to a protected route on successful authentication or log the error on the browser console.

Using Next Auth, we can have more than one authentication method in our Next 13 app. We can have Google Authentication, Github authentication, or even our custom authentication method (which we use in our case) among other methods. These are made available through “Providers” and you can read more about them here.

Hidden Page

This is a protected page and will only be accessible if the user has successfully logged in. This page will be available at the /hidden client route. So, make a folder called hidden inside app directory and then create a page.tsx inside it. Code and explanations follow.

"use client";
import { signOut } from "next-auth/react";
import React from "react";
import { useDisconnect } from "wagmi";

const HiddenPage = () => {
  const { disconnectAsync } = useDisconnect();
  const handleSignout = async () => {
    disconnectAsync();
    signOut({callbackUrl:"/"});
  };
  return (
    <div className="flex min-h-screen flex-col items-center justify-center">
      {" "}
      <h1 className="text-5xl tracking-tight font-extrabold text-gray-300">
        Yohoo!!
      </h1>
      <h2 className="text-3xl text-gray-500">
        You have <span className="font-bold">Started</span>.
      </h2>
      <p className="text-gray-500">
        You have been signed in{" "}
        <span className="font-semibold text-green-400 text-xl">
          successfully
        </span>
        !
      </p>
      <button
        className="rounded-lg py-2 px-4 mt-6 bg-red-700 hover:border hover:border-red-700 hover:bg-transparent"
        onClick={handleSignout}
      >
        Sign Out
      </button>
    </div>
  );
};

export default HiddenPage;

This is another client page as you can see above. This page mainly is used for Logging out. The “Sign Out” button has a click handler where we disconnect from the wallet connection at line 9 and then use the signOut() function to tell Next Auth to destroy the user session (effectively logging out) and then redirect to the Home page using the callbackUrl value.

That’s about it really about the pages, next we will get into the Next Auth-related changes and that’s where the tricky parts come in.

Next Auth Integration

There is a reason why Next Auth is often the de facto auth library used with Next JS. It offers a ton of options for authentication and makes session management quite easy. But to use it inside any Next App, we need to follow a certain list of steps first. This section discusses those steps in detail.

How to use Next Auth’s AuthContext in Next 13?

In the previous article, we discussed that we can include any Context we want as a client component and wrap the children inside the layout.tsx file. We even created a <Providers /> component which was our kind of Barrel Export.
So, inside our _providers directory, create a file called AuthContext.tsx. Inside this file, we create the following client-side component:

"use client";

import { SessionProvider } from "next-auth/react";

export interface AuthContextProps {
  children: React.ReactNode;
}

export default function AuthContext({ children }: AuthContextProps) {
  return <SessionProvider>{children}</SessionProvider>;
}

We wrap the {children} props with the <SessionProvider /> component from Next Auth’s next-auth/react. This <AuthContext/> component can now be used inside of our <Providers/> component inside providers.tsx file like shown below and we will not have to touch layout.tsx file.

"use client";
import React from "react";
import WagmiProvider from "./WagmiProvider";
import AuthContext from "./AuthContext";

type ProviderType = {
  children: React.ReactNode;
};

const Providers = ({ children }: ProviderType) => {
  return (
    <WagmiProvider>
      <AuthContext>{children}</AuthContext>
    </WagmiProvider>
  );
};

export default Providers;

This completes our first step.

Defining Server Route for Next Auth.

Next Auth by default functions on the /api/auth server route if used server side. We won’t change that. So, create a folder called api inside app directory and then another nested folder called auth inside api. Inside auth directory, create a directory named […nextauth]. Notice the weird name. That’s essential for Next Auth to work correctly. Inside the […nextauth] directory create a route.ts. There won’t be a .tsx suffix. This is a server route and not a component.

In the next 80-ish Lines of code pasted below, we will tell Next Auth to use the CredentialsProvider for signing in users using a custom method. Paste the code below inside the route.ts file. Explanations follow.

import { AuthOptions } from "next-auth";
import NextAuth from "next-auth/next";
import CredentialsProvider from "next-auth/providers/credentials";
import { getCsrfToken } from "next-auth/react";
import { SiweMessage } from "siwe";

export const authOptions: AuthOptions = {
  providers: [
    CredentialsProvider({
      id: "web3",
      name: "web3",
      credentials: {
        message: { label: "Message", type: "text" },
        signedMessage: { label: "Signed Message", type: "text" }, // aka signature
      },
      async authorize(credentials, req) {
        if (!credentials?.signedMessage || !credentials?.message) {
          return null;
        }

        try {
          // On the Client side, the SiweMessage()
          // will be constructed like this:
          //
          // const siwe = new SiweMessage({
          //   address: address,
          //   statement: process.env.NEXT_PUBLIC_SIGNIN_MESSAGE,
          //   nonce: await getCsrfToken(),
          //   expirationTime: new Date(Date.now() + 2*60*60*1000).toString(),
          //   chainId: chain?.id
          // });

          const siwe = new SiweMessage(JSON.parse(credentials?.message));
          const result = await siwe.verify({
            signature: credentials.signedMessage,
            nonce: await getCsrfToken({ req }),
          });

          if (!result.success) throw new Error("Invalid Signature");

          if (result.data.statement !== process.env.NEXT_PUBLIC_SIGNIN_MESSAGE)
            throw new Error("Statement Mismatch");

          // if (new Date(result.data.expirationTime as string) < new Date())
          //   throw new Error("Signature Already expired");
          console.log("Returning")
          return {
            id: siwe.address,
          };
        } catch (error) {
          console.log(error);
          return null;
        }
      },
    }),
  ],
  session: { strategy: "jwt" },

  debug: process.env.NODE_ENV === "development",

  secret: process.env.NEXTAUTH_SECRET,

  callbacks: {
    async session({ session, token }: { session: any; token: any }) {
      session.user.address = token.sub;
      session.user.token = token;
      return session;
    },
  },
  pages: {
    signIn:"/auth"
  },
};

const handler = NextAuth(authOptions);

export { handler as GET, handler as POST };

In the above code we create our custom Next Auth handler called handler (shocker there 😊 ). The handler is created using NextAuth by specifying the authentication options and then the handler is mapped to GET and POST routes in the last line. This means the Next Auth handler will respond to GET and POST requests on the /api/auth route.

How to create Next Auth `authOptions`?

The authOptions declaration starting at line 7 contains, firstly, a list of providers through the array passed into providers. This is where you can specify Github, Google, Facebook and other providers for sign-in. The sign in developer experience is seamlessly handled by Next Auth with those providers.

In our case, we specify a CredentialsProvider. This is used for custom sign-in methodologies. The id and name are important values. Imagine in your Next App you have 2 custom sign in options –

Using Wallet Sign In
Using Username and Password Sign In

That’s when you will use two different CredentialsProvider with different names and pass them to the providers array. In such a case, from the frontend, you will specify the ID of the CredentialsProvider to the signIn() method from next-auth/react along with the required credentials for that type of sign-in.

Next Auth Modification for Web3

Thankfully, in our case, we need only one. We provide the types and names of the credentials on line 12. Following this, we have the authorize() function where the main logic is implemented. In a Web2-esque sign-in, this is where you will fetch the values like username, email, and hashedPassword from the DB and compare the user. If this function returns null then Next Auth assumes authentication failure and reverts with an error.

As iterated before, we do not need any DB. In our case, we will just verify if the message and signedMessage (or signature, whatever you want to call it) match our expectations or not. We recover the SIWE message sent to the handler from the frontend in a stringified manner. In line 34, invoking the verify() method on the reconstructed message by passing in the signature or in our case the value of the cred signedMessage along with the nonce will help us in verifying the message authenticity.

The Nonce value here can be obtained by again calling in the getCsrfToken() method. But this time, we need to pass in the req object to the method to record the CSRF token from the Request sent to the Next Auth handler.

If result.success from this operation is true then we can say that the signature is for the same SIWE message. But keep in mind we cannot say that the messages signed were the same. For this, we need an additional check at line 41 checking the value of our Logging Message (stored as an env variable) with the message inside the SIWE message object reconstructed from the request.

If these checks pass, then we can be assured of an authentic Sign In request and we return the Wallet Address of the signer with siwe.address at line 47.

Modifying Session Management, Secrets & Pages in Next Auth

Next, we need to tell Next Auth that with this credential’s provider, Next Auth is supposed to use the jwt strategy. This means the access token is maintained on the client side and not on the server side. That’s what we do at line 57.

You might be aware that for using JWT we need secrets. That’s what we specify at line 61. We store our secret in our .env file. The methods in callbacks are called when creating, using, destroying JWT tokens, or manipulating the Session in any way.

By default, the session object is made available through the useSession() hook on the client side containing a user object with name, email, and image properties. Those are not valid for us. We need the user object to contain the wallet address of the user. In our case, the subject of the JWT token (token.sub) will contain that value. So we need to modify the session object of Next Auth. You might also need the user object to contain the token itself in your use case. Both of these are accomplished through lines 65 and 66 respectively.

At line 71, under pages we tell Next Auth to use the ‘/auth` route for Sign In requests. So, it knows that any requests coming from that route are for Signing In. With this, our work is almost done.

Protecting Routes in Next JS using Next Auth

Two Lines - that's all it takes. To protect routes in Next JS using Next Auth, we need to create a middleware.ts file in the root of our project. Inside this file, we need to tell Next Auth which routes in our app are protected. Next Auth will make sure that only authenticated users can access these. This can be done by placing the following code inside the above-mentioned file.

`typescript

export { default } from "next-auth/middleware"
export const config = { matcher: ["/hidden"] }

You can specify route patterns inside the matcher array using regex. Next Auth will make sure that if any unauthenticated requests are placed to these routes, then the user goes through the sign-in page. In our case, we have previously told Next Auth that the sign-in page in our app is at /auth route inside the route.ts above. So, Next Auth will redirect users to that page.

Our Next App till now

At this stage, we have a full authentication flow in our app. A user can start from the landing page and then sign in using their wallet. This will redirect them to a protected page. This completes our app up to the 60% mark. We still have major work to do where our app will be able to interact with a smart contract.

Conclusion

This was one long article. I honestly didn’t think it would be this big.

Another reason its funny for me is that I discussed in the previous article that this would be a two-part series and now it has become a three-part series. So now I feel like I am making a Fast and Furious franchise-like series.

Until the next article, keep building awesome things on Web3 and WAGMI!

NextJS 13 – How to Web3?

Abhik Banerjee — Mon, 26 Jun 2023 14:45:20 +0000

These past couple of weeks have been weeks of breaking changes, especially for the Web3 Frontend landscape. We now have a new underdog called Viem which is challenging the dominance of EthersJs. Ethers has released version 6 which comes with breaking changes. Viem has been adopted by Wagmi – a favourite Web3 Frontend library. This means Wagmi.sh also has introduced breaking changes in its new version. To top it off, WalletConnect has sunset v1 in favour of the much-awaited v2. To top it off, NextJS 13.4 has now been termed as a stable-ish version of NextJS 13 by its creators.

This article is the first part in a two-part series where we will look at the following and try to make a mini-project to understand how things work now:

Next JS 13 (Note: whenever you see NextJS 13 or Next or NextJs, assume its NextJS 13.4)
WalletConnect v2
Wagmi.sh
Viem

We will use Tailwind CSS for it and the code can be found at this Repo:

Fair Warning: I will not be explaining NextJS 13 in-depth. Read the Docs or watch Traversy Media or Code With Antonio's tutorials on YoutTube for an in-depth explanation of Next 13 my fellow Lyadhkhor devs.

In this article I will:

Briefly touch NextJS 13 and how it works.
Setup Wagmi and WalletConnect in a NextJs 13 App.
Using WalletConnect v2

The next article in this series will show how one can use Viem and Wagmi.sh to read and write data from a smart contract deployed on Polygon Mumbai Testnet (honestly, who uses Sepolia Testnet now-a-days?).

The code for this series will be available at this Github Repo:

abhik-99 / NextJS-Blog

This repo contains code for the "NextJS - How to Web3?" blog series. It contains a Next 13 App styled with Tailwind. The app uses WalletConenctV2, Wagmi and Viem.

NextJS 13 – what gives?

NextJS has always been a favourite for the range of benefits it has historically provided over React. An unopinionated client-side rendering library like React has had its pitfalls – like poor SEO. With the current Next version, Vercel just made things simpler.

Now by default, all components are server components and to have a component render client side you need to use the “use client” tag at the top of the component file. What’s the difference?

Server components are first rendered on the server when someone requests and then sent to the client side (browsers and such). Client Components do not get rendered on the server and instead get rendered on the client itself.
Server Components will return the full DOM essentially when requested, Client components won’t. So, it’s better for SEO.
You won’t be able to use React Hooks and Context on the server. So, say goodbye to useEffect and useState when using Server Components.
Conversely, you can actually query a DB in a server component and have the results rendered without the general risks of doing the same in a client React component.

These, among other things, outline the advantages of using NextJS. Watch/Read those resources for a complete difference and working of a NextJS app.

The interesting thing is that while you cannot use client-side interaction hooks in a server component, you can encapsulate the parts requiring client interaction inside a client component and then use that component inside a server component. In simpler terms, a component decorated with “use client” can be included in a server component.

Moreover, in a client component, you can execute server-side code in the form of actions (async functions). These actions are composable meaning they can be kept inside together in any other part of the app and then called and executed in a client component. You need to annotate these actions by the “use server” tag inside the function (in its first line). At the time of writing, you will have to enable this feature manually as its experimental.

Another conundrum is the naming convention. One might think that everything inside app directory is routable. This is not true. NextJS considers only those directories which have a page.tsx file inside them as routable. To differentiate, here we will prefix _ to every directory which is not meant to be routable. These things more or less cover what we need to know.

In this section, we will setup a clean NextJS 13 app and discuss the changes introduced along with how to work around certain things. Firstly run npx create-next-app@latest. This will give you the options for your app starting with the app name. We will:

Use Typescript with NextJS 13 app.
Use ESLint.
Use Tailwind CSS in our Next app.
We will not be using the src directory
We will definitely use the App Router with NextJS 13
Change the import alias to @

This will create a directory for you with a directory structure as shown below. The app directory does not have an api directory. We won’t need it. NextJS also brings a lot of change on the API Routes side of things but that can be discussed some other time. You can run npm run dev to start the dev server. This will start the Next App on Port 3000 as shown below. This completes the NextJS part of things.

WalletConnect

WalletConnect is a utility that allows us to connect to multiple wallets quite easily (duh, that’s the name). It provides a layer of abstraction over the injectors and wallet connectors. One can easily customize the options like the button for connecting and the modal which opens. WalletConnectv2 has been a long time coming (though not as long as Bootstrap 5). In this article, we will be using WalletConnectv2.

WalletConnect builds nicely on top of Wagmi. This allows you to have access to Wagmi.sh hooks and provide functionality through a common context. Now talking of hooks and context should tell you that this is something we need on the client side.

But first things first, we need a Project ID to work with WalletConnect. You need to:

Go to the WalletConnect Cloud, create an account & login.
Create a “New Project” with whatever name you want. Here we go with “next13-web3”.
Copy the Project ID. It will be shown in the section as shown in the image below.

Once you have the project ID, you need to create an environment file in the root of your project to say this. NextJS just like React has a special convention for the environment variables:

All Environment variables declared in a .env file in NextJS are server-side. They will not be exposed to Client-Side Components.
If you want an environment variable to be available on the client side, you need to prefix NEXT_PUBLIC_ to the name of the environment variable (similar to REACT_APP_ in React).

But even after this, we need to go the extra mile because we are using Typescript in NextJS. When using Typescript in NextJS, you will encounter a special problem referencing environment variable using process.env as these variables can be string | undefined by default and not many arguments allow that type.

WalletConnect client takes in project ID which is of type string so having string | undefined is problematic. You can either typecast it using as string after the environment variable in the code. A Better way would be to create a additional-env.d.ts file the root of your project. Add this file to include:[] array in your tsconfig.json file. Inside the additional-env.d.ts file add the following code:

declare global {
  namespace NodeJS {
    interface ProcessEnv {
      NODE_ENV: "development" | "production";
      NEXT_PUBLIC_W3C_PID: string;
    }
  }
}

export {};

You can add your environment variable name followed by type inside the ProcessEnv interface in a manner similar to the code above. Then add them to your environment file and Typescript will not complain about your use of env variable in any project (not just in Next). Now open a terminal in VS Code and run npm install @web3modal/ethereum @web3modal/react wagmi viem like shown below.

This completes the Wallet Connect and related dependency installation (Wagmi and Viem included). After this, we need to:

Create a Wallet Connect and Wagmi Config
Provide it throughout the app by wrapping the app with the config.
Place the Web3Modal from @web3modal/react somewhere it won’t create a problem for the rest of the app.
Use Web3Button from @web3modal/react to use WalletConnect to connect to Wallets.

Creating Config and Providing it through the App

Now, creating a config part is easy. Using a Provider and making it available throughout the app is the difficult part. The provider needs client components but by default, NextJs components are server components.

A poor solution to the problem will be opening the Root Layout (layout.tsx inside the app directory) and adding use client at line 1. That would make the Layout a server component. This is the root layout so the config will be provided to every component in the app. But our app suffers from poor SEO and that defeats the purpose of NextJs.

So, a better solution will be to create a client component and use that inside the Root Layout server component (refer to the NextJS section of the article). We will call this component WagmiProvider.tsx. In a real-world app, you will have multiple such Providers. So a good practice here would be to bundle them all inside a RootProvider component of sorts and then to wrap the children inside the <body> of the RootLayout. The RootProvider will only need to be declared “use client” and the individual providers do not need to declared with this tag. This solves the Provider problem in NextJS. This is how you can use Context Providers, Theme Provider and Wagmi Provider etc. in NextJS 13.

Create a _providers directory inside the app directory. Inside this, create a file called WagmiProvider.tsx and place in the following code:

import React from "react";

import {
  EthereumClient,
  w3mConnectors,
  w3mProvider,
} from "@web3modal/ethereum";
import { Web3Modal } from "@web3modal/react";
import { configureChains, createConfig, WagmiConfig } from "wagmi";
import { polygonMumbai } from "wagmi/chains";

type WagmiProviderType = {
  children: React.ReactNode;
};

const chains = [polygonMumbai];
const projectId = process.env.NEXT_PUBLIC_W3C_PID;

const { publicClient } = configureChains(chains, [w3mProvider({ projectId })]);
const wagmiConfig = createConfig({
  autoConnect: true,
  connectors: w3mConnectors({ projectId, version: 2, chains }),
  publicClient,
});

const ethereumClient = new EthereumClient(wagmiConfig, chains);
const WagmiProvider = ({ children }: WagmiProviderType) => {
  return (
    <>
      <WagmiConfig config={wagmiConfig}>{children}</WagmiConfig>
      <Web3Modal projectId={projectId} ethereumClient={ethereumClient} />
    </>
  );
};

export default WagmiProvider;

In the code above, at line 12 WagmiProviderType we declare the prop type. We will only need to use the children prop here and that’s what we specify. The chains array at line 16 contains a list of all EVM-compatible chains on which our app would function. These chains are where our smart contracts need to deployed.

We use the Web3Modal provider and pass in our project ID to it along with the chains as argument to the configureChains and then use the public client (a Viem term) to create a Wagmi config at line 20. This will be passed to the WagmiConfig provider. We then create a ethereumClient for Wallet Connect and pass it to the <Web3Modal /> component along with the project ID. Notice how we wrap the <WagmiConfig /> around the children.

After this, create a separate file called Providers.tsx and paste the following code in. Explanations follow.

"use client"
import React from 'react'
import WagmiProvider from './WagmiProvider'

type ProviderType = {
  children: React.ReactNode
}

const Providers = ({children}: ProviderType) => {
  return (
    <WagmiProvider>{children}</WagmiProvider>
  )
}

export default Providers

We make the Providers.tsx as a client component using the ”use client” tag. We create the prop type with the ProviderType which again will be just the children prop. Nothing special there. Inside the component, we wrap the {children} with the WagmiProvider we had just created. This Provider component is where you will import and wrap all your other Providers like say Material UI Provider, Context Provider, Auth Provider and so on in NextJS.

All we need to do is to import this <Providers /> component inside our Root Layout (layout.tsx inside app directory) and wrap the children like the code shown below:

import Providers from './_providers/providers'
import './globals.css'
import { Inter } from 'next/font/google'

const inter = Inter({ subsets: ['latin'] })

export const metadata = {
  title: 'Next13 Web3',
  description: 'A Web3 Example on using NextJs 13',
}

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body className={inter.className}><Providers>{children}</Providers></body>
    </html>
  )
}

In the above code for the Root Layout, I have just changed the Metadata title and description. You can do it for every layout in NextJS using the Metadata API. At line 19, I have wrapped the <Providers /> component around the children.

With this, we do not need to declare our Layout as a client component in NextJS and still have the client functionalities we
need.

Using Web3Button

Next we move to page.tsx inside the app directory. We don’t really need any code inside the <main /> tags. So in the code section below, I have deleted all that and just added a single button component <Web3Button /> from @web3modal/react. We need to tag the page.tsx file with ”use client” because we need the button onClick interaction. Even the <Web3Button /> component uses context which, again, is a client side feature.

If you have your dev server running, browse to localhost:3000 and you will encounter something similar to the screen below:

This means that we have completed all the coding bits required for this part of the article. Keep in mind that you can change this. You have the option to instead use the useWeb3Modal hook from @web3modal/react to have the Web3Modal /> handlers using your own styled button.

Connecting to Wallets using WalletConnectV2

If you click on the blue button on the screen, the Web3 Modal of WalletConnect will open and you will be greeted with a similar view:

You can choose to connect using any wallet you want. In my case, I clicked on Metamask and that opened the Metamask extension on my browser. Once you have connected using Metamask or your wallet of choice, the button will change to the appearance shown below:

This means you are connected. You can use the useAccount() wagmi hook to check if you want to verify.

Conclusion

This brings us to the end of this article. In this article we discussed how to use Wagmi, WalletConnectV2, Viem with NextJS 13. We briefly touched on NextJS 13 and why it is considered by many to be a framework of choice. We created the first part of our Web3 mini-project.

Hope this article was helpful for you. In the next part, we will use Wagmi and Viem to interact with a Smart Contract deployed on Polygon Mumbai Testnet. Until then, keep building awesome stuff on Web3 and WAGMI!

Forem: Abhik Banerjee

Routing the Easy Way in Go

abhik-99 / Passwordless-Login-in-Go

This repo contains code for my article series on creating a Passwordless Login system in Go from scratch.

Crash Course into Routing

The routes package

Authentication Routes

User Routes

The controllers package

Authentication-oriented Controllers

User-oriented Controllers

The middlewares package

Conclusion

Modelling your Data Layer in Go

The data package

User Profile Representation in Go

Authentication-related modeling in Go

Conclusion

Password-less Auth in Go – Hands-on Part 1

Utility Package

Config Package

Main Package

Conclusion

Password-less Login in Go from Scratch

Full Disclosure

abhik-99 / Passwordless-Login-in-Go

This repo contains code for my article series on creating a Passwordless Login system in Go from scratch.

Housekeeping

Conclusion

Understanding Chainlink CCIP in 15 bullet points

Chainlink CCIP in 15 bullet points

What’s next?

Next x Nest – GraphQL for REST API developers – Part 2

Nuances of using a Code-first Approach

Remaining Resolvers

Board

Module

Resolver

Service

BoardUser

Module

Resolver

Service

What’s Next?

Next x Nest – GraphQL for REST API developers - Part 1

Housekeeping

Using Multiple Prisma Schema in a single project

Prisma Supabase Module

Prisma Render Module

GraphQL Resolvers

Circular Dependency

User Module

User Entity

Module

Resolver

Service

What’s Next?

abhik-99 / Trivial-Kanban

This is a mini-project part of the series 'Next x Nest'. It uses NextJs 13+ to create a Kanban board and has NestJs on the backend.

Next x Nest - Using Supabase & Google OAuth in NestJS

abhik-99 / Trivial-Kanban

This is a mini-project part of the series 'Next x Nest'. It uses NextJs 13+ to create a Kanban board and has NestJs on the backend.

Housekeeping

Using Environment variables in NestJS

Adding Passport and Google OAuth to NestJS

Creating Google OAuth Strategy & Guard in Nest

Creating a JWT Auth Strategy & Guard in NestJs

Decorators for Routes in NestJS

Public Route Decorator

HTTP Auth User Decorator

GraphQL Auth User Decorator

Adding Supabase to Nest

Difference between DATABASE_URL and DIRECT_URL in Supabase

Creating a Prisma Module in NestJS

Schema Introspection with Prisma

Authentication Endpoints (AuthModule)

Importing Strategies and Attaching Guards

Testing out Backend

Frontend & Backend Interaction in a NextJS and NestJS app

Making the Next App Work with Nest Authentication

The `routes` package

The `controllers` package

The `middlewares` package

The `data` package

How to create Next Auth `authOptions`?