DEV Community: Tonie

Implementing a Custom Payment Gateway Integration in MedusaJS

Tonie — Wed, 02 Aug 2023 08:00:12 +0000

When it comes to processing online payments, offering a diverse range of payment options is crucial for e-commerce applications. While MedusaJS provides native support for popular payment gateways, you may have specific requirements that necessitate integrating a custom payment gateway like Paystack. In this article, we will guide you through the process of implementing Paystack as a custom payment gateway in MedusaJS, empowering you to offer seamless payment experiences to your customers.

What is MedusaJS?

Medusa is an open-source, composable commerce platform specifically designed for developers. With its flexible architecture, MedusaJS empowers users to build highly customized commerce solutions catering to their needs. By providing modular commerce infrastructure, Medusa simplifies the custom development process, allowing developers to focus on creating unique and tailored e-commerce experiences.

You can learn more about the Medusa architecture in their official documentation .

One of the key strengths of MedusaJS is its ability to leverage cutting-edge infrastructure technologies. It embraces serverless architecture and employs edge workers to ensure exceptional scalability, reliability, and performance. This enables online stores built on Medusa to handle increasing traffic and deliver seamless user experiences, even during peak periods.

Why Paystack?

Paystack is a popular payment gateway used across several countries in Africa. It offers a developer-friendly API, and robust security features, and supports various payment methods.

Integrating Paystack into a Medusa store offers several benefits, including a developer-friendly API, robust security measures, and support for multiple payment methods.

Prerequisite

To fully understand the content of this article, you will need the following:

A recent version of node v16+
Yarn (or npm) installed on your computer
A code editor
A Paystack account (If you do not have one you can sign up using this link)
Git
PostgreSQL

Setting up Medusa Backend and Admin Dashboard

In this section, we'll go through how to set and configure the Medusa backend and admin dashboard.

The Medusa Backend acts as the core element accountable for managing the logic and data of the store. It provides REST APIs that are utilized by the Medusa Admin and Storefront for tasks such as data retrieval, creation, and modification.

Installing the Medusa backend and Admin Dashboard

Follow these steps to install the Medusa backend and admin dashboard.

Open your terminal and run the following command:

yarn create medusa-app

You'll be prompted to enter the name of your project which will be used to create your project directory. You can use the default name my-medusa-store or any name of your choice.
Next, you will be asked to provide the necessary PostgreSQL database credentials, including the username and password. If the credentials are valid, you can proceed to the next step.
You'll then be asked to enter an email for your admin user. This email will be used to signup on your admin dashboard.
After these, the setup process will begin and on completion, the Medusa backend will start and the admin dashboard will be opened in your default browser. This is where you sign up using the email you provided during the setup process.
Follow the tutorial steps on the dashboard to create your first product.

Installing packages and configuring the backend.

Open your terminal and type in the following command to install the medusa-payment-paystack plugin.

yarn add medusa-payment-paystack

This adds Paystack as a payment provider to Medusa e-commerce stores.

Open your project with your code editor and go to the .env file. Here you'll have to add your paystack secret key using the following format You can get your secret key from the setting page on your paystack admin dashboard.

PAYSTACK_SECRET_KEY=yourpaystacksecretkey

Navigate to the medusa-config.js file and add the following lines of code within the plugins array

  {
    resolve: `medusa-payment-paystack`,
    options: {
      secret_key: PAYSTACK_SECRET_KEY, //declare this as a variable just above your plugin
    },
  },

Your medusa-config.js file should look like this

const dotenv = require("dotenv");

let ENV_FILE_NAME = "";
switch (process.env.NODE_ENV) {
  case "production":
    ENV_FILE_NAME = ".env.production";
    break;
  case "staging":
    ENV_FILE_NAME = ".env.staging";
    break;
  case "test":
    ENV_FILE_NAME = ".env.test";
    break;
  case "development":
  default:
    ENV_FILE_NAME = ".env";
    break;
}

try {
  dotenv.config({ path: process.cwd() + "/" + ENV_FILE_NAME });
} catch (e) {}

// CORS when consuming Medusa from admin
const ADMIN_CORS =
  process.env.ADMIN_CORS || "http://localhost:7000,http://localhost:7001";

// CORS to avoid issues when consuming Medusa from a client
const STORE_CORS = process.env.STORE_CORS || "http://localhost:8000";

const DATABASE_URL =
  process.env.DATABASE_URL || "postgres://localhost/medusa-store";

const REDIS_URL = process.env.REDIS_URL || "redis://localhost:6379";
const PAYSTACK_SECRET_KEY = process.env.PAYSTACK_SECRET_KEY;
const STRIPE_API_KEY = process.env.STRIPE_API_KEY;

const plugins = [
  `medusa-fulfillment-manual`,
  `medusa-payment-manual`,
  {
    resolve: `@medusajs/file-local`,
    options: {
      upload_dir: "uploads",
    },
  },
  {
    resolve: `medusa-payment-stripe`,
    options: {
      api_key: STRIPE_API_KEY,
    },
  },
  {
    resolve: `medusa-payment-paystack`,
    options: {
      secret_key: PAYSTACK_SECRET_KEY,
    },
  },
  {
    resolve: "@medusajs/admin",
    /** @type {import('@medusajs/admin').PluginOptions} */
    options: {
      autoRebuild: true,
      develop: {
        open: process.env.OPEN_BROWSER !== "false",
      },
    },
  },
];

const modules = {
  /*eventBus: {
    resolve: "@medusajs/event-bus-redis",
    options: {
      redisUrl: REDIS_URL
    }
  },
  cacheService: {
    resolve: "@medusajs/cache-redis",
    options: {
      redisUrl: REDIS_URL
    }
  },*/
};

/** @type {import('@medusajs/medusa').ConfigModule["projectConfig"]} */
const projectConfig = {
  jwtSecret: process.env.JWT_SECRET,
  cookieSecret: process.env.COOKIE_SECRET,
  store_cors: STORE_CORS,
  database_url: DATABASE_URL,
  admin_cors: ADMIN_CORS,
  // Uncomment the following lines to enable REDIS
  // redis_url: REDIS_URL
};

/** @type {import('@medusajs/medusa').ConfigModule} */
module.exports = {
  projectConfig,
  plugins,
  modules,
};

And that's all for the backend. Go to your terminal and run yarn start to start up your backend server and admin dashboard.

Adding Paystack as a Payment Option on the Admin Dashboard.

With your backend now configured and running on the terminal. Open up your browser and go to http://localhost:9000/app to access your admin dashboard. Log in using your credentials and use the following steps to Add Paystack as a payment option.

On the navigation panel, click on the settings button to go to the settings page.
Next, click on the + icon to set up a new region or choose an existing region. click on the three dots and select Edit region to edit the details about a particular region.
Enter the necessary details (Country, currency, etc). Scroll to the bottom of the page where you have Payment Providers. If you set up the Medusa backend correctly, you should see paystack as a payment option. Select it and save.

note: on the settings page you can add a new currency specific to your region by opening the currency tab.

That's all you have to do on your Admin dashboard. Next, we will setup and configure our Storefront.

Setting up and Configuring the Storefront

For the storefront, we'll be using the Medusa Nextjs starter template. Use the following steps to install.

Installing the Storefront

Open your terminal and type run the following

npx create-next-app -e https://github.com/medusajs/nextjs-starter-medusa my-medusa-storefront

After the installation process, change to the newly created directory my-medusa-storefront and rename the template environment variable file to use environment variables in development:

cd my-medusa-storefront
mv .env.template .env

note: running the storefront in a Windows environment throws some errors, you should instead run it on a Linux-like environment.

Installing Packages

Open up your terminal and run the following command to install the react-paystack package:

yarn add react-paystack
//you might need to delete the package-lock.json

This is a React library for implementing a Paystack payment gateway in React applications. It provides us with some vital components and functions to initiate and authorize payments.

Open up your project within your code editor and navigate to the .env file to add your paystack public test key using the format below:

# Paystack Public Key
NEXT_PUBLIC_PAYSTACK_PUBLIC_KEY=yourpublicapikey

Configuring the Paystack Button Component

Next, we will need to add Paystack as a payment provider in the payment button component. Navigate to the /src/modules/checkout/components/payment-button/index.tsx file and update it using the following steps:

First, we import the PaystackButton component from the react-paystack component we installed earlier.

import { PaystackButton } from "react-paystack"

Next, we will add paystack as a case in the switch statement within the PaymentButton function. In this case, we'll return a PayStackPaymentButton component which we'll create in the next step. Update the switch statement to look like this:

switch (paymentSession?.provider_id) {
    case "stripe":
      return (
        <StripePaymentButton session={paymentSession} notReady={notReady} />
      )
    case "paystack":
      return (
        <PayStackPaymentButton session={paymentSession} notReady={notReady} />
      )
    case "manual":
      return <ManualTestPaymentButton notReady={notReady} />
    case "paypal":
      return (
        <PayPalPaymentButton notReady={notReady} session={paymentSession} />
      )
    default:
      return <Button disabled>Select a payment method</Button>
  }

Now, it's time to create the PayStackPaymentButton we used earlier. To do that, create a new component just under the PaymentButton like the one below.

/* 
Assigns the value of the environment variable 
NEXT_PUBLIC_PAYSTACK_PUBLIC_KEY to PAYSTACK_PUBLIC_KEY 
or an empty string if the environment variable is not set
*/
const PAYSTACK_PUBLIC_KEY = process.env.NEXT_PUBLIC_PAYSTACK_PUBLIC_KEY || ""
const PayStackPaymentButton = ({
  session,
  notReady,
}: {
  session: PaymentSession
  notReady: boolean
}) => {
  const { cart } = useCart()
  const { onPaymentCompleted } = useCheckout()

  const txRef = String(session.data?.paystackTxRef)
  const total = cart?.total || 0
  const email = cart?.email || ""
  const currency =
    cart?.region.currency_code.toUpperCase() === "NGN" ? "NGN" : "USD" || "NGN"

  return (
    <PaystackButton
      email={email}
      amount={total}
      reference={txRef}
      publicKey={PAYSTACK_PUBLIC_KEY}
      currency={currency}
      text="Pay with Paystack"
      onSuccess={onPaymentCompleted}
    />
  )
}

The code above defines a component called PayStackPaymentButton which takes two props: session of type PaymentSession and notReady of type boolean.

Within the component, it uses hooks to access the cart and checkout functionalities. It extracts the paystackTxRef from the session data, the total from the cart, and the email from the cart.

Based on the region currency code in the cart, it determines the currency to be either "NGN" or "USD" (defaulting to "NGN" if neither).

Finally, it renders the PaystackButton component imported from the react-paystack library called with various props including the extracted email, total, txRef, PAYSTACK_PUBLIC_KEY, currency, and a success callback function called onPaymentCompleted. which was destructured from the useCheckout hook.

After adding all these changes, your payment button component should look like this

import { useCheckout } from "@lib/context/checkout-context"
import { PaymentSession } from "@medusajs/medusa"
import Button from "@modules/common/components/button"
import Spinner from "@modules/common/icons/spinner"
import { OnApproveActions, OnApproveData } from "@paypal/paypal-js"
import { PayPalButtons, PayPalScriptProvider } from "@paypal/react-paypal-js"
import { useElements, useStripe } from "@stripe/react-stripe-js"
import { useCart } from "medusa-react"
import React, { useEffect, useState } from "react"
import { PaystackButton } from "react-paystack"

type PaymentButtonProps = {
  paymentSession?: PaymentSession | null
}

const PaymentButton: React.FC<PaymentButtonProps> = ({ paymentSession }) => {
  const [notReady, setNotReady] = useState(true)
  const { cart } = useCart()

  useEffect(() => {
    setNotReady(true)

    if (!cart) {
      return
    }

    if (!cart.shipping_address) {
      return
    }

    if (!cart.billing_address) {
      return
    }

    if (!cart.email) {
      return
    }

    if (cart.shipping_methods.length < 1) {
      return
    }

    setNotReady(false)
  }, [cart])

  switch (paymentSession?.provider_id) {
    case "stripe":
      return (
        <StripePaymentButton session={paymentSession} notReady={notReady} />
      )
    case "paystack":
      return (
        <PayStackPaymentButton session={paymentSession} notReady={notReady} />
      )
    case "manual":
      return <ManualTestPaymentButton notReady={notReady} />
    case "paypal":
      return (
        <PayPalPaymentButton notReady={notReady} session={paymentSession} />
      )
    default:
      return <Button disabled>Select a payment method</Button>
  }
}

const PAYSTACK_PUBLIC_KEY = process.env.NEXT_PUBLIC_PAYSTACK_PUBLIC_KEY || ""
const PayStackPaymentButton = ({
  session,
  notReady,
}: {
  session: PaymentSession
  notReady: boolean
}) => {
  const { cart } = useCart()
  const { onPaymentCompleted } = useCheckout()

  const txRef = String(session.data?.paystackTxRef)
  const total = cart?.total || 0
  const email = cart?.email || ""
  const currency =
    cart?.region.currency_code.toUpperCase() === "NGN" ? "NGN" : "NGN" || "NGN"

  return (
    <PaystackButton
      email={email}
      amount={total}
      reference={txRef}
      publicKey={PAYSTACK_PUBLIC_KEY}
      currency={currency}
      text="Pay with Paystack"
      onSuccess={onPaymentCompleted}
    />
  )
}

const StripePaymentButton = ({
  session,
  notReady,
}: {
  session: PaymentSession
  notReady: boolean
}) => {
  const [disabled, setDisabled] = useState(false)
  const [submitting, setSubmitting] = useState(false)
  const [errorMessage, setErrorMessage] = useState<string | undefined>(
    undefined
  )

  const { cart } = useCart()
  const { onPaymentCompleted } = useCheckout()

  const stripe = useStripe()
  const elements = useElements()
  const card = elements?.getElement("cardNumber")

  useEffect(() => {
    if (!stripe || !elements) {
      setDisabled(true)
    } else {
      setDisabled(false)
    }
  }, [stripe, elements])

  const handlePayment = async () => {
    setSubmitting(true)

    if (!stripe || !elements || !card || !cart) {
      setSubmitting(false)
      return
    }

    await stripe
      .confirmCardPayment(session.data.client_secret as string, {
        payment_method: {
          card: card,
          billing_details: {
            name:
              cart.billing_address.first_name +
              " " +
              cart.billing_address.last_name,
            address: {
              city: cart.billing_address.city ?? undefined,
              country: cart.billing_address.country_code ?? undefined,
              line1: cart.billing_address.address_1 ?? undefined,
              line2: cart.billing_address.address_2 ?? undefined,
              postal_code: cart.billing_address.postal_code ?? undefined,
              state: cart.billing_address.province ?? undefined,
            },
            email: cart.email,
            phone: cart.billing_address.phone ?? undefined,
          },
        },
      })
      .then(({ error, paymentIntent }) => {
        if (error) {
          const pi = error.payment_intent

          if (
            (pi && pi.status === "requires_capture") ||
            (pi && pi.status === "succeeded")
          ) {
            onPaymentCompleted()
          }

          setErrorMessage(error.message)
          return
        }

        if (
          (paymentIntent && paymentIntent.status === "requires_capture") ||
          paymentIntent.status === "succeeded"
        ) {
          return onPaymentCompleted()
        }

        return
      })
      .finally(() => {
        setSubmitting(false)
      })
  }

  return (
    <>
      <Button
        disabled={submitting || disabled || notReady}
        onClick={handlePayment}
      >
        {submitting ? <Spinner /> : "Checkout"}
      </Button>
      {errorMessage && (
        <div className="text-red-500 text-small-regular mt-2">
          {errorMessage}
        </div>
      )}
    </>
  )
}

const PAYPAL_CLIENT_ID = process.env.NEXT_PUBLIC_PAYPAL_CLIENT_ID || ""

const PayPalPaymentButton = ({
  session,
  notReady,
}: {
  session: PaymentSession
  notReady: boolean
}) => {
  const [submitting, setSubmitting] = useState(false)
  const [errorMessage, setErrorMessage] = useState<string | undefined>(
    undefined
  )

  const { cart } = useCart()
  const { onPaymentCompleted } = useCheckout()

  const handlePayment = async (
    _data: OnApproveData,
    actions: OnApproveActions
  ) => {
    actions?.order
      ?.authorize()
      .then((authorization) => {
        if (authorization.status !== "COMPLETED") {
          setErrorMessage(`An error occurred, status: ${authorization.status}`)
          return
        }
        onPaymentCompleted()
      })
      .catch(() => {
        setErrorMessage(`An unknown error occurred, please try again.`)
      })
      .finally(() => {
        setSubmitting(false)
      })
  }
  return (
    <PayPalScriptProvider
      options={{
        "client-id": PAYPAL_CLIENT_ID,
        currency: cart?.region.currency_code.toUpperCase(),
        intent: "authorize",
      }}
    >
      {errorMessage && (
        <span className="text-rose-500 mt-4">{errorMessage}</span>
      )}
      <PayPalButtons
        style={{ layout: "horizontal" }}
        createOrder={async () => session.data.id as string}
        onApprove={handlePayment}
        disabled={notReady || submitting}
      />
    </PayPalScriptProvider>
  )
}

const ManualTestPaymentButton = ({ notReady }: { notReady: boolean }) => {
  const [submitting, setSubmitting] = useState(false)

  const { onPaymentCompleted } = useCheckout()

  const handlePayment = () => {
    setSubmitting(true)

    onPaymentCompleted()

    setSubmitting(false)
  }

  return (
    <Button disabled={submitting || notReady} onClick={handlePayment}>
      {submitting ? <Spinner /> : "Checkout"}
    </Button>
  )
}

export default PaymentButton

Finally, we need to add Paystack as an option in our payment element. Navigate to /src/modules/checkout/components/payment-element/index.tsx and update the PaymentInfoMap object to look like this

const PaymentInfoMap: Record<string, { title: string; description: string }> = {
  stripe: {
    title: "Credit card",
    description: "Secure payment with credit card",
  },
  "stripe-ideal": {
    title: "iDEAL",
    description: "Secure payment with iDEAL",
  },
  paypal: {
    title: "PayPal",
    description: "Secure payment with PayPal",
  },
  paystack: {
    title: "Paystack",
    description: "Secure payment with Paystack",
  },
  manual: {
    title: "Test payment",
    description: "Test payment using medusa-payment-manual",
  },
}

This code defines a constant variable named "PaymentInfoMap" as an object with key-value pairs. The keys are strings representing various payment methods, and the values are objects with two properties: "title" and "description".

And voila, you've successfully integrated the Paystack payment processor into the Medusa e-commerce application. Here's a quick demo of the checkout process

https://youtu.be/_AN60Cg7wOI

Conclusion

In this article, we've covered how to implement a custom payment processor like Paystack into a Medusa e-commerce application.

The process involves setting up the Medusa backend and admin dashboard, installing the necessary packages, configuring the backend to include the Paystack plugin, and adding Paystack as a payment option in the admin dashboard. Additionally, the storefront needs to be set up and configured to integrate Paystack as a payment provider. This includes installing the Medusa Next.js starter template, configuring the Paystack button component in the payment button module, and adding paystack as an option in the payment element.

By following these steps, you can successfully integrate Paystack into MedusaJS and offer seamless payment experiences to customers. The integration of Paystack expands the payment options available to customers, enhances security, and ensures a smooth checkout process, ultimately improving the overall user experience and driving customer satisfaction.

Resources

Medusa Documentation: The official documentation of Medusa provides in-depth information about the platform's features, architecture, and usage. It serves as a comprehensive guide to help you understand and utilize Medusa effectively.
Medusa GitHub Repository: The GitHub repository of Medusa houses the source code, issue tracker, and community contributions. You can explore the repository to access the latest updates, contribute to the project, or report any issues you encounter.
Paystack Documentation: If you want to delve deeper into Paystack's capabilities and explore its features, the Paystack documentation provides comprehensive resources, including API references, integration guides, and troubleshooting tips.
Article Code Repository: Access the GitHub repository containing the code for this article to explore the complete implementation of the Paystack custom payment gateway in Medusa. The repository includes the backend and frontend code, as well as instructions for setup and configuration.

Introduction to Authentication and Authorization using JSON Web Tokens in Nodejs

Tonie — Thu, 11 May 2023 05:54:46 +0000

As someone who’s been deeply involved with web applications, I can’t emphasize enough how critical they’ve become in our daily lives. Consequently, they demand reliable authentication and authorization mechanisms to safeguard sensitive information from prying eyes. In my opinion, JSON Web Tokens (JWT) offer a refreshingly simple yet secure way to implement these mechanisms in Node.js applications. In this article, I’ll provide you with a detailed guide to JWT-based authentication and authorization in Node.js, complete with a step-by-step walkthrough, helpful code snippets, and best practices you can follow.

What are JSON Web Tokens (JWTs)?

JSON Web Tokens (JWTs) are compact, URL-safe means of representing claims to be transferred between two parties. JWTs consist of three parts: a header, a payload, and a signature. The header contains metadata about the token, such as the algorithm used to sign it. The payload contains claims, which are statements about an entity (typically, the user) and additional data. The signature is used to verify that the sender of the JWT is who it says it is and to ensure that the message wasn’t changed along the way.

JWTs provide several advantages over traditional session-based authentication. Firstly, they don’t require storing user information on the server, which makes them highly scalable and easy to use. Secondly, they are stateless, which means that there is no need to manage server-side sessions. Thirdly, they can be easily exchanged between different systems and applications.

Overview of JWT structure

JSON Web Tokens (JWTs) are a type of token that consists of three parts: a header, a payload, and a signature. JWTs are encoded in Base64 URL format, which makes them easy to transmit over HTTP.

The header of a JWT contains information about the token, such as the algorithm used for the signature. The header is typically a JSON object that looks like this:

{
  "alg": "HS256",
  "typ": "JWT"
}

The alg property specifies the algorithm used for the signature, which can be HMAC, RSA, or ECDSA. The typ property specifies the type of token, which is always “JWT” for JWTs.

The payload of a JWT contains the claims, or pieces of information, about the user or client. The payload is also a JSON object that looks like this:

{
  "sub": "1234567890",
  "name": "John Doe",
  "iat": 1516239022
}

The sub property specifies the subject of the token, which is typically the user ID. The name property specifies the name of the user. The iat property specifies the time at which the token was issued, in Unix timestamp format.

Finally, the signature of a JWT is used to verify the integrity of the token. The signature is calculated by combining the header and payload of the token with a secret key, and then encoding the result using the algorithm specified in the header.

HMACSHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  your-256-bit-secret
) secret base64 encoded

JWT claims and their significance

JWT claims are pieces of information about the user or client that are included in the token’s payload. Claims can be used to provide context about the user or client, such as their ID or role, and can be used for both authentication and authorization purposes.

There are three types of claims in a JWT:

Registered claims – These are a set of predefined claims that are commonly used in JWTs. Some examples of registered claims include iss (issuer), exp (expiration time), and nbf (not before). Registered claims are optional, but using them can make your JWTs more interoperable with other systems.
Public claims – These are claims that are defined by the user and are intended to be shared with others. Public claims should follow the naming conventions specified in the JWT specification.
Private claims – These are claims that are specific to your application and are not intended to be shared with others. Private claims should use a namespace that is specific to your application, to avoid conflicts with other claims.

Uses of JWT Claims

JWT claims can be used for various purposes in your application, including:

Authentication – JWTs can be used to authenticate users by including a sub claim in the payload that identifies the user. When a user logs in, you can create a JWT with the user’s ID as the sub claim, and then use the JWT to authenticate the user on subsequent requests.
Authorization – JWTs can be used to authorize users by including a roles claim in the payload that specifies the user’s roles or permissions. When a user makes a request, you can verify their JWT and check whether the roles claim includes the required role for the requested action.
Statelessness – Because JWTs contain all the necessary information about the user or client, they can be used to create stateless APIs. This means that you don’t need to store session data on the server, which can improve scalability and reduce complexity.

Benefits of JWT

Stateless: JWTs are stateless, meaning that the server does not need to keep track of sessions or tokens. This makes JWTs easier to scale and more efficient to use in distributed systems.
Cross-domain: JWTs can be used across different domains and servers, making them a flexible solution for authentication and authorization in modern web applications.
Security: JWTs are digitally signed using a secret key, making it difficult for an attacker to forge or tamper with the token. Additionally, JWTs can be encrypted to provide an extra layer of security.
Decentralized: JWTs can be generated and verified by different services, allowing for decentralized authentication and authorization in microservices architectures.
Payload: JWTs can contain a payload of user data, such as user ID or user permissions, making them useful for authorization as well as authentication.

Authentication with JWT in Node.js

Authentication is the process of verifying the identity of a user or a client trying to access a resource or service. In Node.js, authentication is typically implemented by requiring users to provide a valid set of credentials, such as a username and password, to gain access to the application. The server then checks the provided credentials against a database or a third-party authentication service, and if the credentials are valid, the user is granted access.

When a user or client logs in to a Node.js web application, the server generates a JWT and sends it back to the client. This JWT contains a set of claims, which are pieces of information about the user or client, such as their ID or role. The JWT is then stored on the client side, typically in a cookie or in local storage.

The authentication process using JWT involves three steps: (1) the client sends a login request with their credentials, (2) the server verifies the credentials and generates a JWT, and (3) the server sends the JWT to the client, which can then use it to access protected resources.

To implement JWT-based authentication in Node.js, you can use the “jsonwebtoken” library. Here’s a step-by-step guide:

Install the “jsonwebtoken” library using npm.

`npm install jsonwebtoken`

Create a login route in your Node.js application that accepts user credentials (e.g., username and password).
Validate the credentials and generate a JWT using the “jsonwebtoken” library.
Send the JWT back to the client as a response.

app.post('/login', (req, res) => {
  const { username, password } = req.body;

  // Check if the user exists and the password is correct
  const user = users.find(user => user.username === username && user.password === password);

  if (!user) {
    return res.status(401).json({ message: 'Invalid username or password' });
  }

  // Generate a JWT with a secret key
  const payload = { username: user.username };
  const secretKey = 'mySecretKey';
  const options = { expiresIn: '1h' };
  const token = jwt.sign(payload, secretKey, options);

  // Return the token to the client
  res.status(200).json({ token });
});

In the example above, we create a login route that accepts a username and password from the client. We then check if the user exists and the password is correct. If the credentials are valid, we generate a JWT using the “jsonwebtoken” library and send it back to the client as a response.

Authorization with JWT in Node.js

Authorization, on the other hand, is the process of determining whether a user or a client has the necessary permissions to access a specific resource or perform a specific action in the application. In Node.js, authorization is typically implemented by assigning roles or permissions to users based on their identity or other attributes. For example, a user with an “admin” role may be authorized to access and modify certain parts of the application, while a regular user may only be authorized to view certain resources.

Authorization in the context of JWTs is often implemented by including user or client permissions as claims in the JWT. For example, a user with an “admin” role may have an “admin” claim in their JWT, which grants them access to certain parts of the application that regular users cannot access. The server can then check the presence of the “admin” claim in the JWT to determine whether the user is authorized to perform a specific action or access a specific resource.

Once a client has a valid JWT, they can use it to access protected resources on the server. To implement JWT-based authorization in Node.js, you can use middleware functions that verify the JWT and check the user’s permissions before allowing access to the protected resource.

Here’s a step-by-step guide for implementing JWT-based authorization in Node:

Create a middleware function that verifies the JWT and check the user’s permissions before allowing access to the protected resource.

const authMiddleware = (req, res, next) => {
  const token = req.headers.authorization;

  if (!token) {
    return res.status(401).json({ message: 'No token provided' });
  }

  jwt.verify(token, secretKey, (err, decoded) => {
    if (err) {
      return res.status(401).json({ message: 'Invalid token' });
    }

    req.user = decoded;
    next();
  });
};

app.get('/protected', authMiddleware, (req, res) => {
  res.status(200).json({ message: 'You are authorized to access this resource' });
});

In the example above, we create a middleware function that verifies the JWT and sets the decoded payload as the req.user object. We then use this middleware function to protect the /protected route.

When a client tries to access the /protected route, the middleware function will verify the JWT in the “Authorization” header. If the JWT is valid, the middleware function will set the req.user object and allow the client to access the protected resource. If the JWT is invalid or missing, the middleware function will return an error response.

Token Refresh and Expiry

One of the key features of JWTs is their ability to set an expiration time for the token. This provides an added layer of security by ensuring that a token cannot be used indefinitely. When a token expires, the user must obtain a new token to continue accessing protected resources.

In addition to setting an expiration time, JWTs can also include a refresh token. A refresh token is a separate token that is used to obtain a new JWT when the original token has expired. This can provide a better user experience by allowing users to continue accessing protected resources without having to constantly log in.

To implement token refresh and expiry in your Node.js application, you can use a combination of middleware and token management libraries. Here’s an example of how to implement token refresh and expiry using the jsonwebtoken library:

const jwt = require('jsonwebtoken');
const refreshTokenSecret = 'your_refresh_token_secret';
const accessTokenSecret = 'your_access_token_secret';
const refreshTokens = [];

// Middleware to check if user is authenticated
const authenticateJWT = (req, res, next) => {
  const authHeader = req.headers.authorization;
  if (authHeader) {
    const token = authHeader.split(' ')[1];

    jwt.verify(token, accessTokenSecret, (err, user) => {
      if (err) {
        return res.sendStatus(403);
      }

      req.user = user;
      next();
    });
  } else {
    res.sendStatus(401);
  }
};

// Endpoint to generate new access and refresh tokens
app.post('/token', (req, res) => {
  const { refreshToken } = req.body;
  if (!refreshToken || !refreshTokens.includes(refreshToken)) {
    return res.sendStatus(403);
  }

  jwt.verify(refreshToken, refreshTokenSecret, (err, user) => {
    if (err) {
      return res.sendStatus(403);
    }

    const accessToken = jwt.sign({ username: user.username }, accessTokenSecret, { expiresIn: '15m' });
    res.json({ accessToken });
  });
});

// Endpoint to log in and generate access and refresh tokens
app.post('/login', (req, res) => {
  // authenticate user
  const username = req.body.username;
  const user = { username: username };

  const accessToken = jwt.sign(user, accessTokenSecret, { expiresIn: '15m' });
  const refreshToken = jwt.sign(user, refreshTokenSecret);
  refreshTokens.push(refreshToken);

  res.json({ accessToken, refreshToken });
});

// Endpoint to log out and revoke refresh token
app.post('/logout', (req, res) => {
  const { refreshToken } = req.body;
  if (!refreshToken) {
    return res.sendStatus(400);
  }

  const index = refreshTokens.indexOf(refreshToken);
  if (index !== -1) {
    refreshTokens.splice(index, 1);
  }

  res.sendStatus(204);
});

In this example, we’re using two JWT secrets: one for access tokens and one for refresh tokens. We’re also storing refresh tokens in an array on the server, so that we can check whether a given refresh token is valid.

The authenticateJWT middleware checks whether a user is authenticated by verifying the access token. If the token is valid, it sets the req.user property to the user object.

The /token endpoint is used to generate new access tokens using a valid refresh token. If the refresh token is valid, we verify it and generate a new access token with a 15 minute expiration time.

The /login endpoint is used to log in and generate a new access token and refresh token pair. We generate both tokens and store the refresh token in the refreshTokens array

Best Practices for JWT-based Authentication and Authorization

Here are some best practices to follow when implementing JWT-based authentication and authorization in Node.js:

Always use a secure random secret key for signing and verifying JWTs.
Use short-lived JWTs (e.g., one hour) to minimize the risk of token hijacking.
Implement rate limiting and other security measures to prevent brute force attacks on the login endpoint.
Use HTTPS to encrypt all communication between the client and the server.
Store sensitive user data (e.g., passwords) securely using hashing and salting.
Use a consistent naming convention for JWT-related headers and payload fields.
Use middleware functions to validate JWTs and protect resources.

Conclusion

JSON Web Tokens (JWTs) provide a secure and efficient way to implement authentication and authorization in Node.js applications. By following the best practices outlined in this article, you can ensure that your JWT-based authentication and authorization system is robust and secure.

What is Algorithmic Efficiency?: An Introduction to Asymptotic Analysis.

Tonie — Mon, 13 Mar 2023 08:00:39 +0000

Algorithms are at the heart of computer science and programming. They are a set of instructions that a computer follows to perform a specific task.

It's like a recipe that helps you bake a cake or cook a meal, but for computers. Just like there are different recipes to cook a meal, there are also different ways to solve a problem in programming and it is in the interest of the programmer to pick the most efficient approach.

Algorithmic efficiency is the measurement of the performance of an algorithm in terms of time and space/memory complexity. Simply put, an efficient/ideal algorithm takes up the least possible memory and executes it in the least possible time.

When analyzing algorithms, it's not enough to simply measure how long an algorithm takes to run on a specific input. Instead, we need to have an understanding of how an algorithm's performance scales as the input size grows.

This is where Asymptotic analysis comes in. It allows us to analyze the performance of an algorithm as the input size grows larger and larger. By using asymptotic analysis, we can compare different algorithms and make informed decisions about which algorithm to use in a given situation. We can also identify bottlenecks in an algorithm's performance and find ways to optimize it.

What is Asymptotic Analysis?

Asymptotic analysis is a technique that is used to analyze the behavior and performance of an algorithm as the input size grows larger and larger.

To understand this, let's consider a simple example:

Imagine you were given an array of numbers and told to find a number within that list and deduce its position.

Linear Search Algorithm

One way you can solve this task is to go into the array and check the position of every value in the list until we get to the value we are looking for. And if we don't find the value only then can we confirm that the element does not exist in the array.

This is called the linear search algorithm and here is an example of its implementation in python:

def linear_search(array, target):
    for i in range(len(array)):
        if array[i] == target:
            return i
    return None

In the above code, the function linear_search function takes an array and a target element as inputs. It then iterates through each element in the array until it finds the target element, and returns the index position of the target element. If the target element is not found in the array, the function returns None.

Given an array of 5 elements, this might look like a very good algorithm as it won't take much time to find the target element. But if we keep increasing the size of the array, we would find out that there would be a proportionate increase in the amount of time it will take for our algorithm to execute the task.

A graphical interpretation of this algorithm will look like this:

As we can see, this is not an efficient algorithm because as the input size increases, it takes more and more time to execute.

Here's a better way to search -

Binary Search Algorithm

This algorithm begins by comparing the target value to the middle element of the array. If the middle element is the target value, the search is complete. Otherwise, the algorithm determines whether the target value is greater or less than the middle element, and discards half of the list based on this comparison. The process is repeated with the remaining half of the list until the target value is found or the list is empty

For example, let's say we have a sorted list of numbers [0, 1, 3, 4, 5, 7, 9, 11, 13] and we want to search for the value 7.

The algorithm starts by comparing 7 to the middle element, which is 5.
Since 7 is greater than 5, the algorithm discards the first half of the list and repeats the process with the remaining half [7, 9, 11, 13].
The algorithm now compares 7 to the middle element of this new list, which is 9.
Since 7 is less than 9, the algorithm discards the second half of the list and repeats the process with the remaining half [7].
The algorithm has now found the target value and the search is complete.

Note: In a binary search, the elements must be arranged in sorted order.

Here's an implementation of the binary search algorithm in python:

def binary_search(list, item):
    low = 0
    high = len(list) - 1

    while low <= high:
        mid = int((low + high)/2)
        guess = list[mid]

        if guess == item:
            return mid
        if guess > item:
            high = mid - 1
        else:
            low = mid + 1
    return None

sorted_list = [0, 1, 3,4, 5, 7, 9, 11, 13] 

print(binary_search(sorted_list, 7))

Now let's see the graphical representation of how this algorithm compares to the linear search algorithm

As we can see, the binary search outperforms the linear search algorithm as the input size keeps increasing. This makes it a more efficient algorithm for this case.

I want you to observe something peculiar in the graph above. We can see that for small input sizes, the linear search algorithm and the binary search look to perform at the same rate. If we were to take our decision from this point, it would be a wrong and ill-informed decision. This is why we use asymptotic analysis!

Benefits of Asymptotic Analysis

As we have seen earlier, asymptotic analysis is a very important tool for analyzing the efficiency of algorithms. I've listed some of its benefits below:

Simplification: Asymptotic analysis allows us to simplify the performance analysis of algorithms by focusing on their growth rate as the input size increases.
Efficiency Comparison: Asymptotic analysis allows us to compare the efficiency of algorithms for large input sizes, regardless of the specific hardware or software environment in which they are executed.
Design Improvement: Asymptotic analysis can help us identify inefficiencies in algorithms and guide us in making improvements to their design, leading to faster and more scalable solutions.
Prediction: Asymptotic analysis can help us predict the behavior of algorithms for large input sizes, allowing us to plan for the resources needed to execute them effectively.
Language and platform independence: Asymptotic analysis provides a language and platform-independent way of analyzing algorithms, making it easier to communicate about their performance characteristics and compare them across different programming languages and platforms.

And that's a wrap 😃

As we have seen, Algorithmic efficiency refers to how well an algorithm performs in terms of the resources it requires, such as time and memory. Asymptotic analysis is a technique used to analyze the efficiency of an algorithm as the input size grows.

An efficient algorithm should be able to handle large inputs in a reasonable amount of time and with minimal memory usage.

If you found this article insightful, kindly like, comment, and share it. I'd like this article to reach as many people as possible.

Thank you and happy coding

Dockerizing Your React App: A Step-by-Step Guide

Tonie — Tue, 07 Mar 2023 08:20:18 +0000

Docker is a popular tool for software developers and engineers looking to streamline the process of building, testing, and deploying applications. With its ability to create lightweight, portable containers that can run on any platform, Docker has significantly impacted the way we build and deploy software applications.

One of the many benefits of Docker is that it allows you to easily containerize your applications, which can help to simplify the process of deploying your code to different environments. In this article, we will focus specifically on how to Dockerize a React application.

React is a popular JavaScript library for building user interfaces, while Vite is a modern build tool that enables fast and efficient development.

Prerequisite

To follow along in this tutorial, you will need the following:

Node and npm installed on your machine
A recent version of Docker on your local machine.
A text editor (preferably, VSCode)

Create a React Application

Create a new folder and open it within your text editor. Navigate to your terminal and type in the following command:
Go into the package.json file within your application and update the dev command within the script tag with this
Type in the following command to start your development server

How to Dockerize a React Application

Create two files in the root directory named Dockerfile Dockerfile.dev respectively. The difference between these files is that the former is used for a production build while the latter is used for a development build.
Copy the following code into the two Dockerfiles
Create a new file within the root directory and name it docker-compose.yml Copy the code below and paste it into the file
Now that we have set up our application. Go to your terminal and type in the following code to build the application

If everything ran successfuly, you should see a message like the one below in your terminal

docker-compose up
[+] Running 1/1
 - Container docker-react-client-1 Recreated 1.6s 
Attaching to docker-react-client-1
docker-react-client-1 | 
docker-react-client-1 | > docker-react@0.0.0 dev 
docker-react-client-1 | > vite --port 3000 --host
docker-react-client-1 | 
docker-react-client-1 | 
docker-react-client-1 | VITE v4.1.4 ready in 4809 ms
docker-react-client-1 | 
docker-react-client-1 | Local: http://localhost:3000/
docker-react-client-1 | Network: http://172.19.0.2:3000/

Voila!! You have dockerized your first react application. Now you can go ahead and develop your application and all the changes you make will be automatically picked up by docker whenever you run the docker-compose up command.

To see your application, go to your browser and type http://localhost:3000/

If you found this helpful, please like, comment and share it. I'd like this article to reach as many people as possible.

The source code can be found here on github. Don't forget to star

Building a Location-Map App in React using Vite and Mapbox

Tonie — Mon, 20 Feb 2023 10:35:44 +0000

Location-map apps like Google maps have become increasingly part of our day-to-day activities as we rely on them to navigate our surroundings and also get information about other places.

In this article, we will explore how to build a location-map app in React using Vite and Mapbox.

React is a popular JavaScript library for building user interfaces, while Vite is a modern build tool that enables fast and efficient development.

Mapbox, on the other hand, is a powerful platform for building custom maps and integrating them into web and mobile applications.

Throughout this article, we will cover the basic steps of setting up a React application, integrating Vite for fast development, and using Mapbox to add custom maps and location data to our app.

And by the end of this article, you will have the knowledge and tools to create your location-map app using these technologies.

Prerequisites

To follow along in this tutorial, you will need the following:

Basic knowledge of React and JavaScript
Node and npm installed on your machine
A Mapbox account (this is because you will need a personalized API key). If you don't have a Mapbox account, you can sign up using this link

You can view the live version of this project here. This will give you an idea and expectation of the application we will be building today

Building out our Location-Map App

Now that we have the prerequisites out of the way, it's time to get our hands dirty. Let's go!

Project setup

Create a new folder on your local machine and open it within your preferred code editor. In this tutorial, we named our folder "location-map" and we used VS Code as our code editor.

Open your terminal and type in the following command. This is to create our react project using Vite. The period sign "." tells Vite that we want our project to be initialized in our current directory.

npm create vite@latest . //if you use npm 
//or
yarn create vite . //if you use yarn

Follow the prompts using your arrow keys and pressing enter. Once you are done, you should have a project structure like the one below

Next, we need to install one dependency which is the Mapbox package. Open your terminal and type

npm install mapbox-gl //if you use npm
//or
yarn add mapbox-gl //if you use yarn

Configuring our App

Go into the index.css file within the src folder. Replace the css there with the one below

* {
  box-sizing: border-box;
  padding: 0;
  margin: 0;
}

body {
  margin: 0;
  font-size: 1rem;
  overflow-x: hidden;
}

Also, go into the App.css file and replace the code there with the one below:

.map-container {
  height: 100vh;
  width: 100vw;
}

.sidebar {
  background-color: rgba(35, 55, 75, 0.9);
  color: #fff;
  padding: 6px 12px;
  font-family: monospace;
  z-index: 1;
  position: absolute;
  bottom: 1rem;
  left: 0;
  margin: 12px;
  border-radius: 4px;
}

These are just some default styles for our component and divs which we will create later.

Also within the head tag in the index.html file, we need to add the following link tag. To enable us to use the default styles provided by Mapbox.

<link
      rel="stylesheet"
      href="https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-directions/v4.1.1/mapbox-gl-directions.css"
      type="text/css"
    />

Now go into the App.jsx file and delete every code logic within the div with the class name App. Your file should look like this.

Next go into your src folder and create a new file named ".env". This is where we will store our API key.

Go to your Mapbox dashboard and at the bottom of the page, you will find your API key. Copy and paste it into the .env file so:

VITE_MAPBOX_KEY = YOUR_API_KEY

Creating our Map using Mapbox

Go into the App.jsx file within the src folder and update the code to look like this:

import mapboxgl from "mapbox-gl";
import { useEffect, useRef, useState } from "react";
import "./App.css";

mapboxgl.accessToken = import.meta.env.VITE_MAPBOX_KEY;
function App() {
  const mapContainer = useRef(null);
  const map = useRef(null);
  const [lng, setLng] = useState(-70.9);
  const [lat, setLat] = useState(42.35);
  const [zoom, setZoom] = useState(9);

  useEffect(() => {
    if (map.current) return; // initialize map only once
    map.current = new mapboxgl.Map({
      container: mapContainer.current,
      style: "mapbox://styles/mapbox/streets-v12",
      center: [lng, lat],
      zoom: zoom,
    });

  return (
    <div className="App">
      <div ref={mapContainer} className="map-container" />
    </div>
  );
}

export default App;

In the code snippet above, we imported the Mapbox package we installed earlier and we initialized our access token with the value we stored in our .env file.

Next, we declared our app's default state using the useState and useRef hooks. Then we initialized our map using a useEffect hook. This will ensure that our map will be created as soon as our App component is mounted in the DOM.

Also, we rendered this map in a div within the return statement.

Open your terminal and start your application using the code below to see the application on your device's browser.

npm run dev 
//or
yarn run dev

Adding a Div to show Longitude, Latitude and Zoom level

Next, we need to add some interactivity to our application. First, we will add a div that shows the latitude and longitude of any location the user clicks on the map.

For this, add another useEffect hook to our App.jsx component just below the previous one.

 useEffect(() => {
    if (!map.current) return; // wait for map to initialize
    map.current.on("move", () => {
      setLng(map.current.getCenter().lng.toFixed(4));
      setLat(map.current.getCenter().lat.toFixed(4));
      setZoom(map.current.getZoom().toFixed(2));
    });
  });

This utilizes the useState hook we created earlier and updates the longitude, latitude and zoom level according to the user's interaction with the application.

Update the return block in our to look like this:

return (
    <div className="App">
      <div className="sidebar">
        Longitude: {lng} | Latitude: {lat} | Zoom: {zoom}
      </div>
      <div ref={mapContainer} className="map-container" />
    </div>
  );

Save your code and refresh your browser to see how it looks. Nice, yeah? Now let's add more functionality

Adding More Functionalities

For this, we need to add some code to our first useEffect code block. Update the useEffect code block to look like this:

useEffect(() => {
    if (map.current) return; // initialize map only once
    map.current = new mapboxgl.Map({
      container: mapContainer.current,
      style: "mapbox://styles/mapbox/streets-v12",
      center: [lng, lat],
      zoom: zoom,
    });
    map.current.addControl(new mapboxgl.NavigationControl());
    map.current.addControl(new mapboxgl.FullscreenControl());
    map.current.addControl(
      new mapboxgl.GeolocateControl({
        positionOptions: {
          enableHighAccuracy: true,
        },
        trackUserLocation: true,
      })
    );
  });

mapboxgl.NavigationControl() adds a button to enable the user zoom in, zoom out and rotate the map.
mapboxgl.FullscreenControl() adds a button that allows the user to full-screen mode.
mapboxgl.GeolocateControl() adds a button that lets the user view their current location

Adding the direction component

One final component we will need in our application is a direction component that lets the user know the distance and time it will take to get from one point on our map to another. This will specify different formats like driving, cycling, walking etc.

To achieve this, we'll be adding a cdn script tag to our index.html file. Add the following script tag within the head tag in the index.html file:

<script src="https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-directions/v4.1.1/mapbox-gl-directions.js"></script>

After adding this tag, your index.html file should look like this:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <script src="https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-directions/v4.1.1/mapbox-gl-directions.js"></script>
    <link
      rel="stylesheet"
      href="https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-directions/v4.1.1/mapbox-gl-directions.css"
      type="text/css"
    />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Location App using Map Box</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.jsx"></script>
  </body>
</html>

Next, we need to add some code to display the directions component in our application. To do that, add the following code snippet to the first useEffect code block in our App.jsx file:

  map.current.addControl(
      new MapboxDirections({
        accessToken: mapboxgl.accessToken,
      }),
      "top-left"
    );

This will add the direction control at the top-left of our screen. At this point your App.jsx file should look like this:

import mapboxgl from "mapbox-gl";
import { useEffect, useRef, useState } from "react";
import "./App.css";

mapboxgl.accessToken = import.meta.env.VITE_MAPBOX_KEY;

function App() {
  const mapContainer = useRef(null);
  const map = useRef(null);
  const [lng, setLng] = useState(-70.9);
  const [lat, setLat] = useState(42.35);
  const [zoom, setZoom] = useState(9);

  useEffect(() => {
    if (map.current) return; // initialize map only once
    map.current = new mapboxgl.Map({
      container: mapContainer.current,
      style: "mapbox://styles/mapbox/streets-v12",
      center: [lng, lat],
      zoom: zoom,
    });
    map.current.addControl(new mapboxgl.NavigationControl());
    map.current.addControl(new mapboxgl.FullscreenControl());
    map.current.addControl(
      new mapboxgl.GeolocateControl({
        positionOptions: {
          enableHighAccuracy: true,
        },
        trackUserLocation: true,
      })
    );

    map.current.addControl(
      new MapboxDirections({
        accessToken: mapboxgl.accessToken,
      }),
      "top-left"
    );
  });

  useEffect(() => {
    if (!map.current) return; // wait for map to initialize
    map.current.on("move", () => {
      setLng(map.current.getCenter().lng.toFixed(4));
      setLat(map.current.getCenter().lat.toFixed(4));
      setZoom(map.current.getZoom().toFixed(2));
    });
  });

  return (
    <div className="App">
      <div className="sidebar">
        Longitude: {lng} | Latitude: {lat} | Zoom: {zoom}
      </div>
      <div ref={mapContainer} className="map-container" />
    </div>
  );
}

export default App;

Conclusion

In this article, we explored how to build a location-map app in React using Vite and Mapbox.

We saw how to use React to build a flexible and responsive user interface that can easily integrate with Mapbox's mapping platform, which offers numerous customization options to create maps that fit the specific needs of our app.

Whether it's visualizing data, creating interactive experiences, or simply providing a more immersive way to view a location, a location-map app built with React, Vite, and Mapbox has the potential to be a valuable tool for a wide range of use cases.

Resources

Here are some useful resources to aid your development of this project

Project live version
Project Source code. Don't forget to star the repository
Mapbox React Documentation
Vite Docs

If you have any questions or suggestions, I'm buzzing to hear from you in the comment section.

Happy coding

What is Database Migration?: Benefits of Database Migration

Tonie — Thu, 16 Feb 2023 07:48:30 +0000

A database is an organized collection of structured and logically related data and information.

Databases play a crucial role in the development of modern-day technology, as they store and manage large amounts of data in an organized manner.

To keep up with the ever-increasing demand for better data management solutions, the rapid pace of technological advancements, and the growth of an application, businesses usually have to change the properties and confines of the database, to enhance performance, security, and scalability.

In this article, we'll explore the concept of database migration and its benefits.

What is Database Migration?

In an application's lifecycle, there might be a need to make changes to the functionality of the application. To track these changes, we employ the services of version control.

Version control is a set of practices and tools to track and manage our application's source files such that any version of the application at different points in the project's history can be retrieved.

But what if our application utilizes an external and explicit dependency like a database? How do we version control this dependency? The answer to this is database migration.

Database migration is a controlled way to manage and track incremental changes within a database.

It helps transform a database from its current state to a new or desired state while preventing the loss of data.

Why do we do Database Migration?

Let's consider a simple example:

Imagine you have an application that stores users' information. To store this data, you would probably need a database that looks like this 👇🏼

Now, due to certain reasons, you need to update the functionality of your application. Maybe the government says that all applications that process and store users' data must process and store their email too.

You quickly go over to your application and make changes to your codebase to accommodate this new rule by adding an extra field to the form and some logic to process it and then you realize that your database cannot store this new field as it was not predefined when creating the database.

Well, you could decide to create an entirely new database and then configure your application to utilize it. But there's a tradeoff here: you will lose all the data that was present in your old database!

So what's the solution to this dilemma? How do you update the boundaries and properties of your database to include this new field without losing your data?

The solution to this is database migration!

Database migration helps you make and track these changes within your database and also updates the properties of your database to reflect them while preserving your existing data.

Back to our example. If a migration tool was used to initialize our database it means that the migration tool is aware of the current state of our database which can be called version one.

Now to update the properties of our database, we would go into our migration script and redefine its properties to include or exclude the fields we want to have (in this case we want to add a new "email" column).

Our migration tool will now go back to our database and apply the changes structurally and logically while keeping our current data. This updated version of our database is now tracked and saved as "version 2". This means we can roll back these changes at any point during our application's life cycle.

Our updated database should look like this after the migration has taken place and we've added a new user

As we can see we have added a new user to the database with all the current fields and our old users that have not yet provided this information (the email) have been assigned a value of null.

Now they can be prompted to provide this information which will be used to populate their respective fields.

Benefits of Database Migration

As we have seen earlier, database migration is a very beneficial tool for software developers working with databases.

Here are some benefits of database migration

Preservation of data.
Creating a dependable data backup.
Increased efficiency within an application.
Reduced downtime.
Integration with modern technologies.

In conclusion, database migration is a critical process that enables businesses to enhance their data management capabilities by keeping track of the changes in their database.

It can help organizations achieve better performance, security, scalability, and flexibility while minimizing costs and downtime. However, the migration process can be complex, and several factors need to be considered to ensure a successful outcome.

It's essential to choose the right approach, plan the migration carefully, and perform thorough testing to minimize risks and avoid data loss.

By understanding database migration and its benefits, businesses can make smart decisions that help them achieve their data management goals and maintain a competitive advantage.

What is CORS? : How to enable CORS in Nodejs App.

Tonie — Mon, 13 Feb 2023 08:00:39 +0000

Cross-Origin Resource Sharing (CORS) is a web browser mechanism that allows for resources that are restricted outside a domain (origin) to be requested from another domain.

In this article, we'll get to understand why we use CORS and how to enable it in a Nodejs App.

Why do we use CORS?

To understand why we use CORS, we need to understand the underlying security risk it protects us from.

Web scripting is the process of creating and embedding scripts that automates various functions and sequential tasks in a web page. These scripts can be used for various purposes including animations, tracking of information within our application, integration, ads etc.

This variation poses a very potential security risk because third-party scripts can access our application and steal sensitive data which can then be used to perform some harmful operations within our application. Due to this risk, same-origin policy was introduced.

Same-origin policy is a web mechanism that allows a web page to retrieve or access resources from applications that are within its origin. Two resources can be said to have the same origin if their URL has the same host, port, and protocol.

For instance:

https://www.hashnode.com and https://www.hashnode.com/@TonieNG are of the same origin while https://www.hashnode.com/@TonieNG and https://tonie.hashnode.dev/ are of different origins.

CORS serves as a mechanism that when enabled can allow for resource sharing between applications that are of different origins and it is implemented on top of HTTP so that the server side can instruct the browser to allow interactions from certain URLs.

It consists of a preflight request, sent by the browser before each request. A set of headers should then be added on every server response (preflight or not) to allow or disallow the request if the origin is forbidden.

How to enable CORS in Nodejs App?

Create a new folder on your local device and open it with your preferred IDE. In this tutorial, I used VS Code.
Open your terminal and type in the following code to initialize a nodejs project:
Now we need to install the dependencies for this project. Open your terminal and enter this command
Create a file named index.js and in the package.json file add a start property within the script object. Your package.json and folder structure should look like this
Next, go into the index.js file and type in the following to set up our application using express:
Now to enable CORS , we will need to make a few changes to our index.js file. Update the contents of your file to look like this

As we can see, it's quite easy to set up CORS in our Nodejs Application. For further clarifications or research, check the cors documentation. I've also provided the GitHub repository that contains the code written in this tutorial here (give it a star).

If you have any question or suggestions, feel free to ask in the comment section. You can also shoot me a DM on Twitter.

Happy Coding

Sending Emails from a Nodejs Application using Nodemailer

Tonie — Fri, 27 Jan 2023 08:33:51 +0000

As a Software Developer, you've probably worked on a project where you need to communicate some information in real-time from your Nodejs application.

This information can be anything from password reset to notifications on subscription services, to changes in terms and services. There's a whole lot of information that can be communicated and there are several ways through which we can send this information.

In this article, we will learn how to send emails from a Nodejs application using nodemailer.

Why use Nodemailer?

There are different reasons why we should use Nodemailer to send emails, I've listed some of them below:

We can send different types of data like plain text, HTML content, etc.
It has OAuth2 authentication.
It has Unicode support for any character, which means we can send emojis within our emails
It uses different transport methods like the SES transport method in addition to the built-in SMTP support.

Prerequisites

To follow along, you would need the following:

A code editor of your choice (preferably VS Code) and a stable internet connection.
An updated version of the Nodejs software is installed on your local device. You can visit the Nodejs download site and follow the prompts to install it.
Minimal experience working with nodejs applications using express.js
Experience using API testing tools (preferably postman)

Now let's get to coding.....

Initializing our Nodejs project

Create a new folder, with any name of your choice and open it with your code editor. In this case, we used VS Code and we have named our folder "nodemailer-tutorial".
Open up your terminal and type in the following command
Now we need to install the dependencies that will be needed for this project. On your terminal, type in the following command and press enter.
Now we're done with the installation, go into the package.json file and within the script object, add this line of code.
For the next step, we need to create files and folders for our application.

Configuring our App and Creating Routes

Navigate to your index.js file and write the lines of code below:

const express = require("express");
const cors = require("cors");
const dotenv = require("dotenv");
const app = express();
const email = require("./routes/email");

app.use(express.json());
app.use(
  cors({
    origin: "*",
  })
);
dotenv.config();

app.get("/", (req, res) => {
  res.status(200).send("Welcome");
});

app.use("/email", email);

app.listen(process.env.PORT || 3000, () => {
  console.log(`Server is up and running`);
});

Here, we are importing the modules and packages we imported earlier and then configuring them. Also, we set up our app to listen on port 3000. To start up our application, open your terminal, type in npm start and hit enter. You should see a message that reads "Server is up and running". Go to postman and send a get request to this URL http://127.0.0.1:3000/. You should be met with a "Welcome" message like the one below.

Now go into the email.js file and then type in the following lines of code

const router = require("express").Router();
const sendMail = require("../utilities/sendemail");

router.post("/", async (req, res) => {
  try {
    // Here is where we write our logic and functionalities to send the email
  } catch (error) {
    res.status(500).send(error.message);
  }
});

module.exports = router;

Here we just set up the route that will be used for sending our emails. We also imported a module in the second line which is a function that defines how our emails are sent and structured.

Before we write out this function, we need to enable some security features on our host account (the email address from which we would send out emails). Go to your account settings and set up an "Application specific" credential for your nodejs application and you'll be provided with a password. Open up the .env file and type the following code.

HOST = smtp.gmail.com
SERVICE = gmail
EMAIL_PORT = 587
SECURE= true
USER = tutorial@gmail.com //Replace with your email address
PASS = password // Replace with your application-specific password

Note *: We are using Gmail in this tutorial. The settings might be different if you use another email service.*

Now go over to the sendemail.js file and type in the following code

const nodemailer = require("nodemailer");

module.exports = async (email, subject, text) => {
  try {
    // initialize and define the mode of transport
    const transporter = nodemailer.createTransport({
      host: process.env.HOST,
      service: process.env.SERVICE,
      port: Number(process.env.EMAIL_PORT),
      secure: Boolean(process.env.SECURE),
      auth: {
        user: process.env.USER,
        pass: process.env.PASS,
      },
    });

    // Defining the mail and sending it using the transport
    const sentEmail = await transporter.sendMail({
      from: process.env.USER,
      to: email,
      subject: subject,
      text: text,
    });
    const response = "Email sent successfully";
    console.log(response);
  } catch (error) {
    console.log(error.message);
    return response;
  }
};

Here, we created a function and within it, we used the nodemailer package to create a transport. Transport defines the method and medium that will be used to send the email. We also called the sendMail method that sends the email using the preselected transport object.

You can access the nodemailer documentation to learn more about these methods and parameters.

Back to the email.js Route

We can now use the sendemail function. To do that, update the code to look like this

const router = require("express").Router();
const sendMail = require("../utilities/sendemail");

router.post("/", async (req, res) => {
  try {
    const email = await req.body.email;
    const message = await req.body.message;
    const subject = await req.body.subject;

    const sentEmail = await sendMail(email, subject, message);

    return res.status(200).send("You email is on the way");
  } catch (error) {
    res.status(500).send(error.message);
  }
});

module.exports = router;

Let's test this out on postman. Copy the JSON object below and provide the details you want to send:

{
    "email": "myaddress@gmail.com", //Input the address you want to mail
    "subject": "Testing my email server", //Change to any subject you want
    "message": "Confirm you can see this" //Use a personalized message of your choice
}

Back to postman, go to "Body", click on "raw" and then select JSON. Paste the JSON object into the text area and send a post request to http://127.0.0.1:3000/email. Your request should look like this

Now check your recipient email inbox and you will see your message sitting right there waiting to be clicked.

Conclusion

And that's a wrap. We've successfully built a Nodejs application that enables us to send emails using Nodemailer: a module that allows you to send emails from your server with ease.

I've provided a link to the project on GitHub. Here you can find all the code snippets used for this project.

If you have any questions or suggestions, I'll be buzzing to hear from you in the comment section.

Happy coding 💫

What is a REST API?

Tonie — Tue, 18 Oct 2022 08:29:02 +0000

REST APIs provide a flexible and lightweight way to integrate applications and are emerging as the most popular way to connect components in microservices architectures.

An API (Application programming interface) is a a set of rules and protocols that defines how software products and applications communicate with each other.

Let's visualize an API as a waiter in a restaurant. You the customer can be referred to as the client while the chefs in the kitchen can be called the Server.

Now the Waiter is a way or protocol through which you place your order (communicate) to the chef (server) and also get a response if any (your food perhaps).

If there are any errors, let's say the food isn't available. The chef will communicate to you through the waiter and so on.

This simple analogy can be applied to how software applications communicate.

Now that we have had an overview of how APIs work, What is a REST API and why do we use it?

What is a REST API?

A REST API also known as RESTful API is an API that follows the design principles of REST (Representational State Transfer) architectural system.

REST APIs are the most widely appreciated APIs and are preferred to other APIs like SOAP or XML-RPC because of the flexibility it offers to software developers.

It is also language agnostic, meaning that they can be implemented in virtually any programming language and they support several data formats.

The only condition in developing REST APIs is that they conform to the following REST design principles listed below:

Uniform Interface : This means that each request made from the client to the server should look alike no matter where that request is made from. The REST API should guarantee that the same chunk of data from the client belongs to only one URI (Unique Resource Identifier).
Cacheability : Resources being communicated via a REST API should be cacheable on both the client and server side of the application. Responses should also include information that tells the client if caching is available for that resource. This helps improve performance on the client side and scalability on the server side.
Client-Server decoupling : The client and server side of the application must be independent of each other. The only information about the server that should be known by the client is the URI of a requested resource. The client should not be able to interact with the server in any way. Likewise, the server shouldn't be able to alter the client, it should only be able to process the requested data via HTTP.
Layered system architecture : The calls and responses in REST go through different categories also known as layers. This means that the client and server may not connect directly with each other. There may be several channels in the communication loop.

To this end, REST APIs need to be designed so that the client and server are not aware of the communication channel used(whether it's an end to end communication or through an intermediary between them).
Statelessness : REST APIs are stateless. Rather than relying on the server remembering previous requests, REST applications require each request to contain all of the information necessary for the server to process it. Server applications arent allowed to store any data related to a client request.

How does a REST API Work?

REST APIs communicate through HTTP(hyper text transfer protocol) to carry out database functions or operations like creating, reading, updating, and deleting information (also known as CRUD) within a resource.

In HTTP, there are five common methods that are used for communication, they are:

GET: The get method is used to read or retrieve the representation of a resource in a database.
POST: The post method is used to create new resources in the database.
PATCH: The patch method is used to modify the data or information within a resource identified by a URI. This request only needs to contain the changes to the resource not the complete resource.
PUT: The put method is used to update and modify the data within a resource identified by a URI. This request needs to contain the complete resource ie. if you want to change the username of a user, you'll need to provide every other information relating to that user resource.
DELETE: As the name implies, the delete method is used to delete a resource identified by a URI.

The state of a resource at any particular instant is known as the resource representation and this information can be delivered to a client in several formats including JavaScript Object Notation (JSON), HTML, XLT, Python, PHP, or plain text.

JSON is by far the most used between software developers because it is readable by both humans and machines and it is programming language-agnostic.

Request headers and response headers, along with conventional HTTP status codes, are commonly used within REST APIs.

Request headers and parameters contain important identifier information like metadata, authorizations, uniform resource identifiers (URIs), caching, cookies etc.

Benefits Of REST APIs

Flexibility and Scalability : One of the most important benefit of REST APIs is the scalability and flexibility it offers software engineers. REST APIs can be scaled quickly due to the separation between the client and the server. Additionally, due to its flexible nature engineers can also easily integrate REST APIs without much added work.
Independence : In the architectural design of REST APIs, the client and server are independent of each other. This means that engineers can go on to work on different parts of the application separately.
Lightweight : One of the main benefits of REST APIs is that they follow HTTP standard, which means that they're format-agonistic and you can use XML, JSON, HTML, etc. Making REST APIs fast and lightweight. This feature is particularly necessary for mobile app projects, internet of things devices, and more.

Disadvantage of REST APIs

Flexibility : Yeah, you heard right FLEXIBILITY! Although it is a big advantage of REST API design, it also makes it easy to develop an API thats broken or/and performs poorly.

REST APIs are the most popular and widely used APIs in the world of software development . They are efficient, high-performing, consume less bandwidth, and are cost-effective.

That's a wrap, you can go ahead and start building your own APIs. While designing your APIs, you should make sure to take cognizance of your consumer's objectives and then build accordingly.

If you have any questions or suggestions, I'll be buzzing to hear from you in the comment section.

Happy coding 💫

State Management in React with Redux Toolkit (RTK)

Tonie — Wed, 05 Oct 2022 09:32:18 +0000

Have you ever tried to re-render a component or some form of data whenever there's a change in the UI of your application?

You've probably tried to use Hooks to effect (pun intended :-) ) this change and where needed you've applied some prop values. Well you've just managed the state of your application.

But while this might be effective for your small and simple project, it's actually a reductant approach and might prove ineffective when you start working on bigger and more complex applications.

In this article, we'll be looking at the basics of state in React and how to manage it using Redux Toolkit (RTK).

State and state management is one of the most complex concepts for developers and quite rightly so.

The state is a built-in JavaScript object that contains the data and information about a component.

This data is dynamic and can be modified overtime. When they do, the component re-renders to reflect the necessary changes.

The change in state of a component can occur as a response to a user's action or a system generated event, either way these changes needs to be managed.

The state of an application helps us to track the changing data in a component and managing the state of application simply means managing the reaction of an application's component to these state changes.

There are 4 different kinds of states in React with different ways to mange them. However in this article, we'll be focusing on managing the Global state which is the state across multiple components.

Although this article is beginner friendly, I suggest you know a little bit of JavaScript and React in order to fully grasp the ideas, code and logic.

State Management using RTK

Let's imagine for a second we have a dashboard application in react where we display the user's information across multiple components like the Navbar, main page and possibly the footer.

This is a dynamic information that can change overtime ie it depends on the user's action.

Let's say the user wants to update the username and email, we have to somehow track this change and dynamically render it across the multiple components.

To do this, we could create the variables at the top level of our react application, and pass it as a prop down to its child components and then to its grandchild till we get to the components where it is needed. This is known as prop-drilling.

While this might work, it is redundant and makes it hard to maintain our application in the future.

Also we are often left with unnecessary prop values in components where they are not needed across multiple points in our application. To tackle this, we use state management tools like the Redux Toolkit.

The Redux Toolkit provides a very simple and straightforward solution: create a store independent from any component and then make it accessible to every component at all levels of our application.

Here are the steps in using the Redux Toolkit:

Install and Configure the Redux Toolkit and Redux
Create a Redux Folder (preferably)
Create a Slice
Create a store
Provide Store to React at the top most component
Proceed to use the store values anywhere across the application.

I'll be explaining each of these steps below, let's go! But first, go ahead and create your react application as I won't be going over that.

We'll be using the user information example we discussed earlier and also try to update the information across multiple components in our application.

Install and Configure Redux and Redux Toolkit.

In your terminal, type the following lines of code

npm install @reduxjs/toolkit react-redux

This will install and configure the Redux Toolkit

Create a Redux folder

Create a Folder for the Redux Logic preferably inside the src folder of your application. Let's call this folder redux.

Create a Redux Slice

Create a new file and name it userSlice.js. A slice is simply just a collection of our redux reducer logic and actions for a single feature in your react application defined together in a single file. Type in the following code snippet

import {createSlice} from "@reduxjs/toolkit"
export const useeSlice = createSlice ({
  name: "user",
  initialState: {
   username: "Tonie"
   email: "tonie@email.com"
  },
  reducers: {
   update: (state, action) => {
    state.username = action.payload.username;
    state.email= action.payload.email
   },
  },
})
export const {update} = userSlice.actions;
export default userSlice.reducer

What is happening here?

The name represents the name of our slice, in this case, we've chosen "user"
InitialState: This sets the initial or default state of our react element.
Reducers: This contains all the logic and actions that is used to update our state.
The action.payload tracks the changes to our state and passes it to the necessary state variables.

Create a Store

In React, a store is a state container which holds the application's state. Redux can have only a single store in your application and you have to specify or add our reducers from our slice to it. Type in the following in your redux store file.

import {configureStore} from "@reduxjs/toolkit"
import userReducer from './userSlice'
//this is a default export, that's why we could name it this way. It is our reducer in our slice

export default configureStore ({
 reducer: {
  user: userReducer,
 }
});

Provide the Redux Store to React

Once the store has been created, we can make it available to our React components by putting a React-Redux around our application in src/index.js. Import the Redux store we just created, put a around your , and pass the store as a prop:

import React from 'react'
import ReactDOM from 'react-dom'
import './index.css'
import App from './App'
import { store } from './app/store'
import { Provider } from 'react-redux'

ReactDOM.render(
  <Provider store={store}>
    <App />
  </Provider>,
  document.getElementById('root')
)

Proceed to use the store values anywhere across the application.

Now we can use the React-Redux hooks to let React components interact with the Redux store. We can read data from the store with useSelector, and dispatch actions using useDispatch hooks respectively.

To access the data from the store using the useSelector hook in any component, just type in the following code snippet.

import React from "react"
import { useSelector } from "react-redux"

export function Navbar() {
 const name = useSelector( (state) => state.user.username)

 const email = useSelector( (state) => state.user.email)
//Then we can proceed to use these variables to represent the name and email in out
}

This will assign the variables of name and email to the values contained in the store.

To change or update the values of our store variables, we make use of the useDispatch hook.

Let's say we have a form and a button that handles this update on the Update component of our application. And we want to update our user information we do it like so:

import { useState } from "react";
import { useSelector, useDispatch } from "react-redux";
import { update } from "../redux/userSlice";

export default function Update () {
 const [name, setName] = useState(" ");
 const [email, setEmail] = useState(" ");
 const user = useSelector ( (state) => (state.user) )
 const dispatch = useDispatch();

 //Here we de-structure the user object and assign respective values. 
 user {
  username: name,
  email: email
 }

 const handleUpdate = (e) => {
  e.preventDefault();
  dispatch(update(user))
 };

<>
 <form>
  <input 
   placeholder = "username"
   onChange = {(e) => setName(e.target.value)} 
   />
  <input 
   placeholder = "email"
   onChange = {(e) => setEmail(e.target.value)} 
  />
  <button onClick = {handleUpdate}>
   Update 
  <button/>
 <form>
</>
};

As the name suggests the dispatch simply sends the action of our slice's reducer to the store. Hence performing the necessary updates and changes.

And that's a wrap, as we have seen, Redux toolkit makes it easier for us to manage state in react.

Although it might seem complex now, with some practice you should get familiar with it and use it effectively in your application.

Let me know in the comment section if you have questions or suggestions.

If you found this insightful, do well to share with your friends across your social media platforms.

Happy coding 💫

How to make your First Open-Source Contribution

Tonie — Fri, 16 Sep 2022 12:55:45 +0000

Contributing to open source is an effective way to learn, teach and gain or build real world experience in just about any skill you can think of.

Open Source refers to any software whose 'source code' is open and accessible to the public. It is a software that anyone can inspect modify or enhance.

The source code is any code created in a programming language that defines the structure and functionality of a software application.

And here's the catch, you don't have to know how to code to contribute to open source, there's a ton of opportunities in the space.

This includes writing documentations, teaching people on how to use the product, designing etc. The opportunities are vast.

And with this opportunities comes numerous benefits. I've listed some of them below:

It helps you improve the software applications you use.
Actively contributing to open source helps develop your technical skills.
By contributing to open source, you can also enhance your soft skills like communication and collaboration with people.
Contributing to open source gives you an experience that is akin to the real world experience of a software developer as the skills and process you will be using will be particularly important in the professional world.

How to find Open Source Projects:

Here's a list of online resources that can help you find open source projects:

These are only a few, you can do a manual search on Google and you'll be provided with several options.

However there are somethings you should look out for in a project before proceeding to make your contribution. The project should meet the following criteria:

The project must have a License.
The project should have a clearly defined and documented ReadMe file
The project is ACTIVELY accepting contributions
The project is welcoming and engaging.

How to Contribute to Open Source?

Now that you've found a project, how do you make your contribution? To contribute to open source, you will have to know how to use Git and GitHub as they are the most popular and effective tools to use.

Here's how to make your first open source contribution using Git and GitHub:

Find a project : The first step is to of course find a project to contribute to, there's a lot of them out there and many ways of finding them as we've discussed earlier.
Fork the repository : Once you've found a project on github, click on the fork button. This will sort of copy or reproduce the project under a new repository in your GitHub user.
Clone the repository : To do this, copy the link of your newly formed repository, it'll look like this; https://github.com/<YourUsername>/git-demo.git Now open your terminal on your device and run the following command.
Create a new remote for the upstream repository : This will help keep your code in sync with the original project. To do this, run the following command
Create a new branch : Now we need to create and move into a new branch, run the following command
Make a Change to the code : Now it's time to add, remove and modify the code. After you are done, you can proceed to add these changes to the staging area by running the following command:
Commit your code changes : After adding your changes to the staging area, it's time to commit them. Run the following command:
Push to your repository : Now it's time to move these changes to your repository, run the following command:
Create a pull request : Once you push to your repository, you can go to that repository on GitHub and click on the "Compare and Pull request" button.

This will notify the project owners of your changes and contributions. After inspecting them, they can merge your pull request.

And Voila, you've made your first open-source contribution

That's a wrap, if you found this insightful, do well to share it with your friends and colleagues.

If you're contributing to a project, let me know in the comment section. I'll be buzzing to hear from you.