Forem: Juliet Ofoegbu

Structuring Relational Data Properly

Juliet Ofoegbu — Thu, 12 Feb 2026 08:33:44 +0000

Most application problems don’t start in the frontend or API layer.

They start in the database.

When relational data isn’t structured properly, you get

Duplicate records
Inconsistent reporting
Complex queries
Systems that are hard to maintain

Good structure means:

Proper primary and foreign keys
Clear tables with single responsibilities
Relationships that reflect real business logic
A design that can scale over time

Your database is the foundation of your system. If it’s weak, everything built on top becomes fragile.

I wrote a deeper breakdown on how to structure relational data effectively using a Pixar-inspired example as a fun analogy here 👉: https://thebcms.com/blog/structuring-relational-data

Implementing Role-Based Access Control in a Real-Time Collaborative App with Permit, Liveblocks, and Clerk

Juliet Ofoegbu — Mon, 30 Jun 2025 13:10:05 +0000

Building a real-time collaborative document editor can be both fun and challenging. It's like Google Docs where multiple users can work on the same document in real-time.

In this tutorial, I’ll walk you through how I built a live collaborative docs app using Next.js 15, Clerk for authentication, Permit.io for role-based access control (RBAC), and Liveblocks for real-time syncing. I also used Tailwind CSS v4 and Shadcn UI to design a clean UI.

Why focus on RBAC?

In a multi-user SaaS app where users can collaborate in real time, permissions matter. Permission on who can edit, who can only view, and who’s allowed to delete a document entirely. Not everyone should be able to edit or delete every document.

That’s where Permit.io comes in to make managing these permissions simple and scalable.

We’ll use:

1. Next.js 15

Next.js is a powerful React framework for building full-stack web applications. It offers features like server-side rendering (SSR), API routes, static site generation (SSG), and routing out of the box.
Features:

Handles both frontend and backend logic in one unified project.
It is ideal for building dynamic, fast, SEO-friendly apps.
It enables server functions like user.actions.ts with the 'use server' directive.

2. Clerk

Clerk is an authentication and user management solution for modern web apps. It provides prebuilt UI components and APIs for sign-up, sign-in, and user profile management. It easily integrates with Next.js for secure user handling and offers session management and roles with minimal config..

3. Permit.io

Permit.io is an authorization-as-a-service platform that helps you manage user access control and permissions in your application.
In this our application, we'll have fine-grained control over who can read/write to rooms or documents. It is also useful for managing user roles dynamically via policies.

4. Liveblocks

Liveblocks enables real-time collaboration features like presence, live cursors, and document editing. It will perform a lot of functions in this app, such as providing a collaborative room-based functionality and letting us add multiplayer experience similar to Google Docs with minimal setup.

5. Tailwind CSS + Shadcn/ui

Tailwind CSS is a utility-first CSS framework that allows you to rapidly build modern, responsive user interfaces using utility classes. shadcn/ui is a customizable collection of accessible UI components built with Tailwind CSS and Radix UI.

This is what we intend to build.

Understanding RBAC and Its Importance

What is RBAC?
Role-Based Access Control (RBAC) is a method of managing permissions based on a user’s role within an application. For a collaborative document app, this makes perfect sense. Instead of setting permissions for each user individually, you assign roles like "creator", "editor", or "viewer", and then define what each role can or cannot do.

RBAC vs ABAC

RBAC: Permission is tied to the user’s role (e.g., editor, viewer).
ABAC: Uses attributes (e.g., department, time of access) to grant permission. More flexible, but also more complex.

Typical Roles in a Collaborative Docs App:

Creator: Full control (edit, share, delete)
Editor: Can edit and comment
Viewer: Read-only access

RBAC helps prevent unauthorized access and ensures users see only what they’re meant to see. This provides a smooth and secure real-time experience, improves usability, and simplifies policy management, especially in collaborative, real-time environments like the real-time collaborative app we want to build.

Setting Up the Next.js Application

We’re using the App Router in Next.js 15, and here’s how we bootstrapped the project.

Start by initializing a new Next.js 15 app:

npx create-next-app@latest collaborative-docs-app

Navigate to your project:

cd collaborative-docs-app

Install Shadcn and some components from it:

npm shadcn-ui@latest init
npm shadcn@latest add button dialog input label popover select

This will automatically create a ui folder inside a newly created components folder in the src directory with the 6 installed ShadCN components in your project.

Install core dependencies:

npm install permit.io @clerk@5.2.4 @clerk/themes@2.1.12

Install other dependencies:

npm install nanoid@5.0.7 lexical @lexical/react

The nanoid is a library used to generate unique string IDs.

Install and initialize Tailwind:

npm install tailwindcss@3.4.1 --save -D postcss@8 tailwind-merge tailwindcss-animate

Create a postcss.config.mjs file in the root of your project and add the following lines of code to the PostCSS configuration.

/** @type {import('postcss-load-config').Config} */
const config = {
  plugins: {
    tailwindcss: {},
  },
};

export default config;

Finally, let's install JSM editor, which is a lexical editor component. Run npm i jsm-editor@0.0.12 and then: npx jsm-editor add editor. The purpose of the npx command is to initialize the editor to generate the editor folder.

After you have successfully ran the npx command you should get the output below in your terminal.

NB: A lot of the packages used in this application are deprecated, so when installing it, install the exact package version and use the -legacy-peer-deps flag in the npm install command.

Project folder structure

Asides the auto generated files, create the rest of the folders and files contained in the folder structure below:

live-docs/
┣ app/
┃ ┣ (auth)/
┃ ┃ ┣ sign-in/
┃ ┃ ┃ ┗ [[...sign-in]]/
┃ ┃ ┃   ┗ page.tsx
┃ ┃ ┗ sign-up/
┃ ┃   ┗ [[...sign-up]]/
┃ ┃ ┃   ┗ page.tsx
┃ ┣ (root)/
┃ ┃ ┣ documents/
┃ ┃ ┃ ┗ [id]/
┃ ┃ ┃   ┗ page.tsx
┃ ┃ ┗ page.tsx
┃ ┣ api/
┃ ┃ ┣ liveblocks-auth/
┃ ┃ ┃ ┗ route.ts
┃ ┃ ┗ permit/
┃ ┃   ┣ role-assign/
┃ ┃ ┃ ┃ ┗ route.ts
┃ ┃   ┣ role-unassign/
┃ ┃ ┃ ┃ ┗ route.ts
┃ ┃   ┗ sync/
┃ ┃ ┃   ┗ route.ts
┃ ┣ Provider.tsx
┃ ┣ favicon.ico
┃ ┣ global-error.tsx
┃ ┣ globals.css
┃ ┗ layout.tsx
┣ components/
┃ ┣ editor/
┃ ┃ ┣ plugins/
┃ ┃ ┃ ┣ FloatingToolbarPlugin.tsx
┃ ┃ ┃ ┣ Theme.ts
┃ ┃ ┃ ┗ ToolbarPlugin.tsx
┃ ┃ ┗ Editor.tsx
┃ ┣ ui/
┃ ┃ ┣ button.tsx
┃ ┃ ┣ dialog.tsx
┃ ┃ ┣ input.tsx
┃ ┃ ┣ label.tsx
┃ ┃ ┣ popover.tsx
┃ ┃ ┗ select.tsx
┃ ┣ ActiveCollaborators.tsx
┃ ┣ AddDocumentBtn.tsx
┃ ┣ CollaborativeRoom.tsx
┃ ┣ Collaborator.tsx
┃ ┣ Comments.tsx
┃ ┣ DeleteModal.tsx
┃ ┣ Header.tsx
┃ ┣ Loader.tsx
┃ ┣ Notifications.tsx
┃ ┣ ShareModal.tsx
┃ ┗ UserTypeSelector.tsx
┣ lib/
┃ ┣ actions/
┃ ┃ ┣ permissions.ts
┃ ┃ ┣ room.actions.ts
┃ ┃ ┗ user.actions.ts
┃ ┣ liveblocks.ts
┃ ┣ permit.ts
┃ ┗ utils.ts
┣ public/
┣ styles/
┣ types/
┃ ┗ index.d.ts
┣ .eslintrc.json
┣ .gitignore
┣ README.md
┣ components.json
┣ instrumentation.ts
┣ liveblocks.config.ts
┣ middleware.ts
┣ next.config.mjs
┣ package-lock.json
┣ package.json
┣ postcss.config.mjs
┣ tailwind.config.ts
┗ tsconfig.json

Refer to the GitHub section of the following components:

The code in the mentioned files must be copied and pasted exactly as they are.

Create a file in the root directory of your project and name it .env.local. This file will contain your API keys from Clerk, Liveblocks and Permit.

Paste these in the file:

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=
CLERK_SECRET_KEY=
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up

LIVEBLOCKS_SECRET_KEY=
PERMIT_API_KEY=

Later on, you'll replace the placeholder keys with the API keys from Permit, Clerk, and Liveblocks.

The home page of the collaborative docs application.

Let's take a look at the app/(root)/page.tsx file which is the home page.

I'll explain what it does but first, paste these lines of code in the file:

import AddDocumentBtn from '@/components/AddDocumentBtn';
import { DeleteModal } from '@/components/DeleteModal';
import Header from '@/components/Header'
import Notifications from '@/components/Notifications';
import { Button } from '@/components/ui/button'
import { getDocuments } from '@/lib/actions/room.actions';
import { dateConverter } from '@/lib/utils';
import { SignedIn, UserButton } from '@clerk/nextjs'
import { currentUser } from '@clerk/nextjs/server';
import Image from 'next/image';
import Link from 'next/link';
import { redirect } from 'next/navigation';

const Home = async () => {
  const clerkUser = await currentUser();
  if(!clerkUser) redirect('/sign-in');

  const roomDocuments = await getDocuments(clerkUser.emailAddresses[0].emailAddress);

  return (
    <main className="home-container">
      <Header className="sticky left-0 top-0">
        <div className="flex items-center gap-2 lg:gap-4">
          <Notifications />
          <SignedIn>
            <UserButton />
          </SignedIn>
        </div>
      </Header>

      {roomDocuments.data.length > 0 ? (
        <div className="document-list-container">
          <div className="document-list-title">
            <h3 className="text-28-semibold">All documents</h3>
            <AddDocumentBtn 
              userId={clerkUser.id}
              email={clerkUser.emailAddresses[0].emailAddress}
            />
          </div>
          <ul className="document-ul">
            {roomDocuments.data.map(({ id, metadata, createdAt }: any) => (
              <li key={id} className="document-list-item">
                <Link href={`/documents/${id}`} className="flex flex-1 items-center gap-4">
                  <div className="hidden rounded-md bg-dark-500 p-2 sm:block">
                    <Image 
                      src="/assets/icons/doc.svg"
                      alt="file"
                      width={40}
                      height={40}
                    />
                  </div>
                  <div className="space-y-1">
                    <p className="line-clamp-1 text-lg">{metadata.title}</p>
                    <p className="text-sm font-light text-blue-100">Created about {dateConverter(createdAt)}</p>
                  </div>
                </Link>
                <DeleteModal roomId={id} />
              </li>
            ))}
          </ul>
        </div>
      ): (
        <div className="document-list-empty">
          <Image 
            src="/assets/icons/doc.svg"
            alt="Document"
            width={40}
            height={40}
            className="mx-auto"
          />

          <AddDocumentBtn 
            userId={clerkUser.id}
            email={clerkUser.emailAddresses[0].emailAddress}
          />
        </div>
      )}
    </main>
  )
}

export default Home

As stated previously, this is the home page of the application. After users sign in, they're taken to this page to either create a new document, collaborate on a document they've been added to, see notifications, see their account details, or sign out.

It ensures that a user is signed in via Clerk (currentUser), fetching the user’s documents (getDocuments), rendering a list of documents or a message if there are none, and providing buttons for adding and deleting documents.

A lib folder will also be created inside the src directory. This lib folder will contain a utils.ts file to store reusable helper functions or small logic chunks that are used across multiple parts of your app.

In the /lib/utils.ts file, paste these lines of code:

import { type ClassValue, clsx } from 'clsx';
import { twMerge } from 'tailwind-merge';

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

export const parseStringify = (value: any) => JSON.parse(JSON.stringify(value));

export const getAccessType = (userType: UserType) => {
  switch (userType) {
    case 'creator':
      return ['room:write'];
    case 'editor':
      return ['room:write'];
    case 'viewer':
      return ['room:read', 'room:presence:write'];
    default:
      return ['room:read', 'room:presence:write'];
  }
};

export const dateConverter = (timestamp: string): string => {
  const timestampNum = Math.round(new Date(timestamp).getTime() / 1000);
  const date: Date = new Date(timestampNum * 1000);
  const now: Date = new Date();

  const diff: number = now.getTime() - date.getTime();
  const diffInSeconds: number = diff / 1000;
  const diffInMinutes: number = diffInSeconds / 60;
  const diffInHours: number = diffInMinutes / 60;
  const diffInDays: number = diffInHours / 24;

  switch (true) {
    case diffInDays > 7:
      return `${Math.floor(diffInDays / 7)} weeks ago`;
    case diffInDays >= 1 && diffInDays <= 7:
      return `${Math.floor(diffInDays)} days ago`;
    case diffInHours >= 1:
      return `${Math.floor(diffInHours)} hours ago`;
    case diffInMinutes >= 1:
      return `${Math.floor(diffInMinutes)} minutes ago`;
    default:
      return 'Just now';
  }
};

// Function to generate a random color in hex format, excluding specified colors
export function getRandomColor() {
  const avoidColors = ['#000000', '#FFFFFF', '#8B4513']; // Black, White, Brown in hex format

  let randomColor;
  do {
    // Generate random RGB values
    const r = Math.floor(Math.random() * 256); // Random number between 0-255
    const g = Math.floor(Math.random() * 256);
    const b = Math.floor(Math.random() * 256);

    // Convert RGB to hex format
    randomColor = `#${r.toString(16)}${g.toString(16)}${b.toString(16)}`;
  } while (avoidColors.includes(randomColor));

  return randomColor;
}

export const brightColors = [
  '#2E8B57', // Darker Neon Green
  ....
];

export function getUserColor(userId: string) {
  let sum = 0;
  for (let i = 0; i < userId.length; i++) {
    sum += userId.charCodeAt(i);
  }

  const colorIndex = sum % brightColors.length;
  return brightColors[colorIndex];
}

This file functions as a general-purpose utility helper. In this case, it includes some helper functions, like parseStringify(...) used to deep clone and sanitize objects, especially useful when dealing with data serialization issues, like when returning data from APIs or actions.

Other helpers include getAccessType(...), which will determine permission levels based on user roles like "creator," "editor," or "viewer." The dateConverter(...) function will translate a given timestamp into a readable relative time like "2 days ago."

To support visual identity features, the file includes a getRandomColor() generator and a predefined array of brightColors, plus getUserColor(...), which consistently assigns a color from the list to a user based on their ID. These utilities are designed to keep code clean and reusable across components and server logic.

Next up is the types/index.d.ts file which is basically a typeScript type declarations for key entities. We defines interfaces for Document, User, Collaborator, etc.

/* eslint-disable no-unused-vars */
declare type SearchParamProps = {
  params: { [key: string]: string };
  searchParams: { [key: string]: string | string[] | undefined };
};

declare type AccessType = ["room:write"] | ["room:read", "room:presence:write"];

declare type RoomAccesses = Record<string, AccessType>;

declare type UserType = "creator" | "editor" | "viewer";

declare type RoomMetadata = {
  creatorId: string;
  email: string;
  title: string;
};

declare type CreateDocumentParams = {
  userId: string;
  email: string;
};

declare type User = {
  id: string;
  name: string;
  email: string;
  avatar: string;
  color: string;
  userType?: UserType;
};

declare type ShareDocumentParams = {
  roomId: string;
  email: string;
  userType: UserType;
  updatedBy: User;
};

declare type UserTypeSelectorParams = {
  userType: string;
  setUserType: React.Dispatch<React.SetStateAction<UserType>>;
  onClickHandler?: (value: string) => void;
};

declare type ShareDocumentDialogProps = {
  roomId: string;
  collaborators: User[];
  creatorId: string;
  currentUserType: UserType;
};

declare type HeaderProps = {
  children: React.ReactNode;
  className?: string;
};

declare type CollaboratorProps = {
  roomId: string;
  email: string;
  creatorId: string;
  collaborator: User;
  user: User;
};

declare type CollaborativeRoomProps = {
  roomId: string;
  roomMetadata: RoomMetadata;
  users: User[];
  currentUserType: UserType;
};

declare type AddDocumentBtnProps = {
  userId: string;
  email: string;
};

declare type DeleteModalProps = { roomId: string };

declare type ThreadWrapperProps = { thread: ThreadData<BaseMetadata> };

These interfaces defined ensures type safety across components and actions.

Implementing Authentication & User Management

We used Clerk for seamless authentication. It handles:

User sign-up & sign-in
Session management
Profile display
Protecting routes

Setting up Authentication

Create a project

Go to Clerk and create a new project. Set up your Clerk API keys in the dashboard and add the project keys in your .env.local file located in the main directory of your project.

Update middleware.ts file. Paste these lines of code:

import { clerkMiddleware } from "@clerk/nextjs/server";

export default clerkMiddleware();

export const config = {
  matcher: ["/((?!.*\\..*|_next).*)", "/", "/(api|trpc)(.*)"],
};

This clerkMiddleware helper enables authentication and is where you'll configure your protected routes.

Sign-up and Sign-in pages using Clerk

In the app/(auth)/sign-up/[[...sign-up]]/page.tsx file, paste these lines of code:

import { SignUp } from '@clerk/nextjs'

const SignUpPage = () => {
  return (
    <main className="auth-page">
      <SignUp />
    </main>
  )
}

export default SignUpPage

Similar to the sign up page, in the app/(auth)/sign-in/[[...sign-in]]/page.tsx file, paste these lines of code:

import { SignIn } from '@clerk/nextjs'

const SignInPage = () => {
  return (
    <main className="auth-page">
      <SignIn />
    </main>
  )
}

export default SignInPage

After a user signs in to the application, they'll be navigated to the home page.

Provider file

In the app/Provider.tsx file in the app directory, paste these lines of code:

'use client';

import Loader from '@/components/Loader';
import { getClerkUsers, getDocumentUsers } from '@/lib/actions/user.actions';
import { useUser } from '@clerk/nextjs';
import { ClientSideSuspense, LiveblocksProvider } from '@liveblocks/react/suspense';
import { ReactNode } from 'react';

const Provider = ({ children }: { children: ReactNode}) => {
  const { user: clerkUser } = useUser();

  return (
    <LiveblocksProvider 
      authEndpoint="/api/liveblocks-auth"
      resolveUsers={async ({ userIds }) => {
        const users = await getClerkUsers({ userIds});

        return users;
      }}
      resolveMentionSuggestions={async ({ text, roomId }) => {
        const roomUsers = await getDocumentUsers({
          roomId,
          currentUser: clerkUser?.emailAddresses[0].emailAddress!,
          text,
        })

        return roomUsers;
      }}
    >
      <ClientSideSuspense fallback={<Loader />}>
        {children}
      </ClientSideSuspense>
    </LiveblocksProvider>
  )
}

export default Provider

Now, wrap the app with Clerk’s provider in app/layout.tsx:

import { Inter as FontSans } from "next/font/google"
import { Toaster } from "@/components/ui/sonner"
import { cn } from "@/lib/utils"
import './globals.css'
import { Metadata } from "next"
import { ClerkProvider } from "@clerk/nextjs"
import { dark } from "@clerk/themes"
import Provider from "./Provider"

const fontSans = FontSans({
  subsets: ["latin"],
  variable: "--font-sans",
})

export const metadata: Metadata = {
  title: 'LiveDocs',
  description: 'Your go-to collaborative editor',
}

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <ClerkProvider
      appearance={{
        baseTheme: dark,
        variables: { 
          colorPrimary: "#3371FF" ,
          fontSize: '16px'
        },
      }}
    >
      <html lang="en" suppressHydrationWarning>
        <body
          className={cn(
            "min-h-screen font-sans antialiased",
            fontSans.variable
          )}
        >
          <Provider>
            {children}
          </Provider>
          <Toaster />
        </body>
      </html>
    </ClerkProvider>
  )
}

This ClerkProvider component provides Clerk's authentication context to your app.

Handle user-related operations

The lib/actions/user.actions.ts file will handle actions related to user data using Clerk and Liveblocks. The getClerkUsers(...) function takes an array of email addresses, fetches corresponding user details from Clerk (like name, avatar, and email), and returns a sorted list matching the input order.

It uses parseStringify(...) to ensure the response is clean and serializable for use in UI components or further processing.

Paste these lines of code in it:

'use server';

import { clerkClient } from "@clerk/nextjs/server";
import { parseStringify } from "../utils";
import { liveblocks } from "../liveblocks";

export const getClerkUsers = async ({ userIds }: { userIds: string[]}) => {
  try {
    const { data } = await clerkClient.users.getUserList({
      emailAddress: userIds,
    });

    const users = data.map((user) => ({
      id: user.id,
      name: `${user.firstName} ${user.lastName}`,
      email: user.emailAddresses[0].emailAddress,
      avatar: user.imageUrl,
    }));

    const sortedUsers = userIds.map((email) => users.find((user) => user.email === email));

    return parseStringify(sortedUsers);
  } catch (error) {
    console.log(`Error fetching users: ${error}`);
  }
}

export const getDocumentUsers = async ({ roomId, currentUser, text }: { roomId: string, currentUser: string, text: string }) => {
  try {
    const room = await liveblocks.getRoom(roomId);

    const users = Object.keys(room.usersAccesses).filter((email) => email !== currentUser);

    if(text.length) {
      const lowerCaseText = text.toLowerCase();

      const filteredUsers = users.filter((email: string) => email.toLowerCase().includes(lowerCaseText))

      return parseStringify(filteredUsers);
    }

    return parseStringify(users);
  } catch (error) {
    console.log(`Error fetching document users: ${error}`);
  }
}

The second function, getDocumentUsers(...), queries Liveblocks to get users with access to a collaborative document (called a room). It filters out the current user and supports an optional search text input to narrow down the results (e.g., when inviting or tagging users).

Integrating Permit for Role-Based Access Control

Permit handles all our authorization logic — roles, permissions, and policies.

Step 1: Set Up Permit

Go to Permit.io
Create a project and API key (which will be added to your .env.local file)
Define resources (like document) and roles (creator, editor, viewer)

Step 2: Create Roles and Permissions

Create roles and permissions like this:

Creator: Can read, write, and delete
Editor: Can read and write but can't delete
Viewer: Can only read but can't write or delete

Step 3: Code Integration

First, add Permit client config in lib/permit.ts:

import { Permit } from 'permitio';

const PERMIT_API_KEY = process.env.PERMIT_API_KEY as string;
// This line initializes the SDK and connects your Node.js app
// to the Permit.io PDP container you've set up in the previous step.
const permit = new Permit({
  // your API Key
  token: PERMIT_API_KEY, // Store your API key in .env
  // in production, you might need to change this url to fit your deployment
  pdp: 'https://cloudpdp.api.permit.io', // Default Permit.io PDP URL
  // if you want the SDK to emit logs, uncomment this:
  log: {
    level: "debug",
  },
  // The SDK returns false if you get a timeout / network error
  // if you want it to throw an error instead, and let you handle this, uncomment this:
  throwOnError: true,
});

export default permit;

Define routes to assign and unassign roles

In the api/permit/role-assign/route.ts file, paste the following lines of code:

import { NextResponse } from 'next/server';
import permit from "../../../../lib/permit"

const allowedRoles: string[] = ['editor', 'viewer'];

export async function POST(request: Request) {
  const { userId, role } = await request.json();

  if (!userId || !role) {
    return NextResponse.json(
      { error: 'userId and role are required.' },
      { status: 400 }
    );
  }

  if (!allowedRoles.includes(role)) {
    return NextResponse.json(
      { error: 'Invalid role. Allowed roles: editor, viewer' },
      { status: 400 }
    );
  }

  try {
    // Assign role using SDK
    await permit.api.roleAssignments.assign({
      user: userId,
      role,
      tenant: "default",
    });

    return NextResponse.json({
      message: "Role assigned successfully",
      data: { userId, role }
    }, { status: 200 });
  } catch (error) {
    console.error("Failed to assign role in Permit.io:", error);

    // Handle role not assigned case
    if (typeof error === "object" && error !== null && "status" in error && (error as any).status === 404) {
      return NextResponse.json(
        { 
          success: false, 
          message: "Role not assigned to user",
          error: (error as any).message 
        },
        { status: 404 }
      );
    }

    return NextResponse.json(
      { 
        success: false, 
        message: "Failed to assign role in Permit.io",
        error: typeof error === "object" && error !== null && "message" in error ? (error as any).message : String(error)
      },
      { status: typeof error === "object" && error !== null && "status" in error ? (error as any).status : 500 }
    );
  }
}

This assigns a role to users who are added by the creator to the document, either as editors or as viewers.

Next, in the api/permit/role-unassign/route.ts file, paste the following lines of code:

import { NextResponse } from 'next/server';
import permit from "../../../../lib/permit"

export async function DELETE(request: Request) {
  const { userId, role } = await request.json();

  if (!userId || !role) {
    return NextResponse.json(
      { error: 'userId and role are required.' },
      { status: 400 }
    );
  }

  try {
    // Unassign role using SDK
    await permit.api.roleAssignments.unassign({
      user: userId,
      role,
      tenant: "default",
    });

    return NextResponse.json({
      message: "Role unassigned successfully",
      data: { userId, role }
    }, { status: 200 });
  } catch (error) {
    console.error("Failed to unassign role in Permit.io:", error);

    // Handle role not assigned case
    if (typeof error === "object" && error !== null && "status" in error && (error as any).status === 404) {
      return NextResponse.json(
        { 
          success: false, 
          message: "Role not assigned to user",
          error: (error as any).message 
        },
        { status: 404 }
      );
    }

    return NextResponse.json(
      { 
        success: false, 
        message: "Failed to unassign role in Permit.io",
        error: typeof error === "object" && error !== null && "message" in error ? (error as any).message : String(error)
      },
      { status: typeof error === "object" && error !== null && "status" in error ? (error as any).status : 500 }
    );
  }
}

This unassigns a role that has been assigned to a user.

Sync user info with Permit via api/permit/sync/route.ts like this:

import { NextResponse } from 'next/server';
import permit from "../../../../lib/permit"

const allowedRoles: string[] = ['editor', 'viewer'];

export async function POST(request: Request) {
  const { firstName, lastName, email, role, userId } = await request.json();

  if (!email || !role || !userId) {
    return NextResponse.json(
      { error: 'Email, role, and userId are required.' },
      { status: 400 }
    );
  }

  if (!allowedRoles.includes(role)) {
    return NextResponse.json(
      { error: 'Invalid role. Allowed roles: editor, viewer' },
      { status: 400 }
    );
  }

  try {
    // First check if user exists using SDK
     // Create new user and assign role in one operation
      await permit.api.users.sync({
        key: email,
        email,
        first_name: firstName,
        last_name: lastName,
        role_assignments: [{ role, tenant: "default" }]
      });

      return NextResponse.json({
        message: "User created and role assigned successfully",
        data: { email, role }
      }, { status: 201 });

  } catch (error) {
    console.error("Failed to sync user to Permit.io:", error);

    return NextResponse.json(
      { 
        success: false, 
        message: "Failed to sync with Permit.io",
        error: typeof error === "object" && error !== null && "message" in error ? (error as any).message : String(error)
      },
      { status: typeof error === "object" && error !== null && "status" in error ? (error as any).status : 500 }
    );
  }
}

Integrating Liveblocks for Real-Time Collaboration

We used Liveblocks to power document syncing and collaboration. Each document becomes a Liveblocks room.

The key features include:

Real-time syncing of text edits
Collaborative cursors and presence
Tagging document collaborators

Set up Liveblocks account

Sign up to Liveblocks
Create a project

A page will open up which will prompt you to choose the application you want to build, in this case, it's the Text editor. Choose Liveblocks lexical and then Next.js.

Installation steps:

First, initialize Liveblocks and Lexical with the following commands:

npm install @liveblocks/client@2.3.0 @liveblocks/react@2.3.0 @liveblocks/react-ui@2.3.0 @liveblocks/react-lexical@2.3.0 lexical@0.16.1 @lexical/react@0.16.1

npx create-liveblocks-app@latest --init --framework react

The second command is used to initialize a Liveblocks config file. Now, paste these lines of code into the generated liveblocks.config.ts file:

// Define Liveblocks types for your application
// https://liveblocks.io/docs/api-reference/liveblocks-react#Typing-your-data
declare global {
  interface Liveblocks {
    // Each user's Presence, for useMyPresence, useOthers, etc.
    Presence: {
      // Example, real-time cursor coordinates
      // cursor: { x: number; y: number };
    };

    // The Storage tree for the room, for useMutation, useStorage, etc.
    Storage: {
      // Example, a conflict-free list
      // animals: LiveList<string>;
    };

    // Custom user info set when authenticating with a secret key
    UserMeta: {
      id: string;
      info: {
        id: string;
        name: string;
        email: string;
        avatar: string;
        color: string;
      };
    };

    // Custom events, for useBroadcastEvent, useEventListener
    RoomEvent: {};
      // Example has two events, using a union
      // | { type: "PLAY" } 
      // | { type: "REACTION"; emoji: "🔥" };

    // Custom metadata set on threads, for useThreads, useCreateThread, etc.
    ThreadMetadata: {
      // Example, attaching coordinates to a thread
      // x: number;
      // y: number;
    };

    // Custom room info set with resolveRoomsInfo, for useRoomInfo
    RoomInfo: {
      // Example, rooms with a title and url
      // title: string;
      // url: string;
    };
  }
}

export {};

Then install Liveblocks node using the npm install @liveblocks/node@2.3.0 command. Copy the liveblocks auth api in the code. This package will be helpful in setting up an authentication for liveblocks.

Core integration steps:

First, we'll set up Liveblocks config in lib/liveblocks.ts file:

import { Liveblocks } from "@liveblocks/node";

export const liveblocks = new Liveblocks({
  secret: process.env.LIVEBLOCKS_SECRET_KEY as string,
});

Next up is the API route for Liveblocks auth in the app/api/liveblocks-auth/route.ts file:

import { liveblocks } from "@/lib/liveblocks";
import { getUserColor } from "@/lib/utils";
import { currentUser } from "@clerk/nextjs/server";
import { redirect } from "next/navigation";

export async function POST(request: Request) {
  const clerkUser = await currentUser();

  if(!clerkUser) redirect('/sign-in');

  const { id, firstName, lastName, emailAddresses, imageUrl } = clerkUser;

  // Get the current user from your database
  const user = {
    id,
    info: {
      id,
      name: `${firstName} ${lastName}`,
      email: emailAddresses[0].emailAddress,
      avatar: imageUrl,
      color: getUserColor(id),
    }
  }

  // Identify the user and return the result
  const { status, body } = await liveblocks.identifyUser(
    {
      userId: user.info.email,
      groupIds: [],
    },
    { userInfo: user.info },
  );

  return new Response(body, { status });
}

The app/(root)/documents/[id]/page.tsx file will be the document editor page for a specific document ID. Paste the following lines of code:

import CollaborativeRoom from "@/components/CollaborativeRoom"
import { getDocument, verifyUserPermission } from "@/lib/actions/room.actions";
import { getClerkUsers } from "@/lib/actions/user.actions";
import { currentUser } from "@clerk/nextjs/server"
import { redirect } from "next/navigation";

const Document = async ({ params: { id } }: SearchParamProps) => {
  const clerkUser = await currentUser();
  if (!clerkUser) redirect('/sign-in');

  const userEmail = clerkUser.emailAddresses[0]?.emailAddress;

  try {
    const canView = await verifyUserPermission(userEmail, 'read');
    if (!canView) {
      redirect(`/error?reason=no-read-access`);
    }

    const room = await getDocument({
      roomId: id,
      userId: userEmail,
    });

    if (!room) {
      redirect(`/error?reason=room-not-found`);
    }

    const canEdit = await verifyUserPermission(userEmail, 'edit');
    const currentUserType = canEdit ? 'editor' : 'viewer';

    const userIds = Object.keys(room.usersAccesses || {});
    const users = await getClerkUsers({ userIds });

    const usersData = users
      .filter((user: User | null): user is User => !!user && !!user.email)
      .map((user: User) => ({
        ...user,
        userType: room.usersAccesses?.[user.email]?.includes('room:write')
          ? 'editor'
          : 'viewer'
      }));

    return (
      <main className="flex w-full flex-col items-center">
        <CollaborativeRoom 
          roomId={id}
          roomMetadata={room.metadata}
          users={usersData}
          currentUserType={currentUserType}
        />
      </main>
    );
  } catch (error) {
    console.error("Error loading document:", error);
    redirect(`/error?reason=${encodeURIComponent('load-failed')}`);
  }
};

export default Document;

The above file fetches document metadata (title, permissions, collaborators). It uses <CollaborativeRoom /> to manage real-time editing via Liveblocks.

The components/ActiveCollaborators.tsx file contains code that shows who’s currently editing. It uses Liveblocks presence API to display avatars/names.

import { useOthers } from '@liveblocks/react/suspense'
import Image from 'next/image';

const ActiveCollaborators = () => {
  const others = useOthers();

  const collaborators = others.map((other) => other.info);

  return (
    <ul className="collaborators-list">
      {collaborators.map(({ id, avatar, name, color }) => (
        <li key={id}>
          <Image 
            src={avatar}
            alt={name}
            width={100}
            height={100}
            className='inline-block size-8 rounded-full ring-2 ring-dark-100'
            style={{border: `3px solid ${color}`}}
          />
        </li>
      ))}
    </ul>
  )
}

export default ActiveCollaborators

The components/AddDocumentBtn.tsx file contains the button UI "Start a blank document" to create a new document.

'use client';

import { createDocument } from '@/lib/actions/room.actions';
import { Button } from './ui/button'
import Image from 'next/image'
import { useRouter } from 'next/navigation';

const AddDocumentBtn = ({ userId, email }: AddDocumentBtnProps) => {
  const router = useRouter();

  const addDocumentHandler = async () => {
    try {
      const room = await createDocument({ userId, email });

      if(room) router.push(`/documents/${room.id}`);
    } catch (error) {
      console.log(error)
    }
  }

  return (
    <Button type="submit" onClick={addDocumentHandler} className="gradient-blue flex gap-1 shadow-md">
      <Image 
        src="/assets/icons/add.svg" alt="add" width={24} height={24}
      />
      <p className="hidden sm:block">Start a blank document</p>
    </Button>
  )
}

export default AddDocumentBtn

On click, it creates a new document and navigates to the new document’s page.

Wrap the editor environment in the components/CollaborativeRoom.tsx file, like this:

'use client';

import { ClientSideSuspense, RoomProvider } from '@liveblocks/react/suspense'
import { Editor } from '@/components/editor/Editor'
import Header from '@/components/Header'
import { SignedIn, SignedOut, SignInButton, UserButton } from '@clerk/nextjs'
import ActiveCollaborators from './ActiveCollaborators';
import { useEffect, useRef, useState } from 'react';
import { Input } from './ui/input';
import Image from 'next/image';
import { updateDocument } from '@/lib/actions/room.actions';
import Loader from './Loader';
import ShareModal from './ShareModal';

const CollaborativeRoom = ({ roomId, roomMetadata, users, currentUserType }: CollaborativeRoomProps) => {
  const [documentTitle, setDocumentTitle] = useState(roomMetadata.title);
  const [editing, setEditing] = useState(false);
  const [loading, setLoading] = useState(false);

  const containerRef = useRef<HTMLDivElement>(null);
  const inputRef = useRef<HTMLDivElement>(null);

  const updateTitleHandler = async (e: React.KeyboardEvent<HTMLInputElement>) => {
    if(e.key === 'Enter') {
      setLoading(true);

      try {
        if(documentTitle !== roomMetadata.title) {
          const updatedDocument = await updateDocument(roomId, documentTitle);

          if(updatedDocument) {
            setEditing(false);
          }
        }
      } catch (error) {
        console.error(error);
      }

      setLoading(false);
    }
  }

  useEffect(() => {
    const handleClickOutside = (e: MouseEvent) => {
      if(containerRef.current && !containerRef.current.contains(e.target as Node)) {
        setEditing(false);
        updateDocument(roomId, documentTitle);
      }
    }

    document.addEventListener('mousedown', handleClickOutside);

    return () => {
      document.removeEventListener('mousedown', handleClickOutside);
    }
  }, [roomId, documentTitle])

  useEffect(() => {
    if(editing && inputRef.current) {
      inputRef.current.focus();
    }
  }, [editing])


  return (
    <RoomProvider id={roomId}>
      <ClientSideSuspense fallback={<Loader />}>
        <div className="collaborative-room">
          <Header>
            <div ref={containerRef} className="flex w-fit items-center justify-center gap-2">
              {editing && !loading ? (
                <Input 
                  type="text"
                  value={documentTitle}
                  ref={inputRef}
                  placeholder="Enter title"
                  onChange={(e) => setDocumentTitle(e.target.value)}
                  onKeyDown={updateTitleHandler}
                  disable={!editing}
                  className="document-title-input"
                />
              ) : (
                <>
                  <p className="document-title">{documentTitle}</p>
                </>
              )}

              {currentUserType === 'editor' && !editing && (
                <Image 
                  src="/assets/icons/edit.svg"
                  alt="edit"
                  width={24}
                  height={24}
                  onClick={() => setEditing(true)}
                  className="pointer"
                />
              )}

              {currentUserType !== 'editor' && !editing && (
                <p className="view-only-tag">View only</p>
              )}

              {loading && <p className="text-sm text-gray-400">saving...</p>}
            </div>
            <div className="flex w-full flex-1 justify-end gap-2 sm:gap-3">
              <ActiveCollaborators />

              <ShareModal 
                roomId={roomId}
                collaborators={users}
                creatorId={roomMetadata.creatorId}
                currentUserType={currentUserType}
              />

              <SignedOut>
                <SignInButton />
              </SignedOut>
              <SignedIn>
                <UserButton />
              </SignedIn>
            </div>
          </Header>
        <Editor roomId={roomId} currentUserType={currentUserType} />
        </div>
      </ClientSideSuspense>
    </RoomProvider>
  )
}

export default CollaborativeRoom

This file initializes a Liveblocks room with the document ID. It connects editor state to Liveblocks storage and presence and handles the sharing functionality based on user's role.

The components/Collaborator.tsx code represents a single collaborator.

import Image from 'next/image';
import React, { useState } from 'react'
import UserTypeSelector from './UserTypeSelector';
import { Button } from './ui/button';
import { removeCollaborator, updateDocumentAccess } from '@/lib/actions/room.actions';

const Collaborator = ({ roomId, creatorId, collaborator, email, user }: CollaboratorProps) => {
  const [userType, setUserType] = useState(collaborator.userType || 'viewer');
  const [loading, setLoading] = useState(false);

  const shareDocumentHandler = async (type: string) => {
    setLoading(true);

    await updateDocumentAccess({ 
      roomId, 
      email, 
      userType: type as UserType, 
      updatedBy: user 
    });

    setLoading(false);
  }

  const removeCollaboratorHandler = async (email: string) => {
    setLoading(true);

    await removeCollaborator({ roomId, email });

    setLoading(false);
  }

  return (
    <li className="flex items-center justify-between gap-2 py-3">
      <div className="flex gap-2">
        <Image 
          src={collaborator.avatar}
          alt={collaborator.name}
          width={36}
          height={36}
          className="size-9 rounded-full"
        />
        <div>
          <p className="line-clamp-1 text-sm font-semibold leading-4 text-white">
            {collaborator.name}
            <span className="text-10-regular pl-2 text-blue-100">
              {loading && 'updating...'}
            </span>
          </p>
          <p className="text-sm font-light text-blue-100">
            {collaborator.email}
          </p>
        </div>
      </div>

      {creatorId === collaborator.id ? (
        <p className="text-sm text-blue-100">Creator</p>
      ): (
        <div className="flex items-center">
          <UserTypeSelector 
            userType={userType as UserType}
            setUserType={setUserType || 'viewer'}
            onClickHandler={shareDocumentHandler}
          />
          <Button type="button" onClick={() => removeCollaboratorHandler(collaborator.email)}>
            Remove
          </Button>
        </div>
      )}
    </li>
  )
}

export default Collaborator

It renders collaborator avatar, name, email, current selection or user type.

Enforcing RBAC in the Application

Once roles and policies are in place, we can enforce them both:

1. Centralize permission-checking logic
The lib/actions/permissions.ts file is typically where you’ll call Permit to check permissions. Paste these lines of code:

import axios from 'axios';
import permit from "../permit"; // Adjust the import path as necessary

const PERMIT_API_BASE = "https://api.permit.io/v2/facts";
const PERMIT_PROJ_ID = "your_permit_project_id";
const PERMIT_ENV_ID = "your_permit_env_id";
const PERMIT_API_KEY = process.env.PERMIT_API_KEY as string;

const permitApi = axios.create({
  baseURL: PERMIT_API_BASE,
  headers: {
    Authorization: `Bearer ${PERMIT_API_KEY}`,
    "Content-Type": "application/json",
  },
});

// Cache for user existence checks
const userExistenceCache = new Map<string, boolean>();

export const checkUserExistsInPermit = async (email: string): Promise<boolean> => {
  // Check cache first
  if (userExistenceCache.has(email)) {
    return userExistenceCache.get(email)!;
  }

  try {
    const response = await permit.api.users.get(email);
    userExistenceCache.set(email, true);
    return true;
  } catch (error) {
    if (typeof error === "object" && error !== null && "status" in error && (error as any).status === 404) {
      userExistenceCache.set(email, false);
      return false;
    }
    console.error('Permit user check failed:', error);
    // Assume user exists to prevent duplicate creation
    return true;
  }
};

export const syncUserWithPermit = async (email: string, role: 'editor' | 'viewer' | 'creator') => {
  try {
    const userExists = await checkUserExistsInPermit(email);
    if (userExists) return;

    // User doesn't exist, create them
    await permitApi.post(`/${PERMIT_PROJ_ID}/${PERMIT_ENV_ID}/users`, {
      key: email,
      email,
      role_assignments: [{ role, tenant: "default" }],
    });
    userExistenceCache.set(email, true);
  } catch (error) {
    console.error("Permit sync error:", error);
    throw error;
  }
};

export const assignRoleWithPermit = async (email: string, role: 'editor' | 'viewer' | 'creator') => {
  try {
    // First check if user exists as a fallback
    const userExists = await checkUserExistsInPermit(email);
    if (!userExists) {
      console.log(`User ${email} not found, attempting to sync first...`);
      await syncUserWithPermit(email, role);
      await new Promise(resolve => setTimeout(resolve, 3000));
    }
    // Assign the role
    await permitApi.post(`/${PERMIT_PROJ_ID}/${PERMIT_ENV_ID}/users/${email}/roles`, {
      role,
      tenant: "default"
    });
    console.log(`Successfully assigned ${role} role to ${email}`);
  } catch (error) {
    console.error(`Failed to assign ${role} role to ${email}:`, error);
    throw error;
  }
};
export const unassignRoleWithPermit = async (email: string, role: 'editor' | 'viewer') => {
  try {
    await permitApi.delete(`/${PERMIT_PROJ_ID}/${PERMIT_ENV_ID}/users/${email}/roles`, {
      data: {
        role,
        tenant: "default"
      }
    });
  } catch (error) {
    console.error("Permit role unassignment error:", error);
    throw error;
  }
};

// Add this new function for checking permissions
export const checkUserPermission = async (email: string, action: string): Promise<boolean> => {
  try {
    const resource = "Document"; // Fixed resource type as per your requirement
    const permitted = await permit.check(email, action, resource);
    console.log(`Permission check for ${email} to ${action} on ${resource}:`, permitted);
    return permitted;
  } catch (error) {
    console.error(`Error checking permission for ${email}:`, error);
    return true; // Fallback to allow access
  }
};

It is called in both server-side routes and client-side components for RBAC enforcement.

2. Manage document-level operations

We'll include functions to create, fetch, update, delete documents in the lib/actions/room-actions.ts file, like this:

'use server';

import { nanoid } from 'nanoid'
import { liveblocks } from '../liveblocks';
import { revalidatePath } from 'next/cache';
import { getAccessType, parseStringify } from '../utils';
import { redirect } from 'next/navigation';
import { 
  assignRoleWithPermit, 
  checkUserPermission, 
  syncUserWithPermit, 
  unassignRoleWithPermit
} from './permissions';

export const createDocument = async ({ userId, email }: CreateDocumentParams) => {
  const roomId = nanoid();

  try {
    // Sync user with Permit as editor
    await syncUserWithPermit(email, 'editor').catch(() => {
      console.log('Permit sync failed, proceeding with document creation');
    });

    const metadata = {
      creatorId: userId,
      email,
      title: 'Untitled'
    }

    const usersAccesses: RoomAccesses = {
      [email]: ['room:write']
    }

    const room = await liveblocks.createRoom(roomId, {
      metadata,
      usersAccesses,
      defaultAccesses: []
    });

    revalidatePath('/');
    return parseStringify(room);
  } catch (error) {
    console.log(`Error happened while creating a room: ${error}`);
    throw error;
  }
}

// Update the getDocument function to check permissions
export const getDocument = async ({ roomId, userId }: { roomId: string; userId: string }) => {
  try {
    // First check Permit permissions
    const canView = await verifyUserPermission(userId, 'read');
    if (!canView) {
      throw new Error('You do not have permission to view this document');
    }

    const room = await liveblocks.getRoom(roomId);
    return parseStringify(room);
  } catch (error) {
    console.log(`Error happened while getting a room: ${error}`);
    throw error;
  }
};

export const updateDocument = async (roomId: string, title: string) => {
  try {
    const updatedRoom = await liveblocks.updateRoom(roomId, {
      metadata: {
        title
      }
    })

    revalidatePath(`/documents/${roomId}`);

    return parseStringify(updatedRoom);
  } catch (error) {
    console.log(`Error happened while updating a room: ${error}`);
  }
}

export const getDocuments = async (email: string ) => {
  try {
      const rooms = await liveblocks.getRooms({ userId: email });

      return parseStringify(rooms);
  } catch (error) {
    console.log(`Error happened while getting rooms: ${error}`);
  }
}

export const updateDocumentAccess = async ({ roomId, email, userType, updatedBy }: ShareDocumentParams) => {
  try {
    // Verify current user has permission to edit
    const canEdit = await verifyUserPermission(updatedBy.email, 'edit');
    if (!canEdit) {
      throw new Error('You do not have permission to modify access');
    }

    const usersAccesses: RoomAccesses = {
      [email]: getAccessType(userType) as AccessType,
    }

    const room = await liveblocks.updateRoom(roomId, { 
      usersAccesses
    });

    if (room) {
      const notificationId = nanoid();
      await liveblocks.triggerInboxNotification({
        userId: email,
        kind: '$documentAccess',
        subjectId: notificationId,
        activityData: {
          userType,
          title: `You have been granted ${userType} access to the document by ${updatedBy.name}`,
          updatedBy: updatedBy.name,
          avatar: updatedBy.avatar,
          email: updatedBy.email
        },
        roomId
      });
    }

    revalidatePath(`/documents/${roomId}`);
    return parseStringify(room);
  } catch (error) {
    console.error(`Error updating document access:`, error);
    throw error; // Let the UI component handle the error display
  }
}

export const removeCollaborator = async ({ roomId, email }: {roomId: string, email: string}) => {
  try {
    const room = await liveblocks.getRoom(roomId)

    if(room.metadata.email === email) {
      throw new Error('You cannot remove yourself from the document');
    }

    // Unassign all roles in Permit
    await unassignRoleWithPermit(email, 'editor');
    await unassignRoleWithPermit(email, 'viewer');

    const updatedRoom = await liveblocks.updateRoom(roomId, {
      usersAccesses: {
        [email]: null
      }
    })

    revalidatePath(`/documents/${roomId}`);
    return parseStringify(updatedRoom);
  } catch (error) {
    console.log(`Error happened while removing a collaborator: ${error}`);
    throw error;
  }
}

export const deleteDocument = async (roomId: string) => {
  try {
    await liveblocks.deleteRoom(roomId);
    revalidatePath('/');
    redirect('/');
  } catch (error) {
    console.log(`Error happened while deleting a room: ${error}`);
  }
}

// Update the verifyUserPermission function
export const verifyUserPermission = async (email: string, requiredAction: 'edit' | 'read'): Promise<boolean> => {
  try {
    const hasPermission = await checkUserPermission(email, requiredAction);
    if (!hasPermission) {
      console.warn(`User ${email} lacks permission to ${requiredAction} document`);
      return false;
    }
    return true;
  } catch (error) {
    console.error(`Permission verification failed for ${email}:`, error);
    // Remove the redirect here - let the calling function handle it
    return false;
  }
};

It interacts with the database and checks for permissions before performing actions.

3. Manages document comments

The components/Comments.tsx file manages document comments, displays comments linked to ranges or selections, and allows editors/creators to add, edit or delete comments.

import { cn } from '@/lib/utils';
import { useIsThreadActive } from '@liveblocks/react-lexical';
import { Composer, Thread } from '@liveblocks/react-ui';
import { useThreads } from '@liveblocks/react/suspense';
import React from 'react'

const ThreadWrapper = ({ thread }: ThreadWrapperProps) => {
  const isActive = useIsThreadActive(thread.id);

  return (
    <Thread 
      thread={thread}
      data-state={isActive ? 'active' : null}
      className={cn('comment-thread border', 
        isActive && '!border-blue-500 shadow-md',
        thread.resolved && 'opacity-40'
      )}
    />
  )
}

const Comments = () => {
  const { threads } = useThreads();

  return (
    <div className="comments-container">
      <Composer className="comment-composer" />

      {threads.map((thread) => (
        <ThreadWrapper key={thread.id} thread={thread} />
      ))}
    </div>
  )
}

export default Comments

You can tag a collaborator in a comment so they get it as an in-app notification and attend to it promptly. Other things you can do include editing, deleting, resolving a comment, and responding to a comment in thread so as not to break the line of communication. These features are availiable thanks to Liveblocks.

4. Handle document deletion

The components/DeleteModal.tsx file contains the delete dialog. It displays a modal asking creators to confirm deletion.

It calls delete API from the lib/actions/room.actions.ts file.

"use client";

import Image from "next/image";
import { useState } from "react";

import { deleteDocument } from "@/lib/actions/room.actions";

import {
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog";

import { Button } from "./ui/button";

export const DeleteModal = ({ roomId }: DeleteModalProps) => {
  const [open, setOpen] = useState(false);
  const [loading, setLoading] = useState(false);

  const deleteDocumentHandler = async () => {
    setLoading(true);

    try {
      await deleteDocument(roomId);
      setOpen(false);
    } catch (error) {
      console.log("Error notif:", error);
    }

    setLoading(false);
  };

  return (
    <Dialog open={open} onOpenChange={setOpen}>
      <DialogTrigger asChild>
        <Button className="min-w-9 rounded-xl bg-transparent p-2 transition-all">
          <Image
            src="/assets/icons/delete.svg"
            alt="delete"
            width={20}
            height={20}
            className="mt-1"
          />
        </Button>
      </DialogTrigger>
      <DialogContent className="shad-dialog">
        <DialogHeader>
          <Image
            src="/assets/icons/delete-modal.svg"
            alt="delete"
            width={48}
            height={48}
            className="mb-4"
          />
          <DialogTitle>Delete document</DialogTitle>
          <DialogDescription>
            Are you sure you want to delete this document? This action cannot be
            undone.
          </DialogDescription>
        </DialogHeader>

        <DialogFooter className="mt-5">
          <DialogClose asChild className="w-full bg-dark-400 text-white">
            Cancel
          </DialogClose>

          <Button
            variant="destructive"
            onClick={deleteDocumentHandler}
            className="gradient-red w-full"
          >
            {loading ? "Deleting..." : "Delete"}
          </Button>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  );
};

5. In-app notifications

The components/Notifications.tsx file shows in-app notifications, like when a user is granted access permission or a user is mentioned. Paste these following lines of code in the file:

'use client'

import {
  Popover,
  PopoverContent,
  PopoverTrigger,
} from "@/components/ui/popover"
import { InboxNotification, InboxNotificationList, LiveblocksUIConfig } from "@liveblocks/react-ui"
import { useInboxNotifications, useUnreadInboxNotificationsCount } from "@liveblocks/react/suspense"
import Image from "next/image"
import { ReactNode } from "react"

const Notifications = () => {
  const { inboxNotifications } = useInboxNotifications();
  const { count } = useUnreadInboxNotificationsCount();

  const unreadNotifications = inboxNotifications.filter((notification) => !notification.readAt);

  return (
    <Popover>
      <PopoverTrigger className="relative flex size-10 items-center justify-center rounded-lg">
        <Image 
          src="/assets/icons/bell.svg"
          alt="inbox"
          width={24}
          height={24}
        />
        {count > 0 && (
          <div className="absolute right-2 top-2 z-20 size-2 rounded-full bg-blue-500" />
        )}
      </PopoverTrigger>
      <PopoverContent align="end" className="shad-popover">
        <LiveblocksUIConfig 
          overrides={{
            INBOX_NOTIFICATION_TEXT_MENTION: (user: ReactNode) => (
              <>{user} mentioned you.</>
            )
          }}
        >
          <InboxNotificationList>
            {unreadNotifications.length <= 0 && (
              <p className="py-2 text-center text-dark-500">No new notifications</p>
            )}

            {unreadNotifications.length > 0 && unreadNotifications.map((notification) => (
              <InboxNotification 
                key={notification.id}
                inboxNotification={notification}
                className="bg-dark-200 text-white"
                href={`/documents/${notification.roomId}`}
                showActions={false}
                kinds={{
                  thread: (props) => (
                    <InboxNotification.Thread {...props} 
                      showActions={false}
                      showRoomName={false}
                    />
                  ),
                  textMention: (props) => (
                    <InboxNotification.TextMention {...props} 
                      showRoomName={false}
                    />
                  ),
                  $documentAccess: (props) => (
                    <InboxNotification.Custom {...props} title={props.inboxNotification.activities[0].data.title} aside={<InboxNotification.Icon className="bg-transparent">
                      <Image 
                        src={props.inboxNotification.activities[0].data.avatar as string || ''}
                        width={36}
                        height={36}
                        alt="avatar"
                        className="rounded-full"
                      />
                    </InboxNotification.Icon>}>
                      {props.children}
                    </InboxNotification.Custom>
                  )
                }}
              />
            ))}
          </InboxNotificationList>
        </LiveblocksUIConfig>
      </PopoverContent>
    </Popover>
  )
}

export default Notifications

6. Handle document sharing logic

In the components/ShareModal.tsx file, paste these lines of code:

'use client'

import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog"
import { useSelf } from '@liveblocks/react/suspense';
import React, { useState } from 'react'
import { Button } from "./ui/button";
import Image from "next/image";
import { Label } from "./ui/label";
import { Input } from "./ui/input";
import UserTypeSelector from "./UserTypeSelector";
import Collaborator from "./Collaborator";
import { updateDocumentAccess } from "@/lib/actions/room.actions";
import { toast } from "sonner"

const ShareModal = ({ roomId, collaborators, creatorId, currentUserType }: ShareDocumentDialogProps) => {
  const user = useSelf();

  const [open, setOpen] = useState(false);
  const [loading, setLoading] = useState(false);
  const [assigningRole, setAssigningRole] = useState(false);
  const [roleAssigned, setRoleAssigned] = useState(false);
  const [email, setEmail] = useState('');
  const [userType, setUserType] = useState<UserType>('viewer');

  const handleAssignRole = async () => {
    if (!email) {
      toast.error('Please enter an email address first');
      return;
    }

    setAssigningRole(true);
    try {
      const response = await fetch('/api/permit/sync', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          userId: email,
          role: userType,
          email,
        })
      });

      if (!response.ok) {
        throw new Error('Failed to assign role');
      }

      toast.success(`Role assigned successfully`);
      setRoleAssigned(true);
    } catch (error) {
      console.error('Error assigning role:', error);
      toast.error('Failed to assign role');
    } finally {
      setAssigningRole(false);
    }
  };

  const shareDocumentHandler = async () => {
    setLoading(true);
    try {
      const result = await updateDocumentAccess({ 
        roomId, 
        email, 
        userType, 
        updatedBy: user.info,
      });

      toast.success('Access updated successfully');
      setRoleAssigned(false);
    } catch (error) {
      console.error('Error sharing document:', error);
      toast.error(error instanceof Error ? error.message : 'Failed to update access');
    } finally {
      setLoading(false);
    }
  }

  return (
    <Dialog open={open} onOpenChange={setOpen}>
      <DialogTrigger>
        <Button className="gradient-blue flex h-9 gap-1 px-4" disabled={currentUserType !== 'editor'}>
          <Image
            src="/assets/icons/share.svg"
            alt="share"
            width={20}
            height={20}
            className="min-w-4 md:size-5"
          />
          <p className="mr-1 hidden sm:block">Share</p>
        </Button>
      </DialogTrigger>
      <DialogContent className="shad-dialog">
        <DialogHeader>
          <DialogTitle>Manage document access</DialogTitle>
          <DialogDescription>
            Assign roles and share this document with collaborators
          </DialogDescription>
        </DialogHeader>

        <div className="space-y-4">
          <div>
            <Label htmlFor="email" className="text-blue-100">
              Email address
            </Label>
            <Input
              id="email"
              placeholder="Enter email address"
              value={email}
              onChange={(e) => setEmail(e.target.value)}
              className="mt-2 text-black"
            />
          </div>

          <div>
            <Label className="text-blue-100">Access level</Label>
            <UserTypeSelector 
              userType={userType}
              setUserType={setUserType}
            />
          </div>

          <div className="flex gap-3">
            <Button
              onClick={handleAssignRole}
              className="flex-1 bg-dark-400 hover:bg-dark-300"
              disabled={assigningRole || !email}
            >
              {assigningRole ? 'Assigning...' : 'Assign Role'}
            </Button>

            <Button 
              onClick={shareDocumentHandler} 
              className="flex-1 gradient-blue"
              disabled={loading || !roleAssigned}
            >
              {loading ? 'Sending...' : 'Invite'}
            </Button>
          </div>
        </div>

        <div className="mt-6 space-y-2">
          <h3 className="text-sm font-medium text-blue-100">Current collaborators</h3>
          <ul className="flex flex-col">
            {collaborators.map((collaborator) => (
              <Collaborator 
                key={collaborator.id}
                roomId={roomId}
                creatorId={creatorId}
                email={collaborator.email}
                collaborator={collaborator}
                user={user.info}
              />
            ))}
          </ul>
        </div>
      </DialogContent>
    </Dialog>
  )
}

export default ShareModal

It contains the UI for sharing document and assigning roles. It allows creator/editors to invite other users by email or user ID and assign roles (viewer or editor) to invitees via UserTypeSelector.

7. Selecting user's role

Finally, the components/UserTypeSelector.tsx file is a dropdown to choose role type (viewer and editor) which is used inside the ShareModal. It updates state for role assignment.

import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@/components/ui/select"

const UserTypeSelector = ({ userType, setUserType, onClickHandler }: UserTypeSelectorParams) => {
  const accessChangeHandler = (type: UserType) => {
    setUserType(type);
    onClickHandler && onClickHandler(type);
  }

  return (
    <Select value={userType} onValueChange={(type: UserType) => accessChangeHandler(type)}>
      <SelectTrigger className="shad-select">
        <SelectValue />
      </SelectTrigger>
      <SelectContent className="border-none bg-dark-200">
        <SelectItem value="viewer" className="shad-select-item">can view</SelectItem>
        <SelectItem value="editor" className="shad-select-item">can edit</SelectItem>
      </SelectContent>
    </Select>
  )
}

export default UserTypeSelector

For the other components, check out the code in the GitHub repo.

Here's a demo of the collaborative docs application after everything is set.

Conclusion

We’ve covered a lot.

Here’s a recap of what we did. We built a functional, collaborative SaaS app with:

Built a real-time collaborative document app
Used Clerk for secure and seamless authentication
Integrated Liveblocks for live editing & syncing
Implemented RBAC using Permit.io

Check out the GitHub repo for the complete codebase and the live application.

By implementing RBAC, we ensured that users only see and do what they’re allowed to, making our app secure, scalable, and user-friendly.

If you're building a multi-user app, Permit + Clerk + Liveblocks with Next.js is a great combo you should definitely try.

There are various ways authorization can be implemented in other real-world applications such as implementing multi-tenant RBAC in Nuxt.js, implementing multi-tenancy RBAC in MongoDB, and using JWTs for authorization.

Building a Comment System in a Next.js Blog with BCMS

Juliet Ofoegbu — Thu, 03 Apr 2025 06:32:21 +0000

So, I recently set up a comment system in a Next.js app using BCMS, and I wrote about the whole process.

Why BCMS? It’s super flexible, has a clean API, and makes managing dynamic content (like user comments) way easier. No need to hack things together—it just works.

In the article, I break down:

How to structure comments in BCMS
Setting up an API route in Next.js to handle submissions
Displaying comments on the frontend

If you’ve ever wanted to add a simple comment system to your project, this might help. Check it out here on the BCMS blog site.

Forget Disqus and build your own comment system!

Build a Simple Blog with Astro, BCMS & TailwindCSS

Juliet Ofoegbu — Mon, 24 Feb 2025 10:37:18 +0000

Want to build a high-performance blog? Here’s how I did it with Astro + BCMS using the BCMS Astro blog starter.

I just wrote a new article where I walk you through building a fully functional blog using Astro and BCMS, a headless CMS that allows you to manage your content easily and integrates easily with modern frameworks.

Content of the blog includes:
•⁠ ⁠Setting up Astro & BCMS for easy content management using the BCMS Astro start command
•⁠ ⁠Understanding concepts in BCMS such as templates, properties, and entries
•⁠ ⁠Fetching & displaying blog posts dynamically
•⁠ ⁠Other things you should know about utilizing the BCMS + Astro blog starter.

If you’re a developer, blogger, or just curious about modern web development, this guide has everything you need to start building.

Check out the full blog here.

A Developer's Take on Cerbos: The Smarter Way to Handle Authorization

Juliet Ofoegbu — Thu, 19 Dec 2024 06:20:36 +0000

Authentication combined with authorization forms the backbone of application security and secure access control, with authorization ensuring that users can only access what they are allowed to. For many developers, implementing authorization is complex and time-consuming.

Enter Cerbos: an open-source solution that takes the burden out of creating and managing authorization, so you can focus on implementing other features in your application.

Today, I'm going to share my Cerbos experience and why I believe it's a game changer for developers, whether you're a developer working on a side project, developing any kind of application, or managing a large business system.

What Is Authorization?

First, let’s start with the basics. Authorization is the process of determining what actions a user is allowed to perform and what resources they can access within an application.

Just look at it this way:

Authentication is the “Who are you?” part (logging in, verifying identity).
Authorization is the “What can you do?” part (access control).

In the real world, authorization might mean ensuring that:

Users can only access their own data. For example, a customer can see their own invoices but not others'.
Admins have the right level of control. For example, an admin can control user accounts but would not have access to their sensitive details.
Guests and public users have restricted access. A guest can see a website's content but cannot make purchases without the necessary permissions.
Roles and permissions align with duties within a team. For example, a project manager can change project details, but team members can only see the tasks assigned to them.

This sounds simple enough, but implementing it in your application or system is a different challenge, and here's why:

If you hardcode rules directly into your application, it will quickly become a complex web of if-else statements and conditions, which turns into having to do a lot of maintenance over time.
Businesses and their requirements evolve over time. New roles, permissions, and exceptions come up, and your system needs to keep up with these changes. Adapting to these changing requirements can introduce bugs or require you to rewrite the whole authorization code.
Building a custom authorization system from scratch takes months of effort, and that's before you even start testing and scaling it.

With these challenges in mind, you need a solution that makes the authorization process easy for your application, and in comes Cerbos.

What Is Cerbos, and How Does It Work?

Cerbos is a policy-based access control (PBAC) solution that simplifies the implementation and management of fine-grained application access control.

Compared to traditional role-based systems (RBAC), PBAC is more flexible. Cerbos, for example, doesn't restrict privileges to static roles but allows you to create rules that consider changing factors such as user attributes, resources, environment, etc.

Here’s how it works:

Write and update policies: Cerbos policies are written in YAML, a clean, human-readable, and version-controllable format. You decide who can do what and under what conditions and update these policies anytime you want. For example:

resources:
  Orders:
    kind: Orders
    id: Orders:001
    attr:
      example: true

Check permissions: Cerbos provides APIs for evaluating these policies. It is as easy as sending the user, resource, and action in a request:

if (await cerbos.isAllowed({ principal: user, resource, action: "edit" })) { // allowed }

Make requests: The application makes a call to Cerbos' SDK, which returns information about the user and the resource requested.
Get a response: Cerbos compares the request to current policies and returns an allow or deny response.
Deploy anywhere: You can deploy Cerbos to fit your stack, whether you're running a monolithic architecture or a complex microservices setup. It supports multiple languages such as JavaScript, Python, Java, PHP, etc., which makes it versatile and developer-friendly.
Real-time flexibility: Cerbos is not restricted to static policies. You can define dynamic conditions based on runtime data, such as allowing access only during certain hours or while a user's subscription is active.

What Makes Cerbos Stand Out?

Here’s what I love about Cerbos:

1. No more hardcoding rules

When you hardcode rules in your application, every small change means going back into your codebase, rewriting logic, and testing everything over again. With Cerbos, rules are externalized into policies. If you need to adjust permissions, just modify the YAML file; no need to redeploy.

2. Dynamic, context-aware policies

Defining roles like "system admin," "developer," etc. sometimes isn't enough; you'd want to grant personnel permission only when certain conditions, which evaluate the ownership of a resource, the time of access, or specific attributes of the user or resource, are met.

An example could be allowing personnel to access certain information only when they're in a secure location, like within the organization, or restricting access when their logged in with a public WiFi.

For example, this policy allows customers to only view orders where customerId matches their userId.

For example:

match:
  expr: request.resource.attributes.customerId ==  request.principal.attributes.userId

This allows you to manage situations when permissions are based on the user's relationship with the resource rather than just their job.

For more details on context-aware policies in Cerbos, read this Understanding Context-Aware Permissions blog.

3. Centralized and transparent

Having a single place for all of your authorization rules makes it easier to manage, audit, and troubleshoot them. Plus, Cerbos is open-source, which means you can inspect and understand how decisions are made.

4. Built for developers by developers

Cerbos speaks our language, literally. It’s quick and easy to get started thanks to the available SDKs for various programming languages and integrations.

A Day in the Life of Using Cerbos

I’ll demonstrate all I’ve been saying about Cerbos with a practical example.

Let's say I’m building an online store application. My users include regular customers, managers, and administrators. Each of these roles has different permissions:

Customers are end users who browse the store, place orders, and manage their accounts.
Managers are the staff responsible for managing inventory and tracking order statuses.
Admins are superusers with full control over the system, including user and inventory management.

Here’s how I’d handle this with Cerbos:

1. Define Policies

First, I’ll write policies that clearly outline who can do what. These policies will be stored in a YAML file, which I can version-control alongside my code. This allows me to easily track changes and collaborate with my team.

The principals.yaml file:

principals:
  admin:
    id: admin@yourapp.example.com
    roles:
      - admin
    attr:
      example: true

  customer:
    id: customer@yourapp.example.com
    roles:
      - customer
    attr:
      example: true

  manager:
    id: manager@yourapp.example.com
    roles:
      - manager
    attr:
      example: true

The resources.yaml file:

resources:
  Orders:
    kind: Orders
    id: Orders:001
    attr:
      example: true

  Products:
    kind: Products
    id: Products:001
    attr:
      example: true

  Users:
    kind: Users
    id: Users:001
    attr:
      example: true

Here’s how it looks on my Cerbos playground:

2. Integrate with My App

I'll then integrate Cerbos into my application by adding a few lines of code, configure it with this policy, and use the Cerbos API to check permissions.

For example, to check if a user can delete a product:

const { isAllowed } = await cerbos.check({
  resource: "products",
  action: "delete",
  principal: { role: "manager" },
});

if (isAllowed) {
  // Perform the delete action
} else {
  // Deny access
}

3. Version Control My Policies

Next, I’ll store the policy YAML file in my repository to track changes and ensure it is consistent across environments.

4. Adapt Over Time

As my platform grows and new roles and features are added, I will simply update the policies. There is no need to touch my application logic, which reduces the risk of breaking existing functionality.

Seamless right? I thought so too.

Cerbos Hub for Enterprises

I previously mentioned that Cerbos is an open-source solution; however, while the open-source version of Cerbos is enough for most use cases, business enterprises often require more.

This is when Cerbos Hub comes into play, and here are some of its features:

Its centralized management allows you to manage policies for multiple apps, teams, and projects through a single interface.
It allows you to find which policies are being used the most, identify potential bottlenecks, and receive insights into your access control system.
In businesses where compliance is very important, the "audit trails" feature allows you to prove that your access controls are strong and reliable.

Final Thoughts

Cerbos helps simplify a difficult aspect of software development-authorization as it allows you to focus on what you do best. So even if you're building a simple app or a complex system, Cerbos makes authorization feel simple.

But don't just take my word for it. If you're not familiar with it, try Cerbos for yourself, and perhaps after experiencing its simplicity, you'll wonder why you haven't used it before.

To get started, run Cerbos from one of the many options available. But before that, you can try out the Cerbos’ playground—an interactive environment for creating and testing authorization policies in real-time—to see what it can actually do.

What do you think about Cerbos? If you’ve used it or have questions, drop a comment below.

Comprehensive Guide to Top Monitoring and Logging Services

Juliet Ofoegbu — Wed, 28 Aug 2024 07:46:15 +0000

Prerequisites

Basic technical knowledge of IT infrastructure
Experience with IT tools (monitoring and logging tools)

Introduction

If you own a business, downtime on your website or application can lead to income and client losses. A security breach that goes unnoticed in the system can expose personal information about clients or the organization. Things can go wrong to compromise the security of an organization's system.

Effective monitoring and logging services protect business operations from potential threats. They are an essential part of every organization's technical infrastructure. These services ensure the systems run smoothly and provide insights into potential issues that systems may encounter, preventing them from worsening and affecting users.

Suppose you're a developer, DevOps engineer, or IT personnel who works with an organization's computer networks and servers and wants to improve the performance and security of your infrastructure. In that case, you'll find this article quite helpful. It will help you to make informed decisions about your monitoring and logging needs.

Let's start with understanding these terms in relation to IT infrastructure: monitoring, monitoring services, logging, and logging services.

Understanding Monitoring and Logging

Monitoring and Monitoring Services
Monitoring involves constantly inspecting systems to ensure they are working properly and detecting problems such as performance bottlenecks, errors, or downtime.

Monitoring services, therefore, are services or tools that help you inspect your computer systems, applications, and networks to ensure everything is working smoothly. If something goes wrong, they notify you so you can fix it before it affects your users.
Logging and Logging Services
Conversely, logging captures and records system events and activities, creating a detailed logbook used to debug issues and understand system behavior over time.

Logging services are services or tools that record what happens within your systems and applications. Every system event is recorded in a log. These records help you understand what happened and why, making troubleshooting and improving your systems easier.

Top Monitoring and Logging Services

There are lots of monitoring and logging services available in the market.

In this tutorial, we'll go over some of the most popular ones, such as Amazon CloudWatch, Datadog, Splunk, Prometheus & Grafana, and the ELK (ElasticSearch, Logstach, Kibana) Stack, covering their features, capabilities, integrations, benefits, use cases, and pros and cons.

1. Amazon CloudWatch

Amazon CloudWatch is a monitoring and management platform that offers detailed insights into your applications, infrastructure, and services, allowing you to resolve issues quickly and enhance your application's performance. It is a service provided by Amazon Web Services (AWS) for developers, system administrators, and IT managers.

Key Features:

Real-time Monitoring:
With CloudWatch, you can monitor your AWS services in real time. You can also monitor EC2 instances, RDS databases, and Lambda functions. CloudWatch enables you to collect and track metrics, create alarms that send an Amazon SNS message or perform an action, and respond to changes in your AWS environment.
Custom Metrics
You can create, publish, and monitor your custom metrics if you want to monitor application-specific metrics not included by default in CloudWatch.
Alarms and Notifications
One of CloudWatch's many features allows you to set up alarms to monitor metrics and send out notifications for quick response to changes in your application. You can also set alarms to automate actions when thresholds are exceeded. An example would be using Amazon SNS to alert an operator of an Auto Scaling action. You can create metric and composite alarms in Amazon CloudWatch.
Logs Management
With the CloudWatch Logs service, you can collect, monitor, store, and access log files from different sources, such as AWS Lambda, AWS CloudTrail, Amazon API Gateway, etc. This helps you identify and understand the root cause of your application's behavior.
CloudWatch Dashboards
Your CloudWatch dashboard allows you to easily customize and view your AWS resources and analytics in real-time. CloudWatch's customizable dashboard feature enables you to create dashboards that you can use to monitor operational data, visualize metrics, and log data all in one place.
Events
CloudWatch Events provide a near-real-time stream of system events that indicate changes in the AWS resources. You can set up rules that automatically respond to and perform some actions when these event changes are detected.

Capabilities:

Scalability: CloudWatch can scale with your AWS resources to handle data from hundreds of resources. You can find AWS Cloud computing data center facilities in regions known as Regions. These regions provide additional scalability and reliability.
Automation: Metric alerts and events trigger automated actions like scaling and notifications.
Retention: CloudWatch has a long-term data storage and retrieval feature that allows one to store metric data for over 15 months.

Integrations

AWS services: CloudWatch allows seamless integrations with various AWS services, including EC2, RDS, Lambda, and ECS.
Third-party tools: To improve functionality, it can be integrated with other monitoring tools, such as Prometheus and Grafana.
Custom applications: CloudWatch allows integration with various language SDKs to make it easy for developers to build applications in their preferred language.

Benefits

Offers detailed insights into how the AWS resources are being utilized, as well as the performance and operational health of the application.
Provides detailed logs and real-time monitoring of infrastructures and systems to improve troubleshooting skills.
Enables one to proactively manage their infrastructures by activating alarms and automating metrics-based actions.
Identifies unused resources to allow for better resource utilization and cost savings.

Use Cases

Tracking application performance and identifying issues.
Monitoring AWS infrastructure's health and performance.
Anomaly detection
Auditing operations using logs and events.

Pros and Cons

Pros

It can be easily integrated with various AWS services, allowing you to monitor all of your AWS resources.
You can adjust monitoring to meet your specific needs with custom metrics and dashboards.
It allows for automated actions responding to alarms and events, eliminating the need for manual intervention.
It provides real-time insights, allowing you to respond quickly to issues.

Cons

It can become quite expensive as costs build up over time, especially with high-frequency custom metrics and log retention. Due to its many features and capabilities, it can be challenging for new users. Therefore, it requires time and effort to fully understand and use all the features effectively.

2. Datadog

Datadog is a cloud-based platform for monitoring servers, databases, and services through a SaaS-based data analytics platform. It helps organizations improve application performance and ensure the reliability of their systems.

Key Features:

Infrastructure Monitoring
One of Datadodog's key features is its infrastructure monitoring, which provides real-time metrics, analytics, visualizations, and detailed insight into the performance of infrastructure servers, databases, and other components.
Application Performance Monitoring (APM)
Datadog's APM feature helps one monitor, troubleshoot, and improve application performance. It provides detailed insights into application code, latency, and error rates.
Log Management
Datadog supports centralized logging. With the Datadog log management feature, you can collect, manage, and analyze log data from all your systems and services at any scale.
Dashboards and Visualizations
Datadog enables users to create customizable dashboards to get real-time data and help you keep track of critical metrics.
Alerts and Notifications
Datadog's automated alerts feature notifies you of any application performance issues, anomalies, or breaches.

Capabilities

Scalability: Datadog can scale to monitor large, complex environments with many hosts and containers.
Single monitoring view: You can combine APM, infrastructure monitoring, and log management to get a single view of your environment in Datadog.

Integrations

Datadog comes with more than 750 built-in integrations.

Cloud providers: Integrates easily with various cloud providers such as AWS, Azure, Google Cloud, and more to monitor your cloud-based infrastructures.
Containers and Orchestration: Datadog supports Docker, Kubernetes, Fabric, and other container & orchestration technologies.
Third-party tools: Datadog also works with various third-party tools for notifications, incident management systems, and CI/CD pipelines.

Benefits

Datadog provides a single platform view to monitor your entire stack, from infrastructure to applications, network flows, and logs. With this, you can easily navigate between metrics, tracks, and logs.
Its simple user interface makes it easy to use. It also has customizable dashboards that make it easy to monitor and analyze data.
It enables proactive monitoring and alerting to help prevent issues before they affect users.
Datadog improves one's troubleshooting skills with detailed metrics and centralized logging features.

Use Cases

Infrastructure monitoring to monitor the health and performance of servers, databases, and other infrastructure components.
Application performance monitoring to track application performance in real-time and troubleshoot issues.
Security monitoring to track potential threats across your entire stack.
Cloud monitoring to monitor cloud infrastructure and services from various cloud providers.
Log management to analyze logs from various sources.

Pros and Cons

Pros

Datadog supports a wide range of tools and integrations.
It combines infrastructure, APM, and log management that can viewed in one platform.
It provides real-time insights and alerts.
It is easy to set up and use.

Cons

The cost can be high, especially for big companies with complex and extensive monitoring data.
It can be hard to setup and configure for large environments.
It has limited data retention periods depending on the pricing plan (e.g., 15 months metric retention for the Pro plan).

3. Splunk

Splunk is a data platform for searching, collecting, monitoring, and analyzing machine-generated data using a web interface. It gives organizations full visibility into their digital operations, allowing them to identify risks and issues before they become problems.
With automation support, teams can respond quickly, preventing problems from escalating. Splunk can also help you uncover data patterns and use insights to improve company operations and metrics.

Key Features

Log Management
The Splunk log management feature enables collecting, parsing, and analyzing log data. Types of log data include application logs, security logs, network logs, etc.
Reporting and Metrics
You can create real-time reports and schedule them to run at intervals. You get the visual analysis of metrics, logs, and event data for your report.
Machine Learning
Splunk incorporates AI and machine learning algorithms into its data strategy to gain insights, such as detecting anomalies, predicting trends, forecasting time series, and making smarter decisions.
Dashboards and Visualizations
Create interactive, real-time dashboards that visualize data insights, like critical metrics and trends. There are also lots of visualization types to choose from, including area and line charts, bubble charts, maps, graphs, etc.
Alerting
Splunk's alerting feature allows you to monitor specific conditions, get real-time updates on critical events, and respond to events. Splunk can notify you via email, Slack using Slack webhook, or configuring a custom webhook.

Capabilities

Flexibility: It supports data collection from various data sources, such as databases, web services, and files, providing flexibility in data collection and analysis.
Real-time processing: Processes and analyzes data in real-time to enable quick responses to issues.

Integrations

Cloud services: You Splunk can be easily with cloud service providers like AWS, Azure, and Google Cloud Platform.
Container orchestration: Integrates with containers like Kubernetes.
Security tools: Integrates well with security information and event management (SIEM) tools for enhanced security threats detection and monitoring.

Benefits

Splunk gives detailed insights into log data, allowing you to better understand and improve your systems.
Splunk advanced search and real-time analysis enhance troubleshooting.
Splunk leverages Artificial Intelligence and Machine Learning for deeper insights to improve your business decision-making process.
Splunk monitoring and alert feature enables proactive monitoring and alerts to prevent issues from happening.

Use Cases

Advanced threat detection and analysis of network activity that might threaten the systems.
Security monitoring using Splunk's SIEM capabilities to gain end-to-end visibility and monitor and respond to security threats.
Incident management analytics to quickly investigate and fight security threats in the IT infrastructure.
Analyzing business data to gain insights and drive strategic decisions.

Pros and Cons

Pros

It is scalable, which is important for large enterprises with large data volumes.
It provides advanced searching and analyzing capabilities.
It leverages AI and machine learning for advanced data insights and analysis.
It supports a wide range of data sources.

Cons

It can be expensive to deploy, especially when dealing with large volumes of data.
It can be complex to set up and manage.

4. Prometheus and Grafana

Prometheus and Grafana are two popular open-source tools that are often used together for monitoring and visualization.

Prometheus is an open-source monitoring solution that collects and stores metrics and insights, while Grafana is a data visualization and monitoring solution that collects, correlates, and visualizes data with dashboards.

Prometheus

Grafana

Key Features

Prometheus:

Time-Series Database
Prometheus stores and collects metrics as time series data using a pull model over HTTP. Prometheus identifies these metrics by their names and key/value pairs.
Multidimensional Data Model
Prometheus uses a multidimensional data model that includes labels for identifying time-series data.
Powerful Query Language (PromQL)
Prometheus has a feature - PromQL, that can be used to slice and dice collected time series data into tables, graphs, and alerts.
Service Discovery
Prometheus uses service discovery and static configuration to automatically discover and scrape metrics from targets.
Alerting
Prometheus's alerting system uses PromQL to define the alert conditions and supports many notification channels.

Grafana:

Visualization
Grafana is excellent for visualizing data from various sources in different formats, like tables, charts, and graphs.
Data Source Integrations
Grafana supports multiple data sources, including Prometheus, Cloudflare, Azure Monitor, Elasticsearch, Splunk, and so on.
Custom Plugins and Extensibility
Grafana's plugin system enables you to extend its functionality with various plugins, like Zabbix.
Alerting
Grafan also provides an alerting feature based on the dashboard data. These alerts can be sent using different notifiers, including Email, Slack, and PagerDuty.

Capabilities

Flexibility: Using Prometheus' query language feature and Grafana's visualization together makes data analysis and presentation flexible.
Scalability: Prometheus and Grafana can scale to monitor large environments handling lots of data.

Integrations

Prometheus
Prometheus enables integrations with various exporters to collect metrics from different systems, including MongoDB, Kubernetes, Jira, Jenkins, and more.
Grafana
Prometheus enables integrations with multiple data sources and supports different data plugins for additional functionalities.

Benefits

Prometheus is great for collecting data and metrics, and Grafana is an excellent tool for visualizing the data.
Prometheus and Grafana have alerting features to notify you of anomalies based on defined conditions.
Grafana has a customizable dashboard functionality that allows you to personalize the visual presentation of your data.
Prometheus and Grafana are both open-source, making them cost-efficient.

Use Cases

Monitor and optimize application performance to identify and troubleshoot problems.
Monitor Kubernetes clusters with Prometheus and display the data with Grafana.
Collect and visualize custom metrics for your apps and services.

Pros and Cons

Pros

They are both free to use as they are open-source tools.
Supports a wide range of data sources and integrations.
Grafana provides rich, customizable dashboards.

Cons

They can be complex to configure, especially when working in large environments.
Prometheus' alerting capabilities can be limited as you'll need to install a separate plugin to push the notification to the necessary channels.

5. ELK Stack (Elasticsearch, Logstash, Kibana)

The Elastic, Logstash, and Kibana (ELK) Stack comprises three open-source tools: Elasticsearch, Logstash, and Kibana. These tools enable users to take data from any source, search, analyze, and visualize it in real time.

Key Features

Elasticsearch

Search and Analytics Engine
Elasticsearch is a distributed search and analytics engine that stores your data so you can index, search, and analyze them.
Scalability
Elasticsearch can scale horizontally to meet your needs, handle large volumes of data, and balance multi-node clusters.
Full-Text Search
Elasticsearch's full-text search functionality enables searches within full-text fields to find the most relevant documents. The full-text queries allow you to search the analyzed text fields.

Logstash

Data Ingestion
Logstash is a server-side data processing pipeline that ingests data from multiple sources, transforms it, and sends it to your desired storage location (e.g., Elasticsearch).
Main Components
The Logstash pipeline has three main components or stages - inputs, filters, and outputs. The inputs are used to get data into Logstash. The filters are where the data is processed and transformed. The output is the final phase of the Logstash pipeline, and it's where the processed data is sent (Elasticsearch, file, graphite, or statsd)
Plugin Ecosystem
Logstash has over 200 plugins for inputs, filters, and outputs that can be used to customize your data pipeline.

Kibana

Visualization
Kibana offers visualization capabilities in addition to Elasticsearch data. You can create bar charts, line graphs, pie charts, and maps. Kibana also lets you generate visualization for metrics like count, average, sum, min, max, standard deviation, etc.
Dashboard Creation
Kibana lets you create and share dashboards that combine a collection of visualizations (charts, maps, filters) to display the full picture of your data and aid decision-making. The image panel allows you to add your own logos and graphics to personalize your dashboards.

Capabilities

Search and analytics: Elasticsearch has extensive search and analytics capabilities to handle massive data sets.
Data ingestion: Logstash can ingest data from various sources, transform it, and store it in Elasticsearch.
Data visualization: Kibana lets you visualize your data for analysis and interpretation.

Integrations

Data sources: Logstash supports multiple data sources, including databases, application log files, metrics, and network traffic.
Third-party tools: Integrates with other monitoring tools, security solutions, cloud provider solutions, and data storage services.

Benefits

The ELK Stack provides full data analysis capabilities, such as data ingestion, full-text search, and data visualization.
The ELK stack is cost-effective as its components are open-source and free.
The ELK Stack allows for real-time monitoring and analysis of log data.
It can manage large volumes of data, making it ideal for enterprise monitoring.

Use Cases

Application performance monitoring to monitor real-time performance, identify performance issues, and fix problems quickly.
Log management to analyze logs from different sources.
Security Information and Event Management (SIEM) to help you monitor your systems for security threats and respond to security threats.
Business analytics to analyze large datasets, generate insights, and build interactive dashboards to drive strategic business decisions.

Pros and Cons

Pros:
Elasticsearch offers advanced search and analytics capabilities and can also handle a large volume of data as it is designed for horizontal scalability.

Supports ingestion from a wide range of data sources.
It is free to start, as all its components are open-source products.

Cons:

The ELK stack can be complex to set up and maintain.
Requires significant resources, such as memory and CPU, for efficient performance.
Although it is free to use, it might become costly as your applications grow or if you store a large volume of log data.

Similarities and Differences Between These Tools

Feature/Service	Amazon CloudWatch	Datadog	Splunk	Prometheus & Grafana	ELK Stack (Elasticsearch, Logstash, Kibana)
Overview	AWS-native monitoring and management service	Cloud-based monitoring and analytics platform	Comprehensive data analysis and monitoring tool	Open-source monitoring and visualization	Open-source log management and analysis platform
Key Features	Metrics collection, log monitoring, alarms, dashboards	Metrics, traces, logs, APM, dashboards	Log management, search, visualization, machine learning	Time-series data collection, alerting, dashboards	Full-text search, log aggregation, visualization
Capabilities	Cloud resource monitoring, custom metrics, automation	End-to-end visibility, real-time monitoring, analytics	Advanced search and query, machine learning, alerting	Metrics collection, visualization, alerting	Log indexing, search, data visualization
Integrations	AWS services, third-party integrations	Cloud services, third-party tools	Wide range of integrations and apps	Various exporters and integrations	Numerous log sources, data pipelines
Use Cases	AWS resource monitoring, application performance	Full-stack monitoring, infrastructure management	Security information, operational intelligence	Infrastructure and application monitoring	Log analysis, application monitoring, data visualization
Pros	AWS integration, easy setup for AWS users	Comprehensive features, user-friendly, scalable	Powerful search capabilities, extensive features	Open-source, flexible, highly customizable	Scalable, strong community support, flexible
Cons	AWS-centric, can be expensive	Can be costly at scale, complex setup	Expensive, high learning curve	Requires setup and management, not a complete solution	Can be complex to configure, resource-intensive

Criteria for selecting monitoring and logging services

When selecting monitoring and logging services, remember these points to ensure you choose a solution that meets your organization's requirements.

1. Features

What features does the tool have?

Ensure the tool you're considering provides services you'll need for your monitoring/logging needs, such as application performance, network monitoring, and log management.

Make sure the tool has real-time alerting functionality and customizable dashboards, as these are all important features. This might not be a priority, but you can check how long the service retains historical data.

2. Integration

How well does the service integrate with your existing tools and systems?

Ensure the monitoring and logging service integrates seamlessly with your systems' existing tools and platforms. The tool might not include some functionalities by default, so check to see if there are available plugins or extensions to extend its capabilities.

3. Scalability

Can it scale to meet your business's needs?

One crucial factor, especially for large organizations, is to know if their service can scale to handle large volumes of data and more complex requirements as the infrastructure grows. It should be scalable and maintain constant and efficient system performance as it expands.

4. Security

Does the service provide proper security measures?

Security is crucial to any organization, so look for services that prioritize data security, like utilizing SIEM.

5. Cost

What is the cost of using and maintaining the service?

If the service offers free trials or tiers, try them out before upgrading your plan or making payments. Check out the metrics on which the pricing is based, such as data volume, number of hosts, etc. Consider the subscription fee and the cost of maintaining the service.

6. Ease of use

How easy is it to use this tool?

Tools that are not user-friendly or difficult to use usually discourage potential consumers. To avoid complications, ensure the service is user-friendly and easy to configure and monitor. Ensure that the service includes thorough documentation and tutorials for users so that they can quickly resolve any issues that may come up.

Conclusion

The right monitoring and logging service depends on your system requirements, environment, and budget. Understanding the features, capabilities, pros, and cons of each tool allows you to make an informed decision that improves the reliability, performance, and security of your IT infrastructure.

Since monitoring and logging are essential aspects of IT infrastructure management, investing in the proper monitoring and logging services is necessary to ensure effective business operations.

Build a Finance Tracker with Next.js, Strapi, and Chartjs: Part 3

Juliet Ofoegbu — Tue, 06 Aug 2024 07:10:12 +0000

Part 3: Setting up user authentication and personalized reporting

This Part 3 is a continuation of Part 2 of our blog series. If you haven't read Part 1 and Part 2 of this series, it's advisable that you do so to understand how we got to this stage.

Tutorial Outline

For reference, here are the previous parts of this blog series:

Part 1: Build a finance tracker app - Setting up Strapi & implementing the app's CRUD functionalities
Part 2: Build a finance tracker app - Adding visualization with charts
Part 3: Setting up user authentication and personalized reporting

We'll add some protection for Part 3 of this blog series to prevent unauthorized access to our application.

Configure Settings in Strapi

Strapi provides built-in authentication and user management features, including roles and permissions. Follow these steps to configure these settings and set roles and permissions.

Create Roles and Permissions:

Navigate to the Strapi admin panel.
Go to the USERS & PERMISSIONS PLUGIN section.
Click on the option - Roles.
Configure the permissions for authenticated and public roles according to your application's needs. To do this, select the 'Authenticated' option.

Scroll down the page that opens up and toggle the 'Users-permission' dropdown.
- Under the 'Auth' section, tick the 'connect' and 'register' checkboxes.
- Under the 'Roles' section, tick the 'createRole', 'find', and 'findOne' checkboxes.
- Under the 'User' section, tick the 'create', 'find', 'me', and 'findOne' checkboxes.

Save your configuration.

Create The Authentication Page in Next.js

We'll start by creating our folder structure layout for these authentication pages. We need two pages for authentication: the signup page and the login page.

Remember, in Part 1 of this blog series, we made the 'Overview' page the first page displayed to the user when they enter the application. We'll change it to be the page they're navigated to after a successful signup and login, meaning we'll make the sign-up/log-in page the main page of the application.

Page Layout for the Authentication Routes

Let's create our components first.

In our app folder, we'll create a new folder and name it auth. We'll create two sub-folders in this newly created folder - 'signup' and 'signin'.
In the 'signup' folder, we'll also create a component called SignUp.tsx In the 'signin' folder, we'll create two components - page.tsx and SignIn.tsx.
These will be the signup and sign-in form pages, which will contain forms for signing up and logging in to the application.

The layout will look like this:

app/
┣ auth/
┃ ┣ signin/
┃ ┃ ┣ page.tsx
┃ ┃ ┗ SignIn.tsx
┃ ┗ signup/
┃   ┗ SignUp.tsx
┣ dashboard/
┣ globals.css
┣ head. tsx
┣ layout. tsx
┗ page.tsx

In the page.tsx component inside the app folder, the first page of the application will be changed from the overview dashboard page to the signup page.

To do this, we'll change this page.tsx component from this:

import SideNav from "@/components/SideNav";
import Overview from "./dashboard/Overview";

const page = () => {
  return (
    <>
      <div>
        <SideNav />
        <div>
          <Overview />
        </div>
      </div>
    </>
  );
};
export default page;

To this:

"use client";
import SignUp from "./auth/signup/SignUp";

function App() {
  return (
    <div>
      <SignUp />
    </div>
  );
}
export default App;

We'll have to change the 'Overview. tsx' file name to 'page.tsx'. The component will look like this now:

'use client'
import React, { useState, useEffect } from 'react';
import axios from 'axios';
import BarChart from './budget/BarChart';
import PieChart from './budget/PieChart';

const page: React.FC = () => {
    const [budgets, setBudgets] = useState<{ category: string; amount: number; }[]>([]);
    const [chartType, setChartType] = useState<'bar' | 'pie'>('bar');

    useEffect(() => {
        const fetchBudgets = async () => {
            try {
                const res = await axios.get('http://localhost:1337/api/budgets?populate=budget');
                const data = res.data.data.map((budget: any) => ({
                    category: budget.attributes.category,
                    amount: budget.attributes.amount,
                }));
                setBudgets(data);
            } catch (error) {
                console.error('Error fetching budgets:', error);
            }
        };

        fetchBudgets();
    }, []);

    const categories = budgets.map(budget => budget.category);
    const amounts = budgets.map(budget => budget.amount);

    return (
        <main>
            <div>
                    <h2>OVERVIEW</h2>
                    <div>
                        <button onClick={() => setChartType('bar')} className={`mx-2 py-2 px-3 ${chartType === 'bar' ? 'bg-teal-500 text-white' : 'bg-gray-200 text-gray-700'} rounded-lg`}>
                            Bar Chart
                        </button>
                        <button onClick={() => setChartType('pie')} className={`mx-2 py-2 px-3 ${chartType === 'pie' ? 'bg-teal-500 text-white' : 'bg-gray-200 text-gray-700'} rounded-lg`}>
                            Pie Chart
                        </button>
                    </div>
                </section>
                <section className="mt-">
                    {chartType === 'bar' ? (
                        <BarChart categories={categories} amounts={amounts} />
                    ) : (
                        <PieChart categories={categories} amounts={amounts} />
                    )}
            </div>
        </main>
    );
};

export default page;

Note: This overview page was worked on in Part 2 of our series.

Creating the Forms

Let's create the forms that will be used to authenticate users.

Create the sign-up form page
Let's go to our SignUp.tsx component and paste these lines of code to build the sign-up form.

"use client";
import React, { useState } from "react";
import { FaEye, FaEyeSlash } from "react-icons/fa";
import Link from "next/link";
import axios from "axios";
import { useRouter } from "next/navigation";

const SignUp = () => {
  const [username, setUsername] = useState("");
  const [email, setEmail] = useState("");
  const [password, setPassword] = useState("");
  const [showPassword, setShowPassword] = useState(false);
  const handleTogglePassword = () => {
    setShowPassword((prevShowPassword) => !prevShowPassword);
  };

  const router = useRouter();

  const handleSubmit = async (event: { preventDefault: () => void }) => {
    event.preventDefault();
    try {
      const response = await axios.post(
        "http://localhost:1337/api/auth/local/register",
        {
          username,
          email,
          password,
        },
      );
      console.log(response.data);
      alert("Registration successful!");

      // Clear the form inputs
      setUsername("");
      setEmail("");
      setPassword("");

      // Redirect to the login page
      if (typeof window !== "undefined") {
        router.push("/auth/signin");
      }
    } catch (error) {
      console.error(
        "Registration failed:",
        error.response?.data || error.message,
      );
      alert("Registration failed. Username or email invalid or already taken");
    }
  };

  return (
    <main>
      <h1>Sign up</h1>
      <form onSubmit={handleSubmit}>
        <div>
          <label htmlFor="username">Username</label>
          <input
            type="text"
            placeholder="Enter your username"
            value={username}
            onChange={(e) => setUsername(e.target.value)}
          />
        </div>

        <div>
          <label htmlFor="email">Email</label>
          <input
            type="email"
            placeholder="Enter your email address"
            value={email}
            onChange={(e) => setEmail(e.target.value)}
          />
        </div>

        <div>
          <label htmlFor="password">Password</label>
          <input
            type={showPassword ? "text" : "password"}
            placeholder="*******"
            value={password}
            onChange={(e) => setPassword(e.target.value)}
          />
          <div onClick={handleTogglePassword}>
            {showPassword ? <FaEyeSlash /> : <FaEye />}
          </div>
        </div>

        <button type="submit">Sign Up</button>
      </form>

      <p>
        {" "}
        Already have an account?
        <Link href="/auth/signin">
          <span>Login</span>
        </Link>
      </p>
    </main>
  );
};

export default SignUp;

Note: I don't want the code to be too long, so I've omitted the styling for all the components in this article. You can check out the full TailwindCSS code later.

Code explanation:

We first have to set up state management to manage the states for username input, email input, password input, and showPassword for password visibility using the useState hook.
We created a handleTogglePassword function to handle the password visibility toggle.
Using the useRouter hook from Next.js, we handled page routing after a successful signup.
We created a handleSubmit function to send a POST request to the Strapi registration endpoint (http://localhost:1337/api/auth/local/register). This function logs the response data to the console and displays an alert for successful signup. It then clears the form inputs and redirects us to the sign-in page (/auth/signin) upon a successful registration.
We then rendered the signup form UI with username, email, and password inputs.

Here's what our signup page looks like after styling:

Create the sign-in form page
Inside our SignIn.tsx component that's located inside the 'signin' folder we created, we'll paste these lines of code:

"use client";
import React, { useState } from "react";
import { FaEye, FaEyeSlash } from "react-icons/fa";
import Link from "next/link";
import axios from "axios";
import { useRouter } from "next/navigation";

const SignIn = () => {
  const [email, setEmail] = useState("");
  const [password, setPassword] = useState("");
  const [showPassword, setShowPassword] = useState(false);

  const router = useRouter();

  const handleTogglePassword = () => {
    setShowPassword((prevShowPassword) => !prevShowPassword);
  };

  const handleSubmit = async (event: { preventDefault: () => void }) => {
    event.preventDefault();
    try {
      if (!email || !password) {
        throw new Error("Please fill in all fields.");
      }
      const response = await axios.post(
        "http://localhost:1337/api/auth/local",
        {
          identifier: email,
          password,
        },
      );
      console.log(response.data);
      alert("Login successful!");

      // Save user information in local storage
      localStorage.setItem("user", JSON.stringify(response.data.user));

      // Redirect to the dashboard page
      if (typeof window !== "undefined") {
        router.push("/dashboard");
      }
    } catch (error: any) {
      console.error("Login failed:", error.response?.data || error.message);
      alert("Invalid login details");
    }
  };

  return (
    <main>
      <h1>Login</h1>
      <form onSubmit={handleSubmit}>
        <div>
          <label htmlFor="email">Email</label>
          <input
            type="email"
            placeholder="Enter your email address"
            value={email}
            onChange={(e) => setEmail(e.target.value)}
          />
        </div>

        <div>
          <label htmlFor="password">Password</label>
          <input
            type={showPassword ? "text" : "password"}
            placeholder="*******"
            value={password}
            onChange={(e) => setPassword(e.target.value)}
          />
          <div onClick={handleTogglePassword}>
            {showPassword ? <FaEyeSlash /> : <FaEye />}
          </div>
        </div>

        <button type="submit">Sign in</button>
      </form>

      <p>
        {" "}
        Don't have an account?
        <Link href="/">
          <span>Sign Up</span>
        </Link>
      </p>
    </main>
  );
};

export default SignIn;

Code explanation:

We set up state management to manage the states for email input, password input, and showPassword for password visibility using the useState hook.
The'handleTogglePassword' function was set up to handle the password visibility toggle.
Using the useRouter hook from Next.js, we handled page routing to the dashboard.
Next, we created a handleSubmit function that sends a POST request to the Strapi authentication endpoint (http://localhost:1337/api/auth/local). This function logs the response data to the console, displays an alert for successful sign-in, and saves our info in localStorage. It then clears the form inputs and redirects us to the dashboard page (/dashboard) upon successful sign-in.
Finally, we rendered the sign-in form with email and password input fields.

NOTE: Both sign-in and signup pages use similar functionality but handle different authentication endpoints (sign-in uses /api/auth/local, and signup uses /api/auth/local/register).

Here's what our sign-in form looks like after styling:

You can include a more advanced form validation and error handling method like Formik, Zod, or any other library.

Set the route for the login page
In the page.tsx component located inside the 'signin' folder, we'll paste these lines of code:

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

const page = () => {
  return (
    <>
      <SignIn />
    </>
  );
};

export default page;

Add a 'Log out' button in your sidebar navigation that will navigate users back to the signup or sign-in page.

<Link href="/auth/signin">
  <section>
    <FaSignOutAlt />
    <span>Log out</span>
  </section>
</Link>;

We can test out this functionality by inputting our registration details, logging in, and we'll be directed to the dashboard page. If we go to the 'Content-Type Builder' page of our Strapi admin panel, we'll to see the details we signed up with in the 'User' collection type.

We didn't need to create a collection type for the user's details like we did with the budget, income, and expense collections. That's because 'User' is a collection type that's available for use by default whenever we create a new Strapi project.

Update the dashboard main page
Let's go to to the 'page. tsx' file located in our 'dashboard' folder and update the code to this:

"use client";
import SideNav from "@/components/SideNav";
import React, { useEffect, useState } from "react";
import { useRouter } from "next/navigation";
import axios from "axios";
import BarChart from "./budget/BarChart";
import PieChart from "./budget/PieChart";

const page = () => {
  const [budgets, setBudgets] = useState<
    { category: string; amount: number }[]
  >([]);
  const [chartType, setChartType] = useState<"bar" | "pie">("bar");

  const [user, setUser] = useState<{ username: string; email: string } | null>(
    null,
  );
  const router = useRouter();

  useEffect(() => {
    // Retrieve user data from local storage
    const storedUser = localStorage.getItem("user");
    if (storedUser) {
      setUser(JSON.parse(storedUser));
    } else {
      // Redirect to login page if no user data is found
      router.push("/auth/signin");
    }
  }, [router]);

  useEffect(() => {
    const fetchBudgets = async () => {
      try {
        const res = await axios.get(
          "http://localhost:1337/api/budgets?populate=budget",
        );
        const data = res.data.data.map((budget: any) => ({
          category: budget.attributes.category,
          amount: budget.attributes.amount,
        }));
        setBudgets(data);
      } catch (error) {
        console.error("Error fetching budgets:", error);
      }
    };

    fetchBudgets();
  }, []);

  const categories = budgets.map((budget) => budget.category);
  const amounts = budgets.map((budget) => budget.amount);

  return (
    <>
      <main>
        <SideNav />

        <div>
          <section>
            <h2>OVERVIEW</h2>
            {user && (
              <p className="mt-4 text-lg">
                Welcome {user.username ? user.username : user.email}!
              </p>
            )}
            <div>
              <button
                onClick={() => setChartType("bar")}
                className={`mx-2 py-2 px-3 ${chartType === "bar" ? "bg-teal-500 text-white" : "bg-gray-200 text-gray-700"} rounded-lg`}
              >
                Bar Chart
              </button>
              <button
                onClick={() => setChartType("pie")}
                className={`mx-2 py-2 px-3 ${chartType === "pie" ? "bg-teal-500 text-white" : "bg-gray-200 text-gray-700"} rounded-lg`}
              >
                Pie Chart
              </button>
            </div>
          </section>

          {budgets.length === 0 ? (
            <div>
              <p>No budget has been added, so no visuals yet.</p>
            </div>
          ) : (
            <section className="mt-5">
              {chartType === "bar" ? (
                <BarChart categories={categories} amounts={amounts} />
              ) : (
                <PieChart categories={categories} amounts={amounts} />
              )}
            </section>
          )}
        </div>
      </main>
    </>
  );
};

export default page;

The things we added to this component include:

We imported SideNav component, along with the useRouter method from Next.js.
Next, we created a state to store the signed-in user's details (username and email): const [user, setUser] = useState<{ username: string, email: string } | null>(null);.
We called the useRouter method and implemented the useEffect hook to retrieve user data from local storage where it was stored in the 'Signin' page.
If the stored user data is available, it is parsed in JSON format. We will be redirected back to the login page if our data isn't found.
The username or email is then rendered in the overview page along with the charts like this:

Our app is almost ready at this point.

The Authentication Method used by Strapi

When we inspect our console in the browser, we should see the client-side code typically interacting with JWT tokens provided by the Strapi server during signup and sign-in.

That's because Strapi's server-side endpoints (/api/auth/local and /api/auth/local/register) handle JWT authentication internally.

For the Signup:
When we sign up, our credentials are usually sent to the server. After successful authentication, the server generates a JWT token containing our information and signs it with a secret key.
The JWT token is then returned to the client and stored securely, usually in local storage or a secure cookie.

For the Signin:
When we sign in, our credentials are sent to the server. After a successful authentication, the server generates a new JWT token or refreshes the existing token and returns it to the client.

To get a good understanding of this authentication method used in Strapi, take a look at beginners guide to authentication and authorization in strapi article.

Now, let's move on to a more advanced feature: personalized financial reports in our finance tracker application.

Personalized Financial Report

We want to implement a feature that will enable us to generate a personalized report based on our financial data.

Let's build!

Configuring the Strapi Backend

We'll need to configure the Strapi backend to enable this functionality. So how do we go about this?

Let's navigate to the Strapi backend folder of our project and follow the steps below:

We'll first create a new file for our controller in './src/api/report/controllers/report.js' and include these lines of code:

"use strict";

/**
 * report controller
 */

// path: src/api/report/controllers/report.js

module.exports = {
  async generate(ctx) {
    const { budgets, incomes, expenses } = ctx.request.body;

    if (!budgets.length && !incomes.length && !expenses.length) {
      return ctx.badRequest("No data available to generate report.");
    }

    // Calculate totals and find max expense
    const totalExpenses = expenses.reduce(
      (sum, expense) => sum + expense.amount,
      0,
    );
    const totalIncomes = incomes.reduce(
      (sum, income) => sum + income.amount,
      0,
    );

    let maxExpenseCategory = "N/A";
    let maxExpenseAmount = 0;

    if (expenses.length > 0) {
      const maxExpense = expenses.reduce(
        (max, expense) => (expense.amount > max.amount ? expense : max),
        expenses[0],
      );
      maxExpenseCategory = maxExpense.description;
      maxExpenseAmount = maxExpense.amount;
    }

    // Analyze and generate personalized report
    let report = " ";

    // budget report logic
    if (budgets.length > 0) {
      report += "Based on your data: ";
      budgets.forEach((budget) => {
        report += `Your budget for '${budget.category}' is '${budget.amount}', `;
      });
      report += "<br>";
    }

    // income and expenses report logic
    if (expenses.length > 0) {
      report += `You are spending more on ${maxExpenseCategory} than other expenses. <br>`;
      if (totalExpenses >= totalIncomes) {
        report += `You've spent a total of <strong>$${totalExpenses}</strong> on expenses while having an inflow/income of <strong>$${totalIncomes}</strong>, meaning you've spent more than you earned. Oops!🙁. <br>`;
      } else {
        report += `You've spent a total of <strong>$${totalExpenses}</strong> on expenses while having an inflow/income of <strong>$${totalIncomes}</strong>, meaning you managed to spend less than you earned. Kudos 🎉. <br>`;
      }
    }

    const createdReport = await strapi.query("api::report.report").create({
      data: { report },
    });

    return ctx.send({ report: createdReport.report });
  },
};

Controller code explanation:

First, we destructured to extract budgets, incomes, and expenses arrays from the request body.
We then validated the data. If all arrays are empty, it responds with a "Bad Request" error indicating no data is available to generate a report: if (!budgets.length && !incomes.length && !expenses.length) { return ctx.badRequest('No data available to generate report.'); }.
We calculated the total amounts for expenses and incomes and found the expense with the highest amount. If there are no expenses, it defaults to 'N/A.
Then, we created a personalized report string based on the provided data. This string will include HTML tags for bold formatting and break lines.
We stored the generated report in the Strapi reports collection and sent the generated report as a response.

This controller file contains the logic for generating personalized financial reports based on user data.

This is just a basic report that we generated. Feel free to change the content of the report as best you see fit.

Next, we'll create a file for our route configuration in './src/api/report/routes/report.js' and include these lines of code:

"use strict";

/**
 * report routes
 */

module.exports = {
  routes: [
    {
      method: "POST",
      path: "/generate-report",
      handler: "report.generate",
      config: {
        policies: [],
        middlewares: [],
      },
    },
  ],
};

We'll also create a file for schema in './src/api/report/content-types/report/schema.json' and include these lines of code:

{
  "kind": "collectionType",
  "collectionName": "reports",
  "info": {
    "singularName": "report",
    "pluralName": "reports",
    "displayName": "Reports",
    "description":"  "
  },
  "options": {
    "draftAndPublish": true
  },
  "pluginOptions": {},
  "attributes": {
    "report": {
      "type": "text"
    }
  }
}

Here's how our folder structure for these Strapi configuration files will look like now:

report/
┣ content-types/
┃ ┗ report/
┃   ┗ schema.json
┣ controllers/
┃ ┗ report.js
┗ routes/
  ┗ report.js

We'll need to stop our panel server from running in the terminal using the 'cls' command for windows powershell. Then we'll run the server again with the npm run develop command to make sure Strapi is aware of our new controller, route, and schema.

Open up the server in the browser.

NOTE: Anytime you make changes to the Strapi backend, the server reloads.
You'll see that Strapi automatically created a 'Report' collection in the content-type builder due to the configurations made.
Let's go to USERS AND PERMISSION PLUGINS settings, click 'Roles', and select the 'Public' option. We'll look for the newly added 'Report' permission, toggle its dropdown, and tick the 'generate' button.

We'll save it and wait for the panel to reload.

Updating the Frontend

What is left to do is to update the frontend code to implement the personalized report logic and display the report.

Let's navigate to our 'page. tsx' file inside our "/src/app/dashboard/page.tsx" and include these lines of code:

We'll create states to store the income, expenses, and report text.

const [incomes, setIncomes] = useState<
  { description: string; amount: number }[]
>([]);
const [expenses, setExpenses] = useState<
  { description: string; amount: number }[]
>([]);
const [report, setReport] = useState<string | null>(null);

Next, we'll create a fetchIncomesAndExpenses function inside the useEffect hook that's handling the budget fetching. This function will retrieve income and expense data from the Strapi API and set the state for these data in the component:

// Fetch incomes and expenses for the report
const fetchIncomesAndExpenses = async () => {
  try {
    const incomeRes = await axios.get("http://localhost:1337/api/incomes");
    const expenseRes = await axios.get("http://localhost:1337/api/expenses");

    const incomeData = incomeRes.data.data.map((income: any) => ({
      description: income.attributes.description,
      amount: income.attributes.amount,
    }));

    const expenseData = expenseRes.data.data.map((expense: any) => ({
      description: expense.attributes.description,
      amount: expense.attributes.amount,
    }));

    setIncomes(incomeData);
    setExpenses(expenseData);
  } catch (error) {
    console.error("Error fetching incomes and expenses:", error);
  }
};

We'll need to call the function in the useEffect hook like this: fetchIncomesAndExpenses();
Then, we'll create a separate generateReport function to send a POST request to the new Strapi API to generate personalized financial reports based on the current budget, income, and expense data.

If the request is successful, the generated report from the response is set in the component state using setReport. If the request fails, an error message is logged to the console, and a message alert is displayed on the app.

const generateReport = async () => {
  try {
    const res = await axios.post("http://localhost:1337/api/generate-report", {
      budgets,
      incomes,
      expenses,
    });

    setReport(res.data.report);
  } catch (error) {
    console.error("Failed to generate report:", error);
    alert("Failed to generate report");
  }
};

Lastly, we'll render a button that generates the report when it is clicked. We'll also render the report using the dangerouslySetInnerHTML property to render the HTML string.

<div className="container mx-auto py-6 flex justify-center">
  <button onClick={generateReport}>Generate Report</button>
</div>;

{
  report && (
    <div>
      <h3>Financial report</h3>
      <div dangerouslySetInnerHTML={{ __html: report }}></div>
    </div>
  );
}

NOTE: You can view the full complete code for the now updated 'page.tsx' component here.

We'll go to our browser, refresh the web app to ensure changes are reflected. In our overview page, at the bottom, click the "Generate report" button. We'll get a simplified report of our financial data.
When we go to the 'Content Manager' section in your Strapi admin panel, we'll see that the generated report was created as an entry in the 'Report' collection.

There you have it. Our finance tracker application is functional and ready for use.
You can generate a more comprehensive report using this technique.

Here's a quick demo of the report generation feature.

If you make any changes to your financial data (budget, income, expenses), the page refreshes and you can generate a new report to reflect the changes made.

Printing and Exporting Generated Report

If we want someone else to be able to view this report, we can add a functionality that allows us to export the report as PDF.

For example, if we want to export only the budget data report, including either of the charts, we can omit the part that analyzes the income and expenses in the report.js file in the controllers.

Let's only generate a report for the budget data so we can export the budget report.

So how do we print and export this data report along with the chart? Here's how we'll do it.

We'll use three libraries - html-to-pdfmake, pdfmake and html2canvas for the printing functionality.

The html-to-pdfmake library is for generating PDFs from HTML content. The pdfmake library is used to generate PDFs for both client-side and server-side, allowing us to create PDFs from structured data. The html2canvas library will be used to capture the chart as an image, and then the image will be included in the PDF document generated by the pdfmake library.

We'll have to install these libraries using this command:
"

npm install html-to-pdfmake pdfmake html2canvas

Update our overview component, like this:

First, we'll import the installed libraries.

import htmlToPdfmake from 'html-to-pdfmake';
import pdfMake from 'pdfmake/build/pdfmake';
import pdfFonts from 'pdfmake/build/vfs_fonts';
import html2canvas from 'html2canvas';

Next, we'll add this under the imports: pdfMake.vfs = pdfFonts.pdfMake.vfs;
We'll create a printReport function that will convert the HTML content of the report to a PDF and trigger a download. This function will capture the chart as an image using the html2canvas package. It will then convert the chart image and the HTML content of the report to a PDF document, including the captured chart image.

const printReport = async () => {
  try {
    const printContent = document.getElementById("report-content")?.innerHTML;
    const chartCanvas = chartRef.current;

    if (printContent && chartCanvas) {
      const canvas = await html2canvas(chartCanvas);
      const chartImage = canvas.toDataURL("image/png");

      const docDefinition = {
        content: [
          { text: "Financial Report", style: "header" },
          { image: chartImage, width: 500 },
          htmlToPdfmake(printContent),
        ],
        styles: {
          header: {
            fontSize: 18,
            bold: true,
            margin: [0, 0, 0, 10],
          },
        },
      };

      pdfMake.createPdf(docDefinition).download("financial_report.pdf");
    }
  } catch (error) {
    console.error("Failed to generate PDF:", error);
  }
};

We'll also import a useRef hook at the top of our file and use this hook to get a reference to the chart section in the DOM, like this:
const chartRef = useRef(null);
Here's how we'll add the ref to the 'Chart' Section:

<section ref={chartRef}>
  {chartType === "bar" ? (
    <BarChart categories={categories} amounts={amounts} />
  ) : (
    <PieChart categories={categories} amounts={amounts} />
  )}
</section>;

We'll then include the button to export the report as a PDF. This button will call the printReport function:

<button onClick={printReport}>
  Export as PDF
</button>

Save the file and refresh the webpage.

Now, when we generate a report by clicking the "Generate report" button, our budget report is generated along with an "Export as PDF" button. When we click this button, our report will be exported as PDF, and it will automatically download the report as PDF to your system.

Feel free to style your report in any way you want it to appear in the PDF inside the printReport function.

If we want to download a copy of the report with the pie chart instead of the bar chart, we'll switch the chart type to 'pie chart' on the web page. Click the "Generate report" button again and export.

If we want to enable cashflow statement report generation for the income and expenses, we'll follow the same steps and export it the same way.

This is the GitHub repo for this article.

Series Wrap Up

In this "Build a Finance Tracker with Next.js, Strapi, and Chart.js" blog series, here's a summary of what we learned:

How to set up Strapi, build the frontend UI, connect the frontend to Strapi, and implement the CRUD functionalities for the data.
How to integrate Chart.js to create charts/visuals of our financial budget data.
How to authenticate users and configure the Strapi backend to implement a personalized report feature.
How to print and export generated reports.

This app can be used by individuals hoping to manage their finances, observe their spending habits, track their financial data, and get a simplified report of their finances.

I hope you enjoyed this series and were able to code along with me and build your own finance tracker application.

Build a Finance Tracker with Next.js, Strapi, and Chartjs: Part 2

Juliet Ofoegbu — Tue, 06 Aug 2024 07:09:53 +0000

This is a continuation of Part 1 of our blog series. It's advisable to read Part 1 to understand how we got to this stage.

Tutorial Outline

For reference, here's the outline of this blog series:

Part 1: Build a finance tracker app - Setting up Strapi & implementing the app's CRUD functionalities.
Part 2: Adding visualization with charts
Part 3: Setting up user authentication and personalized reporting

In this, we'll learn how to visualize the financial data we dealt with in the previous part using Chart.js. We want to view our financial data using bar charts and pie charts.

Introduction to Data Visualization

Why is it important to visualize financial data?
Visualizing financial data is essential for several reasons such as:

It provides clarity. When complex, we visually represent using charts and graphs, which makes it easier to understand than plain text.
It helps track financial goals and monitors progress over time. They provide a clear view of budgets, income, expenses, and overall financial health.
Visualization helps identify trends in income and spending, which can help you make informed decisions about your finances.

Overview of Chart.js

Chart.js is a flexible and easy-to-use open-source JavaScript library for creating charts and graphs. It is easy to use and provides a simple API for creating different types of charts with a few lines of code.

Chart.js offers customization options, allowing users to style charts to meet their specific requirements. It also has built-in support for animations.

Install Chart.js in the Next.js Project

To visualize our application's budget data, we'll use two charts (a bar chart and a pie chart).

To get started, let's install the Chart.js library using this command:
```
npm install chart.js
```
We'll also install the chartjs-plugin-datalabels plugin. This plugin allows us to display custom labels inside or outside chart elements, like pie slices. We'll be using it specifically for the pie chart.
```
npm install chartjs-plugin-datalabels
```
Since we'll be using two charts, let's create two components for the charts inside our budget folder, located inside the dashboard folder. We'll name them - BarChart.tsx and PieChart.tsx.

Prepare the `Overview.tsx` Component for Receiving Chart Data

If you recall, or you can refer back to Part 1 of this series, you'll see how the Overview component is structured. We'll need to add a few things to implement this visualization feature.

Let's modify our Overview component to fetch the budget data from Strapi CMS and display the charts.
Here's how we'll do it:

First, we'll import the hooks we'll be using. We'll import the Axios library and then the two newly created components in our Overview.tsx component.

"use client";
import React, { useState, useEffect } from "react";
import axios from "axios";
import BarChart from "./budget/BarChart";
import PieChart from "./budget/PieChart";

We'll create states to store the budget and chart data types. The states will enable users to select which chart visual they want to view (bar chart or pie chart), the default being bar chart:
```
const [budgets, setBudgets] = useState<{ category: string; amount: number }[]>(
[],
);
const [chartType, setChartType] = useState<"bar" | "pie">("bar");
```
We'll implement the useEffect hook to take two arguments. The first argument is a function that runs as the side effect and an empty dependency array. This dependency array will only run once when the component mounts.
```
useEffect(() => {
 ...
}, []);
```
Inside the useEffect hook, we'll create a fetchBudgets asynchronous function to fetch the budget data from the API. Using the Axios library, we'll send a GET request to the budget API endpoint.
The response res will contain the data property of the budget data. Then, we'll use the map array method to iterate over each budget item and create a new array of objects containing only the category and amount properties.
The setBudgets(data) will then update the budget state with the fetched and mapped data.

const fetchBudgets = async () => {
  try {
    const res = await axios.get(
      "http://localhost:1337/api/budgets?populate=budget",
    );
    const data = res.data.data.map((budget: any) => ({
      category: budget.attributes.category,
      amount: budget.attributes.amount,
    }));
    setBudgets(data);
  } catch (error) {
    console.error("Error fetching budgets:", error);
  }
};

fetchBudgets();

We'll call the fetchBudgets function after defining it within the useEffect hook.

After that, we will store the budget category and amount inside variables categories and amounts:

const categories = budgets.map((budget) => budget.category);
const amounts = budgets.map((budget) => budget.amount);

Visualize Budget Categories With Bar Chart

It's time to write the functionalities to create these charts.

We will navigate to the BarChart.tsx component.

We'll first import the necessary hooks and the chart.js library. We'll use the auto package to ensure all features from chart.js are available.
```
import React, { useEffect, useRef } from "react";
import Chart from "chart.js/auto";
```
We'll define an interface for the props expected by the component - arrays for categories and amounts.
```
interface BarChartProps {
categories: string[];
amounts: number[];
}
```
The BarChart component will take categories and amounts as props. We will create a chartRef function to reference the canvas element, which we will soon create to represent the Chart.js instance.
```
const BarChart: React.FC<BarChartProps> = ({ categories, amounts }) => {
const chartRef = useRef<HTMLCanvasElement | null>(null);
```

Using the useEffect hook, we'll create the chart when the component mounts or when the categories and amounts props change:

useEffect(() => {
if (chartRef.current) {
const chartInstance = new Chart(chartRef.current, {
  type: "bar",
  data: {
    labels: categories,
    datasets: [
      {
        label: "Budget Amount",
        data: amounts,
        backgroundColor: [
          "rgba(75, 192, 192, 0.2)",
          "rgba(54, 162, 235, 0.2)",
          "rgba(153, 102, 255, 0.2)",
        ],
        borderColor: [
          "rgb(75, 192, 192)",
          "rgb(54, 162, 235)",
          "rgb(153, 102, 255)",
        ],
        borderWidth: 1,
      },
    ],
  },
  options: {
    scales: {
      y: {
        beginAtZero: true,
      },
    },
    plugins: {
      title: {
        display: true,
        text: "Budget data - bar chart",
        padding: {
          top: 10,
          bottom: 30,
        },
      },
    },
  },
});

return () => {
  chartInstance.destroy();
};
}
}, [categories, amounts]);

return ;


- In the `useEffect` function above, we added the `if (chartRef.current)` to ensure that the chart is only created if the canvas element is available.

- The `new Chart(chartRef.current, { ... })` creates a new Chart.js instance with the specified type, data, and options.

- `type: 'bar'` specifies that the chart is a bar chart.

- The `data` object contains the chart's labels (`categories`) and datasets (`amounts`), including the label, data, and bar colors.

- The `options` object is the configuration options for the chart, such as making the y-axis start at zero. The `plugins` object inside the `options has a property for setting a title for the chart.

- The `return () => { chartInstance.destroy(); }` statement cleans up the chart instance when the component unmounts or updates.


- Lastly, the `<canvas ref={chartRef} />` renders a canvas element with a `ref` to attach the Chart.js instance.



## Visualize Budget Categories With Pie Chart
For our pie chart, we want to view the percentage each budget category is taking, e.g., 20% for savings, 40% for food, etc.

We will head over to the `PieChart.tsx` component and perform the following updates.

- Similar to the `BarChart` component, we'll start by importing the necessary hooks and dependencies:
```javascript
import React, { useEffect, useRef } from 'react';
import Chart from 'chart.js/auto';
import ChartDataLabels from 'chartjs-plugin-datalabels';

We'll include this method from the chartjs-plugin-datalabels plugin:
```
Chart.register(ChartDataLabels);
```
We'll then define the interface for the props expected by the component - arrays for categories and amounts.
```
interface PieChartProps {
categories: string[];
amounts: number[];
}
```
Next, we'll define the PieChart component. It will take categories and amounts as props. Then, we'll define the chartRef: Ref function to reference the canvas element.
```
const PieChart: React.FC<PieChartProps> = ({ categories, amounts }) => {
const chartRef = useRef<HTMLCanvasElement | null>(null);
```

Next, we initialize the chart inside a useEffect hook like this:

useEffect(() => {
if (chartRef.current) {
const totalAmount = amounts.reduce((acc, amount) => acc + amount, 0);

const chartInstance = new Chart(chartRef.current, {
  type: "pie",
  data: {
    labels: categories,
    datasets: [
      {
        label: "Budget Amount",
        data: amounts,
        backgroundColor: [
          "rgba(255, 99, 132, 0.6)",
          "rgba(54, 162, 235, 0.6)",
          "rgba(255, 206, 86, 0.6)",
          "rgba(75, 192, 192, 0.6)",
          "rgba(153, 102, 255, 0.6)",
          "rgba(255, 159, 64, 0.6)",
        ],
        borderColor: [
          "rgba(255, 99, 132, 1)",
          "rgba(54, 162, 235, 1)",
          "rgba(255, 206, 86, 1)",
          "rgba(75, 192, 192, 1)",
          "rgba(153, 102, 255, 1)",
          "rgba(255, 159, 64, 1)",
        ],
        borderWidth: 1,
      },
    ],
  },
  options: {
    responsive: true,
    maintainAspectRatio: false,
    plugins: {
      title: {
        display: true,
        text: "Budget data - pie chart",
        padding: {
          top: 10,
          bottom: 30,
        },
      },
      datalabels: {
        color: "white",
        formatter: (value, context) => {
          const percentage = ((value / totalAmount) * 100).toFixed(2);
          return `${percentage}%`;
        },
      },
    },
  },
});

return () => {
  chartInstance.destroy();
};
}
}, [categories, amounts]);

We initialized the useEffect hook and added a totalAmount function to calculate the percentage of each category compared to other categories.
Just like the bar chart, the type: 'pie' specifies that the chart is a pie chart.
The backgroundColor and borderColor arrays specify the colors for the pie chart segments.
The options: { responsive: true } object makes the pie chart responsive. We added the maintainAspectRatio: false in the options object to ensure that the chart does not maintain the default aspect ratio and can scale to the size of its container.

NOTE: The default size can be quite large and take up a lot of space on your page, so you can set width and height to reduce pie chart size.
The title property inside the plugins object sets the title display to true, which displays the chart's title.
The datalabels object contains each category's percentage values and sets the percentage text's color to white.
We returned the canvas element by wrapping the canvas element in a div element with specific width and height styles.
We gave the canvas element width and height attributes to set its width and height.

return (
  <div style={{ marginTop: "15px", width: "700px", height: "700px" }}>
    <canvas
      ref={chartRef}
      width="700"
      height="700"
      aria-label="Hello ARIA World"
      role="img"
    />
  </div>
);

You can adjust your chart size any way you want it to look.

Render the Pie and Bar Charts in the Overview Page

We've modified the overview page by preparing it for the charts and writing the code. Now, we need to display the charts on the overview page.

In the JSX of our Overview.tsx component, we'll render the UI:

<main>
  <div>
    <section>
      <h2>OVERVIEW</h2>
      <div>
        <button
          onClick={() => setChartType("bar")}
          className={`mx-2 py-2 px-3 ${chartType === "bar" ? "bg-teal-500 text-white" : "bg-gray-200 text-gray-700"} rounded-lg`}
        >
          Bar Chart
        </button>
        <button
          onClick={() => setChartType("pie")}
          className={`mx-2 py-2 px-3 ${chartType === "pie" ? "bg-teal-500 text-white" : "bg-gray-200 text-gray-700"} rounded-lg`}
        >
          Pie Chart
        </button>
      </div>
    </section>
    <section className="mt-8">
      {chartType === "bar" ? (
        <BarChart categories={categories} amounts={amounts} />
      ) : (
        <PieChart categories={categories} amounts={amounts} />
      )}
    </section>
  </div>
</main>;

We created a div element with two buttons. Each button has an onClick handler that sets the chart type to either 'bar' or 'pie.'
The buttons are styled based on the current chartType state, representing the type we want to display.
The page then conditionally renders either the BarChart or PieChart component based on the current value of chartType.
If chartType is 'bar', the BarChart component is rendered. If chartType is 'pie', the PieChart component is rendered.
Both components receive categories and amounts as props to display the data.

Now our charts are ready.

Here's what our bar chart should look like:

Here's what our pie chart should look like:

If we edit a budget item from the budget page, like the category it falls under or the amount, the charts will adjust to match the new budget value.

Items and values will be dynamically added to the charts if we add more budgets via the budget page. Change the background and border colors and play around with the values.

Add Animation to the Charts

Let's add a little animation to our charts.

First, in the bar chart, we'll add the easeOutElastic animation property.

To do this, we'll include another property in the options object called animation. This property will be an object with two values - duration and easing. javascript animation: { duration: 6000, // Increase or decrease the duration easing: 'easeOutElastic', // Using the easing function },

We set the duration to 6000 milliseconds (6 seconds) to make the animation slower and more noticeable. When our visualization loads, the bars elasticate for 6 seconds before setting to their proper position.

In the pie chart, we'll add a bouncing animation using the easeOutBounce property.

We'll include the animation property inside the options object with two values to do this. javascript animation: { duration: 6000, easing: 'easeOutBounce', },

Animation Demo

When we load our page, we'll see the bar chart's elastic animation and the pie segments' bouncing animation.

More Animations?

Check out the chart.js documentation site for a full list of other animations and transitions you can add to the charts.

We can use other charts to visualize financial data, but we will only use bar and pie charts for this article. If you're interested in exploring more visualizations with Chart.js, check out other chart types.

You can apply this concept to visualize other parts of your application. For example, you can visualize expenses for a few months to see how much you spent in a particular month compared to other months.

This is useful for making financial decisions and identifying trends.

Conclusion

In Part 2 of this tutorial series, we reviewed an overview of charts, set up Pie and Bar charts in Next.js using Chart.js and Strapi CMS, prepared them for data, added animation, and rendered them.

This project's GitHub repo has been updated to include financial data visualization.

Watch for the last part (part 3) of this blog series, where we'll add authentication and a personalized reporting feature to our finance tracker application.

Build a Finance Tracker with Next.js, Strapi, and Chartjs: Part 1

Juliet Ofoegbu — Fri, 02 Aug 2024 09:12:41 +0000

Introduction

This is part one of this blog series, where we'll learn to set up the Strapi backend with collections, create the app's user interface, connect it to Strapi CMS, and implement the functionalities for budget, income, and expenses to build a finance tracker application.

For reference, here's the outline of this blog series:

Part 1: Setting up Strapi & implementing the app's CRUD functionalities.
Part 2: Adding visualization with charts.
Part 3: Setting up user authentication and personalized reporting.

Prerequisites

Before we dive in, ensure you have the following:

NodeJs installed on your local machine.
Basic understanding of Next.js and CRUD operations. You can check out the Epic Next.js 14 Tutorial Part 1: Learn Next.js by building a real-life project.
Experience with RESTful APIs. You can check out Strapi's REST APIs docs.
Ensure you have a good knowledge of Tailwind CSS. You will be using it to style the front-end of this page based on your preference.

Technologies

You will learn how to use and implement these JavaScript libraries.

Chart.js for building charts visualization of the financial data
html-to-pdfmake for generating PDF from HTML content.
pdfmake for generating PDFs for both client-side and server-side
html2canvas to take screenshots of the webpage directly on the browser.

Tutorial Objectives

The following are the objectives of this tutorial:

Learn about the full-stack development process.
Set up backend with Strapi.
Master frontend development using Next.js for interface.
Visualizing financial data.
Setting up user authentication.
Adding a personalized financial report feature that users can export.

What We Are Building

In this tutorial, we will build a Finance Tracker app. This app is designed to help individuals or organizations monitor and manage their financial activities. It lets users record and track budgets, income, expenses, and other financial transactions.

Why is a Finance Tracker Application Useful?

A finance tracker app is helpful because:

It helps users become more aware of their spending habits and financial status.
It helps users set and stick to budgets.
It helps users set financial goals, e.g., car savings.

These are just a few practical uses of a finance tracker application.

Project Overview

At the end of this tutorial, we can create budgets, manage income and expenses through the app, visualize their data, and use advanced features like authentication and personalized financial reports.

App overview:

First, let's set up the Strapi backend and implement the logic for managing budgets, income, and expenses.

Setting Up Strapi Backend

In this section, we'll set up Strapi as the backend platform for storing financial data (budget, income, and expenses). Strapi will aslo serve as our RESTful API.

Create Project Directory

Create a directory for your project. This directory will contain the project's Strapi backend folder and the Next.js frontend folder.

mkdir finance-tracker && cd finance-tracker

Create a Strapi Project

Next, you have to create a new Strapi project, and you can do this using this command:

npx create-strapi-app@latest backend --quickstart

This will create a new Strapi application in the finance-tracker directory and install necessary dependencies, such as Strapi plugins.

After a successful installation, your default browser automatically opens a new tab for the Strapi admin panel at "http://localhost:1337/admin." Suppose it doesn't just copy the link provided in the terminal and paste it into your browser.

Fill in your details on the form provided and click on the "Let's start" button.

Your Strapi admin panel is ready for use!

Create Collection Type and Content Types

If you click on the 'Content-Type Builder' tab at the left sidebar, you'll see that there's already a collection type named 'User'. Create a new collection type by clicking on the "+ Create new collection type". After that, proceed to create the following collections:

Collection 1 - Budgets Create a new collection called Budget.

These are the fields we'll need for this collection. So go ahead and create them:

Field Name	Data Type
`category`	Enumeration
`amount`	Number

In the category field above, which is an Enumeration type, provide the following as shown in the image below:

food
transportation
housing
savings

Click the 'Finish' button, and your Budget collection type should now look like this:

Ensure to click the 'Save' button and wait for the app to restart the server.

Collection 2 - Incomes Follow the same steps you did to create the first collection above. Name this collection Incomes. The fields you'll need for this collection are:

Field Name	Data Type
`description`	Text - Short text
`amount`	Number

Collection 3 - Expenses Create another collection called Expenses. The fields you'll need for this collection are:

Field Name	Data Type
`description`	Text - Short text
`amount`	Number

Create Entries

Fill in the amount field and choose an option for the category field. Save it and then hit the 'Publish' button to add the entry.

NOTE: They are saved as drafts by default, so you need to publish it to view it.

Do the same for the other two collections. Create entries for each of their respective fields, save, and publish.

Set API Permissions

The last step of setting up our Strapi backend is to grant users permission to create, find, edit, and delete budgets in the app. To do this, go to the Settings > Roles > USERS & PERMISSIONS PLUGIN section. Select Public.

Toggle the 'Budgets' section and then check the 'Select all' checkbox. By checking this box, we will allow users to perform CRUD operations. Save it.

Toggle the 'Incomes' and 'Expenses' sections and check the 'Select all' checkbox to grant users access to perform CRUD operations on these collections.

Don't forget to save it.

That is all for the Strapi backend configuration. Let's move on to the frontend.

Creating the User Interface with Next.js

Using Next.js, we'll build the frontend view that allows users to view and manage their budget, income, and expenses. It'll also handle the logic and functionalities.

Testing the API Endpoints from Strapi

To ensure that the RESTful API endpoints from Strapi are all working well, paste the endpoints into your browser so you can see the entries you created.
For the first collection Budgets, paste the URL "http://localhost:1337/api/budgets" in your browser.

You'll get this:

We will do the same for the income endpoint "http://localhost:1337/api/incomes", and the expenses endpoint at "http://localhost:1337/api/expenses" to see their respective entries.

If we can view the entries, it means our endpoints are ready to be used.

Create a New Next.js Application

Go to your root directory /finance-tracker. Create your Next.js project using this command:

npx create-next-app frontend

When prompted in the command line, choose to use 'Typescript' for the project. Select 'Yes' for the ESLint, 'Yes' to use the src/ directory, and 'Yes' for the experimental app directory to complete the set-up. This selection will create a new Next.js app.

Navigate to the app you just created using the command below:

cd frontend

Install Dependencies

Next, install the necessary JavaScript libraries or dependencies for this project:

Axios: Axios is a JavaScript library used to send asynchronous HTTP requests to REST endpoints. It's commonly used to perform CRUD operations. Install Axios using this command:

npm install axios

Tailwind CSS: We'll be using this CSS framework to style our application. Install Tailwind CSS and then run the init command to generate both tailwind.config.js and postcss.config.js.

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

React Icons: A package to include icons in your project.

npm i react-icons

date-fns: This is a JavaScript date library to ensure consistent date and time formatting in an application. We'll be using it to format the date entries are made.

Install using the command:

npm install date-fns

Start the Next.js App

We'll start up the frontend app with the following command:

npm run dev

View it on your browser using the link "http://localhost:3000".

Folder Structure

Here's an overview of the complete folder structure:

src/
┣ app/
┃ ┣ dashboard/
┃ ┃ ┣ budget/
┃ ┃ ┃ ┣ Budget.tsx
┃ ┃ ┃ ┣ BudgetForm.tsx
┃ ┃ ┃ ┗ page.tsx
┃ ┃ ┣ cashflow/
┃ ┃ ┃ ┣ expense/
┃ ┃ ┃ ┃ ┣ Expense.tsx
┃ ┃ ┃ ┃ ┗ ExpenseForm.tsx
┃ ┃ ┃ ┣ income/
┃ ┃ ┃ ┃ ┣ Income.tsx
┃ ┃ ┃ ┃ ┗ IncomeForm.tsx
┃ ┃ ┃ ┣ Cashflow.tsx
┃ ┃ ┃ ┗ page.tsx
┃ ┃ ┗ Overview.tsx
┃ ┣ globals.css
┃ ┣ head.tsx
┃ ┣ layout.tsx
┃ ┗ page.tsx
┣ components/
┃ ┗ SideNav.tsx

Our app will have a dashboard interface where users can view and manage their budget, income, and expenses. Let's list out the folders and components we'll be needing for the layout:

We'll work mainly with two folders, some sub-folders, and some files for this project. So, we'll create some folders inside the app directory.
We'll create a components folder inside the src directory and a new file called SideNav.tsx inside it.
In the app directory, we'll create a folder called dashboard with two subfolders.

The first subfolder, budget, will contain three component files named page.tsx, BudgetForm.tsx, and Budget.tsx. This is the folder where the routing for the budget page will be located.

The second subfolder, cashflow, will also contain two folders and two component files: page.tsx and Cashflow.tsx. This is the folder where the routing for the cash-flow (income & expenses) page will be located.

The two folders inside this cashflow folder should be named expense and income for easy identification. The expense folder will contain two components: Expense.tsx and ExpenseForm.tsx.

The same is true for the income folder. It should have two components: Income.tsx and IncomeForm.tsx.
Next, Create an Overview.tsx file inside the dashboard folder. This component will be the dashboard page route. It will be used sparingly in this part, but it'll come in handy later on.
The last component file we'll work with is the page.tsx component, located directly inside the app folder. This component is the main application component.

Integrating with Strapi

In this section, we get to the main task of integrating the data from Strapi into the frontend.

Fetching Data from Strapi API and Displaying Budget Info

Let's fetch the data entries from the Strapi collections we created and display them on the frontend page.

We'll start with the 'Budget' information, but first, let's create the page layout.

Layout of the Overall Application

The Overview.tsxpage will be the first one as it's the first route. It won't be useful now, but we'll write the JSX for it like this:

import React from 'react'

const Overview = () => {
    return (
        <>
          <main>
                <div>
                    <p>Overview</p>
                </div>
            </main>
        </>
    )
}

export default Overview

Note: I'll be omitting the styling so that it won't take up too much space here. It will be available in the GitHub repo I'll provide at the end of this article.

Building the Side Navigation View

Next up is the SideNav.tsx component, where the page's routing will be located.

'use client'
import Link from "next/link";
import { FaFileInvoice, FaWallet } from "react-icons/fa";
import { MdDashboard } from "react-icons/md";
import { usePathname } from 'next/navigation';

const SideNav = () => {
    const pathname = usePathname();

    return (
        <div>
            <section>
                <p>Tracker</p>
            </section>

            <section>
                <Link href="/" >
                    <section>
                        <MdDashboard />
                        <span>Overview</span>
                    </section>
                </Link>
            </section>

            <section>
                <Link href="/dashboard/budget">
                    <section>
                        <FaFileInvoice />
                        <span>Budget</span>
                    </section>
                </Link>
            </section>

            <section>
                <Link href="/dashboard/cashflow">
                    <section>
                        <FaWallet />
                        <span>Cashflow</span>
                    </section>
                </Link>
            </section>
        </div >
    );
};

export default SideNav;

Rendering the Layout Components

For the final layout of the main app, we'll render the two components we worked on recently. Locate the pages.tsx component inside the app directory and paste these lines of code:

import SideNav from '@/components/SideNav'
import Overview from './dashboard/Overview'

const page = () => {
    return (
        <>
          <div>
            <SideNav />
            <div>
                <Overview />
            </div>
          </div>
        </>
    )
}

export default page

This is how the page layout should look like after styling:

When we click the "Budget" tab, we'll be directed to the budget page. When we click the "Cashflow" tab, we'll be directed to the cashflow (income & expenses) page.

Building the `Budget` Page

The budget folder is where all components related to the budget page will be located.

In the Budget.tsx file of our budget folder located in dashboard directory, build the budget page layout:

Import the library and hooks we'll be using:

'use client'
import React, { useEffect, useState } from 'react';
import axios from 'axios';

Set the Budget TypeScript interface to define the structure of the budget object:

interface Expense {
id: number;
attributes: {
    category: string;
    amount: number;
};
}

Set the state as an array to store the budgets we'll fetch from the Strapi backend:
```
const [budgets, setBudgets] = useState<Budget[]>([]);
```
Use the useEffect hook to fetch budgets when the component mounts using the fetch() API. The fetched data is stored in the budgets state we set above.
An error will be thrown if the data response fails. If it's successful and passed as JSON, the function then checks to see if it's an array.
If it is, then we'll be able to map through it to render and display the budget data. It then saves this data in the budget state, else it logs an error.

useEffect(() => {
    const fetchBudgets = () => {
        fetch("http://localhost:1337/api/budgets?populate=budget")
            .then((res) => {
                if(!res.ok) {
                  throw new Error("Network response was not ok");
                }
                return res.json();
            })
            .then((data) => {
                console.log("Fetched budgets:", data);
                if (Array.isArray(data.data)) {
                    setBudgets(data.data);
                } else {
                    console.error("Fetched data is not an array");
                }
            })
            .catch((error) => {
                console.error("Error fetching budgets:", error);
            });
       };

   fetchBudgets();
}, []);

We'll use the map method to map through the array and render each budget individually on the page, like this:

<section>
    {budgets.length === 0 ? (
        <>
          <div>
             <p>You haven't added a budget..</p>
          </div>
        </>
    ) : (
        <>
          <article>
              {budgets.map((budget) => (
                  <article key={budget.id}>
                      <section>
                         <p>{budget.attributes.category}</p>
                         <span>Budget planned</span>
                         <h1>${budget.attributes.amount}</h1>
                      </section>
                 </article>
             ))}
         </article >
       </>
    )}
</section>

After styling this page, this is what it looks like now:

We've successfully fetched the budget data from the Strapi backend and displayed it on the frontend page. Great!

Building the Modal for the Budget Form

This will be an interactive application, meaning users will be able to interact with the app and add new budgets to the endpoint. To enable the creation of new budgets, we want a modal to open up when we perform an action (click a button).

Inside this modal, there will be a form where we must fill in the details necessary to create a new budget. The field names will be the same as the ones we created (category and amount) when we set up the collection for the budgets in Strapi.

We also want to be able to edit any budget data. The form for editing a budget will be the same as the one for creating a new budget, so let's make the form modal component.

Open the BudgetForm.tsx component in the budget folder.

First, we'll import the necessary libraries, hooks, and the Budget component:

'use client';
import React, { ChangeEvent, useEffect, useReducer, useState } from 'react';
import axios from 'axios';
import Budget from './Budget';

Next, we'll define the BudgetFormProps interface by passing in three props. The first one, onClose, will close the form. The second prop, setBudgets will update the budgets state in the parent component (Budget.tsx component). The third one selectedBudget will select a budget that's being edited or set it to null.

interface BudgetFormProps {
   onClose: () => void;
   setBudgets: React.Dispatch<React.SetStateAction<Budget[]>>;
   selectedBudget: Budget | null;
}

We'll pass these props into this component so that they can be used by other components:

const BudgetForm: React.FC<BudgetFormProps> = ({ 
onClose, 
setBudgets, 
selectedBudget
}) => {
// Other functionalities
}

Then, we'll define the initialState object to set the initial states (values) for the form fields.

const initialState = {
   category: 'food',
   amount: 0,
};

Next is the reducer function that will update the state based on the field and value provided to handle form field updates. Then we'll use the useReducer hook to manage the form fields state, initializing it with the initialState object.

function reducer(state = initialState, { field, value }: { field: string, value: any }) {
   return { ...state, [field]: value };
}

const [formFields, dispatch] = useReducer(reducer, initialState);

We'll define the useEffect function that pre-fills the form when the user wants to edit budget data. It runs whenever the selectedBudget changes. It will populate the form fields with the budget data if there is a selected budget. If there is no selected budget, the form fields are reset to their initial values. The [selectedBudget] dependency array ensures this effect runs only when selectedBudget changes.

useEffect(() => {
     if (selectedBudget) {
         for (const [key, value] of Object.entries(selectedBudget?.attributes)) {
             dispatch({ field: key, value });
         }
     } else {
         for (const [key, value] of Object.entries(initialState)) {
             dispatch({ field: key, value });
         }
     }
}, [selectedBudget]);

We'll then define a handleInputChange function that will handle changes to the form input fields and update the corresponding state fields. It will destructure name and value from the event target and then dispatch an action to update the state field corresponding to the name with the new value.

const handleInputChange = (e: ChangeEvent<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>) => {
    const { name, value } = e.target;
    ispatch({ field: name, value });
};

We'll create another function -handleSendBudget. This function will handle the logic for sending a budget to the Strapi backend. It will send a POST request to create a new budget or a PUT request to update an existing one. It will first extract the necessary budget details from formFields and then check if there is a selected budget.

const handleSendBudget = async () => {
    try {
        const { category, amount } = formFields;

        if (selectedBudget) {
           // Update an existing budget field
           const data = await axios.put(`http://localhost:1337/api/budgets/${selectedBudget.id}`, {
                data: { category, amount },
            });
            console.log(data)
            setBudgets((prev) => prev.map((inv) => (inv.id === selectedBudget.id ? { ...inv, ...formFields } : inv)));
            window.location.reload()
          } else {
            // Create a new budget
            const { data } = await axios.post('http://localhost:1337/api/budgets', {
                data: { category, amount },
             });
             console.log(data);
             setBudgets((prev) => [...prev, data.data]);
          }
          onClose();
     } catch (error) {
          console.error(error);
     }
};

Let's now render the form UI.

<form>
    <h2>{selectedBudget ? 'Edit Budget' : 'Create Budget'}</h2>
    <button onClick={onClose}>
        &times;
    </button>

    <div>
        <div>
            <label htmlFor="category">
                Budget category
            </label>
            <select
               id="category"
               name="category"
               value={formFields.category}
               onChange={handleInputChange}
            >
               <option value="food">Food</option>
               <option value="transportation">Transportation</option>
               <option value="housing">Housing</option>
               <option value="savings">Savings</option>
               <option value="miscellaneous">Miscellaneous</option>
            </select>
         </div>

         <div>
             <label htmlFor="amount">
                 Category Amount
             </label>
             <input
                 id="amount"
                 name="amount"
                 type="number"
                 placeholder="Input category amount"
                 onChange={handleInputChange}
                 value={formFields.amount}
                 required
              />
         </div>

         <button
             type="button"
             onClick={handleSendBudget} >
             {selectedBudget ? 'Update Budget' : 'Add Budget'}
         </button>
    </div>
</form>

After styling our form as desired, here's how it might look like:

Implement Create/Edit Functionalities in The 'Budget' Component

We have to implement the creation and edit functionalities in the parent component, Budget.tsx.

Let's first import the form component and some icons from react-icons.

import BudgetForm from './BudgetForm';
import { FaEdit, FaTrash } from 'react-icons/fa';

We'll create two states. The first one isBudgetFormOpen, will store the state of the budget form component - if it's opened or closed(default). The second one, selectedBudget will store the state of any selected budget.

const [isBudgetFormOpen, setIsBudgetFormOpen] = useState(false);
const [selectedBudget, setSelectedBudget] = useState<Budget | null>(null);

We'll then create two functions - handleOpenBudgetForm and handleCloseBudgetForm to handle the opening and closing of the form modal.

const handleOpenBudgetForm = () => {
    setSelectedBudget(null);
    setIsBudgetFormOpen(true);
};

const handleCloseBudgetForm = () => {
    setSelectedBudget(null);
    setIsBudgetFormOpen(false);
};

Let's add a button to open the form modal:

<button onClick={handleOpenBudgetForm}>
    Add a budget
</button>

Now, let's define the handleEditBudget function that will open the form and pre-populate the fields with the selected budget's data for editing. It will set the selectedBudget to the budget that we want to edit. It will also open the form by setting isBudgetFormOpen to true.

const handleEditBudget = (budget: Budget) => {
    console.log("Editing:", budget);
    setSelectedBudget(budget);
    setIsBudgetFormOpen(true);
};

Let's go ahead and add an onClick event for the handleEditBudget function in a button in the JSX:
```
<span>
<FaEdit onClick={() => handleEditBudget(budget)} />
</span>
```
Conditionally, we'll render the form component at the bottom of the 'Budget' component:

{isBudgetFormOpen && (
    <BudgetForm
        onClose={handleCloseBudgetForm}
        setBudgets={setBudgets}
        selectedBudget={selectedBudget}
    />
)}

Implement the Delete Functionality

The last functionality for the CRUD operation is the delete functionality.

Let's create a handleDeleteBudget function that will delete a budget data by selecting its id and sending a DELETE request to the API. This ,will remove or filter out the deleted budget from the budget state.

const handleDeleteBudget = async (id: number) => {
    try {
       alert("Are you sure you want to delete this budget?")
       await axios.delete(`http://localhost:1337/api/budgets/${id}`);
       setBudgets(budgets.filter((budget) => budget.id !== id));
    } catch (error) {
       console.error(error);
    }
};

Now, we'll add an onClick event for the handleDeleteBudget function in the trash icon in the JSX:
```
<span>
<FaTrash onClick={() => handleDeleteBudget(budget.id)} />
</span>
```
We'll then render both the SideNav.tsx component and the Budget.tsx component on the main page. Go to the page.tsx component located in the budget folder and paste this:

import SideNav from '@/components/SideNav'
import Budget from './Budget'

const page = () => {
  return (
    <>
      <div>
          <SideNav />

           <div>
              <Budget />
          </div>
      </div>
    </>
  )
}
export default page

When we go to our browser, we'll see the changes made.

This is how it should look after styling:

This is functional now. The 'create', 'edit', and 'delete' functionalities should work as expected.

Fetching Data from Strapi API to Display the Expenses

The cash flow page code will be similar to the code you used to create the budget page. It will be a single page, 'Cashflow', but will render the income and expenses pages.

Remember the cashflow folder we created at the beginning of this tutorial, that has 2 sub-folders (expense and income)?, we'll open it up.

Building the Expenses Form Modal

Locate the ExpenseForm.tsx component inside the expense folder, and we'll paste these lines of code into it.

We'll first import the necessary libraries: useState and useEffect to manage state and side effects and Axios to make HTTP requests.
```
import React, { useState, useEffect } from 'react';
import axios from 'axios';
```
We'll then define the TypeScript interface ExpenseFormProps. This interface will specify the props the component expects. isOpen determines if the form is open, the onClose function closes the form, expense is the expense to be edited or null, and refreshCashflow is a function to refresh the cashflow column.
```
interface ExpenseFormProps {
isOpen: boolean;
onClose: () => void;
expense: { id: number, attributes: { description: string, amount: number } } | null;
refreshCashflow: () => void;
}
```

We'll declare the ExpenseForm component and initialize state variables description and amount for the two input fields we'll need.

const ExpenseForm: React.FC<ExpenseFormProps> = ({ isOpen, onClose, expense, refreshCashflow }) => {
const [description, setDescription] = useState('');
const [amount, setAmount] = useState<number>(0);

We'll then implement the useEffect hook to update the form fields when expenses change. If expense is not null, it will populate the fields with its attributes. If it is null, it will reset the fields.

useEffect(() => {
if (expense) {
 console.log("Editing expense:", expense);
 setDescription(expense.attributes.description);
 setAmount(expense.attributes.amount);
} else {
 setDescription('');
 setAmount(0);
}
}, [expense]);

Next, we'll define a handleSubmit function to handle the form submission. If an expense exists, we'll update it using the PUT request; otherwise, we'll create a new expense using the POST request. Refresh the cash flow page after the change and close the form after the request.

const handleSubmit = async (e: React.FormEvent) => {
e.preventDefault();

const expenseData = { description, amount };

try {
    if (expense) {
        await axios.put(`http://localhost:1337/api/expenses/${expense.id}`, { data: expenseData });
    } else {
        await axios.post('http://localhost:1337/api/expenses', { data: expenseData });
    }
    refreshCashflow();
    onClose();
} catch (error) {
    console.error('Error submitting expense:', error);
}
};

If the form is not open, it will return null to prevent rendering.
```
if (!isOpen) return null;
```
Let's go ahead and render the modal form UI. We'll add input fields for the description and the amount with their corresponding labels. The form submission will be handled by handleSubmit function.

As part of the modal form rendering, we will add a submit button with conditional text based on whether an expense is being edited or created.

<form onSubmit={handleSubmit}>
    <h2>
        {expense ? 'Edit Expense' : 'Add Expense'}
    </h2>
    <button
        onClick={onClose}>
        &times;
    </button>

    <div>
        <div >
            <label htmlFor="description">
                Description
            </label>
            <input
                id="description"
                name="description"
                type="text"
                placeholder="Input description"
                value={description}
                onChange={(e) => setDescription(e.target.value)}
                required
            />
        </div>

        <div>
            <label htmlFor="amount">
                Category Amount
            </label>
            <input
                id="amount"
                name="amount"
                type="number"
                placeholder="Input amount"
                value={amount}
                onChange={(e) => setAmount(parseFloat(e.target.value))}
                required
            />
        </div>

        <button type="submit">
            {expense ? 'Edit Expense' : 'Add Expense'}
        </button>
    </div>
</form>

That's what it takes to create the form logic for creating and editing an expense.

Implementing the Functionalities for the 'Expense' Page

Now, to implement the functionalities inside the main expense page, let's locate the Expense.tsx component inside the expense folder.

Paste these lines of code into it:

'use client'
import React, { useEffect, useState } from 'react';
import axios from 'axios';
import ExpenseForm from './ExpenseForm';
import { format, parseISO } from 'date-fns';
import { FaEdit, FaPlus, FaTrash } from 'react-icons/fa';
import { BsThreeDotsVertical } from "react-icons/bs";

interface Expense {
    id: number;
    attributes: {
        description: string;
        createdAt: string;
        amount: number;
    };
}

interface ExpenseProps {
    refreshCashflow: () => void;
}

const Expense: React.FC<ExpenseProps> = ({ refreshCashflow }) => {
    const [expenses, setExpenses] = useState<Expense[]>([]);
    const [isExpenseFormOpen, setIsExpenseFormOpen] = useState(false);
    const [selectedExpense, setSelectedExpense] = useState<Expense | null>(null);
    const [dropdownOpen, setDropdownOpen] = useState<number | null>(null);

    useEffect(() => {
        fetchExpenses();
    }, []);

    const fetchExpenses = () => {
        fetch("http://localhost:1337/api/expenses?populate=expense")
            .then((res) => {
                if (!res.ok) {
                    throw new Error("Network response was not ok");
                }
                return res.json();
            })
            .then((data) => {
                if (Array.isArray(data.data)) {
                    setExpenses(data.data);
                } else {
                    console.error("Fetched data is not an array");
                }
            })
            .catch((error) => {
                console.error("Error fetching expenses:", error);
            });
    };

    const handleOpenExpenseForm = () => {
        setSelectedExpense(null);
        setIsExpenseFormOpen(true);
    };

    const handleCloseExpenseForm = () => {
        setSelectedExpense(null);
        setIsExpenseFormOpen(false);
    };

    const handleEditExpense = (expense: Expense) => {
        setSelectedExpense(expense);
        setIsExpenseFormOpen(true);
    };

    const handleDeleteExpense = async (id: number) => {
        try {
            await axios.delete(`http://localhost:1337/api/expenses/${id}`);
            setExpenses(expenses.filter((expense) => expense.id !== id));
            refreshCashflow();
        } catch (error) {
            console.error(error);
        }
    };

    const formatDate = (dateString: string) => {
        const date = parseISO(dateString);
        return format(date, 'yyyy-MM-dd HH:mm:ss');
    };

    const toggleDropdown = (id: number) => {
        setDropdownOpen(dropdownOpen === id ? null : id);
    };

    return (
        <section>
            <div>
                <h1>Expenses</h1>
                <FaPlus />
            </div>
            <div>
                {expenses.map((expense) => (
                    <div key={expense.id}>
                        <div>
                            <p>{expense.attributes.description}</p>
                            <div>
                                <BsThreeDotsVertical onClick={() => toggleDropdown(expense.id)} />

                                {dropdownOpen === expense.id && (
                                    <div>
                                        <FaEdit onClick={() => handleEditExpense(expense)} /> Edit
                                        <FaTrash onClick={() => handleDeleteExpense(expense.id)} /> Delete
                                    </div>
                                )}
                            </div>
                        </div>
                        <div>
                            <span>{formatDate(expense.attributes.createdAt)}</span>
                            <h1>${expense.attributes.amount}</h1>
                        </div>
                    </div>
                ))}
            </div>
            {isExpenseFormOpen && (
                <ExpenseForm
                    isOpen={isExpenseFormOpen}
                    onClose={() => {
                        handleCloseExpenseForm();
                        fetchExpenses();
                    }}
                    expense={selectedExpense}
                    refreshCashflow={() => {
                        refreshCashflow();
                        fetchExpenses();
                    }}
                />
            )}
        </section>
    );
};

export default Expense;

This is similar to the code in the Budget.tsx component.

Code Explanation:

As usual, we'll first import the necessary libraries and components - ExpenseForm.
We'll use the JavaScript data library date-fns for consistent date and time formatting to avoid time zone issues arising from using JavaScript's Date object. We've already installed it at the beginning of the tutorial.
Then, we'll define the TypeScript interface Expense to represent the structure of an expense object and the TypeScript interface ExpenseProps to specify the props the component expects. In this case, it is refreshCashflow, which is a function to refresh cashflow.
Next, we declare the Expense component and initialize state variables expenses, isExpenseFormOpen, selectedExpense, and dropdownOpen.
We'll use the useEffect hook to fetch expenses when the component mounts.
Next, we'll define the fetchExpenses function to fetch expenses from the API. If the response is not OK, it will throw an error. If data is an array, it will update the expenses state. Otherwise, it will log an error.

We'll now define some handler functions:

handleOpenExpenseForm to open the form for adding a new expense.
handleCloseExpenseForm to close the form.
handleEditExpense to open the form to edit a selected expense.
handleDeleteExpense to delete an expense from the API and update the state.
- Next, we'll create formatDate function to format date and time consistently using the format and parseISO property from the date-fns library.
- The last function is the toggle dropdown function to handle the opening and closing of dropdown menus for each expense. This dropdown menu will contain the texts 'Edit' and 'Delete' to enable the two functionalities on the page.
- Finally, we'll render the Expense component, which will display a list of expenses. Each expense item has options to edit or delete. When isExpenseFormOpen is true, it renders the ExpenseForm component with the appropriate props. The form will be conditionally rendered based on the isOpen prop.

NB: The createdAt attribute is gotten from the Strapi backend. It gives you the exact date and time an item was created.

Let's test our application to ensure it works as expected.

Fetching Data from Strapi API to Display the Income

Since the income functionality is similar to the expenses functionality, we'll follow the steps we used to create the expense section to create this income section.

Building the income form modal:
In the IncomeForm.tsx component inside the income folder, we'll paste the same code in our ExpenseForm.tsx component. We'll then change components or texts from expense to income and Expense to Income, even the imported component, etc.
Implementing the functionalities for the 'Income' page:
In the Income.tsx component inside the income folder, we'll paste the same code that's in our Expense.tsx
We'll follow the same steps to implement the income functionalities. Don't forget to change components or texts from expense to income and Expense to Income, even your import.

Combining the 'Income' and 'Expense' Component in a Single Page

We'll want expenses and income to be on the same page, not separate pages. So, what we'll do is to combine the two components and display them on the 'cashflow' page like this:

We want to fill out the blank 'Cashflow' column. One other functionality we'll include is that we add incomes and expenses; it should also show up in the 'Cashflow' column arranged in order of time created.

It should function the same way transaction history of a mobile bank app does, where you have a list of all debits and credits all in one page arranged according to the date the transactions were made.

In the Cashflow.tsx component, we'll add these lines of code:

'use client'
import React, { useEffect, useState } from 'react';
import axios from 'axios';
import Income from './income/Income';
import Expense from './expense/Expense';
import { format, parseISO } from 'date-fns';

interface CashflowItem {
    id: number;
    type: 'income' | 'expense';
    description: string;
    createdAt: string;
    amount: number;
}

const Cashflow: React.FC = () => {
    const [cashflow, setCashflow] = useState<CashflowItem[]>([]);

    const fetchCashflow = async () => {
    try {
      const incomesResponse = await axios.get('http://localhost:1337/api/incomes?populate=income');
      const expensesResponse = await axios.get('http://localhost:1337/api/expenses?populate=expense');

      const incomes = incomesResponse.data.data.map((income: any) => ({
        id: income.id,
        type: 'income',
        description: income.attributes.description,
        createdAt: income.attributes.createdAt,
        amount: income.attributes.amount,
      }));

      const expenses = expensesResponse.data.data.map((expense: any) => ({
        id: expense.id,
        type: 'expense',
        description: expense.attributes.description,
        createdAt: expense.attributes.createdAt,
        amount: expense.attributes.amount,
      }));

      // Combine incomes and expenses and sort by createdAt in descending order
      const combined = [...incomes, ...expenses].sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
      setCashflow(combined);
    } catch (error) {
      console.error('Error fetching cashflow:', error);
    }
  };

    useEffect(() => {
        fetchCashflow();
    }, []);

    return (
        <main>
            <Income refreshCashflow={fetchCashflow} />

            <section>
                <div>
                    <h1>Cashflow</h1>
                </div>
                <div>
                    {cashflow.map((item) => (
                        <div key={item.id}>
                            <div>
                                <p>{item.description}</p>
                                <span>{format(parseISO(item.createdAt), 'yyyy-MM-dd HH:mm:ss')}</span>
                                <h1>
                                    ${item.amount.toFixed(2)}
                                </h1>
                            </div>
                        </div>
                    ))}
                </div>
            </section>

            <Expense refreshCashflow={fetchCashflow} />
        </main>
    );
};

export default Cashflow;

Code explanation:

We imported the necessary libraries and components and set the Typescript interface CashflowItem to define the structure of the cashflow items.
We then declared the Cashflow component and initialized a state variable cashflow. This state will hold an array of cash flow items.
Next, we created afetchCashflow function to fetch income and expenses data from the API. We used the axios.get method to send GET requests to the respective API endpoints.
Mapping the responses to format them into arrays of objects similar to the CashflowItem interface comes next.
Then we combined the incomes and expenses into a single array and sort them by createdAt date in descending order. This createdAt property was gotten from Strapi.
Next, we updated the cashflow state with the combined and sorted data.
Then, we implemented the useEffect hook to call the fetchCashflow function when the component mounts. The empty dependency array [] ensures this effect runs only once.
Finally, we rendered the UI of the cashflow column, mapping through the cashflow state to render each cashflow item. Include the Income and Expense components, passing fetchCashflow as the refreshCashflow prop. This allows it to trigger a cashflow refresh whenever an action is performed in either of the respective components.

Combine Income and Expenses in the Cashflow Page

Now render it along with the side navigation like this inside the page.tsx component located in that same cashflow folder.

import SideNav from '@/components/SideNav'
import Cashflow from './Cashflow'

const page = () => {
    return (
        <>
          <div>
             <SideNav />

             <div>
                 <Cashflow />
             </div>
          </div>
        </>
    )
}
export default page

This is our cash flow page, which now consists of both the income and expense functionalities after styling.

We're almost done with our app. Now, let's add one last functionality for this part.

Setting Budget Limit

We want to be able to set a budget limit amount that users won't be able to exceed when creating budgets.

The total of all the budget amounts must not be more than the budget limit amount set. If the user attempts to set an amount greater than the limit, they will get an error message saying "You've exceeded the budget limit for this month".

Create the Budget Limit Collection in Strapi

In the Strapi admin panel, go to Content-Types Builder.
Add a new collection type and name it "BudgetLimits".
Add a field named limit of type 'Number'.
Save the changes.
Create an entry, save, and publish.
We got to roles settings and updated the permission to enable CRUD functionalities.

Fetch the Budget Limit and Update the Budget Component
Let's go to our Budget.tsx file.

We'll create a state for the budget limit:
const [budgetLimit, setBudgetLimit] = useState<number | null>(null);

Inside our useEffect function, we'll create a fetchBudgetLimit function to fetch the budget limit data:

const fetchBudgetLimit = async () => {
try {
    const res = await axios.get("http://localhost:1337/api/budget-limits");
     if (res.data.data && res.data.data[0]) {
      setBudgetLimit(res.data.data[0].attributes.limit);
     }
} catch (error) {
    console.error("Error fetching budget limit:", error);
}
};

Next, we'll call the budget limit function in the useEffect hook:
fetchBudgetLimit();

Let's now create a function that will calculate the total amount of budget categories inputted:

const totalBudgetedAmount = budgets.reduce((total, budget) => total + budget.attributes.amount, 0);

Next, we'll update the rendered UI to include the budget limit amount and the total amount of budget categories inputted:
```
<section>
<h3>Budget Limit: ${budgetLimit}</h3>
<h3>Total Budgeted: ${totalBudgetedAmount}</h3>
</section>
```

Lastly, update the rendered budget form component to include the props that will be passed from the form:

{isBudgetFormOpen && (
<BudgetForm
    onClose={handleCloseBudgetForm}
    setBudgets={setBudgets}
    selectedBudget={selectedBudget}
    budgetLimit={budgetLimit}
    totalBudgetedAmount={totalBudgetedAmount}
/>
)}

We'll see the total budget amount and the limit value displayed in our app.

Update the Budget Form Component
We'll need to update the BudgetForm to check the total budgeted amount against the limit before submitting.

We'll add props for the budget limit and total budget amount by updating our BudgetFormProps to look like this:

interface BudgetFormProps {
onClose: () => void;
setBudgets: React.Dispatch<React.SetStateAction<Budget[]>>;
selectedBudget: Budget | null;
budgetLimit: number | null;
totalBudgetedAmount: number;
}

We'll then pass the recently added props into the component like this:

const BudgetForm: React.FC<BudgetFormProps> = ({ onClose, setBudgets, selectedBudget, budgetLimit, totalBudgetedAmount }) => { 
//other lines of code
}

We'll create a state to store an error message when a user exceeds the budget limit set:
const [error, setError] = useState<string | null>(null);
Let's update the handleSendBudget function to include the new functionality:

const handleSendBudget = async () => {
    try {
      const { category, amount } = formFields;
      const newAmount = parseFloat(amount);
      const currentAmount = selectedBudget ? selectedBudget.attributes.amount : 0;
      const newTotal = totalBudgetedAmount - currentAmount + newAmount;

      if (budgetLimit !== null && newTotal > budgetLimit) {
        setError("You've exceeded the budget limit for this month");
        return;
      }

      if (selectedBudget) {
        // Update an existing budget
        const data = await axios.put(`http://localhost:1337/api/budgets/${selectedBudget.id}`, {
          data: { category, amount: newAmount },
        });
        console.log(data);
        setBudgets((prev) => prev.map((inv) => (inv.id === selectedBudget.id ? { ...inv, ...formFields, amount: newAmount } : inv)));
        window.location.reload();
      } else {
        // Create a new budget
        const { data } = await axios.post('http://localhost:1337/api/budgets', {
          data: { category, amount: newAmount },
        });
        console.log(data);
        setBudgets((prev) => [...prev, data.data]);
      }

      setError(null);
      onClose();
    } catch (error) {
      console.error(error);
      setError("An error occurred while saving the budget.");
    }
  };

Lastly, we'll render the error message in the form: {error && <p className="text-red-500 text-sm">{error}</p>}

Our app will be updated now. It will display the budget limit and the total budget amount at the top of our budget page. It will then implement the error message when the user attempts to exceed the set budget limit.

To test this out, we'll input a budget limit amount on our Strapi CMS admin panel, save it, and publish it. When we go back to the app, we'll try to update an amount in any budget category that will exceed the budget limit set. We'll get an error message letting us know that we can't perform that action because we are attempting to exceed our set budget amount limit.

We're done with part one of this blog series. Stay tuned for part two, where we'll continue this tutorial by adding visualization for our financial data using Chart.js.

Conclusion

In this part one of this tutorial series, we learned how to set up Strapi for backend storage, how to create collections and entries, and how to connect it to the frontend.

You also learned how to build a functional, interactive personal finance app where a user can create and track budgets, income and expenses. This should enrich your frontend development skills.

In the next part, we will learn how to add visualization with charts and graphs.

How To Refactor Your Codebase

Juliet Ofoegbu — Fri, 19 Jul 2024 08:34:50 +0000

Introduction

Programming is the process of writing programs or code to solve problems. The process of writing code is only the beginning of the development journey.

As a project progresses and changes are made, the need to refactor the code arises and becomes unavoidable throughout the project’s lifecycle.

Nobody likes a messy codebase, especially maintaining one they didn't initially write. If you were asked to refactor someone's codebase or your messy codebase, how would you do this?

In this article, we'll learn what code refactoring is all about and how to go about it.

Code Refactoring

Code refactoring is the act of restructuring the existing code without affecting its behavior and functionality. The main idea behind code refactoring is to improve code readability and maintainability, hence contributing to the overall quality of software or an application.

The first step in refactoring a codebase is identifying “code smells”.

Code Smells

Code smells are signs that indicate that there is an issue with your code. Code smells are not necessarily bugs or errors and they won’t prevent your code from functioning as it should. They are like ‘signals’ that warn you of pending problems in your code.

Identifying these code smells early in the development process helps you avoid several issues later on. Regular code reviews, utilizing code analysis tools like SonarQube, running tests, and adopting clean coding practices are all necessary for early detection of code smells.

Benefits of Code Refactoring

Code refactoring offers you some benefits that contribute to the overall quality of your software project. Here are some key benefits of code refactoring:

Improves code readability and reusability: Refactoring involves the process of simplifying code structure to make the codebase more readable, even for other developers who will read or use your code. It also often requires breaking down functions or classes into reusable components.
Improves performance: Identifying and improving inefficient algorithms in the refactoring process can lead to more efficient software. This in turn enhances the performance of the application.
Enhances code maintainability: Code refactoring increases code maintainability by breaking down large functions and structuring them logically. When large code functions are broken down into smaller units, they are easier to manage and maintain.
Reduces technical debt: Technical debt is incurred when programmers implement quick solutions or shortcuts during software development which can result in bad code or an unstructured codebase. Regularly refactoring your code helps you reduce technical debt by reducing the accumulation of poorly structured code, eliminating code smells, improving code quality, and making future development smoother and more efficient.
Enhance team collaboration: When a codebase is refactored, it becomes easier to understand and maintain. This fosters better collaboration among team members as they can understand each other's code more easily.

Code Refactoring Tools and Techniques

As a programmer, there are several tools and techniques that you can utilize to improve the quality and maintainability of your code.

Code Refactoring Tools

These tools are software applications that help programmers restructure and improve the quality of their code while maintaining its functionality.

Examples of code refactoring tools include:

CodeRush: CodeRush is a refactoring tool in Visual Studio Code for .NET development. It offers features for enhancing code quality, including code refactoring, code generation, and code analysis to improve code readability. Here's a guide on how to use the CodeRush refactoring assistance on VS Code.
IntelliJ IDEA: IntelliJ IDEA is a popular (IDE) for Java and Kotlin development. It offers a lot of automatic refactoring capabilities like renaming, extracting, and deleting to improve code maintainability and readability.
Visual Studio Code: Visual Studio Code (VS Code) is a popular open-source code editor that supports refactoring methods like the extraction method. VS Code also supports a range of extensions including those for code refactoring.
An example of this is the built-in support for TypeScript and JavaScript refactoring through the TypeScript language service. Also in VS Code, Code Actions (the light bulb icon indicating possible fixes to a code) can provide both refactoring and Quick Fixes for detected issues
ReSharper: ReSharper is a Visual Studio IDE Extension for .NET developers. It offers refactoring features, code analysis, code generation, and code navigation tools.
Using the 'Refactor This' action provides you with a shortcut of all the refactoring available in the current context of your code.

Code Refactoring Techniques

1. Extraction Method

This involves breaking down a large piece of code that performs a specific function into smaller, simpler portions by creating a new method. This improves the code structure, readability, and reuse.

Example: Assume you have a component whose function is to add items to a shopping cart and then calculate the total price of items in the cart.
If the calculation part is getting bulky and taking up a lot of space in the component, you can decide to extract that calculation into its separate function called calculateTotalPrice. This way, the main function becomes simpler and easier to understand.

2. Abstraction Method

This involves reorganizing code into a high-level concept to focus on the main idea. This reduces code redundancy, eliminates duplication, and improves code structure.

Example: Assume you have a program that checks and calculates the area of different shapes like triangles, squares, etc. Each of these shapes has its method for calculating area. You can decide to separately implement these methods for each shape but this will lead to code duplication and affect the code maintainability.

Instead of doing this, you can use the abstraction method to refactor this code by creating a higher-level function called calculateArea. This function will then take the shape as input and calculate its area based on the type.

Code snippet:



import React from 'react';

// Functional component for Shape
function Shape({ type, calculateArea }) {
    return (
        <div>
            <h2>{type}</h2>
            <p>Area: {calculateArea()}</p>
        </div>
    );
}

// Component for Circle
function Circle({ radius }) {
    const calculateArea = () => Math.PI * radius ** 2;
    return <Shape type="Circle" calculateArea={calculateArea} />;
}

// Component for Square
function Square({ sideLength }) {
    const calculateArea = () => sideLength ** 2;
    return <Shape type="Square" calculateArea={calculateArea} />;
}

// Component for Triangle
function Triangle({ base, height }) {
    const calculateArea = () => 0.5 * base * height;
    return <Shape type="Triangle" calculateArea={calculateArea} />;
}

// Main Component
function App() {
    return (
        <div>
            <Circle radius={6} />
            <Square sideLength={4} />
            <Triangle base={3} height={6} />
        </div>
    );
}

export default App;

3. Code Simplification

This involves identifying and simplifying complex functions or unnecessary code and this increases code readability.

Example: Let's say you have a function that filters out even numbers from an array and returns a new array containing only the even numbers. Initially, the function might include redundant code and be unnecessarily complex. We can simplify it by removing redundancy and simplifying the logic.

Initial code version:



function filterEvenNumbers(arr) {
  let evenNumbers = [];

  for (let i = 0; i < arr.length; i++) {
    if (arr[i] % 2 === 0) {
      evenNumbers.push(arr[i]);
    }
  }

  return evenNumbers;
}

Refactored code:



function filterEvenNumbers(arr) {
  return arr.filter(num => num % 2 === 0);
}

Here, the filter method is used to create a new array containing only the elements that satisfy the condition specified in the callback function. This eliminates the need for a separate loop and the creation of a new array to store the even numbers.

4. Red-Green-Refactor

In test-driven development (TDD), this method involves you writing a test that fails (Red), writing the minimum amount of code to make the test pass (Green), and then improving the code's structure and readability without changing its behavior (Refactor).

Steps in Refactoring a Codebase

Following these steps when refactoring a codebase can help you enhance the quality of your code:

1. Understand the codebase
Before refactoring a codebase especially one you are not familiar with, it's important to take out time to understand the existing codebase thoroughly.

It includes familiarizing yourself with the design patterns, coding conventions, architecture, and existing documentation.

2. Identify code smells
As explained in a previous section, code smells are indicators of potential issues in the code that may warrant refactoring. Common code smells include complex conditional logic, large classes, duplication, and too many dependencies.

Use code analysis tools (SonarQube, Coverity, DeepSource, Codacy, etc) or manual code reviews to identify these code smells.

3. Prioritize refactoring targets
In every codebase, there are high-priority target areas that are either frequently changed, prone to bugs or are very crucial for performance. Some areas may not require immediate attention.

Consider prioritizing refactoring targets based on factors like how it changes frequently, its impact on the whole software, and the seriousness of the code smell.

4. Choose the right refactoring technique
There are lots of techniques available for code refactoring like the ones mentioned in the previous section. Choose the best technique that is suitable for addressing the identified code smells in the codebase. Choose techniques that improve code readability and maintainability.

5. Plan refactoring tasks
Before you start refactoring the codebase, think about the specific improvements to be made and break down the tasks into smaller units so they can be easily managed.
Write down what needs to be done and how these changes might affect other parts of the code.

6. Execute refactoring safely
When you're making changes to the code, do it little by little and test each change to make sure it doesn't break anything or have any bugs. Use version control systems, like GitHub to keep track of the changes you're making, so if something goes wrong, you can easily track it and go back to the previous version.

Also, follow good practices like writing unit tests, having others review your code, and using automated testing tools (JUnit for Java and pytest for Python for writing unit tests).

7. Feedback, monitor, and iterate
After making changes to the code, pay attention to how they affect the code quality, its performance, and the effect on developer productivity. Ask for feedback from your team and anyone else involved. Use this feedback to make further improvements.

Step-by-step guide for using the VS Code Extension - Glean to refactor a React codebase

VS Code Glean is a VS Code extension that provides refactoring features for your React codebase such as extracting JSX into a new component, converts class components to functional components, converting functional components to class components, wrapping with Hooks and more.

Here's a step-by-step guide on how to use Glean to refactor a complex codebase directly in your VS Code editor:

Step 1: Open your Next.js or React project in VS Code
Launch Visual Studio Code and open your project.
Step 2: Install Glean extension
Navigate to the VS Code extensions marketplace or press (Ctrl+Shift+X) and type 'glean' in the search box. This will bring up the Glean extension code refactoring tools. Select the first option that comes up and click on the "Install" button.
Step 3: Use Glean refactoring features
Once you've identified areas for refactoring, use Glean's refactorings to make the necessary changes. Here are some examples of refactorings you can perform with Glean:
- A. Extract Component: You can extract a portion of JSX code into a new React component. Select the block of code, click on the light bulb icon, and select the "Extract Component to File" option. A dropdown with a list of the directories you can extract your component to will appear.

You can either select a component you want it extracted to or you can input a new file you want the component to be extracted to, e.g., '/Form.tsx'. Hit enter. Doing this will extract that JSX code to a new component called Form.tsx while providing it with all the props it needs.

B. Conversion: You can seamlessly convert class components to functional components and vice versa. All you need to do is highlight everything in the component file. Next, click the light bulb icon. Select the "Convert Function to Class component" or the "Convert Class to Function component" option depending on whether it's a functional or state component you're converting from.

C. Rename: Use the "Rename" refactoring to quickly rename any state variables, functions, or components throughout your codebase. Highlight the variable you intend to rename, click on the light bulb icon, and then choose the "Rename State" option. This will prompt you to enter the name you want, hit enter and it will rename the state variable for you.

Step 4: Review, test, and commit After refactoring, review your changes to ensure they haven't introduced any bugs. Once you're satisfied with the refactored code, commit your changes to your version control system if you need to.

By following these steps and using Glean's refactoring features, you can effectively refactor a more complex codebase, improving its maintainability and readability.

NB: For more VS Code refactoring extensions, navigate to the extensions marketplace view in your VS Code or press (Ctrl+Shift+X) and type 'refactor' in the search box. This will bring up some options for code refactoring tools.

Some are specifically for different programming languages. You can then sort these results by popularity, category, recently published, and so on.

Always conduct proper research on the particular refactoring tool you intend to use. Check for the number of downloads, ratings, and support that the tool has.

When You Should Consider Refactoring Your Code

Here are some common scenarios when you should consider refactoring your code:

When introducing new features that change an existing code, consider refactoring.
During code reviews, a team member can highlight areas of code that are complex, have code smells, or violate coding standards. This is an ideal time to refactor your code.
If a code is extremely complex or adds to the problem, refactor it to address bugs and errors that will arise during development.

A point to note is that code refactoring is NOT fixing bugs in your code. It is NOT adding new features. Code refactoring is deeper than all these and it’s done to improve the codebase's internal structure.

Refactoring a full codebase

We've learned what it means to refactor a codebase and how it can be done using different tools and techniques. I also provided examples and small code snippets illustrating how to refactor some parts of a component/file. To make sure we understand this well, I'll demonstrate all we've learned by refactoring a full codebase.

The project codebase we'll be refactoring is an invoicing application I recently built using Nextjs, TypeScript, Tailwindcss for styling, and Strapi as the headless CMS.

Here's the GitHub page for the project. Study the codebase, you'll notice that originally only 3 files were used to build the functionalities.

We'll focus on breaking down the code into more manageable pieces, improving readability, and maintaining functionality. Here's how you can approach this:

Refactor the 'InvoiceForm' component

First, we'll refactor the code components for the 'InvoiceForm' component.

We'll be using three techniques to refactor this codebase.

1. Extraction Method
Extract repetitive UI elements into reusable components:

Create a new component for input fields (InputField.tsx):



// components/InputField.tsx
import React, { ChangeEvent } from 'react';

interface InputFieldProps {
  label: string;
  id: string;
  name: string;
  type: string;
  placeholder: string;
  value: string | number;
  onChange: (e: ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) => void;
  required?: boolean;
}

const InputField: React.FC<InputFieldProps> = ({ label, id, name, type, placeholder, value, onChange, required = false }) => (
  <div className="flex flex-col w-[45%] mb-4">
    <label className="block text-gray-700 text-sm font-bold mb-2" htmlFor={id}>
      {label}
    </label>
    <input
      className="shadow appearance-none border rounded w-full py-2 px-3 text-gray-700 leading-tight focus:outline-none focus:shadow-outline"
      id={id}
      name={name}
      type={type}
      placeholder={placeholder}
      onChange={onChange}
      value={value}
      required={required}
    />
  </div>
);

export default InputField;

Create a new component for textarea fields (TextAreaField.tsx):



// components/TextAreaField.tsx
import React, { ChangeEvent } from 'react';

interface TextAreaFieldProps {
  label: string;
  id: string;
  name: string;
  placeholder: string;
  value: string;
  onChange: (e: ChangeEvent<HTMLTextAreaElement>) => void;
  required?: boolean;
}

const TextAreaField: React.FC<TextAreaFieldProps> = ({ label, id, name, placeholder, value, onChange, required = false }) => (
  <div className="flex flex-col w-[45%] mb-4">
    <label className="block text-gray-700 text-sm font-bold mb-2" htmlFor={id}>
      {label}
    </label>
    <textarea
      className="shadow appearance-none border rounded w-full py-2 px-3 text-gray-700 leading-tight focus:outline-none focus:shadow-outline"
      id={id}
      name={name}
      placeholder={placeholder}
      onChange={onChange}
      value={value}
      required={required}
    />
  </div>
);

export default TextAreaField;

2. Abstraction Method
Abstract the form state management logic into a custom hook (useInvoiceForm.tsx):



// hooks/useInvoiceForm.ts
import { useReducer, useEffect } from 'react';
import { Invoice } from '../components/InvoiceForm';

const initialState = {
  name: '',
  senderEmail: '',
  recipientEmail: '',
  shippingAddress: '',
  date: '',
  dueDate: '',
  invoiceNote: '',
  description: '',
  qty: 0,
  rate: 0,
  total: 0,
};

function reducer(state = initialState, { field, value }: { field: string, value: any }) {
  return { ...state, [field]: value };
}

const useInvoiceForm = (selectedInvoice: Invoice | null) => {
  const [formFields, dispatch] = useReducer(reducer, initialState);

  useEffect(() => {
    if (selectedInvoice) {
      for (const [key, value] of Object.entries(selectedInvoice?.attributes)) {
        dispatch({ field: key, value });
      }
    } else {
      for (const [key, value] of Object.entries(initialState)) {
        dispatch({ field: key, value });
      }
    }
  }, [selectedInvoice]);

  useEffect(() => {
    const { qty, rate } = formFields;
    const total = qty * rate;
    dispatch({ field: 'total', value: total });
  }, [formFields.qty, formFields.rate]);

  const handleInputChange = (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) => {
    const { name, value } = e.target;
    dispatch({ field: name, value });
  };

  return { formFields, handleInputChange };
};

export default useInvoiceForm;

3. Code Simplification
Simplify the 'InvoiceForm' component using the new reusable components and the custom hook:



// components/InvoiceForm.tsx
'use client';
import React from 'react';
import axios from 'axios';
import InputField from './InputField';
import TextAreaField from './TextAreaField';
import useInvoiceForm from '../hooks/useInvoiceForm';

interface InvoiceFormProps {
  onClose: () => void;
  setInvoices: React.Dispatch<React.SetStateAction<Invoice[]>>;
  selectedInvoice: Invoice | null;
}

interface Invoice {
  id: number;
  name: string;
  attributes: any;
  senderEmail: string;
  recipientEmail: string;
  shippingAddress: string;
  date: string;
  dueDate: string;
  invoiceNote: string;
  description: string;
  qty: number;
  rate: number;
  total: number;
}

const InvoiceForm: React.FC<InvoiceFormProps> = ({ onClose, setInvoices, selectedInvoice }) => {
  const { formFields, handleInputChange } = useInvoiceForm(selectedInvoice);

  const handleSendInvoice = async () => {
    try {
      const { name, senderEmail, recipientEmail, date, dueDate, shippingAddress, invoiceNote, description, qty, rate, total } = formFields;

      if (selectedInvoice) {
        const data = await axios.put(`http://localhost:1337/api/invoices/${selectedInvoice.id}`, {
          data: { name, senderEmail, recipientEmail, shippingAddress, dueDate, date, invoiceNote, description, qty, rate, total },
        });
        setInvoices((prev) => prev.map((inv) => (inv.id === selectedInvoice.id ? { ...inv, ...formFields } : inv)));
        window.location.reload();
      } else {
        const { data } = await axios.post('http://localhost:1337/api/invoices', {
          data: { name, senderEmail, recipientEmail, shippingAddress, dueDate, date, invoiceNote, description, qty, rate, total },
        });
        setInvoices((prev) => [...prev, data.data]);
      }

      onClose();
    } catch (error) {
      console.error(error);
    }
  };

  return (
    <main className="fixed top-0 z-50 left-0 w-screen h-screen flex justify-center items-center bg-black bg-opacity-50">
      <section className="relative lg:px-10 px-6 py-8 lg:mt-8 lg:w-[60%] bg-white shadow-md rounded px-8 pt-2 pb-8 mb-4">
        <form className="pt-4">
          <h2 className="text-lg font-medium mb-4">{selectedInvoice ? 'Edit Invoice' : 'Create Invoice'}</h2>
          <button className="absolute top-2 right-8 font-bold text-black cursor-pointer text-2xl" onClick={onClose}>
            &times;
          </button>
          <div className="mb-4 flex flex-row justify-between">
            <InputField
              label="Your name"
              id="name"
              name="name"
              type="text"
              placeholder="Sender's name"
              value={formFields.name}
              onChange={handleInputChange}
              required
            />
            <InputField
              label="Your email address"
              id="senderEmail"
              name="senderEmail"
              type="email"
              placeholder="Sender's email"
              value={formFields.senderEmail}
              onChange={handleInputChange}
              required
            />
            <InputField
              label="Recipient's Email"
              id="recipientEmail"
              name="recipientEmail"
              type="email"
              placeholder="Client's email address"
              value={formFields.recipientEmail}
              onChange={handleInputChange}
              required
            />
          </div>

          <div className="mb-4 flex flex-row justify-between">
            <InputField
              label="Date"
              id="date"
              name="date"
              type="date"
              value={formFields.date}
              onChange={handleInputChange}
              required placeholder={''}
            />

            <InputField
              label="Due Date"
              id="dueDate"
              name="dueDate"
              type="date"
              value={formFields.dueDate}
              onChange={handleInputChange}
              required
              placeholder={''}
            />
          </div>

          <div className="mb-4 flex flex-row justify-between">
            <TextAreaField
              label="Shipping Address"
              id="shippingAddress"
              name="shippingAddress"
              placeholder="Office address of recipient"
              value={formFields.shippingAddress}
              onChange={handleInputChange}
              required
            />
            <TextAreaField
              label="Invoice Note"
              id="invoiceNote"
              name="invoiceNote"
              placeholder="Account details"
              value={formFields.invoiceNote}
              onChange={handleInputChange}
              required
            />
          </div>

          <div className="flex justify-center items-center">
            <InputField
              label="Invoice Item"
              id="description"
              name="description"
              type="text"
              placeholder="Description of Item"
              value={formFields.description}
              onChange={handleInputChange}
              required
            />
            <InputField
              label="Qty"
              id="qty"
              name="qty"
              type="number"
              placeholder="Quantity of item"
              value={formFields.qty}
              onChange={handleInputChange}
              required
            />
            <InputField
              label="Rate"
              id="rate"
              name="rate"
              type="number"
              placeholder="Price of item"
              value={formFields.rate}
              onChange={handleInputChange}
              required
            />

            <div className="block text-gray-700 text-sm font-bold mb-2 w-full mr-3">
              <label>Total</label>
              <div className="shadow appearance-none border rounded w-full py-2 px-3 text-gray-700 mb-3 leading-tight">
                {formFields.total}
              </div>
            </div>
          </div>

          <hr className="mt-5 border-1" />

          <div className="mt-4 flex justify-center">
            <button
              type="button"
              className="py-2 px-4 border border-transparent shadow-sm text-sm font-medium rounded-md text-white bg-green-600 hover:bg-green-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-green-500"
              onClick={handleSendInvoice}
            >
              {selectedInvoice ? 'Update Invoice' : 'Send Invoice'}
            </button>
          </div>
        </form>
      </section>
    </main>
  );
};

export default InvoiceForm;

Explanation

1. Reusable Components:
The InputField and TextAreaField components were created for reusability and cleaner code. These components simplify the form by reducing repetitive code for the inputs.

2. Custom Hook:
The useInvoiceForm custom hook handles the form state and logic, making the component leaner. It handles initial state setup, modal visibility, and updates based on selected invoice and field changes.

3. Refactored InvoiceForm component:
The InvoiceForm component then uses InputField and TextareaField for the form fields. This component then uses the useInvoiceForm hook for state management, making the component more readable and maintainable.

Refactor the 'Invoices' component

Now let's refactor the Invoices component and break it down.

1. Extraction Method
Extract the invoice header and invoice page layout into separate components.

Create the InvoiceHeader.tsx component.



// components/InvoiceHeader.tsx
import React from 'react';

interface InvoiceHeaderProps {
  onOpen: () => void;
}

const InvoiceHeader: React.FC<InvoiceHeaderProps> = ({ onOpen }) => (
  <div className="w-[65%] flex flex-row justify-between items-center mb-6">
    <h1 className="text-2xl font-bold">Invoices</h1>

    <button
      className="bg-green-500 hover:bg-green-700 text-white font-bold py-2 px-4 rounded"
      onClick={onOpen}>
      Create Invoice
    </button>
  </div>
);

export default InvoiceHeader;

Create the InvoiceLayout.tsx component.



// components/InvoiceLayout.tsx
import React from 'react';
import { Invoice } from '../types';
import useInvoiceDownload from '@/hooks/useInvoiceDownload';

interface InvoiceLayoutProps {
    invoices: Invoice[];
    onEdit: (invoice: Invoice) => void;
    onDelete: (id: number) => void;
    onDownload: (invoice: Invoice) => void;
}

const InvoiceLayout: React.FC<InvoiceLayoutProps> = ({ invoices, onEdit, onDelete, onDownload }) => (
    <div className="w-[70%]">
        <div className="px-5 py-5 mx-auto">
          {invoices.map((invoice) => (
                <>
                    <div className="flex flex-wrap border-t-2 border-b-2 border-gray-200 border-opacity-60" key={invoice.id}>
                        <div className="lg:w-1/3 md:w-full px-8 py-6 border-opacity-60">
                            <div>
                                <h2 className="text-base text-gray-900 font-medium mb-1">Issued:</h2>
                                <p className="leading-relaxed text-sm mb-4">{invoice.attributes.date}</p>
                            </div>
                            <div className="mt-12">
                                <h2 className="text-base text-gray-900 font-medium">Due:</h2>
                                <p className="leading-relaxed text-sm mb-4">{invoice.attributes.dueDate}</p>
                            </div>
                        </div>

                        <div className="lg:w-1/3 md:w-full px-8 py-6 border-l-2 border-gray-200 border-opacity-60">
                            <h2 className="text-base text-gray-900 font-medium mb-2">Billed To:</h2>
                            <div className="">
                                <h2 className=" text-gray-900 text-sm mb-1 font-medium">Recipient's Email</h2>
                                <p className="leading-relaxed text-sm mb-5">{invoice.attributes.recipientEmail}</p>
                            </div>

                            <div>
                                <h2 className=" text-gray-900 text-sm mb-1 font-medium">Shipping Address</h2>
                                <p className="leading-relaxed text-sm mb-4">{invoice.attributes.shippingAddress}</p>
                            </div>
                        </div>

                        <div className="lg:w-1/3 md:w-full px-8 py-6 border-l-2 border-gray-200 border-opacity-60">
                            <h2 className="text-base text-gray-900 font-medium mb-2">From:</h2>
                            <div className="">
                                <h2 className=" text-gray-900 text-sm mb-1 font-medium">Sender's Name</h2>
                                <p className="leading-relaxed text-sm mb-5">{invoice.attributes.name}</p>
                            </div>

                            <div>
                                <h2 className=" text-gray-900 text-sm mb-1 font-medium">Sender's Email</h2>
                                <p className="leading-relaxed text-sm mb-4">{invoice.attributes.senderEmail}</p>
                            </div>
                        </div>
                    </div>

                    <div className="w-full px-5 py-12 mx-auto">
                        <div className="flex flex-row justify-between border-b-2 border-gray-300">
                            <div>
                                <h2 className="text-lg font-medium text-gray-700 mb-2">Invoice Item</h2>
                            </div>

                            <div className="flex flex-row mb-2">
                                <p className="ml-2 text-lg font-medium text-gray-800">Qty</p>
                                <p className="ml-[6rem] text-lg font-medium text-gray-800">Rate</p>
                                <p className="ml-[6rem] text-lg font-medium text-gray-800">Total</p>
                            </div>
                        </div>

                        <div className="flex flex-row justify-between mt-4">
                            <div>
                                <h2 className="text-base text-gray-700 mb-4">{invoice.attributes.description}</h2>
                            </div>

                            <div className="flex flex-row mb-4">
                                <p className="ml-2 text-base text-gray-800">{invoice.attributes.qty}</p>
                                <p className="ml-[6rem] text-base text-gray-800">${invoice.attributes.rate}</p>
                                <p className="ml-[6rem] text-base text-gray-800">${invoice.attributes.total}</p>
                            </div>
                        </div>

                        <div className="grid justify-end pt-[2.5rem]">
                            <div className="flex flex-row justify-between">
                                <div>
                                    <h2 className="text-lg font-medium text-gray-700 mb-4">Tax (0%)</h2>
                                </div>

                                <div className="flex flex-row">
                                    <p className="ml-[10rem] text-base text-gray-800">0.00</p>
                                </div>
                            </div>

                            <div className="flex flex-row justify-between border-y-2 border-green-400">
                                <div className="pt-4">
                                    <h2 className="text-lg font-medium text-gray-700 mb-4">Amount due:</h2>
                                </div>

                                <div className="flex flex-row pt-4">
                                    <p className="ml-[10rem] text-lg font-medium text-gray-800">${invoice.attributes.total}.00</p>
                                </div>
                            </div>
                        </div>
                    </div>

                    <div className="flex flex-row justify-between w-full mt-1">
                        <div>
                            <button className="bg-blue-500 px-2 py-2 rounded text-white hover:bg-blue-600"
                                onClick={() => onDownload(invoice)}>
                                Download invoice
                            </button>

                            <button className="bg-green-500 px-2 py-2 rounded text-white hover:bg-green-600 ml-4"
                                onClick={() => onEdit(invoice)}>
                                Edit invoice
                            </button>
                        </div>

                        <div className="flex justify-end bg-red-400 px-2 py-2 rounded text-white hover:bg-red-500">
                            <button 
                                onClick={() => onDelete(invoice.id)}>
                                Delete invoice
                            </button>
                        </div>
                    </div>
                </>
            ))}
        </div>
    </div>
);

export default InvoiceLayout;

2. Abstraction Method
Abstract the form state management logic into a custom hook (useInvoices.tsx).



// hooks/useInvoices.ts
import { useState, useEffect } from 'react';
import axios from 'axios';
import { Invoice } from '../types';

const useInvoices = () => {
  const [invoices, setInvoices] = useState<Invoice[]>([]);
  const [selectedInvoice, setSelectedInvoice] = useState<Invoice | null>(null);
  const [isModalOpen, setIsModalOpen] = useState(false);

  useEffect(() => {
    const fetchInvoices = async () => {
      try {
        const { data } = await axios.get('http://localhost:1337/api/invoices');
        setInvoices(data.data);
      } catch (error) {
        console.error(error);
      }
    };

    fetchInvoices();
  }, []);

  const handleDelete = async (id: number) => {
    try {
      alert("Are you sure you want to delete this invoice?")
      await axios.delete(`http://localhost:1337/api/invoices/${id}`);
      setInvoices(invoices.filter((invoice) => invoice.id !== id));
    } catch (error) {
      console.error(error);
    }
  };

  return {
    invoices,
    setInvoices,
    selectedInvoice,
    setSelectedInvoice,
    isModalOpen,
    setIsModalOpen,
    handleDelete,
  };
};

export default useInvoices;

Create a custom hook (useInvoiceDownload.tsx) for the download functionality:



// hooks/useInvoiceDownload.ts
import jsPDF from 'jspdf';
import autoTable from 'jspdf-autotable';
import { Invoice } from '../types';

const useInvoiceDownload = () => {
  const downloadInvoice = (invoice: Invoice) => {
    const doc = new jsPDF();

    doc.setFontSize(18);
    doc.text('Invoice', 14, 22);

    autoTable(doc, {
      startY: 30,
      head: [['Name', 'Sender Email', 'Recipient Email', 'Date', 'Due Date', 'Total']],
      body: [
        [
          invoice.attributes.name,
          invoice.attributes.senderEmail,
          invoice.attributes.recipientEmail,
          invoice.attributes.date,
          invoice.attributes.dueDate,
          invoice.attributes.total,
        ],
      ],
    });

    doc.save(`invoice_${invoice.id}.pdf`);
  };

  return { downloadInvoice };
};

export default useInvoiceDownload;

Create a types file for common types.



// types.tsx
export interface Invoice {
  id: number;
  attributes: {
    name: string;
    senderEmail: string;
    recipientEmail: string;
    shippingAddress: string;
    date: string;
    dueDate: string;
    invoiceNote: string;
    description: string;
    qty: number;
    rate: number;
    total: number;
  };
}

3. Code Simplification
Refactor the main Invoice component by refactoring the Invoices component using the new reusable components and the custom hook:



// components/Invoices.tsx
'use client';
import React from 'react';
import InvoiceHeader from './InvoiceHeader';
import InvoiceLayout from './InvoiceLayout';
import InvoiceForm from './InvoiceForm';
import useInvoices from '../hooks/useInvoices';
import useInvoiceDownload from '../hooks/useInvoiceDownload';

const Invoices: React.FC = () => {
  const {
    invoices,
    setInvoices,
    selectedInvoice,
    setSelectedInvoice,
    isModalOpen,
    setIsModalOpen,
    handleDelete,
  } = useInvoices();

  const handleEdit = (invoice: Invoice) => {
    setSelectedInvoice(invoice);
    setIsModalOpen(true);
  };

  const { downloadInvoice } = useInvoiceDownload();

  return (
    <>
      <div className="flex flex-col items-center justify-center">
        <InvoiceHeader onOpen={() => setIsModalOpen(true)} />

        {isModalOpen && (
          <InvoiceForm
            onClose={() => setIsModalOpen(false)}
            setInvoices={setInvoices}
            selectedInvoice={selectedInvoice}
          />
        )}

        {invoices.length === 0 ? (
          <p>No invoice yet.</p>
        ) : (
          <InvoiceLayout invoices={invoices} onEdit={handleEdit} onDelete={handleDelete} onDownload={downloadInvoice} />
        )}
      </div>
    </>
  );
};

export default Invoices;

We were able to refactor the full codebase of this web application using the refactoring techniques explained, making it reusable, readable, and maintainable without changing its functionalities.

Compare this with the original codebase of the project to see the differences. Test it out on your browser to see that the functionality doesn't change but the codebase did. The application components are now more reusable and can be easily maintained by anybody.

Conclusion

This article provides insights into the art of code refactoring, the identification of code smells, the benefits of code refactoring, code refactoring tools, and techniques, steps in refactoring a codebase, when you should consider refactoring a codebase, and what doesn’t count as code refactoring.

Code refactoring is an essential quality of a good programmer. So don’t hesitate to improve your programming skills by learning how to refactor your code to build readable and maintainable software applications.

How To Refactor Your Codebase

Juliet Ofoegbu — Fri, 19 Jul 2024 08:34:50 +0000

Introduction

Programming is the process of writing programs or code to solve problems. The process of writing code is only the beginning of the development journey.

As a project progresses and changes are made, the need to refactor the code arises and becomes unavoidable throughout the project’s lifecycle.

Nobody likes a messy codebase, especially maintaining one they didn't initially write. If you were asked to refactor someone's codebase or your messy codebase, how would you do this?

In this article, we'll learn what code refactoring is all about and how to go about it.

Code Refactoring

The first step in refactoring a codebase is identifying “code smells”.

Code Smells

Benefits of Code Refactoring

Code refactoring offers you some benefits that contribute to the overall quality of your software project. Here are some key benefits of code refactoring:

Improves code readability and reusability: Refactoring involves the process of simplifying code structure to make the codebase more readable, even for other developers who will read or use your code. It also often requires breaking down functions or classes into reusable components.
Improves performance: Identifying and improving inefficient algorithms in the refactoring process can lead to more efficient software. This in turn enhances the performance of the application.
Enhances code maintainability: Code refactoring increases code maintainability by breaking down large functions and structuring them logically. When large code functions are broken down into smaller units, they are easier to manage and maintain.
Reduces technical debt: Technical debt is incurred when programmers implement quick solutions or shortcuts during software development which can result in bad code or an unstructured codebase. Regularly refactoring your code helps you reduce technical debt by reducing the accumulation of poorly structured code, eliminating code smells, improving code quality, and making future development smoother and more efficient.
Enhance team collaboration: When a codebase is refactored, it becomes easier to understand and maintain. This fosters better collaboration among team members as they can understand each other's code more easily.

Code Refactoring Tools and Techniques

As a programmer, there are several tools and techniques that you can utilize to improve the quality and maintainability of your code.

Code Refactoring Tools

These tools are software applications that help programmers restructure and improve the quality of their code while maintaining its functionality.

Examples of code refactoring tools include:

CodeRush: CodeRush is a refactoring tool in Visual Studio Code for .NET development. It offers features for enhancing code quality, including code refactoring, code generation, and code analysis to improve code readability. Here's a guide on how to use the CodeRush refactoring assistance on VS Code.
IntelliJ IDEA: IntelliJ IDEA is a popular (IDE) for Java and Kotlin development. It offers a lot of automatic refactoring capabilities like renaming, extracting, and deleting to improve code maintainability and readability.
Visual Studio Code: Visual Studio Code (VS Code) is a popular open-source code editor that supports refactoring methods like the extraction method. VS Code also supports a range of extensions including those for code refactoring.
An example of this is the built-in support for TypeScript and JavaScript refactoring through the TypeScript language service. Also in VS Code, Code Actions (the light bulb icon indicating possible fixes to a code) can provide both refactoring and Quick Fixes for detected issues
ReSharper: ReSharper is a Visual Studio IDE Extension for .NET developers. It offers refactoring features, code analysis, code generation, and code navigation tools.
Using the 'Refactor This' action provides you with a shortcut of all the refactoring available in the current context of your code.

Code Refactoring Techniques

1. Extraction Method

This involves breaking down a large piece of code that performs a specific function into smaller, simpler portions by creating a new method. This improves the code structure, readability, and reuse.

2. Abstraction Method

This involves reorganizing code into a high-level concept to focus on the main idea. This reduces code redundancy, eliminates duplication, and improves code structure.

Code snippet:

import React from 'react';

// Functional component for Shape
function Shape({ type, calculateArea }) {
    return (
        <div>
            <h2>{type}</h2>
            <p>Area: {calculateArea()}</p>
        </div>
    );
}

// Component for Circle
function Circle({ radius }) {
    const calculateArea = () => Math.PI * radius ** 2;
    return <Shape type="Circle" calculateArea={calculateArea} />;
}

// Component for Square
function Square({ sideLength }) {
    const calculateArea = () => sideLength ** 2;
    return <Shape type="Square" calculateArea={calculateArea} />;
}

// Component for Triangle
function Triangle({ base, height }) {
    const calculateArea = () => 0.5 * base * height;
    return <Shape type="Triangle" calculateArea={calculateArea} />;
}

// Main Component
function App() {
    return (
        <div>
            <Circle radius={6} />
            <Square sideLength={4} />
            <Triangle base={3} height={6} />
        </div>
    );
}

export default App;

3. Code Simplification

This involves identifying and simplifying complex functions or unnecessary code and this increases code readability.

Initial code version:

function filterEvenNumbers(arr) {
  let evenNumbers = [];

  for (let i = 0; i < arr.length; i++) {
    if (arr[i] % 2 === 0) {
      evenNumbers.push(arr[i]);
    }
  }

  return evenNumbers;
}

Refactored code:

function filterEvenNumbers(arr) {
  return arr.filter(num => num % 2 === 0);
}

4. Red-Green-Refactor

Steps in Refactoring a Codebase

Following these steps when refactoring a codebase can help you enhance the quality of your code:

1. Understand the codebase
Before refactoring a codebase especially one you are not familiar with, it's important to take out time to understand the existing codebase thoroughly.

It includes familiarizing yourself with the design patterns, coding conventions, architecture, and existing documentation.

Use code analysis tools (SonarQube, Coverity, DeepSource, Codacy, etc) or manual code reviews to identify these code smells.

Consider prioritizing refactoring targets based on factors like how it changes frequently, its impact on the whole software, and the seriousness of the code smell.

Also, follow good practices like writing unit tests, having others review your code, and using automated testing tools (JUnit for Java and pytest for Python for writing unit tests).

Step-by-step guide for using the VS Code Extension - Glean to refactor a React codebase

Here's a step-by-step guide on how to use Glean to refactor a complex codebase directly in your VS Code editor:

Step 1: Open your Next.js or React project in VS Code
Launch Visual Studio Code and open your project.
Step 2: Install Glean extension
Navigate to the VS Code extensions marketplace or press (Ctrl+Shift+X) and type 'glean' in the search box. This will bring up the Glean extension code refactoring tools. Select the first option that comes up and click on the "Install" button.
Step 3: Use Glean refactoring features
Once you've identified areas for refactoring, use Glean's refactorings to make the necessary changes. Here are some examples of refactorings you can perform with Glean:
- A. Extract Component: You can extract a portion of JSX code into a new React component. Select the block of code, click on the light bulb icon, and select the "Extract Component to File" option. A dropdown with a list of the directories you can extract your component to will appear.

B. Conversion: You can seamlessly convert class components to functional components and vice versa. All you need to do is highlight everything in the component file. Next, click the light bulb icon. Select the "Convert Function to Class component" or the "Convert Class to Function component" option depending on whether it's a functional or state component you're converting from.

C. Rename: Use the "Rename" refactoring to quickly rename any state variables, functions, or components throughout your codebase. Highlight the variable you intend to rename, click on the light bulb icon, and then choose the "Rename State" option. This will prompt you to enter the name you want, hit enter and it will rename the state variable for you.

Step 4: Review, test, and commit After refactoring, review your changes to ensure they haven't introduced any bugs. Once you're satisfied with the refactored code, commit your changes to your version control system if you need to.

By following these steps and using Glean's refactoring features, you can effectively refactor a more complex codebase, improving its maintainability and readability.

Some are specifically for different programming languages. You can then sort these results by popularity, category, recently published, and so on.

Always conduct proper research on the particular refactoring tool you intend to use. Check for the number of downloads, ratings, and support that the tool has.

When You Should Consider Refactoring Your Code

Here are some common scenarios when you should consider refactoring your code:

When introducing new features that change an existing code, consider refactoring.
During code reviews, a team member can highlight areas of code that are complex, have code smells, or violate coding standards. This is an ideal time to refactor your code.
If a code is extremely complex or adds to the problem, refactor it to address bugs and errors that will arise during development.

Refactoring a full codebase

The project codebase we'll be refactoring is an invoicing application I recently built using Nextjs, TypeScript, Tailwindcss for styling, and Strapi as the headless CMS.

Here's the GitHub page for the project. Study the codebase, you'll notice that originally only 3 files were used to build the functionalities.

We'll focus on breaking down the code into more manageable pieces, improving readability, and maintaining functionality. Here's how you can approach this:

Refactor the 'InvoiceForm' component

First, we'll refactor the code components for the 'InvoiceForm' component.

We'll be using three techniques to refactor this codebase.

1. Extraction Method
Extract repetitive UI elements into reusable components:

Create a new component for input fields (InputField.tsx):

// components/InputField.tsx
import React, { ChangeEvent } from 'react';

interface InputFieldProps {
  label: string;
  id: string;
  name: string;
  type: string;
  placeholder: string;
  value: string | number;
  onChange: (e: ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) => void;
  required?: boolean;
}

const InputField: React.FC<InputFieldProps> = ({ label, id, name, type, placeholder, value, onChange, required = false }) => (
  <div className="flex flex-col w-[45%] mb-4">
    <label className="block text-gray-700 text-sm font-bold mb-2" htmlFor={id}>
      {label}
    </label>
    <input
      className="shadow appearance-none border rounded w-full py-2 px-3 text-gray-700 leading-tight focus:outline-none focus:shadow-outline"
      id={id}
      name={name}
      type={type}
      placeholder={placeholder}
      onChange={onChange}
      value={value}
      required={required}
    />
  </div>
);

export default InputField;

Create a new component for textarea fields (TextAreaField.tsx):

// components/TextAreaField.tsx
import React, { ChangeEvent } from 'react';

interface TextAreaFieldProps {
  label: string;
  id: string;
  name: string;
  placeholder: string;
  value: string;
  onChange: (e: ChangeEvent<HTMLTextAreaElement>) => void;
  required?: boolean;
}

const TextAreaField: React.FC<TextAreaFieldProps> = ({ label, id, name, placeholder, value, onChange, required = false }) => (
  <div className="flex flex-col w-[45%] mb-4">
    <label className="block text-gray-700 text-sm font-bold mb-2" htmlFor={id}>
      {label}
    </label>
    <textarea
      className="shadow appearance-none border rounded w-full py-2 px-3 text-gray-700 leading-tight focus:outline-none focus:shadow-outline"
      id={id}
      name={name}
      placeholder={placeholder}
      onChange={onChange}
      value={value}
      required={required}
    />
  </div>
);

export default TextAreaField;

2. Abstraction Method
Abstract the form state management logic into a custom hook (useInvoiceForm.tsx):

// hooks/useInvoiceForm.ts
import { useReducer, useEffect } from 'react';
import { Invoice } from '../components/InvoiceForm';

const initialState = {
  name: '',
  senderEmail: '',
  recipientEmail: '',
  shippingAddress: '',
  date: '',
  dueDate: '',
  invoiceNote: '',
  description: '',
  qty: 0,
  rate: 0,
  total: 0,
};

function reducer(state = initialState, { field, value }: { field: string, value: any }) {
  return { ...state, [field]: value };
}

const useInvoiceForm = (selectedInvoice: Invoice | null) => {
  const [formFields, dispatch] = useReducer(reducer, initialState);

  useEffect(() => {
    if (selectedInvoice) {
      for (const [key, value] of Object.entries(selectedInvoice?.attributes)) {
        dispatch({ field: key, value });
      }
    } else {
      for (const [key, value] of Object.entries(initialState)) {
        dispatch({ field: key, value });
      }
    }
  }, [selectedInvoice]);

  useEffect(() => {
    const { qty, rate } = formFields;
    const total = qty * rate;
    dispatch({ field: 'total', value: total });
  }, [formFields.qty, formFields.rate]);

  const handleInputChange = (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) => {
    const { name, value } = e.target;
    dispatch({ field: name, value });
  };

  return { formFields, handleInputChange };
};

export default useInvoiceForm;

3. Code Simplification
Simplify the 'InvoiceForm' component using the new reusable components and the custom hook:

// components/InvoiceForm.tsx
'use client';
import React from 'react';
import axios from 'axios';
import InputField from './InputField';
import TextAreaField from './TextAreaField';
import useInvoiceForm from '../hooks/useInvoiceForm';

interface InvoiceFormProps {
  onClose: () => void;
  setInvoices: React.Dispatch<React.SetStateAction<Invoice[]>>;
  selectedInvoice: Invoice | null;
}

interface Invoice {
  id: number;
  name: string;
  attributes: any;
  senderEmail: string;
  recipientEmail: string;
  shippingAddress: string;
  date: string;
  dueDate: string;
  invoiceNote: string;
  description: string;
  qty: number;
  rate: number;
  total: number;
}

const InvoiceForm: React.FC<InvoiceFormProps> = ({ onClose, setInvoices, selectedInvoice }) => {
  const { formFields, handleInputChange } = useInvoiceForm(selectedInvoice);

  const handleSendInvoice = async () => {
    try {
      const { name, senderEmail, recipientEmail, date, dueDate, shippingAddress, invoiceNote, description, qty, rate, total } = formFields;

      if (selectedInvoice) {
        const data = await axios.put(`http://localhost:1337/api/invoices/${selectedInvoice.id}`, {
          data: { name, senderEmail, recipientEmail, shippingAddress, dueDate, date, invoiceNote, description, qty, rate, total },
        });
        setInvoices((prev) => prev.map((inv) => (inv.id === selectedInvoice.id ? { ...inv, ...formFields } : inv)));
        window.location.reload();
      } else {
        const { data } = await axios.post('http://localhost:1337/api/invoices', {
          data: { name, senderEmail, recipientEmail, shippingAddress, dueDate, date, invoiceNote, description, qty, rate, total },
        });
        setInvoices((prev) => [...prev, data.data]);
      }

      onClose();
    } catch (error) {
      console.error(error);
    }
  };

  return (
    <main className="fixed top-0 z-50 left-0 w-screen h-screen flex justify-center items-center bg-black bg-opacity-50">
      <section className="relative lg:px-10 px-6 py-8 lg:mt-8 lg:w-[60%] bg-white shadow-md rounded px-8 pt-2 pb-8 mb-4">
        <form className="pt-4">
          <h2 className="text-lg font-medium mb-4">{selectedInvoice ? 'Edit Invoice' : 'Create Invoice'}</h2>
          <button className="absolute top-2 right-8 font-bold text-black cursor-pointer text-2xl" onClick={onClose}>
            &times;
          </button>
          <div className="mb-4 flex flex-row justify-between">
            <InputField
              label="Your name"
              id="name"
              name="name"
              type="text"
              placeholder="Sender's name"
              value={formFields.name}
              onChange={handleInputChange}
              required
            />
            <InputField
              label="Your email address"
              id="senderEmail"
              name="senderEmail"
              type="email"
              placeholder="Sender's email"
              value={formFields.senderEmail}
              onChange={handleInputChange}
              required
            />
            <InputField
              label="Recipient's Email"
              id="recipientEmail"
              name="recipientEmail"
              type="email"
              placeholder="Client's email address"
              value={formFields.recipientEmail}
              onChange={handleInputChange}
              required
            />
          </div>

          <div className="mb-4 flex flex-row justify-between">
            <InputField
              label="Date"
              id="date"
              name="date"
              type="date"
              value={formFields.date}
              onChange={handleInputChange}
              required placeholder={''}
            />

            <InputField
              label="Due Date"
              id="dueDate"
              name="dueDate"
              type="date"
              value={formFields.dueDate}
              onChange={handleInputChange}
              required
              placeholder={''}
            />
          </div>

          <div className="mb-4 flex flex-row justify-between">
            <TextAreaField
              label="Shipping Address"
              id="shippingAddress"
              name="shippingAddress"
              placeholder="Office address of recipient"
              value={formFields.shippingAddress}
              onChange={handleInputChange}
              required
            />
            <TextAreaField
              label="Invoice Note"
              id="invoiceNote"
              name="invoiceNote"
              placeholder="Account details"
              value={formFields.invoiceNote}
              onChange={handleInputChange}
              required
            />
          </div>

          <div className="flex justify-center items-center">
            <InputField
              label="Invoice Item"
              id="description"
              name="description"
              type="text"
              placeholder="Description of Item"
              value={formFields.description}
              onChange={handleInputChange}
              required
            />
            <InputField
              label="Qty"
              id="qty"
              name="qty"
              type="number"
              placeholder="Quantity of item"
              value={formFields.qty}
              onChange={handleInputChange}
              required
            />
            <InputField
              label="Rate"
              id="rate"
              name="rate"
              type="number"
              placeholder="Price of item"
              value={formFields.rate}
              onChange={handleInputChange}
              required
            />

            <div className="block text-gray-700 text-sm font-bold mb-2 w-full mr-3">
              <label>Total</label>
              <div className="shadow appearance-none border rounded w-full py-2 px-3 text-gray-700 mb-3 leading-tight">
                {formFields.total}
              </div>
            </div>
          </div>

          <hr className="mt-5 border-1" />

          <div className="mt-4 flex justify-center">
            <button
              type="button"
              className="py-2 px-4 border border-transparent shadow-sm text-sm font-medium rounded-md text-white bg-green-600 hover:bg-green-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-green-500"
              onClick={handleSendInvoice}
            >
              {selectedInvoice ? 'Update Invoice' : 'Send Invoice'}
            </button>
          </div>
        </form>
      </section>
    </main>
  );
};

export default InvoiceForm;

Explanation

Refactor the 'Invoices' component

Now let's refactor the Invoices component and break it down.

1. Extraction Method
Extract the invoice header and invoice page layout into separate components.

Create the InvoiceHeader.tsx component.

// components/InvoiceHeader.tsx
import React from 'react';

interface InvoiceHeaderProps {
  onOpen: () => void;
}

const InvoiceHeader: React.FC<InvoiceHeaderProps> = ({ onOpen }) => (
  <div className="w-[65%] flex flex-row justify-between items-center mb-6">
    <h1 className="text-2xl font-bold">Invoices</h1>

    <button
      className="bg-green-500 hover:bg-green-700 text-white font-bold py-2 px-4 rounded"
      onClick={onOpen}>
      Create Invoice
    </button>
  </div>
);

export default InvoiceHeader;

Create the InvoiceLayout.tsx component.

// components/InvoiceLayout.tsx
import React from 'react';
import { Invoice } from '../types';
import useInvoiceDownload from '@/hooks/useInvoiceDownload';

interface InvoiceLayoutProps {
    invoices: Invoice[];
    onEdit: (invoice: Invoice) => void;
    onDelete: (id: number) => void;
    onDownload: (invoice: Invoice) => void;
}

const InvoiceLayout: React.FC<InvoiceLayoutProps> = ({ invoices, onEdit, onDelete, onDownload }) => (
    <div className="w-[70%]">
        <div className="px-5 py-5 mx-auto">
          {invoices.map((invoice) => (
                <>
                    <div className="flex flex-wrap border-t-2 border-b-2 border-gray-200 border-opacity-60" key={invoice.id}>
                        <div className="lg:w-1/3 md:w-full px-8 py-6 border-opacity-60">
                            <div>
                                <h2 className="text-base text-gray-900 font-medium mb-1">Issued:</h2>
                                <p className="leading-relaxed text-sm mb-4">{invoice.attributes.date}</p>
                            </div>
                            <div className="mt-12">
                                <h2 className="text-base text-gray-900 font-medium">Due:</h2>
                                <p className="leading-relaxed text-sm mb-4">{invoice.attributes.dueDate}</p>
                            </div>
                        </div>

                        <div className="lg:w-1/3 md:w-full px-8 py-6 border-l-2 border-gray-200 border-opacity-60">
                            <h2 className="text-base text-gray-900 font-medium mb-2">Billed To:</h2>
                            <div className="">
                                <h2 className=" text-gray-900 text-sm mb-1 font-medium">Recipient's Email</h2>
                                <p className="leading-relaxed text-sm mb-5">{invoice.attributes.recipientEmail}</p>
                            </div>

                            <div>
                                <h2 className=" text-gray-900 text-sm mb-1 font-medium">Shipping Address</h2>
                                <p className="leading-relaxed text-sm mb-4">{invoice.attributes.shippingAddress}</p>
                            </div>
                        </div>

                        <div className="lg:w-1/3 md:w-full px-8 py-6 border-l-2 border-gray-200 border-opacity-60">
                            <h2 className="text-base text-gray-900 font-medium mb-2">From:</h2>
                            <div className="">
                                <h2 className=" text-gray-900 text-sm mb-1 font-medium">Sender's Name</h2>
                                <p className="leading-relaxed text-sm mb-5">{invoice.attributes.name}</p>
                            </div>

                            <div>
                                <h2 className=" text-gray-900 text-sm mb-1 font-medium">Sender's Email</h2>
                                <p className="leading-relaxed text-sm mb-4">{invoice.attributes.senderEmail}</p>
                            </div>
                        </div>
                    </div>

                    <div className="w-full px-5 py-12 mx-auto">
                        <div className="flex flex-row justify-between border-b-2 border-gray-300">
                            <div>
                                <h2 className="text-lg font-medium text-gray-700 mb-2">Invoice Item</h2>
                            </div>

                            <div className="flex flex-row mb-2">
                                <p className="ml-2 text-lg font-medium text-gray-800">Qty</p>
                                <p className="ml-[6rem] text-lg font-medium text-gray-800">Rate</p>
                                <p className="ml-[6rem] text-lg font-medium text-gray-800">Total</p>
                            </div>
                        </div>

                        <div className="flex flex-row justify-between mt-4">
                            <div>
                                <h2 className="text-base text-gray-700 mb-4">{invoice.attributes.description}</h2>
                            </div>

                            <div className="flex flex-row mb-4">
                                <p className="ml-2 text-base text-gray-800">{invoice.attributes.qty}</p>
                                <p className="ml-[6rem] text-base text-gray-800">${invoice.attributes.rate}</p>
                                <p className="ml-[6rem] text-base text-gray-800">${invoice.attributes.total}</p>
                            </div>
                        </div>

                        <div className="grid justify-end pt-[2.5rem]">
                            <div className="flex flex-row justify-between">
                                <div>
                                    <h2 className="text-lg font-medium text-gray-700 mb-4">Tax (0%)</h2>
                                </div>

                                <div className="flex flex-row">
                                    <p className="ml-[10rem] text-base text-gray-800">0.00</p>
                                </div>
                            </div>

                            <div className="flex flex-row justify-between border-y-2 border-green-400">
                                <div className="pt-4">
                                    <h2 className="text-lg font-medium text-gray-700 mb-4">Amount due:</h2>
                                </div>

                                <div className="flex flex-row pt-4">
                                    <p className="ml-[10rem] text-lg font-medium text-gray-800">${invoice.attributes.total}.00</p>
                                </div>
                            </div>
                        </div>
                    </div>

                    <div className="flex flex-row justify-between w-full mt-1">
                        <div>
                            <button className="bg-blue-500 px-2 py-2 rounded text-white hover:bg-blue-600"
                                onClick={() => onDownload(invoice)}>
                                Download invoice
                            </button>

                            <button className="bg-green-500 px-2 py-2 rounded text-white hover:bg-green-600 ml-4"
                                onClick={() => onEdit(invoice)}>
                                Edit invoice
                            </button>
                        </div>

                        <div className="flex justify-end bg-red-400 px-2 py-2 rounded text-white hover:bg-red-500">
                            <button 
                                onClick={() => onDelete(invoice.id)}>
                                Delete invoice
                            </button>
                        </div>
                    </div>
                </>
            ))}
        </div>
    </div>
);

export default InvoiceLayout;

2. Abstraction Method
Abstract the form state management logic into a custom hook (useInvoices.tsx).

// hooks/useInvoices.ts
import { useState, useEffect } from 'react';
import axios from 'axios';
import { Invoice } from '../types';

const useInvoices = () => {
  const [invoices, setInvoices] = useState<Invoice[]>([]);
  const [selectedInvoice, setSelectedInvoice] = useState<Invoice | null>(null);
  const [isModalOpen, setIsModalOpen] = useState(false);

  useEffect(() => {
    const fetchInvoices = async () => {
      try {
        const { data } = await axios.get('http://localhost:1337/api/invoices');
        setInvoices(data.data);
      } catch (error) {
        console.error(error);
      }
    };

    fetchInvoices();
  }, []);

  const handleDelete = async (id: number) => {
    try {
      alert("Are you sure you want to delete this invoice?")
      await axios.delete(`http://localhost:1337/api/invoices/${id}`);
      setInvoices(invoices.filter((invoice) => invoice.id !== id));
    } catch (error) {
      console.error(error);
    }
  };

  return {
    invoices,
    setInvoices,
    selectedInvoice,
    setSelectedInvoice,
    isModalOpen,
    setIsModalOpen,
    handleDelete,
  };
};

export default useInvoices;

Create a custom hook (useInvoiceDownload.tsx) for the download functionality:

// hooks/useInvoiceDownload.ts
import jsPDF from 'jspdf';
import autoTable from 'jspdf-autotable';
import { Invoice } from '../types';

const useInvoiceDownload = () => {
  const downloadInvoice = (invoice: Invoice) => {
    const doc = new jsPDF();

    doc.setFontSize(18);
    doc.text('Invoice', 14, 22);

    autoTable(doc, {
      startY: 30,
      head: [['Name', 'Sender Email', 'Recipient Email', 'Date', 'Due Date', 'Total']],
      body: [
        [
          invoice.attributes.name,
          invoice.attributes.senderEmail,
          invoice.attributes.recipientEmail,
          invoice.attributes.date,
          invoice.attributes.dueDate,
          invoice.attributes.total,
        ],
      ],
    });

    doc.save(`invoice_${invoice.id}.pdf`);
  };

  return { downloadInvoice };
};

export default useInvoiceDownload;

Create a types file for common types.

// types.tsx
export interface Invoice {
  id: number;
  attributes: {
    name: string;
    senderEmail: string;
    recipientEmail: string;
    shippingAddress: string;
    date: string;
    dueDate: string;
    invoiceNote: string;
    description: string;
    qty: number;
    rate: number;
    total: number;
  };
}

3. Code Simplification
Refactor the main Invoice component by refactoring the Invoices component using the new reusable components and the custom hook:

// components/Invoices.tsx
'use client';
import React from 'react';
import InvoiceHeader from './InvoiceHeader';
import InvoiceLayout from './InvoiceLayout';
import InvoiceForm from './InvoiceForm';
import useInvoices from '../hooks/useInvoices';
import useInvoiceDownload from '../hooks/useInvoiceDownload';

const Invoices: React.FC = () => {
  const {
    invoices,
    setInvoices,
    selectedInvoice,
    setSelectedInvoice,
    isModalOpen,
    setIsModalOpen,
    handleDelete,
  } = useInvoices();

  const handleEdit = (invoice: Invoice) => {
    setSelectedInvoice(invoice);
    setIsModalOpen(true);
  };

  const { downloadInvoice } = useInvoiceDownload();

  return (
    <>
      <div className="flex flex-col items-center justify-center">
        <InvoiceHeader onOpen={() => setIsModalOpen(true)} />

        {isModalOpen && (
          <InvoiceForm
            onClose={() => setIsModalOpen(false)}
            setInvoices={setInvoices}
            selectedInvoice={selectedInvoice}
          />
        )}

        {invoices.length === 0 ? (
          <p>No invoice yet.</p>
        ) : (
          <InvoiceLayout invoices={invoices} onEdit={handleEdit} onDelete={handleDelete} onDownload={downloadInvoice} />
        )}
      </div>
    </>
  );
};

export default Invoices;

We were able to refactor the full codebase of this web application using the refactoring techniques explained, making it reusable, readable, and maintainable without changing its functionalities.

Conclusion

5 Considerations When Choosing a Front-end Framework

Juliet Ofoegbu — Thu, 27 Jun 2024 10:06:06 +0000

Your role in choosing the proper front-end framework is crucial to the success of your project. With many options available, each with its own set of advantages and challenges, understanding the key factors to consider is vital to make an informed decision.

This article will examine five essential considerations to help front-end developers, technical leads, CTOs, companies, startups, and so on, navigate this decision-making process. By evaluating project requirements, community support, performance, scalability, and the learning curve, you will understand how to make an informed decision to ensure that your chosen framework aligns with your front-end development goals.

Let's get started!

1. Project Requirements

As a key player in your project, understanding its specific requirements is paramount when it comes to selecting a front-end framework.

Every project has specific requirements. Your project can be a simple website or a complex web application, and each has different requirements. So, your chosen framework must align with your project's specific requirements.

Here are a few key elements to consider:

1. Functionality Needs:

What is your project about? Does it require features like real-time data updates, complex state management, e-commerce functionalities, applicant or goods tracking, or a combination?

Consider using frameworks that have been proven to effectively handle the features you want your application to have. For example, you can decide to use Astro or React for e-commerce applications. Both support component-based architecture, making it easier to manage and scale complex e-commerce sites. With these frameworks, you can build reusable components for product listings, shopping carts, and checkout processes.

2. Application Complexity:

When building simple applications like a simple website, consider using lightweight frameworks like Vue.js, as they are easy to use and flexible. Svelte is also a good example of a lightweight framework that builds on HTML and has a small bundle size.

For large-scale, complex applications, however, you might consider using React or Angular due to their extensive ecosystem.

For large-scale, complex applications however, you might consider using React or Angular due to their extensive ecosystem.

2. Community Support and Ecosystem

The strength of a framework's community support and ecosystem is a significant factor to consider when choosing a front-end framework, and here's why:

1. Community Size, Support, and Troubleshooting:

A framework with a large and active community can prove very useful. This is because more resources, such as tutorials, documentation, and forums, are available to help you overcome challenges you might face when using the framework.

It also means easier troubleshooting. There might be issues you'll face that have most likely been encountered and solved by others. You can find solutions to these problems on a variety of platforms, including Stack Overflow, Discord, GitHub, and Reddit.

For example, frameworks such as React and Vue have large, active communities that help members face challenges with the framework, and they also actively contribute to the framework's development and maintenance.

2. Library and Tooling Ecosystem:

One critical factor to consider when choosing a framework is its ecosystem of libraries and tools that can accelerate front-end development. These third-party resources, such as libraries, plugins, components, and tools, are integral to popular frameworks and greatly enhance productivity.

They can also save you time; you won't have to build everything from scratch. Vue.js, for example, has an official library called 'Vuex' that manages states in Vue.js applications.

3. Regular Updates and Long-term Viability:

Frameworks with significant community support are more likely to receive regular updates and improvements as members suggest improvements.

These updates ensure the framework is updated with industry changes and security standards. A framework with a continuous release cycle gives its users confidence in its long-term viability.

3. Performance

Performance is an important consideration when selecting a front-end framework because it directly affects the user's experience and the overall efficiency of your web application. Here's why performance is essential when considering a framework:

1. Load Times:

Studies show that the average human attention span is around 8 seconds, so within this short time frame, you need to retain your users' attention when they visit your web application/website. You can't retain their attention if your website lags or loads slowly because slow load times lead to an increase in bounce rate.

Faster load times improve user retention and provide a seamless experience. Frameworks like React, Astro, and Vue.js are known for their efficient rendering and quick load times, which help keep users engaged.

2. Efficiency in Rendering:

How a framework handles rendering might impact your project's responsiveness. For example, frameworks that use virtual DOM, like React, can efficiently update and render components, increasing performance. Learn about How to Build a To-Do List Application with Strapi and React.js.

Also, frameworks that support Server-Side Rendering (SSR), such as Next.js (built on React) or Nuxt.js (built on Vue.js), can improve performance by pre-rendering content on the server, thereby reducing the load on the client's browser.

3. Optimization Ability:

Code optimization results in high application performance. Performance optimization features like code splitting, lazy loading, and tree shaking help reduce the initial load and improve performance. React, Angular and Svelte offer built-in tools that can help you optimize your application's performance.

4. Scalability and Maintainability

Scalability refers to the ability of a system to handle an increasing amount of work/load or its ability to expand to handle that growth.

Maintainability refers to how easy it is to maintain a system, such as fixing bugs, adding new features, and updating it over time.

When selecting a front-end framework, you must consider how well it handles scalability and maintainability to ensure your project can grow and adapt quickly over time.

1. Scalability:

As your project's features and user base grow, you'll need a framework to handle the additional workload or complexity. Frameworks like Angular are designed to support large-scale applications.

2. Code Organization:

Nobody likes a messy codebase, especially when you have to refactor one you didn't initially work on. So, it's essential to keep an effective, organized codebase, as this helps maintain your project.

Vue.js is a framework that supports modularity and clear separation of concerns. This makes it easy to manage the codebase and scale, helping to maintain code quality as your project grows.

3. Component Reusability:

Reusing components improves scalability and maintainability, as it saves you the trouble of writing the same code repeatedly. React's component-based architecture enables developers to create reusable UI components, making it easier to maintain the application without having to rewrite a lot of code.

5. Learning curve

The learning curve of a front-end framework is also an important issue, especially when assessing how much time and effort will be required to become proficient in using it.

When working on a new project that requires you to use a framework with which you are unfamiliar, you'll want one that's easy to learn and quick to implement.

1. Ease of learning:

Frameworks like Vue.js have a smooth learning curve, allowing beginner developers to catch up quickly. This can be especially useful if you're transitioning from other technologies and for teams that are onboarding new members. Angular, on the other hand, has a steep learning curve, which can be difficult for a beginner to fully understand at first.

2. Quality Documentation and Tutorials:

The availability of exceptionally high-quality documentation impacts a framework's learning curve. React, for example, has significant documentation and various quality learning resources to help developers understand and use the framework more effectively.

3. Community and Support:

A framework with an active community can help developers learn more effectively. Members of a framework's forum and discussion groups like Discord can help developers resolve issues and share best practices. Angular and React are examples of frameworks that provide excellent community support. You can learn how to build a news app using Angular and Strapi.

Switching frameworks: Why and When?

Sometimes, even after careful consideration, you might need to switch front-end frameworks. Switching can happen due to changing project requirements, limitations of the current framework, or new technological advancements. Knowing why and when to switch keeps your project running smoothly and efficiently.

Scenarios that may require switching frameworks

1. Performance Issues:
If your current framework is causing slow load times or poor performance, it may be time to consider switching. Also, related to performance issues, when your application grows, the initial framework or performance optimization methods might not handle increasing data or user loads efficiently. Switching to a more scalable framework can help manage larger applications better.

Let's take an example.

When your e-commerce application starts as a small online store, you might use a lightweight framework like Vue.js due to its simplicity. However, as your business grows and you add more features like real-time inventory updates, good tracking, and customer reviews, Vue.js might need help to efficiently handle the increasing data and user loads. In this case, switching to a more scalable framework like Angular might come in handy to help you better manage the more extensive application. You can learn more Vue.js on how to build a ticketing app using Vue.js and Strapi.

2. Maintenance Challenges:
Suppose the framework you are using is no longer actively being maintained or updated. In that case, you must switch to a more up-to-date, reliable option to avoid security challenges and ensure ongoing support.

3. Project Requirements:
Switching may be necessary if your project requires additional features that are better supported by a different framework. For instance, switching to Next.js from React because of its better server-side rendering capabilities can benefit your project.

Pros and Cons of Switching Frameworks

Switching frameworks mid-development or after production comes with some benefits and some setbacks.

Pros of Switching Frameworks
Here are some of the advantages of switching frameworks:

Modern frameworks can improve application performance. Switching from outdated to modern frameworks enables your application to handle larger loads more efficiently and improve your application's performance.
New frameworks often include the latest features that can enhance functionality. For example, frameworks actively maintained receive regular security updates, enabling them to bypass certain challenges that older, outdated frameworks may have.
Switching to a framework with a larger, active community can provide you with better support and faster issue resolution.

Cons of Switching Frameworks
As with everything that has its advantages, switching frameworks also has disadvantages.

Migrating to a new framework can be time-consuming and expensive. Companies may need to hire a developer proficient in that framework to rewrite or refactor existing code.
For individuals, it will require learning new concepts and utilizing developer resources relating to the new framework.
Switching to a new framework requires time to adapt to the framework's tools and workflows, which can temporarily slow down front-end development and production.
Switching to a new framework might introduce new bugs and issues to the codebase that must be resolved before production.

Conclusion

Each framework has unique strengths and challenges, so it is essential to assess these considerations against your project's specific needs.

Thoroughly evaluating these factors is a sign of diligence and responsibility. It ensures that the framework you choose not only meets your project demands but also fosters the future growth of your project.