full stack - freeCodeCamp.org

How to Build a Fashion App That Helps You Organize Your Wardrobe

Mokshita V P — Tue, 14 Apr 2026 16:26:39 +0000

I used to spend too long deciding what to wear, even when my closet was full.

That frustration made the problem feel very clear to me: it was not about having fewer clothes. It was about having better organization, better visibility, and better guidance when making outfit decisions.

So I built a fashion web app that helps users organize their wardrobe, get outfit suggestions, evaluate shopping decisions, and improve recommendations over time using feedback.

In this article, I’ll walk through what the app does, how I built it, the decisions I made along the way, and the challenges that shaped the final result.

Table of Contents
What the App Does
Why I Built It
Tech Stack
Product Walkthrough (What Users See)
How I Built It
Challenges I Faced
What I Learned
What I Want to Improve Next
Future Improvements
Conclusion

What the App Does

At a high level, the app combines six core capabilities:

Wardrobe management
Outfit recommendations
Shopping suggestions
Discard recommendations
Feedback and usage tracking
Secure multi-user accounts

Users can upload clothing items, explore suggested outfits, and mark recommendations as helpful or not helpful. They can also rate outfits and track whether items are worn, kept, or discarded.

That feedback becomes structured data for improving future recommendation quality.

Why I Built It

I wanted to create something that felt personal and actually useful. A lot of fashion apps look polished, but they do not always help with everyday decisions. My goal was to build something that could make wardrobe management easier and outfit selection less overwhelming. The app needed to do three things well:

store each user’s wardrobe data
personalize recommendations
learn from user feedback over time .

That feedback loop mattered to me because it makes the app feel more alive instead of static.

Tech Stack

Here are the tools I used to built the app:

Frontend: React + Vite
Backend: FastAPI
Database: SQLite (local development)
Background jobs: Celery + Redis
Authentication: JWT (access + refresh token flow)
Deployment support: Docker and GitHub Codespaces

This ended up giving me a pretty modular setup, which helped a lot as features started increasing: fast frontend iteration, clean API boundaries, and room to evolve recommendations separately from UI.

Product Walkthrough (What Users See)

1. Onboarding and Account Setup

To start using the app, a user needs to register, verify their email, and complete some profile basics.

Each account is isolated, so wardrobe history and recommendations stay user-specific.

In this onboarding screen above, you can see account creation, email verification, and profile fields for body shape, height, weight, and style preferences.

2. Wardrobe Upload

Users can upload clothing images .

Image analysis labels each item and makes it searchable for recommendations. The wardrobe upload form shows image analysis results with category, dominant color, secondary color, and pattern details listed.

3. Outfit Recommendations

Users can request recommendations, then rate outputs.

Above you can see the outfit recommendation dashboard that shows ranked outfit cards with feedback and rating actions. Recommendations are ranked by a weighted scoring model.

4. Shopping and Discard Assistants

The app evaluates new items against existing wardrobe data and flags low-value wardrobe items that may be worth removing.

You can see the recommendation scores, written reasons (not just a binary decision), and styling guidance for each item above. It also features a "how to style it" incase the user still wants to keep the item.

How I Built It

1. Frontend Setup (React + Vite)

I used React + Vite because I wanted fast iteration and a clean component structure.

The frontend is split into feature areas like onboarding, wardrobe management, outfits, shopping, and discarded-item suggestions. I also keep API calls in a service layer so the UI components stay focused on rendering and interaction.

The snippet below is a simplified example of the API service pattern used in the app. It is not meant to be copy-pasted as-is, but it shows the same structure the frontend uses when talking to the backend.

Example API client pattern:

export async function getOutfitRecommendations(userId, params = {}) {
  const query = new URLSearchParams(params).toString();
  const url = `/users/\({userId}/outfits/recommend\){query ? `?${query}` : ""}`;

  const response = await fetch(url, {
    headers: {
      Authorization: `Bearer ${localStorage.getItem("access_token")}`,
    },
  });

  if (!response.ok) {
    throw new Error("Failed to fetch outfit recommendations");
  }

  return response.json();
}

Here's what's happening in that snippet:

URLSearchParams builds optional query strings like occasion, season, or limit.
The request path is user-scoped, which keeps each user’s recommendations isolated.
The Authorization header sends the access token so the backend can verify the session.
The response is checked before parsing so the UI can surface a useful error if the request fails.

This pattern kept the frontend simple and reusable as the number of API calls grew.

2. Backend Architecture with FastAPI

The backend is organized around clear route groups:

auth routes for register, login, refresh, logout, and sessions
user analysis routes
wardrobe CRUD routes
recommendation routes for outfits, shopping, and discard analysis
feedback routes for ratings and helpfulness signals

One of the most important design choices was enforcing ownership checks on user-scoped resources. That prevented one user from accessing another user’s wardrobe or feedback data.

The backend snippet below is another simplified example from the app’s route layer. It shows the request validation and orchestration logic, while the actual scoring work stays in the recommendation service.

@app.get("/users/{user_id}/outfits/recommend")
def recommend_outfits(user_id: int, occasion: str | None = None, season: str | None = None, limit: int = 10):
    user = get_user_or_404(user_id)
    wardrobe_items = get_user_wardrobe(user_id)

    if len(wardrobe_items) < 2:
        raise HTTPException(status_code=400, detail="Not enough wardrobe items")

    recommendations = outfit_generator.generate_outfit_recommendations(
        wardrobe_items=wardrobe_items,
        body_shape=user.body_shape,
        undertone=user.undertone,
        occasion=occasion,
        season=season,
        top_k=limit,
    )

    return {"user_id": user_id, "recommendations": recommendations}

Here's how to read that code:

get_user_or_404 loads the profile data needed for personalization.
get_user_wardrobe fetches only the current user’s items.
The minimum wardrobe check prevents the recommendation logic from running on incomplete data.
generate_outfit_recommendations handles the scoring logic separately, which keeps the route handler small and easier to test.
The response returns the results in a shape the frontend can consume directly.

That separation helped keep the API layer readable while the recommendation logic stayed isolated in its own service.

3. Recommendation Logic

I intentionally started with deterministic rules before introducing heavy ML. That made behavior easier to debug and explain.

The outfit recommender scores combinations using weighted signals:

$$\text{outfit score} = 0.4 \cdot \text{color harmony} + 0.4 \cdot \text{body-shape fit} + 0.2 \cdot \text{undertone fit}$$

The snippet below is a simplified example from the recommendation engine. It shows how the app combines multiple signals into a single score:

def score_outfit(combo, user_context):
    color_score = color_harmony.score(combo)
    shape_score = body_shape_rules.score(combo, user_context.body_shape)
    undertone_score = undertone_rules.score(combo, user_context.undertone)

    total = 0.4 * color_score + 0.4 * shape_score + 0.2 * undertone_score
    return round(total, 3)

The logic behind this approach is straightforward:

color harmony helps the outfit feel visually coherent
body-shape scoring helps the outfit feel flattering
undertone scoring helps the colors work better with the user’s profile

I used a similar structure for discard recommendations and shopping suggestions, but with different factors and thresholds.

4. Authentication and Secure Multi-user Design

Security was one of the most important parts of this build.

I implemented:

short-lived access tokens
refresh tokens with JTI tracking
token rotation on refresh
session revocation (single session and all sessions)
email verification and password reset flows

The snippet below is a simplified example of the refresh-token lifecycle used in the app. It shows the important control points rather than every helper function:

def refresh_access_token(refresh_token: str):
    payload = decode_jwt(refresh_token)
    jti = payload["jti"]

    token_record = db.get_refresh_token(jti)
    if not token_record or token_record.revoked:
        raise AuthError("Invalid refresh token")

    new_refresh, new_jti = issue_refresh_token(payload["sub"])
    token_record.revoked = True
    token_record.replaced_by_jti = new_jti

    new_access = issue_access_token(payload["sub"])
    return {"access_token": new_access, "refresh_token": new_refresh}

What this code is doing:

It decodes the refresh token and looks up its JTI in the database.
It rejects reused or revoked sessions, which helps prevent replay attacks.
It rotates the refresh token instead of reusing it.
It issues a fresh access token so the session stays valid without forcing the user to log in again.

This design made multi-device sessions safer and gave me server-side control over logout behavior.

5. Background Jobs for Long-running Operations

Image analysis can be expensive, especially when the app needs to classify clothing, analyze colors, and estimate body-shape-related signals. To keep the request path responsive, I added Celery + Redis support for background tasks.

That gave the app two modes:

synchronous processing for simpler local development
queued processing for heavier or slower jobs

That tradeoff mattered because it let me keep the developer experience simple without blocking the app during more expensive work.

6. Data Model and Feedback Capture

A recommendation system only improves if it captures the right signals.

So I added dedicated feedback tables for:

outfit ratings (1-5 + optional comments)
recommendation helpful/unhelpful feedback
item usage actions (worn/kept/discarded)

Here is the shape of one of those models:

class RecommendationFeedback(Base):
    __tablename__ = "recommendation_feedback"

    id = Column(Integer, primary_key=True)
    user_id = Column(Integer, ForeignKey("users.id"), nullable=False)
    recommendation_type = Column(String(50), nullable=False)
    recommendation_id = Column(Integer, nullable=False)
    helpful = Column(Boolean, nullable=False)
    created_at = Column(DateTime, default=datetime.utcnow)

How to read this model:

user_id ties feedback to the person who gave it.
recommendation_type tells me whether the feedback belongs to outfits, shopping, or discard suggestions.
recommendation_id identifies the exact recommendation.
helpful stores the user’s direct response.
created_at makes it possible to analyze feedback trends over time.

This part of the system gives the app a real learning foundation, even though the feedback-to-model-update loop is still a future improvement.

Challenges I Faced

This was the section that taught me the most.

1. Image-heavy endpoints were slower than I wanted

The analyze and wardrobe upload flows were doing a lot of work at once: image validation, classification, color extraction, storage, and database writes.

At first, that made the request flow feel heavier than it should have.

What I changed:

I bounded concurrent image jobs so the app wouldn't try to do too much at once.
I separated slower jobs into background processing where possible.
I used load-test results to confirm which endpoints were actually expensive.

The practical effect was that heavy image requests stopped competing with each other so aggressively. Instead of letting many expensive tasks pile up inside the same request cycle, I limited the active work and pushed slower operations into the queue when needed.

Why this fixed it:

Bounding concurrency prevented the system from overloading CPU-bound tasks.
Moving expensive work into async jobs kept the main request/response cycle more responsive.
Load testing gave me evidence instead of guesswork, so I could tune the system based on real performance behavior.

In other words, I didn't just “optimize” the endpoint in theory. I changed the execution model so expensive analysis could not block every other request behind it.

2. JWT sessions needed real server-side control

A basic JWT setup is easy to get working, but it becomes less useful if you cannot revoke sessions or manage multiple devices cleanly.

What I changed:

I stored refresh tokens in the database.
I tracked token JTI values.
I rotated refresh tokens when users refreshed their session.
I added endpoints for logging out a single session or all sessions.

The important shift here was moving from “token exists, therefore session is valid” to “token exists, matches the database record, and has not been revoked or replaced.” That gave the server the authority to invalidate old sessions immediately.

Why this fixed it:

Server-side token tracking made revocation possible.
Rotation reduced the chance of token reuse.
Session management became visible to the user, which made the app feel more trustworthy.

This is what made logout-all and multi-device management work in a real way instead of just being cosmetic UI actions.

3. User data isolation had to be explicit

Because this is a multi-user app, I had to be careful that one account could never accidentally see another account’s wardrobe data.

What I changed:

I added ownership checks to user-scoped routes.
I kept all wardrobe and feedback queries filtered by user_id.
I used encrypted image storage instead of exposing raw paths.

In practice, this meant every route had to ask the same question: “Does this user own the resource they are trying to access?” If the answer was no, the request stopped immediately.

Why this fixed it:

Ownership checks made data access rules explicit.
User-filtered queries prevented accidental cross-account reads.
Encrypted storage improved privacy and reduced the risk of exposing image data directly.

That combination is what kept wardrobe data, feedback history, and images separated correctly across accounts.

The app includes the frontend, backend, Redis, Celery worker, and Celery Beat, so the first challenge was making the setup feel reproducible instead of fragile.

What I changed:

I defined the stack in Docker Compose.
I documented the required environment variables.
I kept the dev stack aligned with how the app runs in practice.

This removed a lot of setup ambiguity. Instead of asking someone to manually figure out how the frontend, backend, Redis, and workers fit together, I made the stack describe itself.

Why this fixed it:

Docker let contributors start the project with fewer manual steps.
Clear environment configuration reduced setup mistakes.
Matching the stack to the architecture made the app easier to understand and test.

That was important because the app depends on several moving parts, and the simplest way to make the project approachable was to make startup behavior predictable.

What I Learned

This project taught me a few important lessons:

Small features become much more valuable when they work together.
Feedback data is one of the strongest signals for improving recommendations.
Clean data modeling matters a lot when multiple users are involved.
Docker and clear setup instructions make a project much easier for other people to try.

I also learned that a project does not need to be huge to be useful. A focused app that solves one problem well can still feel meaningful.

What I Want to Improve Next

My roadmap from here:

Integrate feedback directly into ranking updates
Add visual analytics for recommendation quality trends
Improve mobile UX parity
Deploy with persistent cloud storage and production database defaults
Provide a public demo mode for easier evaluation

Future Improvements

There are still a few things I would like to add later:

a more advanced recommendation engine
visual analytics for user feedback
better mobile support
live deployment with persistent cloud storage
a public demo mode for easier testing

Conclusion

This project began as a personal frustration and turned into a full web application with authentication, wardrobe storage, recommendation logic, and feedback infrastructure.

The most rewarding part was seeing how practical software decisions, not just flashy UI, can help people make everyday choices faster.

If you want to explore or run the project, check out the repo. You can try the flows and share feedback. I would especially love input on recommendation quality, UX clarity, and what features would make this genuinely useful in daily life.

How to Build a Full-Stack CRUD App with React, AWS Lambda, DynamoDB, and Cognito Auth

Benedicta Onyebuchi — Tue, 17 Mar 2026 15:13:02 +0000

Building a web application that works only on your local machine is one thing. Building one that is secure, connected to a real database, and accessible to anyone on the internet is another challenge entirely. And it requires a different set of tools.

Most production web applications share a common set of needs: they store and retrieve data, they expose that data through an API, they require users to authenticate before accessing sensitive operations, and they need to be deployed somewhere reliable and fast.

Meeting all of those needs used to require managing servers, configuring databases, handling authentication infrastructure, and provisioning hosting environments – often as separate, manual processes.

AWS changes that model significantly. With the combination of services you'll use in this tutorial (Lambda, DynamoDB, API Gateway, Cognito, and CloudFront), you can build and deploy a fully functional, secured, globally distributed application without managing a single server.

Each service handles one specific responsibility:

DynamoDB stores your data
Lambda runs your business logic on demand
API Gateway exposes your functions as a REST API
Cognito manages user authentication
CloudFront delivers your frontend worldwide over HTTPS.

The AWS CDK (Cloud Development Kit) ties all of this together by letting you define every one of those services as TypeScript code. Instead of clicking through the AWS Console to configure each resource manually, you describe your entire infrastructure in a single file and deploy it with one command.

By the end of this tutorial, you will have a fully deployed vendor management dashboard. Users can sign up, log in, and then create, read, and delete vendors, with all data securely stored in AWS DynamoDB and all routes protected by Amazon Cognito authentication.

What You'll Build

In this handbook, you'll build a two-panel web app where authenticated users can:

Add a new vendor (name, category, contact email)
View all saved vendors in real time
Delete a vendor from the list
Sign in and sign out securely

The frontend is built with Next.js. The backend runs entirely on AWS: DynamoDB stores the data, Lambda functions handle the logic, API Gateway exposes a REST API, Cognito manages authentication, and CloudFront serves the app globally over HTTPS.

Who This Is For
Prerequisites
Architecture Overview
Part 1: Set Up Your AWS Account and Tools
Part 2: Set Up the Project Structure
Part 3: Define the Database (DynamoDB)
Part 4: Write the Lambda Functions
Part 5: Build the API with API Gateway
Part 6: Deploy the Backend to AWS
Part 7: Build the React Frontend
Part 8: Add Authentication with Amazon Cognito
Part 9: Deploy the Frontend with S3 and CloudFront
What You Built
Conclusion

Who This Is For

This tutorial is for developers who know basic JavaScript and React but have never used AWS. You don't need any prior backend, cloud, or DevOps experience. I'll explain every AWS concept before we use it.

Prerequisites

Before starting, make sure you have the following installed and available:

Node.js 18 or higher: Download here
npm: Included with Node.js
A code editor: I recommend VS Code
A terminal: Any terminal on macOS, Linux, or Windows (WSL recommended on Windows)
An AWS account: You will create one in Part 1. A credit card is required, but the Free Tier covers everything in this tutorial.
Basic familiarity with React and TypeScript: You should understand components, useState, and useEffect.

Architecture Overview

Before writing any code, here's a plain-English description of how the pieces fit together.

When a user clicks "Add Vendor" in the React app:

The frontend reads the user's JWT auth token from the browser session
It sends a POST request to API Gateway, including the token in the request header
API Gateway checks the token against Cognito. If the token is invalid or missing, it rejects the request with a 401 error immediately
If the token is valid, API Gateway passes the request to the createVendor Lambda function
The Lambda function writes the new vendor to DynamoDB
DynamoDB confirms the write, and the Lambda returns a success response
The frontend re-fetches the vendor list and updates the UI

The same flow applies to reading and deleting vendors, with different Lambda functions and HTTP methods.

How the app is deployed: Your React app is exported as a static site, uploaded to an S3 bucket, and served globally through CloudFront. Your backend infrastructure (Lambda functions, API Gateway, DynamoDB, Cognito) is defined in TypeScript using AWS CDK and deployed with a single command.

Part 1: Set Up Your AWS Account and Tools

Before writing any application code, you need three things in place: an AWS account, the right tools on your machine, and credentials that let those tools communicate with AWS on your behalf.

1.1 Create Your AWS Account

If you don't have an AWS account:

Go to https://aws.amazon.com
Click Create an AWS Account
Follow the sign-up prompts and add a payment method
Once registered, log in to the AWS Management Console

AWS has a Free Tier that covers all the services used in this tutorial. You won't be charged for normal use while following along.

1.2 Install the AWS CLI and CDK

The AWS CLI is a command-line tool that lets you interact with AWS from your terminal: checking resources, configuring credentials, and more.

The AWS CDK (Cloud Development Kit) is the tool you will use to define your entire backend (database, Lambda functions, API) using TypeScript code. Instead of clicking through the AWS Console to create each resource, you describe what you want in a TypeScript file and CDK builds it for you.

Install both:

# Install AWS CLI (macOS)
curl "https://awscli.amazonaws.com/AWSCLIV2.pkg" -o "AWSCLIV2.pkg"
sudo installer -pkg AWSCLIV2.pkg -target /

# For Linux, see: https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2-linux.html
# For Windows, see: https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2-windows.html

# Install AWS CDK globally
npm install -g aws-cdk

Verify both are installed:

aws --version
cdk --version

Both commands should print a version number. If they do, you are ready to move on.

1.3 Configure Your AWS Credentials (IAM)

This step is critical. Your terminal needs a set of credentials – like a username and password – to act on your behalf inside AWS.

Think of your root account (the one you signed up with) as the master key to your entire AWS account. You should never use it for day-to-day development. Instead, you will create a separate IAM user with its own set of keys. If those keys are ever exposed, you can delete them without compromising your root account.

Phase 1: Create an IAM User

Log in to the AWS Console and search for IAM in the top search bar
In the left sidebar, click Users, then click Create user
Name the user cdk-dev. Leave "Provide user access to the AWS Management Console" unchecked – you only need terminal access, not console access
On the permissions screen, choose Attach policies directly

Search for AdministratorAccess and check the box next to it

Note on permissions: In a production job you would use a more restricted policy. For this tutorial, Administrator access is needed because CDK creates many different types of AWS resources.

6. Click through to the end and click Create user

Phase 2: Generate Access Keys

Click on your newly created cdk-dev user from the Users list
Go to the Security credentials tab
Scroll down to Access keys and click Create access key
Select Command Line Interface (CLI), check the acknowledgment box, and click Next
Click Create access key

Important: Copy both the Access Key ID and the Secret Access Key right now. You will never be able to see the Secret Access Key again after closing this screen. Save both values in a password manager or secure note.

Phase 3: Connect Your Terminal to AWS

Run the following command in your terminal:

aws configure

You will be prompted for four values:

AWS Access Key ID:     [paste your Access Key ID]
AWS Secret Access Key: [paste your Secret Access Key]
Default region name:   us-east-1
Default output format: json

Use us-east-1 as your region for this tutorial. After this step, every CDK and AWS CLI command you run will use these credentials automatically.

Part 2: Set Up the Project Structure

You will use a monorepo layout – one top-level folder with two sub-projects inside: frontend for your React app and backend for your AWS infrastructure code. They are deployed independently but live side by side.

2.1 Create the Workspace

mkdir vendor-tracker && cd vendor-tracker
mkdir backend frontend

2.2 Initialize the Frontend (Next.js)

Navigate into the frontend folder and run:

cd frontend
npx create-next-app@latest .

When prompted, choose the following options:

TypeScript --> Yes
ESLint --> Yes
Tailwind CSS --> Yes
src/ directory -->No
App Router --> Yes
Import alias --> No

2.3 Initialize the Backend (CDK)

Navigate into the backend folder and run:

cd ../backend
cdk init app --language typescript

This generates a boilerplate CDK project. The most important file it creates is backend/lib/backend-stack.ts. This is where you will define all of your AWS infrastructure as TypeScript code.

Also install esbuild, which CDK uses to bundle your Lambda functions:

npm install --save-dev esbuild

2.4 Understanding CDK Before You Write Any Code

CDK is likely different from most tools you have used. Here is how it works:

Normally, you would create AWS resources by clicking through the AWS Console: create a table here, configure a Lambda function there. CDK lets you do all of that using TypeScript code instead.

When you run cdk deploy, CDK reads your TypeScript file, converts it into an AWS CloudFormation template (an internal AWS format for describing infrastructure), and submits it to AWS. AWS then creates all the resources you described.

A few terms you will see throughout this tutorial:

Stack: The collection of all AWS resources you define together. Your BackendStack class is your stack.
Construct: Each individual AWS resource you create inside a stack (a table, a Lambda function, an API) is called a construct.
Deploy: Running cdk deploy sends your TypeScript definition to AWS and creates or updates the real resources.

The main file you'll work in is backend/lib/backend-stack.ts. Think of it as the blueprint for your entire backend.

Your final project structure will look like this:

vendor-tracker/
├── backend/
│   ├── lambda/
│   │   ├── createVendor.ts
│   │   ├── getVendors.ts
│   │   └── deleteVendor.ts
│   ├── lib/
│   │   └── backend-stack.ts
│   └── package.json
└── frontend/
    ├── app/
    │   ├── layout.tsx
    │   ├── page.tsx
    │   └── providers.tsx
    ├── lib/
    │   └── api.ts
    ├── types/
    │   └── vendor.ts
    └── .env.local

Part 3: Define the Database (DynamoDB)

DynamoDB is AWS's NoSQL database. Think of it as a fast, scalable key-value store in the cloud. Every item in a DynamoDB table must have a unique ID called the partition key. For your vendor table, that key will be vendorId.

Open backend/lib/backend-stack.ts. Replace the entire file contents with the following:

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';

export class BackendStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // 1. DynamoDB Table
    const vendorTable = new dynamodb.Table(this, 'VendorTable', {
      partitionKey: {
        name: 'vendorId',
        type: dynamodb.AttributeType.STRING,
      },
      billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
      removalPolicy: cdk.RemovalPolicy.DESTROY, // For development only
    });
  }
}

What each line does:

partitionKey tells DynamoDB that vendorId is the unique identifier for every record. No two vendors can share the same vendorId.
PAY_PER_REQUEST means you only pay when data is actually read or written. There is no charge when the table is idle, which makes it cost-effective for learning.
RemovalPolicy.DESTROY means the table will be deleted when you run cdk destroy. For production apps you would not use this.

Part 4: Write the Lambda Functions

A Lambda function is your server, but unlike a traditional server, it only runs when it's called. AWS spins it up on demand, runs your code, and shuts it down. You're only charged for the time your code is actually running.

You'll write three Lambda functions:

createVendor.ts: Adds a new vendor to DynamoDB
getVendors.ts: Returns all vendors from DynamoDB
deleteVendor.ts: Removes a vendor from DynamoDB by ID

Create a new folder inside backend:

mkdir backend/lambda

A Note on the AWS SDK

All three Lambda functions use AWS SDK v3 (@aws-sdk/client-dynamodb and @aws-sdk/lib-dynamodb). This is the current standard. An older version of the SDK (aws-sdk) exists but is deprecated and not bundled in the Node.js 18 Lambda runtime, which is what you'll use. Stick to v3 throughout.

4.1 Create Vendor Lambda

Create backend/lambda/createVendor.ts:

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb";
import { randomUUID } from "crypto";

const client = new DynamoDBClient({});
const docClient = DynamoDBDocumentClient.from(client);

export const handler = async (event: any) => {
  try {
    const body = JSON.parse(event.body);

    const item = {
      vendorId: randomUUID(), // Generates a collision-safe unique ID
      name: body.name,
      category: body.category,
      contactEmail: body.contactEmail,
      createdAt: new Date().toISOString(),
    };

    await docClient.send(
      new PutCommand({
        TableName: process.env.TABLE_NAME!,
        Item: item,
      })
    );

    return {
      statusCode: 201,
      headers: {
        "Access-Control-Allow-Origin": "*",
        "Access-Control-Allow-Headers": "Content-Type,Authorization",
        "Access-Control-Allow-Methods": "OPTIONS,POST,GET,DELETE",
      },
      body: JSON.stringify({ message: "Vendor created", vendorId: item.vendorId }),
    };
  } catch (error) {
    console.error("Error creating vendor:", error);
    return {
      statusCode: 500,
      headers: { "Access-Control-Allow-Origin": "*" },
      body: JSON.stringify({ error: "Failed to create vendor" }),
    };
  }
};

What each part does:

randomUUID() generates a universally unique ID using Node's built-in crypto module. No extra package is needed. This is more reliable than Date.now(), which can produce duplicate IDs if two requests arrive within the same millisecond.
process.env.TABLE_NAME reads the DynamoDB table name from an environment variable. You'll set this value in the CDK stack. This avoids hardcoding the table name inside your Lambda code.
The headers block is required for CORS (Cross-Origin Resource Sharing). Without Access-Control-Allow-Origin, your browser will block responses from a different domain than your frontend. Without Access-Control-Allow-Headers, the Authorization header you add later for Cognito will be rejected during the browser's preflight check.

4.2 Get Vendors Lambda

Create backend/lambda/getVendors.ts:

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, ScanCommand } from "@aws-sdk/lib-dynamodb";

const client = new DynamoDBClient({});
const docClient = DynamoDBDocumentClient.from(client);

export const handler = async () => {
  try {
    const response = await docClient.send(
      new ScanCommand({
        TableName: process.env.TABLE_NAME!,
      })
    );

    return {
      statusCode: 200,
      headers: {
        "Access-Control-Allow-Origin": "*",
        "Access-Control-Allow-Headers": "Content-Type,Authorization",
        "Content-Type": "application/json",
      },
      body: JSON.stringify(response.Items ?? []),
    };
  } catch (error) {
    console.error("Error fetching vendors:", error);
    return {
      statusCode: 500,
      headers: { "Access-Control-Allow-Origin": "*" },
      body: JSON.stringify({ error: "Failed to fetch vendors" }),
    };
  }
};

What each part does:

ScanCommand reads every item in the table and returns them as an array. For a learning project this is fine. In a production app with millions of rows, you would use a more targeted QueryCommand to avoid reading the entire table on every request.
response.Items ?? [] returns an empty array if the table is empty, preventing the frontend from crashing when there are no vendors yet.

4.3 Delete Vendor Lambda

Create backend/lambda/deleteVendor.ts:

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, DeleteCommand } from "@aws-sdk/lib-dynamodb";

const client = new DynamoDBClient({});
const docClient = DynamoDBDocumentClient.from(client);

export const handler = async (event: any) => {
  try {
    const body = JSON.parse(event.body);
    const { vendorId } = body;

    if (!vendorId) {
      return {
        statusCode: 400,
        headers: { "Access-Control-Allow-Origin": "*" },
        body: JSON.stringify({ error: "vendorId is required" }),
      };
    }

    await docClient.send(
      new DeleteCommand({
        TableName: process.env.TABLE_NAME!,
        Key: { vendorId },
      })
    );

    return {
      statusCode: 200,
      headers: {
        "Access-Control-Allow-Origin": "*",
        "Access-Control-Allow-Headers": "Content-Type,Authorization",
        "Access-Control-Allow-Methods": "OPTIONS,POST,GET,DELETE",
      },
      body: JSON.stringify({ message: "Vendor deleted" }),
    };
  } catch (error) {
    console.error("Error deleting vendor:", error);
    return {
      statusCode: 500,
      headers: { "Access-Control-Allow-Origin": "*" },
      body: JSON.stringify({ error: "Failed to delete vendor" }),
    };
  }
};

What each part does:

DeleteCommand removes the item whose vendorId matches the key you provide. DynamoDB doesn't return an error if the item doesn't exist. It simply does nothing.
The 400 guard at the top returns a clear error if the caller forgets to send a vendorId, rather than letting DynamoDB throw a confusing internal error.

Part 5: Build the API with API Gateway

API Gateway is what gives your Lambda functions a public URL. Without it, there's no way for your browser to trigger a Lambda function. Think of it as the front door of your backend: it receives HTTP requests, checks whether the caller is authorized, routes the request to the correct Lambda, and returns the Lambda's response to the caller.

Now you'll wire everything together in backend/lib/backend-stack.ts.

5.1 Add Lambda Functions and API Gateway to the Stack

Replace the entire contents of backend/lib/backend-stack.ts with this complete, assembled file:

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
import * as apigateway from 'aws-cdk-lib/aws-apigateway';
import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';

export class BackendStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // 1. DynamoDB Table 
    const vendorTable = new dynamodb.Table(this, 'VendorTable', {
      partitionKey: {
        name: 'vendorId',
        type: dynamodb.AttributeType.STRING,
      },
      billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
      removalPolicy: cdk.RemovalPolicy.DESTROY,
    });

    // 2. Lambda Functions
    const lambdaEnv = { TABLE_NAME: vendorTable.tableName };

    const createVendorLambda = new NodejsFunction(this, 'CreateVendorHandler', {
      entry: 'lambda/createVendor.ts',
      handler: 'handler',
      environment: lambdaEnv,
    });

    const getVendorsLambda = new NodejsFunction(this, 'GetVendorsHandler', {
      entry: 'lambda/getVendors.ts',
      handler: 'handler',
      environment: lambdaEnv,
    });

    const deleteVendorLambda = new NodejsFunction(this, 'DeleteVendorHandler', {
      entry: 'lambda/deleteVendor.ts',
      handler: 'handler',
      environment: lambdaEnv,
    });

    // 3. Permissions (Least Privilege)
    vendorTable.grantWriteData(createVendorLambda);
    vendorTable.grantReadData(getVendorsLambda);
    vendorTable.grantWriteData(deleteVendorLambda);

    // 4. API Gateway
    const api = new apigateway.RestApi(this, 'VendorApi', {
      restApiName: 'Vendor Service',
      defaultCorsPreflightOptions: {
        allowOrigins: apigateway.Cors.ALL_ORIGINS,
        allowMethods: apigateway.Cors.ALL_METHODS,
        allowHeaders: ['Content-Type', 'Authorization'],
      },
    });

    const vendors = api.root.addResource('vendors');
    vendors.addMethod('POST', new apigateway.LambdaIntegration(createVendorLambda));
    vendors.addMethod('GET', new apigateway.LambdaIntegration(getVendorsLambda));
    vendors.addMethod('DELETE', new apigateway.LambdaIntegration(deleteVendorLambda));

    // 5. Outputs
    new cdk.CfnOutput(this, 'ApiEndpoint', {
      value: api.url,
    });
  }
}

What each section does:

NodejsFunction is a special CDK construct that automatically bundles your Lambda code and all its dependencies into a single file using esbuild before uploading it to AWS. This is why you installed esbuild in Part 2.

Always use NodejsFunction instead of the basic lambda.Function construct. The basic version requires you to manually manage bundling, which causes "Module not found" errors at runtime.

Permissions (Least Privilege): In AWS, no resource can communicate with any other resource by default. A Lambda function has no access to DynamoDB, S3, or anything else unless you explicitly grant it.

This is called the Least Privilege principle: each piece of your system gets exactly the permissions it needs, and nothing more. grantWriteData lets a Lambda write and delete items. grantReadData lets a Lambda read items. Using separate grants for each function means the getVendors Lambda can never accidentally delete data.

CfnOutput prints a value to your terminal after cdk deploy completes. You'll use the ApiEndpoint URL to configure your frontend.

Part 6: Deploy the Backend to AWS

Your infrastructure is fully defined in code. Now you'll deploy it to AWS and get a live API URL.

6.1 Bootstrap Your AWS Environment

Before your first CDK deployment, AWS needs a small landing zone in your account – an S3 bucket where CDK can upload your Lambda bundles and other assets. This setup step is called bootstrapping and only needs to be done once per AWS account per region.

From inside your backend folder, run:

cdk bootstrap

Important: Bootstrapping is region-specific. If you ever switch to a different AWS region, you will need to run cdk bootstrap again in that region.

6.2 Deploy

Run:

cdk deploy

CDK will display a summary of everything it is about to create and ask for your confirmation. Type y and press Enter.

When the deployment finishes, you'll see an Outputs section in your terminal:

Outputs:
BackendStack.ApiEndpoint = https://abcdef123.execute-api.us-east-1.amazonaws.com/prod/

Copy that URL. You'll need it when building the frontend.

6.3 Troubleshooting: How to Read AWS Error Logs

Real deployments rarely go perfectly the first time. If something goes wrong after deploying, here is how to find the actual error message.

Error: 502 Bad Gateway

A 502 means API Gateway received your request but your Lambda crashed before it could respond. The most common cause is a missing environment variable – for example, if TABLE_NAME was not passed correctly and the Lambda cannot find the table.

To find the actual error message, use CloudWatch Logs:

Log in to the AWS Console and search for CloudWatch
In the left sidebar, click Logs --> Log groups

Find the group named /aws/lambda/BackendStack-CreateVendorHandler...
Click the most recent Log stream
Read the error message. It will tell you exactly what went wrong

Two common messages and their fixes:

Runtime.ImportModuleError : Your Lambda cannot find a module. Make sure you're using NodejsFunction (not lambda.Function) in your CDK stack. NodejsFunction automatically bundles dependencies; lambda.Function does not.
AccessDeniedException: Your Lambda tried to access DynamoDB but doesn't have permission. Check that you have the correct grantWriteData or grantReadData call in your stack for that Lambda.

Part 7: Build the React Frontend

Your backend is live. Now you'll build the React UI that talks to it.

7.1 Define the Vendor Type

Before writing any API or component code, define what a "vendor" looks like in TypeScript. This gives you type safety throughout your frontend code.

Create frontend/types/vendor.ts:

export interface Vendor {
  vendorId?: string; // Optional when creating — the Lambda generates it
  name: string;
  category: string;
  contactEmail: string;
  createdAt?: string;
}

The vendorId? is marked optional with ? because when you are creating a new vendor, you don't have an ID yet. The createVendor Lambda generates one. When you read vendors back from the API, vendorId will always be present.

7.2 Create the API Service Layer

Rather than writing fetch calls directly inside your React components, you'll centralize all your API logic in one file. This pattern is called a service layer. It keeps your components clean and makes it easy to update API calls in one place.

First, create a .env.local file inside your frontend folder to store your API URL:

# frontend/.env.local
NEXT_PUBLIC_API_URL=https://abcdef123.execute-api.us-east-1.amazonaws.com/prod

Replace the URL with the ApiEndpoint value from your cdk deploy output. The NEXT_PUBLIC_ prefix is required by Next.js to make an environment variable accessible in the browser.

You might be wondering: why not hardcode the URL? If you paste your API URL directly into your code and push it to GitHub, it becomes publicly visible. While an API URL alone does not expose your data (Cognito will protect that), it's good practice to keep URLs and secrets out of source control. Always use .env.local and add it to your .gitignore.

Make sure .env.local is in your .gitignore:

echo ".env.local" >> frontend/.gitignore

Now create frontend/lib/api.ts:

import { Vendor } from '@/types/vendor';

const BASE_URL = process.env.NEXT_PUBLIC_API_URL!;

export const getVendors = async (): Promise => {
  const response = await fetch(`${BASE_URL}/vendors`);
  if (!response.ok) throw new Error('Failed to fetch vendors');
  return response.json();
};

export const createVendor = async (vendor: Omit): Promise => {
  const response = await fetch(`${BASE_URL}/vendors`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(vendor),
  });
  if (!response.ok) throw new Error('Failed to create vendor');
};

export const deleteVendor = async (vendorId: string): Promise => {
  const response = await fetch(`${BASE_URL}/vendors`, {
    method: 'DELETE',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ vendorId }),
  });
  if (!response.ok) throw new Error('Failed to delete vendor');
};

What each part does:

Omit means the createVendor function accepts a vendor without an ID or timestamp (those are generated server-side).
if (!response.ok) throw new Error(...) ensures that any HTTP error (4xx or 5xx) surfaces as a JavaScript error in your component, where you can show the user a meaningful message instead of silently failing.

You'll update these functions later in Part 8 to include the Cognito auth token.

7.3 Build the Main Page

Now create the main page component. It includes a form for adding vendors and a live list that displays all current vendors.

Replace the contents of frontend/app/page.tsx with:

'use client';

import { useState, useEffect } from 'react';
import { createVendor, getVendors, deleteVendor } from '@/lib/api';
import { Vendor } from '@/types/vendor';

export default function Home() {
  const [vendors, setVendors] = useState([]);
  const [form, setForm] = useState({ name: '', category: '', contactEmail: '' });
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState('');

  const loadVendors = async () => {
    try {
      const data = await getVendors();
      setVendors(data);
    } catch {
      setError('Failed to load vendors.');
    }
  };

  // Load vendors once when the page first renders
  useEffect(() => {
    loadVendors();
  }, []);
  // The empty [] means this runs only once. Without it, the effect would
  // run after every render, causing an infinite loop of fetch requests.

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault(); // Prevent the browser from reloading the page on submit
    setLoading(true);
    setError('');
    try {
      await createVendor(form);
      setForm({ name: '', category: '', contactEmail: '' }); // Reset the form
      await loadVendors(); // Refresh the list from DynamoDB
    } catch {
      setError('Failed to add vendor. Please try again.');
    } finally {
      setLoading(false);
    }
  };

  const handleDelete = async (vendorId: string) => {
    try {
      await deleteVendor(vendorId);
      await loadVendors(); // Refresh after deleting
    } catch {
      setError('Failed to delete vendor.');
    }
  };

  return (
    
      Vendor Tracker
      Manage your vendors, stored in AWS DynamoDB.

      {error && (
        {error}
      )}

      

        {/* ── Add Vendor Form ── */}
        
          Add New Vendor
          
             setForm({ ...form, name: e.target.value })}
              required
            />
             setForm({ ...form, category: e.target.value })}
              required
            />
             setForm({ ...form, contactEmail: e.target.value })}
              required
            />
            
          
        

        {/* ── Vendor List ── */}
        
          
            Current Vendors ({vendors.length})
          
          
            {vendors.length === 0 ? (
              No vendors yet. Add one using the form.
            ) : (
              vendors.map(v => (
                
                  
                    {v.name}
                    {v.category} · {v.contactEmail}
                  
                  
                
              ))
            )}
          
        

      
    
  );
}

Key points in this component:

'use client' at the top is a Next.js directive. It tells Next.js that this component uses browser APIs (useState, useEffect, event handlers) and must run in the browser, not be pre-rendered on the server.
e.preventDefault() inside handleSubmit stops the browser's default form submission behavior, which would cause a full page reload and wipe your React state.
After every createVendor or deleteVendor call, loadVendors() is called again. This re-fetches the latest data from DynamoDB so the UI always matches what is actually stored in the database.

7.4 Test the App Locally

Start your Next.js development server:

cd frontend
npm run dev

Open http://localhost:3000 in your browser. You should see the two-panel layout. Try adding a vendor and confirm it appears in the list.

Verifying the connection to AWS:

Open Chrome DevTools (F12) and click the Network tab. When you add a vendor, you should see:

A POST request to your AWS API URL returning a 201 status code
A GET request returning 200 with the updated vendor list

You can also verify the data was saved by opening the AWS Console, navigating to DynamoDB --> Tables --> VendorTable --> Explore table items. Your vendor should appear there.

Part 8: Add Authentication with Amazon Cognito

Right now your API is completely open. Anyone who finds your API URL can add or delete vendors. You'll fix that with Amazon Cognito.

Cognito is AWS's authentication service. It manages a User Pool – a database of registered users with usernames and passwords. When a user logs in, Cognito issues a JWT (JSON Web Token): a cryptographically signed string that proves who the user is. Your API Gateway will check for this token on every request. No valid token means no access.

What is a JWT? A JSON Web Token is a string that looks like eyJhbGci.... It contains encoded information about the user and is signed by Cognito using a secret key.

API Gateway can verify the signature without contacting Cognito on every request, which makes token checking fast. Think of it as a tamper-proof badge: anyone can read the name on it, but only Cognito's signature makes it valid.

8.1 Add Cognito to the CDK Stack

Open backend/lib/backend-stack.ts and update it to include Cognito. Here is the complete updated file:

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
import * as apigateway from 'aws-cdk-lib/aws-apigateway';
import * as cognito from 'aws-cdk-lib/aws-cognito';
import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';

export class BackendStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // ─── 1. DynamoDB Table ────────────────────────────────────────────────────
    const vendorTable = new dynamodb.Table(this, 'VendorTable', {
      partitionKey: { name: 'vendorId', type: dynamodb.AttributeType.STRING },
      billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
      removalPolicy: cdk.RemovalPolicy.DESTROY,
    });

    // ─── 2. Lambda Functions ──────────────────────────────────────────────────
    const lambdaEnv = { TABLE_NAME: vendorTable.tableName };

    const createVendorLambda = new NodejsFunction(this, 'CreateVendorHandler', {
      entry: 'lambda/createVendor.ts',
      handler: 'handler',
      environment: lambdaEnv,
    });

    const getVendorsLambda = new NodejsFunction(this, 'GetVendorsHandler', {
      entry: 'lambda/getVendors.ts',
      handler: 'handler',
      environment: lambdaEnv,
    });

    const deleteVendorLambda = new NodejsFunction(this, 'DeleteVendorHandler', {
      entry: 'lambda/deleteVendor.ts',
      handler: 'handler',
      environment: lambdaEnv,
    });

    // ─── 3. Permissions ───────────────────────────────────────────────────────
    vendorTable.grantWriteData(createVendorLambda);
    vendorTable.grantReadData(getVendorsLambda);
    vendorTable.grantWriteData(deleteVendorLambda);

    // ─── 4. Cognito User Pool ─────────────────────────────────────────────────
    const userPool = new cognito.UserPool(this, 'VendorUserPool', {
      selfSignUpEnabled: true,
      signInAliases: { email: true },
      autoVerify: { email: true },
      userVerification: {
        emailStyle: cognito.VerificationEmailStyle.CODE,
      },
    });

    // Required to host Cognito's internal auth endpoints
    userPool.addDomain('VendorUserPoolDomain', {
      cognitoDomain: {
        domainPrefix: `vendor-tracker-${this.account}`,
      },
    });

    const userPoolClient = userPool.addClient('VendorAppClient');

    // ─── 5. API Gateway + Authorizer ──────────────────────────────────────────
    const api = new apigateway.RestApi(this, 'VendorApi', {
      restApiName: 'Vendor Service',
      defaultCorsPreflightOptions: {
        allowOrigins: apigateway.Cors.ALL_ORIGINS,
        allowMethods: apigateway.Cors.ALL_METHODS,
        allowHeaders: ['Content-Type', 'Authorization'],
      },
    });

    const authorizer = new apigateway.CognitoUserPoolsAuthorizer(
      this,
      'VendorAuthorizer',
      { cognitoUserPools: [userPool] }
    );

    const authOptions = {
      authorizer,
      authorizationType: apigateway.AuthorizationType.COGNITO,
    };

    const vendors = api.root.addResource('vendors');
    vendors.addMethod('GET', new apigateway.LambdaIntegration(getVendorsLambda), authOptions);
    vendors.addMethod('POST', new apigateway.LambdaIntegration(createVendorLambda), authOptions);
    vendors.addMethod('DELETE', new apigateway.LambdaIntegration(deleteVendorLambda), authOptions);

    // ─── 6. Outputs ───────────────────────────────────────────────────────────
    new cdk.CfnOutput(this, 'ApiEndpoint', { value: api.url });
    new cdk.CfnOutput(this, 'UserPoolId', { value: userPool.userPoolId });
    new cdk.CfnOutput(this, 'UserPoolClientId', { value: userPoolClient.userPoolClientId });
  }
}

What changed:

CognitoUserPoolsAuthorizer tells API Gateway to check every request for a valid Cognito JWT before passing it to any Lambda. If the token is missing or invalid, API Gateway rejects the request with a 401 Unauthorized response without ever touching your Lambda.
authOptions is applied to all three API methods: GET, POST, and DELETE. All routes are now protected.
autoVerify: { email: true } tells Cognito to mark the email attribute as verified after a user confirms via the verification code email. It doesn't skip the verification email, as users still receive a code. If you want to skip verification during development, you can manually confirm users in the Cognito console (covered in section 8.5).
Two new CfnOutput values (UserPoolId and UserPoolClientId) will appear in your terminal after the next deployment. Your frontend needs them to connect to Cognito.

Deploy the updated stack:

cd backend
cdk deploy

After deployment, your terminal output will include three values:

Outputs:
BackendStack.ApiEndpoint     = https://abc123.execute-api.us-east-1.amazonaws.com/prod/
BackendStack.UserPoolId      = us-east-1_xxxxxxxx
BackendStack.UserPoolClientId = xxxxxxxxxxxxxxxxxxxx

Save all three values. You'll use them in the next step.

8.2 Install and Configure AWS Amplify

AWS Amplify is a frontend library that handles all the complex authentication logic for you: it manages the login UI, stores tokens in the browser, refreshes expired tokens automatically, and exposes a simple API to read the current user's session.

Install the Amplify libraries inside your frontend folder:

cd frontend
npm install aws-amplify @aws-amplify/ui-react

Create frontend/app/providers.tsx. This file initializes Amplify with your Cognito configuration. It runs once when the app loads:

'use client';

import { Amplify } from 'aws-amplify';

Amplify.configure(
  {
    Auth: {
      Cognito: {
        userPoolId: process.env.NEXT_PUBLIC_USER_POOL_ID!,
        userPoolClientId: process.env.NEXT_PUBLIC_USER_POOL_CLIENT_ID!,
      },
    },
  },
  { ssr: true }
);

export function Providers({ children }: { children: React.ReactNode }) {
  return <>{children};
}

Add the Cognito IDs to your frontend/.env.local file:

NEXT_PUBLIC_API_URL=https://abc123.execute-api.us-east-1.amazonaws.com/prod
NEXT_PUBLIC_USER_POOL_ID=us-east-1_xxxxxxxx
NEXT_PUBLIC_USER_POOL_CLIENT_ID=xxxxxxxxxxxxxxxxxxxx

Replace the values with the outputs from your cdk deploy.

8.3 Wire Providers into the App Layout

This step is critical. Amplify must be initialized before any component tries to use authentication. If you skip this step, fetchAuthSession() will throw an "Amplify not configured" error and nothing will work.

Open frontend/app/layout.tsx and update it to wrap the app in the Providers component:

import type { Metadata } from 'next';
import './globals.css';
import { Providers } from './providers';

export const metadata: Metadata = {
  title: 'Vendor Tracker',
  description: 'Manage your vendors with AWS',
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    
      
        {children}
      
    
  );
}

By wrapping {children} in , you ensure that Amplify is configured once at the root of the app, before any child page or component renders.

8.4 Protect the UI with withAuthenticator

Now wrap your Home component so that unauthenticated users see a login screen instead of the dashboard.

Replace the contents of frontend/app/page.tsx with this updated version:

'use client';

import { useState, useEffect } from 'react';
import { withAuthenticator } from '@aws-amplify/ui-react';
import '@aws-amplify/ui-react/styles.css';
import { getVendors, createVendor, deleteVendor } from '@/lib/api';
import { Vendor } from '@/types/vendor';

// withAuthenticator injects `signOut` and `user` as props automatically
function Home({ signOut, user }: { signOut?: () => void; user?: any }) {
  const [vendors, setVendors] = useState([]);
  const [form, setForm] = useState({ name: '', category: '', contactEmail: '' });
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState('');

  const loadVendors = async () => {
    try {
      const data = await getVendors();
      setVendors(data);
    } catch {
      setError('Failed to load vendors.');
    }
  };

  useEffect(() => {
    loadVendors();
  }, []);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setLoading(true);
    setError('');
    try {
      await createVendor(form);
      setForm({ name: '', category: '', contactEmail: '' });
      await loadVendors();
    } catch {
      setError('Failed to add vendor.');
    } finally {
      setLoading(false);
    }
  };

  const handleDelete = async (vendorId: string) => {
    try {
      await deleteVendor(vendorId);
      await loadVendors();
    } catch {
      setError('Failed to delete vendor.');
    }
  };

  return (
    
      {/* ── Header ── */}
      
        
          Vendor Tracker
          Signed in as: {user?.signInDetails?.loginId}
        
        
      

      {error && (
        {error}
      )}

      

        {/* ── Add Vendor Form ── */}
        
          Add New Vendor
          
             setForm({ ...form, name: e.target.value })}
              required
            />
             setForm({ ...form, category: e.target.value })}
              required
            />
             setForm({ ...form, contactEmail: e.target.value })}
              required
            />
            
          
        

        {/* ── Vendor List ── */}
        
          
            Current Vendors ({vendors.length})
          
          
            {vendors.length === 0 ? (
              No vendors yet.
            ) : (
              vendors.map(v => (
                
                  
                    {v.name}
                    {v.category} · {v.contactEmail}
                  
                  
                
              ))
            )}
          
        

      
    
  );
}

// Wrapping Home with withAuthenticator means any user who is not logged in
// will see Amplify's built-in login/signup screen instead of this component.
export default withAuthenticator(Home);

8.5 Pass the Auth Token to API Calls

Now that API Gateway requires a JWT on every request, your fetch calls need to include the token in the Authorization header. Without it, every request will return a 401 Unauthorized error.

Update frontend/lib/api.ts with a token helper and updated fetch calls:

import { fetchAuthSession } from 'aws-amplify/auth';
import { Vendor } from '@/types/vendor';

const BASE_URL = process.env.NEXT_PUBLIC_API_URL!;

// Retrieves the current user's JWT token from the active Amplify session
const getAuthToken = async (): Promise => {
  const session = await fetchAuthSession();
  const token = session.tokens?.idToken?.toString();
  if (!token) throw new Error('No active session. Please sign in.');
  return token;
};

export const getVendors = async (): Promise => {
  const token = await getAuthToken();
  const response = await fetch(`${BASE_URL}/vendors`, {
    headers: { Authorization: token },
  });
  if (!response.ok) throw new Error('Failed to fetch vendors');
  return response.json();
};

export const createVendor = async (
  vendor: Omit
): Promise => {
  const token = await getAuthToken();
  const response = await fetch(`${BASE_URL}/vendors`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: token,
    },
    body: JSON.stringify(vendor),
  });
  if (!response.ok) throw new Error('Failed to create vendor');
};

export const deleteVendor = async (vendorId: string): Promise => {
  const token = await getAuthToken();
  const response = await fetch(`${BASE_URL}/vendors`, {
    method: 'DELETE',
    headers: {
      'Content-Type': 'application/json',
      Authorization: token,
    },
    body: JSON.stringify({ vendorId }),
  });
  if (!response.ok) throw new Error('Failed to delete vendor');
};

What getAuthToken does:

fetchAuthSession() reads the currently logged-in user's session from the browser. Amplify stores the session in memory and localStorage after the user signs in.

session.tokens?.idToken is the JWT string that API Gateway's Cognito Authorizer is looking for. Passing it as the Authorization header tells API Gateway: "This request is from an authenticated user."

8.6 Troubleshooting Cognito

When a new user signs up through the Amplify UI, Cognito marks the account as Unconfirmed until the user verifies their email address. A verification code is sent to the user's email. After entering the code, the account becomes confirmed and the user can log in.

If you are testing locally and want to skip the email step, you can manually confirm any account in the AWS Console:

Open the AWS Console and navigate to Cognito
Click on your User Pool (VendorUserPool...)
Click the Users tab
Click on the user's email address
Open the Actions dropdown and click Confirm account

401 Unauthorized errors after deployment

If you are getting 401 errors, check two things:

Open Chrome DevTools --> Network tab, click the failing request, and look at the Request Headers. You should see an Authorization header with a long string of characters. If it is missing, getAuthToken is failing. Check that Amplify is configured correctly in providers.tsx and wired in via layout.tsx.
In your CDK stack, confirm that authorizationType: apigateway.AuthorizationType.COGNITO is present on every protected method definition. If it is missing, API Gateway may not be checking tokens even though the authorizer is defined.

Part 9: Deploy the Frontend with S3 and CloudFront

Your app works locally. Now you'll deploy it to a real HTTPS URL that anyone in the world can visit.

The strategy: Next.js will export your React app as a set of static HTML, CSS, and JavaScript files. Those files will be uploaded to an S3 bucket (AWS's file storage service). CloudFront sits in front of the bucket as a Content Delivery Network (CDN), distributing your files to servers around the world and serving them over HTTPS.

9.1 Configure Next.js for Static Export

Open frontend/next.config.js (or next.config.mjs) and add the output: 'export' setting:

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export', // Generates a static /out folder instead of a Node.js server
};

export default nextConfig;

Note on 'use client' and static export: When output: 'export' is set, Next.js builds every page at compile time. Any component that uses browser-only APIs – like withAuthenticator from Amplify – must have 'use client' at the top of the file. This tells Next.js to skip server-side rendering for that component and run it only in the browser.

You already have 'use client' in page.tsx. If you ever see a build error mentioning window is not defined or similar, check that the relevant component has 'use client' at the top.

Build the frontend:

cd frontend
npm run build

This generates an /out folder containing your complete website as static files. Verify the folder was created:

ls out
# You should see: index.html, _next/, etc.

9.2 Add S3 and CloudFront to the CDK Stack

Open backend/lib/backend-stack.ts and add the hosting infrastructure. Here's the complete final version of the file:

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
import * as apigateway from 'aws-cdk-lib/aws-apigateway';
import * as cognito from 'aws-cdk-lib/aws-cognito';
import * as s3 from 'aws-cdk-lib/aws-s3';
import * as cloudfront from 'aws-cdk-lib/aws-cloudfront';
import * as origins from 'aws-cdk-lib/aws-cloudfront-origins';
import * as s3deploy from 'aws-cdk-lib/aws-s3-deployment';
import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';

export class BackendStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // 1. DynamoDB Table 
    const vendorTable = new dynamodb.Table(this, 'VendorTable', {
      partitionKey: { name: 'vendorId', type: dynamodb.AttributeType.STRING },
      billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
      removalPolicy: cdk.RemovalPolicy.DESTROY,
    });

    // 2. Lambda Functions
    const lambdaEnv = { TABLE_NAME: vendorTable.tableName };

    const createVendorLambda = new NodejsFunction(this, 'CreateVendorHandler', {
      entry: 'lambda/createVendor.ts',
      handler: 'handler',
      environment: lambdaEnv,
    });

    const getVendorsLambda = new NodejsFunction(this, 'GetVendorsHandler', {
      entry: 'lambda/getVendors.ts',
      handler: 'handler',
      environment: lambdaEnv,
    });

    const deleteVendorLambda = new NodejsFunction(this, 'DeleteVendorHandler', {
      entry: 'lambda/deleteVendor.ts',
      handler: 'handler',
      environment: lambdaEnv,
    });

    // 3. Permissions
    vendorTable.grantWriteData(createVendorLambda);
    vendorTable.grantReadData(getVendorsLambda);
    vendorTable.grantWriteData(deleteVendorLambda);

    // 4. Cognito User Pool
    const userPool = new cognito.UserPool(this, 'VendorUserPool', {
      selfSignUpEnabled: true,
      signInAliases: { email: true },
      autoVerify: { email: true },
      userVerification: {
        emailStyle: cognito.VerificationEmailStyle.CODE,
      },
    });

    userPool.addDomain('VendorUserPoolDomain', {
      cognitoDomain: { domainPrefix: `vendor-tracker-${this.account}` },
    });

    const userPoolClient = userPool.addClient('VendorAppClient');

    // 5. API Gateway + Authorizer
    const api = new apigateway.RestApi(this, 'VendorApi', {
      restApiName: 'Vendor Service',
      defaultCorsPreflightOptions: {
        allowOrigins: apigateway.Cors.ALL_ORIGINS,
        allowMethods: apigateway.Cors.ALL_METHODS,
        allowHeaders: ['Content-Type', 'Authorization'],
      },
    });

    const authorizer = new apigateway.CognitoUserPoolsAuthorizer(
      this,
      'VendorAuthorizer',
      { cognitoUserPools: [userPool] }
    );

    const authOptions = {
      authorizer,
      authorizationType: apigateway.AuthorizationType.COGNITO,
    };

    const vendors = api.root.addResource('vendors');
    vendors.addMethod('GET', new apigateway.LambdaIntegration(getVendorsLambda), authOptions);
    vendors.addMethod('POST', new apigateway.LambdaIntegration(createVendorLambda), authOptions);
    vendors.addMethod('DELETE', new apigateway.LambdaIntegration(deleteVendorLambda), authOptions);

    // 6. S3 Bucket (Frontend Files) 
    const siteBucket = new s3.Bucket(this, 'VendorSiteBucket', {
      blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
      removalPolicy: cdk.RemovalPolicy.DESTROY,
      autoDeleteObjects: true,
    });

    // 7. CloudFront Distribution (HTTPS + CDN)
    const distribution = new cloudfront.Distribution(this, 'SiteDistribution', {
      defaultBehavior: {
        origin: new origins.S3Origin(siteBucket),
        viewerProtocolPolicy: cloudfront.ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
      },
      defaultRootObject: 'index.html',
      errorResponses: [
        {
          // Redirect all 404s back to index.html so React can handle routing
          httpStatus: 404,
          responseHttpStatus: 200,
          responsePagePath: '/index.html',
        },
      ],
    });

    // 8. Deploy Frontend Files to S3 
    new s3deploy.BucketDeployment(this, 'DeployWebsite', {
      sources: [s3deploy.Source.asset('../frontend/out')],
      destinationBucket: siteBucket,
      distribution,
      distributionPaths: ['/*'], // Clears CloudFront cache on every deploy
    });

    // 9. Outputs ───────────────────────────────────────────────────────────
    new cdk.CfnOutput(this, 'ApiEndpoint', { value: api.url });
    new cdk.CfnOutput(this, 'UserPoolId', { value: userPool.userPoolId });
    new cdk.CfnOutput(this, 'UserPoolClientId', { value: userPoolClient.userPoolClientId });
    new cdk.CfnOutput(this, 'CloudFrontURL', {
      value: `https://${distribution.distributionDomainName}`,
    });
  }
}

What the hosting infrastructure does:

The S3 bucket stores your static HTML, CSS, and JavaScript files. It is private – users cannot access it directly.
CloudFront is the CDN that sits in front of S3. It gives you an HTTPS URL and caches your files at edge locations worldwide, so the app loads fast no matter where users are located. REDIRECT_TO_HTTPS automatically upgrades any HTTP request to HTTPS.
The error response for 404 returns index.html instead of an error page. This is necessary for single-page apps: if a user navigates directly to a route like /vendors/123, CloudFront cannot find a file at that path, but sending back index.html lets the React app handle the routing correctly.
distributionPaths: ['/*'] tells CloudFront to invalidate its entire cache after every deployment. This ensures users always see the latest version of your app immediately.
BucketDeployment is a CDK construct that automatically uploads the contents of your frontend/out folder to the S3 bucket every time you run cdk deploy.

9.3 Run the Final Deployment

First, build the frontend with the latest environment variables:

cd frontend
npm run build

Then deploy everything from the backend folder:

cd ../backend
cdk deploy

After deployment finishes, copy the CloudFrontURL from the terminal output:

Outputs:
BackendStack.CloudFrontURL = https://d1234abcd.cloudfront.net

Open that URL in your browser. Your app is now live on the internet, served over HTTPS, globally distributed.

What You Built

You now have a fully deployed, production-style full-stack application. Here is a summary of every piece you built and what it does:

Layer	Service	What it does
Frontend	Next.js + CloudFront	React UI served globally over HTTPS
Auth	Amazon Cognito + Amplify	User sign-up, login, and JWT token management
API	API Gateway	Routes HTTP requests, validates auth tokens
Logic	AWS Lambda (×3)	Creates, reads, and deletes vendors on demand
Database	DynamoDB	Stores vendor records with no idle cost
Storage	S3	Holds your built frontend files
Infrastructure	AWS CDK	Defines and deploys all of the above as code

Conclusion

You have built and deployed the foundational pattern of almost every cloud application: a secured API backed by a database, deployed with infrastructure as code. Here is everything you accomplished:

You set up a professional AWS development environment with scoped IAM credentials. You defined your entire backend infrastructure as TypeScript code using AWS CDK, which means your database, API, Lambda functions, and authentication system are all version-controlled, repeatable, and deployable with a single command.

You wrote three Lambda functions that handle create, read, and delete operations, each with proper error handling and the correct AWS SDK v3 patterns. You connected them to a REST API through API Gateway and protected every route with Amazon Cognito authentication, so only registered, verified users can interact with your data.

On the frontend, you built a Next.js application with a service layer that cleanly separates API logic from UI components, manages JWTs automatically through AWS Amplify, and gives users a complete sign-up and sign-in flow without you writing a single line of authentication UI code.

Finally, you deployed the entire system: your backend to AWS Lambda and DynamoDB, and your frontend as a static site served globally through CloudFront over HTTPS.

The full source code for this tutorial is available on GitHub. Clone it, modify it, and use it as a reference for your own projects.

How to Test a Complex Full-Stack App: Manual Approach vs AI-Assisted Testing

Ajay Yadav — Mon, 16 Mar 2026 17:53:09 +0000

A few days ago, I ran an experiment with an AI-powered testing agent that lets you write test cases in plain English instead of code. I opened its natural language interface and typed four simple sentences to test google.com:

1. Go to google.com
2. There should be a long input field on the page
3. Type something and verify suggestions appear in a dropdown
4. The input field should not have any placeholder text

A real browser opened Google, found the search bar, typed a query, checked for the autocomplete dropdown, and verified there was no placeholder, all from those four lines.

No Playwright selectors. No page.getByRole(). No CSS class names. Just plain English describing what a user would do.

That made me curious: what happens if I try this on something actually complex? So I tested my own full-stack app's auth endpoint the same way:

Send a GET request to /api/auth/status without any session cookie. Verify it returns 401.

Within 15 seconds, done.

The same test took me an hour to set up manually, building a session helper, separating my Express app from the server startup, seeding a test database, just so I could write five lines of Supertest code.

I ended up testing my entire application both ways: the traditional manual approach and the AI-assisted approach. Same endpoints, same assertions, completely different experience. This article is about what I learned.

But before I get into how I tested it, let's talk about what actually matters: the testing concepts themselves. Because no approach, manual or automated, will save you time or energy if you don't understand what you're testing and why.

What we'll cover:

Prerequisites
How Testing Actually Works in Full-Stack Apps
What Made This Hard
The Manual Approach
The AI-Assisted Approach
When to Use Which Approach
Conclusion

Prerequisites

To get the most out of this article, you should have a basic understanding of JavaScript and Node.js, along with some familiarity with React and Express.

Experience writing simple tests with any JavaScript testing framework like Jest or Vitest will be helpful, though I'll explain the core testing concepts as we go.

You should also have Node.js installed on your machine. If you want to follow along with the manual testing examples, you'll need Vitest (or Jest) for unit and API tests, Supertest for HTTP endpoint testing, and Playwright for end-to-end browser tests. For the AI-assisted approach, I used KaneAI by LambdaTest, which you can explore through their platform.

How Testing Actually Works in Full-Stack Apps

If you've only tested isolated React components or written a few unit tests for utility functions, full-stack testing feels like a different sport. The concepts are the same, but the complexity jumps dramatically. Here's what you actually need to know.

Three Layers, Three Different Jobs

Every full-stack application has three natural testing layers, and trying to cover everything with just one of them leads to either fragile tests or blind spots.

Unit Tests

Unit tests check that individual functions return the right output for a given input. They don't touch the database, the network, or the browser.

They run in milliseconds. If your function takes a string and returns a formatted slug, a unit test calls that function and checks the result. That's it.

it("converts a title to a slug", () => {
  expect(slugify("My First Post")).toBe("my-first-post");
});

API Tests

API tests check that your backend endpoints return the right responses. They send real HTTP requests to your Express (or Next.js) app and verify the status codes, response shapes, and error handling.

If your /api/auth/status endpoint should return 401 without a session cookie, an API test confirms that contract.

it("returns 401 without session cookie", async () => {
  const res = await request(app).get("/api/auth/status");
  expect(res.status).toBe(401);
});

End-to-end (E2E) Tests

End-to-end (E2E) tests open a real browser and interact with your app the way a user would. They click buttons, fill forms, navigate pages, and check that the right things appear on screen.

If your login flow should redirect to a dashboard after authentication, an E2E test walks through that entire journey.

test("login redirects to dashboard", async ({ page }) => {
  await page.goto("/");
  await page.getByTestId("username-input").fill("ajay");
  await page.getByTestId("password-input").fill("password123");
  await page.getByTestId("login-button").click();
  await expect(page.getByTestId("dashboard")).toBeVisible();
});

The Pain Points Nobody Warns You About

Tutorials make all three layers look straightforward. In practice, each one has a trap.

First, we have the session cookie problem. Most real apps have authentication. To test any authenticated endpoint, you need a valid session.

That means you need a helper function that logs in a test user, extracts the session cookie from the Set-Cookie header, and returns it for future requests.

This sounds simple. It took me an hour to build one that actually works with express-session. Every project reinvents this wheel.

Then we have the app vs. server separation issue. Supertest (the most popular API testing library) needs to import your Express app without starting a real server.

If your app.ts file has app.listen(3000) at the bottom, Supertest will try to bind to port 3000, and your tests will crash when running in parallel.

You have to separate your app definition from the server startup. app.ts exports the Express instance, server.ts calls .listen(). It's a three-minute refactor, but nobody tells you about it until your tests fail.

You also have the SSE and real-time nightmare. If your app uses Server-Sent Events (SSE) or WebSockets, you're testing time-dependent behavior.

You open a connection, trigger an action, and wait for an event to arrive. If the event takes too long, your test times out. If you don't set a timeout, the test hangs forever. You end up writing 30 lines of Promise wrappers, timeout handlers, and cleanup logic for a single assertion.

Finally, there's the selector fragility trap. E2E tests that use CSS selectors (.btn-primary, .card-title) break every time you rename a class.

The fix is using data-testid attributes, stable identifiers that exist solely for testing and don't change during refactors. But retrofitting them into an existing app means touching dozens of components.

Schema Validation: The Hidden Time Sink

Here's something nobody tells you about API testing. Writing the assertion for "does this endpoint return 200" takes one line.

Writing assertions that verify the shape of the response, every field exists, every field has the right type, every enum value is valid, takes 15 to 20 lines per endpoint. Multiply that across a dozen endpoints and you're spending hours writing boilerplate like:

expect(res.body[0]).toHaveProperty("title");
expect(typeof res.body[0].title).toBe("string");
expect(res.body[0]).toHaveProperty("status");
expect(["open", "closed", "merged"]).toContain(res.body[0].status);

It's important work, though: schema validation catches real bugs when your backend changes a response shape. But the repetitiveness is what makes it a good candidate for automation, which I'll get to later.

These aren't edge cases. These are the everyday realities of testing a full-stack app. Knowing them upfront saves you from the "why is this so much harder than the tutorial??" frustration.

What Made This Hard

A few months ago, I wrote a freeCodeCamp article about testing JavaScript apps from unit tests to AI-augmented QA. That article covered testing fundamentals with clean, simple examples.

After publishing it, I kept thinking: what happens when you apply all of this to something messy?

I had the perfect candidate. Creoper (code name) is an AI-powered project management tool I built that connects GitHub with Discord.

Teams can monitor repositories, track pull requests, and query project status using natural language, all without leaving their chat platform.

I built it across two internal hackathons at CreoWis, and it won both times. What started as a simple GitHub-Discord automation bot evolved into a full product with five interconnected components:

It has a React dashboard with GitHub OAuth. An Express backend with REST APIs and SSE. A Discord bot that processes natural language through an LLM intent detection layer. PostgreSQL with Prisma. GitHub webhook handlers.

But here's the thing: despite winning two hackathons, Creoper had zero test cases. The app wasn't even deployed yet. I'd been stuck on Railway monorepo deployment issues for weeks.

So I was staring at a system that had every real-world testing challenge I'd just written about, auth flows, real-time events, multiple integration points, complex business logic, and no safety net at all.

I decided to test it two different ways and document what actually happened. If you want to explore the full project, I've written two separate blogs about how I built it.

The Manual Approach

I mapped pure logic components like the intent parser and embed builder to unit tests, since they deal with straightforward input-output behavior. I assigned Express endpoints to API tests using Supertest, which let me send real HTTP requests and verify response codes and shapes.

I planned to cover the React dashboard with end-to-end tests using Playwright, simulating actual user interactions in a real browser. As for Discord bot interactions and webhook delivery, those couldn't be automated reliably yet, so I documented them and tested them manually.

Here's what each layer looked like in practice.

Unit Tests: The Easy Win

Creoper has a function that classifies Discord messages into structured intents. If someone types "list prs," it should return LIST_PRS with a high confidence score.

If the message is gibberish, it should return UNKNOWN with zero confidence. The confidence score matters because anything below a threshold triggers a safe fallback instead of executing an action.

it("detects LIST_PRS intent", () => {
  const result = parseIntent("list prs");
  expect(result.action).toBe("LIST_PRS");
  expect(result.confidence).toBeGreaterThan(0.8);
});

it("returns low confidence when repo name is missing", () => {
  const result = parseIntent("set active repo");
  expect(result.confidence).toBeLessThan(0.8);
});

Notice these aren't just "does it work" checks. They're testing a safety mechanism, the threshold between executing an action and falling back.

These are exactly the kinds of tests that need to be written by hand because you have to understand the business logic behind the numbers.

I also tested the Discord embed builder the same way. Give it push event data, check that the formatted message contains the right repo name, author, branch, and commit messages.

Pure input, pure output, no external dependencies. Unit tests ran in milliseconds and caught edge cases like empty commit arrays immediately.

API Tests: Where the Friction Starts

Testing the Express endpoints required the infrastructure work I described earlier. I separated app.ts from server.ts, built the createTestSession() helper, and set up an in-memory test database so tests wouldn't touch real data.

it("returns 401 without session cookie", async () => {
  const res = await request(app).get("/api/auth/status");
  expect(res.status).toBe(401);
  expect(res.body).toHaveProperty("error");
});

it("returns user data with valid session", async () => {
  const cookie = await createTestSession();
  const res = await request(app)
    .get("/api/auth/status")
    .set("Cookie", cookie);
  expect(res.status).toBe(200);
  expect(res.body).toHaveProperty("username");
  expect(res.body).not.toHaveProperty("accessToken");
});

Five lines of test code, one hour of infrastructure to make those five lines work.

Then I had to repeat this pattern across every endpoint: repos, pull requests, issues, active repo configuration, each with happy path, error cases, and the tedious schema validation I mentioned earlier.

The SSE test was the worst. I needed a Promise wrapper, an EventSource connection, a timeout handler, an onopen callback to trigger the change, an event listener to catch the response, and cleanup for both the connection and the server. About 30 lines for a single assertion, and it took three attempts to get the timing right.

E2E Tests: The Full Journey

Playwright's E2E tests were actually pleasant to write once I added data-testid attributes to the React components. The login flow, note creation, editing, and deletion all followed a predictable pattern.

test("login and create a note", async ({ page }) => {
  await page.goto("/");
  await page.getByTestId("username-input").fill("ajay");
  await page.getByTestId("password-input").fill("password123");
  await page.getByTestId("login-button").click();
  await expect(page.getByTestId("username-display")).toContainText("ajay");
});

The real cost wasn't writing the tests — it was maintaining them. Midway through development, I renamed a CSS class from .repo-list-item to .repository-card. Two Playwright tests broke immediately. I found the references, updated them, re-ran. Ten minutes for a CSS rename. I can see this becoming death-by-a-thousand-cuts as the UI evolves.

The AI-Assisted Approach

Now here's the same project, tested with a fundamentally different workflow.

Instead of writing test code, you describe what you want to test in natural language. An AI agent interprets your intent, interacts with the actual application, generates assertions, and produces exportable test code.

The tool I used is KaneAI, a GenAI-native testing agent that covers web UIs, APIs, and mobile apps through natural language test authoring with real browser execution. That's the only background you need. Let me show you the workflow.

API Testing: Describing Instead of Coding

Instead of writing Supertest code, I opened the slash command menu, selected API, and pasted a curl command:

curl -X GET http://localhost:3000/api/auth/status

It fired the request through the tunnel, showed the 401 response, and I added it to my test steps. For the authenticated version, I pasted the same command with a session cookie from DevTools. No createTestSession() helper. No test database. No app separation.

For the repository endpoints, I described the flow in plain English:

1. Set active repository to "atechajay/no-javascript" via POST to /api/repos/active
2. Verify the response confirms the repository is active
3. Fetch open pull requests via GET to /api/repos/pulls
4. Verify each item has title, author, url, and status fields
5. Try an invalid repository name, verify 400 error

It generated assertions for the happy path and added schema validation I didn't ask for checking that title is a string, labels is an array, status is one of the expected values. That's the tedious work that ate up hours in the manual approach, generated in seconds.

E2E Testing: Plain English, Real Browser

For the React dashboard, instead of Playwright selectors, I described:

1. Navigate to localhost:3001
2. Click "Go to Dashboard"
3. Verify redirect to GitHub OAuth
4. After auth, verify the dashboard loads
5. Verify the username appears in the sidebar

It executed each step in a real cloud browser connected to my localhost. No page.getByRole(), no page.waitForURL(), no selector debugging.

After each test, I exported the generated code. It came with wait conditions and assertion logic baked in.

It wasn't perfect copy-paste: I updated environment variables, adjusted base URLs, and fixed a few field name mismatches where it expected pullRequestUrl instead of my actual url field. But it gave me roughly 70–80% of the foundation.

The Feature That Surprised Me

Midway through testing, I renamed that CSS class from .repo-list-item to .repository-card. My manual Playwright tests broke immediately.

But the AI tool's auto-healing detected the selector change, found the closest matching element based on the test's original intent, and continued the test with a review flag. No code changes needed.

For a rapidly changing MVP where class names are still in flux, that alone saved significant maintenance time.

When to Use Which Approach

After testing the same project both ways, here's my honest take.

Write tests by hand when you're testing business logic that requires domain understanding. For Creoper's intent parser, I needed to think about what "low confidence" means in the context of the application's safety mechanism.

An AI tool can generate assertions, but it can't understand why a confidence score of 0.5 should trigger a fallback instead of an action. Pure logic with meaningful edge cases is where hand-written tests earn their keep.

You should also write tests by hand when they need to run in CI without external dependencies. Vitest tests with mocked dependencies are self-contained. They run in milliseconds and don't need a tunnel, a cloud browser, or a third-party account.

Hand-written tests are also best when the team needs to maintain them. Hand-written tests are transparent. Generated code, even when exported, can feel opaque to someone who wasn't there when it was authored.

Reach for AI-assisted testing, on the other hand, when your UI changes frequently. For an MVP where CSS classes and component structure are still in flux, auto-healing prevents the "my tests broke because I renamed a div" problem. You spend less time fixing selectors and more time shipping features.

AI-assisted testing is also helpful when you need coverage fast and plan to refine later. The 70–80% foundation is a real boost when you're the only developer and you need coverage now. You can always hand-tune the exported code later.

Never rely solely on either approach to understand your system. No tool knows that an SSE connection drops after 30 seconds if the heartbeat isn't configured. No tool understands that a Discord bot should never execute a write action when confidence is below 0.8. No tool realizes the OAuth callback silently fails if the redirect_uri doesn't match precisely.

The strategy relies on you knowing which endpoints are crucial, identifying dangerous edge cases, and understanding what should occur during failures. The tool simply accelerates how quickly you can articulate and implement that strategy.

Conclusion

My Full-stack app won two hackathons. But without tests, it was a house of cards. One renamed CSS class, one changed API response, and the whole system could silently break.

Testing it both ways taught me that the manual vs AI question is the wrong question. The real skill is matching the approach to the problem.

Write unit tests by hand for business logic. Use AI-assisted testing when you're drowning in repetitive schema validation across a dozen endpoints.

Use auto-healing for E2E tests on a fast-changing UI. And for the things you can't automate yet, like Discord bot interactions or webhook delivery, document them and test them manually until you can.

If you're building something complex and thinking "I'll add tests after I deploy", flip that. Test what you can now. Document what you can't. When deployment day comes, you'll ship with confidence instead of anxiety.

Before We End

I hope you found this article insightful. I’m Ajay Yadav, a software developer and content creator.

You can connect with me on:

Twitter/X and LinkedIn, where I share insights to help you improve 0.01% each day.
Check out my GitHub for more projects.
Check out my Medium page for more blogs.
I also run a YouTube Channel where I share content about careers, software engineering, and technical writing.

See you in the next article — until then, keep learning!

How to Deploy a MERN Stack Notes App on AWS

Umair Mirza — Sat, 17 Jan 2026 02:25:39 +0000

Platforms like Vercel, Netlify, and Render simplify deployment by handling infrastructure for you. In this tutorial, we’ll step one layer deeper and work directly with AWS to understand the building blocks behind these platforms.

You'll take a small React and Express notes app and ship it straight to AWS. We'll use EC2 for the API, RDS Postgres for the database, and S3 (optionally CloudFront) for the frontend. If you're new to AWS, you can turn on the Free Tier first: https://aws.amazon.com/free.

If you’ve mostly used one-click deployments before, this guide will help you understand what’s happening behind the scenes. You’ll work directly with the core AWS services involved, focusing only on the pieces that matter so you can see how everything fits together. This will also enable you to have more control over cost, security, and scaling.

If you just want to grab the finished code, it's all in this public repo: umair-mirza/mern-notes-aws. You can clone or fork it and follow along without creating a new project from scratch.

What You’ll Build
Prerequisites
Mental Map
Free Tier Basics
Environment Variables
Step #1 - Run It Locally First
Step #2 - Push to GitHub (So EC2 Can Pull)
Step #3 - Create AWS Resources (Quick Path)
Step #4 - Configure the EC2 Box
Step #5 - Build and Upload the Frontend
Step #6 - Quick Troubleshooting
Step #7 - Secure and Save
Step #8 - Verify End-to-End
Next Steps

What You’ll Build

Before touching any buttons in AWS, it's helpful to know the exact pieces you're trying to build. At the end of this guide, you'll have a classic three-tier web app: a browser-based frontend, a backend API, and a database, all talking to each other over a network.

API (Express/Node) on EC2
Postgres on RDS (Free Tier eligible)
React/Vite frontend on S3 (CloudFront optional for CDN/HTTPS)
Health check at /api/health and CRUD at /api/notes

Prerequisites

You don't need to be a DevOps expert to follow along, but you should be comfortable running basic commands in a terminal and editing some config files. If you've ever used npm install before, then you're in the right place.

AWS account + AWS CLI configured (aws configure) – see AWS account setup and AWS CLI install.
Node.js 18+ and npm – get it from nodejs.org .
Git + GitHub repo – see GitHub getting started.
(Optional) Route 53 domain for a clean URL – Route 53 domains.

Mental Map

AWS throws a lot of jargon at you (VPCs, security groups, subnets). This section is the story version of what happens when someone opens your app in the browser, without any buzzwords. If you can picture this flow, the later AWS screens will feel less scary.

Browser loads the built React app from S3 (or CloudFront -> S3)
Browser calls the API on EC2 over HTTP/HTTPS
EC2 talks to RDS Postgres on port 5432 inside your VPC
Security groups: allow 80/443 to EC2; allow 5432 only from the EC2 SG to RDS

Free Tier Basics

AWS can be cheap if you use the free tier, but it can also surprise you with bills if you accidentally orprovision or leave things running. Here are the main knobs that affect cost for this tutorial and what to watch out for.

EC2: t2.micro or t3.micro ~750 hours/month
RDS: db.t3.micro Postgres/MySQL with ~20 GB storage
S3/CloudFront: Small sites cost pennies - free tier includes some egress
Save money: Stop EC2 when idle. Delete unused buckets/DBs

Environment Variables

Environment variables are just configuration values that live outside your code: ports, database URLs, and allowed origins. They keep secrets (like DB passwords) out of your Git repo and let the same code run in different places (local, staging, production) with different settings.

Backend: PORT, DATABASE_URL (your RDS endpoint), DATABASE_SSL (true on RDS), CORS_ORIGIN
Frontend: VITE_API_URL (API base, for example, https://api.example.com/api)

Step #1 - Run It Locally First

Before touching AWS, you want to prove the app actually works on your own machine. This removes a whole category of "Is it AWS or my code?" debugging later. In this step you just install dependencies and run both backend and frontend in dev mode.

cd mern-notes-aws

# Backend
cd backend
npm install
cp .env.example .env   # set DATABASE_URL to RDS (or local Postgres), DATABASE_SSL=true for RDS
npm run dev            # API on http://localhost:4000

# Frontend (new terminal)
cd frontend
npm install
cp .env.example .env   # keep API URL at http://localhost:4000/api for local dev
npm run dev            # SPA on http://localhost:5173

Open http://localhost:5173, add a note, and check if it persists. /api/health should return { status: 'ok' }. If something is broken here, pause and fix it before moving on. AWS will only make debugging harder.

Step #2 - Push to GitHub (So EC2 Can Pull)

Your EC2 server in AWS needs a place to pull your code from. Using GitHub is the simplest option: you push your code once, then the EC2 instance clones that repo. You can also reuse this repo later with CI/CD if you decide to automate deployments.

cd mern-notes-aws
git init
git add .
git commit -m "feat: mern notes app"
git branch -M main
git remote add origin https://github.com//mern-notes-aws.git
git push -u origin main

If you're following along with my example repo instead of creating your own, you can simply fork umair-mirza/mern-notes-aws and use that as your remote.

Before pushing, make sure your .env file is not committed to GitHub. Add it to your .gitignore so secrets like database passwords never end up in version control:

echo ".env" >> .gitignore

If you’ve already created a .env file locally, double-check it doesn’t appear in git status before committing.

Step #3 - Create AWS Resources (Quick Path)

RDS (Postgres, Free Tier template)

RDS (Relational Database Service) is AWS's way of running managed databases for you. Instead of installing Postgres manually on a VM, you click a few options and AWS handles backups, patching, and high availability. For this app we only need a small, free tier–eligible Postgres instance.

For more background, you can skim the official Amazon RDS for PostgreSQL docs.

We’ll start by creating the database layer. The settings below are the minimum you need for a small, production-style Postgres setup that stays within the AWS Free Tier while still following basic best practices.

RDS Create database Postgres Free Tier.
Class db.t3.micro, storage 20 GB gp2/gp3.
Set master user/pass. You'll need them for DATABASE_URL.
Public access: No.
Security group: allow 5432 only from the EC2 security group.
Enable backups and Require SSL. Download the RDS CA if you want strict cert validation.

S3 Bucket for the Frontend

S3 is AWS's "infinite hard drive" for files. A React/Vite app builds down to plain HTML, CSS, and JavaScript files, which are perfect to host from S3. Think of S3 as a very simple web server that just serves static files.

If you want to see more options, check the Hosting a static website on Amazon S3 guide.

Now, we’ll create an S3 bucket to host the React frontend. These options configure the bucket for static website hosting while keeping it simple and inexpensive.

Create bucket mern-notes-aws-frontend-.
For simple hosting, enable static website hosting and allow public reads, or keep private and use CloudFront + OAC.
Turn on versioning if you want rollback safety.

EC2 for the API

EC2 is "a computer in the cloud" that you control. You'll install Node.js on it, pull your code, and run server.js so that your backend API is always on. The security group attached to this instance works like a firewall.

If you've never launched an instance before, the Getting started with Amazon EC2 guide walks through the console screens you'll see.

Finally, we’ll provision a small EC2 instance to run the Express API. The configuration below focuses on a free tier–eligible setup that’s secure enough for learning and easy to extend later.

Launch Amazon Linux 2023, size t3.micro.
Inbound SG: 22 (your IP), 80 (world), 443 if you add HTTPS on the instance/ALB.
Attach this SG as the allowed source to RDS.

Optional: CloudFront + Route 53

CloudFront is AWS's CDN (content delivery network), and Route 53 is their DNS service. You don't strictly need them to get your app working, but they make it faster and nicer: your app loads from edge locations close to users and can live behind a friendly domain like app.example.com.

For more details, see Getting started with Amazon CloudFront and the Route 53 DNS developer guide.

Origin: the S3 bucket. Default root index.html. Add OAC if bucket is private.
Request an ACM cert in us-east-1, then create a Route 53 A/AAAA alias to the distribution.

Step #4 - Configure the EC2 Box

Once your EC2 instance is running, you treat it like a clean Linux machine. The commands below install the tools your API needs, pull your code from GitHub, configure environment variables, and run the server in a production-safe way.

Install basics:

sudo dnf update -y

This command updates all system packages to the latest versions. It's a good first step on any new Linux server.

sudo dnf install -y git

Installs Git so the EC2 instance can clone your repository from GitHub.

curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -

Adds the official NodeSource repository so you can install a modern version of Node.js (v20). Amazon Linux doesn’t ship with recent Node versions by default.

sudo dnf install -y nodejs

Installs Node.js and npm, which are required to run your Express API.

sudo npm install -g pm2

Installs PM2, a lightweight process manager that keeps your Node app running in the background and restarts it if it crashes or the server reboots.

Pull code and set environment variables:

git clone https://github.com//mern-notes-aws.git
cd mern-notes-aws/backend
npm install

cat <<'EOF' > .env
PORT=80
DATABASE_URL=postgres://:@:5432/
DATABASE_SSL=true
CORS_ORIGIN=https://
EOF

Start the API with PM2:

pm2 start server.js --name mern-notes-api
pm2 save
pm2 startup systemd -u ec2-user --hp /home/ec2-user

PM2 is a small process manager that makes sure your Node server keeps running if the machine reboots or the process crashes. Test on the box: curl http://localhost/api/health. From your laptop: http:///api/health (make sure SG allows 80/443).

Step #5 - Build and Upload the Frontend

In development, Vite serves your React app from memory, but in production you want a set of static files that any web server (or S3) can host. npm run build creates an optimized dist/ folder that you sync to S3 so the browser can load it.

cd frontend
setx VITE_API_URL "https:///api"
npm run build

This sets an environment variable called VITE_API_URL on your local machine. Vite only exposes environment variables to the frontend if they start with the VITE_ prefix.

Upload:

aws s3 sync dist/ s3://mern-notes-aws-frontend-/ --delete

This uploads your compiled frontend (dist/) to S3 and removes old files that no longer exist locally, ensuring the bucket reflects the current version of the app

Open the S3 website URL or your CloudFront URL.

Step #6 - Quick Troubleshooting

If something doesn't work the first time, that's normal, especially with networking and AWS permissions. This section gives you a few quick places to look before you start randomly changing settings in the console.

API 500s: pm2 logs mern-notes-api. This is often a bad DATABASE_URL or SSL flag.
DB connect issues: RDS SG must allow the EC2 SG - use the RDS endpoint.
CORS errors: CORS_ORIGIN must match your frontend origin exactly.
403 from S3: If you’re using static website hosting, allow public reads. With CloudFront, keep bucket private and use OAC.
Blank page: Confirm that you’ve uploaded dist/ to the right bucket.

Step #7 - Secure and Save

Once everything works, you don't want to accidentally expose your database to the internet or burn through free tier hours. These are simple, beginner-friendly hardening steps that make your setup safer and cheaper without turning you into a full-time security engineer.

Turn off SSH after setup or switch to SSM Session Manager.
Use HTTPS (CloudFront + ACM or ALB + ACM).
Keep RDS private and use SSM port forwarding if needed.
Ship PM2 logs with CloudWatch Agent and add alarms for CPU/status checks.
Snapshot RDS daily and stop EC2 when idle to save hours.

Step #8 - Verify End-to-End

Before you celebrate, run through the app like a real user: open it in the browser, create notes, refresh, and make sure everything behaves as expected. This confirms your frontend, API, and database are all wired together correctly.

Load the frontend (S3 or CloudFront).
Create and delete notes. They should persist in RDS.
Hit /api/health for a quick liveness check.

Next Steps

Once you're comfortable with this manual setup, you can start layering on more advanced tools. The ideas are the same: frontend, API and database but you get more automation, safety, and scalability.

Add Prisma + migrations for stronger schemas.
Add auth (Cognito/Auth0) and per-user notes.
Containerize and run on ECS/Fargate or add an ALB in front of EC2.
Use Terraform/CDK to recreate this stack with one command.

How to Get Type Safety Without Code Generation Using tRPC and Hono

Tarun Singh — Mon, 12 Jan 2026 17:53:20 +0000

Have you ever updated your backend API property name but neglected to also update the frontend? I'm sure you have. When this occurs, it leads to production crashes and unhappy customers, plus you've wasted your entire week fixing the problem.

To resolve this issue in the past, you typically had to create a multitude of TypeScript interfaces by hand, using GraphQL Code Generator to generate the interface files, or hope that it all worked out. Well, there’s a better way to accomplish this now, without the need for code generation.

tRPC and Hono are two applications that are changing how we develop TypeScript-based applications throughout the entirety of the full-stack.

By the end of this tutorial, you’ll understand:

Why traditional REST APIs fail at type safety
How tRPC provides full end-to-end type inference between backend and frontend
How Hono delivers type-safe APIs while staying REST-friendly
When to choose tRPC vs Hono for your projects
How these tools improve developer experience, team velocity, and reliability

If you’re building full-stack TypeScript applications and want fewer runtime bugs and faster iteration, this guide is for you.

Prerequisites
The Problem with Traditional APIs
What Makes tRPC Different?
Hono: The Lightweight Challenger
Why This Matters These Days
Getting Started
The Future is Type-Safe

Prerequisites

To follow along comfortably, you should have:

Basic knowledge of TypeScript
Familiarity with REST APIs and how frontend-backend communication works
Some experience with Node.js and modern JavaScript frameworks
A general understanding of frontend frameworks like React or Next.js (helpful, but not required)

You don’t need prior experience with tRPC, Hono, or GraphQL.

The Problem with Traditional APIs

You’ve probably written something like this a hundred times:

// Backend (Express)
app.post('/api/users', (req, res) => {
  const { name, email } = req.body;
  // Do stuff with user
  res.json({ id: 1, name, email });
});

// Frontend
const createUser = async (name: string, email: string) => {
  const response = await fetch('/api/users', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ name, email })
  });
  return response.json(); 
};

The backend knows the shape of the data. But the frontend...it hopes it gets it right. You end up writing interfaces manually, like:

interface User {
  id: number;
  name: string;
  email: string;
}

If you change the backend tomorrow to return userId instead of id, TypeScript won't catch it. Your types and reality have diverged, and you won't know until runtime.

GraphQL tried to solve this with schemas and codegen, but honestly? Setting up GraphQL feels like assembling IKEA furniture without instructions. You need a schema, resolvers, code generation tools, and suddenly your "simple" API has a 30-minute setup process.

What Makes tRPC Different?

tRPC flips the script entirely. Instead of defining your API in a separate schema language, your TypeScript code is the schema. Here's the same API in tRPC:

// Backend (tRPC router)
import { initTRPC } from '@trpc/server';
import { z } from 'zod';

const t = initTRPC.create();

export const appRouter = t.router({
  createUser: t.procedure
    .input(z.object({
      name: z.string(),
      email: z.string().email(),
    }))
    .mutation(({ input }) => {
      // Do stuff with user
      return { id: 1, name: input.name, email: input.email };
    }),
});

export type AppRouter = typeof appRouter;

This is where it gets cool. On your frontend:

// Frontend - fully type-safe!
import { createTRPCClient } from '@trpc/client';
import type { AppRouter } from './server';

const client = createTRPCClient({
  url: 'http://localhost:3000/trpc',
});

// TypeScript knows EVERYTHING about this call
const user = await client.createUser.mutate({
  name: 'Alice',
  email: 'alice@example.com'
});

// user is automatically typed as { id: number; name: string; email: string; }

No code generation or build step, or GraphQL schema. Just pure TypeScript inference doing its thing. If you rename id to userId in your backend, your frontend will immediately show a TypeScript error. You'll catch it before you even save the file.

This is what we call end-to-end type safety, and it's honestly a great transition.

Hono: The Lightweight Challenger

While tRPC is amazing for full-stack TypeScript apps where you control both ends, Hono takes a slightly different approach. It's a lightweight web framework that gives you type safety while still being a traditional HTTP framework.

Here's the same example in Hono:

import { Hono } from 'hono';
import { z } from 'zod';
import { zValidator } from '@hono/zod-validator';

const app = new Hono();

const userSchema = z.object({
  name: z.string(),
  email: z.string().email(),
});

app.post('/api/users', zValidator('json', userSchema), (c) => {
  const { name, email } = c.req.valid('json');
  return c.json({ id: 1, name, email });
});

export type AppType = typeof app;

On the frontend, you can use Hono’s RPC client:

import { hc } from 'hono/client';
import type { AppType } from './server';

const client = hc('http://localhost:3000');

const response = await client.api.users.$post({
  json: { name: 'Bob', email: 'bob@example.com' }
});

const user = await response.json();
// user is fully typed!

Hono is incredibly fast (it runs on Cloudflare Workers, Deno, Bun, and Node.js), and it gives you that sweet type safety while still being a "regular" HTTP framework. You get RESTful routes, middleware, and all the familiar patterns – just with TypeScript powers.

Why This Matters These Days

You might think to yourself, “Okay, I know what you mean, but why should I care about it?” There’s a reason why these tools are being utilized more now than ever before.

Developer experience is essential

In 2026 and beyond, we’ll no longer accept long feedback loops. The ability to modify your backend code and see what might break on your frontend application without having to run the application will be fantastic for productivity. We’ll spend less time fixing bugs and more time creating new functionalities.

Smaller teams, better apps

With tRPC or Hono, one developer can create an entire full-stack application with type safety at a very fast pace because they don’t have to switch back and forth between REST documentation and TypeScript interfaces – all the data is flowing to and from their backend code directly to their frontend.

The end of “Works on my machine“

With type safety, errors are caught at compile time instead of at the time your end-user clicks on a button. This is especially impactful when working in larger teams, when the backend developers and front-end developers may not be in constant communication with one another.

Getting Started

Want to try this out? Here's the fastest way:

For tRPC:

npm create @trpc/next-app@latest

This scaffolds a Next.js app with tRPC already configured. Check out the official tRPC docs for more.

For Hono:

npm create hono@latest

Pick your runtime (Node.js, Cloudflare Workers, etc.), and you're off to the races. The Hono documentation is excellent and super approachable.

The Future is Type-Safe

Look, REST isn't going anywhere, and GraphQL has its place. But for full-stack TypeScript developers, tRPC and Hono represent something special: type safety without the ceremony. No code generation or no schema duplication, just TypeScript doing what it does best.

In the future, when you start a new project, give one of these a shot. Your future self – the one who's refactoring code at 2 AM – will thank you.

Happy coding!

Become a Full Stack Developer with One Video

Beau Carnes — Wed, 01 Oct 2025 21:08:15 +0000

What if you could learn what you need to know to become a full stack developer in just one video.

We just published a 48-hour course on the freeCodeCamp.org YouTube channel that will take you from square one to being a hireable full-stack developer. This course was developed by the team at Scrimba.

This course starts right at the beginning with HTML and CSS, giving you the essential building blocks. Then, it dives deep into JavaScript, ensuring you understand the advanced concepts needed for complex applications.

From there, you’ll learn the industry-standard front-end tools: React.js for building slick user interfaces and Next.js to handle the heavy lifting like routing and server-side rendering. For the backend, you will learn about Node.js and learn how to connect it all to databases.

The course also covers TypeScript, which is important for writing safer, more scalable code that won't break at the drop of a hat. And you will learn about testing, so you can confidently build features that actually work.

Finally, the course covers Tools of the Trade and a gives practical look at how AI Engineering is starting to change the way we code. By the time you finish this one course, you won't just have a beginner's understanding; you'll have a complete skill set ready to tackle your first job or build your own startup.

Watch the full course on the freeCodeCamp.org YouTube channel (48-hour watch).

Learn Key System Design Principles Behind High-Traffic Platforms Like Gaming and Job Discovery

Prankur Pandey — Wed, 20 Aug 2025 16:34:29 +0000

Over the last three months, life has had me juggling a lot – managing my marriage, taking care of family health issues, and overseeing new construction work at home. Somehow, I got through it all. But looking back, I realised something important: I could’ve handled it much better if I had a system in place.

For me, a system means a set of rules, processes, and triggers that guide the entire workflow. This helps you conserve energy and not have to figure things out in the moment. It keeps things productive, efficient, and consistent.

Now that the chaos has settled, I’ve been thinking a lot about systems – not just in life, but in tech. I wish I had applied the same principles of system design earlier.

In this article, we’re going to explore real-world system design examples from domains like gaming and job platforms. These industries don’t just scale massively – they also demand high availability, low latency, and seamless customer experiences. Understanding how they’re built is a powerful way to level up your thinking as a developer or architect.

What We’ll Cover

Introduction: What is System Design and Why Scale Matters
Approaches to System Design
Important Concepts in System Design
Case Studies: Scaling in the Real World
- Case Study 1: Scaling a Job Search Application
- Case Study 2: Scaling an Online Gaming Application
Q&A
Final Notes
Conclusion

Introduction: What is System Design and Why Scale Matters

System design is the process of defining the architecture, modules, interfaces, and data of a system.

In other words, system design means explaining the different parts of a system, like its structure, building blocks (modules), and components.

It’s a process used to define, develop, and design a system in a way that meets the specific needs of a business or organisation.

The main goal of system design is to give enough information and details about the system, and to properly implement its parts using models and views. Let’s now talk about the different parts of a system.

Elements of a System:

Architecture: This is a basic structure or model that shows how the system works, looks, and behaves.
We often use flowcharts to explain and represent this architecture.
Modules: These are smaller parts or sections of the system. Each module handles a specific task. When all modules are combined, they make the complete system.
Components: These provide a specific function or a group of related functions. Components are usually made from one or more modules.
Interfaces: This is the connection point where different parts (components) of the system exchange information with each other.
Data: This refers to managing information and how it flows through the system.

Why System Design Matters

System design is important for a number of practical reasons. First, it can help companies and teams solve complex business problems and make sure they thoroughly analyse all requirements before building. It also reduces the chance that errors will be introduced into processes while making design phases more efficient and structured. Finally, it helps you efficiently gather and present your data in a useful format and improves the overall quality of the system.

Approaches to System Design

There are several methods you can use to approach system design. The main ones are:

1. Bottom-Up Approach

In this method, the design starts from the lowest-level components or subsystems. These small parts are gradually combined to form higher-level components. This process continues until the entire system is built as one complete structure.

The more abstraction we use, the higher the level of the design becomes.

Advantages:

Components can be reused in other systems.
It’s easier to identify risks early.
It helps in hiding low-level technical details and can be combined with the top-down approach.

Disadvantages:

It’s not very focused on the overall structure of the problem.
Building high-quality bottom-up solutions is hard and time-consuming.

2. Top-Down Approach

Here, the design starts from the entire system, and you break it down into smaller subsystems and components as you go. Each of these subsystems then gets broken down further, step by step, creating a hierarchical structure.

In simple terms, you start with the big picture and keep dividing it until you reach the smallest parts of the system.

To sum up, design starts with defining the whole system, then continues by defining its subsystems and components. When all definitions are ready and fit together, the system is complete.

Advantages:

The focus is on understanding the requirements first, which leads to a responsive and purpose-driven design.
It’s easier to handle errors in interfaces between components.

Disadvantages:

Components can’t be reused easily in other systems.
The resulting architecture is often less flexible or not very clean.

3. Hybrid Design

The hybrid design approach is a mix of top-down and bottom-up methods. Instead of committing to just one way, it takes the strengths of both. You start by looking at the overall system (like in top-down) so that you don’t lose sight of the big picture. At the same time, you also focus on building solid, reusable modules or components (like in bottom-up).

In simple terms, you first plan the big picture, then create smaller components that can work independently, and finally combine everything into a cohesive system.

For instance, in our sports team site, we’d use top-down to define the whole fan journey (homepage → match details → live scores). But bottom-up, we’d build modular components like authentication or stats tracking, which can later be reused in new features like ticket booking or merchandise sales.

Advantages:

You get the clarity of a top-down plan while still building reusable modules.
It strikes a balance between high-level design and detailed implementation.
Risks are easier to manage since you’re considering both structure and components.

Disadvantages:

It can be complex to manage since you’re juggling two approaches.
Requires more coordination between teams working on different levels.
It might take more time compared to using a single approach.

Important Concepts in System Design

Before exploring core components, I want you to first understand two key concepts:

Full stack web application components
How computers talk to each other (via the internet)

Full Stack Web Application Components

A full-stack web application is a software application that combines both the frontend (what users see and interact with) and the backend (the server, database, and logic that power the app) into one complete system.

Generally, simple websites don’t require much system design – and in some cases, no system design at all. But when it comes to viral applications or platforms offering complex services, system design becomes essential. Most modern applications are full-stack applications, meaning they involve multiple interconnected layers working together.

Here’s a simplified overview of a typical full-stack application:

Before diving deep into each of these components, let me first give you a quick, high-level overview of what they are and how they fit into the bigger picture (starting from the bottom of the image above).

Frontend – The user interface where people interact with your application.
Backend – The logic and brain of the application that processes requests.
APIs – The bridge that allows communication between frontend, backend, and external services.
Database – The storage system where all your structured information lives.
Server – The infrastructure that hosts, runs, and delivers your application.

Now, we need to understand how computers talk to each other.

How Computers Talk to Each Other (The Internet)

When you type a website's URL into the browser – and this site could be a simple portfolio site or a full stack app – how does your computer know where to send the request? It uses the Domain Name System (DNS). The DNS is like a phonebook for the internet – it translates a human-readable website name, like "example.com," into a unique numeric IP address that computers can understand.

Once your computer has the IP address, it uses communication protocols to send and receive data. One of the most important protocols is TCP. It breaks data into small, numbered packets. If a packet gets lost or arrives out of order, TCP ensures it's resent and reassembled correctly, making it a very reliable way to send data.

On top of TCP, we use higher-level protocols like HTTP. This is an application-level protocol that's easier for developers to use. It's the language your browser speaks to the server.

HTTPS is the same, but it adds an extra layer of encryption for security.

Now that we understand the basics of the Internet, remember that it serves billions of people worldwide.

Let’s break this down with a real-life example. Imagine you own a restaurant with a seating capacity of 50 people. One day, 10 extra guests arrive – and with a bit of adjustment, you still manage. But suddenly, a thousand more people show up at your door. What would you do then? It’s not just about adding more chairs and tables anymore – you’ll need extra food supplies, more staff, and a bigger setup to handle such massive traffic.

This simple example reflects the real challenge of growth and scalability. And that’s exactly what I’ll be diving into in the next chapter of this tutorial.

The Problem of Growth

Imagine you've built a simple website for a local sports team. Initially, it's just you and a few friends using it, so a single server is sufficient. This server holds all the website's logic and connects to a single database where player stats are stored.

As the team becomes more popular, though, more people visit your site, and it suddenly becomes slow. This is a scaling issue. Your system can't handle all the new traffic.

Scaling Your System: Two Main Ways

There are two ways to solve this. The first is vertical scaling. This is like giving your one server a bigger engine and more memory. You'd upgrade the CPU (the brain) or add more RAM (temporary memory). You could also use a faster disk storage like an SSD.

The problem is, you can only upgrade so much before you hit the limits of what's available. Plus, if that single server fails, your entire website goes down.

A better approach is horizontal scaling. This means adding more servers instead of just upgrading one. Now you have a team of servers, and each can handle a portion of the incoming user requests.

This approach allows for almost unlimited growth. It also creates redundancy and fault tolerance, because if one server breaks, the others can pick up the slack, and your site stays online.

Directing Traffic with a Load Balancer

With multiple servers, you need a way to make sure no single server gets overwhelmed. This is where a load balancer comes in. It acts like a traffic cop, sitting in front of your servers and directing each new request to the best-suited server. It uses different algorithms to decide where to send the traffic.

For example, the Round Robin method sends requests to servers one by one, in a cycle. Another method is Least Connection, which sends the request to the server that has the fewest active connections.

Speeding Up Your Website with Caching and CDNs

Imagine your website is now used by people all over the world. A user in another country might experience slow loading times because their request has to travel all the way to your servers.

To fix this, you can use a Content Delivery Network (CDN). A CDN is a network of servers around the world that store copies of your website's static files – like images, videos, and text files. When a user requests one of these files, the CDN serves it from the closest server, making the website load much faster for them.

This process is a form of caching. Caching is the general idea of making copies of data and storing them in a faster-to-access location. You can cache data on your server so it doesn't need to fetch the same player stats from the database every time. This reduces the load on your database and speeds up the entire application.

You can read more about the difference between CDNs and caching here.

Building Your Application: Monolith vs. Microservices

As your website grows, its code can become a tangled mess. You might start with a monolith, where all the features (like player stats and live scores, in our example) are built into a single, large program. A monolith is easier to start with, but it can be hard to manage and update.

A better approach for a large-scale application is to use a microservice architecture. This means breaking your application into smaller, independent services, each with a specific job. For example, one service could handle player stats and another could handle live scores. This makes your code more organised and easier to update, because a change in one service won't affect the others.

With microservices, you need an API Gateway. This acts as a single entry point for all user requests, directing them to the correct microservice behind the scenes. It also handles security and other common tasks.

The APIs

Think of APIs (Application Programming Interfaces) as the “middlemen” that let different pieces of software talk to each other.

In simple terms, an API is like a waiter in a restaurant. You (the user) tell the waiter what you want, the waiter takes your order to the kitchen (the system), and then brings the food (data or result) back to you.

Without APIs, your app, website, or software wouldn’t know how to ask another system for information or services.

For example, on our sports team website:

The front-end (what fans see) uses an API to fetch player stats from the database.
When someone buys match tickets, the API talks to the payment system to confirm the transaction.
If fans want live score updates, the API makes sure the real-time data flows smoothly from the server to their screen.

So, APIs are important for system design because they shape how efficiently different systems connect, share data, and stay reliable under real-world use.

Your front-end and back-end services can communicate in several ways. The most common is a REST API. It's a standardised set of rules that uses HTTP to create a consistent way for a client and server to talk to each other. For example, it defines a standard way to signal a successful request ("OK") or a server error ("Internal Server Error").

When to use REST

Best when: you need simplicity, broad adoption, and easy integration with browsers, mobile apps, or third-party services.
Example: CRUD apps (blogging platforms, e-commerce sites, user management).
Strength: Human-readable JSON, stateless, widely supported.
Weakness: Over-fetching (getting more data than needed) or under-fetching (not enough data).

Another style is GraphQL. Instead of getting all the data a REST API provides, GraphQL lets the client ask for only the specific data it needs, which can make things faster and more efficient.

When to use GraphQL

Best when: clients (like mobile apps) need fine-grained control over exactly what data they fetch.
Example: social media feeds, dashboards with lots of widgets, mobile apps with limited bandwidth.
Strength: Flexible queries, reduces over-fetching, strong typing system.
Weakness: More complex server setup, which can cause performance issues if queries aren’t optimised.

For server-to-server communication, gRPC is often used. It's known for being very fast because it uses a more efficient data format called Protocol Buffers instead of JSON.

When to use gRPC

Best when: services talk to each other in microservice architectures, and speed/efficiency is critical.
Example: real-time systems (streaming, payments, IoT, machine learning inference).
Strength: Super fast (binary Protocol Buffers), built-in support for streaming, strong contracts.
Weakness: Not browser-native (needs extra tooling for web), harder debugging compared to REST

So to summarize based on my observations of what I have worked on so far:

If you’re building something public-facing and widely consumed → go for REST.
If your app has complex, dynamic queries from clients → go for GraphQL.
If you’re dealing with high-performance internal service-to-service calls → go for gRPC.

In system design, choosing the right API style directly affects performance, scalability, and user experience. If you pick REST for its simplicity, GraphQL for its flexibility, or gRPC for its speed, you’re shaping how well your system can grow and adapt as real-world demands change.

Handling Real-Time Data

Real-time data handling is challenging because it requires maintaining an active connection to continuously transmit and receive data simultaneously. Traditional servers follow a request–response model, where data is only sent when explicitly requested.

That's where WebSockets come in. Unlike HTTP, which is a one-and-done request-and-response model, a WebSocket creates a continuous, two-way connection between the client and server. This allows the server to send updates to the user as soon as they happen, creating a real-time experience.

When microservices need to communicate without being directly connected, they can use message queues. A service sends a message to the queue, and another service picks it up when it's ready. This helps to decouple the services, so they don't have to worry about the other service being available at that exact moment.

On our sports site, WebSockets allow fans to see live scores instantly without refreshing the page – just like in chat apps, but here it keeps the excitement of the game alive in real time

Databases

Databases are a critical part of any full-stack application because they serve as the permanent home for user data. Once you’ve decided how to scale your servers and manage communication, you also need to consider the database layer. If everything else scales but the database does not, it can quickly become a bottleneck – leading to crashes, inconsistent records, or even data loss.

Many applications rely on relational databases (SQL), which store data in structured tables with rows and columns and are great for handling structured information. But for applications requiring high flexibility or handling massive unstructured datasets, NoSQL databases (like MongoDB or Cassandra) are often chosen. These databases don't follow the strict rules of SQL and are better for handling massive amounts of data.

They follow ACID properties:

Atomicity: A transaction is all or nothing.
Consistency: The data always remains in a valid state.
Isolation: Multiple transactions don't interfere with each other.
Durability: Once a transaction is complete, the data is permanently saved.

Just like with servers, you might need to scale your database. You can use sharding, which divides your data across multiple databases, or replication, which creates copies of your database to handle more read requests.

Understanding the CAP Theorem

When you're dealing with a distributed system and multiple databases, you inevitably face trade-offs. The CAP Theorem states that you can only guarantee two out of the following three properties at the same time:

Consistency – Every user sees the same, most up-to-date data.
Availability – The system is always available to respond to requests.
Partition Tolerance – The system continues to operate even if a part of the network fails.

Now, from a system design perspective, this theorem forces us to make conscious architectural choices. For example, in financial applications (like banking), consistency often takes priority over availability because even a small inconsistency in balance data can cause chaos.

On the other hand, in social media feeds, availability and partition tolerance are often prioritised – it's okay if you see a slightly outdated post, but the system should never be down.

In the flow we’ve been discussing, whenever we introduce a new component or scale out across multiple regions, we need to reassess which two guarantees matter most for our business case. That decision directly drives what database technology we pick, how we design failover strategies, and what trade-offs we accept in user experience.

In short, the CAP theorem isn’t just a theory – it’s a practical compass. It guides us to balance user expectations, business priorities, and technical feasibility without breaking existing functionality, while still leaving room for future growth.

Rate Limiting and Monitoring

When designing a system, it’s not just about making it work – it’s about making it resilient. Two core guardrails here are rate limiting and monitoring.

What is Rate Limiting?

Rate limiting is the practice of controlling how many requests a user, client, or service can make to your system within a given timeframe. For example, you might cap an API at 100 calls per user per hour. This prevents abuse, safeguards against denial-of-service attempts, and ensures fair usage across all consumers.

Rate limiting comes into play any time your service is exposed publicly or internally to multiple clients.

To incorporate it, you can implement limits at the API gateway, reverse proxy (like NGINX), or within your service logic itself. Many cloud providers (AWS API Gateway, GCP Endpoints) also have built-in support.

What is Monitoring?

Monitoring is the practice of collecting metrics, logs, and traces from your system to understand its health in real time. Typical signals include:

Error rates (for example, how often requests fail)
Latency (how long requests take)
Traffic volume (load across the system)
Resource utilisation (CPU, memory, disk, and so on)

Monitoring is important from day one – it’s your feedback loop. Without it, you’re essentially flying blind.

To work it into your system, you can use observability stacks like Prometheus + Grafana, or managed solutions like Datadog, New Relic, or CloudWatch. You can also set alerts for threshold breaches (for example, 5% error rate spike).

In practice, rate limiting and monitoring work hand-in-hand. Rate limiting proactively guards against overload, while monitoring gives you visibility into whether the limits are working, whether scaling is needed, or whether a new type of failure is emerging.

For example, if you’ve designed a booking system (like in our earlier flow), rate limiting would ensure a single user can’t spam seat reservations, while monitoring would flag anomalies such as unusual spikes in request volume or sudden latency increases – helping you act before the system collapses.

Why Does This Matter for System Design?

These topics matter for good system design because they form the foundational building blocks of how modern applications actually operate in the real world. The way systems communicate, the type of APIs we adopt, and how we manage real-time interactions directly influence whether a product feels fast, reliable, and seamless – or slow and frustrating. In short, they determine how well the overall experience holds up when real users put it to the test.

When we develop a deeper understanding of how computers communicate, we begin to see the inner mechanics of client–server architecture – how APIs fetch data from databases through backend system calls. From this baseline, we can pivot into higher-level concerns:

Scalability and resilience: Using load balancers to protect against server overload.
Security: Introducing rate limiting to mitigate potential cyberattacks.
Efficiency: Choosing the right type of API calls and leveraging caching/CDNs for speed and reduced overhead.
Reliability: Implementing logging and monitoring to detect issues early and debug faster.

Together, these practices elevate a system from simply working to being robust, performant, and future-ready.

We’ve discussed the basics of all the most important concepts you’ll need to understand before building an end-to-end system. Now it’s time to deep dive into the case studies, where I’ll show you how different types of applications use system design to scale and serve billions of users.

I have picked services that are complex to build and handle multiple different types of components at a time, like gaming, education, and job search platforms.

Now let’s decode each of them together, and I’ll explain how I would scale the application if I were the developer building it.

Case Studies: Scaling in the Real World

System design is best understood when you see it in action. To show how principles like scaling, caching, load balancing, and real-time data management come together, let’s walk through two very different types of applications:

A job search platform (focused on structured data and reliability).
An online gaming platform (focused on real-time speed and responsiveness).

Looking at both will show you that, while the tools and concepts may be similar, the way we apply them depends on the type of system we’re building.

Both are high-traffic platforms, but with totally different needs. The job portal is about accuracy, reliability, and data-driven workflows, while the gaming platform is about instant responsiveness, fairness, and global reach.

In a job portal, a 1-second delay just means waiting. In a gaming app, a 1-second delay could mean losing the match. Both are failures – but for completely different reasons, and with different consequences.

Together, they show how the same building blocks of system design (scaling, caching, APIs, monitoring) are applied differently depending on context.

Case Study 1: Scaling a Job Search Application

A job search platform is one of the most used applications nowadays, as there are always people looking for a job. And there are many different job portals out there that handle the complete process, from finding jobs to user onboarding.

We’ll look at an example site called Upstaff. It’s a platform that focuses on hiring AI engineers as its core service (although it services other job profiles as well). At its core, it handles structured information – things like user profiles, job postings, and applications.

Day one, you have a few hundred users. On day one hundred, you may have tens of thousands. And in a year? Possibly millions. That growth means you have to think about scale, speed, and data integrity from the start.

🔹 The Core Components

User Management: registration, login, and role-based access (job seeker vs employer).
User Profiles: résumés, skills, preferences, stored in structured databases.
Job Posting and Listings: employers create jobs, seekers browse/search/filter.
Application Tracking: Every job seeker’s application status needs to be accurate and up to date.
Recommendation Engine: jobs matched to users based on history and profile.
Notifications: alerts for new job matches, recruiter replies, deadlines.

Every one of these features depends on the system’s ability to handle large amounts of structured data – and handle it reliably.

Step 1: Starting Small

At the beginning, everything can run on one server with a single database. This setup is enough for a few thousand users.

Step 2: Growth and Traffic Spikes

As more users join, the single server starts to slow down. To fix this, we add a load balancer and scale horizontally – adding multiple servers that share the traffic.

Step 3: Database Challenges

Soon, the database becomes the bottleneck. Searching across thousands of jobs slows things down. To fix this, we:

Use sharding (split the database by user IDs or job IDs).
Add a cache (like Redis) to store frequent queries such as “Software Engineer in New York.”
Use a CDN to deliver logos, profile pictures, and other static files faster.

Step 4: Heavy Features

New features like a résumé parser or recommendation engine require extra computing power. Instead of overloading the main app, we move these into separate microservices.

Step 5: Security and Reliability

Finally, as traffic grows, we add:

Rate limiting to stop any one user from spamming APIs.
Monitoring to track errors, latency, and user activity in real time.
API Gateway to ensure all requests are secure and validated. Here is an overview of the entire system scaling in an image :

This example shows how careful planning makes growth smooth. By scaling horizontally, caching smartly, and splitting heavy features into microservices, a job portal like Upstaff can handle millions of users without breaking.

Case Study 2: Scaling an Online Gaming Application

Now let’s flip the script. In a gaming platform like this site, speed and responsiveness matter more than anything. A 1-second delay in a job search is annoying. But in gaming, a 1-second delay can make players quit forever. Unlike job portals, the biggest challenge here is real-time responsiveness. A tiny delay can ruin the user experience.

🔹 The Core Components

User Management Service: accounts, profiles, and login.
Game Lobby and Matchmaking: pair players by skill, region, and latency.
Game Server Manager: spin up and manage live matches.
Real-Time Communication: powered by WebSockets or UDP for low latency.
Game State Store (Redis): fast sync of health, scores, and positions.
Leaderboard & Stats Engine: global rankings, achievements, and progress.
In-Game Economy: coins, tokens, inventory.
Payment Gateway: subscriptions and purchases.
Anti-Cheat Security Layer: fairness across all players.
Monitoring and Logging: server uptime, latency, and crash reports.

Unlike a job portal, every millisecond counts.

Step 1: Starting Small

At first, one powerful server is enough to run both the game logic and user accounts. With just a few players, things run smoothly.

Step 2: More Players, More Problems

As millions of players log in, the single server crashes. To fix this, we:

Add a Game Server Manager that spins up separate servers for each match.
Introduce a load balancer that assigns players to available servers.

Step 3: Real-Time Data Handling

In gaming, speed is everything. Instead of slow HTTP, we switch to WebSockets or UDP for instant communication. To keep everyone’s game view in sync:

Use in-memory databases like Redis for positions, scores, and health.
Update leaderboards in near real time.

Step 4: Scaling Features

Other services run in parallel:

Matchmaking service pairs players by skill, location, and latency.
Economy service manages coins, rewards, and in-game items.
Payment gateway handles subscriptions and purchases securely.
Notification system sends updates like “new event starting.”

Step 5: Global Expansion and Security

When the game expands worldwide:

Use a CDN to deliver maps and skins quickly to all regions.
Add an Anti-Cheat layer to detect and block unfair play.
Build an Admin and Monitoring panel to track system health and user behavior.

In gaming, system design focuses less on structured data and more on low latency, real-time communication, and fairness. Scaling here means keeping gameplay smooth and secure, even when millions of players join at once. Here is the image representation of the complete game platform system design

Why Both Case Studies Matter

You might wonder – why show two different systems instead of just one? The answer is that system design isn’t “one-size-fits-all.”

The job portal teaches us how to scale structured, data-heavy applications where reliability and accuracy matter most.
The gaming platform shows us how to design for speed, real-time communication, and fairness under extreme load.

Together, these examples prove that the same system design principles of scaling, caching, monitoring, and microservices apply everywhere. What changes is how you use them to solve the unique challenges of your platform.

Q&A

How to get into system design if you don’t understand anything (yet)?

I get this question all the time – and the first thing you need to know is that system design isn’t some separate, elite domain. It’s an additional skill that complements your development journey.

If you're a full-stack developer (or aiming to be one), learning system design gives you a huge edge. After all, building an app isn't just about making it work – it’s about making it work well at scale.

So if you’re just starting and don’t even know how to become a full-stack developer yet, start there. Learn to build applications first, and then system design will start making a lot more sense. Read this guide How to Become a Full-Stack Developer in 2025 (and Get a Job) – A Handbook for Beginners to learn how to become a full-stack developer.

How do you understand system design concepts?

The short answer: with time and consistent practice.

Think of it like this: if you know how to use a pencil, it’s up to you whether you use it to sketch or to write. The pencil is just a tool. Similarly, in system design, once you understand the core concepts, it’s about knowing when and where to apply them. The rest – frameworks, tools, and technologies – are just means to an end.

It’s not about memorising patterns, it’s about developing the instinct to use the right building blocks at the right time.

What tools should you know before diving into system design?

The truth is, the list keeps growing. New tools and platforms are constantly emerging. But in my experience, having a solid foundation in the following areas makes a huge difference:

Full Stack Development – so you understand how both frontend and backend systems interact.
Cloud Platforms (like AWS, GCP, or Azure) – because most modern systems are cloud-native.
CI/CD Pipelines – for automating testing, integration, and deployment.
Deployment Strategies – to know how to roll out new changes with minimal risk.

Mastering these gives you the technical muscle to design systems that are scalable, reliable, and production-ready. I am a frontend developer, why should I know the system design

What resources should I study to learn system design?

In my last article, I shared all the resources that helped me learn system design.

System design is crucial for building reliable, high-performance applications. I explored the following resources:

Case studies and real-world architectures can also help you understand large-scale systems. You can follow any big tech engineering blog (Uber has a great one).

For high-level concepts, I went through the Grokking System Design course. It’s a paid resource, and I used it to deepen my understanding of system design. It’s not mandatory, but it helped me think about architecture at scale.

Note: there are other sites and courses out there of course, but I only share what I have personally experienced and used, and I focus on FREE material first.

Where to practice system design

This is where real learning begins. Start by picking any existing application from the internet, just like I did. Google something specific, like “job application portal,” but avoid the results on the first page. Those apps are usually well-optimised and already follow best practices in system design.

Instead, dig deeper and explore results from the second or third page. Look for an app that seems to be in its early stages.

Once you find one, try to understand how the entire application works. Break it down into its core components and then imagine what would happen if that app started receiving 1 million users a day. You’ll naturally begin to see what system design elements are needed to handle that kind of load.

Final Notes

Learning system design becomes much easier when you’ve already built something. Let’s say you’ve created an app and now you're thinking about how to scale it – that’s where real learning begins. The moment you start writing down your requirements (like how your app should behave when it starts getting more traffic), you naturally begin to develop system-level thinking. It’s this process of planning and anticipating real-world usage that turns theory into a practical skill.

Conclusion

Full Stack + System Design = The Ultimate Developer Stack 🔥

By mastering these skills, you can turn any idea into a real-world product, secure high-paying jobs, and even start your tech venture.

Now it's your turn – what are you building next? Let me know!

That’s all from my side. If you found this article helpful, feel free to share it and connect with me. I’m always open to new opportunities:

Follow me on X: Prankur's Twitter
Connect with me on LinkedIn: Prankur's LinkedIn
Follow me on GitHub: Prankur’s Github
View my Portfolio: Prankur's Portfolio

How to Build Production-Ready Full Stack Apps with the MERN Stack

Mohit Menghnani — Mon, 07 Jul 2025 13:48:52 +0000

As developers, we’re always looking for more efficient tools. The MERN stack (MongoDB, Express.js, React, and Node.js) stands out for its JavaScript-centric nature, offering a unified language across the entire application.

In this guide, you'll build a complete Task Manager app with user authentication, protected routes, and full CRUD functionality, built with React on the frontend and Express/MongoDB on the backend.

This article will serve as your hands-on, code-first guide to building, securing, and deploying a MERN application, drawing from my own practical experience. Every section has code you can run, and I’ll give concise explanations along the way.

It doesn’t matter if you're just getting started with MERN or looking to level up your architecture and production deployment knowledge – this article is designed to get you from zero to production with confidence.

Prerequisites
- Tools & Tech Stack
- Skills & Setup
Project Setup: Laying the Groundwork
- Project Structure
- Code Quality: Linting and Formatting
Testing: Ensuring Robustness
- Backend Testing (Node.js/Express.js)
- Frontend Testing (React Testing Library + Cypress)
How to Build the Task Manager
- Backend Implementation (Node.js/Express.js)
- Frontend Implementation (React)
Deployment: From Localhost to Live
Security Best Practices: Fortifying Your Application
Monitoring and Logging with Winston and Morgan
- Frontend Error Monitoring (Sentry)
Conclusion

Prerequisites

Before jumping in the project, here’s what you’ll need to get the most out of this tutorial:

Tools & Tech Stack

You’ll be using the following technologies throughout the project:

Node.js & npm – Backend runtime and package manager
Express.js – Web framework for Node
MongoDB Atlas – Cloud-hosted NoSQL database
Mongoose – ODM for MongoDB
React – Frontend UI library
React Router – For client-side routing
Axios – For making API requests
Jest & Supertest – For backend tests
React Testing Library & Cypress – For Frontend unit and E2E tests
ESLint + Prettier – For code formatting, linting
Husky – To setup pre-commit hooks
Helmet, Joi, express-rate-limit, cors – For security, validation, and best practices
PM2 & NGINX – For backend deployment
Sentry – For error monitoring

Skills & Setup

Basic knowledge of JavaScript, React, and Node.js
Familiarity with REST APIs and HTTP request/response flows
Git and a GitHub account for version control
A free MongoDB Atlas account
Node.js and npm installed locally (Node 18+ recommended)

Project Setup: Laying the Groundwork

A well-structured project is crucial for maintainability. We'll adopt a clear separation between the front end and the back end here.

Project Structure

This structure clearly separates the React front end (client/) from the Node.js/Express.js back end (server/), promoting modularity and easier management.

my-mern-app/                # Root folder
├── client/                 # React frontend
│   ├── public/
│   ├── src/
│   │   ├── components/
│   │   ├── pages/
│   │   ├── App.js
│   │   └── index.js
│   └── package.json
├── server/                 # Node.js/Express.js backend
│   ├── config/
│   ├── controllers/
│   ├── models/
│   ├── routes/
│   ├── services/
│   ├── app.js
│   └── package.json

Code Quality: Linting and Formatting

Consistency is key when you’re building a production-grad application like this one. We'll use ESLint with Airbnb style and Prettier for automated code quality and formatting.

To install these tools, run this in your terminal:

npm install --save-dev eslint prettier eslint-config-airbnb-base eslint-plugin-prettier

And here are some setups with their recommended configurations:

This configuration sets up ESLint for a Node.js project using the Airbnb and Prettier style guides, with custom rules to relax strict linting constraints like allowing console.log and disabling mandatory function names.

.eslintrc.js (server-side example)

module.exports = {

  env: {

    node: true,

    commonjs: true,

    es2021: true,

  },

  extends: ["airbnb-base", "prettier"],

  plugins: ["prettier"],

  parserOptions: {

    ecmaVersion: 12,

  },

  rules: {

    "prettier/prettier": "error",

    "no-console": "off",

    "func-names": "off",

    "no-process-exit": "off",

    "class-methods-use-this": "off",

    "import/no-extraneous-dependencies": "off",

  },

};

.prettierrc

This config enforces consistent formatting: add semicolons, use trailing commas where valid, and prefer single quotes for strings.

{

  "semi": true,

  "trailingComma": "all",

  "singleQuote": true

}

Version Control: Git Essentials

Git is indispensable. You can use feature branches and pull requests for collaborative development, making it easier to work on large projects with coworkers. Consider using Husky for pre-commit hooks to enforce linting and testing.

Install Husky:

Install Husky to easily manage Git hooks, allowing you to automate tasks like linting and testing before commits.

npm install husky --save-dev

package.json (add script)

This package.json file sets up a Node.js project named my-mern-app, and configures a prepare script to install Git hooks using Husky (v7). It's ready for adding pre-commit automation, such as linting or testing.

{

  "name": "my-mern-app",

  "version": "1.0.0",

  "description": "",

  "main": "index.js",

  "scripts": {

    "prepare": "husky install"

  },

  "keywords": [],

  "author": "",

  "license": "ISC",

  "devDependencies": {

    "husky": "^7.0.0"

  }

}

Create a pre-commit hook

The below command sets up a pre-commit hook that automatically runs your tests and linter before each commit, ensuring code quality and preventing errors from entering your codebase.

npx husky add .husky/pre-commit "npm test && npm run lint"

Testing: Ensuring Robustness

Automated testing is vital. We'll cover unit, integration, and end-to-end testing in this guide.

Backend Testing (Node.js/Express.js)

You’ll use Jest for unit testing and Supertest for API integration tests.

Install them like this:

npm install --save-dev jest supertest

You’ll use Jest to write unit tests for your JavaScript code and Supertest to test HTTP requests against your Express.js API.

Example Test (server/tests/auth.test.js):

This test suite uses Supertest to simulate API calls for user registration and login, asserting that the responses have the expected status codes and properties.

const request = require('supertest');

const app = require('../app'); // Your Express app instance

describe('Auth API', () => {

  it('should register a new user', async () => {

    const res = await request(app)

      .post('/api/auth/register')

      .send({

        username: 'testuser',

        email: 'test@example.com',

        password: 'password123',

      });

    expect(res.statusCode).toEqual(201);

    expect(res.body).toHaveProperty('_id');

  });


  it('should login an existing user', async () => {

    const res = await request(app)

      .post('/api/auth/login')

      .send({

        email: 'test@example.com',

        password: 'password123',

      });

    expect(res.statusCode).toEqual(200);

    expect(res.headers['set-cookie']).toBeDefined();

  });

});

Frontend Testing (React Testing Library + Cypress)

You’ll use Jest and the React Testing Library for unit/integration tests, and Cypress for E2E tests.

You can install these like this:

npm install --save-dev @testing-library/react @testing-library/jest-dom jest cypress

React Testing Library will help you test your React components, and Cypress will provide comprehensive end-to-end testing of your frontend application.

Example Component Test (client/src/components/Button.test.js):

This unit test uses the React Testing Library to render a Button component and verifies that the specified text content is present in the rendered output.

import React from 'react';

import { render, screen } from '@testing-library/react';

import Button from './Button';


test('renders button with text', () => {

  render(<Button>Click MeButton>);

  const buttonElement = screen.getByText(/Click Me/i);

  expect(buttonElement).toBeInTheDocument();

});

The following Cypress test simulates a complete user authentication flow, from registration to login and logout, asserting expected URL changes and page content.

Example E2E Test (cypress/e2e/auth.cy.js)

describe('Authentication Flow', () => {

  it('should allow a user to register and login', () => {

    cy.visit('/register');

    cy.get('input[name="username"]').type('e2euser');

    cy.get('input[name="email"]').type('e2e@example.com');

    cy.get('input[name="password"]').type('password123');

    cy.get('button[type="submit"]').click();

    cy.url().should('include', '/dashboard');

    cy.contains('Welcome, e2euser');

    cy.get('button').contains('Logout').click();

    cy.url().should('include', '/login');

    cy.get('input[name="email"]').type('e2e@example.com');

    cy.get('input[name="password"]').type('password123');

    cy.get('button[type="submit"]').click();

    cy.url().should('include', '/dashboard');

  });

});

How to Build the Task Manager

We'll build a simple Task Manager with user authentication and CRUD operations for tasks so you can see how the whole thing comes together.

Backend Implementation (Node.js/Express.js)

Dependencies

Start by installing our core backend libraries: Express for routing, Mongoose for MongoDB interactions, dotenv for environment variables, bcrypt/jsonwebtoken/cookie-parser for secure authentication, and helmet for setting secure HTTP headers:

npm install express mongoose dotenv bcryptjs jsonwebtoken cookie-parser

server/app.js (Entry Point)

Next, we’ll set up the first or the main entry point for the backend. This is the main Express.js application file, which configures middleware, establishes a MongoDB connection, and sets up API routes for authentication and task management.

const express = require('express');

const mongoose = require('mongoose');

const dotenv = require('dotenv');

const cookieParser = require('cookie-parser');

const helmet = require('helmet');

const authRoutes = require('./routes/authRoutes');

const taskRoutes = require('./routes/taskRoutes');

const { notFound, errorHandler } = require('./middleware/errorMiddleware');

dotenv.config();


const app = express();

app.use(helmet());

app.use(express.json());

app.use(cookieParser());


mongoose.connect(process.env.MONGO_URI)

  .then(() => console.log('MongoDB connected!'))

  .catch(err => console.error('MongoDB connection error:', err));


app.use('/api/auth', authRoutes);

app.use('/api/tasks', taskRoutes);


app.get('/', (req, res) => {

  res.send('MERN Task Manager API is running!');

});


app.use(notFound);

app.use(errorHandler);


const PORT = process.env.PORT || 5000;

app.listen(PORT, () => {

  console.log(`Server running on port ${PORT}`);

});

server/.env

To avoid hardcoding secrets, we’ll add a .env file where we can securely store environment variables, such as our database URI and JWT secret. This file stores sensitive environment variables such as your MongoDB connection string, server port, and JWT secret, keeping them secure and separate from your codebase.

MONGO_URI=your_mongodb_connection_string_here

PORT=5000

JWT_SECRET=supersecretjwtkey

server/models/User.js

Now, let’s define our User model using MongoDB. This schema includes fields for username, email, and password, with pre-save hooks for password hashing and a method for password comparison.

const mongoose = require('mongoose');

const bcrypt = require('bcryptjs');


const UserSchema = new mongoose.Schema({

  username: {

    type: String,

    required: true,

    unique: true,

  },

  email: {

    type: String,

    required: true,

    unique: true,

  },

  password: {

    type: String,

    required: true,

  },

});

UserSchema.pre('save', async function (next) {

  if (!this.isModified('password')) {

    next();

  }

  const salt = await bcrypt.genSalt(10);

  this.password = await bcrypt.hash(this.password, salt);

});


UserSchema.methods.matchPassword = async function (enteredPassword) {

  return await bcrypt.compare(enteredPassword, this.password);

};


module.exports = mongoose.model('User', UserSchema);

server/models/Task.js

Next, we’ll create the Task model. This schema defines the Task model, which links each task to a user and includes fields for title, description, completion status, and creation timestamp.

const mongoose = require('mongoose');


const TaskSchema = new mongoose.Schema({

  user: {

    type: mongoose.Schema.Types.ObjectId,

    ref: 'User',

    required: true,

  },

  title: {

    type: String,

    required: true,

    trim: true,

  },

  description: {

    type: String,

    trim: true,

  },

  completed: {

    type: Boolean,

    default: false,

  },

  createdAt: {

    type: Date,

    default: Date.now,

  },

});


module.exports = mongoose.model('Task', TaskSchema);

server/controllers/authController.js

Let’s build out the authentication controller. This controller handles user authentication flows, including registration, login, logout, and fetching user profiles, using JWTs and secure HTTP-only cookies.

const User = require('../models/User');

const jwt = require('jsonwebtoken');

const generateToken = (id) => {

  return jwt.sign({ id }, process.env.JWT_SECRET, {

    expiresIn: '1h',

  });

};

exports.registerUser = async (req, res) => {

  const { username, email, password } = req.body;

  try {

    const userExists = await User.findOne({ email });

    if (userExists) return res.status(400).json({ message: 'User already exists' });

    const user = await User.create({ username, email, password });

    if (user) {

      const token = generateToken(user._id);

      res.cookie('token', token, { httpOnly: true, secure: process.env.NODE_ENV === 'production', maxAge: 3600000 });

      res.status(201).json({ id: user.id, username: user.username, email: user.email });

    } else {

      res.status(400).json({ message: 'Invalid user data' });

    }

  } catch (error) {

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

  }

};


exports.loginUser = async (req, res) => {

  const { email, password } = req.body;

  try {

    const user = await User.findOne({ email });

    if (user && (await user.matchPassword(password))) {

      const token = generateToken(user._id);

      res.cookie('token', token, { httpOnly: true, secure: process.env.NODE_ENV === 'production', maxAge: 3600000 });

      res.json({ id: user.id, username: user.username, email: user.email });

    } else {

      res.status(401).json({ message: 'Invalid email or password' });

    }

  } catch (error) {

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

  }

};


exports.logoutUser = (req, res) => {

  res.cookie('token', '', { httpOnly: true, expires: new Date(0) });

  res.status(200).json({ message: 'Logged out successfully' });

};


exports.getUserProfile = async (req, res) => {

  try {

    const user = await User.findById(req.user._id).select('-password');

    if (user) {

      res.json(user);

    } else {

      res.status(404).json({ message: 'User not found' });

    }

  } catch (error) {

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

  }

};

server/controllers/taskController.js

Now it’s time to implement the task controller. This controller provides the logic for fetching, creating, updating, and deleting tasks, ensuring that users can only interact with their tasks.

const Task = require('../models/Task');


exports.getTasks = async (req, res) => {

  try {

    const tasks = await Task.find({ user: req.user._id });

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

  } catch (error) {

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

  }

};


exports.createTask = async (req, res) => {

  const { title, description } = req.body;

  if (!title) return res.status(400).json({ message: 'Please add a title' });

  try {

    const task = await Task.create({ title, description, user: req.user._id });

    res.status(201).json(task);

  } catch (error) {

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

  }

};


exports.updateTask = async (req, res) => {

  try {

    const task = await Task.findById(req.params.id);

    if (!task) return res.status(404).json({ message: 'Task not found' });

    if (task.user.toString() !== req.user._id.toString()) return res.status(401).json({ message: 'Not authorized' });


    const updatedTask = await Task.findByIdAndUpdate(req.params.id, req.body, { new: true, runValidators: true });

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

  } catch (error) {

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

  }

};


exports.deleteTask = async (req, res) => {

  try {

    const task = await Task.findById(req.params.id);

    if (!task) return res.status(404).json({ message: 'Task not found' });

    if (task.user.toString() !== req.user._id.toString()) return res.status(401).json({ message: 'Not authorized' });


    await Task.deleteOne({ _id: req.params.id });

    res.status(200).json({ message: 'Task removed' });

  } catch (error) {

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

  }

};

server/middleware/authMiddleware.js

To protect private routes, we will create a middleware that verifies the JWT from the request's cookies, ensuring that only authenticated users can access specific endpoints.

const jwt = require('jsonwebtoken');

const User = require('../models/User');

exports.protect = async (req, res, next) => {

  let token;

  if (req.cookies.token) {

    try {

      token = req.cookies.token;

      const decoded = jwt.verify(token, process.env.JWT_SECRET);

      req.user = await User.findById(decoded.id).select('-password');

      next();

    } catch (error) {

      res.status(401).json({ message: 'Not authorized, token failed' });

    }

  } else {

    res.status(401).json({ message: 'Not authorized, no token' });

  }

};

server/middleware/errorMiddleware.js

To handle errors cleanly across our backend, we’ll add global error-handling middleware that can handle 404 Not Found errors and provide a centralized error-handling mechanism for consistent API error responses.

exports.notFound = (req, res, next) => {

  const error = new Error(`Not Found - ${req.originalUrl}`);

  res.status(404);

  next(error);

};


exports.errorHandler = (err, req, res, next) => {

  const statusCode = res.statusCode === 200 ? 500 : res.statusCode;

  res.status(statusCode);

  res.json({

    message: err.message,

    stack: process.env.NODE_ENV === 'production' ? null : err.stack,

  });

};

server/routes/authRoutes.js

Next, let’s define our authentication routes. These endpoints enable user authentication and map HTTP methods to their corresponding controller functions.

const express = require('express');

const { registerUser, loginUser, logoutUser, getUserProfile } = require('../controllers/authController');

const { protect } = require('../middleware/authMiddleware');


const router = express.Router();


router.post('/register', registerUser);

router.post('/login', loginUser);

router.get('/logout', logoutUser);

router.get('/profile', protect, getUserProfile);


module.exports = router;

server/routes/taskRoutes.js

Now we’ll add the routes for task operations. This file defines the API routes for task management, applying the protect middleware to secure all task-related operations.

const express = require('express');

const { getTasks, createTask, updateTask, deleteTask } = require('../controllers/taskController');

const { protect } = require('../middleware/authMiddleware');

const router = express.Router();

router.route('/').get(protect, getTasks).post(protect, createTask);

router.route('/:id').put(protect, updateTask).delete(protect, deleteTask);

module.exports = router;

Frontend Implementation (React)

Dependencies

Now, you’ll need to initialize a new React project and install your essential libraries: Axios for HTTP requests, React Router for navigation, and React Toastify for displaying notifications.

npm install axios react-router-dom react-toastify

client/src/index.js

Let’s start the frontend by setting up the entry point. Here we are rendering the main App component and wrapping it with AuthProvider to provide authentication context globally.

import React from 'react';

import ReactDOM from 'react-dom/client';

import './index.css';

import App from './App';

import { AuthProvider } from './context/AuthContext';


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

root.render(

  <React.StrictMode>

    <AuthProvider>

      <App />

    AuthProvider>

  React.StrictMode>

);

client/src/App.js

Next, we’ll define our main App component. This sets up the client-side routing for the application, and defines public and private routes, and includes a navigation bar and toast notification system.

import React from 'react';

import { BrowserRouter as Router, Routes, Route } from 'react-router-dom';

import { ToastContainer } from 'react-toastify';

import 'react-toastify/dist/ReactToastify.css';


import Navbar from './components/Navbar';

import Register from './pages/Register';

import Login from './pages/Login';

import Dashboard from './pages/Dashboard';

import PrivateRoute from './components/PrivateRoute';


function App() {

  return (

    <Router>

      <Navbar />

      <ToastContainer />

      <div className="container">

        <Routes>

          <Route path="/register" element={<Register />} />

          <Route path="/login" element={<Login />} />

          <Route path="/dashboard" element={<PrivateRoute />}>

            <Route index element={<Dashboard />} />

          Route>

          <Route path="/" element={<h1>Welcome to Task Manager!h1>} />

        Routes>

      div>

    Router>

  );

}

export default App;

client/src/context/AuthContext.js

We’ll create an authentication context that manages the global authentication state. It provides functions for user login, registration, and logout, and automatically loads user data on component mount.

import React, { createContext, useState, useEffect } from 'react';

import axios from 'axios';

const AuthContext = createContext();

export const AuthProvider = ({ children }) => {

  const [user, setUser] = useState(null);

  const [loading, setLoading] = useState(true);


  useEffect(() => {

    const loadUser = async () => {

      try {

        const res = await axios.get('/api/auth/profile');

        setUser(res.data);

      } catch (err) {

        setUser(null);

      } finally {

        setLoading(false);

      }

    };

    loadUser();

  }, []);


  const login = async (email, password) => {

    try {

      const res = await axios.post('/api/auth/login', { email, password });

      setUser(res.data);

      return true;

    } catch (err) {

      console.error(err.response.data.message);

      return false;

    }

  };


  const register = async (username, email, password) => {

    try {

      const res = await axios.post('/api/auth/register', { username, email, password });

      setUser(res.data);

      return true;

    } catch (err) {

      console.error(err.response.data.message);

      return false;

    }

  };


  const logout = async () => {

    try {

      await axios.get('/api/auth/logout');

      setUser(null);

    } catch (err) {

      console.error(err);

    }

  };


  return (

    <AuthContext.Provider value={{ user, loading, login, register, logout }}>

      {children}

    AuthContext.Provider>

  );

};


export default AuthContext;

client/src/components/Navbar.js

Here’s a dynamic navigation bar component that dynamically displays links based on the user's authentication status, showing either login/register options or a welcome message and logout button.

import React, { useContext } from 'react';

import { Link } from 'react-router-dom';

import AuthContext from '../context/AuthContext';


const Navbar = () => {

  const { user, logout } = useContext(AuthContext);


  return (

    <nav>

      <h1>Task Managerh1>

      <div>

        {user ? (

          <>

            <span>Welcome, {user.username}span>

            <button onClick={logout}>Logoutbutton>

            <Link to="/dashboard">DashboardLink>

          

        ) : (

          <>

            <Link to="/login">LoginLink>

            <Link to="/register">RegisterLink>

          

        )}

      

    

  );

};


export default Navbar;

client/src/components/PrivateRoute.js

To protect certain pages, we can create a Private Route component. This will be a guard for private routes, ensuring that only authenticated users can access them and redirecting unauthenticated users to the login page.

import React, { useContext } from 'react';

import { Navigate, Outlet } from 'react-router-dom';

import AuthContext from '../context/AuthContext';


const PrivateRoute = () => {

  const { user, loading } = useContext(AuthContext);


  if (loading) {

    return <div>Loading...div>; // Or a spinner

  }


  return user ? <Outlet /> : <Navigate to="/login" replace />;

};

export default PrivateRoute;

client/src/pages/Register.js

Now, let’s create the Register component, which provides a user registration form, handles input state and form submission, and displays success or error messages using toast notifications.

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

import { useNavigate } from 'react-router-dom';

import { toast } from 'react-toastify';

import AuthContext from '../context/AuthContext';


const Register = () => {

  const [username, setUsername] = useState('');

  const [email, setEmail] = useState('');

  const [password, setPassword] = useState('');

  const { register } = useContext(AuthContext);

  const navigate = useNavigate();


  const handleSubmit = async (e) => {

    e.preventDefault();

    const success = await register(username, email, password);

    if (success) {

      toast.success('Registration successful!');

      navigate('/dashboard');

    } else {

      toast.error('Registration failed. Please try again.');

    }

  };


  return (

    <div>

      <h2>Registerh2>

      <form onSubmit={handleSubmit}>

        <div>

          <label>Username:label>

          <input type="text" value={username} onChange={(e) => setUsername(e.target.value)} required />

        div>

        <div>

          <label>Email:label>

          <input type="email" value={email} onChange={(e) => setEmail(e.target.value)} required />

        div>

        <div>

          <label>Password:label>

          <input type="password" value={password} onChange={(e) => setPassword(e.target.value)} required />

        div>

        <button type="submit">Registerbutton>

      form>

    div>

  );

};


export default Register;

client/src/pages/Login.js

Now, for the login form, it works similarly to the register page but logs users into the system instead. This page manages input fields, handles form submissions, and provides feedback via toast notifications.

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

import { useNavigate } from 'react-router-dom';

import { toast } from 'react-toastify';

import AuthContext from '../context/AuthContext';


const Login = () => {

  const [email, setEmail] = useState('');

  const [password, setPassword] = useState('');

  const { login } = useContext(AuthContext);

  const navigate = useNavigate();


  const handleSubmit = async (e) => {

    e.preventDefault();

    const success = await login(email, password);

    if (success) {

      toast.success('Login successful!');

      navigate('/dashboard');

    } else {

      toast.error('Login failed. Invalid credentials.');

    }

  };


  return (

    <div>

      <h2>Loginh2>

      <form onSubmit={handleSubmit}>

        <div>

          <label>Email:label>

          <input type="email" value={email} onChange={(e) => setEmail(e.target.value)} required />

        div>

        <div>

          <label>Password:label>

          <input type="password" value={password} onChange={(e) => setPassword(e.target.value)} required />

        div>

        <button type="submit">Loginbutton>

      form>

    div>

  );

};


export default Login;

client/src/pages/Dashboard.js

Finally, we’ll build the Dashboard page. This dashboard component displays a user's tasks, allowing them to create new tasks, mark tasks as complete or incomplete, and delete tasks, with real-time updates.

import React, { useState, useEffect, useContext } from 'react';

import axios from 'axios';

import { toast } from 'react-toastify';

import AuthContext from '../context/AuthContext';


const Dashboard = () => {

  const { user } = useContext(AuthContext);

  const [tasks, setTasks] = useState([]);

  const [newTaskTitle, setNewTaskTitle] = useState('');

  const [newTaskDescription, setNewTaskDescription] = useState('');


  useEffect(() => {

    if (user) {

      fetchTasks();

    }

  }, [user]);


  const fetchTasks = async () => {

    try {

      const res = await axios.get('/api/tasks');

      setTasks(res.data);

    } catch (err) {

      toast.error('Failed to fetch tasks.');

      console.error(err);

    }

  };


  const handleCreateTask = async (e) => {

    e.preventDefault();

    try {

      await axios.post('/api/tasks', { title: newTaskTitle, description: newTaskDescription });

      setNewTaskTitle('');

      setNewTaskDescription('');

      toast.success('Task created successfully!');

      fetchTasks();

    } catch (err) {

      toast.error('Failed to create task.');

      console.error(err);

    }

  };


  const handleUpdateTask = async (id, completed) => {

    try {

      await axios.put(`/api/tasks/${id}`, { completed });

      toast.success('Task updated successfully!');

      fetchTasks();

    } catch (err) {

      toast.error('Failed to update task.');

      console.error(err);

    }

  };


  const handleDeleteTask = async (id) => {

    try {

      await axios.delete(`/api/tasks/${id}`);

      toast.success('Task deleted successfully!');

      fetchTasks();

    } catch (err) {

      toast.error('Failed to delete task.');

      console.error(err);

    }

  };


  return (

    <div>

      <h2>Welcome, {user ? user.username : 'Guest'}!h2>

      <h3>Your Tasksh3>

      <form onSubmit={handleCreateTask}>

        <input

          type="text"

          placeholder="New Task Title"

          value={newTaskTitle}

          onChange={(e) => setNewTaskTitle(e.target.value)}

          required

        />

        <input

          type="text"

          placeholder="Description (optional)"

          value={newTaskDescription}

          onChange={(e) => setNewTaskDescription(e.target.value)}

        />

        <button type="submit">Add Taskbutton>

      form>

      <ul>

        {tasks.map((task) => (

          <li key={task._id}>

            <span style={{ textDecoration: task.completed ? 'line-through' : 'none' }}>

              {task.title}: {task.description}

            span>

            <button onClick={() => handleUpdateTask(task._id, !task.completed)}>

              {task.completed ? 'Mark Incomplete' : 'Mark Complete'}

            button>

            <button onClick={() => handleDeleteTask(task._id)}>Deletebutton>

          li>

        ))}

      ul>

    div>

  );

};


export default Dashboard;

Deployment: From Localhost to Live

Deploying a MERN stack application involves deploying the backend API and the frontend React application separately.

Let’s talk about why we do it separately. As you have seen from above, in a MERN stack app, the frontend and backend are separate by design. React handles the UI, while Express and Node handle server logic and API calls. Because they serve different roles, you'll need to deploy them separately.

The backend runs on a Node.js compatible server, which connects to a database such as MongoDB Atlas. The frontend, once it is built, becomes static files that can be hosted from anywhere, from NGINX to hosting platforms like Netlify or Vercel.

This separation provides you with flexibility and improved scalability. Let’s walk through how to deploy each part.

Backend Deployment (Node.js/Express.js)

For backend deployment, platforms like Heroku, Render, or AWS EC2 are common choices. Here, I’ll outline a general approach for a cloud VM on AWS EC2

1. Prepare for Production

To start, set the environment to production and install only the dependencies your app needs to run, optimizing your application's performance. Skipping devDependencies helps reduce its footprint.

export NODE_ENV=production

npm install --production

2. Process Manager (PM2)

Next, we’ll set up a process manager to keep our backend server running reliably. PM2 is a popular tool that handles automatic restarts if your Node.js application crashes, manages multiple app instances, and also helps ensure high availability in production environments.

npm install -g pm2

pm2 start server/app.js --name mern-api

pm2 save

pm2 startup

3. NGINX as a Reverse Proxy

Now that our backend is running with PM2, we need a way to handle incoming web traffic. That’s where NGINX comes in. We'll install NGINX to serve as a high-performance reverse proxy directing incoming web traffic to your Node.js backend and serving static frontend files.

sudo apt update

sudo apt install nginx

Once NGINX is installed, it’s time to configure it (/etc/nginx/sites-available/default or a new config file). We’ll set it up to forward API requests to the backend and serve the React app, acting as the single entry point. You can update the default configuration file or create a new one:

# /etc/nginx/sites-available/default
server {

    listen 80;

    server_name your_domain_or_ip;


    location /api/ {

        proxy_pass http://localhost:5000;

        proxy_http_version 1.1;

        proxy_set_header Upgrade $http_upgrade;

        proxy_set_header Connection 'upgrade';

        proxy_set_header Host $host;

        proxy_cache_bypass $http_upgrade;

    }


    location / {

        root /var/www/my-mern-app/client/build; # Path to your React build folder

        try_files $uri /index.html;

    }

}

With the NGINX configuration created, we’ll enable it and restart the service to apply the changes, making your application go live:

sudo ln -s /etc/nginx/sites-available/default /etc/nginx/sites-enabled/

sudo systemctl restart nginx

4. HTTPS with Certbot (Let's Encrypt)

To secure your app with HTTPS, we can install Certbot and use it to automatically obtain and configure a free SSL/TLS certificate from Let’s Encrypt, enabling secure HTTPS connections for your domain.

sudo snap install --classic certbot

sudo certbot --nginx -d your_domain_or_ip

Frontend Deployment (React)

With the backend deployed, let’s move to the frontend. For the React frontend, we’ll build the application and serve the static files via NGINX (as shown above) or a dedicated static site hosted on platforms like Netlify, Vercel, or AWS S3 + CloudFront.

Build the React App

This command compiles and optimizes your React application into a build folder containing static assets, ready for efficient deployment to any web server or static hosting service.

cd client

npm run build

Database Deployment (MongoDB Atlas)

For production, we’ll use a managed MongoDB service like MongoDB Atlas. It handles replication, sharding, and backups, simplifying database management significantly.

Create a Cluster on MongoDB Atlas

Sign up/Log in to MongoDB Atlas.
Create a new cluster (choose a cloud provider and region).
Set up a database user with appropriate permissions.
Configure network access (allow connections from your server's IP address).
Get your connection string and update MONGO_URI in your server/.env file.

1. `.env` Configuration Example

After creating the cluster and user in MongoDB Atlas, you’ll receive a connection string. You need to update your .env file with it

# server/.env
MONGO_URI=mongodb+srv://yourUser:yourPassword@cluster0.mongodb.net/yourDBName
JWT_SECRET=your_secret_jwt_key
NODE_ENV=production

2. Connect to MongoDB in `app.js`

Next, in the server/app.js file, make sure you're using the connection string from the environment variable:

const mongoose = require('mongoose');
const dotenv = require('dotenv');
dotenv.config();

mongoose.connect(process.env.MONGO_URI)
  .then(() => console.log('MongoDB connected!'))
  .catch((err) => console.error('Connection error:', err));

Other Deployment Options

While this article drives you through manual deployment with EC2 and NGINX, other platforms can simplify the process:

Render, Railway, and Heroku offer easy full-stack deployment with GitHub integration.
Vercel and Netlify are ideal for hosting the React frontend.
You may consider using Docker to maintain consistent environments across development and production.
For CI/CD, Linting, Testing, & Deployment can be automated on every push using tools like GitHub Actions

There is no right or wrong choice here. Select the setup that best suits your project’s scale, team experience, and desired level of control.

Security Best Practices: Fortifying Your Application

Security is paramount. You can implement these best practices to protect your MERN application.

Setup Input Validation and Sanitization

Always validate and sanitize input on the server side. You can use libraries like Joi or Zod to make this process easier.

Example with Joi:

To validate and sanitize incoming data on the server, we will utilize Joi, a powerful library for defining schemas and enforcing input rules.

npm install joi

Now that we’ve installed Joi, we will use it to define strict validation rules for user registration and login inputs. This ensures data quality and prevents common injection attacks.

// server/validators/authValidator.js

const Joi = require('joi');


const registerSchema = Joi.object({

  username: Joi.string().min(3).max(30).required(),

  email: Joi.string().email().required(),

  password: Joi.string().min(6).required(),

});


const loginSchema = Joi.object({

  email: Joi.string().email().required(),

  password: Joi.string().required(),

});


module.exports = { registerSchema, loginSchema };

Next, we’ll integrate these schemas directly into our authentication controller to automatically validate incoming request bodies against predefined schemas.

// server/controllers/authController.js (snippet)

const { registerSchema, loginSchema } = require('../validators/authValidator');


exports.registerUser = async (req, res) => {

  const { error } = registerSchema.validate(req.body);

  if (error) return res.status(400).json({ message: error.details[0].message });

  // ... rest of the registration logic

};


exports.loginUser = async (req, res) => {

  const { error } = loginSchema.validate(req.body);

  if (error) return res.status(400).json({ message: error.details[0].message });

  // ... rest of the login logic

};

Add Authentication and Authorization

You can use JWTs for authentication and implement middleware for protected routes.

JWT Implementation (covered in authController.js and authMiddleware.js above)

Key aspects:

HttpOnly Cookies: Store JWTs in HttpOnly cookies to prevent client-side JavaScript access, mitigating XSS attacks.
Secure Flag: Use secure: true in production to ensure cookies are only sent over HTTPS.

These practices ensure that authentication tokens are securely transmitted and stored, protecting against common web vulnerabilities like Cross-Site Scripting (XSS).

Implement Rate Limiting

To protect our API from abuse and malicious intent, we will implement basic rate limiting. This helps protect against brute-force login attempts and DDoS attacks.

Installation

We will install express-rate-limit package for it

npm install express-rate-limit

server/app.js (snippet)

Once it is installed, let’s configure the rate limiter and apply it to all incoming requests. This ensures that no single IP can overwhelm your server with repeated calls. The following middleware limits each IP address to 200 requests within a 15-minute window.

const rateLimit = require('express-rate-limit');

const limiter = rateLimit({

  windowMs: 15 * 60 * 1000, // 15 minutes

  max: 200, // Limit each IP to 200 requests per windowMs

  message: 'Too many requests from this IP, please try again after 15 minutes',

});

app.use(limiter); // Apply to all requests

Next, we move our focus to enable secure communication between your frontend and backend. By default, all browsers block cross-origin requests, so we need to configure CORS (Cross-Origin Resource Sharing) to permit the React app to communicate with the Express API.

Installation

npm install cors

server/app.js (snippet)

Once installed, we can configure CORS for our Express application, specifying allowed origins and enabling credential sharing for secure cross-origin requests. Remember to replace the origin with your actual production URL when deploying.

const cors = require('cors');

app.use(cors({

  origin: 'http://localhost:3000', // Replace with your frontend URL in production

  credentials: true,

}));

Use Environment Variables

To keep sensitive information secure and out of your codebase, we will use environment variables. This allows us to efficiently manage secrets, such as database connection strings and JWT keys, without hardcoding them or including them in the source code.

Create a .env file in your server/ directory:

.env (example)

This .env file stores sensitive configuration details like database connection strings and API keys

MONGO_URI=your_mongodb_connection_string

JWT_SECRET=your_super_secret_jwt_key

NODE_ENV=production

Monitoring and Logging with Winston and Morgan

Once the application is live, it's critical to monitor the behavior and catch issues promptly. Monitoring and logging help you measure performance, find bugs, and keep a log of all server activity.

We’ll use Morgan for logging HTTP requests and Winston for more general-purpose application logging.

Installation

We will install Morgan for logging HTTP requests and Winston for comprehensive and customizable application logging.

npm install morgan winston

server/config/logger.js

Next, let’s configure Winston to handle our application logs. This will output logs to the console by default, with options to enable file-based logging for errors and general information.

const winston = require('winston');

const logger = winston.createLogger({

  level: 'info',

  format: winston.format.combine(

    winston.format.timestamp(),

    winston.format.json()

  ),

  transports: [

    new winston.transports.Console(),

    // new winston.transports.File({ filename: 'error.log', level: 'error' }),

    // new winston.transports.File({ filename: 'combined.log', level: 'info' }),

  ],

});

module.exports = logger;

server/app.js (snippet)

With Winston and Morgan set up, now let’s integrate them into our app.js file. We’ll use Morgan for request logging during development and replace standard console.log calls with Winston logs for structured and configurable application logging.

const morgan = require('morgan');

const logger = require('./config/logger');

if (process.env.NODE_ENV === 'development') {

  app.use(morgan('dev'));

}

// Replace console.log with logger.info for database connection

mongoose.connect(process.env.MONGO_URI)

  .then(() => logger.info('MongoDB connected!'))

  .catch(err => logger.error('MongoDB connection error:', err));


// Replace console.log in app.listen

app.listen(PORT, () => {

  logger.info(`Server running on port ${PORT}`);

});

Frontend Error Monitoring (Sentry)

To monitor errors in the frontend, we’ll integrate Sentry. It’s a fantastic tool for tracking exceptions and performance issues in real time. It helps us capture and report client-side errors.

Installation

npm install @sentry/react @sentry/tracing

client/src/index.js (snippet)

After installation, let’s initialize Sentry in the React application so that it can automatically capture errors and performance data. We’ll add this to our index.js file.

import * as Sentry from '@sentry/react';

import { BrowserTracing } from '@sentry/tracing';


Sentry.init({

  dsn: "YOUR_SENTRY_DSN", // Replace with your Sentry DSN

  integrations: [new BrowserTracing()],

  tracesSampleRate: 1.0,

  environment: process.env.NODE_ENV,

});

And that’s it! Congratulations on building and deploying a full-stack MERN app.

Conclusion

This article provided a code-first walkthrough of building, securing, and deploying a MERN stack application. By focusing on practical code examples and essential configurations, you now have a solid foundation for your MERN projects.

Remember, continuous learning and adaptation are key in the ever-evolving world of web development. Happy coding!

How to Build a Replit Clone with Socket.io, Monaco Editor, and Copilotkit

Prankur Pandey — Thu, 20 Feb 2025 23:16:04 +0000

I’ve been coding for about a decade now. And over the years, I’ve tried my fair share of development tools—especially IDEs like Sublime Text, Atom, and even NetBeans back in my college days. But when VS Code came along, it completely changed the game for me. It’s lightweight, fast, and packed with features that just make life easier as a developer. It quickly became my favourite tool.

With all the recent advancements in AI, I wanted to build something that’s not just fun but also a meaningful learning experience. That’s how this project was born—a simple Replit-inspired clone for the web. It combines AI to generate code, lets you run React files, and displays the output seamlessly, just like Replit. On top of that, you can edit files and save your work in real-time, so nothing ever gets lost.

Prerequisites & Tools

In this tutorial, we’ll build an AI-powered Replit clone—a web-based IDE. This IDE will enable you to generate React code files, edit them in a VSCode-like environment, preview the final output, and save the code in real time. It will also support CRUD operations on the generated files.

For this project, I’ll leverage some tools I’ve used in the past, including those from my SQL Query Data Extractor project. Below are the tools and technologies we’ll use:

Database

The database is the backbone of any application—it stores data and serves it as needed. For this project, I’ll use my all-time favourite, MongoDB Atlas.

I chose MongoDB Atlas because it integrates seamlessly with Next.js, and since it’s a cloud-based database, I don’t need to host it manually—making it a plug-and-play solution. Performing CRUD operations with MongoDB Atlas is straightforward and efficient.

Code Editor

The code editor is the core of this project, as it powers the IDE experience. For this, I’ll use the legendary Monaco Editor, the same editor that drives VSCode. Monaco Editor handles files effortlessly and supports a wide range of file types. In this project, it will allow users to view and edit code files.

Code Preview

Once we generate and edit code in the Monaco Editor, we’ll need a way to preview its output. For this, I’ll use CodeSandbox’s Sandpack, a free and powerful tool for live code previews.

Sandpack supports various frameworks and file types, whether you’re working with static HTML/CSS files or frameworks like React. It displays files and their real-time output seamlessly.

AI Agent

The AI Agent will be responsible for generating code using Natural Language Processing (NLP). Acting as a bridge between your ideas and the code, it will take user prompts and translate them into functional code files.

For this, I’ll use CopilotKit, my favourite free and open-source tool for AI-powered code generation. CopilotKit will take your ideas and create the corresponding code files based on your input.

AI Model

The AI Agent relies on an underlying AI model to process user inputs and generate code. For this project, I’ll use GroqAI, a flexible and reliable platform that supports various popular AI models. GroqAI’s versatility makes it perfect for this project’s requirements.

Next.js

To build a robust web application that combines both frontend and backend functionalities, I’ll use Next.js. It’s an excellent framework for creating scalable applications, offering server-side rendering and other powerful features that are ideal for this project.

Deployment

For deployment, you can choose any service. I prefer Vercel, as it integrates seamlessly with Next.js and is free for hobby projects.

By combining these tools, you’ll build a powerful, user-friendly application that effortlessly produces the code and provides a live preview like Replit does.

What We’ll Do Here

In this tutorial, you’ll follow these steps to build our app:

Step 1 – Set Up the Database:

Set up a database either locally or on the cloud. For seamless integration, use an online database tool that supports data access and extraction via REST APIs.

Step 2 – Obtain Cloud API Keys:

Retrieve the necessary API keys for your AI model to enable smooth and secure integration.

Step 3 – Build the Web Application:

Develop a web application and configure the backend to integrate CopilotKit. Ensure it’s properly set up for efficient functionality.

Step 4 – Train CopilotKit with Your Database:

Provide your database data to CopilotKit so it can understand and utilize the information for natural language processing.

Step 5 – Integrate the CopilotKit Chat Interface:

Embed the CopilotKit chat interface into your application and configure it to work seamlessly with your app’s workflow.

Step 6 – Test Locally:

Run the application on your local machine, thoroughly testing each feature to identify and resolve any issues.

Step 7 – Deploy the Application:

Once testing is complete and the app is working as expected, deploy it to a hosting platform for public use.

How Does the App Work?

This project is a fun experiment and a step toward my long-term goal of building something around code editors, particularly inspired by VSCode.

The real magic happens with CopilotKit. As soon as you input an idea into CopilotKit, it uses predefined system prompts that adapt to your project requirements. These prompts allow CopilotKit to interpret plain English instructions and transform them into meaningful outputs. In this tutorial, I’ll show you how to configure these system prompts effectively to maximize results.

For example, if you enter the idea “build a simple React app”, CopilotKit passes that idea to the integrated AI model. The AI model, working in coordination with CopilotKit’s system prompts, generates the necessary code files based on your input.

The generated files are then displayed in the File Explorer on the left side of the screen. You can easily browse through the files created by CopilotKit.

To preview the code, simply click on a file like App.js. The file’s code will load into the Monaco Editor on the left, while the Sandpack preview on the right will render a real-time output of the file.

You can now experiment with the files—tweak the code, change colours, fonts, or text, and even write your own logic, just like working with regular HTML, CSS, or React files. Any changes you make will be saved in real time to the database. So even if you accidentally close the project, your progress will be intact. Simply refresh the page, and your code will be right where you left it.

How to Set Up Your Tools

Now we’ll go through everything you need to set up the project.

Install Next.js and dependencies:

First, you’ll need to create a Next.js app. Go to the terminal and run the following command:

npx create-next-app@latest my-next-app

Replace my-next-app with your desired project name and use TypeScript.

Navigate to the project folder:

cd my-next-app

Start the development server:

npm run dev

Open your browser and navigate to http://localhost:3000 to see your Next.js app in action.

Install CopilotKit and dependencies

Navigate to the project’s root folder in the terminal and run the following command. This will install all the necessary dependencies for CopilotKit along with other essential packages, such as dotenv, groq-sdk, sandpack, Monaco Editor, Lucide React, Socket and Mongoose.

npm install @copilotkit/react-ui @copilotkit/react-core
npm install dotenv
npm install groq-sdk
npm install @codesandbox/sandpack-react
npm install @monaco-editor/react
npm install lucide-react
npm install mongoose
npm install socket.io
npm install socket.io-client

CopilotKit: This dependency handles all operations and configurations related to CopilotKit.
Dotenv: Used for managing environment variables, and keeping sensitive keys secure within the project.
GroqSDK: Facilitates access to various LLM models through a single API key.
CodeSandbox Sandpack (React): Provides the ability to display real-time previews of the code.
Monaco Editor: Powers the VSCode-like environment, enabling real-time code editing.
Lucide React: An icon library used to display icons for files and folders.
Mongoose: Manages MongoDB schemas for storing and retrieving data from the database.
socket.io: A very powerful tool for real-time data syncing between client and server.
socket.io client: Extra socket.io client package for data communication.

Set Up the LLM for Action:

This step is crucial for the project, as it involves setting up the LLM (Large Language Model) to convert natural language (plain English) queries into a React framework working code.

There are many LLMs available, each with its unique strengths. Some are free, while others are paid, making the selection process for this project a bit challenging.

After thorough experimentation, I chose the Groq Adapter because:

It integrates multiple LLMs into a single platform.
It offers access via a unified API key.
It’s fully compatible with CopilotKit.

How to Set Up Groq Cloud

To get started with Groq Cloud, visit its website and either log in if you already have an account or create a new account if you’re new. Once logged in, navigate to the Groq Dashboard.

This is the homepage of Groq cloud:

Once logged in, a new page will open that’ll look like this:

As you can see, the sidebar has an API Keys link. Click on it, and it will open a new page as shown in the image below. You can also select any LLM of your choice which is given at the top right before the view code option.

Here, click on the Create API Key button it will open a pop up like you see below. Just enter the name of your API key and click on Submit to create a new API key for you. Then copy this API key and paste it inside your .env file.

To enable seamless access to various LLMs on Groq Cloud, generate an API key by going to the Groq API Keys section. Create a new API key specifically for the LLM, ensuring that it is properly configured.

With the LLM set-up and all components ready, you are now prepared to build the project.

How to setup the database

Step 1: Create a MongoDB Atlas Account

Go to the MongoDB Atlas website.
Click on "Try Free" or "Sign Up".
Fill in your details (name, email, password) to create an account.
Verify your email address by clicking the link sent to your inbox.

Step 2: Create a New Project
After logging in, you will be directed to the MongoDB Atlas dashboard.
Click on the "New Project" button. This will take you to the Create a Project page.
Fill in the Project name and click on the next button, and it will open a new page to show the project owner's information.
Now click on the Create Project Button. This will take you to the main dashboard of the project where you will get the option to create the database.
Now Click on the Create Button to open a new page with details of deploying your cluster.
Choose a cloud provider (AWS, Google Cloud, or Azure) and a region closest to your location.
Select the "Free Tier" (free forever, but with limited resources) or a paid tier for larger projects.
Give your cluster a name (for example, MyCluster).
Click "Create Deployment". It will take a few minutes for the cluster to be provisioned.
Then It will ask you to connect your cluster to the database through a service. You should see your username and password – keep this somewhere.
Here, you will have to make yourself a database user, so click on the Create Database user button.
It will take a few seconds to complete this process. Once it’s done, close the pop-up and return back to the dashboard.
On the dashboard page you can see Get Connection String button. Go on and click on it.
It will open a new popup containing your MongoDB atlas URI. Simply copy the string, put it into your .env file and use the password you created in step 14.

Example use case :

//.env file
MONGODB_URI='YOUR MONGODB URL'

Structure and Features of the App

The focus of this project is on simplicity and functionality, to replicate Replit's core features like code editing and real-time previews. The idea is to create a straightforward web application that lets you:

Host three essential components: a File Explorer, the Monaco Editor, and a Sandbox.
Open files generated by CopilotKit in the Monaco Editor and perform CRUD operations on them.
See the real-time output of your code as you work.
Chat with the CopilotKit chatbot, which will be fully integrated into the front end.

The plan is to keep the implementation clean and practical while delivering a smooth coding experience.

Webpage Structure

Since we’ve already set up the Next.js app, the next step is to create a minimalistic webpage with the following components:

File Explorer: Displays the files generated by CopilotKit.
Monaco Editor: A versatile code editor that handles various file types and displays the content.
Sandbox: Shows the real-time output of the code.
CopilotKit Chatbot: Generates code files based on natural language prompts.

Key Features

Error Handling: Any failures, such as API or database issues, will be highlighted with red text for immediate visibility.
Data Presentation: Data is presented in two parts: first in the File Explorer for code files, and second in the Monaco Editor for viewing the content of those files.
CopilotKit Chatbot Integration: The chatbot will allow natural language interactions with the database. The blue-coloured ball on the page represents the CopilotKit chatbot, which serves as the key interface for interacting with the database.
- Users can ask questions about the database using natural language.
- The chatbot processes these queries, converts them into SQL, and fetches the results seamlessly.

The front end will look something like this: https://replit-mongodb.vercel.app/

How to Build the Back End

Before we start building the back end, you’ll need to put all important credentials into your .env file, which should look like this:

NEXT_PUBLIC_GROQ_CLOUD_API_KEY=<your-key-here>
MONGODB_URI=<your-mongodb-url>

These are environment variables used to configure sensitive or environment-specific settings in an application:

NEXT_PUBLIC_GROQ_CLOUD_API_KEY:
- This is a public API key for accessing the Groq Cloud API.
- It is prefixed with NEXT_PUBLIC_, which means it is exposed to the client-side code in a Next.js application.
- Replace with the actual API key provided by Groq Cloud.
MONGODB_URI:
- This is the connection string for a MongoDB database.
- It includes the database URL, credentials, and other connection details.
- Replace with the actual MongoDB connection string.

How to Configure the CopilotKit Back End

Open your Next.js app in any code editor—I prefer VSCode—and go to the root folder, which looks like this:

Inside the app folder, make a new folder called api. Inside the API folder, make another folder called copilotkit. Then in there, make a new file called route.js and paste this code inside the file:

import {
  CopilotRuntime,
  GroqAdapter,
  copilotRuntimeNextJSAppRouterEndpoint,
} from "@copilotkit/runtime";

import Groq from "groq-sdk";

const groq = new Groq({ apiKey: process.env.NEXT_PUBLIC_GROQ_CLOUD_API_KEY });

const copilotKit = new CopilotRuntime({
  async onResponse({ message, context }) {
    try {
      // Extract any file operations from the message and process them
      const fileBlocks = message.content.split("---");
      if (fileBlocks.length > 0) {
        // Format the response to use processFiles action
        return {
          content: `@processFiles(response: \\`${message.content}\\`)`,
        };
      }
      return message;
    } catch (error) {
      console.error("Error in onResponse:", error);
      return message;
    }
  },
});

const serviceAdapter = new GroqAdapter({
  groq,
  model: "llama-3.3-70b-versatile",
  systemPrompt: `You are an AI-powered code generator integrated into a web-based IDE. Your task is to generate project files and code based on user commands.

When generating files, use this exact format:

FILE: filename.ext
CODE:
[code content here]

For multiple files, separate them with "---".

Example response:
I'll create a React component:

FILE: Button.jsx
CODE:
import React from 'react';

const Button = () => {
  return (
    
  );
};

export default Button;

Important rules:
- Always include both FILE: and CODE: markers
- Use appropriate file extensions
- Generate complete, working code
- Maintain proper indentation
- Explain what you're creating before showing the files
- Make sure code is syntactically correct`,
});

export const POST = async (req) => {
  const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
    runtime: copilotKit,
    serviceAdapter,
    endpoint: "/api/copilotkit",
  });

  return handleRequest(req);
};

Here’s a detailed explanation of each part:

This code defines a CopilotKit Runtime integration with Next.js, designed to process requests for generating and managing code files in a web-based IDE environment. It connects to the Groq cloud service for additional functionalities and processes file-based outputs from AI-generated responses.

This code sets up a CopilotRuntime integration with Groq's AI model to generate and process code files in response to user requests. Here's a breakdown:

Key Components:

Groq Initialization:
- The Groq SDK is initialized using the NEXT_PUBLIC_GROQ_CLOUD_API_KEY environment variable.
- The model used is llama-3.3-70b-versatile.
CopilotRuntime:
- A CopilotRuntime instance is created with a custom onResponse handler.
- The onResponse function processes the AI's response:
  - Extracts file blocks (separated by ---) from the message.
  - Formats the response to trigger a processFiles action if file blocks are detected.
GroqAdapter:
- A GroqAdapter is configured to interact with the Groq API.
- It includes a system prompt that instructs the AI to generate code files in a specific format:
  - Files are marked with FILE: and CODE:.
  - Multiple files are separated by ---.
  - The AI is instructed to generate complete, syntactically correct code with proper explanations.
API Endpoint:
- A POST the endpoint is exposed using Next.js App Router.
- It uses copilotRuntimeNextJSAppRouterEndpoint to handle incoming requests, passing them to the CopilotRuntime and GroqAdapter.

Example Usage

Request

A POST request to /api/copilotkit might look like this:

  curl -X POST http://localhost:3000/api/copilotkit \
  -H "Content-Type: application/json" \
  -d '{"command": "Create a React component for a button"}'

AI Response (Processed by onResponse)

AI might return this response:

  FILE: Button.jsx
  CODE:
  import React from 'react';

  const Button = () => {
    return ;
  };

  export default Button;

Response to Client

The API wraps the response into the formatted structure:

  {
    "content": "@processFiles(response: `FILE: Button.jsx\nCODE:\nimport React from 'react';\n\nconst Button = () => {\n  return ;\n};\n\nexport default Button;`)"
  }

Key Features

AI-Powered Code Generation with copilotkit popup:
- The system generates complete project files based on user instructions.
- Ensures proper formatting (for example, FILE: and CODE: markers).
File Handling:
- Splits multi-file responses into manageable blocks using ---.
- Supports actions like @processFiles for integration with the IDE.
Scalable API:
- Modular design with CopilotRuntime and GroqAdapter allows easy extension and customization.
Error Handling:
- Logs errors without interrupting the workflow.
- Defaults to returning the unprocessed message on failure.

Making Routes for CRUD Operation

So far, we've covered how to integrate CopilotKit into the backend. Now, we need to handle file operations, so we'll create another route to manage files with the database.

To develop the backend for file handling, I'll create a new folder inside the API folder and name it files. Inside the files folder, I’ll create a simple route.js file. Here’s the code I’ll be using inside the file:

app/api/files/route.tsx


  import { NextResponse } from "next/server";
  import mongoose from "mongoose";
  import { connectDB, File } from "@/app/lib/mongodb";

  // Type for the request body
  interface FileRequestBody {
    id?: string;
    name?: string;
    content?: string;
  }interface FileCreateRequest {
    name: string;
    content: string;
  }

  interface FileUpdateRequest {
    id: string;
    name?: string;
    content?: string;
  }

  // Fetch all files (GET /api/files)
  export async function GET(): Promise<Response> {
  try {
      await connectDB(); // Ensure DB connection
      const files = await File.find({});
      return NextResponse.json(files, { status: 200 });
    } catch (error) {
      return NextResponse.json(
        { error: "Failed to fetch files" },
        { status: 500 }
      );
    }
  }

  // Create a new file (POST /api/files)
  export async function POST(req: Request): Promise<Response> {
  try {
      await connectDB(); // Ensure DB connection is successful
      // Parse the request body
      const { name, content }: FileRequestBody = await req.json();
      if (!name || !content) {
        throw new Error("Missing required fields: name or content");
      }

      // Log the incoming data for debugging
      console.log("Creating file with data:", { name, content });

      // Create a new file in the database
      const newFile = new File({ name, content });
      await newFile.save();

      // Return the newly created file
      return NextResponse.json(newFile, { status: 201 });
    } catch (error: any) {
      // Log the error for debugging
      console.error("Error creating file:", error);

      return NextResponse.json(
        { error: "Failed to create file", message: error.message },
        { status: 400 }
      );
    }
  }

  // Update file content (PUT /api/files)
  export async function PUT(req: Request): Promise<Response> {
  try {
      await connectDB(); // Ensure DB connection
      const { id, name, content }: FileRequestBody = await req.json();

      // Validate ID format
      if (!id || !mongoose.Types.ObjectId.isValid(id)) {
        return NextResponse.json({ error: "Invalid file ID" }, { status: 400 });
      }

      // Update file name or content if provided
      const updatedFile = await File.findByIdAndUpdate(
        id,
        { ...(name && { name }), ...(content && { content }) },
        { new: true }
      );

      if (!updatedFile) {
        return NextResponse.json({ error: "File not found" }, { status: 404 });
      }

      return NextResponse.json(updatedFile, { status: 200 });
    } catch (error: any) {
      return NextResponse.json(
        { error: "Failed to update file" },
        { status: 400 }
      );
    }
  }

  // Delete a file (DELETE /api/files)
  export async function DELETE(req: Request): Promise<Response> {
  try {
      await connectDB(); // Ensure DB connection
      const { id }: FileRequestBody = await req.json();

      // Validate ID format
      if (!id || !mongoose.Types.ObjectId.isValid(id)) {
        return NextResponse.json({ error: "Invalid file ID" }, { status: 400 });
      }

      await File.findByIdAndDelete(id);
      return NextResponse.json(
        { message: "File deleted successfully" },
        { status: 200 }
      );
    } catch (error: any) {
      return NextResponse.json(
        { error: "Failed to delete file" },
        { status: 400 }
      );
    }
  }

Code explanation :

This code defines API routes for handling CRUD operations (Create, Read, Update, Delete) on a MongoDB collection called File in a Next.js application. Each route is connected to MongoDB using Mongoose and we used NextResponse to format the responses.

Code Breakdown

1. Imports

import { NextResponse } from "next/server";
import mongoose from "mongoose";
import connectDB from "@/app/lib/mongodb"; //we made this file
import File from "@/app/lib/models/File"; //we made this file

NextResponse: Used for creating HTTP responses in Next.js API routes.
connectDB: Connects to the MongoDB database.
File: A Mongoose model representing the File collection.

2. Fetch All Files (GET)

export async function GET() {
  await connectDB(); // Ensure DB connection
  try {
    const files = await File.find({}); // Fetch all files
    return NextResponse.json(files, { status: 200 }); // Return files in JSON format
  } catch (error) {
    return NextResponse.json(
      { error: "Failed to fetch files" },
      { status: 500 }
    );
  }
}

Purpose: Retrieves all documents in the File collection.
Flow:
1. Connects to MongoDB.
2. Uses File.find({}) to fetch all files.
3. Returns the files with a 200 status or an error with a 500 status.

3. Create a New File (POST)

export async function POST(req) {
  await connectDB(); // Ensure DB connection

  try {
    const { name, content } = await req.json(); // Parse the request body
    if (!name || !content) {
      throw new Error("Missing required fields: name or content");
    }

    const newFile = new File({ name, content }); // Create new file
    await newFile.save(); // Save to MongoDB

    return NextResponse.json(newFile, { status: 201 }); // Return the new file
  } catch (error) {
    return NextResponse.json(
      { error: "Failed to create file", message: error.message },
      { status: 400 }
    );
  }
}

Purpose: Creates a new document in the File collection.
Flow:
1. Parses the name and content fields from the request body.
2. Validates the required fields.
3. Creates and save the file in MongoDB.
4. Returns the new file with a 201 status or an error with a 400 status.

4. Update a File (PUT)

export async function PUT(req) {
  await connectDB(); // Ensure DB connection
  try {
    const { id, name, content } = await req.json();

    if (!mongoose.Types.ObjectId.isValid(id)) {
      return NextResponse.json({ error: "Invalid file ID" }, { status: 400 });
    }

    const updatedFile = await File.findByIdAndUpdate(
      id,
      { ...(name && { name }), ...(content && { content }) },
      { new: true }
    );

    if (!updatedFile) {
      return NextResponse.json({ error: "File not found" }, { status: 404 });
    }

    return NextResponse.json(updatedFile, { status: 200 });
  } catch (error) {
    return NextResponse.json(
      { error: "Failed to update file" },
      { status: 400 }
    );
  }
}

Purpose: Updates an existing document in the File collection.
Flow:
1. Parses the id, name, and content from the request body.
2. Validates the id using Mongoose's ObjectId.
3. Updates the document using File.findByIdAndUpdate() (updates only provided fields).
4. Returns the updated document with a 200 status, or an error with 400 or 404.

5. Delete a File (DELETE)

export async function DELETE(req) {
  await connectDB(); // Ensure DB connection
  try {
    const { id } = await req.json();

    if (!mongoose.Types.ObjectId.isValid(id)) {
      return NextResponse.json({ error: "Invalid file ID" }, { status: 400 });
    }

    await File.findByIdAndDelete(id); // Delete the document
    return NextResponse.json(
      { message: "File deleted successfully" },
      { status: 200 }
    );
  } catch (error) {
    return NextResponse.json(
      { error: "Failed to delete file" },
      { status: 400 }
    );
  }
}

Purpose: Deletes a document from the File collection.
Flow:
1. Parses the id from the request body.
2. Validates the id format.
3. Uses File.findByIdAndDelete() to remove the document.
4. Returns a success message with a 200 status or an error with 400.

Example API Requests: How to test API in local

GET All Files

 curl -X GET http://localhost:3000/api/files

Create a File (POST)

 curl -X POST http://localhost:3000/api/files \
 -H "Content-Type: application/json" \
 -d '{"name": "example.txt", "content": "This is a test file"}'

Update a File (PUT)

 curl -X PUT http://localhost:3000/api/files \
 -H "Content-Type: application/json" \
 -d '{"id": "64ffab67c728f51234567890", "name": "updated.txt", "content": "Updated content"}'

Delete a File (DELETE)

 curl -X DELETE http://localhost:3000/api/files \
 -H "Content-Type: application/json" \
 -d '{"id": "64ffab67c728f51234567890"}'

Creating MongoDB Schemas

Now, create a lib folder inside the app folder. This lib folder will handle essential database tasks, such as database schema and connectivity. Inside the lib folder, create another folder named models. Within this models folder, create a new file called File.js and paste the following code into it.

This version simplifies the instructions and improves clarity while maintaining the original meaning.


import mongoose, { Schema, Document, Model } from "mongoose";

// Define an interface for the file document
interface IFile extends Document {
  name: string;
  content: string;
  createdAt: Date;
  updatedAt: Date;
}

// Define the schema for the file model
const fileSchema = new Schema(
  {
    _id: { type: Schema.Types.ObjectId, auto: true }, // MongoDB default _id
    name: { type: String, required: true }, // Removed unique constraint
    content: { type: String, required: true },
  },
  { timestamps: true } // Automatically adds createdAt & updatedAt
);

// Export the File model with type safety
const File: Model =
  mongoose.models.File || mongoose.model("File", fileSchema);

export default File;

Code Explanation

This code defines a Mongoose schema and model for a File collection in a MongoDB database. It specifies the structure and rules for documents in the collection.

This code defines a Mongoose schema and model for a File document in MongoDB. Here's a brief explanation:

Key Components:

Interface (IFile):
- Defines the structure of a File document with:
  - name (string, required).
  - content (string, required).
  - createdAt and updatedAt (automatically managed by Mongoose).
Schema (fileSchema):
- Maps the IFile interface to a MongoDB schema.
- Includes:
  - _id: Auto-generated MongoDB ObjectId.
  - name and content: Required fields.
  - timestamps: true: Automatically adds createdAt and updatedAt fields.
Model (File):
- Creates or retrieves the Mongoose model for the File collection.
- Ensures type safety using the IFile interface.

Connecting to database

Half of the work is done! Now, it’s time to connect our app to the database. To do this, I’ll create a new file inside the lib folder, where we previously created the database schema. I’ll name the file mongodb.tsx and paste the following code inside it:

import mongoose, { Schema, Model, Connection } from "mongoose";
import { IFile } from "../types";

// Define mongoose connection URI
const MONGODB_URI = process.env.MONGODB_URI;

if (!MONGODB_URI) {
  throw new Error(
    "Please define the MONGODB_URI environment variable inside .env.local"
  );
}

let cached: {
  conn: Connection | null;
  promise: Promise | null;
} = { conn: null, promise: null };

export async function connectDB(): Promise<Connection> {
  if (cached.conn) {
    return cached.conn;
  }

  if (!cached.promise) {
    cached.promise = mongoose.connect(MONGODB_URI!).then((mongoose) => {
      return mongoose.connection;
    });
  }

  try {
    cached.conn = await cached.promise;
  } catch (e) {
    cached.promise = null;
    throw e;
  }

  return cached.conn;
}

// Define the schema for the file model
const fileSchema = new Schema(
  {
    name: { type: String, required: true },
    content: { type: String, required: true },
  },
  {
    timestamps: true,
  }
);

// Export the File model with type safety
export const File = (mongoose.models.File ||
mongoose.model("File", fileSchema)) as Model;

Code Explanation

This code sets up a MongoDB connection using the mongoose library in a Node.js or Next.js application. It ensures that the database is connected efficiently and prevents redundant connections.

This code sets up a MongoDB connection and defines a Mongoose schema and model for a File document. Here's a brief explanation:

Key Components:

MongoDB Connection:
- Uses the MONGODB_URI environment variable to connect to MongoDB.
- Implements a caching mechanism to reuse the connection and avoid multiple connections.
- Throws an error if MONGODB_URI is not defined.
Schema (fileSchema):
- Defines the structure of a File document with:
  - name (string, required).
  - content (string, required).
- Automatically adds createdAt and updatedAt timestamps.
Model (File):
- Creates or retrieves the Mongoose model for the File collection.
- Ensures type safety using the IFile interface.

Example Directory Structure:

/project
  /pages
    /api
      test.js
  /utils
    connectDB.js
  .env.local

Final Notes:

This code avoids multiple MongoDB connections by checking the readyState.
It's reusable and modular, making it easy to maintain.
Always secure the MONGODB_URI in-environment variables to avoid exposing sensitive credentials.

Ensuring type safety

Since we are using TypeScript, we will have to declare the file type files , socket and an index. To do so, create a new folder in root directory of the project and name it types and make three files socket.ts ,files.ts and index.ts inside the folder. Inside each file, paste the given code for their respective file.

//index.ts
export interface IFile {
  _id: string;
  name: string;
  content: string;
  createdAt?: Date;
  updatedAt?: Date;
}
//socket.ts
import { FileData } from '../types/file';

export interface ServerToClientEvents {
"new-file": (file: FileData) => void;
"delete-file": (fileId: string) => void;
"file-update": (data: { fileId: string; content: string }) => void;
}

export interface ClientToServerEvents {
"new-file": (file: FileData) => void;
"delete-file": (fileId: string) => void;
"file-update": (data: { fileId: string; content: string }) => void;
}
//file.ts
export interface FileData {
_id: string;
name: string;
content: string;
}

How to Build the Front End

For the front end, we’ll keep it simple, aiming for a UI that closely resembles Replit. The key components we need for this project are a File Explorer, Monaco Editor, and Sandbox component.

File Explorer: This component will display and manage the code files, positioned on the left side of the screen.
Monaco Editor: This component will allow users to view and edit the content of the code files.
Sandbox: This component will render the live preview of the content inside the code files.

To build these components, we won’t use any third-party UI libraries; instead, we’ll rely solely on TailwindCSS, which is pre-configured with Next.js.

Now, let’s build the components:

Open your VS Code.
Open the Next.js folder where you created your project.

Since I work without a src folder, you’ll find only an app folder. Inside the app folder, create a new folder called components.

After creating the folder, your project structure should look something like this:
FileExplorer.js -This is our file explorer
ScreenOne.js- This is our Monaco editor
LivePreview.js- This is our sandbox component

Let’s see how I build these components and you can too,

FileExploer.tsx

The FileExplorer is a React component that displays a list of files fetched from a backend (MongoDB) and allows users to select, create, edit, and delete files. It uses React Hooks for state management and lifecycle effects, Tailwind CSS for styling, and lucide-react icons for UI actions.

import React, { useEffect, useState } from "react";
import { Plus, Trash2, Pencil } from "lucide-react";
import io, { Socket } from "socket.io-client";
import { FileData } from '../types/file';

interface FileExplorerProps {
files: FileData[];
onFileSelect: (file: FileData) => void;
currentFile: FileData | null;
}

const FileExplorer: React.FC = ({
files: initialFiles,
onFileSelect,
currentFile,
}) => {
const [files, setFiles] = useState(initialFiles);
  const [socket, setSocket] = useStatenull>(null);
  const [loading, setLoading] = useState<boolean>(true);
  const [error, setError] = useState<string | null>(null);
  const [newFileName, setNewFileName] = useState<string>("");
  const [editingFile, setEditingFile] = useState<string | null>(null);
  const [editedFileName, setEditedFileName] = useState<string>("");

  // Initialize socket connection
  useEffect(() => {
    const socketInstance = io("http://localhost:3000", {
      reconnection: true,
      reconnectionAttempts: 5,
      reconnectionDelay: 1000,
    });

    socketInstance.on("connect", () => {
      console.log("Connected to Socket.IO server");
    });

    socketInstance.on("connect_error", (error) => {
      console.error("Socket connection error:", error);
    });

    socketInstance.on("disconnect", () => {
      console.log("Disconnected from Socket.IO server");
    });

    setSocket(socketInstance);

    return () => {
      if (socketInstance) {
        socketInstance.disconnect();
      }
    };
  }, []);

  useEffect(() => {
    if (!socket) return;

    // Listen for real-time updates
    socket.on("new-file", (newFile: FileData) => {
      setFiles((prevFiles) => {
        if (!prevFiles.some((file) => file._id === newFile._id)) {
          return [...prevFiles, newFile];
        }
        return prevFiles;
      });
    });

    socket.on("delete-file", (fileId: string) => {
      setFiles((prevFiles) => prevFiles.filter((file) => file._id !== fileId));
    });

    socket.on("update-file", (updatedFile: FileData) => {
      setFiles((prevFiles) =>
        prevFiles.map((file) =>
          file._id === updatedFile._id
            ? { ...file, name: updatedFile.name }
            : file
        )
      );
    });

    return () => {
      socket.off("new-file");
      socket.off("delete-file");
      socket.off("update-file");
    };
  }, [socket]);

  // Fetch initial files
  const fetchFiles = async () => {
    try {
      const response = await fetch("/api/files");
      if (!response.ok) throw new Error("Failed to fetch files");
    const data: FileData[] = await response.json();
      setFiles(data);
    } catch (error) {
      console.error("Error fetching files:", error);
      setError("Failed to load files");
    } finally {
      setLoading(false);
    }
  };

  useEffect(() => {
    fetchFiles();
  }, []);

  // Create new file
  const createNewFile = async () => {
    if (!newFileName.trim()) return;
    try {
      const response = await fetch("/api/files", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ name: newFileName }),
      });

      if (!response.ok) throw new Error("Failed to create file");

    const newFile: FileData = await response.json();
      socket?.emit("new-file", newFile);
      setNewFileName("");
    } catch (error) {
      console.error("Error creating file:", error);
    }
  };

  const handleDeleteFile = async (e: React.MouseEvent, id: string) => {
    e.stopPropagation();
    setFiles((prevFiles) => prevFiles.filter((file) => file._id !== id)); // Optimistic update

    try {
      const response = await fetch("/api/files", {
        method: "DELETE",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ id }),
      });

      if (!response.ok) throw new Error("Failed to delete file");

      socket?.emit("delete-file", id);
    } catch (error) {
      console.error("Error deleting file:", error);
      await fetchFiles(); // Revert state if API call fails
    }
  };

const handleEditStart = (e: React.MouseEvent, file: FileData) => {
    e.stopPropagation();
    setEditingFile(file._id);
    setEditedFileName(file.name);
  };

  const handleEditSave = async (
    e: React.FocusEvent | React.KeyboardEvent,
    id: string
  ) => {
    e.preventDefault();
    if (!editedFileName.trim()) return;

    const previousFiles = [...files];
    setFiles((prevFiles) =>
      prevFiles.map((file) =>
        file._id === id ? { ...file, name: editedFileName } : file
      )
    ); // Optimistic update

    try {
      const response = await fetch("/api/files", {
        method: "PUT",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ id, name: editedFileName }),
      });

      if (!response.ok) throw new Error("Failed to update file");

    const updatedFile: FileData = await response.json();
      socket?.emit("update-file", updatedFile);
      setEditingFile(null);
    } catch (error) {
      console.error("Error updating file:", error);
      setFiles(previousFiles); // Revert state if API call fails
    }
  };

  return (
    "w-64 bg-gray-900 p-4 h-full text-white rounded-lg shadow-lg flex flex-col">
      "text-lg font-semibold mb-4">Files

      {loading ? (
        "text-gray-400 text-sm">Loading files...
      ) : error ? (
        "text-red-500 text-sm">{error}
      ) : files.length === 0 ? (
        "text-gray-400 text-sm">No files yet
      ) : (
        "space-y-2 overflow-y-auto flex-grow">
          {files.map((file) => (
            `cursor-pointer flex justify-between items-center p-2 rounded text-white transition-all duration-200 ${
                currentFile?._id === file._id
                  ? "bg-blue-600"
                  : "hover:bg-gray-700"
              }`}
              onClick={() => onFileSelect(file)}
            >
              {editingFile === file._id ? (
                type="text"
                  value={editedFileName}
                onChange={(e: React.ChangeEvent) => setEditedFileName(e.target.value)}
                onBlur={(e: React.FocusEvent) => handleEditSave(e, file._id)}
                onKeyDown={(e: React.KeyboardEvent) =>
                e.key === "Enter" ? handleEditSave(e, file._id) : null
                }
                  autoFocus
                  className="bg-gray-800 text-white p-1 rounded outline-none w-32"
                />
              ) : (
                "truncate flex-grow">📄 {file.name}
              )}

              "flex items-center gap-2">
                
                
              
            
          ))}
        
      )}


    
  );
};

export default FileExplorer;

Code Explanation

Brief Explanation of the Code

The FileExplorer component is a React component designed to manage and display a list of files in real time. It uses Socket.IO for real-time updates, allowing users to add, delete, and edit files dynamically.

Key Features:

1. State Management

The component uses React's useState Hook to manage the following states:

files: List of files displayed in the File Explorer.
socket: The active Socket.IO connection.
loading & error: Manage the state of file loading.
newFileName, editingFile, and editedFileName: Manage file creation and editing processes.

const [files, setFiles] = useState([]);
const [socket, setSocket] = useState(null);
const [loading, setLoading] = useState(true);
const [error, setError] = useState(null);
const [newFileName, setNewFileName] = useState("");
const [editingFile, setEditingFile] = useState(null);
const [editedFileName, setEditedFileName] = useState("");

2. Socket.IO Integration

Establishes a real-time connection to a Socket.IO server.
Listens for events like new-file, delete-file, and update-file to update the file list dynamically.
Cleans up the socket connection when the component unmounts.

useEffect(() => {
  const socketInstance = io("http://localhost:3000", {
    reconnection: true,
    reconnectionAttempts: 5,
    reconnectionDelay: 1000,
  });

  socketInstance.on("connect", () => {
    console.log("Connected to Socket.IO server");
  });

  setSocket(socketInstance);

  return () => {
    if (socketInstance) socketInstance.disconnect();
  };
}, []);

3. Real-Time File Updates

Handles real-time events for creating, deleting, and updating files.

useEffect(() => {
  if (!socket) return;

  socket.on("new-file", (newFile) => {
    setFiles((prevFiles) =>
      prevFiles.some((file) => file._id === newFile._id)
        ? prevFiles
        : [...prevFiles, newFile]
    );
  });

  socket.on("delete-file", (fileId) => {
    setFiles((prevFiles) => prevFiles.filter((file) => file._id !== fileId));
  });

  socket.on("update-file", (updatedFile) => {
    setFiles((prevFiles) =>
      prevFiles.map((file) =>
        file._id === updatedFile._id
          ? { ...file, name: updatedFile.name }
          : file
      )
    );
  });

  return () => {
    socket.off("new-file");
    socket.off("delete-file");
    socket.off("update-file");
  };
}, [socket]);

4. CRUD Operations

Fetch Files: Retrieves the initial list of files from the server.
Create File: Sends a POST request to add a new file.
Delete File: Sends a DELETE request to remove a file and updates the UI optimistically.
Edit File: Sends a PUT request to update a file's name and performs optimistic updates.

This code defines a FileExplorer React component that allows users to manage and interact with files in a file system.

Note: All the operations on the application get saved in real-time for the demo you can refresh the page to see the changes don’t get removed.

ScreenOne.tsx

The ScreenOne component is a code editor panel that dynamically displays and updates code for a selected file. It integrates the Monaco Editor to highlight syntax based on the file type (for example, JavaScript, HTML, CSS).

The component shows the selected file's name, allows users to edit its content, and sends updates back to the database in real time. It also offers a clean, user-friendly interface with a dark theme and configurable editor options. This is ideal for coding environments like IDEs or code playgrounds.


import React, { useEffect, useState } from "react";
import { Editor } from "@monaco-editor/react";

interface File {
  name: string;
}

interface ScreenOneProps {
  selectedFile: File | null;
  code: string;
  onChange: (newCode: string | undefined) => void;
}

const ScreenOne: React.FC = ({ selectedFile, code, onChange }) => {
  const [language, setLanguage] = useState<string>("javascript");

  useEffect(() => {
    if (!selectedFile) return;
    setLanguage(getLanguageForFile(selectedFile.name));
  }, [selectedFile]);

  const getLanguageForFile = (filename: string): string => {
    const extension = filename.split(".").pop()?.toLowerCase();
    switch (extension) {
      case "js":
      case "jsx":
        return "javascript";
      case "html":
        return "html";
      case "css":
        return "css";
      case "json":
        return "json";
      default:
        return "plaintext";
    }
  };

  const handleCodeChange = (newCode: string | undefined): void => {
    onChange(newCode); // Call the onChange prop to update the code in LivePreview
  };

  return (
    "flex-1 flex flex-col bg-[#2d2d2d] text-white p-6 rounded-lg shadow-md">
      "flex items-center justify-between mb-4">
        "text-2xl font-semibold">Code Editor
        "text-sm text-gray-400">
          {selectedFile ? selectedFile.name : "No file selected"}
        
      
      "flex-grow bg-gray-800 rounded-lg shadow-inner">
        "calc(100vh - 160px)"
          language={language}
          value={code}
          onChange={handleCodeChange} // Update the code on change
          theme="vs-dark"
          options={{
            minimap: { enabled: false },
            lineNumbers: "on",
            wordWrap: "on",
            scrollBeyondLastLine: false,
          }}
        />
      
    
  );
};

export default ScreenOne;

Code Explanation

Explanation of the Code:

This React component, ScreenOne, represents a code editor screen where users can edit files in a specified programming language. The editor dynamically adjusts its syntax highlighting based on the selected file's type. It uses the @monaco-editor/react library for the editor interface.

This code defines a ScreenOne React component, which is a code editor using the Monaco Editor (used in VS Code). Here's a brief explanation:

Key Features:

Code Editor:
- Uses the @monaco-editor/react library to render a code editor.
- Supports syntax highlighting for various languages (for example, JavaScript, HTML, CSS, JSON).
Dynamic Language Detection:
- Detects the programming language based on the selected file's extension (for example, .js → JavaScript).
- Defaults to plaintext for unsupported file types.
Props:
- selectedFile: The currently selected file (contains the file name).
- code: The current code content to display in the editor.
- onChange: A callback function to handle code changes.
UI:
- Displays the file name and a title ("Code Editor").
- Styled with Tailwind CSS for a dark theme and rounded corners.
Editor Configuration:
- Uses the vs-dark theme.
- Disables the mini-map and enables line numbers and word wrap.

LivePreview.tsx

The LivePreview component dynamically generates a live code preview for either static projects (HTML, CSS, JS) or React-based projects. It detects the type of project, and sets up the required files (for example, index.html, App.js), and renders a real-time preview using CodeSandbox's Sandpack. The preview adapts to the selected file and updates as the code changes, providing a seamless coding experience.


import React, { useEffect, useState } from "react";
import {
  SandpackProvider,
  SandpackLayout,
  SandpackCodeEditor,
  SandpackPreview,
  SandpackThemeProvider,
} from "@codesandbox/sandpack-react";

interface FileAccumulator {
[key: string]: { code: string };
}

interface File {
  name: string;
  content: string;
}

interface LivePreviewProps {
files: File[];
currentFile: File | null;
code: string;
onCodeChange?: (value: string | undefined) => void;
}
interface SandpackFile {
  code: string;
}

interface SandpackFiles {
  [key: string]: SandpackFile;
}

const LivePreview: React.FC = ({ files, currentFile, code }) => {
  const [sandboxFiles, setSandboxFiles] = useStatestring, { code: string }>>({});
  const [template, setTemplate] = useState<"vanilla" | "react">("vanilla"); // Default to static
  const [loading, setLoading] = useState<boolean>(true);

  useEffect(() => {
    if (!currentFile || !files) return;

    const newFiles: SandpackFiles = files.reduce((acc: FileAccumulator, file) => {
    acc[`/${file.name}`] = { code: file.content };
    return acc;
    }, {});

    // Check if the project is React-based
    const isReactProject = files.some(
      (file) =>
        file.name.endsWith(".jsx") ||
        (file.name.endsWith(".js") && file.content.includes("React"))
    );

    if (isReactProject) {
      setTemplate("react");

      // Ensure App.js exists
      if (!newFiles["/App.js"]) {
        newFiles["/App.js"] = {
          code: `
            import React from "react";
            function App() { return Hello, React!; }
            export default App;
          `,
        };
      }

      // Ensure index.js exists
      newFiles["/index.js"] = {
        code: `
          import React from "react";
          import ReactDOM from "react-dom/client";
          import App from "./App";

          const root = document.getElementById("root");
          if (root) {
            ReactDOM.createRoot(root).render();
          } else {
            console.error("Root element not found!");
          }
        `,
      };

      // Ensure index.html exists
      newFiles["/index.html"] = {
        code: `
          
          
          
            
            
            React App
          
          
            
          
          
        `,
      };

      // Ensure package.json exists
      newFiles["/package.json"] = {
        code: JSON.stringify(
          {
            main: "/index.js",
            dependencies: {
              react: "18.2.0",
              "react-dom": "18.2.0",
            },
          },
          null,
          2
        ),
      };
    } else {
      setTemplate("vanilla");

      const htmlFile = files.find((f) => f.name.endsWith(".html"));
      if (htmlFile) {
        let htmlContent = htmlFile.content;

        // Inject CSS files
        files
          .filter((f) => f.name.endsWith(".css"))
          .forEach((cssFile) => {
            htmlContent = htmlContent.replace(
              "",
              `${cssFile.name}">`
            );
          });

        // Inject JS files
        files
          .filter((f) => f.name.endsWith(".js"))
          .forEach((jsFile) => {
            htmlContent = htmlContent.replace(
              "",
              ``
            );
          });

        newFiles["/index.html"] = { code: htmlContent };
      }
    }

    // Ensure the current file is included
    newFiles[`/${currentFile.name}`] = { code };
    setSandboxFiles(newFiles);
    setLoading(false);
  }, [files, currentFile, code]);

  return (
    "flex-1 bg-white border-l border-gray-300">
      {loading ? (
        "h-full flex items-center justify-center text-gray-500">
          Loading...
        
      ) : currentFile ? (
        `/${currentFile.name}` }}
        >
        
            
            false}  />
            "600px", border: "none" }} />
            
        
        
      ) : (
        "h-full flex items-center justify-center text-gray-500">
          Select a file to preview
        
      )}
    
  );
};

export default LivePreview;

Code Explanation

Explanation of the Code:

The LivePreview component provides a real-time live preview environment for static HTML/CSS/JS files or React-based projects. It uses the CodeSandbox Sandpack library to dynamically render code files in a browser-like preview window. The component automatically adjusts its behavior based on the file types and content to determine if the project is static or React-based.

This code defines a LivePreview React component that uses Sandpack (from CodeSandbox) to provide a live code editor and preview environment. Here's a brief explanation:

Key Features:

Sandpack Integration:
- Uses @codesandbox/sandpack-react to render a code editor and live preview.
- Supports both React and vanilla JavaScript/HTML/CSS projects.
Dynamic File Handling:
- Converts a list of files (files prop) into a format compatible with Sandpack.
- Automatically detects if the project is React-based (e.g., contains .jsx or React imports).
- Ensures necessary files (for example, App.js, index.js, index.html, package.json) exist for React projects.
Template Switching:
- Sets the Sandpack template to "react" for React projects or "vanilla" for static HTML/CSS/JS projects.
Code Injection:
- For vanilla projects, injects linked CSS and JS files into the HTML file.
Loading State:
- Displays a loading message while processing files.
UI:
- Shows a code editor and live preview side by side.
- Displays a message if no file is selected.

Running sockets in the app

Now it is time to eat that big frog. As you know we are using sockets for real-time data communication so we need a server.tsx file in the root directory of the app (outside of the src folder) and paste this code:


import { createServer, IncomingMessage, ServerResponse } from "http";
import { parse, UrlWithParsedQuery } from "url";
import next from "next";
import { Server, Socket } from "socket.io";

const dev: boolean = process.env.NODE_ENV !== "production";
const app = next({ dev });
const handle = app.getRequestHandler();

app.prepare().then(() => {
  const httpServer = createServer((req: IncomingMessage, res: ServerResponse) => {
    const parsedUrl: UrlWithParsedQuery = parse(req.url || "", true);
    handle(req, res, parsedUrl);
  });

  // Determine the CORS origin dynamically
  const allowedOrigin: string = dev
    ? "http://localhost:3000" // Local development
    : "*"; // Vercel deployment

  // Initialize Socket.IO with dynamic CORS configuration
  const io = new Server(httpServer, {
    cors: {
      origin: allowedOrigin,
      methods: ["GET", "POST"],
      credentials: true,
    },
  });

  // Socket.IO event handlers
  io.on("connection", (socket: Socket) => {
    console.log("Client connected");

    // Handle new file creation
    socket.on("new-file", (newFile: { id: string; name: string; content: string }) => {
      console.log("New file created:", newFile);
      // Broadcast to all clients except sender
      socket.broadcast.emit("new-file", newFile);
    });

    // Handle file deletion
    socket.on("delete-file", (fileId: string) => {
      console.log("File deleted:", fileId);
      socket.broadcast.emit("delete-file", fileId);
    });

    // Handle file update
    socket.on("update-file", (updatedFile: { id: string; name: string; content: string }) => {
      console.log("File updated:", updatedFile);
      socket.broadcast.emit("update-file", updatedFile);
    });

    // Handle client disconnect
    socket.on("disconnect", () => {
      console.log("Client disconnected");
    });
  });

  // Start the server on the specified port
  const PORT: number | string = process.env.PORT || 3000;
  httpServer.listen(PORT, () => {
    console.log(`> Ready on ${dev ? "http://localhost:3000" : allowedOrigin}`);
  });
});

Code Explanation

This code sets up a Next.js server with Socket.IO for real-time communication. It:

Initializes a Next.js app and prepares it to handle HTTP requests.
Configures CORS dynamically for Socket.IO, allowing connections from localhost:3000 in development or all origins in production.
Sets up Socket.IO to handle real-time events like:
- New file creation
- File deletion
- File updates
- Client disconnection
Broadcasts events to all connected clients except the sender.
Starts the server on a specified port (default: 3000).

It’s a basic real-time server for file management with Next.js and Socket.IO.

Clubbing all components together

To do this we will have to tweak the page.tsx. Just copy the given code and paste it into the page.js


"use client";
import React, { useState, useEffect } from "react";
import { useCopilotAction, useCopilotReadable } from "@copilotkit/react-core";
import { CopilotPopup } from "@copilotkit/react-ui";
import ScreenOne from "./components/ScreenOne";
import FileExplorer from "./components/FileExplorer";
import LivePreview from "./components/LivePreview";
import io, { Socket } from "socket.io-client";

interface File {
  _id: string;
  name: string;
  content: string;
}

function Page() {
  const [files, setFiles] = useState([]);
  const [currentFile, setCurrentFile] = useStatenull>(null);
  const [code, setCode] = useState<string>("// Select or create a file");
  const [socket, setSocket] = useStatenull>(null);
  const [fileContents, setFileContents] = useStatestring, string>>({});

  // Initialize socket connection
  useEffect(() => {
    const socketInstance = io("http://localhost:3000", {
      reconnection: true,
      reconnectionAttempts: 5,
      reconnectionDelay: 1000,
    });

    socketInstance.on("connect", () => {
      console.log("Connected to Socket.IO server");
    });

    // Handle real-time file updates
    socketInstance.on(
      "file-update",
      ({ fileId, content }: { fileId: string; content: string }) => {
        setFileContents((prev) => ({
          ...prev,
          [fileId]: content,
        }));

        if (currentFile && currentFile._id === fileId) {
          setCode(content);
        }
      }
    );

    socketInstance.on("new-file", (newFile: File) => {
      setFiles((prev) => [...prev, newFile]);
      setFileContents((prev) => ({
        ...prev,
        [newFile._id]: newFile.content,
      }));
    });

    socketInstance.on("delete-file", (fileId: string) => {
      setFiles((prev) => prev.filter((file) => file._id !== fileId));
      setFileContents((prev) => {
        const updated = { ...prev };
        delete updated[fileId];
        return updated;
      });
    });

    setSocket(socketInstance);

    return () => {
      if (socketInstance) {
        socketInstance.disconnect();
      }
    };
  }, [currentFile]);

useCopilotReadable({
description: "Current state of the workspace",
value: {
    files: files.map((f) => f.name),
    currentFile: currentFile?.name,
    currentCode: code,
},
});

  const fetchFiles = async () => {
    try {
      const response = await fetch("/api/files");
      if (!response.ok) throw new Error("Failed to fetch files");
      const data: File[] = await response.json();

      // Store all file contents in state
      const contents: Record<string, string> = {};
      data.forEach((file) => {
        contents[file._id] = file.content;
      });

      setFiles(data);
      setFileContents(contents);
    } catch (error) {
      console.error("Error fetching files:", error);
    }
  };

  useEffect(() => {
    fetchFiles();
  }, []);

  const handleFileSelect = async (file: File) => {
    setCurrentFile(file);

    // Use cached content if available
    if (fileContents[file._id]) {
      setCode(fileContents[file._id]);
    } else {
      try {
        const response = await fetch(`/api/files/${file._id}`);
        if (!response.ok) throw new Error("Failed to fetch file content");
        const data = await response.json();

        setFileContents((prev) => ({
          ...prev,
          [file._id]: data.content,
        }));
        setCode(data.content);
      } catch (error) {
        console.error("Error fetching file content:", error);
      }
    }
  };

  const handleCodeChange = async (value: string | undefined) => {
    if (!currentFile || !value) return;

    // Update local state immediately
    setCode(value);
    setFileContents((prev) => ({
      ...prev,
      [currentFile._id]: value,
    }));

    try {
      // Emit the change to other clients
      if (socket) {
        socket.emit("file-update", {
          fileId: currentFile._id,
          content: value,
        });
      }

      // Save to backend
      await fetch("/api/files", {
        method: "PUT",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ id: currentFile._id, content: value }),
      });
    } catch (error) {
      console.error("Error updating file:", error);
    }
  };

  const processFiles = async ({ response }: { response: string }) => {
    try {
      const filePattern =
        /FILE:\s*([\w.\-\/]+)\s*\nCODE:\s*([\s\S]*?)(?=\nFILE:|$)/g;
      let match;
      const newFiles: File[] = [];

      while ((match = filePattern.exec(response)) !== null) {
        const fileName = match[1].trim();
        const fileContent = match[2].trim();

        if (fileName && fileContent) {
          const res = await fetch("/api/files", {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({ name: fileName, content: fileContent }),
          });

          if (res.ok) {
            const savedFile: File = await res.json();
            newFiles.push(savedFile);

            // Update local state
            setFileContents((prev) => ({
              ...prev,
              [savedFile._id]: savedFile.content,
            }));

            // Emit new file to other clients
            if (socket) {
              socket.emit("new-file", savedFile);
            }
          }
        }
      }

      setFiles((prevFiles) => [...prevFiles, ...newFiles]);
      return `Files saved successfully: ${newFiles
        .map((f) => f.name)
        .join(", ")}`;
    } catch (error) {
      console.error("Error processing files:", error);
      return "Failed to save files.";
    }
  };

  useCopilotAction({
    name: "processFiles",
    description: "Processes AI-generated files and saves them to MongoDB",
    parameters: [{ name: "response", type: "string", required: true }],
    handler: processFiles,
  });

  return (
    "h-screen flex bg-gray-100">
      
      "flex-1 flex flex-col p-4">
        
      
      
      `
    You are an AI-powered code generator. Use the following actions:

    1. @processFiles - To create new files, use this format:
    @processFiles(response: \`
    FILE: filename.ext
    CODE:
    [file content]
    \`)

    - Store new files in MongoDB using /api/files.
    - Then immediately fetch the files from database and show the files to FileExplorer
    - Correctly classify and separate different file types:
      - Static: HTML, CSS, JS
      - React: JSX, JS (React components)
    - For React projects:
      - Ensure the presence of index.js as the entry point.
      - Ensure there is a App.css file for styling
      - Ensure index.html contains a root .
      - Separate components correctly (e.g., App.js, Header.jsx).
      - Include a package.json file with necessary React dependencies.
      - Ensure all React files follow ES6+ syntax and React best practices.

    2. @updateFile - To update existing files:
    @updateFile(filename: "file.ext", content: "new content")

    - Maintain compatibility with React environment.
    - Ensure any updated files do not break existing imports.
  `}
        labels={{
          title: "Project Assistant",
          initial: "What would you like to create?",
        }}
      />
    
  );
}

export default Page;

Code explanation

State Management:
- Tracks files (files), the currently selected file (currentFile), code in the selected file (code), real-time file contents (fileContents), and a socket connection (socket).
Socket.IO:
- Establishes a connection to a server using Socket.IO, and handling real-time file updates like file creation, updates, and deletions.
- Listens for events such as file-update, new-file, and delete-file to update the UI and propagate changes across users.
Fetching Files:
- On component mount, it fetches all files from an API and populates the state with the files and their contents.
- Upon selecting a file, the content is either retrieved from the cached state or fetched from the server.
Code Changes:
- When code in the Monaco Editor is updated, the new content is saved locally and sent to the server and other connected clients via the socket.
File Processing by AI:
- When AI generates code, the processFiles function parses the generated content, creates files on the backend, and updates the frontend. These files are stored in MongoDB and synchronized with the client via Socket.IO.
CopilotKit Integration:
- Uses the useCopilotAction hook to integrate AI-driven file generation and updating functionality.
- Provides instructions for creating and updating files via the CopilotPopup.
- Always give detailed instructions to the CopilotPopup .
UI Components:
- The UI includes components like FileExplorer, ScreenOne, and LivePreview, which displays files, allows editing, and provides a live preview of the code.
- The CopilotPopup acts as an assistant to guide the AI in generating or updating files.

This setup creates a collaborative, real-time code editing environment with support for both static and React-based projects.

Configuring CopilotKit for the Whole App

This is going to be the last step of building the application. Navigate to the layout.tsx file and add this code:

import { CopilotKit } from "@copilotkit/react-core";
import "./globals.css";
import "@copilotkit/react-ui/styles.css";
import { ReactNode } from "react";

export const metadata = {
  title: "Replit Clone",
  description: "Copilotkit Replit Clone",
};

// Define props type for RootLayout
interface RootLayoutProps {
  children: ReactNode;
}

export default function RootLayout({ children }: RootLayoutProps) {
  return (
    <html lang="en">
      <body>
        <CopilotKit runtimeUrl="/api/copilotkit">{children}CopilotKit>
      body>
    html>
  );
}

Here’s what’s going on in this code:

This code defines a RootLayout component, which serves as the root layout for a Next.js application. Here's a brief explanation:

Key Features:

CopilotKit Integration:
- Wraps the entire application with the CopilotKit component from @copilotkit/react-core.
- Configures the runtimeUrl to /api/copilotkit, which is the endpoint for handling Copilot-related functionality.
Global Styles:
- Imports global CSS styles (globals.css) and CopilotKit UI styles (@copilotkit/react-ui/styles.css).
Metadata:
- Sets metadata for the application (title: "Replit Clone", description: "Copilotkit Replit Clone").
Layout Structure:
- Uses the html and body tags to structure the document.
- Renders children (the rest of the application) inside the CopilotKit wrapper.

Some Important Notes

Designing and deploying a database can vary depending on the tools and requirements. For this project, I’ve chosen the simplest and most accessible approach.

Why CopilotKit?

CopilotKit is a powerful tool that converts natural language processing (NLP) queries into actionable backend code that runs on meta LLM. If you have an alternative that serves a similar purpose, feel free to use it. It effectively bridges the gap between natural language input and technical execution, making it an ideal choice for projects like this.

Why GroqCloud?

I selected GroqCloud because it’s free and offers access to multiple large language models (LLMs) with a single API key. While alternatives like ChatGPT are available, they may require paid plans. GroqCloud’s versatility and affordability make it the perfect fit for this tutorial.

Security Best Practices

Never expose your credentials publicly. Always store sensitive information like API keys in an .env file to keep your project secure.

Future Enhancements

While this tutorial focuses on setting up and working with React files, CopilotKit has a much broader range of capabilities that I will explain in the upcoming blog posts.

I aim to build at least 15 AI products in 2025.

Support for static files is coming soon.

As promised in the previous tutorial, I’ve implemented the CopilotKit CRUD feature in this tutorial as well.

In my next tutorial, I will demonstrate how to build something more cool with CopilotKit to create a more dynamic and functional application.

Playing with the Replit Clone

You can explore the live project via the following link and ask the chatbot to build something in React. Live Project Link.

For a deeper understanding of the code, check out the GitHub repository here: GitHub Repository.

Also, here’s a screenshot showcasing its practical use. In this example, instead of manually creating project files, you can simply ask the CopilotKit chatbot to generate those files for you. You can then edit and play around with them.

For example, you can give the CopilotKit chatbot commands like: “Create a React app”.

Handling Errors

File Explorer Delays: Occasionally, due to database or Vercel deployment issues, files may be generated but not immediately visible in the File Explorer. In such cases, simply refresh the page, and the missing components will appear. This applies to all CRUD operations on files and their content as well.
Real-Time Saving: Any changes you make to files are saved to the database in real-time, ensuring that your work is never lost.
Command Errors: If the chatbot shows an error when processing your commands, simply retry the command until you receive a response.
Adding Extra Files:To add new files to the current project, simply ask the chatbot:
“Add a new file to the current project with the file name and extension.”

For example: “Add a new file named readme.md in this project”

Video Demo

Conclusion

I hope you’ve enjoyed building this simple Replit AI clone. In this project, we used a MongoDB database, but the approach can easily be applied to other databases, as long as you can retrieve the data.

I plan to create many more projects involving AI and other cutting-edge tools. AI is truly a game-changer in the IT field, and I’m excited to share more insights and practical implementations of the latest technologies.

That’s all from my side. If you found this article helpful, feel free to share it and connect with me. I’m always open to new opportunities:

Follow me on X: Prankur's Twitter
Connect with me on LinkedIn: Prankur's LinkedIn
Follow me on Github: Prankur’s Github
View my Portfolio: Prankur's Portfolio

How to Build an Invoice SaaS App with Next.js, Resend, Clerk and Neon Postgres

Ankur Tyagi — Thu, 01 Aug 2024 20:58:01 +0000

In this tutorial, you will learn how to build an invoicing web app that allows users to add their bank information, manage a list of customers, and create and send invoices to customers. You'll also learn how to print and send React components as invoices and email templates directly from the application to the customer's email.

This will be a great project to help you learn how to put together full stack apps, and how to create an app where the backend can communicate with the frontend in real time.

While building the application, you will gain hands-on experience working with the following developer tools:

Neon: a Postgres database that enables us to store and retrieve data easily within the application.
Clerk: a complete authentication system that ensures only authenticated users can perform specific actions within the application.
React-to-print: a package that allows us to convert and print React components as PDF files.
Resend and React Email: for sending beautifully designed digital invoices directly to the customers' email.

Here is the source code (remember to give it a star ⭐).

What is Neon?
Building the Invoice Application with Next.js
How to Authenticate Users Using Clerk
How to Add Neon to a Next.js app
How to Set Up Neon Serverless Driver with Drizzle ORM in Next.js
Creating the API endpoints for the application
How to Print and Download Invoices in Next.js
How to Send Digital Invoices with Resend and React Email
Next Steps

What is Neon?

Neon is an open-source, scalable, and efficient Postgres DB that separates compute from storage. This means that database computation processes (queries, transactions, and so on) are handled by one set of resources (compute), while the data itself is stored on a separate set of resources (storage).

This architecture allows for greater scalability and performance, making Neon a solid choice for modern web applications.

Neon - a serverless Postgres database

Building the Invoice Application with Next.js

In this section, I'll guide you through building the various pages of the invoicing application using Next.js. The application is divided into six key pages, each serving a specific purpose:

Home Page: This is the landing page. It provides an overview of the application and signs users into the application.
Settings Page: Here, users can update their bank information as it will be displayed on the invoices.
Customers Page: This page allows users to manage their customer base, and add or delete customers when needed.
Dashboard: The core of the application where users can create new invoices. Users can select a customer, enter the title and description of the invoice, and generate invoices.
History Page: This page displays recently created invoices. It includes links that enable users to preview each invoice, providing a quick way to review past transactions.
Print and Send Invoice Page: This page allows users to print and send invoices to customers.

Before we proceed, create a TypeScript Next.js project by running the following code snippet in your terminal:

npx create-next-app invoice-app-with-neon

Add a types.d.ts file within the project folder. It will contain the type declarations for the variables within the application.

interface Item {
    id: string;
    name: string;
    cost: number;
    quantity: number;
    price: number;
}

interface Invoice {
    id?: string,
    created_at?: string,
    user_id:  string,
    customer_id: number,
    title: string,
    items: string,
    total_amount: number,
}

interface Customer {
    user_id: string,
    name: string,
    email: string,
    address: string
}

interface BankInfo {
    user_id: string,
    account_name: string,
    account_number: number,
    bank_name: string,
    currency: string
}

Home Page

Copy the code snippet below into the app/page.tsx file. It displays brief information about the application and a button that redirects users to the dashboard or login page, depending on their authentication status.

import Link from "next/link";

export default function Home() {
  return (
    <main className='w-full'>
      <section className='p-8 h-[90vh] md:w-2/3 mx-auto text-center w-full flex flex-col items-center justify-center'>
        <h2 className='text-3xl font-bold mb-4 md:text-4xl'>
          Create invoices for your customers
        h2>
        <p className='opacity-70 mb-4 text-sm md:text-base leading-loose'>
          Invoicer is an online invoicing software that helps you craft and
          print professional invoices for your customers for free! Keep your
          business and clients with one invoicing software.
        p>
        <Link
          href='/dashboard'
          className='rounded w-[200px] px-2 py-3 bg-blue-500 text-gray-50'
        >
          LOG IN
        Link>
      section>
    main>
  );
}

Invoice-app-home-page

Settings Page

Add a settings folder containing a page.tsx file within the Next.js app directory and copy the following code snippet into the file:

"use client";
import { ChangeEvent, useEffect, useState, useCallback } from "react";
import SideNav from "@/app/components/SideNav";

export default function Settings() {
    //👇🏻 default bank info
    const [bankInfo, setBankInfo] = useState({
        account_name: "",
        account_number: 1234567890,
        bank_name: "",
        currency: "",
 });

    //👇🏻 bank info from the form entries
    const [inputBankInfo, setInputBankInfo] = useState({
        accountName: "",
        accountNumber: 1234567890,
        bankName: "",
        currency: "",
 });

    //👇🏻 updates the form entries state
    const handleUpdateBankInfo = (
        e: ChangeEvent
 ) => {
        const { name, value } = e.target;
        setInputBankInfo((prevState) => ({
 ...prevState,
 [name]: value,
 }));
 };

    //👇🏻 updates the bank info
    const handleSubmit = (e: React.FormEvent) => {
        e.preventDefault();
        console.log("Tries to update bank info...");
 };
return ()
}

The code snippet above shows that the page displays the user’s bank information and also allows the user to update it when necessary.

Return the UI elements below from the component:

export default function Settings() {
  //…React states and functions

  return (
    <div className='w-full'>
      <main className='min-h-[90vh] flex items-start'>
        <SideNav />

        <div className='md:w-5/6 w-full h-full p-6'>
          <h2 className='text-2xl font-bold'>Bank Informationh2>
          <p className='opacity-70 mb-4'>
            Update your bank account information
          p>

          <div className='flex md:flex-row flex-col items-start justify-between w-full md:space-x-4'>
            <section className='md:w-1/3 w-full bg-blue-50 h-full p-3 rounded-md space-y-3'>
              <p className='text-sm opacity-75'>
                Account Name: {bankInfo.account_name}
              p>
              <p className='text-sm opacity-75'>
                Account Number: {bankInfo.account_number}
              p>
              <p className='text-sm opacity-75'>
                Bank Name: {bankInfo.bank_name}
              p>
              <p className='text-sm opacity-75'>
                Currency: {bankInfo.currency}
              p>
            section>

            <form
              className='md:w-2/3 w-full p-3 flex flex-col'
              method='POST'
              onSubmit={handleSubmit}
            >
              <label htmlFor='accountName' className='text-sm'>
                Account Name
              label>
              <input
                type='text'
                name='accountName'
                id='accountName'
                className='border-[1px] p-2 rounded mb-3'
                required
                value={inputBankInfo.accountName}
                onChange={handleUpdateBankInfo}
              />

              <label htmlFor='accountNumber' className='text-sm'>
                Account Number
              label>
              <input
                type='number'
                name='accountNumber'
                id='accountNumber'
                className='border-[1px] p-2 rounded mb-3'
                required
                value={inputBankInfo.accountNumber}
                onChange={handleUpdateBankInfo}
              />

              <label htmlFor='bankName' className='text-sm'>
                Bank Name
              label>
              <input
                type='text'
                name='bankName'
                id='bankName'
                className='border-[1px] p-2 rounded mb-3'
                required
                value={inputBankInfo.bankName}
                onChange={handleUpdateBankInfo}
              />

              <label htmlFor='currency' className='text-sm'>
                Currency
              label>
              <select
                name='currency'
                id='currency'
                className='border-[1px] p-2 rounded mb-3'
                required
                value={inputBankInfo.currency}
                onChange={handleUpdateBankInfo}
              >
                <option value=''>Selectoption>
                <option value='$'>USDoption>
                <option value='€'>EURoption>
                <option value='£'>GBPoption>
              select>
              <div className='flex items-center justify-end'>
                <button
                  type='submit'
                  className='bg-blue-500 text-white p-2 w-[200px] rounded'
                >
                  Update Bank Info
                button>
              div>
            form>
          div>
        div>
      main>
    div>
  );
}

Invoice-app-settings-page

Customers Page

Add a customers folder containing a page.tsx file within the Next.js directory and copy the code snippet below into the file:

import CustomersTable from "../components/CustomersTable";
import { useCallback, useEffect, useState } from "react";
import SideNav from "@/app/components/SideNav";

export default function Customers() {
  const [customerName, setCustomerName] = useState("");
  const [customerEmail, setCustomerEmail] = useState("");
  const [customerAddress, setCustomerAddress] = useState("");
  const [loading, setLoading] = useState(false);
  const [customers, setCustomers] = useState([]);

  const handleAddCustomer = (e: React.FormEvent) => {
    e.preventDefault();
    // 👉🏻 createCustomer();
  };

  return (
    <div className='w-full'>
      <main className='min-h-[90vh] flex items-start'>
        <SideNav />
        <div className='md:w-5/6 w-full h-full p-6'>
          <h2 className='text-2xl font-bold'>Customersh2>
          <p className='opacity-70 mb-4'>Create and view all your customersp>

          <form className='w-full' onSubmit={handleAddCustomer} method='POST'>
            <div className='w-full flex items-center space-x-4 mb-3'>
              <section className='w-1/2'>
                <label>Customer's Namelabel>
                <input
                  type='text'
                  className='w-full p-2 border border-gray-200 rounded-sm'
                  value={customerName}
                  required
                  onChange={(e) => setCustomerName(e.target.value)}
                />
              section>

              <section className='w-1/2'>
                <label>Email Addresslabel>
                <input
                  type='email'
                  className='w-full p-2 border border-gray-200 rounded-sm'
                  value={customerEmail}
                  onChange={(e) => setCustomerEmail(e.target.value)}
                  required
                />
              section>
            div>
            <label htmlFor='address'>Billing Addresslabel>
            <textarea
              name='address'
              id='address'
              rows={3}
              className='w-full p-2 border border-gray-200 rounded-sm'
              value={customerAddress}
              onChange={(e) => setCustomerAddress(e.target.value)}
              required
            />
            <button
              className='bg-blue-500 text-white p-2 rounded-md mb-6'
              disabled={loading}
            >
              {loading ? "Adding..." : "Add Customer"}
            button>
          form>

          <CustomersTable customers={customers} />
        div>
      main>
    div>
  );
}

The code snippet above allows users to view, create, and delete customers from the application.

Invoice-app-customer-page

Dashboard Page

Create a dashboard folder containing a page.tsx within the Next.js app directory and copy the code snippet below into the file:

"use client";
import InvoiceTable from "@/app/components/InvoiceTable";
import React, { useState, useEffect, useCallback } from "react";
import { useRouter } from "next/navigation";
import SideNav from "@/app/components/SideNav";

export default function Dashboard() {
  const { isLoaded, isSignedIn, user } = useUser();
  const [itemList, setItemList] = useState([]);
  const [customer, setCustomer] = useState("");
  const [invoiceTitle, setInvoiceTitle] = useState("");
  const [itemCost, setItemCost] = useState(1);
  const [itemQuantity, setItemQuantity] = useState(1);
  const [itemName, setItemName] = useState("");
  const [customers, setCustomers] = useState([]);
  const router = useRouter();

  const handleAddItem = (e: React.FormEvent) => {
    e.preventDefault();
    if (itemName.trim() && itemCost > 0 && itemQuantity >= 1) {
      setItemList([
        ...itemList,
        {
          id: Math.random().toString(36).substring(2, 9),
          name: itemName,
          cost: itemCost,
          quantity: itemQuantity,
          price: itemCost * itemQuantity,
        },
      ]);
    }

    setItemName("");
    setItemCost(0);
    setItemQuantity(0);
  };

  const getTotalAmount = () => {
    let total = 0;
    itemList.forEach((item) => {
      total += item.price;
    });
    return total;
  };

  const handleFormSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    //👉🏻 createInvoice();
  };

  return (
    <div className='w-full'>
      <main className='min-h-[90vh] flex items-start'>
        <SideNav />
        <div className='md:w-5/6 w-full h-full p-6'>
          <h2 className='font-bold text-2xl mb-3'>Add new invoiceh2>

          <form className='w-full flex flex-col' onSubmit={handleFormSubmit}>
            <label htmlFor='customer'>Customerlabel>
            <select
              className='border-[1px] p-2 rounded-sm mb-3'
              required
              value={customer}
              onChange={(e) => setCustomer(e.target.value)}
            >
              {customers.map((customer: any) => (
                <option key={customer.id} value={customer.name}>
                  {customer.name}
                option>
              ))}
            select>

            <label htmlFor='title'>Titlelabel>
            <input
              className='border-[1px] rounded-sm mb-3 py-2 px-3'
              required
              value={invoiceTitle}
              onChange={(e) => setInvoiceTitle(e.target.value)}
            />

            <div className='w-full flex justify-between flex-col'>
              <h3 className='my-4 font-bold'>Items Listh3>

              <div className='flex space-x-3'>
                <div className='flex flex-col w-1/4'>
                  <label htmlFor='itemName' className='text-sm'>
                    Name
                  label>
                  <input
                    type='text'
                    name='itemName'
                    placeholder='Name'
                    className='py-2 px-4 mb-6 bg-gray-100'
                    value={itemName}
                    onChange={(e) => setItemName(e.target.value)}
                  />
                div>

                <div className='flex flex-col w-1/4'>
                  <label htmlFor='itemCost' className='text-sm'>
                    Cost
                  label>
                  <input
                    type='number'
                    name='itemCost'
                    placeholder='Cost'
                    className='py-2 px-4 mb-6 bg-gray-100'
                    value={itemCost}
                    onChange={(e) => setItemCost(Number(e.target.value))}
                  />
                div>

                <div className='flex flex-col justify-center w-1/4'>
                  <label htmlFor='itemQuantity' className='text-sm'>
                    Quantity
                  label>
                  <input
                    type='number'
                    name='itemQuantity'
                    placeholder='Quantity'
                    className='py-2 px-4 mb-6 bg-gray-100'
                    value={itemQuantity}
                    onChange={(e) => setItemQuantity(Number(e.target.value))}
                  />
                div>

                <div className='flex flex-col justify-center w-1/4'>
                  <p className='text-sm'>Pricep>
                  <p className='py-2 px-4 mb-6 bg-gray-100'>
                    {Number(itemCost * itemQuantity).toLocaleString("en-US")}
                  p>
                div>
              div>
              <button
                className='bg-blue-500 text-gray-100 w-[100px] p-2 rounded'
                onClick={handleAddItem}
              >
                Add Item
              button>
            div>

            <InvoiceTable itemList={itemList} />
            <button
              className='bg-blue-800 text-gray-100 w-full p-4 rounded my-6'
              type='submit'
            >
              SAVE & PREVIEW INVOICE
            button>
          form>
        div>
      main>
    div>
  );
}

The code snippet above displays a form that accepts the invoice details, such as the customer’s name, invoice title, and items list needed to create an invoice.

Invoice-app-dashboard

History Page

Create a history folder containing a page.tsx file within the Next.js app directory and copy the following code into the file:

"use client";
import { useState, useEffect, useCallback } from "react";
import Link from "next/link";
import SideNav from "@/app/components/SideNav";

export default function History() {
  const { isLoaded, isSignedIn, user } = useUser();
  const [invoices, setInvoices] = useState([]);

  return (
    <div className='w-full'>
      <main className='min-h-[90vh] flex items-start'>
        <SideNav />
        <div className='md:w-5/6 w-full h-full p-6'>
          <h2 className='text-2xl font-bold'>Historyh2>
          <p className='opacity-70 mb-4'>View all your invoices and their statusp>

          {invoices.map((invoice) => (
            <div
              className='bg-blue-50 w-full mb-3 rounded-md p-3 flex items-center justify-between'
              key={invoice.id}
            >
              <div>
                <p className='text-sm text-gray-500 mb-2'>
                  Invoice - #0{invoice.id} issued to{" "}
                  <span className='font-bold'>{invoice.customer_id}span>
                p>
                <h3 className='text-lg font-bold mb-[1px]'>
                  {Number(invoice.total_amount).toLocaleString()}
                h3>
              div>
              <Link
                href={{
                  pathname: `/invoices/${invoice.id}`,
                  query: { customer: invoice.customer_id },
                }}
                className='bg-blue-500 text-blue-50 rounded p-3'
              >
                Preview
              Link>
            div>
          ))}
        div>
      main>
    div>
  );
}

The code snippet above displays the recently created invoices and enables users to preview them when needed.

Invoice-app-history-page

How to Authenticate Users Using Clerk

Clerk is a complete user management platform that enables you to add various forms of authentication to your software applications. It provides easy-to-use, flexible UI components and APIs that can be integrated seamlessly into your application.

Install the Clerk Next.js SDK by running the following code snippet in your terminal:

npm install @clerk/nextjs

Create a middleware.ts file within the Next.js src folder and copy the code snippet below into the file:

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

// the createRouteMatcher function accepts an array of routes to be protected
const protectedRoutes = createRouteMatcher([
    "/customers",
    "/settings",
    "/dashboard",
    "/history",
    "/invoices(.*)",
]);

// protects the route
export default clerkMiddleware((auth, req) => {
    if (protectedRoutes(req)) {
        auth().protect();
 }
});

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

The createRouteMatcher() function accepts an array containing routes to be protected from unauthenticated users, and the clerkMiddleware() function ensures the routes are protected.

Next, import the following Clerk components into the app/layout.tsx file and update the RootLayout function as shown below:

import {
    ClerkProvider,
    SignInButton,
    SignedIn,
    SignedOut,
    UserButton,
} from "@clerk/nextjs";
import Link from "next/link";

export default function RootLayout({
    children,
}: Readonly<{
    children: React.ReactNode;
}>) {
    return (
 <ClerkProvider>
 <html lang='en'>
 <body className={inter.className}>
 <nav className='flex justify-between items-center h-[10vh] px-8 border-b-[1px]'>
 <Link href='/' className='text-xl font-extrabold text-blue-700'>
 Invoicer
 Link>
 <div className='flex items-center gap-5'>
                            {/*-- if user is signed out --*/}
 <SignedOut>
 <SignInButton mode='modal' />
 SignedOut>
                            {/*-- if user is signed in --*/}
 <SignedIn>
 <Link href='/dashboard' className=''>
 Dashboard
 Link>
 <UserButton showName />
 SignedIn>
 div>
 nav>

                    {children}
 body>
 html>
 ClerkProvider>
 );
}

When a user is not signed in, the Sign in button component is rendered.

Clerk-Auth-Signup-Page

Then, after signing into the application, Clerk's User Button component and a link to the dashboard are displayed.

Next, create a Clerk account and add a new application project.

Clerk-Auth-Project-Page

Select email as the authentication method and create the Clerk project.

Finally, add your Clerk publishable and secret keys into the .env.local file.

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=
CLERK_SECRET_KEY=

Clerk provides various ways to read user's data on the client and the server, which is essential for identifying users within the application.

How to Add Neon to a Next.js app

Neon supports multiple frameworks and libraries and provides clear and detailed documentation on adding Neon to them. The Neon serverless driver lets you connect to and interact with Neon in a Next.js application.

Before we proceed, let’s create a Neon account and project.

Neon-postgres-all-project-dashboard

Within your project dashboard, you'll find a database connection string. You'll use this to interact with your Neon database.

Neon-project-dashboard

Next, install the Neon Serverless package into the Next.js project:

npm install @neondatabase/serverless

Copy your database connection string into the .env.local file.

NEON_DATABASE_URL="postgres://:@.neon.tech:/?sslmode=require"

Create a db folder containing an index.ts file within the Next.js app directory and copy the code snippet below into the file:

import { neon } from '@neondatabase/serverless';

if (!process.env.NEON_DATABASE_URL) {
  throw new Error('NEON_DATABASE_URL must be a Neon postgres connection string')
}

export const getDBVersion = async() => {
    const sql = neon(process.env.NEON_DATABASE_URL!);
    const response = await sql`SELECT version()`;
    return { version: response[0].version }
}

Convert the app/page.tsx file to a server component and execute the getDBVersion() function:

import { getDBVersion } from "./db";

export default async function Home() {
    const { version } = await getDBVersion();
    console.log({version})

   return (<div>{/** -- UI elements -- */}div>)

}

The getDBVersion() function establishes a connection with the Neon database and allows us to run SQL queries using the Postgres client. This function returns the database version, which is then logged to the console.

{
version: 'PostgreSQL 16.3 on x86_64-pc-linux-gnu, compiled by gcc (Debian 10.2.1-6) 10.2.1 20210110, 64-bit'
}

Congratulations – you’ve successfully added Neon to your Next.js app.

However, interacting with the Neon database by writing SQL queries directly can require extra learning or introduce complexities for developers who are not familiar with SQL. It can also lead to errors or performance issues when performing complex queries.

This is why Neon supports database ORMs such as Drizzle ORM, which provide a higher-level interface for interacting with the database. Drizzle ORM enables you to write complex query functions and interact with the database easily using TypeScript.

How to Set Up Neon Serverless Driver with Drizzle ORM in Next.js

Drizzle ORM lets you query data and perform various operations on the database using simple TypeScript query commands. It is lightweight, typesafe, and easy to use.

First, you'll need to install the Drizzle Kit and the Drizzle ORM package.

Drizzle Kit lets you manage the database schema and migrations.

npm i drizzle-orm
npm i -D drizzle-kit

Inside the db folder, add an actions.ts, and schema.ts file:

cd db
touch actions.ts schema.ts

The actions.ts file will contain the required database queries and operations, while the schema.ts file will define the database schema for the invoicing application.

Database Design for the invoice application

Recall that users can add customers, update their bank information, and create invoices within the application. So you need to create database tables for the data in Neon.

The user's ID will be used as a foreign key to identify each row of data that belongs to a specific user.

Copy the code snippet below into the db/schema.ts file:

import {  text, serial, pgTable, timestamp, numeric } from "drizzle-orm/pg-core";

//👇🏻 invoice table with its column types
export const invoicesTable = pgTable("invoices", {
    id: serial("id").primaryKey().notNull(),
    owner_id: text("owner_id").notNull(),
    customer_id: text("customer_id").notNull(),
    title: text("title").notNull(),
    items: text("items").notNull(),
    created_at: timestamp("created_at").defaultNow(),
    total_amount: numeric("total_amount").notNull(),
});

//👇🏻 customers table with its column types
export const customersTable = pgTable("customers", {
    id: serial("id").primaryKey().notNull(),
    created_at: timestamp("created_at").defaultNow(),
    owner_id: text("owner_id").notNull(),
    name: text("name").notNull(),
    email: text("email").notNull(),
    address: text("address").notNull(),
})

//👇🏻 bank_info table with its column types
export const bankInfoTable = pgTable("bank_info", {
    id: serial("id").primaryKey().notNull(),
    owner_id: text("owner_id").notNull().unique(),
    bank_name: text("bank_name").notNull(),
    account_number: numeric("account_number").notNull(),
    account_name: text("account_name").notNull(),
    created_at: timestamp("created_at").defaultNow(),
    currency: text("currency").notNull(),
})

The actions.ts file will contain the various database operations required within the application. First, add the code snippet below to the file:

import { invoicesDB, customersDB, bankInfoDB } from ".";
import { invoicesTable, customersTable, bankInfoTable } from './schema';
import { desc, eq } from "drizzle-orm";

//👇🏻 add a new row to the invoices table
export const createInvoice = async (invoice: any) => {
    await invoicesDB.insert(invoicesTable).values({
    owner_id: invoice.user_id,
    customer_id: invoice.customer_id,
    title: invoice.title,
    items: invoice.items,
    total_amount: invoice.total_amount,
 });
};

//👇🏻 get all user's invoices
export const getUserInvoices = async (user_id: string) => {
    return await invoicesDB.select().from(invoicesTable).where(eq(invoicesTable.owner_id, user_id)).orderBy(desc(invoicesTable.created_at));
};

//👇🏻 get single invoice
export const getSingleInvoice = async (id: number) => {
    return await invoicesDB.select().from(invoicesTable).where(eq(invoicesTable.id, id));
};

The createInvoice function accepts invoice details as a parameter and adds a new row of data to its invoice table. The getUserInvoices function filters the table and returns an array of invoices created by the user. The getSingleInvoice function accepts an invoice ID, filters the table, and returns the invoice with a matching ID.

Add the following functions to the db/actions file:

//👇🏻 get customers list
export const getCustomers = async (user_id: string) => {
    return await customersDB.select().from(customersTable).where(eq(customersTable.owner_id, user_id)).orderBy(desc(customersTable.created_at));
};

//👇🏻 get single customer
export const getSingleCustomer = async (name: string) => {
    return await customersDB.select().from(customersTable).where(eq(customersTable.name, name));
};

//👇🏻 add a new row to the customers table
export const addCustomer = async (customer: Customer) => {
    await customersDB.insert(customersTable).values({
        owner_id: customer.user_id,
        name: customer.name,
        email: customer.email,
        address: customer.address,
 });
};

//👇🏻 delete a customer
export const deleteCustomer = async (id: number) => {
  await customersDB.delete(customersTable).where(eq(customersTable.id, id));
};

This code snippet enables users to retrieve all their customers from the database, get a single customer via its ID, add new customers, and delete customers from the customers table.

Finally, add this also to the db/actions.ts file:

//👇🏻 get user's bank info
export const getUserBankInfo = async (user_id: string) => {
    return await bankInfoDB.select().from(bankInfoTable).where(eq(bankInfoTable.owner_id, user_id));
};

//👇🏻 update bank info table
export const updateBankInfo = async (info: any) => {
await bankInfoDB.insert(bankInfoTable)
 .values({
        owner_id: info.user_id,
        bank_name: info.bank_name,
        account_number: info.account_number,
        account_name: info.account_name,
        currency: info.currency,
 })
 .onConflictDoUpdate({
            target: bankInfoTable.owner_id,
            set: {
                bank_name: info.bank_name,
                account_number: info.account_number,
                account_name: info.account_name,
                currency: info.currency,
 },
 });
};

The getUserBankInfo function fetches the user’s bank information from the database, while the updateBankInfo function updates it. If the user already has one, the function updates it with the new details – otherwise, it creates a new entry.

Next, update the db/index.ts file to connect to the Neon database and export the Drizzle instance for each table. This will be used to execute typesafe SQL queries against your Postgres database hosted on Neon.

import { neon } from '@neondatabase/serverless';
import { drizzle } from 'drizzle-orm/neon-http';
import { invoicesTable, customersTable, bankInfoTable } from './schema';

if (!process.env.NEON_DATABASE_URL) {
  throw new Error('DATABASE_URL must be a Neon postgres connection string')
}
const sql = neon(process.env.NEON_DATABASE_URL!);


export const invoicesDB = drizzle(sql, {
  schema: { invoicesTable }
});

export const customersDB = drizzle(sql, {
  schema: { customersTable }
});

export const bankInfoDB = drizzle(sql, {
  schema: { bankInfoTable }
});

Create a drizzle.config.ts file at the root of the Next.js folder and add the following configuration. Ensure you install the Dotenv package.

import type { Config } from "drizzle-kit";
import * as dotenv from "dotenv";

dotenv.config();

if (!process.env.NEON_DATABASE_URL)
    throw new Error("NEON DATABASE_URL not found in environment");

export default {
    schema: "./src/app/db/schema.ts",
    out: "./src/app/db/migrations",
    dialect: "postgresql",
    dbCredentials: {
        url: process.env.NEON_DATABASE_URL,
 },
    strict: true,
} satisfies Config;

The drizzle.config.ts file contains all the information about your database connection, migration folder, and schema files.

Finally, update the package.json file to include the Drizzle Kit commands for generating database migrations and creating the tables.

{
"scripts" : {
"migrate": "npx drizzle-kit generate -- dotenv_config_path='.env.local'",
"db-create": "npx drizzle-kit push -- dotenv_config_path='.env.local'"
}
}

You can now run npm run db-create to push the database tables to the Neon console.

Neon-tables-dashboard

Creating the API Endpoints for the Application

In the previous section, you created the necessary functions to interact with the database. In this section, you will learn how to create the API endpoints for each database operation.

First, create an api folder within the Next.js app directory. It will contain all the API routes for the application.

cd app
mkdir api

Add a bank-info folder containing a route.ts within the api folder. This means that the API route (/api/bank-info) will handle updating and fetching the user’s bank information.

cd api
mkdir bank-info && cd bank-info
touch route.ts

Copy the code snippet below into the /bank-info/route.ts file. The POST request method updates the user’s bank information and returns a response and the GET request method retrieves the bank information from the database using the user’s ID.

import { updateBankInfo, getUserBankInfo } from "@/app/db/actions";
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
    const { accountName, userID, accountNumber, bankName, currency } = await req.json();
    try {
        await updateBankInfo({
            user_id: userID,
            bank_name: bankName,
            account_number: Number(accountNumber),
            account_name: accountName,
            currency: currency,
 });
        return NextResponse.json({ message: "Bank Details Updated!" }, { status: 201 });
 } catch (err) {
        return NextResponse.json(
 { message: "An error occurred", err },
 { status: 400 }
 );
 }
}

export async function GET(req: NextRequest) {
   const userID  = req.nextUrl.searchParams.get("userID");

    try {
        const bankInfo = await getUserBankInfo(userID!);
        return NextResponse.json({ message: "Fetched bank details", bankInfo }, { status: 200 });
 } catch (err) {
        return NextResponse.json(
 { message: "An error occurred", err },
 { status: 400 }
 );
 }
}

Next, add an invoice folder containing a route.ts file to the api directory. Copy the code snippet below into the /api/invoice/route.ts file:

import { createInvoice, getUserInvoices } from "@/app/db/actions";
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
    const { customer, title, items, total, ownerID } = await req.json();

    try {
        await createInvoice({
            user_id: ownerID,
            customer_id: customer,
            title,
            total_amount: total,
            items: JSON.stringify(items),
 })
        return NextResponse.json(
 { message: "New Invoice Created!" },
 { status: 201 }
 );
 } catch (err) {
        return NextResponse.json(
 { message: "An error occurred", err },
 { status: 400 }
 );
 }
}

export async function GET(req: NextRequest) {
    const userID = req.nextUrl.searchParams.get("userID");

    try {
        const invoices = await getUserInvoices(userID!);
        return NextResponse.json({message: "Invoices retrieved successfully!", invoices}, { status: 200 });
 } catch (err) {
        return NextResponse.json(
 { message: "An error occurred", err },
 { status: 400 }
 );
 }
}

The POST request method creates a new invoice and the GET request method returns all the user’s invoices from the database.

You can also create a sub-folder named single within the /api/invoices folder, and add a route.ts file within it.

import { NextRequest, NextResponse } from "next/server";
import { getSingleInvoice } from "@/app/db/actions";

export async function GET(req: NextRequest) {
   const invoiceID = req.nextUrl.searchParams.get("id");

    try {
        const invoice = await getSingleInvoice(invoiceID);
        return NextResponse.json({ message: "Inovice retrieved successfully!", invoice }, { status: 200 });
 } catch (err) {
        return NextResponse.json(
 { message: "An error occurred", err },
 { status: 400 }
 );
 }
}

The code snippet above accepts an invoice ID and retrieves all its data available within the database table. You can do the same with the customers table as well.

Congratulations! You’ve learned how to create, store, and retrieve data from the Neon Postgres database. In the upcoming sections, you’ll uncover how to print and send invoices to customers.

How to Print and Download Invoices in Next.js

The React-to-print package is a simple JavaScript library that allows you to print the contents of a React component easily without tampering with the component's CSS styles. It converts React components exactly as they are into downloadable PDF files.

First, execute the following code snippet in your terminal to install the package:

npm install -save react-to-print

Create a client page (/invoice/[id].tsx).

To do this, add an invoice folder containing a [id] sub-folder to the Next.js app directory. Inside the [id] folder, add a page.tsx file. This page displays all the information about an invoice and allows users to print, download, and send invoices to customers.

Invoice-app-download-page-ui

Create a invoice design similar to the image above by copying the code snippet below into the page.tsx file:

const ComponentToPrint = forwardRef((props, ref) => {
  const { id, customer, invoice, bankInfo } = props as Props;

  return (
    <div className='w-full px-2 py-8' ref={ref}>
      <div className='lg:w-2/3 w-full mx-auto shadow-md border-[1px] rounded min-h-[75vh] p-5'>
        <header className='w-full flex items-center space-x-4 justify-between'>
          <div className='w-4/5'>
            <h2 className='text-lg font-semibold mb-3'>INVOICE #0{id}h2>
            <section className='mb-6'>
              <p className='opacity-60'>Issuer Name: {bankInfo?.account_name}p>
              <p className='opacity-60'>Date: {formatDateString(invoice?.created_at!)}p>
            section>
            <h2 className='text-lg font-semibold mb-2'>TO:h2>
            <section className='mb-6'>
              <p className='opacity-60'>Name: {invoice?.customer_id}p>
              <p className='opacity-60'>Address: {customer?.address}p>
              <p className='opacity-60'>Email: {customer?.email}p>
            section>
          div>

          <div className='w-1/5 flex flex-col'>
            <p className='font-extrabold text-2xl'>
              {`${bankInfo?.currency}${Number(invoice?.total_amount).toLocaleString()}`}
            p>
            <p className='text-sm opacity-60'>Total Amountp>
          div>
        header>
        <div>
          <p className='opacity-60'>Subject:p>
          <h2 className='text-lg font-semibold'>{invoice?.title}h2>
        div>

        <InvoiceTable itemList={invoice?.items ? JSON.parse(invoice.items) : []} />
      div>
    div>
  );
});

ComponentToPrint.displayName = "ComponentToPrint";

The code snippet accepts invoice details, including the customer and user’s bank information and renders them within the component.

Finally, you need to wrap this component with another parent one and instruct React-to-print to print the sub-component. Add the following code snippet below the ComponentToPrint component.

import { useReactToPrint } from "react-to-print";

export default function Invoices() {
  const { id } = useParams<{ id: string }>();
  // Reference to the component to be printed
  const componentRef = useRef();

  // States for the data
  const [customer, setCustomer] = useState();
  const [bankInfo, setBankInfo] = useState();
  const [invoice, setInvoice] = useState();

  // Function that sends invoice via email
  const handleSendInvoice = async () => {};

  // Function that prints the invoice
  const handlePrint = useReactToPrint({
    documentTitle: "Invoice",
    content: () => componentRef.current,
  });

  return (
    <main className='w-full min-h-screen'>
      <section className='w-full flex p-4 items-center justify-center space-x-5 mb-3'>
        <button
          className='p-3 text-blue-50 bg-blue-500 rounded-md'
          onClick={handlePrint}
        >
          Download
        button>
        <button
          className='p-3 text-blue-50 bg-green-500 rounded-md'
          onClick={() => {
            handleSendInvoice();
          }}
        >
          Send Invoice
        button>
      section>

      <ComponentToPrint
        ref={componentRef}
        id={id}
        customer={customer}
        bankInfo={bankInfo}
        invoice={invoice}
      />
    main>
  );
}

The component renders the ComponentToPrint component, creates a reference to it, and prints it using the useReactToPrint hook.

Invoice-app-print-ui

How to Send Digital Invoices with Resend and React Email

Resend is an API service that enables us to send and manage emails programmatically, making it easy to integrate email functionality into software applications.

React Email is a library that allows us to create reusable, beautifully designed email templates using React components. Both packages are created by the person, allowing for smooth integration between the two services.

Install both packages by running the code snippet below:

npm install resend
npm install react-email @react-email/components -E

Configure React Email by including the following script in your package.json file.

The --dir flag gives React Email access to the email templates located within the project. In this case, the email templates are located in the src/app/emails folder.

{
"scripts": {
"email": "email dev --dir src/app/emails"
}
}

Next, create the emails folder containing the email template to be sent to the customers’ email:

import { Heading, Hr, Text } from "@react-email/components";

export default function EmailTemplate({
    invoiceID,
    items,
    amount,
    issuerName,
    accountNumber,
    currency,
}: Props) {
    return (
 <div>
 <Heading as='h2' style={{ color: "#0ea5e9" }}>
 Purhcase Invoice from {issuerName}
 Heading>
 <Text style={{ marginBottom: 5 }}>Invoice No: INV0{invoiceID}Text>
 <Heading as='h3'> Payment Details:Heading>
 <Text>Account Details: {issuerName}Text>
 <Text>Account Number: {accountNumber}Text>
 <Text>Total Amount: {`${currency}${amount}`}Text>
 <Hr />
 <Heading as='h3'> Items: Heading>
            {items &&
                items.map((item, index) => (
 <div key={index}>
 <Text>
                            {item.cost} x {item.quantity} = {item.price}
 Text>
 div>
 ))}
 div>
 );
}

The email template accepts all the invoice details as props and sends a dynamic email template to the user. You can also preview the invoice layout by running npm run email within your terminal.

Next, create a Resend account, and select API Keys from the sidebar menu on your dashboard to create one.

resend-api-keys-dashboard

Copy the API key into the .env.local file.

Finally, create an API endpoint that accepts the invoice details from the frontend and sends an invoice containing the data to a customer.

import { NextRequest, NextResponse } from "next/server";
import EmailTemplate from "@/app/emails/email";
import { Resend } from "resend";
const resend = new Resend(process.env.RESEND_API_KEY!);

export async function POST(req: NextRequest) {
    const {
        invoiceID,
        items,
        title,
        amount,
        customerEmail,
        issuerName,
        accountNumber,
        currency,
 } = await req.json();

    try {
        const { data, error } = await resend.emails.send({
            from: "Acme ",
            to: [customerEmail],
            subject: title,
            react: EmailTemplate({
                invoiceID,
                items: JSON.parse(items),
                amount: Number(amount),
                issuerName,
                accountNumber,
                currency,
 }) as React.ReactElement,
 });

        if (error) {
            return Response.json(
 { message: "Email not sent!", error },
 { status: 500 }
 );
 }

        return NextResponse.json({ message: "Email delivered!" }, { status: 200 });
 } catch (error) {
        return NextResponse.json(
 { message: "Email not sent!", error },
 { status: 500 }
 );
 }
}

The code snippet above accepts invoice details from the frontend, passes the required data into the email template, and sends an email to the user.

Next Steps

Congratulations. By now, you should have a good understanding of how to build full-stack applications with Clerk, Resend, Neon Postgres and Next.js.

If you'd like to learn more about how you can leverage Neon Postgres to build advanced and scalable apps, you can check out the following resources:

Thank you for reading

If you found this article useful, you can:

Subscribe to my newsletter.
Follow me on Twitter where I post about my business and writing journey, side projects, and current learnings.
Checkout my blog for more tutorials like this on developer tools.

Full Stack Development with Next.js, Clerk, and Neon Postgres

Ankur Tyagi — Wed, 10 Jul 2024 15:31:12 +0000

Full stack development is constantly evolving, with new developer tools and products being introduced that allow us to build secure and reliable applications more efficiently.

In this tutorial, I’ll walk you through how to build highly performant web applications with Neon – a serverless PostgreSQL database designed for the cloud. You'll also learn how to perform CRUD (Create, Read, Update, and Delete) operations with Neon.

By the end of this tutorial, you will have the basic knowledge required to start building advanced and scalable web applications with Neon.

What is Neon?

This architecture allows for greater scalability and performance, making Neon a solid choice for modern web applications.

Neon - a serverless Postgres database

3 Things to Remember About Neon:

🐘 Postgres: Neon is built on the foundation of Postgres. It supports the same extensions, drivers, and SQL syntax as Postgres, ensuring familiarity and ease of use.
☁️ Serverless: Neon operates on a serverless model. Your database is represented as a simple URL, and Neon automatically scales up and down based on workload demands. Say goodbye to over-provisioning.
🌱 Branching: Just like version control for code, Neon allows you to create instant, isolated copies of your data. This feature is invaluable for development, testing, and maintaining separate environments.

Why Neon?

Neon brings the serverless experience to Postgres. Developers can build faster and scale their products effortlessly, without the need to dedicate big teams or big budgets to the database.

Neon supports multiple languages and frameworks – but what are the unique features that make Neon stand out?

Instant branching and auto-scaling

Neon allows you to create database branches instantly for testing, development, and staging environments. This lets you experiment without affecting the production database.

It also provides an auto-scaling capability that automatically adjusts resources based on the application's workload, ensuring optimal performance and cost-efficiency.

Neon DB Main Dashboard

Support for AI applications

Neon supports AI and machine learning applications by providing a high-performance and scalable infrastructure. It enables you to perform semantic and similarity searches in Postgres and handles complex queries and large datasets efficiently, making it ideal for AI or LLM applications.

Open-source

Neon is backed by a vibrant community of Postgres hackers, systems engineers, and cloud engineers who are all huge fans of Postgres.

As an open-source platform, Neon offers transparency and flexibility. You can also reach out to the team and contributors to ask questions, contribute, and help improve the software.

Serverless Architecture

Neon eliminates the need for manual server management, allowing you to focus on building applications rather than maintaining infrastructure. Its serverless nature provides on-demand scalability, ensuring that your application can handle varying loads without manual intervention.

Built upon Postgres

Postgres is one of the most reliable open-source relational database systems. Neon inherits all the advanced features, stability, and performance optimizations of Postgres, including support for ACID transactions, advanced SQL, and NoSQL/JSON, to create a cheaper and more efficient database for cloud environments.

How to Add Neon to a Next.js App

Neon supports multiple frameworks and libraries and provides clear and detailed documentation on adding Neon to them. The Neon serverless driver enables us to connect and interact with Neon in a Next.js application.

Before we proceed, let’s create a Neon account and project.

Neon DB Projects Overview: View and manage all your projects in one place.

Within your project dashboard, you'll find a database connection string. You'll use this to interact with your Neon database.

Neon DB Project Dashboard: Manage database settings with ease from the project dashboard.

Create a TypeScript Next.js project by running the following code snippet in your terminal:

npx create-next-app neon-blog-with-clerk

Next, install the Neon Serverless package:

npm install @neondatabase/serverless

Create a .env.local file and copy your database connection string into the file:

NEON_DATABASE_URL="postgres://:@.neon.tech:/?sslmode=require"

Create a 'db' folder containing an index.ts file within the Next.js app directory and copy the code snippet below into the file:

import { neon } from '@neondatabase/serverless';

if (!process.env.NEON_DATABASE_URL) {
  throw new Error('NEON_DATABASE_URL must be a Neon postgres connection string')
}

export const getDBVersion = async() => {
    const sql = neon(process.env.NEON_DATABASE_URL!);
    const response = await sql`SELECT version()`;
    return { version: response[0].version }
}

Convert the app/page.tsx file to a server component and execute the getDBVersion() function:

import { getDBVersion } from "./db";

export default async function Home() {
    const { version } = await getDBVersion();
    console.log({version})

   return (<div>{/** — UI elements — */}div>)

}

The getDBVersion() function establishes a connection with the Neon database and allows us to run SQL queries using the Postgres client. This function returns the database version, which is then logged to the console.

{
version: 'PostgreSQL 16.3 on x86_64-pc-linux-gnu, compiled by gcc (Debian 10.2.1-6) 10.2.1 20210110, 64-bit'
}

Congratulations – you’ve successfully added Neon to your Next.js application.

But interacting with the Neon database by writing SQL queries directly can require extra learning or introduce complexities for developers who are not familiar with SQL. It can also lead to errors or performance issues when performing complex queries.

How to Set Up Neon Serverless Driver with Drizzle ORM in Next.js

Drizzle ORM lets you query data and perform various operations on the database using simple TypeScript query commands. It is lightweight, typesafe, and easy to use.

First, you'll need to install the Drizzle Kit and the Drizzle ORM package.

Drizzle Kit lets you manage the database schema and migrations.

npm i drizzle-orm
npm i -D drizzle-kit

Inside the db folder, add an actions.ts, and schema.ts file:

cd db
touch actions.ts schema.ts

Add the code snippet below into the db/schema.ts file. It contains the database schema.

import {  text, serial, pgTable, timestamp } from "drizzle-orm/pg-core";

export const postsTable = pgTable("posts", {
    id: serial("id").primaryKey().notNull(),
    content: text("content").notNull(),
    author: text("author").notNull(),
    author_id: text("author_id").notNull(),
    title: text("title").notNull(),
    created_at: timestamp("created_at").defaultNow(),
    slug: text("slug").notNull(),
});

Update the db/index.ts file to connect to the Neon database and export the Drizzle instance (db). This will be used to execute typesafe SQL queries against your Postgres database hosted by Neon.

import { neon } from '@neondatabase/serverless';
import { drizzle } from 'drizzle-orm/neon-http';
import { postsTable } from './schema';


if (!process.env.NEON_DATABASE_URL) {
  throw new Error('DATABASE_URL must be a Neon postgres connection string')
}
const sql = neon(process.env.NEON_DATABASE_URL!);

export const db = drizzle(sql, {
  schema: { postsTable }
});

Next, create a drizzle.config.ts file at the root of the Next.js folder and add the following configuration:

import type { Config } from 'drizzle-kit';
import * as dotenv from "dotenv";

dotenv.config();

if (!process.env.NEON_DATABASE_URL) throw new Error('NEON DATABASE_URL not found in environment');

export default {
  schema: './src/app/db/schema.ts',
  out: './src/app/db/migrations',
 dialect: "postgresql",
  dbCredentials: {
    url: process.env.NEON_DATABASE_URL,
 },
  strict: true,
} satisfies Config;

The drizzle.config.ts file contains all the information about your database connection, migration folder, and schema files.

Finally, update the package.json file to include the Drizzle Kit commands for generating database migrations and updating the tables.

{
"scripts" : {
"migrate": "npx drizzle-kit generate -- dotenv_config_path='.env.local'",
"db-create": "npx drizzle-kit push -- dotenv_config_path='.env.local'"
}
}

Neon DB Tables Dashboard: Effortlessly manage your database tables and view all data.

How to Build the Application Interface with Next.js

In this section, you’ll learn how to build a blog application that allows users to read posts and authenticate authors, enabling them to create and delete posts from the Neon database.

The application is divided into 3 pages:

Home Page: displays all the available blog posts.
Post Details Page (/posts/[slug]): displays the content of a particular blog post.
Create Post Page (/posts/create): allows authors to create new blog posts.

Install the following packages:

npm install date-fns react-simplemde-editor easymde react-markdown remark-gfm dotenv

The Date Fns package allows us to convert the posts' timestamps to human-readable forms for display within the application. The React SimpleMDE Editor provides a WYSIWYG editor for creating content in markdown formats using an interactive editor, and the React Markdown package converts the markdown texts to their corresponding plain formats.

Next, create a utils.ts file within the Next.js app folder and copy the code snippet below into the file:

import { format } from "date-fns";

export const formatDateString = (dateString: Date | null): string => {
    if (!dateString) return "";
    const date = new Date(dateString);
    const formattedDate = format(date, "MMMM do yyyy, h:mma");
    return formattedDate;
};

export const slugifySentences = (sentence: string): string => {
    const slug = sentence
 .toLowerCase()
 .replace(/[^a-z0-9\s-]/g, "")
 .replace(/\s+/g, "-");

    // Generate 5 random letters
    const randomLetters = Array.from({ length: 5 }, () =>
        String.fromCharCode(97 + Math.floor(Math.random() * 26))
 ).join("");

    return `${slug}-${randomLetters}`;
};

The formatDateString function accepts a Date object and returns the date and time in a human-readable format using the date-fns package. The slugifySentences function creates a slug for each post using the post's title, which is useful for implementing the routes for each post.

Copy the code snippet below into the app/page.tsx file:

import Link from "next/link";
import { formatDateString, slugifySentences } from "./utils";

interface Post {
    author_id: string;
    title: string;
    content: string;
    author: string;
    slug: string;
    id: number | null;
    created_at: Date | null;
}

export default async function Home() {
    // dummy posts
    const posts: Post[] = [
        {
            author_id: "1",
            title: "Welcome to Neon Tutorial",
            content: "This is a test post",
            author: "John Doe",
            slug: slugifySentences("Welcome to Neon Tutorial"),
            id: 1,
            created_at: new Date(),
        },
        {
            author_id: "1",
            title: "Hello World",
            content: "This is a test post",
            author: "Jane Doe",
            slug: slugifySentences("Hello World"),
            id: 2,
            created_at: new Date(),
        },
    ];

    // shorten posts with longer title
    const shortenText = (text: string): string => {
        return text.length <= 55 ? text : text.slice(0, 55) + "...";
    };

    return (
        <div>
            <main className='md:px-8 py-8 px-4 w-full bg-white'>
                {posts?.map((post) => (
                    <Link
                        href={`/posts/${post.slug}`}
                        className='rounded w-full border-[1px] p-4 text-blue-500 hover:bg-blue-50 hover:drop-shadow-md transition-all duration-200 ease-in-out flex items-center justify-between gap-4 mb-4'
                        key={post.id}
                    >
                        <h3 className='text-lg font-semibold'>{shortenText(post.title)}h3>
                        <div className='flex items-center justify-between'>
                            <p className='text-xs text-gray-500'>
                                {formatDateString(post?.created_at)}
                            p>
                        div>
                    Link>
                ))}
            main>
        div>
    );
}

The app/page.tsx file represents the home page of the application and displays all the available posts.

It's live - see the power of serverless PostgreSQL and Next.js

Next, add the routes for creating posts and reading the contents of each post. Within the Next.js app folder, create a posts directory containing /posts/create and /posts/[slug] subdirectories.

Create a page.tsx file within the /posts/create folder and copy the code snippet below into the file:

use client";
import { useState, useCallback } from "react";
import { useRouter } from "next/navigation";
import SimpleMDE from "react-simplemde-editor";
import "easymde/dist/easymde.min.css";
import { slugifySentences } from "@/app/utils";

export default function PostCreate() {
    const [publishing, setPublishing] = useState(false);
    const [content, setContent] = useState("");
    const [title, setTitle] = useState("");
    const router = useRouter();

    const onChangeContent = useCallback((value: string) => {
        setContent(value);
    }, []);

    const handleCreatePost = async (e: React.FormEvent) => {
        e.preventDefault();
        console.log({ title, content });
        router.push("/");
    };

    return (
        
            
                
                    
                        Title
                    
                     setTitle(e.target.value)}
                        className='px-4 py-3 border-2 rounded-md text-lg mb-4'
                    />

                    
                        Content
                    
                    

                    
                
            
        
    );
}

The /posts/create page renders a form that accepts the title and content of the post, allowing authors to create new blog posts.

Create your next blog post with ease

Finally, update the /posts/[slug] page to display each post's content and include a button that allows only the posts' authors to delete posts. (You'll learn how to implement this later in the tutorial.)

use client";
import { useRouter, useParams } from "next/navigation";
import ReactMarkdown from "react-markdown";
import { useEffect, useState, useCallback } from "react";
import remarkGfm from "remark-gfm";
import { formatDateString } from "@/app/utils";

export default function Post() {
    const router = useRouter();
    const [loading, setLoading] = useState(true);
    const [post, setPost] = useState(null);
    const params = useParams<{ slug: string }>();

    const deletePost = async () => {
        if (confirm("Are you sure you want to delete this post?")) {
            alert(`Delete ${params.slug}`);
            router.push("/");
        }
    };

    return (
        
            
                
                    
                        {post?.title}

                        
                            
                        
                    

                    
                        
                            Author: {post?.author}
                        
                        
                            Posted on:{" "}
                            
                                {formatDateString(post?.created_at!)}
                            
                        
                    
                

                
                    
                        {post?.content!}
                    
                
            
        
    );
}

The /posts/[slug] page accepts the unique slug for each blog post, fetches the post's content, and allows post authors to delete their own posts.

Blog Post

Congratulations! You've completed the user interface for the application.

How to Authenticate Users with Clerk

Install the Clerk Next.js SDK by running the following code snippet in your terminal.

npm install @clerk/nextjs

Create a middleware.ts file within the Next.js src folder and copy the code snippet below into the file:

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


// the createRouteMatcher function accepts an array of routes to be protected
const protectedRoutes = createRouteMatcher(["/posts/create"]);

// protects the route
export default clerkMiddleware((auth, req) => {
    if (protectedRoutes(req)) {
        auth().protect();
 }
});

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

The createRouteMatcher function accepts an array containing routes to be protected from unauthenticated users and the clerkMiddleware() function ensures the routes are protected.

Next, import the following Clerk components into the app/layout.tsx file and update the RootLayout function as shown below:

import {
    ClerkProvider,
    SignInButton,
    SignedIn,
    SignedOut,
    UserButton,
} from "@clerk/nextjs";
import Link from "next/link";

export default function RootLayout({
    children,
}: {
    children: React.ReactNode;
}) {
    return (
        <ClerkProvider>
            <html lang='en'>
                <body className={inter.className}>
                    <nav className='w-full py-4 border-b-[1px] md:px-8 px-4 text-center flex items-center justify-between sticky top-0 bg-white z-10 '>
                        <Link href='/' className='text-xl font-extrabold text-blue-700'>
                            Neon Blog
                        Link>

                        <div className='flex items-center gap-5'>
                            {/*-- if user is signed out --*/}
                            <SignedOut>
                                <SignInButton mode='modal' />
                            SignedOut>
                            {/*-- if user is signed in --*/}
                            <SignedIn>
                                <Link href='/posts/create' className=''>
                                    Create Post
                                Link>
                                <UserButton showName />
                            SignedIn>
                        div>
                    nav>

                    {children}
                body>
            html>
        ClerkProvider>
    );
}

When a user is not signed in, the Sign in button component is rendered.

Seamless sign-ups redefined with Clerk UI

Then, after signing into the application, the Clerk User Button component and a link to create a new post are displayed.

After sign-in: Use Clerk's User Button to create a new post

Next, create a Clerk account and add a new application project.

Clerk's sleek UI dashboard

Select username as the authentication method and create the Clerk project.

Clerk's sleek UI dashboard

Finally, add your Clerk publishable and secret keys into the .env.local file.

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=
CLERK_SECRET_KEY=

Clerk provides various ways to read user's data on the client and the server, which is essential for identifying users within the application.

CRUD Operations with the Neon Database

In this section, you’ll learn how to perform CRUD (Create, Read, Update, Delete) operations with the Neon database. These fundamental operations are essential for interacting with and managing data within any application.

The db/actions.ts file will contain the CRUD operations. Add the following code snippet to the file:

import { db } from ".";
import { postsTable } from './schema';
import { desc, eq } from "drizzle-orm";

// add a new row to the posts table
export const createPost = async (post: Post) => {
    await db.insert(postsTable).values({
        content: post.content,
        author: post.author,
        author_id: post.author_id,
        title: post.title,
        slug: post.slug,
    });
};

// get all the posts
export const getAllPosts = async () => {
    return await db.select().from(postsTable).orderBy(desc(postsTable.created_at));
};

// get a post using its slug
export const getSinglePost = async (slug: string) => {
    return await db.query.postsTable.findFirst({
        where: (post, { eq }) => eq(post.slug, slug)
    });
};

// delete a post
export const deletePost = async (id: number) => {
    await db.delete(postsTable).where(eq(postsTable.id, id));
};

// update a post's content
export const updatePost = async (content: string, id: number) => {
    await db.update(postsTable)
        .set({ content: content })
        .where(eq(postsTable.id, id));
};

From the code snippet above:

This createPost function takes a post object as an argument and inserts a new row into the postsTable with the specified post content, author, author ID, title, and slug.
The getAllPosts function retrieves all the posts from the postsTable and sorts them in descending order by their creation date (created_at).
This getSinglePost function takes a slug as an argument and retrieves the first post that matches the given slug from the postsTable. The slug is unique, so it will return a single object.
This deletePost function takes an id as an argument and deletes the post with the matching ID from the postsTable.
This updatePost function accepts content and a post's id as arguments and updates the post's content with the matching ID in the postsTable.

Finally, you can execute the CRUD functions on the server via API endpoints or Next.js server fetch requests.

For instance, you can fetch all the existing blog posts within the Neon database and display them within the application using the Next.js server data fetching method:

import { getAllPosts } from "./db/actions";

const getPosts = async () => await getAllPosts()

export default async function Home() {
    const posts = await getPosts()

    return (<div>{/** -- UI elements --*/}div>)
}

You can also create a Next.js API endpoint that returns all the available blog posts. Create a /api/posts/all endpoint that returns the posts:

import { getPosts } from "@/app/db/actions";
import { NextRequest, NextResponse } from "next/server";

export async function POST() {


    try {
        const data = await getPosts()
        return NextResponse.json({ message: "Post fetched", data }, { status: 200 });
 } catch (err) {
        return NextResponse.json(
 { message: "Post not available", err },
 { status: 400 }
 );
 }
}

Congratulations! You’ve completed the project for this tutorial.

You can find the code for the app we built here.

Conclusion

In this tutorial, you’ve learned what a Neon database is, how to create one, and how to perform CRUD operations with Neon and Drizzle ORM in a Next.js application.

Neon's serverless architecture, combined with its scalability and performance optimizations, makes it an excellent choice for modern web applications. Neon also provides a smooth developer experience and a community of passionate individuals ready to help you achieve your application goals. Thank you for reading.

Next Steps

By now, you should have a good understanding of how to build full-stack applications with Neon and Next.js.

If you'd like to learn more about how you can leverage Neon to build advanced and scalable applications, you can check out the following resources:

Thanks for Reading!

That's it for this tutorial. I hope you learned something new today.

If you did, please share so that it reaches others as well.

You can connect with me on Twitter or subscribe to my newsletter.

Want to read more interesting blog posts?

You can read more tutorials like this one on my blog.

How to Build a Full-Stack Kanban Task Management App With TypeScript, Next.js, Redux-toolkit, and Firebase

freeCodeCamp — Tue, 26 Mar 2024 21:44:04 +0000

By Olasunkanmi Balogun

In this in-depth tutorial, you'll learn how to build a full-stack Kanban task management app. Along the way, we'll explore the synergies between technologies like Next.js (featuring a dive into the app router), Next-auth for user authentication, and Firebase, a backend as a service platform to save user data in a database.

We'll also cover how you can integrate Firebase Firestore with Redux Toolkit which enables you to cache data you have retrieved from the database to improve performance. You will also learn how to manage state with Redux Toolkit.

To wrap it up, we will employ React-beautiful-dnd, a library that effortlessly integrates drag-and-drop interactions into our Kanban boards to enhance the user experience.

Here's what we'll cover:

How to implement authentication with the next-auth.js library
How to set up and integrate the Redux store with Firestore in Next.js.
How to build and populate the Kanban app markup with data
How to implement Create, Read, Update, and Delete (CRUD) operations on boards and tasks.
How to implement drag and drop with react-beautiful-dnd library.

Prerequisites

You should have prior experience working with the Reactjs/Next.js framework.
You should have an understanding of type annotations in TypeScript, and ultimately, working with TypeScript in React.
An understanding of DSA in JavaScript is a plus.
Experience with Redux-toolkit library will also be a plus.

A few notes:

This article will focus primarily on functionality, but we'll use Tailwind CSS for styling.
I'll also include comments with each code snippet provided throughout this article to explain the code better. Keep an eye out for them.

How To Implement Authentication With next-auth.js
How to Configure the Redux Store
How to Create Your Kanban App Markup
How to Configure Firebase Firestore
How to Add Initial Data to the Firestore Database
How to Use RTK Query to Fetch Data from Cloud Firestore
How to Fetch and Populate Data
How to Implement CRUD Operations
How to Implement Drag and Drop Functionality
Conclusion

When you are ready, let's dive in.

How To Implement Authentication With `next-auth.js`

Begin by running the following command in your terminal to create a new Next.js project:

npx create-next-app@latest kanban-app-tutorial

Throughout the installation process, you will encounter prompts. Make sure you enable TypeScript and Tailwind CSS, as both will be integral to our project development.

Go ahead and clean out the redundant code that comes with the project. Delete the content in the page.tsx file and paste the code below as a placeholder:

export default function Home() {
  return (
    
      Hi
    
  )
}

Also, edit the content in the global.css file and leave only the Tailwind CSS imports.

Once these modifications are complete, install the next-auth.js library with the following command:

npm install next-auth

After successful installation, create an api folder in your root app folder, and inside it create an auth folder. Then, create a [...nextauth] folder inside the auth folder.

Finally, create two files named route.ts and options.ts inside the [...nextauth] folder.

Your file structure should look like the following:

Among the various next-auth.js providers, we will exclusively utilize the Google Provider to execute the authentication process.

In the option.ts file, paste the following code:

import type { NextAuthOptions } from "next-auth";
import GoogleProvider from "next-auth/providers/google";

export const options: NextAuthOptions = {
  providers: [
    GoogleProvider({
      clientId: process.env.GOOGLE_CLIENT_ID as string,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET as string,
    }),
  ],
  secret: process.env.NEXTAUTH_URL,
};

Here, we imported the NextAuthOptions type provided by next-auth for the sake of type safety concerning the options variable.

In the above code, the options object is where whichever provider we want to utilize will be housed (the Google Provider in this case).

You can get your clientId and clientSecret values from the Google Cloud Platform. If you need a step-by-step guide on how to get them, refer to this guide.

Once you have gotten them, create a .env file in the root folder of your application and paste the values in their respective variables.

Lastly, create a secret key for the NEXTAUTH_SECRET variable using the following terminal command:

openssl rand -base64 32

Ultimately, your .env file should contain these variables and values:

GOOGLE_CLIENT_ID = 
GOOGLE_CLIENT_SECRET = 
NEXT_AUTH_SECRET =

Important: You’ll also need these environment variables in production. So, don’t forget to update your production environment variable in your project settings on Vercel.

Proceed to the route.ts file and paste the following code in it:

import NextAuth from "next-auth/next";
import { options } from "./options";

const handler = NextAuth(options);

export { handler as GET, handler as POST };

Here, we imported the options variable from the option.ts file and passed it as a parameter to the NextAuth function, assigning the result to the handler variable.

The final statement ensures that any GET or POST request sent to the api/auth/[...nextauth] route will be managed by next-auth.js.

However, authentication won't be initiated yet because we haven't informed next-auth.js about which pages should be protected.

To implement protected routes, generate a middleware.ts file in the root src folder and insert the following code:

export { default } from 'next-auth/middleware'

export const config = { matcher: ['/'] }

The matcher property in the config object is an array containing the routes you want the middleware to protect. In this case, '/' designates the home page, indicating that the middleware protects the home page.

When you run your project server (with npm run dev), you should see an authentication page as seen below:

Now, let's configure the Redux store in our application.

How to Configure the Redux Store

To set up the Redux store in your application, follow these steps:

Begin by installing the necessary packages. Run the following command in your terminal:

npm install @reduxjs/toolkit react-redux

This installs the Redux Toolkit and react-redux for React bindings.

In the root src directory, create a folder named redux. Within this folder, create a store.ts file. Paste the following code into the store.ts file:

   // store.ts

   import { configureStore } from "@reduxjs/toolkit";
   import { setupListeners } from "@reduxjs/toolkit/dist/query";

   // Create the Redux store
   export const store = configureStore({
     reducer: {}, // Add your reducers here
   });

   // Setup listeners for refetch behaviors
   setupListeners(store.dispatch);

   // Define RootState and AppDispatch types
   export type RootState = ReturnType;
   export type AppDispatch = typeof store.dispatch;

In this code snippet, configureStore is used to create the Redux store, and setupListeners is called to handle refetchOnFocus and refetchOnReconnect behaviours.

Now, create another file in the same redux folder named hooks.ts and add the following code:

// hooks.ts
import { TypedUseSelectorHook, useDispatch, useSelector } from "react-redux";
import type { RootState, AppDispatch } from "./store";
// Typed versions of useDispatch and useSelector hooks

export const useAppDispatch = () => useDispatch();
export const useAppSelector: TypedUseSelectorHook = useSelector;

This code creates typed versions of the useDispatch and useSelector hooks to ensure type safety when interacting with the Redux store.

Still in the redux folder, create a file named provider.tsx with the following code snippet:

// provider.tsx
'use client'
import { store } from "./store";
import { Provider } from "react-redux";

// Custom provider component
export function Providers({ children }: { children: React.ReactNode }) {
   return {children};
 }

This file defines a custom provider component to wrap around your application components.

In your application layout file (src/app/layout.tsx), import the Providers component and wrap it around your main layout as seen below:

// layout.tsx

import type { Metadata } from 'next'
import { Plus_Jakarta_Sans } from "next/font/google";
import './globals.css'
import { Providers } from "@/components/redux/provider";

//font we'll use throughout the project
const pjs = Plus_Jakarta_Sans({ subsets: ["latin"], display: "swap" });
// Metadata definition
export const metadata: Metadata = {
   title: 'Create Next App',
   description: 'Generated by create next app',
  }

// RootLayout component
export default function RootLayout({
   children,
   }: {
   children: React.ReactNode
 }) {
   return (
      
        
          
            {children}
          
        
      
  );
}

By wrapping your components with the Providers component, you ensure that every component in your application has access to the Redux store.

Up to this point, your folder structure should look like this:

With these steps, you have successfully integrated the Redux store into your application, and you are ready to create slices for your application.

Before diving into the implementation of slices, let's create the markup for our application.

How to Create Your Kanban App Markup

This section guides you through the process of building the markup for your Kanban app. By the end of this section, your markup should resemble the image below:

Let's start by creating the navbar component.

Begin by establishing a components folder within the app directory. Inside it, create a Navbar.tsx file and insert the following code:

// src/app/components/Navbar.tsx

export default function Navbar() {

return (
  
    
       Kanban App 
    

   
       
         Board Name
       

      
        
          
            
          
        
      
    
  )}

Next, render the Navbar component in the src/app/layout.tsx file:

   import type { Metadata } from 'next'
   import { Providers } from "@/components/redux/provider";
   import Navbar from './components/Navbar';
   import { Plus_Jakarta_Sans } from "next/font/google";
   import './globals.css'

   const pjs = Plus_Jakarta_Sans({ subsets: ["latin"], display: "swap" });

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

   export default function RootLayout({
    children,
   }: {
    children: React.ReactNode
   }) {
   return (
    
      
        
            {/* Render the component here */}
          {children}
        
      
    
    )}

Now, the Navbar component is available globally across all pages in the application since it's rendered in the root layout component.

After implementing these changes, upon signing in to your application on localhost:3000, you should observe the UI as depicted in the image below.

The placeholder "Current board name" in the navbar will eventually be replaced with the name of an active board once we populate the app with data.

The "Add New Task" button is designed to open the "Add new tasks" modal, and the ellipsis next to it will trigger a dropdown for editing and deleting a board. The implementation of this dropdown is the focus of the next step.

Create a Dropdown.tsx file in the same components folder, and paste the following code into it:

   //src/app/components/Dropdown.tsx

   interface IDropdown {
    show: boolean
   }

   export default function Dropdown({ show }: IDropdown) {

    return (
      
        
          
        
        
          
        
      
    )}

This component takes a show parameter of type boolean as a prop. The dropdown content is displayed when show is true and hidden when it's false.

Now, proceed to the Navbar.tsx file and update the code to render the Dropdown component. Pay attention to the comments in the code snippet below to get a grasp of the updates here:

   //src/app/components/Navbar.tsx

   'use client' // we made this a client component since we have to make use of useState

   import Dropdown from "./Dropdown";
   import { useState } from 'react'

   export default function Navbar() {

   const [show, setShow] = useState(false); // this will manage the state of the show variable

   return (
    
      
         Kanban App 
      

      
        Current board name

        
          
          
            
              {/* render dropdown here and pass show as prop */}
          
        
      
    
    )}

After you make these adjustments in your Navbar component, you can now toggle the dropdown by clicking on the ellipsis:

In the next step, we'll implement components that make up the body of our application, specifically the sidebar components and board that displays the tasks.

To implement the sidebar, create a Sidebar.tsx file within the same components directory. Paste the following code into it:

   // src/app/components/Sidebar.tsx

   export default function Sidebar() {
   return (
    
      
        {`All Boards (0)`}
      
      
        Current board name
      
      
    
   );
   }

Following this, create another file named BoardTasks.tsx and paste the code below to it. This component will contain the contents of an active board task. Since the app is not yet populated with data, we'll use a placeholder that will be substituted by actual tasks later.

   // src/app/components/BoardTasks.tsx

   export default function BoardTasks() {
   return (
    
      
        
          
            This board is empty. Create a new column to get started.
          
          
        
      
    
    );
   }

Then, paste the following code in your src/app/page.tsx file to render both the Sidebar and BoardTasks components:

   import Sidebar from "./components/Sidebar";
   import BoardTasks from "./components/BoardTasks";

   export default function Home() {
   return (
    
      
      
    
   );
   }

Up to this point, your file structure should resemble the following:

Finally, in the root layout.tsx file, update the style of the body tag as shown below:

 // src/app/layout.tsx
   // rest of the code here
   export default function RootLayout({
   children,
   }: {
   children: React.ReactNode;
   }) {
   return (
    
       {/* update style here*/}
        {/* rest of the code here */}
      
    
   );
   }

This adjustment ensures that the content in the BoardTasks component is scrollable on both the x and y axis if it exceeds the length and breadth of the screen.

With this, the markup for our app is complete. Your UI should resemble this if you have been following along:

The sidebar will display the number of boards and the names of available boards in the app. Clicking different boards in the sidebar will switch to the selected board, and clicking "Create New Board" in the sidebar opens the "Add New Board" modal.

Right next to the sidebar, the tasks in each board will be displayed in columns. The current screen will be displayed if the board has no tasks yet. The "+Add New Column" button will open a modal used to add a column to a board.

All these features will be activated as we populate the application with data.

Moving forward, the next section will guide you in integrating Firebase Firestore into your application.

How to Configure Firebase Firestore

To integrate Firestore into your application, you'll need to create a Firebase project using the Firebase console. Feel free to name the project according to your preference, but for the sake of this tutorial, let's name it "Kanban-app-tutorial."

Once the project is created, you'll be prompted to register your app. After registration, install Firebase in your application. Install the Firebase package with the following command in your terminal:

npm install firebase

Now, you need to initialize Cloud Firestore in your application. Create a folder named utils and within it, create a firebaseConfig.ts file. Paste your Firebase configuration into it as shown below:

import { initializeApp } from "firebase/app";
import { getFirestore } from "firebase/firestore";

// Your web app's Firebase configuration
const firebaseConfig = {
 // Paste your Firebase config here
};

// Initialize Firebase
const app = initializeApp(firebaseConfig);
// Initialize Firestore and export it
export const db = getFirestore(app);

Finally, navigate to your newly created project on the cloud platform and create a Cloud Firestore database. Following this, proceed to the "Rules" tab and modify the read and write rules from false to true as illustrated in the image:

This will enable anyone to add data to the database without restrictions. Note that this is not recommended for production – we are implementing it like this for the purpose of this article.

With this setup complete, we can now begin adding data to the Cloud Firestore.

How to Add Initial Data to the Firestore Database

Our goal is to ensure that users aren't greeted with an empty board when they complete the authentication process. Instead, we want to present them with dummy task data that they can interact with, allowing them to explore the application's features.

Also, we aim to make this data user-specific, forming the foundation for each user to build upon by creating new boards and tasks.

To accomplish this, when a new user signs in, we'll generate a new document in the database for that user.

Here's a breakdown of our approach:

Check if the user is new: We need to determine whether the user is signing in for the first time. This way, we can automatically create a new document for the user in the database.
Create a new user document: If the user is new, we proceed to create a new data entry in the database specifically for that user.

To begin, create a data.js file inside the utils folder we created earlier (this will contain our dummy data for a board). Paste the provided data code into it.

//used to generate new id
export const id = () => Math.random().toString(36).substring(2, 10);

export const data = {
  "boards": [
    {
      id: id(),
      name: "Roadmap",
      columns: [
        {
          id: id(),
          name: "Now",
          tasks: [
            {
              id: id(),
              title: "Launch version one",
              status: "Now"
            },
            {
              id: id(),
              title: "Review early feedback and plan next steps for roadmap",
              status: "Now"
            }
          ]
        },
        {
          id: id(),
          name: "Next",
          tasks: []
        },
        {
          id: id(),
          name: "Later",
          tasks: []
        }
      ]
    }
  ]
}

Now, navigate to the src/app/page.tsx file and modify it as demonstrated below:

"use client";
import Sidebar from "./components/Sidebar";
import BoardTasks from "./components/BoardTasks";
// Firestore methods: collection and getDocs for document reference, addDoc for adding a document
import { collection, getDocs, addDoc } from "firebase/firestore";
// Connect our app to Firestore
import { db } from "./utils/firebaseConfig";
import { useEffect, useState } from "react";
// Import getSession from next-auth library to retrieve signed-in user details
import { getSession } from "next-auth/react";
// Import data from data.json, used to initialize the Firestore database for new users
import { data } from "./utils/data.json";

export default function Home() {
  // Manage user details in this state. Key index in TypeScript ensures type safety.
  const [userDetails, setUserDetails] = useState<{ [key: string]: any }>();

  // Get user session using getSession. Contains user's name and email, then passed to user details state.
  const getUserSession = async () => {
    const session = await getSession();
    if (session) {
      setUserDetails(session.user);
    }
  };

  const handleAddDoc = async () => {
    if (userDetails) {
      // Execute code inside curly braces only when `userDetails` is true.

      // Reference to the document with the user's email to check its existence in the database.
      const docRef = collection(db, "users", userDetails.email, "tasks");
      const getDos = await getDocs(docRef);

      // If the document exists, terminate the program.
      if (getDos.docs.length > 0) {
   ;     return;
      } else {
        // If not, submit a new document containing the data from data.json for the user in the database.
        try {
          await addDoc(
            collection(db, "users", userDetails.email, "tasks"),
            data
          );
        } catch (e) {
          console.error("Error adding document: ", e);
        }
      }
    }
  };

  useEffect(() => {
    getUserSession(); // Call getUserSession function after the page renders.
  }, []);

  useEffect(() => {
    handleAddDoc(); // Call handleAddDoc function after the user details update.
  }, [userDetails]);

  return (
    
      
      
    
  );
}

This code ensures that when a user logs in, their details are fetched and checked. If it's a new user, a new document with initial dummy data is added to the Firestore database under the user's email. Make sure you've read through the comments I added if you need any further explanation.

Upon visiting your project console, you'll notice the presence of a document created for the signed-in user (which is you):

The initial setup is now complete, enabling us to fetch data and initiate the population of our application. But before directly interacting with the data, we'll employ RTK query, which is included in the Redux toolkit package, as an intermediary.

This approach not only eliminates the need to write data fetching and caching logic in various components repeatedly, but also eliminates background revalidation, so we don't need explicit manual refreshes.

The next section will explore this process.

How to Use `RTK Query` to Fetch Data from Cloud Firestore

Here, we'll begin the process of creating slices for the reducer, starting with the development of the slice dedicated to data fetching.

Within the src/redux directory, create a new folder named services.

Inside the newly created services folder, establish a file named apiSlice.ts. Copy and paste the provided code into this file:

   import { createApi, fakeBaseQuery } from "@reduxjs/toolkit/query/react";
   import { getSession } from "next-auth/react";
   import { collection, getDocs } from "firebase/firestore";
   import { db } from "@/components/app/utils/firebaseConfig";

   // Create the Firestore API using createApi
   export const fireStoreApi = createApi({
   reducerPath: "firestoreApi", // Specifies the path for the reducer
   baseQuery: fakeBaseQuery(), // Utilizes fakeBaseQuery because Firebase has no traditional REST API endpoint
   tagTypes: ["Tasks"], // Defines tag types for caching purposes
   endpoints: (builder) => ({
    fetchDataFromDb: builder.query<{ [key: string]: any }[], void>({
      // Utilizes builder.query for making requests; builder.mutation can be used for CRUD operations
      async queryFn() {
        // Employs queryFn since we are not fetching data from a conventional API;
        // This allows us to include arbitrary code, as long as we return our data in the { data: results } format

        try {
          const session = await getSession();
          const { user } = session!;
            const ref = collection(db, `users/${user?.email}/tasks`);
            const querySnapshot = await getDocs(ref);
            return { data: querySnapshot.docs.map((doc) => doc.data()) };
            // Data must be returned in this format when using queryFn

        } catch (e) {
          return { error: e };
        }
      },
      providesTags: ["Tasks"], // Specifies tags for caching
    }),
   }),
   });

   // Export hooks for using the created endpoint
   export const { useFetchDataFromDbQuery } = fireStoreApi;

This code establishes a Firestore API using createApi, defining an endpoint for fetching data. The use of fakeBaseQuery is intentional, considering Firebase doesn't have a conventional base URL.

The code also integrates caching and invalidation through tags. In this slice, we've specified tagTypes as 'Tasks'. In subsequent sections, we'll explore how invalidation and refetching can be done through tags.

In the slice, endpoints can be perceived as API endpoints. Functions defined within this endpoints function will be exported in the form of use...Query if it's a builder.query function (as in this case, useFetchDataFromDbQuery), and use...Mutation if it's a builder.mutation function (more on this later).

Now, we'll lay the foundation for incorporating the slices we generate into the Redux store. Since we will create multiple slices in the future, it's prudent to compile them into a dedicated file using combineReducers.

Next, create a rootReducer.ts file within the src/redux folder. Embed the following code snippet into this file to integrate the previously created apiSlice:

  import { combineReducers } from "@reduxjs/toolkit";
   import { fireStoreApi } from "./services/apiSlice";

   export const rootReducer = combineReducers({
    [fireStoreApi.reducerPath]: fireStoreApi.reducer,
   });

In this snippet, we imported the earlier-created apiSlice and include it in the combineReducers function, specifying the key-value pair as [fireStoreApi.reducerPath]: fireStoreApi.reducer.

This configuration ensures that the state managed by the apiSlice is effectively integrated into the Redux store.

Finally, we'll add the rootReducer to the Redux store here. Navigate to the src/redux/store.ts and modify it like below:

import { configureStore } from "@reduxjs/toolkit";
   import { setupListeners } from "@reduxjs/toolkit/dist/query";
   import { rootReducer } from "./rootReducer";
   import { fireStoreApi } from "./services/apiSlice";

   export const store = configureStore({
    reducer: rootReducer,
    middleware: (getDefaultMiddleware) => getDefaultMiddleware().concat(fireStoreApi.middleware),
   });
   setupListeners(store.dispatch)
   export type RootState = ReturnType;
   export type AppDispatch = typeof store.dispatch;

Here, we integrate our rootReducer into the store and pass the fireStoreApi.middleware to the middleware prop of the configureStore function. This ensures that the Redux store uses the middleware for making requests to Firestore.

Now, we can safely start the process of fetching and populating our application with data, which will be the focus of the upcoming section.

How to Fetch and Populate Data

Our approach begins with populating data in the Navbar component, followed by the Sidebar, and finally, the BoardTasks.

For the Navbar, we want to display the name of the current board. But since we'll need this information in other parts of the app, we'll also store it centrally in the Redux store.

To achieve this, we'll create a new slice called appSlice, which will manage the state related to the current board name. This slice will also be responsible for handling logic and state unrelated to API calls.

First, create a features folder within the src/redux directory.

Inside the features folder, create a file named appSlice.ts and paste the following code:

   import { createSlice, PayloadAction } from "@reduxjs/toolkit";
   import { RootState } from "../store";

   // Define the initial state for the slice
   const initialState = {
    currentBoardName: "",
   };

   export const features = createSlice({
   // Name of the slice
   name: "features",
   initialState,
   // Functions that update the initialState are written inside the reducers object
   reducers: {
    // This function updates the board name when called
    setPageTitle: (state, action: PayloadAction) => {
      state.currentBoardName = action.payload;
    },
   },
   });

   // Export the functions defined inside the reducers here
   export const { setPageTitle } = features.actions;

   // Selector function to retrieve the current board name from the state
   export const getPageTitle = (state: RootState) => state.features.currentBoardName;

   // Export the reducer for use in the Redux store
   export default features.reducer;

This code defines the appSlice slice, which includes the initial state, reducers, and actions for managing the current board name.

To make the appSlice available globally, we must integrate it into the Redux store. Open the src/redux/rootReducer.ts file and modify it as follows:

   // src/redux/rootReducer.ts
   import { combineReducers } from "@reduxjs/toolkit";
   import { fireStoreApi } from "./services/apiSlice";
   import  featuresReducer  from "./features/appSlice";

   export const rootReducer = combineReducers({
   //add the features slice here
   features: featuresReducer,
   [fireStoreApi.reducerPath]: fireStoreApi.reducer,
   });

This updated rootReducer now includes the featuresReducer, making the appSlice available throughout the application.

Next, we need to update the Navbar component to fetch the current board name from the Redux store and display it. Open the app/components/Navbar.tsx file and make the following changes:

  'use client' 

   import Dropdown from "./Dropdown";
   import { useState, useEffect } from 'react'
   // Import Redux functions and selectors for managing board names
   import { setCurrentBoardName, getCurrentBoardName } from '../../redux/features/appSlice'
   import { useAppDispatch, useAppSelector } from '@/components/redux/hooks'
   // Import the data-fetching hook from the API slice
   import { useFetchDataFromDbQuery } from "@/components/redux/services/apiSlice";

   export default function Navbar() {
    const [show, setShow] = useState(false);
   // Destructuring assignment to extract data from the useFetchDataFromDbQuery hook
   const { data } = useFetchDataFromDbQuery();
   // Access the Redux dispatch function for calling actions
   const dispatch = useAppDispatch();

   // Effect hook to run when the data updates
   useEffect(() => {
    if (data) {
      // When a user signs in, set the currentBoardName to the first board's name
      const activeBoard = data[0].boards[0];
      dispatch(setCurrentBoardName(activeBoard.name));
    }
   }, [data]);

   // Select the current board name from the Redux store
   const currentBoardName = useAppSelector(getCurrentBoardName);

   return (
    
      
         Kanban App 
      

      
        {/* populate the current board name in the navbar */}
        {currentBoardName}

        
          
          
            
            
          
        
      
    
   );
   }

After these updates, your navbar should now display the name of the current board, which is "Roadmap":

Once populated with data, the sidebar will display the number of boards and the names of the available boards in the application. Clicking on different boards in the sidebar will switch the view to the selected board.

While we currently only have one board available in the data, we'll lay the groundwork for these features to support multiple boards in the future.

Navigate to the Sidebar component and make the following edits as seen below:

import { useState } from "react";
import { useAppDispatch } from "@/components/redux/hooks";
import { useFetchDataFromDbQuery } from "@/components/redux/services/apiSlice";
import { setCurrentBoardName } from "@/components/redux/features/appSlice";

export default function Sidebar() {
  // State to keep track of the index of the active board during navigation
  const [active, setActive] = useState(0);

  const { data } = useFetchDataFromDbQuery();
  const dispatch = useAppDispatch();

  // Function to handle navigation through boards
  const handleNav = (index: number, name: string) => {
    setActive(index);
    dispatch(setCurrentBoardName(name));
  };

  return (
    
      {data && (
        <>
          {/* Display the number of boards available in the data */}
          
            {`All Boards (${data[0]?.boards.length})`}
          
          {/* Display the names of each board */}
          {data[0]?.boards.map(
            (board: { [key: string]: any }, index: number) => {
              const { name, id } = board;
              const isActive = index === active; // Check if the board is active
              return (
                 handleNav(index, name)} // Handle navigation through boards on click
                  className={`${
                    isActive ? 'rounded-tr-full rounded-br-full bg-blue-500 text-white' : 'text-black'
                  } cursor-pointer flex items-center 
                  space-x-2 pl-[2.12rem] py-3 pb-3`}
                >
                  {name}
                
              );
            }
          )}
        
      )}
      
    
  );
}

With the above code, we have prepared the sidebar for handling multiple boards in the future. When multiple boards are available in the data, the sidebar will dynamically display them, allowing users to switch between them seamlessly.

Up to this point, your sidebar UI should reflect these updates:

Moving forward, in the next section we'll populate the BoardTasks component.

How to populate the `BoardTasks` component

In this section, the goal is to present a maximum of seven task columns on the screen. If there are fewer than seven columns, we'll display an option to add more. Also, we'll want to have an indication of an empty column for columns without tasks.

Each task card should feature edit and delete icons. These will serve as placeholders for forthcoming modal functionalities.

To implement these changes, go to the BoardTasks component and make the following updates:

import { useEffect, useState } from "react";
import { useFetchDataFromDbQuery } from "@/components/redux/services/apiSlice";
import { useAppSelector } from "@/components/redux/hooks";
import { getCurrentBoardName } from "@/components/redux/features/appSlice";
import { MdEdit, MdDelete } from "react-icons/md";

// Define types for the tasks data
interface ITask {
  title: string;
  description: string;
  status: string;
}

// Define types for the data in each column
interface Column {
  name: string;
  tasks?: ITask[];
}

export default function BoardTasks() {
  // Get loading state and data from the useFetchDataFromDbQuery endpoint
  const { isLoading, data } = useFetchDataFromDbQuery();
  // Manage column data in columns state
  const [columns, setColumns] = useState([]);
  // Get active board name from the redux store
  const activeBoard = useAppSelector(getCurrentBoardName);

  // Once data fetches successfully, this function in the useEffect runs
  useEffect(() => {
    if (data !== undefined) {
      const [boards] = data;
      if (boards) {
        // Get the data of the active board
        const activeBoardData = boards.boards.find(
          (board: { name: string }) => board.name === activeBoard
        );
        if (activeBoardData) {
          const { columns } = activeBoardData;
          setColumns(columns);
        }
      }
    }
  }, [data, activeBoard]);

  return (
    
      {/* If data has not been fetched successfully, display a loading state, else display the column of tasks */}
      {isLoading ? (
        Loading tasks...
      ) : (
        <>
          {/* If columns of tasks isn't empty: display the tasks, else display the prompt to add a new column */}
          {columns.length > 0 ? (
            
              {columns.map((column) => {
                const { id, name, tasks } = column;
                return (
                  
                    {`${name} (${
                      tasks ? tasks?.length : 0
                    })`}

                    {tasks &&
                      // Display the tasks if there are tasks in the column, if not, display an empty column
                      (tasks.length > 0 ? (
                        tasks.map((task) => {
                          const { id, title, status } = task;

                          return (
                            
                              {title}
                              
                                
                                
                              
                            
                          );
                        })
                      ) : (
                        
                      ))}
                  
                );
              })}
              {/* If the number of columns of tasks is less than 7, display an option to add more columns */}
              {columns.length < 7 ? (
                
                  
                    + New Column
                  
                
              ) : (
                ""
              )}
            
          ) : (
            
              
                
                  This board is empty. Create a new column to get started.
                
                
              
            
          )}
        
      )}
    
  );
}

After you make these edits, your UI should now reflect the changes as demonstrated in the GIF below:

Next, we'll turn our attention to implementing CRUD (Create, Read, Update, and Delete) operations throughout our application.

How to Implement CRUD Operations

Before we dive into implementing CRUD functionalities throughout our app, we need to establish the updateBoardToDb mutation endpoint within the apiSlice. This endpoint will allow us to make necessary updates to our database for CRUD actions.

Integrate the following code into your redux/services/apiSlice.ts file to include the mutation endpoint:

import { createApi, fakeBaseQuery } from "@reduxjs/toolkit/query/react";
import { getSession } from "next-auth/react";
// additionally import the doc and updateDoc method from firestore to get user document reference and update the document, respectively
import { collection, doc, getDocs, updateDoc } from "firebase/firestore";
import { db } from "@/components/app/utils/firebaseConfig";

export const fireStoreApi = createApi({
  reducerPath: "firestoreApi",
  baseQuery: fakeBaseQuery(),
  tagTypes: ["Tasks"],
  endpoints: (builder) => ({
    fetchDataFromDb: builder.query<{ [key: string]: any }[], void>({
      async queryFn() {
        try {
          const session = await getSession();
          if (session?.user) {
            const { user } = session;
            const ref = collection(db, `users/${user.email}/tasks`);
            const querySnapshot = await getDocs(ref);
            return { data: querySnapshot.docs.map((doc) => doc.data()) };
          }
        } catch (e) {
          return { error: e };
        }
      },
      providesTags: ["Tasks"],
    }),
    // endpoint for CRUD actions
    updateBoardToDb: builder.mutation({
      async queryFn(boardData) {
        try {
          const session = await getSession();
          if (session?.user) {
            const { user } = session;
            const ref = collection(db, `users/${user.email}/tasks`);
            const querySnapshot = await getDocs(ref);
            const boardId = querySnapshot.docs.map((doc) => {
              return doc.id;
            });
            await updateDoc(doc(db, `users/${user.email}/tasks/${boardId}`), {
              boards: boardData,
            });
          }
          return { data: null };
        } catch (e) {
          return { error: e };
        }
      },
      invalidatesTags: ["Tasks"], // this will be used to invalidate the initially fetched data. 
      // Data will have to be refetched once this enpoint has been called
    }),
  }),
});

// Export hooks for using the created endpoint
export const { useFetchDataFromDbQuery, useUpdateBoardToDbMutation } =
  fireStoreApi;

Upon calling the useUpdateBoardToDbMutation endpoint, our database data will be updated accordingly.

Following each update, Redux seamlessly performs background refreshes to ensure we're operating with the latest data. This functionality is enabled by the invalidatesTags property we passed to the updateBoardToDb endpoint.

Having successfully implemented the CRUD endpoint, our next step is to implement the features for adding and editing boards.

How to add and edit a board

Once we've completed the UI implementation, the modal for adding a new board should resemble the following:

Similarly, for editing a board:

If you look at the images above, you can see that both modals share a striking resemblance, differing only in their titles.

This presents an excellent opportunity to implement the DRY (Don't Repeat Yourself) concept in programming. In a few steps, we'll explore how to leverage a single modal to fulfill both purposes.

First, we'll use the react-modal library to create a custom modal component. This allows us to avoid building from scratch.

To begin, install the react-modal library by running the following command:

 npm i react-modal

Then create a Modal.tsx file in the app/components directory and add the provided code. This code defines a custom modal component with styling.

import ReactModal from "react-modal";

interface ModalProps {
  children?: React.ReactNode;
  isOpen: boolean;
  onRequestClose: () => void;
}

ReactModal.setAppElement("*");

export function Modal({ children, isOpen, onRequestClose }: ModalProps) {
  const modalStyle = {
    overlay: {
      zIndex: "900000",
      backgroundColor: "rgba(0,0,0,0.45)",
      display: "flex",
      justifyContent: "center",
      alignItems: "center",
    },
    content: {
      top: "50%",
      left: "50%",
      right: "auto",
      bottom: "auto",
      marginRight: "-50%",
      transform: "translate(-50%, -50%)",
      padding: "0px",
      borderRadius: ".5rem",
      width: "auto",
      backgroundColor:  "#fff",
      border: "none",
    },
  };

  return (
    
      {children}
    
  );
}

interface ModalBody {
  children: React.ReactNode;
}

export function ModalBody({ children }: ModalBody) {
  return {children};
}

In this code, we have implemented and styled the overlay and body (content) of the modal.

Now, create a folder named AddAndEditBoardModal.tsx and paste the provided code into it as a placeholder. Don't worry about the red squiggly lines you get in your code editor for now – we'll address them in a bit.

   import { Modal, ModalBody } from "./Modal";

   export default function AddAndEditBoardModal() {

    return (
      
        
         Add and Edit Board Modal
        
      
    );
   }

In this code, we imported our custom modal component, and we've wrapped it around a placeholder text.

Next, render the newly created modal component in the app/page.tsx component:

   // rest of imports here
   import AddAndEditBoardModal from "./components/AddAndEditBoardModal";
   // rest of the code here
   export default function Home() {
   return (
    
      
      
      {/* render modal component here */}
      
    
   );
   }

In this step, we've created a placeholder for the AddAndEditBoardModal component and rendered it in the Page.tsx component.

Next, we'll implement the functions to trigger the modal and manage the open and close state in the redux store to maintain clean code and avoid prop drilling.

Navigate to your redux/features/appSlice.ts file and update it with the code below:

   import { createSlice, PayloadAction } from "@reduxjs/toolkit";
   import { RootState } from "../store";

   const initialState = {
   currentBoardName: "",
   // Manage the state for opening and closing the Add and Edit Board modal
   isAddAndEditBoardModal: { isOpen: false, variant: "" },
   };

   export const features = createSlice({
    name: "features",
    initialState,

    reducers: {
     setCurrentBoardName: (state, action: PayloadAction) => {
      state.currentBoardName = action.payload;
    },
    // Open the Add and Edit Board modal with a specified variant (add or edit)
    openAddAndEditBoardModal: (state, { payload }) => {
      state.isAddAndEditBoardModal.isOpen = true;
      // Set the kind of modal to open (add board or edit board) based on the variant parameter
      state.isAddAndEditBoardModal.variant = payload;
    },
    // Close the Add and Edit Board modal
    closeAddAndEditBoardModal: (state) => {
      state.isAddAndEditBoardModal.isOpen = false;
      state.isAddAndEditBoardModal.variant = "";
    },
   },
   });
   export const {
   setCurrentBoardName,
   openAddAndEditBoardModal,
   closeAddAndEditBoardModal,
   } = features.actions;
   export const getCurrentBoardName = (state: RootState) => state.features.currentBoardName;
   // Selector functions to retrieve isOpen value of state from the isAddAndRditBoardModal state
   export const getAddAndEditBoardModalValue = (state: RootState) => state.features.isAddAndEditBoardModal.isOpen;
   // Selector functions to retrieve isOpen value of state from the isAddAndRditBoardModal state
   export const getAddAndEditBoardModalVariantValue = (state: RootState) => state.features.isAddAndEditBoardModal.variant;
   // Export the reducer for use in the Redux store
   export default features.reducer;

Then, navigate back to the AddAndEditBoardModal.tsx component and update it as seen below:

   import { Modal, ModalBody } from "./Modal";
   import { useAppSelector, useAppDispatch } from "@/components/redux/hooks";
   //import needed functions from the appSlice
   import {
   getAddAndEditBoardModalValue,
   getAddAndEditBoardModalVariantValue,
   closeAddAndEditBoardModal,
   } from "@/components/redux/features/appSlice";

   export default function AddAndEditBoardModal() {
   // get the variant of the modal
   const modalVariant = useAppSelector(getAddAndEditBoardModalVariantValue);
   const dispatch = useAppDispatch();
   // opens that modal is isOpen evaluates to true
   const isOpen = useAppSelector(getAddAndEditBoardModalValue);
   // close the modal
   const closeModal = () => dispatch(closeAddAndEditBoardModal());

   return (
    
      
        {/* display the variant(title) of the modal */}
        {modalVariant}
      
    
   );
   }

Following these updates, we can safely implement the trigger for the add and edit board modal.

Next, navigate to the Sidebar component and update the button with the "+ Create new board" text so it opens the "Add Board" modal when clicked:

   // add this to the imports
   import { openAddAndEditBoardModal } from "@/components/redux/features/appSlice";

   export default function Sidebar() {
    // rest of code here
   return (
     
       {/* rest of code here */}
       {/* trigger the create new board modal */}
       
     
   );
   }

Now, upon clicking the "+ Create new board" button in the sidebar, the modal containing the "Add new board" text should appear. You should also be able to close it by clicking on the overlay:

Next, we'll implement the trigger for the edit board modal.

Navigate to the app/components/Dropdown.tsx component and update the "Edit board" button as follows:

   import { useAppDispatch } from '@/components/redux/hooks'
   import { openAddAndEditBoardModal } from '@/components/redux/features/appSlice';

   interface IDropdown {
    show: boolean
   }

   export default function Dropdown({ show }: IDropdown) {

    const dispatch = useAppDispatch()

    return (
      
        
        {/* trigger Edit Board modal here */}
          
        
        
          
        
      
    );
   }

After making this update, clicking on the "Edit board" button in the dropdown will open the edit board modal, as illustrated in the GIF below:

The option to add a new column to the BoardTasks component should also open this modal when clicked. So navigate to the BoardTasks component and import the openAddEditBoardModal function and useAppDispatch hook from appSlice and redux hooks, respectively.

Then declare the dispatch function in the component with this statement: const dispatch = useAppDispatch()

Finally, update the "+New Column" div element to open the "Edit board" modal when clicked:

   // rest of the code 
     dispatch(openAddAndEditBoardModal("Edit Board"))
    className="rounded-md bg-white w-[17.5rem] mt-12 shrink-0 flex justify-center items-center">
     + New Column 
   
   //rest of the code

After these updates, the "Edit board" modal should open up when the "+New Column" card is clicked:

In the upcoming steps, we'll construct the complete markup and functionalities for our modal.

Referring to the images of both modals presented at the start of this section, in the "Add New Board" modal, the fields for board and column names should be blank. In contrast, the "Edit Board" modal should display the existing name and columns of the board and should be editable.

The "+ Add New Column" button in both modals allows the addition of more fields to the board's columns, and subsequently, the updated data is sent to the database.

Keep in mind that, given the frontend-centric nature of this project, a significant portion of the business logic will be handled on the front-end. However, don’t worry; we will take this snippet by snippet until we completely implement all features.

To begin, update the AddAndEditBoardModal component by pasting the code below:

import { useState, useEffect } from "react";
import { Modal, ModalBody } from "./Modal";
import { useAppSelector, useAppDispatch } from "@/components/redux/hooks";
//import needed functions from the appSlice
import {
  getAddAndEditBoardModalValue,
  getAddAndEditBoardModalVariantValue,
  closeAddAndEditBoardModal,
  getCurrentBoardName,
} from "@/components/redux/features/appSlice";
import {
  useFetchDataFromDbQuery,
  useUpdateBoardToDbMutation,
} from "@/components/redux/services/apiSlice";
import { FaTimes } from "react-icons/fa";
import { id } from '../utils/data'
// define types for boarddata
interface IBoardData {
  id: string,
  name: string;
  columns: {
    id: string;
    name: string;
    columns?: { name: string; tasks?: { [key: string]: any }[] };
  }[];
}
// dummy add board data for the "Add board" modal
let addBoardData = {
  id: id(),
  name: "",
  columns: [
    {
      id: id(),
      name: "",
      tasks:
 [],
    },
  ],};

export default function AddAndEditBoardModal() {
// rest of the code
}

Here, we have made the necessary imports and defined a type for board data - which we will use when populating the modal. We also implemented dummy data for the add board modal. We will see how this will be of use in a bit.

Next, go to the AddAndEditBoardModal function and paste the following code into it to declare variables and state values. The comments explain the future use of each of the declarations.

 //manage the board data state
  const [boardData, setBoardData] = useState();
  // check if the board name field is empty
  const [isBoardNameEmpty, setIsBoardNameEmpty] = useState(false);
  // will be used to check if any of the board column field is empty
  const [emptyColumnIndex, setEmptyColumnIndex] = useState();

  // get the variant of the modal
  const modalVariant = useAppSelector(getAddAndEditBoardModalVariantValue);
  // check the type of the open modal, whether Add new board, or Edit board
  const isVariantAdd = modalVariant === "Add New Board";
  const dispatch = useAppDispatch();
  // opens that modal if isOpen evaluates to true
  const isOpen = useAppSelector(getAddAndEditBoardModalValue);
  const currentBoardTitle = useAppSelector(getCurrentBoardName);
  // close the modal
  const closeModal = () => dispatch(closeAddAndEditBoardModal());
  // Fetch data from the database to populate the edit board modal
  let { data } = useFetchDataFromDbQuery();
  // Mutation hook for updating the board in the database
  const [updateBoardToDb, { isLoading }] = useUpdateBoardToDbMutation();

Here, we’ll implement the functions that will be responsible for the modal’s functionality. Paste the following code just below the declarations above:

  // Effect to set initial data for the modal based on the variant
  useEffect(() => {
    if (data) {

      if (isVariantAdd) {
        setBoardData(addBoardData);
      } else {
        const activeBoard = data[0].boards.find(
          (board: { name: string }) => board.name === currentBoardTitle
        );
        setBoardData(activeBoard);
      }
    }
  }, [data, modalVariant]);

  // Effect to clear error messages after a certain time
  useEffect(() => {
    const timeoutId = setTimeout(() => {
      setIsBoardNameEmpty(false);
      setEmptyColumnIndex(undefined);
    }, 3000);
    return () => clearTimeout(timeoutId);
  }, [emptyColumnIndex, isBoardNameEmpty]);

  // Handler for board name change
  const handleBoardNameChange = (e: React.ChangeEvent) => {
    if (boardData) {
      const newName = { ...boardData, name: e.target.value };
      setBoardData(newName);
    }
  };

  // Handler for column name change. These kind of functions are called closures

  const handleColumnNameChange = (index: number) => {
    return function (e: React.ChangeEvent) {
      // handle change for create new board modal
      if (boardData) {
        const modifyColumns = boardData.columns.map((column, columnIndex) => {
          if (columnIndex === index) {
            return { ...column, name: e.target.value };
          }
          return column;
        });
        const modifiedColumn = { ...boardData, columns: modifyColumns };
        setBoardData(modifiedColumn);
      }
    };
  };

  // Handler for adding a new column to the form
  const handleAddNewColumn = () => {
    // max columns we want to have in a board is 7
    if (boardData && boardData.columns.length < 6) {
      // Make a copy of the existing boardData
      const updatedBoardData = { ...boardData };
      // Create a new column object
      const newColumn = { id: id(), name: "", tasks: [] };
      // Push the new column to the columns array in the copy
      updatedBoardData.columns = [...updatedBoardData.columns, newColumn];
      // Update the state with the modified copy
      setBoardData(updatedBoardData);
    }
  };

  // Handler for deleting a column in the form
  const handleDeleteColumn = (index: number) => {
    if (boardData) {
      const filteredColumns = boardData.columns.filter(
        (_column, columnIndex) => columnIndex !== index
      );
      setBoardData({ ...boardData, columns: filteredColumns });
    }
  };

  // Handler for adding a new board to the database
  const handleAddNewBoardToDb = (e: React.FormEvent) => {
    e.preventDefault();

    // check if any of the column names are empty before submiting
    const emptyColumnStringChecker = boardData?.columns.some(
      (column) => column.name === ""
    ); 

    //condition to run if the board name is empty
    if (boardData?.name === "") {
      setIsBoardNameEmpty(true);
    }

    //if any of the column names is empty, update the emptyColumnIndex with its index
    if (emptyColumnStringChecker) {
      const emptyColumn = boardData?.columns.findIndex(
        (column) => column.name == ""
      );
      setEmptyColumnIndex(emptyColumn);
    }

    if (boardData?.name !== "" && !emptyColumnStringChecker) {
      //submit to the database after verifying that the board name and none of the column names aren't empty
      if (data) {
        let [boards] = data;
        const addBoard = [...boards.boards, boardData];
        boards = addBoard;
        updateBoardToDb(boards);
      }
    }
  };

  // Handler for editing a board in the database
  const handleEditBoardToDb = (e: React.FormEvent) => {
    e.preventDefault();
    const emptyColumnStringChecker = boardData?.columns.some(
      (column) => column.name === ""
    );
    //condition to run if the board name is empty
    if (boardData?.name === "") {
      setIsBoardNameEmpty(true);
    }
    //if any of the column names is empty, update the emptyColumnIndex with its index
    if (emptyColumnStringChecker) {
      const emptyColumn = boardData?.columns.findIndex(
        (column) => column.name == ""
      );
      setEmptyColumnIndex(emptyColumn);
    }
    //submit to the database after verifying that the board name and none of the column names aren't empty
    if (boardData?.name !== "" && !emptyColumnStringChecker) {
      if (data) {
        const [boards] = data;
        const boardsCopy = [...boards.boards]; 
        const activeBoardIndex = boardsCopy.findIndex(
          (board: { name: string }) => board.name === currentBoardTitle
        );
        const updatedBoard = {
          ...boards.boards[activeBoardIndex],
          name: boardData!.name,
          columns: boardData!.columns,
        } ;
        boardsCopy[activeBoardIndex] = updatedBoard;
        updateBoardToDb(boardsCopy);
      }
    }
  };

Finally, update the return statement of the component by pasting the below code snippet into it:

return (
    
      
        {boardData && (
          <>
            {/* display the variant(title) of the modal */}
            {modalVariant}
            
              
                
                  Board Name
                
                
                  
                
                {/* display this error if the board name is empty */}
                {isBoardNameEmpty ? (
                  
                    Board name cannot be empty
                  
                ) : (
                  ""
                )}
              

              
                
                  Board Column
                
                {boardData &&
                  boardData.columns.map(
                    (column: { name: string, id: string }, index: number) => {
                      let { name, id } = column;
                      return (
                        
                          
                             handleColumnNameChange(index)(e)}
                              value={name!}
                            />
                            
                               handleDeleteColumn(index)}
                              />
                            
                          
                          {/* display this error if the board name is empty */}
                          {emptyColumnIndex === index ? (
                            
                              Column name cannot be empty
                            
                          ) : (
                            ""
                          )}
                        
                      );
                    }
                  )}
                
                  
                
              
              
                
              
            
          
        )}
      
    
  );

In the above GIF, we introduced a "Marketing" board with "Todo" and "Doing" columns to our app. You can also see the real-time update of the boards in the sidebar.

Likewise, you can perform edits on a board:

Here, a new column, "After," was added to the "Roadmap" board.

In the upcoming section, we will implement the "Add new task" and "Edit task" functionalities.

How to add and edit tasks

Once you've completed this section, the "Add New Task" modal should resemble the following:

Similarly, for the "Edit Task" modal:

You'll see that these modals share similarities, so we will implement them using the same approach employed in the previous section.

We'll start by updating the initialState object in our appSlice to manage the state of the "Add and Edit tasks" modal.

   const initialState = {
   //add and edit tasks modal state
   isAddAndEditTaskModal: { isOpen: false, variant: "", title: "", index: -1, name: ""},
   };

The keys title and index will respectively store the title and index of the task being edited, while the name key will retrieve the name of the task's column. We'll explore how to utilize this information to edit a task in the upcoming steps.

Next, include the following functions in the reducers object. These will be the functions that will be called to open and close the modal:

    // Open the Add and Edit task modal with a specified variant (add or edit), title, description, status
    openAddAndEditTaskModal: (state, { payload }) => {
      state.isAddAndEditTaskModal.isOpen = true;
      state.isAddAndEditTaskModal.variant = payload.variant;
      state.isAddAndEditTaskModal.title = payload.title;
      state.isAddAndEditTaskModal.index = payload.index;
     state.isAddAndEditTaskModal.name = payload.name;
    },
    // Close the Add and Edit task modal
    closeAddAndEditTaskModal: (state) => {
      state.isAddAndEditTaskModal.isOpen = false;
      state.isAddAndEditTaskModal.variant = "";
      state.isAddAndEditTaskModal.title = "";
      state.isAddAndEditTaskModal.index = "";
      state.isAddAndEditTaskModal.name = "";
    },

Lastly, include the newly implemented functions and the selector functions in the exports:

   export const {
   openAddAndEditTaskModal,
   closeAddAndEditTaskModal,
   //rest of the imports
   } = features.actions;

   // Selector function to retrieve isOpen state value  
   export const getAddAndEditTaskModalValue = (state: RootState) => state.features.isAddAndEditTaskModal.isOpen;
   // Selector function to retrieve variant state value 
   export const getAddAndEditTaskModalVariantValue = (state: RootState) => state.features.isAddAndEditTaskModal.variant;
   // Selector function to retrieve title state value
   export const getAddAndEditTaskModalTitleValue = (state: RootState) => state.features.isAddAndEditTaskModal.title;
   // Selector function to retrieve index state value
   export const getAddAndEditTaskModalIndexValue = (state: RootState) => state.features.isAddAndEditTaskModal.index;
   // Selector function to retrieve name state value
   export const getAddAndEditTaskModalNameValue = (state: RootState) => state.features.isAddAndEditTaskModal.name;
   //rest of the imports

Now, we'll implement the onClick functions that enable users to interact with the modal and perform task-related actions. These functions will allow users to open the "Add new task" modal from the navbar and the "Edit task" modal by clicking the edit icon within individual task cards.

In the components/Navbar, include the openAddAndEditTaskModal among the imported functions from the appSlice:

 import { setCurrentBoardName, getCurrentBoardName, openAddAndEditTaskModal } from '../../redux/features/appSlice'

Then, modify the "+Add new task" button to incorporate an onClick function that triggers the "Add new task" modal:

Next, navigate to the BoardTasks component, where we will also implement the trigger for the "Edit task" modal.

Here, include the openAddAndEditTaskModal function among the imported functions from the appSlice:

import { openAddAndEditBoardModal, openAddAndEditTaskModal } from "@/components/redux/features/appSlice";

Then, update the React icon to incorporate the onClick function that triggers the "Edit Task" modal:

    
    dispatch(
      openAddAndEditTaskModal({
        variant: "Edit Task", title, index, name
      }),
    )
   }
   className="text-lg cursor-pointer"
   />;

Next, we'll create the Add and Edit Board modal component, also integrating its functionalities.

As depicted in the modal images presented at the start of this section, within the "Add New Task" modal, the title field is intended for the task's title a user wishes to add, and the status field should exclusively contain the accurate names of the columns. Any attempt to input a column name that doesn't exist will result in an error.

In the "Edit Task" modal, the title and status fields will display the current title and status of a task. Altering the title will update the task's title while modifying the status will relocate it to the desired column.

To begin, within your src/app/components directory, create a file named AddAndEditTaskModal.tsx, and firstly, insert the provided code to make the necessary imports, type definitions, and initial data for the add task modal:

 "use client";

import { useEffect, useState } from "react";
import { Modal, ModalBody } from "./Modal";
import { useAppDispatch, useAppSelector } from "@/components/redux/hooks";
import {
  getAddAndEditTaskModalValue,
  getAddAndEditTaskModalVariantValue,
  getAddAndEditTaskModalTitle,
  closeAddAndEditTaskModal,
  getCurrentBoardName,
  getAddAndEditTaskModalIndex,
  getAddAndEditTaskModalName,
} from "@/components/redux/features/appSlice";
import {
  useFetchDataFromDbQuery,
  useUpdateBoardToDbMutation,
} from "@/components/redux/services/apiSlice";
import { id } from '../utils/data'

interface ITaskData {
  id: string,
  title: string;
  status: string;
}
// initial task data for the add task modal
let initialTaskData: ITaskData = {
  id: id(),
  title: "",
  status: "",
};

export default function AddOrEditTaskModal() {
//variable declarations, functions, JSX
}

Next, go to the AddAndEditTaskModal function and paste the following code into it to declare variables and state values. The comments provided explain the future use of each of the declarations.

  let { data } = useFetchDataFromDbQuery();
  let [updateBoardToDb, { isLoading }] = useUpdateBoardToDbMutation();
  const [taskData, setTaskData] = useState();
  const [isTaskTitleEmpty, setIsTaskTitleEmpty] = useState();
  const [isTaskStatusEmpty, setIsTaskStatusEmpty] = useState();
  const [statusExists, setStatusExists] = useState(true);
  const [columnNames, setColumnNames] = useState<[]>();
  const dispatch = useAppDispatch();
  const isModalOpen = useAppSelector(getAddAndEditTaskModalValue);
  const modalVariant = useAppSelector(getAddAndEditTaskModalVariantValue);
  const isVariantAdd = modalVariant === "Add New Task";
  const closeModal = () => dispatch(closeAddAndEditTaskModal());
  const currentBoardTitle = useAppSelector(getCurrentBoardName);
  // get task title, index and name from redux store
  const currentTaskTitle = useAppSelector(getAddAndEditTaskModalTitle);
  const currentTaskIndex = useAppSelector(getAddAndEditTaskModalIndex);
  const initialTaskColumn = useAppSelector(getAddAndEditTaskModalName);

Here, we’ll implement functions responsible for the modal functionality. Just below the variable definitions above, paste the following functions:

  // Effect to set initial data for the modal based on the variant
  useEffect(() => {
    if (data) {
      const activeBoard = data[0].boards.find(
        (board: { name: string }) => board.name === currentBoardTitle
      );
      if (activeBoard) {
        const { columns } = activeBoard;
        const columnNames = columns.map(
          (column: { name: string }) => column.name
        );

        if (columnNames) {
          setColumnNames(columnNames);
        }

        if (isVariantAdd) {
          setTaskData(initialTaskData);
        }

        else {
          const activeTask = columns
            .map((column: { tasks: [] }) => column.tasks)
            .flat()
            .find((task: { title: string }) => task.title === currentTaskTitle);
          setTaskData(activeTask);
        }
      }
    }
  }, [data, modalVariant]);

  // Effect to clear error messages after a certain time
  useEffect(() => {
    const timeoutId = setTimeout(() => {
      setIsTaskStatusEmpty(false);
      setIsTaskStatusEmpty(false);
      setStatusExists(true);
    }, 3000);
    return () => clearTimeout(timeoutId);
  }, [isTaskStatusEmpty, isTaskTitleEmpty, statusExists]);

  // Handler for task title change
  const handleTaskTitleChange = (e: React.ChangeEvent) => {
    if (taskData) {
      const newTitle = { ...taskData, title: e.target.value };
      setTaskData(newTitle);
    }
  };

  // Handler for task status change
  const handleTaskStatusChange = (e: React.ChangeEvent) => {
    if (taskData) {
      const newTitle = { ...taskData, status: e.target.value };
      setTaskData(newTitle);
    }
  };

  // Handler to add new task to the db
  const handleAddNewTaskToDb = (e: React.FormEvent) => {

    e.preventDefault();
    const { title, status } = taskData!;

    if (!title) {
      setIsTaskTitleEmpty(true);
    }

    if (!status) {
      setIsTaskStatusEmpty(true);
    }

    // check if the status input exists among the existing columns
    const doesStatusExists = columnNames?.some(
      (column) => column === taskData?.status
    );

    if (!doesStatusExists) {
      setStatusExists(false);
    }

    // if all conditions are met
    if (title && status && doesStatusExists) {
      if (data) {
        const [boards] = data;
        const boardsCopy = [...boards.boards];
        const activeBoard = boardsCopy.find(
          (board: { name: string }) => board.name === currentBoardTitle
        );
        const activeBoardIndex = boardsCopy.findIndex(
          (board: { name: string }) => board.name === currentBoardTitle
        );
        const { columns } = activeBoard;
        // find the column in the board to update
        const getStatusColumn = columns?.find(
          (column: { name: string }) => column.name === status
        );
        const getStatusColumnIndex = columns?.findIndex(
          (column: { name: string }) => column.name === status
        );
        // desctructure tasks in a column. "Now" for example.
        const { tasks } = getStatusColumn;
        const addNewTask = [...tasks, { id: id(), title, status }]; //add new task
        const updatedStatusColumn = { ...getStatusColumn, tasks: addNewTask };
        //update the columns in a board
        const columnsCopy = [...columns];
        columnsCopy[getStatusColumnIndex] = updatedStatusColumn;
        const updatedBoard = {
          ...boards.boards[activeBoardIndex],
          columns: columnsCopy,
        };
        //update the board in the db
        boardsCopy[activeBoardIndex] = updatedBoard;
        updateBoardToDb(boardsCopy);
      }
    }
  };

  const handleEditTaskToDb = (e: React.FormEvent) => {
    e.preventDefault();
    const { title, status } = taskData!;
    if (!title) {
      setIsTaskTitleEmpty(true);
    }
    if (!status) {
      setIsTaskStatusEmpty(true);
    }
    // check if the status input exists among the existing status
    const doesStatusExists = columnNames?.some(
      (column) => column === taskData?.status
    );
    if (!doesStatusExists) {
      setStatusExists(false);
    }
    if (title && status && doesStatusExists) {
      if (data) {
        const [boards] = data;
        const boardsCopy = [...boards.boards];
        const activeBoard = boardsCopy.find(
          (board: { name: string }) => board.name === currentBoardTitle
        );
        const activeBoardIndex = boardsCopy.findIndex(
          (board: { name: string }) => board.name === currentBoardTitle
        );
        const { columns } = activeBoard;
        const getStatusColumnIndex = columns?.findIndex(
          (column: { name: string }) => column.name === status
        );

        // Check if the task status to edit is equal to the column.name
        if (status === initialTaskColumn) {
          const updatedStatusColumn = {
            ...columns[getStatusColumnIndex],
            tasks: columns[getStatusColumnIndex]?.tasks?.map(
              (task: any, index: number) => {
                if (index === currentTaskIndex) {
                  return { title, status };
                }
                return task;
              }
            ),
          };
          const columnsCopy = [...columns];
          columnsCopy[getStatusColumnIndex] = updatedStatusColumn;
          const updatedBoard = {
            ...boards.boards[activeBoardIndex],
            columns: columnsCopy,
          };
          //update the board in the db
          boardsCopy[activeBoardIndex] = updatedBoard;
          updateBoardToDb(boardsCopy);
        } else {
          // Find the column with the name in the task status and append the edited task
          const getStatusColumn = columns?.find(
            (column: { name: string }) => column.name === status
          );
          // delete task from previous column
          const getPrevStatusColumn = columns?.find(
            (column: { name: string }) => column.name === initialTaskColumn
          );
          const getPrevStatusColumnIndex = columns?.findIndex(
            (column: { name: string }) => column.name === initialTaskColumn
          );
          //update the previous column of the task
          const updatedPrevStatusColumn = {
            ...getPrevStatusColumn,
            tasks: getPrevStatusColumn?.tasks.filter(
              (_task: [], index: number) => index !== currentTaskIndex
            ),
          };
          // update the new column of the task
          const updatedStatusColumn = {
            ...getStatusColumn,
            tasks: [...getStatusColumn?.tasks, { title, status }],
          };
          const columnsCopy = [...columns];
          columnsCopy[getStatusColumnIndex] = updatedStatusColumn;
          columnsCopy[getPrevStatusColumnIndex] = updatedPrevStatusColumn;
          const updatedBoard = {
            ...boards.boards[activeBoardIndex],
            columns: columnsCopy,
          };
          //update the board in the db
          boardsCopy[activeBoardIndex] = updatedBoard;
          updateBoardToDb(boardsCopy);
        }
      }
    }
  };

Finally, in this component, paste the code below to implement the JSX of the modal:

return (
    
      
        {modalVariant}
        
          
            
              Title
            
            
              
            
            {isTaskTitleEmpty ? (
              Task title cannot be empty
            ) : (
              ""
            )}
          

          
            
              Status
            
            
              
            
            {isTaskStatusEmpty ? (
              
                Task status cannot be empty
              
            ) : !statusExists ? (
              Column does not exist
            ) : (
              ""
            )}
          
          
            
          
        
      
    
  );

Lastly, import and render the component in your src/app/page.tsx file as seen below:

   //rest of the imports
   import AddAndEditTaskModal from "./components/AddAndEditTaskModal";
     //rest of the code
     return (
    
      
      
      
        //render here
    
    );

With this functionality, you can effortlessly add tasks to any desired columns. For instance, let's add a new task titled "Buy tomatoes" to the "Next" column:

Likewise, we'll illustrate the task-editing feature by changing the column of "Launch version two" from "Now" to "Later":

Finally, in the next section, we'll implement the delete functionalities for both boards and tasks.

How to delete boards and tasks

By the end of this section, the "Delete Board" modal should look like this:

Likewise, the "Delete Task" modal:

As you can see, these modals share similarities, so we will use the same methodology as we did for the previous modal implementations.

To begin, let's update the initialState object in our appSlice to manage the state of the "Delete Board and Tasks" modal. Integrate the isDeleteBoardAndTaskModal state into the initialState object as illustrated below:

    const initialState = {
      //rest of the state
      isDeleteBoardAndTaskModal: { isOpen: false, variant: "",  title:'', status: "", index: -1 },

Next, include the following functions in the reducers object. These functions will be invoked to open and close the modal:

    // Open the delete board and task modal with a specified variant (delete board or task)
   openDeleteBoardAndTaskModal: (state, { payload }) => {
      state.isDeleteBoardAndTaskModal.isOpen = true;
      state.isDeleteBoardAndTaskModal.variant = payload.variant;
      state.isDeleteBoardAndTaskModal.title = payload.title;
      state.isDeleteBoardAndTaskModal.status = payload.status;
      state.isDeleteBoardAndTaskModal.index = payload.index;
    },
   // Close the delete board and task modal
   closeDeleteBoardAndTaskModal: (state) => {
      state.isDeleteBoardAndTaskModal.isOpen = false;
      state.isDeleteBoardAndTaskModal.variant = "";
      state.isDeleteBoardAndTaskModal.title = "";
      state.isDeleteBoardAndTaskModal.status = "";
      state.isDeleteBoardAndTaskModal.index = -1;
    },

Lastly, include the newly implemented functions and the selector functions in the exports:

 export const {
    openDeleteBoardAndTaskModal,
    closeDeleteBoardAndTaskModal,
   } = features.actions;

   // Delete task and board
   export const getDeleteBoardAndTaskModalValue = (state: RootState) => state.features.isDeleteBoardAndTaskModal.isOpen;
   // Selector function to retrieve variant state value 
   export const getDeleteBoardAndTaskModalVariantValue = (state: RootState) => state.features.isDeleteBoardAndTaskModal.variant;
   // Selector function to retrieve title state value 
   export const getDeleteBoardAndTaskModalTitle = (state: RootState) => state.features.isDeleteBoardAndTaskModal.title;
   // Selector function to retrieve status state value
   export const getDeleteBoardAndTaskModalStatus = (state: RootState) => state.features.isDeleteBoardAndTaskModal.status;
   // Selector function to retrieve index state value
   export const getDeleteBoardAndTaskModalIndex = (state: RootState) => state.features.isDeleteBoardAndTaskModal.index;

Following that, we'll implement the onClick functions to enable users to interact with the modal and execute delete-related actions. These functions will permit users to open the "Delete board" modal from the dropdown in the navbar and the "Delete task" modal by clicking the delete icon within individual task cards.

In the components/Dropdown.tsx file, add the openDeleteBoardAndTaskModal function to the list of imported functions from the appSlice:

import { openDeleteBoardAndTaskModal } from '@/components/redux/features/appSlice';

Then adjust the "Delete board" button to incorporate the onClick function to open the modal. This action will trigger the “Delete board” modal:

      "hover:bg-gray-300">

Move on to the BoardTasks component, and similarly, include the function for deleting tasks and boards among the imports from the appSlice:

      import {
         //other imports
         openDeleteBoardAndTaskModal
      } from "@/components/redux/features/appSlice";

Adjust the delete React icon to include the onClick function to open the modal:

      
            dispatch(
               openDeleteBoardAndTaskModal({
                  variant: "Delete this Task?",
                  status,
                  index,
               }),
            )
         }
         className="text-lg cursor-pointer text-red-500"
      />;

Now we'll start building the markup for the delete board and tasks modal, coupled with the implementation of its functionalities.

In your app/components folder, create a file named DeleteBoardAndTask modal and paste the provided code inside of it:

   import { Modal, ModalBody } from "./Modal";
   import { useAppDispatch, useAppSelector } from "@/components/redux/hooks";
   import {
   closeDeleteBoardAndTaskModal,
   getDeleteBoardAndTaskModalValue,
   getDeleteBoardAndTaskModalVariantValue,
   getDeleteBoardAndTaskModalTitle,
   getDeleteBoardAndTaskModalIndex,
   getDeleteBoardAndTaskModalStatus,
   getCurrentBoardName,
   } from "@/components/redux/features/appSlice";
   import {
   useFetchDataFromDbQuery,
   useUpdateBoardToDbMutation,
   } from "@/components/redux/services/apiSlice";

   export default function DeleteBoardAndTaskModal() {
     //variable declarations, functions, JSX
   }

Next, go to the DeleteBoardAndTaskModal function and paste the following code into it to declare variables and state values. The comments provided explain the future use of each of the declarations.

   const dispatch = useAppDispatch();
   const isModalOpen = useAppSelector(getDeleteBoardAndTaskModalValue);
   const closeModal = () => dispatch(closeDeleteBoardAndTaskModal());
   const currentBoardName = useAppSelector(getCurrentBoardName);
   const modalVariant = useAppSelector(getDeleteBoardAndTaskModalVariantValue);
   const taskTitle = useAppSelector(getDeleteBoardAndTaskModalTitle);
   const taskIndex = useAppSelector(getDeleteBoardAndTaskModalIndex);
   const taskStatus = useAppSelector(getDeleteBoardAndTaskModalStatus);
   let { data } = useFetchDataFromDbQuery();
   const [updateBoardToDb, { isLoading }] = useUpdateBoardToDbMutation();

Here, we’ll implement the function responsible for the modal functionality. Just below the variable definitions above, paste the following function:

   const handleDelete = (e: React.FormEvent) => {
    e.preventDefault();
    if (data) {
      if (modalVariant === "Delete this board?") {
        // Implement the logic for deleting the board
        if (currentBoardName) {
          //  Assuming data is available, you need to handle the logic to update the data
          const [boards] = data;
          const updatedBoards = boards.boards.filter(
            (board: { name: string }) => board.name !== currentBoardName
          );
          updateBoardToDb(updatedBoards);
        }
      } else {
        // Implement the logic for deleting a task
        if (taskIndex !== undefined && taskStatus && currentBoardName) {
          const [boards] = data;
          //  Handle the logic to update the tasks
          const updatedBoards = boards.boards.map(
            (board: {
              name: string;
              columns: [{ name: string; tasks: [] }];
            }) => {
            // check the board active board
              if (board.name === currentBoardName) {
                // loop through the columns of the board to find the column in which the task to edit is
                const updatedColumns = board.columns.map((column) => {
                  if (column.name === taskStatus) {
                    // delete the the task
                    const updatedTasks = column.tasks.filter(
                      (_, index: number) => index !== taskIndex
                    );
                    return { ...column, tasks: updatedTasks };
                  }
                  return column;
                });
                return { ...board, columns: updatedColumns };
              }
              return board;
            }
          );
          updateBoardToDb(updatedBoards);
        }
      }
    }
   };

Finally, in this component, paste the code below to implement the JSX of the modal:

   return (
    <Modal isOpen={isModalOpen} onRequestClose={closeModal}>
      <ModalBody>
        <p className="text-red font-bold text-lg">{modalVariant}p>
        <div className="pt-6">
          <p className="text-sm text-medium-grey leading-6">
            {modalVariant === "Delete this board?"
              ? `Are you sure you want to delete the '${currentBoardName}' board? This action will remove all columns
                and tasks and cannot be reversed.`
              : `Are you sure you want to delete the '${taskTitle}' tasks? This action cannot be reversed.`}
          p>
        div>
        <div className="pt-6 flex space-x-2">
          <div className="w-1/2">
            <button
              type="submit"
              onClick={(e: React.FormEvent<HTMLButtonElement>) =>
                handleDelete(e)
              }
              className="bg-red-500 rounded-3xl py-2 w-full text-sm font-bold"
            >
              {" "}
              {isLoading ? "Loading" : "Delete"}
            button>
          div>
          <div className="w-1/2">
            <button
              onClick={closeModal}
              className="bg-stone-200 rounded-3xl py-2 w-full text-sm font-bold"
            >
              Cancel
            button>
          div>
        div>
      ModalBody>
    Modal>
   );
   }

After making this update, import the component in the page.tsx and render it as seen below:

     //rest of the imports
     import DeleteBoardOrTaskModal from "./components/DeleteBoardAndTaskModal";
     //rest of the code
       return (
    
      
      
      
      
      
    
    );

After rendering the component, you can now delete a board. As an example, we’ll delete the “Marketing” board we previously created:

Likewise, you can delete a task:

In the next section, we’ll explore the implementation of the drag and drop functionality with the react-beautiful-dnd library.

How to Implement Drag and Drop Functionality

At the end of this section, you should be able to move tasks between columns and across columns.

To begin, install the react-beautiful-dnd library with the following command:

npm i react-beautiful-dnd

It’s worth noting that the react-beautiful-dnd library does not work inside the StrictMode wrapper which is enabled by default in the app router. So we have to create a custom hook which will enable us use the react-beautiful-dnd library safely with StrictMode.

Create a file named StrictModeDroppable.tsx inside your src/app/components folder and paste the provided code below inside of it:

import { useEffect, useState } from "react";
import { Droppable, DroppableProps } from "react-beautiful-dnd";

export const StrictModeDroppable = ({ children, ...props }: DroppableProps) => {
  const [enabled, setEnabled] = useState(false);

  useEffect(() => {
    const animation = requestAnimationFrame(() => setEnabled(true));

    return () => {
      cancelAnimationFrame(animation);
      setEnabled(false);
    };
  }, []);

  if (!enabled) {
    return null;
  }

  return {children};
};

This way, we have made it compatible with StrictMode, allowing us to safely implement the drag and drop feature.

Next, navigate to the BoardTasks.tsx component and update it with the code below:

Firstly, import needed components from the react-beautiful-dnd library and also from our custom StrictModeDroppable.tsx component:

//import useRef hook
import { useEffect, useState, useRef } from "react";
import { DragDropContext, Draggable } from "react-beautiful-dnd";
// import Droppable from the custom hook
import { StrictModeDroppable as Droppable } from "./StrictModeDroppable";

After updating the imports, go to the BoardTasks function and include the following functions:

// check if it’s the first render
const initialRender = useRef(true);


  const handleDragEnd = async ({ destination, source }: any) => {
    // Check if the destination is not null (i.e., it was dropped in a valid droppable)
    if (!destination) return;


    // get a deep nested copy of the columns state
    const newColumns = columns.map((column) => ({
      ...column,
      tasks: [...column.tasks], // Create a new array for tasks
    }));


    // Find the source and destination columns based on their droppableIds
    const sourceColumnIndex = newColumns.findIndex(
      (col) => col.id === source.droppableId
    );
    const destinationColumnIndex = newColumns.findIndex(
      (col) => col.id === destination.droppableId
    );


    // Task that was dragged
    const itemMoved = newColumns[sourceColumnIndex]?.tasks[source.index];


    // Remove from its source
    newColumns[sourceColumnIndex].tasks.splice(source.index, 1);


    // Insert into its destination
    newColumns[destinationColumnIndex].tasks.splice(
      destination.index,
      0,
      itemMoved
    );


    // Update the state
    setColumns(newColumns);
  };


  useEffect(() => {
    // Check if it's the initial render, to avoid sending the data to the backend on mount
    if (!initialRender.current) {
      // Update the backend with the new order
      try {
        if (data) {
          const [boards] = data;
          const boardsCopy = [...boards.boards];
          const activeBoardIndex = boardsCopy.findIndex(
            (board: { name: string }) => board.name === currentBoardTitle
          );
          const updatedBoard = {
            ...boards.boards[activeBoardIndex],
            columns,
          };
          boardsCopy[activeBoardIndex] = updatedBoard;
          updateBoardToDb(boardsCopy);
        }
      } catch (error) {
        // Handle error
        console.error("Error updating board:", error);
      }
    } else {
      // Set initial render to false after the first render
      initialRender.current = false;
    }
  }, [columns]);

So far here, we implemented a function which will be triggered after a task has been dragged. After each trigger of this function, the columns data is being updated and sent to the Cloud Firestore via the useEffect hook. I added some more comments in the code to help you understand better.

Finally, update the JSX in the return statement as seen below:

 return (
    
      {/* If data has not been fetched successfully, display a loading state, else display the column of tasks */}
      {isLoading ? (
        
          Loading tasks...
        
      ) : (
        <>
          {/* If columns of tasks isn't empty: display the tasks, else display the prompt to add a new column */}
          {columns.length > 0 ? (
            
              
                {columns.map((column, index) => {
                  const { id, name } = column;
                  return (
                    
                      {`${column.name} (${
                        column.tasks ? column.tasks?.length : 0
                      })`}
                      
                        {(provided) => (
                          
                            {column.tasks &&
                              // Display the tasks if there are tasks in the column, if not, display an empty column
                              (column.tasks.length > 0 ? (
                                column.tasks.map((task, index) => {
                                  const { id, title, status } = task;
                                  return (
                                    
                                      {(provided) => (
                                        
                                          {task.title}
                                          
                                            
                                                dispatch(
                                                  openAddAndEditTaskModal({
                                                    variant: "Edit Task",
                                                    title,
                                                    index,
                                                    name,
                                                  })
                                                )
                                              }
                                              className="text-lg cursor-pointer"
                                            />
                                            
                                                dispatch(
                                                  openDeleteBoardAndTaskModal({
                                                    variant:
                                                      "Delete this task?",
                                                    title,
                                                    status,
                                                    index,
                                                  })
                                                )
                                              }
                                              className="text-lg cursor-pointer text-red-500"
                                            />
                                          
                                        
                                      )}
                                    
                                  );
                                })
                              ) : (
                                
                              ))}
                            {provided.placeholder}
                          
                        )}
                      
                    
                  );
                })}
                {/* If the number of columns of tasks is less than 7, display an option to add more columns */}
                {columns.length < 7 ? (
                  
                      dispatch(openAddAndEditBoardModal("Edit Board"))
                    }
                    className="rounded-md bg-white w-[17.5rem] mt-12 shrink-0 flex justify-center items-center"
                  >
                    
                      + New Column
                    
                  
                ) : (
                  ""
                )}
              
            
          ) : (
            
              
                
                  This board is empty. Create a new column to get started.
                
                
              
            
          )}
        
      )}
    
  );

In the code snippet above, we wrapped DragDropContext around the columns of tasks with its onDragEnd attribute, which accepts the handleDragEnd function, which will be triggered after a task has been dragged.

Don’t forget that after each trigger of this function, the columns data is being updated and sent to the Cloud Firestore via the useEffect hook.

Each column of task is also wrapped around the Droppable component. This signifies that this is a location you can drop a task. It also accepts a droppableId attribute which we passed the id of each column to it.

Each task card is also wrapped around the Draggable component, this makes them draggable within and among columns.

With these changes, we have easily implemented the drag and drop feature for our app:

Conclusion

This tutorial guided you through implementing authentication using the next-auth library, setting up a Redux store, and integrating Firebase with its RTK Query in Next.js applications.

You also learned to implement CRUD operations in a Kanban task management app, and looked into form validations with JavaScript.

And finally, we covered the implementation of drag-and-drop functionality using the react-beautiful-dnd library.

Across the tutorial, we also leveraged existing libraries to streamline development rather than building everything from scratch.

If you want to see all the code, you can visit the project's GitHub repository here. Feel free to fork the project and open a PR if you feel the need for any improvements. If you’d also like to play around with the live site, you can find it here.

If you'd also like to explore this project with more advanced features, like dark mode, sleeker UI design, and better functionalities, visit it here.

MERN Stack Roadmap – How to Learn MERN and Become a Full-Stack Developer

Chris Blakely — Thu, 04 Jan 2024 00:57:45 +0000

Have you ever wondered how modern web applications are built? How you can learn and master the technologies that you can use to build your own full stack projects from scratch?

In this handbook, I'm going to introduce you to the MERN stack, a widely-used technology stack embraced by many leading companies. I'll guide you through 7 essential steps to start learning these technologies on your own.

By the time you finish reading, you'll have a solid understanding of what the MERN stack entails, its component technologies, and various resources for learning. You'll also have 10 project ideas that you can develop and showcase in your portfolio.

What is the MERN stack?
The MERN Stack Roadmap
Top Resources to learn the MERN Stack
10 project ideas you can try today
Wrapping up the MERN stack journey

What is the MERN stack?

The MERN stack, comprising MongoDB, Express.js, React, and Node.js, is a cohesive set of technologies used for building efficient and scalable web applications.

Its popularity stems from the seamless integration of each component: MongoDB's flexible data handling, Express.js's efficient server-side networking, React's dynamic user interfaces, and Node.js's powerful back-end runtime environment.

For beginners, the MERN stack is a smart choice because it uses JavaScript across all layers, simplifying the learning curve. This uniformity, coupled with a strong community and ample learning resources, makes it an accessible and practical toolkit for anyone looking to dive into full-stack development.

The MERN stack is also heavily utilized in the industry, favored by startups and large enterprises alike for its efficiency and the robust, modern web applications it can produce. This industry adoption not only validates its effectiveness but also opens up numerous career opportunities for those skilled in these technologies.

Let's look at a brief overview of what each part of the MERN Stack looks like:

Frontend (React)

The frontend of a website is like the dining area of a restaurant. It's everything you see and interact with directly on a website – the layout, design, buttons, and text.

Example: When you visit a website and see a beautiful homepage, interact with menus, or fill out forms, you're experiencing the frontend.

Backend (Node.js)

The backend is like the kitchen in a restaurant. It's where all the behind-the-scenes work happens. It includes the server, applications, and databases that work together to process the information you see on the frontend.

Example: When you order food (submit a form on the website), the kitchen (backend) processes the order (the data) and prepares your meal (the information or service you requested).

Database (MongoDB)

A database in web development is similar to a restaurant’s pantry or storage where all the ingredients (data) are kept. It stores and manages all the information needed by the website, like user profiles, content, and other data.

Example: In an online store, the database stores product information, prices, user reviews, and customer details.

REST APIs (Express)

REST APIs are like the waiters in a restaurant. They are the messengers or go-betweens for the frontend and backend. They take requests (like orders) from the frontend (customer), fetch or update data in the backend (kitchen), and then return responses (prepared orders).

The terms POST, PUT, DELETE, and GET are types of requests used in REST APIs:

POST: Used to create new data. Like placing a new order in the restaurant.
PUT: Used to update existing data. Similar to changing an order you've already placed.
DELETE: Used to remove data. Like cancelling an order.
GET: Used to retrieve data. Comparable to asking about the menu or checking the status of your order.

The MERN Stack Roadmap

STEP 1: Learn the right amount of HTML, JavaScript, and CSS

The MERN stack uses JavaScript heavily, so its a natural first step to learn. In this section you will look at the main things you will use day-to-day when creating full-stack MERN apps.

Understanding JavaScript is like knowing the right amount of ingredients needed for a recipe. You don't need to master everything at once, just the essential ingredients that make your particular dish (or your web project) come to life.

Variables

Variables in JavaScript are like labelled jars in your kitchen. You can store things in them (like numbers, text) and use these jars later in your cooking (or coding).

Example: A variable storing the user's name, so you can use it later to say "Hello, [Name]!"

Functions

Functions are like recipes in a cookbook. They are sets of instructions that perform a specific task. You can reuse these recipes whenever you need to perform that task again.

Example: A function that calculates the total price of items in a shopping cart.

Objects & Arrays

Objects are like information cards holding details about something (like a contact card), and arrays are like lists.

Example of an Object: A card holding a user's information (name, age, email).
Example of an Array: A list of all the user's favorite book titles.

If/else Statements, Switch Statements

These are like decision-making processes. If/else statements are like choosing what to wear based on the weather, and switch statements are like a more complex decision, like choosing what to cook based on multiple ingredients you have.

Example: If it's raining (if), take an umbrella (else), take sunglasses.

Callbacks/Promises/Async Await

These are ways to handle tasks that take some time, like ordering food and waiting for it. Callbacks are like calling a friend to do something when they’re free. Promises are like your friend promising to do it. Async-await is like making a plan to do tasks one after another in an organized way.

Example: Ordering a coffee (a task) and waiting to get it before leaving the cafe (ensuring order of actions).

ECMAScript (Template Strings, Destructuring Assignment, Spread Operator, Default Parameters, and so on)

These are advanced tools and shortcuts in JavaScript to make coding easier and cleaner. It's like having a food processor in your kitchen that makes chopping and mixing faster and more efficient.

Example: Automatically creating a welcome message like "Hello, [Name]!" without manually joining words and variables.

TypeScript

TypeScript is like JavaScript but with more rules for organizing your code (like a more detailed recipe book). It helps in managing larger projects by adding types to your code, making sure you don’t mix incompatible ingredients. This guide teaches you TypeScript basics.

Example: Specifying that a function should only take a number as an input, not text or anything else.

STEP 2: Get Familiar with React

Once you've got a feel for JavaScript, its time to venture into the wonderful world of frontend development.

React.js is a popular JavaScript library used for building user interfaces, particularly known for its efficiency in rendering dynamic, interactive web pages. It enables developers to create large web applications that can change data, without reloading the page, making for a smoother user experience.

Below is a list of common things you want to know when working with React.

Components

Think of components as individual LEGO blocks in a large LEGO model. Each block is a small, reusable piece that you can use to build different parts of your web application.

Example: A 'button' component in a website that can be used in many places, like for submitting a form or closing a pop-up.

JSX (JavaScript XML)

JSX lets you write your website's design code (like HTML) inside your JavaScript code. It's like writing the recipe and the cooking instructions in one place for easier reference.

Example: Writing a piece of JSX code that includes both JavaScript and HTML-like tags to create a user login form.

Props (Properties)

Props are like instructions or settings you pass to your LEGO blocks (components) to tell them what they should look like or do.

Example: Passing a 'color' prop to a 'button' component to make it red or blue depending on the situation.

State

State is like a personal notebook for each component, where it keeps track of its own information, like whether a button is clicked or not. Here's a course all about state management in React.

Example: A 'like' button keeping track of whether it has been clicked (liked) or not.

Hooks

Hooks are special tools in React that let you add features like state to your components without needing to use complex code structures.

Example: Using the useState hook to keep track of a counter in a component.

Event Handling

This is how you tell a component to do something when a user interacts with it, like clicking a button or entering text in a form.

Example: Setting up an event handler so that when a user clicks a 'submit' button, it sends their information to the server.

Conditional Rendering

This is like having a magic painting that can change its picture based on certain conditions. In React, you can show different components based on different conditions.

Example: Showing a 'login' button if a user is not logged in, and a 'logout' button if they are.

Lists and Keys

Keys are like name tags for items in a list. They help React keep track of which items are new, changed, or removed.

Example: Displaying a list of messages in a chat app, where each message has a unique key.

Context API

The Context API a way to share information (like a theme setting or user data) across many components without passing the information through each level manually.

Example: Using Context API to share the current logged-in user's information across different components in a web app.

Fragment

Fragments let you group several components or elements together without adding extra layers to the website. It's like putting multiple LEGO pieces on a baseplate without the baseplate being part of the final model.

Example: Grouping a list of items together in a menu without adding extra wrappers or divs around them.

STEP 3: Understand REST API's and how a backend server works using Express/Node

Every UI needs a way to store and retrieve the data it needs to make the frontend work. This is where our backend comes in.

In the MERN stack, the backend is composed of 3 main bits: Express, a Node.js server, and a database. We'll cover the database shortly, for now we'll focus on the Express/Node pieces of the MERN stack, as they're closely related.

Express.js is a lightweight, flexible framework for Node.js, designed to build web applications and REST APIs with ease and efficiency. Node.js is a powerful JavaScript runtime that allows for the development of scalable server-side applications, making the duo a popular choice for backend development.

Node.js: Foundation for Building Web Applications

Think of Node.js as the foundation for constructing a modern building. It's a platform that lets you build web applications, similar to how you would use a set of basic tools and materials to start building a house. You might hear this being to referred to as the "backend".

Example: Building a chat application where multiple users can send messages in real-time.

Express: Streamlining REST API Development

Express is a helper tool for Node.js. It's like having a pre-built kit that makes building certain parts of your house easier and faster, providing templates and shortcuts so you don't have to start from scratch.

Example: Using Express to quickly set up routes for a website, like a route to a contact page or a product catalog.

Modules and Packages: Ready-Made Components

In Node.js, modules are like pre-made components or sections of a house (like a bathroom unit or a kitchen set) that you can simply choose and add to your building project.

Example: Adding a 'date-time' module to display current times and dates on your web application.

Node Package Manager (NPM): The Tool and Material Warehouse

NPM acts like a vast warehouse where you can find all sorts of tools and materials (modules) you might need. It's a central place to get additional resources for building your web applications.

Example: Installing 'body-parser' from npm to handle JSON data in your web application.

Routing: Directing Web Traffic

Routing in Express is like setting up roads and paths in a housing complex. It's about directing the flow of traffic (data and user requests) to different parts of your web application.

Example: Creating routes in an online store, like /products for the product list and /products/:id for individual product details.

Middleware: Additional Functional Layers

Middleware in Express can be seen as extra layers or services in your building, like security, plumbing, or electrical systems. They add specific functionalities to your web application.

Example: Adding 'cookie-parser' middleware to handle cookies in your web application.

Request and Response: Communication Channels

Requests and responses in Express are like sending and receiving mail or messages. They are the way your web application communicates with users, sending them data or receiving their inputs.

Example: Your application receiving a user's login request (request) and then sending back a confirmation message (response).

Environment Variables: Secure Storage Spaces

Think of environment variables as secure storage spaces or safes in your building. They're used to store sensitive information like passwords or personal settings, keeping them secure and separate from the main construction.

Example: Storing the database connection string in an environment variable to keep it secure.

Security: Building Safeguards

In the context of web applications, security is about building safeguards into your project. It's like installing locks, security systems, and fire safety measures in a building to protect it from various threats.

Example: Implementing HTTPS to secure data transmission and using JWT (JSON Web Tokens) for user authentication to protect user data.

STEP 4: Storing data with MongoDB and Mongoose

MongoDB is a NoSQL database that offers high flexibility and scalability for storing and managing data, making it ideal for handling large volumes and diverse types of data.

Mongoose is an Object Data Modeling (ODM) library for MongoDB, providing a straightforward schema-based solution to model application data, enhancing database interaction with useful features and validation.

MongoDB: A NoSQL Database

MongoDB is a type of database that stores data in a flexible, JSON-like format. This makes it different from traditional databases, which use tables and rows. It's great for handling large volumes of data and is very scalable.

Example: Using MongoDB to store user profiles where each profile can have different fields.

Collections and Documents

In MongoDB, data is stored in 'collections', which are similar to tables in a relational database. Inside these collections, data is stored in 'documents'. Think of a document as a single record in your collection, like an entry in a diary or a contact in an address book.

Example: A 'users' collection with documents each representing a user with details like name and email.

Mongoose: A MongoDB Object Modeling Tool

Mongoose is a library for Node.js that makes it easier to interact with MongoDB. It provides a straightforward, schema-based solution to model your application data. It's like having a personal assistant to help manage the communication between your application and MongoDB.

Example: Using Mongoose to easily add, retrieve, and manage user data in a MongoDB database.

Schemas

In Mongoose, a schema is a structure that defines the format of the data to be stored in MongoDB (like defining fields and data types). Think of it as a blueprint for how your data should look.

Example: Creating a Mongoose schema for a blog post with fields like title, author, and content.

Models

A model in Mongoose acts as a constructor, compiled from the Schema definitions. It represents documents in a MongoDB database. Models are responsible for creating and reading documents from the underlying MongoDB database.

Example: Defining a 'User' model based on a user schema to interact with the 'users' collection in the database.

CRUD Operations

CRUD stands for Create, Read, Update, Delete. These are the basic operations you can perform on the database. Mongoose provides easy methods to execute these operations on your data.

Example: Using Mongoose methods to add new users, find users by name, update user information, or delete users.

Connecting to MongoDB

You can use Mongoose to connect your Node.js application to a MongoDB database. This is like setting up a phone line between your application and the database so they can talk to each other.

Example: Writing a Mongoose connect function to link your Node.js application to a MongoDB database hosted on Atlas.

Querying Data

Mongoose allows you to query your MongoDB database. This means you can search for specific data, filter your data based on certain criteria, and more.

Example: Using a Mongoose query to find all blog posts written by a specific author.

Data Validation

Mongoose provides built-in validation. This is a way to make sure the data being saved to your database is in the right format, like checking if an email address looks like an email address.

Example: Defining a schema in Mongoose where the email field must match the format of an email address.

Middleware (Pre and Post Hooks)

Mongoose middleware are functions which can be executed automatically before or after certain operations, like saving a document. They're useful for complex logic like hashing passwords before saving them to the database.

Example: Using a pre-save middleware in Mongoose to hash user passwords before saving them to the database.

Indexes

Indexes in MongoDB are used to improve the performance of searches. They are similar to indexes in a book, helping the database find data faster.

Example: Creating an index on the 'email' field in a user collection to speed up the search for users by email.

Aggregation

Aggregation in MongoDB is a powerful way to process data and get computed results. It's like having a sophisticated calculator to perform complex operations on your data, such as summing up values or averaging them.

Example: Using MongoDB's aggregation framework to calculate the average number of comments on blog posts.

STEP 5: Writing Tests

Testing in software development is like a safety check to ensure everything in your application works as expected. It's a crucial step in the development process where you look for bugs or issues before your users do. Think of it like proofreading an essay or checking a car before a road trip – it helps catch and fix problems early.

There are different types of testing, each serving a unique purpose:

Unit Testing

This is the most basic form of testing. Here, you test individual parts of your code (like functions or components) in isolation. It's like checking each light bulb in a string of Christmas lights.

In the MERN stack, tools like Jest or Mocha are commonly used for this. They let you write small tests to check if a specific part of your application behaves as expected.

Integration Testing

This type of testing checks how different parts of your application work together. It's like making sure all the light bulbs light up when connected and the string is plugged in.

For the MERN stack, you might still use Jest or Mocha, combined with other tools like Chai for assertions, to ensure that different components or services in your application interact correctly.

End-to-End (E2E) Testing

Here, you test your application's workflow from start to finish. It's like checking if the entire Christmas tree lights up and twinkles as expected.

For a MERN stack application, Cypress or Selenium are popular choices. They simulate real user scenarios, ensuring the entire application, from the front end in React to the back end with Express and Node.js, functions smoothly together.

Performance Testing

This checks if your application can handle stress, like heavy traffic or data processing. It's akin to ensuring the Christmas tree lights don't blow a fuse when they're all on. Tools like Loader.io or Apache JMeter can be used here.

Each type of testing serves to ensure a different aspect of your application is working correctly, and together, they contribute to building a robust, reliable, and user-friendly application.

By employing these tests in the MERN stack, you not only catch bugs early but also maintain a high standard of quality for your application.

STEP 6: Using Git

Git is a version control system, a tool that tracks changes in your code over time. Think of it like a detailed diary for your coding project. Every time you make changes to your code, Git keeps a record of what was changed, when, and by whom. This becomes incredibly useful when you’re working on complex projects, like those involving the MERN stack.

Why is Git so important when building with the MERN stack, or any software for that matter?

Collaboration

Git is like a team playbook. It allows multiple developers to work on the same project without stepping on each other's toes.

Everyone can work on different features or parts of the application simultaneously (like MongoDB database schemas, React components, or Express.js routes). Git helps manage these contributions, ensuring changes can be merged smoothly into the main project.

Tracking Changes

Imagine you've made changes to your React component, and suddenly things aren't working as they used to. Git allows you to go back in time and see what changes were made and by whom.

This historical data is invaluable for understanding how your project evolved and for fixing issues without having to start from scratch.

Branching and Merging

Git’s branching feature lets you diverge from the main line of development and experiment with new features or ideas in a controlled way.

You can create a branch, make your changes, and then merge those changes back into the main project when they're ready. This ensures the main project (often referred to as the 'master' or 'main' branch) remains stable.

Backup and Restore

With Git, your project's entire history is stored in the repository. If anything goes wrong, you can roll back to a previous state. It’s like having a fail-safe backup system.

Documentation

Commit messages in Git provide a narrative for your project. They allow you to document what changes were made and why, which is extremely helpful for both your future self and other developers who might work on the project.

When building applications with the MERN stack, Git offers a safety net and a collaborative workspace. It keeps your project organized, tracks every change, and allows multiple developers to work together more efficiently.

Using Git is essential for managing complex development projects in today's software development world.

STEP 7: Deployments

Code deployment is the process of taking code written by developers and making it operational on a live environment where users can interact with it.

In the context of the MERN stack, which involves technologies like MongoDB, Express.js, React, and Node.js, deployment is the final step in the journey of bringing a full-stack application to life.

Imagine you've built a house (your web application). Deployment is like moving it from the construction site (development environment) to its actual location where people can live in it (production environment). This process involves several key steps to ensure that everything works as expected when users access your app.

Preparing for Deployment

Before deploying, you need to prepare your application. This involves ensuring your code is complete and tested, dependencies are properly managed, and your app is configured for the production environment.

For MERN stack applications, this might mean setting up environment variables, configuring your database (MongoDB) connection for production, and optimizing your React front-end for performance.

Hosting and Servers

Choosing where to host your application is crucial. For MERN stack apps, you can use cloud-based hosting services like AWS, Heroku, or DigitalOcean. These platforms offer services to host both your Node.js backend and MongoDB database, and they often provide additional features like scaling, monitoring, and security.

Continuous Integration/Continuous Deployment (CI/CD)

CI/CD is a methodology that automates the deployment process. Whenever you make changes to your codebase (like fixing a bug or adding a new feature), CI/CD tools automatically test your code and deploy it if the tests pass. This ensures that your application is always up-to-date with the latest changes.

Tools like Jenkins, Travis CI, or GitHub Actions are commonly used for this purpose.

Monitoring and Maintenance

After deployment, it’s important to monitor your application for any issues and perform regular maintenance. This could involve checking server logs, updating dependencies, or rolling out fixes for any bugs that might arise.

Rollbacks

A good deployment strategy also includes plans for rollbacks. If something goes wrong after deployment, you need to be able to revert to the previous version quickly to minimize downtime.

In the MERN stack, each component (MongoDB, Express.js, React, and Node.js) might require specific considerations for deployment. For instance, you might use Docker containers to package your Node.js and Express.js backend, ensuring it runs consistently across different environments. React apps might be minified and bundled for optimal performance.

In essence, deployment in the MERN stack is about getting your application from your local machine to a server where it can serve users reliably and efficiently. It involves careful planning, choosing the right hosting solutions, automating the process as much as possible, and being prepared to address issues post-deployment.

Top Resources to Learn the MERN Stack

Now that you have a pretty good idea of what you need to learn to master the MERN stack, lets look at a list of free resources you can start using today to begin your journey!

The freeCodeCamp curriculum is one of the best places to learn how to code for free. The curriculum is super in depth and covers alot of the topics mentioned in this post.
The freeCodeCamp YouTube channel has a ton of free courses you can try as well. This MERN stack book project is an excellent one for beginners.
Full Stack open is another good resource. It doesn't teach MongoDB but you learn about SQL instead which is equally as useful.
My MERN stack hotel booking app project on YouTube is a free 15 hour course where you will learn everything talked about in this post.

10 Project Ideas You Can Try Today

One of my favourite ways to learn new technologies is to build projects. If you're struggling with coming up with ideas, here's 10 projects you can start building today. I'll be building some of these on my YouTube channel so feel free to subscribe to stay up to date!

Personal Blog Website

Functionality: Users can read posts, and the admin can create, edit, or delete posts.
Learning Focus: Basic CRUD operations, user authentication, integrating React with Express API, and using MongoDB for data storage.

Task Manager (To-Do List)

Functionality: Users can add, view, edit, and delete tasks. Tasks can have deadlines and priority levels.
Learning Focus: React state management, Express route handling, MongoDB operations, and basic UI development.

Simple E-commerce Site

Functionality: Display products, add to cart, and checkout functionality. Admin features for adding or removing products.
Learning Focus: React components for product listing, cart management, Express.js for product APIs, MongoDB for product data, and handling user inputs.

Functionality: Users can post, view, edit, and delete recipes. Implement a rating or comment system for interaction.
Learning Focus: File upload for images, user-generated content management, and MongoDB schema design.

Budget Tracker

Functionality: Users can input their expenses and income, categorize them, and view a summary of their finances.
Learning Focus: Handling forms in React, creating RESTful services with Express, and effective data structuring in MongoDB.

Event Planning Application:

Functionality: Users can create and manage events, send invitations, and track RSVPs.
Learning Focus: Date handling in JavaScript, complex MongoDB documents, and Express middleware for authentication.

Fitness Tracker:

Functionality: Log workouts, track progress over time, set fitness goals.
Learning Focus: Data visualization with React, creating API endpoints for varied data types, and MongoDB for storing time-series data.

Chat Application:

Functionality: Real-time chat rooms, private messaging, and user profiles.
Learning Focus: WebSockets with Node.js for real-time communication, MongoDB for message storage, and React for dynamic UI updates.

Book Review Platform:

Functionality: Users can post book reviews, rate books, and browse reviews by other users.
Learning Focus: Integrating external APIs for book data, user-generated content moderation, and complex querying in MongoDB.

Local Business Directory:

Functionality: Listing of local businesses with categories, user reviews, and contact information.
Learning Focus: Geolocation, advanced querying and indexing in MongoDB, and creating a responsive layout with React.

Wrapping Up the MERN Stack Journey

As we reach the end of our exploration of the MERN stack, I hope this guide has illuminated the path for your journey into the world of full-stack development.

We've covered the fundamental components – MongoDB, Express.js, React, and Node.js – and delved into the practical aspects of building, testing, and deploying applications using this versatile stack.

Remember, the road to mastering the MERN stack is both challenging and rewarding. Each project you undertake will add to your skills and confidence. Use the resources and project ideas provided as stepping stones to build your portfolio and deepen your understanding.

The beauty of the MERN stack lies in its community-driven nature, so don't hesitate to seek help, collaborate, and share your experiences.

If you want to get in touch, you can reach me over at LinkedIn, or drop a comment on my YouTube channel. Good luck and happy coding!

Full Stack Project Tutorial – Create a Recipe App Using React, Node.js and PostgreSQL

Chris Blakely — Thu, 19 Oct 2023 20:31:03 +0000

In this in-depth tutorial, we'll build a full stack recipe app from scratch, using React, Node.js, Postgres and the Spoonacular API. We'll cover features such as:

Building an API server in Node
Integrating securely with a 3rd party API
Interacting with a Postgres database using Prisma
Making API requests from React
Creating reusable components
Working with pagination
Working with UI elements such as tabs, image grids, modals and styling

Let's dive in.

Prerequisites
GitHub Repositories
Video Tutorial
Project Architecture
How to Setup the Backend
How to Setup the Database and Prisma
How to Get and Secure a Spoonacular API Key
How to Create the Search Endpoint
How to Setup the Frontend
How to Call the Search API and Display Results on the Frontend
How to Create the Search Input and Recipe Card Component
How to Build the Pagination and View More Functionality
How to Build the Recipe Summary Modal Component
How to Create Endpoints to Get/Create/Delete Favorite Recipes
How to Add Favorites Functionality to the Frontend
How to Adding CSS/Styling
Conclusion

Prerequisites

Since we will be focusing on how to build a project, there are a few prerequisites that will be needed to get the most out of this tutorial:

Some knowledge about web development concepts (frontend, backend, databases, API's, REST).
Some knowledge of JavaScript (variables, functions, objects, arrays, and so on).
Basic understanding on React (how to create components, add styles, work with state).
Basic understanding on Node.js/Express (working with APIs).

GitHub Repositories

Completed Code

You can find the completed code on GitHub by clicking here, or clone the repo:

git clone git@github.com:chrisblakely01/react-node-recipe-app.git

Starter Code

If you want to save some time and skip the initial setup, you can find the starter code here. This has a skeleton frontend/backend project already setup, as well as the basic layout and CSS. Or clone the repo:

git clone git@github.com:chrisblakely01/react-node-recipe-app-starter.git

Video Tutorial

If you'd like to learn from the video version as well, here it is:

Project Architecture

Here's a diagram that illustrates how the various components of our app will interact with each other:

Diagram illustrating the various components of the app

We will have a React front end and a Node backend. These two will communicate through specific endpoints. We will establish five endpoints, all housed within our backend.

We can categorize these endpoints into two distinct groups. The first group will cater to recipe searches. It will invoke the recipe API and return the results based on a given search query. Our front end will initiate a call to our backend, which will then relay the search request to the recipe API.

We choose not to call the recipe API directly from our front end because it requires an API key—a form of authentication similar to a password. Exposing this key in our front end code could lead to unauthorized access if someone delves into the code through their browser to retrieve the API key.

It's a more secure practice to house the API key on our backend within environment variables. From there, we can call the recipe API and then transmit the response back to our front end.

This approach aligns with common practices in production environments. It also offers the flexibility to modify the data on the backend, if necessary, before sending it back to the front end. And it enhances performance, as the UI will not have to manage multiple API requests to and from the recipe API.

That's the essence of how our search functionality will operate. We'll also have several endpoints to add, create, and delete favorites. These favorites will be stored in our own database, providing a clear picture of what we aim to build.

How to Setup the Backend

In this tutorial, we will walk through the process of building a full-stack recipe application. We'll set up the backend, create the frontend, and link it to a database. We will also connect to a recipe API using an API key.

If you prefer to skip the setup, a starter code is available on CodeCoyotes, which includes some basic setup and CSS. But you'll still need to create a database and obtain an API key.

Let’s start by setting up our workspace:

Step 1: Setup Your Workspace

Start by opening Visual Studio Code (or your preferred code editor). Create a new folder named recipe-app on your desktop or another location. Then drag this folder into the Visual Studio Code window to open it.

Your folder structure should now look like this:

recipe-app

Step 2: Setup the Backend

In the recipe-app folder, create another folder named backend.

Navigate to View -> Terminal in Visual Studio Code to open a terminal. Change your directory to the backend folder using the command cd backend.

Type npm init to initialize a new npm package, then hit Enter to move through the prompts. For the entry point, type ./src/index.ts and hit Enter.

Your folder structure should now look like this:

recipe-app
|-- backend
    |-- package.json

Step 3: Install the Dependencies

First, install the necessary dependencies using the following command:

npm install express prisma @prisma/client cors

Now, install the development dependencies:

npm install --save-dev ts-node typescript nodemon @types/cors @types/express @types/node

Your folder structure should now look like this:

recipe-app
|-- backend
    |-- node_modules
    |-- package.json
    |-- package-lock.json

Step 4: Setup Your Backend Code

In the backend folder, create a new folder named src. Inside src, create a file named index.ts.

Add the following code to index.ts:

import express from "express";
import cors from "cors";

const app = express();

app.use(express.json());
app.use(cors());

app.get("/api/recipe/search", async (req, res) => {
  res.json({ message: "success" });
});

app.listen(5000, () => {
  console.log("Server running on localhost:5000");
});

Step 5: Add the Start Script

First, open package.json in the backend folder. In the scripts section, replace the test script with a start script as follows:

"scripts": {
    "start": "npx nodemon ./src/index.ts"
}

Step 6: Run Your Backend

In the terminal, ensure you are in the backend folder, then type npm start to run your backend server.

Then open a browser and go to http://localhost:5000/api/recipe/search. You should see a response with the message success.

Congratulations! You have successfully set up and run your backend server. In the next part of this tutorial, we will focus on setting up the frontend and connecting to a database.

How to Setup the Database and Prisma

In this section, we'll focus on setting up a Postgres database using ElephantSQL and integrating Prisma to interact with our database effortlessly. Let's jump right in!

Step 1: Set Up the ElephantSQL Database

Start by navigating to ElephantSQL. Click on "Get a managed database today," followed by selecting the "Tiny Turtle" plan for a free instance.

Then enter a name for your database (for example, recipe-app-db), keep the plan on the free tier, and choose a region closest to you.

Click on "Review," verify the details, and then click on "Create instance."

Step 2: Retrieve the Database Credentials

Once your instance is created, click on it to view the details.

Locate and copy the URL under the "Details" section. This URL contains the credentials needed to connect to your database.

Step 3: Create an Environment File

Now, return to your code editor and open the backend folder.

Create a new file named .env. Inside the .env file, add the following line:

DATABASE_URL=

Replace with the URL you copied from ElephantSQL.

Step 4: Integrate Prisma

Stop your server if it's running by pressing Ctrl + C (or Cmd + C on Mac) in the terminal.

In the terminal, ensure you are in the backend directory, and type the following command to initialize Prisma:

npx prisma init

This command will create a new folder named prisma with a file named schema.prisma.

Step 5: Verify Prisma Integration

Now, open prisma/schema.prisma to ensure your DATABASE_URL has been detected correctly.

Start your server again with the command npm start. Then navigate to http://localhost:5000/api/recipe/search in your browser to ensure your API still works and returns the success message.

Your folder structure should now include the Prisma folder and look like this:

recipe-app
|-- backend
    |-- prisma
        |-- schema.prisma
    |-- .env
    |-- ...

How to Get and Secure a Spoonacular API Key

Step 1: Obtain an API Key from Spoonacular

To do this, navigate to Spoonacular and click on "Start Now." Sign up for an account and proceed to the dashboard.

Within the dashboard, click on “Profile” on the left-hand side, and find the section related to API keys. Generate a new API key, and copy it to your clipboard.

Step 2: Store the API Key Securely

Now, return to your code editor and open the .env file in the backend folder.

Add a new environment variable to store your API key as follows:

API_KEY=

Replace with the API key you copied from Spoonacular.

Step 3: Install and Setup Thunder Client

In Visual Studio Code, navigate to the extensions tab (square icon on the sidebar), and search for Thunder Client.

Install Thunder Client by clicking on the Install button. Once installed, you will see a new icon (a purple thunderbolt) on the sidebar.

Step 4: Test the API Key with Thunder Client

Now click on the Thunder Client icon, then click on “New Request.”

Copy the endpoint URL for searching recipes from Spoonacular's documentation. It should look something like this: https://api.spoonacular.com/recipes/complexSearch.

Paste this URL into the URL bar in Thunder Client.

Under the query tab, add two new parameters:

apiKey with the value of your API key.
query with a value of burgers or any other term you wish to search for.

Then hit "Send" to issue the request and observe the response. You should see a list of recipes related to the term you searched for, indicating that your API key and endpoint are working correctly.

How to Create the Search Endpoint

Step 1: Setup a New File for Recipe API Logic

First, navigate to your backend/src folder and create a new file named recipe-api.ts.

In recipe-api.ts, initiate a constant to store your API key from the environment variables:

const API_KEY = process.env.API_KEY;

Step 2: Create the searchRecipes Function

In recipe-api.ts, define a new asynchronous function searchRecipes that takes in a searchTerm and a page as parameters:

export const searchRecipes = async (searchTerm: string, page: number) => {
  if (!API_KEY) {
    throw new Error("API key not found");
  }

  const baseURL = "https://api.spoonacular.com/recipes/complexSearch";
  const url = new URL(baseURL);

  const queryParams = {
    apiKey: API_KEY,
    query: searchTerm,
    number: 10,
    offset: (page - 1) * 10,
  };

  url.search = new URLSearchParams(queryParams).toString();

  try {
    const searchResponse = await fetch(url.toString());
    const resultsJson = await searchResponse.json();
    return resultsJson;
  } catch (error) {
    console.error(error);
  }
};

Step 3: Import and Use `searchRecipes` in index.ts

Now, navigate back to index.ts in the backend/src folder.

Import the searchRecipes function from recipe-api.ts at the top of your file:

import * as RecipeAPI from "./recipe-api";

Locate the endpoint where you wish to utilize the searchRecipes function, and modify it to call searchRecipes with the appropriate arguments, then return the results:

app.get("/api/recipe/search", async (req, res) => {
  const searchTerm = req.query.searchTerm as string;
  const page = parseInt(req.query.page as string);

  const results = await recipeAPI.searchRecipes(searchTerm, page);
  return res.json(results);
});

Step 4: Test Your Endpoint

Now you can restart your server by stopping it (Ctrl + C or Cmd + C on Mac) and then running npm start.

Test your endpoint by sending a GET request with the appropriate query parameters. For example, navigate to http://localhost:5000/api/recipe/search?searchTerm=burgers&page=1 in your browser or use a REST client like Postman or Thunder Client.

You should now see a list of recipes returned in response to your request, indicating that your backend logic for calling the Recipe API and returning the results is functioning as expected.

How to Setup the Frontend

Before you get started on this section, make sure you're in the top-level directory of your project, which in this case is named recipe-app.

Step 1: Create a React App with Vite

Start by opening a terminal and ensuring you're in the top-level folder (recipe-app).

Then run the following command to install the latest version of Vite:

npm install vite@latest --save-dev

Now, initiate a new React project with Vite by running:

npx create-vite frontend --template react-ts

This command creates a new folder named frontend, sets it up as a React project, and specifies TypeScript as the language.

Step 2: Navigate to Your New React App

Change your directory to the frontend folder:

cd frontend

Then install any necessary dependencies:

npm install

Step 3: Start the Development Server

You can start the development server with the following command:

npm run dev

Your default web browser should now open displaying the initial setup of your React app, which includes a counter example.

Step 4: Clean Up and Personalize Your React App

Now you can head back to your code editor and navigate to frontend/src. Delete the index.css file as it won't be needed.

In main.tsx, remove the import statement for index.css.

Now, open App.tsx. Here, you'll see code for a counter. Delete all the content inside App.tsx.

Let’s start fresh by adding the following code to App.tsx:

// src/App.tsx
const App = () => {
  return <div>Hello from Recipe Appdiv>;
};

export default App;

Save App.tsx and check your browser to see the updated text: "Hello from Recipe App".

Step 5: Setup Your Stylesheet

Go to src and open App.css. Delete all the pre-filled styles but keep the .root class definition empty for now.

Add a font-family property to the .root class:

/* src/App.css */
.root {
  font-family: Helvetica, Arial, sans-serif;
}

Then head back to App.tsx and import your stylesheet:

// src/App.tsx
import "./App.css";

const App = () => {
  // ...
};

Then save App.tsx and check your browser to see the updated font.

Now you have a clean slate to start building out the frontend of your recipe app with React and TypeScript, using Vite as your build tool. As you progress, you can now start adding components, routing, and state management to build out your application's UI and functionality.

How to Call the Search API and Display Results on the Frontend

Now we are going to fetch data from an API and display the results on the UI. The API response is structured as follows:

{
  "results": [
    {
      "id": 650235,
      "title": "Loaded Turkey Burgers",
      "image": "https://spoonacular.com/recipeImages/650235-312x231.jpg",
      "imageType": "jpg"
    }
    // ... other recipes
  ],
  "offset": 10,
  "number": 10,
  "totalResults": 50
}

Each recipe object contains an id, title, image, and imageType. We will map through the results array and display each recipe on our UI.

Step 1: Setup State

In your App.tsx, setup state to store the searchTerm and recipes.

import React, { useState } from "react";

const App = () => {
  const [searchTerm, setSearchTerm] = useState("");
  const [recipes, setRecipes] = useState([]);

  // ... rest of your component
};

Step 2: Fetch Data from the API

Create a new file API.ts and set up a function to make the API call.

// src/API.ts
const searchRecipes = async (searchTerm: string, page: number) => {
  const baseURL = new URL("http://localhost:5000/api/recipes/search");
  baseURL.searchParams.append("searchTerm", searchTerm);
  baseURL.searchParams.append("page", page.toString());

  const response = await fetch(baseURL.toString());

  if (!response.ok) {
    throw new Error(`HTTP Error: ${response.status}`);
  }

  return response.json();
};

export { searchRecipes };

Step 3: Create a Handler Function

Back in App.tsx, import the searchRecipes function and create a handler function to be called when the form is submitted.

import React, { useState, FormEvent } from "react";
import { searchRecipes } from "./API";

const App = () => {
  // ... previous state setup

  const handleSearchSubmit = async (event: FormEvent) => {
    event.preventDefault();

    try {
      const { results } = await searchRecipes(searchTerm, 1);
      setRecipes(results);
    } catch (error) {
      console.error(error);
    }
  };

  // ... rest of your component
};

Step 4: Display the Data

Display the recipes data in your component's return statement.

const App = () => {
  // ... previous code

  return (
    <div>
      <form onSubmit={handleSearchSubmit}>
        <button type="submit">Submitbutton>
      form>
      {recipes.map((recipe) => (
        <div key={recipe.id}>
          Recipe Image Location: {recipe.image}
          <br />
          Recipe Title: {recipe.title}
        div>
      ))}
    div>
  );
};

export default App;

Step 5: Define the Recipe Type

Define a Recipe interface in a new file named types.ts.

// src/types.ts
export interface Recipe {
  id: number;
  title: string;
  image: string;
  imageType: string;
}

Back in App.tsx, import the Recipe interface and use it to type your state and map function.

import React, { useState, FormEvent } from 'react';
import { searchRecipes } from './API';
import { Recipe } from './types';

const App = () => {
  const [searchTerm, setSearchTerm] = useState('');
  const [recipes, setRecipes] = useState([]);

  // ... rest of your code

  return (
    <div>
      {/* ... rest of your return statement */}
      {recipes.map((recipe: Recipe) => (
        {/* ... rest of your map function */}
      ))}
    div>
  );
};

export default App;

Step 6: Test Your Setup

Now, start both your frontend and backend servers. Open your browser, navigate to your app, and try submitting a search. You should see the recipes data displayed on the screen.

# In one terminal
cd frontend
npm run dev

# In another terminal
cd backend
npm start

This setup should now fetch and display recipe data based on the hardcoded searchTerm of "burgers". In a real-world scenario, you'd replace the hardcoded searchTerm with a dynamic value from a user input field.

How to Create the Search Input and Recipe Card Component

Step 1: Setup Your Project

Start by setting up a new React project or navigate to your existing project directory.

npx create-react-app recipe-search-ui
cd recipe-search-ui

Step 2: Create State Hooks for User Input and Data

In your src folder, create a new file named App.tsx and import the necessary dependencies:

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

function App() {
  const [searchTerm, setSearchTerm] = useState < string > "";
  const [recipes, setRecipes] = useState < Array < any >> [];

  // ... rest of the code
}

export default App;

Here, we have set up two state hooks: one for capturing the user's search term and another for holding the recipe data returned from the backend.

Step 3: Build a Form to Capture User Input

Within the App component, build a form with an input field and a submit button. We'll also create a function to handle the form submission, which will trigger the API call.

function App() {
  // ... rest of the code

  const handleSearchSubmit = async (event: FormEvent) => {
    event.preventDefault();
    // ... API call logic
  };

  return (
    <div>
      <form onSubmit={handleSearchSubmit}>
        <input
          type="text"
          required
          placeholder="Enter a search term"
          value={searchTerm}
          onChange={(event) => setSearchTerm(event.target.value)}
        />
        <button type="submit">Submitbutton>
      form>
      {/* ... rest of the code */}
    div>
  );
}

Now, users can enter their search term, and upon form submission, handleSearchSubmit will be triggered.

Step 4: Fetch Recipe Data from the Backend

In the handleSearchSubmit function, use the fetch API to send a request to your backend, capture the returned data, and update the recipes state.

const handleSearchSubmit = async (event: FormEvent) => {
  event.preventDefault();
  try {
    const response = await fetch(
      `http://localhost:5000/api/recipes/search?searchTerm=${searchTerm}`
    );
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    const data = await response.json();
    setRecipes(data.results);
  } catch (error) {
    console.error(error);
  }
};

Step 5: Display Recipe Data

Create a new folder named components in your src directory. Inside this folder, create a file named RecipeCard.tsx. This component will display individual recipe data.

import { Recipe } from "../types";

interface Props {
  recipe: Recipe;
}

const RecipeCard = ({ recipe }: Props) => {
  return (
    <div className="recipe-card">
      <img src={recipe.image}>img>
      <div className="recipe-card-title">
        <h3>{recipe.title}h3>
      div>
    div>
  );
};

export default RecipeCard;

Now, go back to App.tsx and import RecipeCard. Map over the recipes state to display each recipe using the RecipeCard component.

import RecipeCard from "./components/RecipeCard";

// ... rest of the code

return (
  <div>
    {/* ... rest of the code */}
    {recipes.map((recipe) => (
      <RecipeCard key={recipe.id} recipe={recipe} />
    ))}
  div>
);

Now, when you submit a search term, the UI will display a list of recipe cards containing the images and titles of the recipes returned from the backend.

Step 6: Test Your UI

Run your React app, enter a search term such as "pasta" or "burgers", and submit the form. You should see a list of recipe cards displaying the relevant recipes from the backend.

npm start

Navigate to http://localhost:3000 in your browser and try out your new recipe search UI!

How to Build the Pagination and View More Functionality

Step 1: Backend Pagination

We added a page query parameter in the search endpoint. The page value is used to calculate the offset for the recipe data fetched from the database or external API.

Step 2: Add "View More" Button to the UI

Navigate to your App.tsx file. Scroll down to the JSX code where you map through the recipes array and add a "View More" button below it.

// ... other code
{
  recipes.map((recipe) => <RecipeCard key={recipe.id} recipe={recipe} />);
}
;
// ... other code

Step 3: Create a `useRef` Hook to Store the Current Page Number

Above your component's return statement, create a useRef hook to keep track of the current page number without causing re-renders.

// ... other code
const pageNumber = useRef(1);
// ... other code

Step 4: Implement the `handleViewMoreClick` Function

Define a function called handleViewMoreClick to handle the logic for loading more recipes.

// ... other code
const handleViewMoreClick = async () => {
  try {
    const nextPage = pageNumber.current + 1;
    const nextRecipes = await api.searchRecipes(searchTerm, nextPage);
    setRecipes((prevRecipes) => [...prevRecipes, ...nextRecipes.results]);
    pageNumber.current = nextPage;
  } catch (error) {
    console.error(error);
  }
};
// ... other code

Step 5: Reset Page Number on New Search

Modify your handleSearchSubmit function to reset the page number back to 1 whenever a new search term is entered.

// ... other code
const handleSearchSubmit = async (event: FormEvent) => {
  // ... other code
  setRecipes(recipes.results);
  pageNumber.current = 1;
};
// ... other code

Step 6: Test Your Implementation

Run your app and perform a search. Click the "View More" button to load more results. Change the search term and ensure that the page number resets, and you get a fresh list of recipes.

npm start

Now, as you search for recipes and click "View More," you should see additional recipes being loaded and displayed in the UI.

I'll walk you through this process step-by-step. We'll create a model that displays a recipe summary using a specific endpoint from the provided API.

Step 1: Understanding the Recipe Summary Endpoint

You can understand where the summary data comes from by looking at your API documentation. The endpoint you need is called Summarize Recipe. This endpoint requires a recipe ID to generate a summary.

Step 2: Setup Backend Endpoint

Create a backend endpoint that interfaces with the Summarize Recipe endpoint.

// In your backend, create an endpoint to fetch recipe summary
// File: recipe-api.ts
export const getRecipeSummary = async (recipeId: string) => {
  if (!apiKey) {
    throw new Error("API key not found");
  }

  const url = new URL(
    `https://api.spoonacular.com/recipes/${recipeId}/summary`
  );
  const params = { apiKey: apiKey };
  url.search = new URLSearchParams(params).toString();

  const response = await fetch(url.toString());
  const json = await response.json();
  return json;
};

Step 3: Create a Backend Route

Create a route in your backend to handle requests to your new endpoint.

// File: index.ts
app.get("/api/recipe/:recipeId/summary", async (req, res) => {
  const recipeId = req.params.recipeId;
  const result = await recipeSummary(recipeId);
  res.json(result);
});

Create a React component for the recipe modal. We will use the useEffect hook to call the backend endpoint we just created, and store the Recipe Summary data in state.

First add a type for RecipeSummary to types.ts

export interface RecipeSummary {
  id: number;
  title: string;
  summary: string;
}

// File: RecipeModal.tsx
import React, { useState, useEffect } from "react";
import { RecipeSummary } from "../types";

interface Props {
  recipeId: string;
  onClose: () => void;
}

const RecipeModal: React.FC = ({ recipeId, onClose }) => {
  const [recipeSummary, setRecipeSummary] =
    (useState < RecipeSummary) | (null > null);

  useEffect(() => {
    const fetchRecipeSummary = async () => {
      try {
        const summary = await getRecipeSummary(recipeId);
        setRecipeSummary(summary);
      } catch (error) {
        console.error(error);
      }
    };
    fetchRecipeSummary();
  }, [recipeId]);

  return (
    <div className="overlay">
      <div className="modal">
        <div className="modal-content">
          <div className="modal-header">
            <h2>{recipeSummary?.title}h2>
            <span className="close-button" onClick={onClose}>
              ×
            span>
          div>
          <p dangerouslySetInnerHTML={{ __html: recipeSummary?.summary }} />
        div>
      div>
    div>
  );
};

export default RecipeModal;

Add the following CSS to style the modal:

/* File: app.css */
.overlay {
  position: fixed;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  background-color: rgba(0, 0, 0, 0.7);
  z-index: 1;
}

.modal {
  position: fixed;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
  z-index: 2;
  background-color: white;
  padding: 2em;
  border-radius: 4px;
  max-width: 500px;
}

.modal-header {
  display: flex;
  flex-direction: row;
  align-items: center;
  justify-content: space-between;
}

Modify your main component to handle rendering and interactions with the modal.

// File: App.tsx
const App: React.FC = () => {
  const [selectedRecipe, setSelectedRecipe] =
    (useState < Recipe) | (undefined > undefined);

  return (
    <div className="App">
      {/* Other components and logic */}
      {selectedRecipe && (
        <RecipeModal
          recipeId={selectedRecipe.id.toString()}
          onClose={() => setSelectedRecipe(undefined)}
        />
      )}
    div>
  );
};

export default App;

Now, when a user clicks on a recipe, the modal will appear displaying the summary of the selected recipe. The modal can be closed by clicking the close button, which will set the selectedRecipe back to undefined, hiding the modal.

How to Create Endpoints to Get/Create/Delete Favorite Recipes

Step 1: Setup the Database

First, we need to extend our database schema to include a table for storing favorite recipes by their IDs.

First, navigate to the Prisma folder within the backend directory of your project. Then open the schema.prisma file.

Define a new model for favorite recipes as follows:

model FavoriteRecipe {
  id        Int    @id @default(autoincrement())
  recipeId  Int    @unique
}

Step 2: Synchronize the Database Schema

Now, let's synchronize the updated schema with our database.

cd backend
npx prisma db push

Step 3: Setup the Endpoints

We need to set up endpoints in our Node backend to handle creating, viewing, and deleting favorites. We'll use the prismaClient to help us perform crud operations on the database.

First, we'll create a new post endpoint like this:

// In backend/index.ts
import { PrismaClient } from "@prisma/client";

const prismaClient = new PrismaClient();

app.post("/api/recipes/favorite", async (req, res) => {
  const { recipeId } = req.body;
  try {
    const favoriteRecipe = await prismaClient.favoriteRecipe.create({
      data: { recipeId },
    });
    res.status(201).json(favoriteRecipe);
  } catch (error) {
    console.error(error);
    res.status(500).json({ error: "Oops, something went wrong." });
  }
});

Next, we'll create the View endpoint. To do that, create a utility function to fetch recipe details by IDs:

// In backend/src/recipe-api.ts
export const getFavoriteRecipesByIds = async (ids: string[]) => {
  if (!apiKey) {
    throw new Error("API Key not found");
  }
  const url = new URL("https://api.spoonacular.com/recipes/informationBulk");
  url.search = new URLSearchParams({
    apiKey: apiKey,
    ids: ids.join(","),
  }).toString();

  const response = await fetch(url);
  const json = await response.json();
  return { results: json };
};

Now, create the endpoint to fetch all favorite recipes:

// In backend/index.ts
import { getFavoriteRecipesByIds } from "./src/recipe-api";

app.get("/api/recipes/favorite", async (req, res) => {
  try {
    const favoriteRecipes = await prismaClient.favoriteRecipe.findMany();
    const recipeIds = favoriteRecipes.map((recipe) =>
      recipe.recipeId.toString()
    );
    const favorites = await getFavoriteRecipesByIds(recipeIds);
    res.json(favorites);
  } catch (error) {
    console.error(error);
    res.status(500).json({ error: "Oops, something went wrong." });
  }
});

Next up is the Delete endpoint:

// In backend/index.ts
app.delete("/api/recipes/favorite", async (req, res) => {
  const { recipeId } = req.body;
  try {
    await prismaClient.favoriteRecipe.delete({
      where: { recipeId },
    });
    res.status(204).send();
  } catch (error) {
    console.error(error);
    res.status(500).json({ error: "Oops, something went wrong." });
  }
});

Step 4: Test the Endpoints

You can use tools like Postman or Thunder Client to test the endpoints. Make sure to adjust the request method and URL accordingly, and provide the necessary request body or parameters.

Creating a Favorite: POST request to /api/recipes/favorite with recipeId in the body.
Viewing Favorites: GET request to /api/recipes/favorite.
Deleting a Favorite: DELETE request to /api/recipes/favorite with recipeId in the body.

Step 5: Verify the Database

Check the favoriteRecipes table in your ElephantSQL database to verify the actions performed through the endpoints.

How to Add Favorites Functionality to the Frontend

Step 1: Setup the Tab Functionality

Next, we'll look at how to integrate these endpoints on the frontend. We'll start by setting up tabs for 'Search' and 'Favorites' in our app.

First, define a new state to keep track of the selected tab.

import React, { useState } from "react";

type Tabs = "search" | "favorites";

function App() {
  const [selectedTab, setSelectedTab] = useState < Tabs > "search";

  // Rest of your code...
}

Step 2: Render Tabs

Now you'll render tabs in your JSX, and handle tab switching with the onClick event. This makes each

element is clickable, and saves the tab the user clicked on in state. This helps conditionally render different UI elements depending on their selection.

// Inside your JSX...
"tabs">
  <h1 onClick={() => setSelectedTab("search")}>Recipe Searchh1>
  <h1 onClick={() => setSelectedTab("favorites")}>Favoritesh1>

Step 3: Conditional Rendering

Based on the selected tab, you want to conditionally render either the search component or the favorites component. This will show/hide either the "search section" or the "favourites" section depending on the selectedTab state variable.

{selectedTab === 'search' && (
  // search component code...
)}
{selectedTab === 'favorites' && (
  // favorites component code...
)}

Step 4: Fetch Favorite Recipes

Next we need to populate the Favorite recipes tab with our favourite recipes. We want to do this when the App loads, for a quick user experience.

To do this, fetch the favorite recipes from the backend when the app loads using the useEffect hook, and store the fetched favorite recipes in a new state.

// api.ts
export const getFavouriteRecipes = async () => {
  const url = new URL("http://localhost:5000/api/recipes/favourite");
  const response = await fetch(url);

  if (!response.ok) {
    throw new Error(`HTTP error! Status: ${response.status}`);
  }
  return response.json();
};

//App.tsx
import React, { useEffect, useState } from "react";

// ... Rest of your imports and code

function App() {
  // ... Rest of your state declarations

  const [favoriteRecipes, setFavoriteRecipes] = useState([]);

  useEffect(() => {
    const fetchFavoriteRecipes = async () => {
      try {
        const favouriteRecipes = await api.getFavouriteRecipes();
        setFavouriteRecipes(favouriteRecipes.results);
      } catch (error) {
        console.error(error);
      }
    };

    fetchFavoriteRecipes();
  }, []);

  // ... Rest of your code
}

Step 5: Render Favorite Recipes

Now you need to render the favorite recipes in the 'Favorites' tab.

{selectedTab === 'favorites' && (
  <div>
    {favoriteRecipes.map(recipe => (
      // Render each favorite recipe card...
    ))}
  div>
)}

Step 6: Add a Heart Icon

Next we'll add a way for the user to add and remove favorites. We'll do this by adding a "heart" icon to each card.

Before diving into the code, ensure you are in the correct directory by navigating to your project's front-end directory in your terminal. Install the necessary package for icons by running:

npm install react-icons

Step 7: Import the Icon

Open the RecipeCard component, and import the heart icon at the top of your file:

import { AiOutlineHeart } from "react-icons/ai";

Step 8: Insert the icon

In the RecipeCard component, add the heart icon within a span element just above the h3 tag:


  <AiOutlineHeart size={25} />

Step 9: Add CSS Styling

In your App.css file, add the following CSS to style the icon and ensure it appears on the same line as the title. Using flex and align-items means the icon and title will be aligned nicely beneath the image:

.recipe-card-title {
  display: flex;
  align-items: center;
  gap: 0.5rem;
}

Step 10: Create an Add Favourite Event Handler

In App.tsx, create an event handler for favoriting a recipe. This is what will get called when the user clicks the heart icon on an recipe that hasn't yet been favorited:

const addfavoriteRecipe = async (recipe) => {
  try {
    await API.addFavoriteRecipe(recipe);
    setFavoriteRecipes([...favoriteRecipes, recipe]);
  } catch (error) {
    console.log(error);
  }
};

Step 11: API Logic

In a new file called API.ts, create a function to handle the API call to save a favorite recipe. This will call our endpoint which we created earlier in the backend:

export const addFavoriteRecipe = async (recipe) => {
  const body = {
    recipeId: recipe.id,
  };
  const response = await fetch("http://localhost:5000/api/recipes/favourite", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });
  if (!response.ok) {
    throw new Error("Failed to save favorite");
  }
};

Step 12: Hook Up the Event Handler

Pass the event handler to the RecipeCard component:

//.. other props
  onFavoriteButtonClick={favoriteRecipe}
/>

Step 13: Create the Remove Favorite Event Handler

Similarly, create an event handler for un-favoriting a recipe in App.tsx:

const removeFavoriteRecipe = async (recipe) => {
  try {
    await API.removeFavoriteRecipe(recipe);
    const updatedRecipes = favoriteRecipes.filter(
      (favRecipe) => favRecipe.id !== recipe.id
    );
    setFavoriteRecipes(updatedRecipes);
  } catch (error) {
    console.log(error);
  }
};

Step 14: API Logic

In API.ts, create a function to handle the API call to remove a favorite recipe. Again, this will call the backend API to remove a recipe which we created earlier:

export const removeFavoriteRecipe = async (recipe) => {
  const body = {
    recipeID: recipe.id,
  };
  const response = await fetch("http://localhost:5000/api/recipes/favourite", {
    method: "DELETE",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });
  if (!response.ok) {
    throw new Error("Failed to remove favorite");
  }
};

Step 15: Conditional Event Handler

Depending on if the user is "favoriting" or "unfavoriting" a recipe, we want to conditionally call either addFavoriteRecipe or removeFavoriteRecipe based on the favorited state:

//.. other props
  onFavoriteButtonClick={isFavorite ? removeFavoriteRecipe : favoriteRecipe}
/>

Step 16: Determine the Favorited State

Before we can display the heart icon a favorited/non-favorited state, we need to know if the recipe is already a or not.

To do this, we determine whether a recipe is favorited by checking if it exists in the favoriteRecipes state array. Pass this information to RecipeCard:

const isFavorite = favoriteRecipes.some(
  (favRecipe) => favRecipe.id === recipe.id
);
<RecipeCard
  // ...other props
  isFavorite={isFavorite}
/>;

Step 17: Display the Favorited State

In RecipeCard, conditionally render a filled or outlined heart icon based on the isFavorite prop:

{
  isFavorite ? (
    <AiFillHeart size={25} color="red" />
  ) : (
    <AiOutlineHeart size={25} />
  );
}

How to Add CSS/Styling

Step 1: Prepare the Hero Image

We've added some basic styling so far, so lets complete the CSS so that our app looks polished!

Firstly obtain an image from a source like Pexels or any other image repository. This will be used in the Hero section of our app at the top, and will have our title overlaid on it. Ensure the image has a horizontal orientation for better handling of aspect ratios.

Place the image in the public folder of your project.

project-folder
│
└───public
    │   hero-image.jpeg

Step 2: Structure the Header

Open app.tsx and locate the JSX markup. Add a className of app-container to the top div element.

Inside the app-container div, add a new div with a className of header. Within the header div, add an img element with a src attribute pointing to your image, and a div element with a className of title containing the app's title.

"app-container">
  <div className="header">
    <img src="/hero-image.jpeg" alt="Hero" />
    <div className="title">My Recipe Appdiv>
  div>
  {/* ...rest of your code */}

Step 3: Style the Header

Open app.css and scroll to the top. Add the following CSS to style the app-container, header, img, and title elements. This makes the title appear on top of the image, with a translucent background:

.app-container {
  display: flex;
  flex-direction: column;
  gap: 2em;
}

.header {
  position: relative;
}

.header img {
  width: 100%;
  height: 500px;
  object-fit: cover;
  object-position: center;
  opacity: 0.5;
  border-radius: 1em;
}

.title {
  position: absolute;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%);
  color: white;
  font-size: 2em;
  text-align: center;
  background-color: black;
  opacity: 0.8;
  padding: 0.5em 1.5em 0.5em 1.5em;
}

Step 4: Adjust the Layout

Add padding to the body element and use a media query to add margins on larger screens. We do this so our app doesn't appear to narrow on mobile devices. When the screen size reaches 768px, the media query will kick in and add margin to the left and right of our app, so that the app doesn't appear too wide.

body {
  padding: 5em 0;
  height: 100vh;
  background-color: #f0f0f0; /* or any color you prefer */
}

@media (min-width: 768px) {
  body {
    margin-left: 10em;
    margin-right: 10em;
  }
}

Step 5: Style Tabs Underline

Currently its not clear which tab the user has selected. What we want to do is add an orange underline to the selected tab. To do this, we can use a combination of CSS classes and conditional rendering.

Within app.tsx, locate your h1 elements representing tabs, and dynamically apply a className of tab-active based on the selected tab.

'search' ? 'tab-active' : ''}>Search
<h1 className={selectedTab === 'favorites' ? 'tab-active' : ''}>Favoritesh1>

In app.css, define the tab-active class:

.tab-active {
  border-bottom: 4px solid orange; /* or any color you prefer */
  padding-bottom: 0.5em;
}

Step 6: Style the Search Bar

We want our search bar to take up the width of the container, and we want to add an icon instead of the search button, which makes our UI more interesting.

In app.tsx, locate the form element within the Search tab. Replace the text "Submit" in the button element with an icon from a library like React Icons.

In app.css, style the form, input, and button elements:

form {
  display: flex;
  background-color: white;
  align-items: center;
}

input {
  padding: 0.5em;
  font-size: 2em;
  flex: 1;
  border: none;
}

input:focus {
  outline: none;
}

button {
  background-color: white;
  border: none;
  cursor: pointer;
}

Step 7: Implement a Responsive Recipe Card Grid

Currently our Recipe Cards are stacked horizontally. We'll use CSS grid to make the recipe cards appear in a grid layout, which will also make things more responsive.

Within app.tsx, create a new div with a className of recipe-grid just above where you map over your recipes, and place the logic to rendering the recipes inside this div.

"recipe-grid">
  {recipes.map((recipe) => {
    const isFavourite = favouriteRecipes.some((favRecipe) => favRecipe.id === recipe.id);

    return (
      <RecipeCard
        key={recipe.id}
        recipe={recipe}
        onFavouriteButtonClick={isFavourite ? removeFavouriteRecipe : addFavouriteRecipe}
        onClick={() => setSelectedRecipe(recipe)}
        isFavourite={isFavourite}
      />
    );
  })}

In app.css, style the recipe-grid and recipe-card elements:

.recipe-grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(400px, 1fr));
  gap: 2em;
}

.recipe-card {
  display: flex;
  flex-direction: column;
  justify-content: space-evenly;
  background-color: white;
  padding: 1em;
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
  position: relative;
  cursor: pointer;
  gap: 1.5em;
}

.recipe-card h3 {
  font-size: 1.5em;
  margin: 0;
  white-space: nowrap;
  overflow: hidden;
  text-overflow: ellipsis;
}

Step 8: Final Touches

Style the "View More" button to make sure it matches the style of our app, and is centered beneath our recipe grid:

.view-more-button {
  font-size: 1.5em;
  padding: 1em;
  font-weight: bold;
  margin: auto;
}

Conclusion

Congrats on making it to the end! Hopefully you've learned a few things about full stack development using React and Node.

If you enjoyed this project, you can find more at CodeCoyotes.com, where you can also send me a message if you need to get in contact.

Thanks for reading, see you in the next one!

Full Stack Project Tutorial – Create A Notes App Using React and Node.js

Chris Blakely — Thu, 28 Sep 2023 14:10:44 +0000

Hey there! Ready to build something cool? In this tutorial, we're going to create a full stack notes app using React, Node.js, and PostgreSQL.

We'll start from scratch and end up with a fully functioning app where you can create, edit, and delete notes. Plus, we're adding validation on both the UI and the backend to keep things in check!

This guide is all about giving you the real-deal experience of building a web app. You'll get to learn how each piece of the puzzle fits together – from the front-end magic with React, to the server-side wonders with Node.js, and storing all the good stuff in a PostgreSQL database. And hey, we're making sure it looks good and works well on mobile screens too!

By the end of this, you’ll have a good grip on full stack development with React and Node, which you can carry with you into future projects. It’s all about learning by doing, and getting the skills to make your ideas come to life. So, grab a cup of coffee, roll up your sleeves, and let’s get coding!

Prerequisites

Since we will be focusing on how to build a project, there are a few prerequisites that will be needed to get the most out of this tutorial:

Some knowledge about web development concepts (frontend, backend, databases, API's, REST).
Some knowledge of JavaScript (variables, functions, objects, arrays, and so on).
Basic understanding on React (how to create components, add styles, work with state).
Basic understanding on Node.js/Express (working with APIs).

What We'll Build
Challenge: Try it Yourself First!
Video Tutorial
PART 1 – Create the UI
PART 2 - Create the Backend
PART 3 - Connect UI to Backend
The End - Why not try the bonus challenges?

What We'll Build

In this tutorial, we'll build a full stack notes app from scratch, using React, Node.js and PostgreSQL, with the following features:

Create/Edit/Delete Notes
Validation on the UI and Backend
Responsive on mobile screens

Challenge: Try it Yourself First!

If you would like to attempt this project yourself first without looking at the tutorial, here's a few hints:

Tackle one little piece at a time. For example, you would focus on getting the UI working on the UI first, and tackle the APIs later.
Think about your data – What do you need to store? What data structure (for example, arrays) will you use to return the data via the API? How will you render this data on the UI?
Don't forget about validation and error handling. What will happen if the user tries to save a note without a title field? How will you prevent this? (Hint: Forms and the required field will be your friend here)
Remember there is no perfect way to complete a project. The tutorial below is one way to tackle the problem. You can choose to go a different way, putting your own unique style on things. The main thing is that you start!

If you need more help on getting started yourself, you can find more hints and tips, starter code, and completed code you can reference over at codecoyotes.com.

Video Tutorial

PART 1 – Create the UI

We'll start this tutorial by creating the UI using some mock data. This lets us focus on our styling, and how things to look, without having to worry about creating a backend right away.

Create a New React App

Okay, first things first: let's set up our project structure. Open your terminal and navigate to your desktop. Our next step is to create a new folder that will hold both our UI and backend code. Let's name it notes-app:

mkdir notes-app

Once that's done, navigate into the newly created notes-app directory:

cd notes-app

Next, we'll create a new React app using TypeScript as our template. We'll use the npx create-react-app command for this, specifying TypeScript as the template:

npx create-react-app notes-app --template typescript

After you hit Enter, the process may take a few minutes to install all necessary packages. Once it's completed, open the notes-app folder in Visual Studio Code or your preferred IDE.

In Visual Studio Code, you should see that the notes-app is at the top level of your directory. As the course progresses, we will add a notes-app-server directory as well to keep all the code together in one place.

Now open a new terminal within your IDE and navigate to your React app's directory (let's assume you named it notes-app):

cd notes-app

Then, run the following command to start the front-end development server:

npm start

If all goes well, your browser will automatically open and display your new React app. You should see a spinning React logo, among other default assets.

Finally, let's clear out the boilerplate code to have a clean starting point for our app. Open src/App.tsx in your IDE and delete its content. This will be our new starting point for building the app.

Add UI Elements

Okay, the first thing we'll do is put some of our UI components in place. This will consist of the general markup and CSS, without involving any JavaScript. This gives us a glimpse of how we envision the layout, without having to concern ourselves with API calls or database interactions at this stage.

We'll navigate to .App.tsx and create a new component. Make sure to import our stylesheet from App.css. The first thing to add is a div with a class name of AppContainer. This will help position our form and the CSS grid for our notes.

Within this div, we'll include our form tags. Here, we'll add an input field for the title — this is where the user can enter the note title. We'll also include a textarea for the note content. Both of these fields will be set to required, enabling browser-native validation messages if the user tries to submit an incomplete form.

At the bottom of the form, we'll include a button of type submit, which will handle form submissions when clicked.

Off to the right, we'll add a div to contain our notes. This will be structured as a CSS grid. Initially, we'll populate this grid with a single note to see how it looks.

For our note, we'll have a header containing a delete button situated on the right-hand side. We'll display the user-entered title – for demonstration purposes, we're using a dummy title. We'll also include the content that the user entered.

Finally, we'll export our component at the very bottom.

Completed code for this section

import "./App.css";

const App = () => {
  return (
    <div className="app-container">
      <form className="note-form">
        <input placeholder="Title" required />
        <textarea placeholder="Content" rows={10} required />

        <button type="submit">Add Notebutton>
      form>
      <div className="notes-grid">
        <div className="note-item">
          <div className="notes-header">
            <button>xbutton>
          div>
          <h2>Note Titleh2>
          <p>Note contentp>
        div>
      div>
    div>
  );
};

export default App;

Add CSS

Start the App

First, let's open a terminal and type npm start. This will launch the app in the browser. As you can see on the right-hand side, the appearance isn't great yet. This is because we haven't applied any styles. To fix this, we'll navigate to App.css and style the classes we added earlier.

You can download the styles from the link in the description if you prefer to copy and paste. Alternatively, feel free to follow along with the video and pause as needed. Remember, these styles are just examples for learning – they don't have to be perfect.

Style the Body and App Container

In App.css, the first thing we'll do is add some styles to the body. We'll give it a gray background and a margin to prevent the app from touching the browser window edges. Next, we'll style our App Container.

We're designing this mobile-first, meaning the default styles will target mobile screens. We'll use media queries for larger displays. This approach is optional, but often it's easier to start with mobile designs.

For mobile screens, we want our App Container to default to a single column layout, stacking our form and notes grid on top of each other.

Use Media Queries

We'll add a media query specifying that for screens larger than 600 pixels, we'll use a two-column layout. We'll define this using grid-template-columns.

The first column will be 200 pixels wide, accommodating the form. The second column will use 1fr, filling the remaining space. A 20-pixel gap will separate the two columns.

Style the Notes Grid

Next, let's style our notes grid. We'll use CSS grid and define grid-template-columns.

Each grid item will have a minimum width of 250 pixels and can expand to fill available space. Don't worry if this sounds confusing – it will become clear soon.

We'll also set grid-auto-rows to ensure each row is a minimum of 250 pixels tall, accommodating notes of different sizes while maintaining a consistent row height.

Style Individual Notes

For each note, we'll use Flexbox and set flex-direction to column, stacking the header, title, and content vertically. We'll also add some basic styles like border, padding, and background color. A box shadow will provide a finishing touch.

Style the Header and Delete Button

The header will also use Flexbox, and we'll set justify-content to flex-end to align the delete button to the right. The button will receive custom styles for a polished look.

Style the Form

Lastly, we'll style the form on the left column. Again, we'll use Flexbox with a column layout and a 20-pixel gap between elements. The text area and input fields will get borders, padding, and resized fonts. We'll also style the submit button and add hover effects.

Completed code for this section

body {
  margin: 20px;
  background-color: lightgrey;
}

.app-container {
  grid-template-columns: 1fr;
}

@media (min-width: 600px) {
  .app-container {
    display: grid;
    grid-template-columns: 200px 1fr;
    gap: 20px;
  }
}

.notes-grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
  grid-auto-rows: minmax(250px, auto);
  gap: 20px;
}

.note-item {
  display: flex;
  flex-direction: column;
  border: 1px solid #ccc;
  padding: 10px;
  border-radius: 5px;
  background-color: #f9f9f9;
  box-shadow: 0px 0px 10px rgba(0, 0, 0, 0.1);
  cursor: pointer;
}

.notes-header {
  display: flex;
  justify-content: flex-end;
}

.notes-header button {
  font-size: 16px;
  background: transparent;
  border: none;
  cursor: pointer;
  max-width: fit-content;
}

h2 {
  margin: 0;
}

.note-form {
  display: flex;
  flex-direction: column;
  gap: 20px;
}

textarea,
input {
  border-radius: 5px;
  border: 1px solid black;
  padding: 10px;
  font-size: 16px;
}

.note-form button {
  border-radius: 5px;
  background-color: rgb(64, 154, 184);
  border: none;
  padding: 10px;
  font-size: 16px;
  color: white;
}

.note-form button:hover {
  background-color: rgb(106, 175, 198);
  cursor: pointer;
}

.edit-buttons {
  display: flex;
  justify-content: space-evenly;
  gap: 5px;
}

.edit-buttons button {
  flex: 1;
}

.edit-buttons button:last-of-type {
  background-color: rgb(220, 89, 89);
  color: white;
}

Add Dummy Notes

Add Dummy Notes for CSS Grid Testing

Now that we have our CSS in place, the next step is to add dummy notes to our App component to test the responsiveness of our CSS grid. To achieve this, we'll navigate to App.tsx and import the useState hook from React.

Inside our App component, we'll store the notes within the useState hook. Whenever you have UI elements that can change, it's a good idea to manage them in the state. We'll initialize this with a dummy array of notes, where each note has an id, a title, and content:

const [notes, setNotes] = useState([
{
  id: 1,
  title: "test note 1",
  content: "bla bla note1",
},
{
  id: 2,
  title: "test note 2 ",
  content: "bla bla note2",
},
{
  id: 3,
  title: "test note 3",
  content: "bla bla note3",
},
{
  id: 4,
  title: "test note 4 ",
  content: "bla bla note4",
},
{
  id: 5,
  title: "test note 5",
  content: "bla bla note5",
},
{
  id: 6,
  title: "test note 6",
  content: "bla bla note6",
},
]);

Think of this as simulating an API call and storing the returned data in the state. The structure of this data will be similar to what we'll receive from our API requests when we eventually build out our backend.

Map Notes to Components

With our array of notes in state, we can now use the map function within our notes grid to display the markup for each note. The map function will run as many times as there are notes in the array. Instead of hardcoding the title and content, we'll pull these values from each note object:

"notes-grid">
  {notes.map((note) => (
    <div className="note-item">
      <div className="notes-header">
        <button>xbutton>
      div>
      <h2>{note.title}h2>
      <p>{note.content}p>
    div>
  ))}

Verify Responsiveness

After these steps, you should see four notes displayed in the browser, populated with the values from the objects in the array.

To verify that our layout is responsive, you can change the window size. You'll see that the notes adjust based on the window size. When the window is at its smallest—simulating a mobile screen—the form will stack vertically above the notes grid.

Save Note Form

Now that we have our UI set up, let's focus on adding functionality to the form that allows us to create a new note. Initially, we'll implement this for the UI. Later, we'll make the data persistent by linking it to the backend, which we'll build separately.

Use State for Form Inputs in React

In React, when working with forms, it's a best practice to maintain a state variable for each form input. This enables React to control those inputs, making it easier to capture their values and use them programmatically.

In our code, we have two form inputs: one for the title and another for the content. For these, we'll set up two state variables called title and content:

const [title, setTitle] = useState("");
const [content, setContent] = useState("");

For the title input, we bind its value to the title state variable and update this state whenever the user types into the field:

(event) => setTitle(event.target.value)}
  placeholder="Title"
  required
>

Similarly, we'll handle the textarea for content:

(<span class="hljs-params">event</span>) =></span> setContent(event.target.value)}
  placeholder=<span class="hljs-string">"Content"</span>
  rows={<span class="hljs-number">10</span>}
  required
>

Handle Form Submission

After binding our form inputs to state variables, the next step is to add a function that handles the form submission. We'll name this function handleAddNote:

const handleAddNote = (event: React.FormEvent) => {
  event.preventDefault();
  console.log("title: ", title);
  console.log("content: ", content);
};

In this function, we specify the parameter type as React.FormEvent to satisfy TypeScript's typing requirement. We also call event.preventDefault() to prevent the form from submitting and refreshing the page, which is its default behavior. Following that, we log the title and content state variables to the console.

Finally, we'll connect this function to the onSubmit event in our form:

{/* ...form inputs here... */}

Test the Form

To test this setup, open the browser console, input a title and some content, and click the "Add Note" button. You should see the title and content values logged in the console, confirming that our form is capturing input as expected.

Handle the "Add Note" Functionality

Now that we've set up our state variables for the title and content, we can proceed to implement the function that handles adding a new note. This function will create a new note object and add it to our notes array, thereby updating the UI.

Create a New Note Object

First, let's create a new note object and specify its type as Note, taking advantage of TypeScript's type system:

const newNote: Note = {
  id: notes.length + 1,
  title: title,
  content: content,
};

Because we've explicitly typed our object, TypeScript's IntelliSense will assist us in populating the object, ensuring that we don't miss any required properties. For now, we'll set the id to the length of the current notes array plus one, although this id will eventually be generated by our backend database.

Update State with New Note

Once we have our new note object, we need to update our notes state array. We'll use the setNotes function for this purpose:

setNotes([newNote, ...notes]);

The new note object will be the first item in the new notes array, followed by the existing notes, which we'll spread into the new array using the spread operator. This effectively makes a copy of the old notes array and inserts it into the new one.

Clear the Form Inputs

Lastly, let's reset the title and content state variables to empty strings, improving the user experience by clearing the form once a note is added:

setTitle("");
setContent("");

Test the Functionality

And that's it! If you now go to the browser, input a title and some content, and then click "Add Note," you'll see your new note appear at the top of the list, and the form fields will be cleared, ready for a new entry.

Handle the "Update Note" Functionality

In this section, we'll focus on implementing the feature that allows users to update an existing note. When a user clicks on a note, we want to populate the title and content fields in our form with the note's existing values. We'll also add a "Save" and "Cancel" button.

Cleanup and Initial Setup

First, let's clean up our code by removing any console.log statements – they are no longer needed:

const [selectedNote, setSelectedNote] = useState(null);

Track the Selected Note

To track which note the user has clicked on, we'll create a new state variable called selectedNote. This state variable will have a type of Note or null to account for the possibility that no note is selected. We'll initialize this state to null.

Create the Click Handler

Next, let's create a function named handleNoteClick to handle the user's click event on a note. This function will take a note object as its argument:

const handleNoteClick = (note: Note) => {
  setSelectedNote(note);
  setTitle(note.title);
  setContent(note.content);
};

Within this function, we'll use setSelectedNote to save the clicked note to our selectedNote state. Additionally, we'll populate the title and content state variables with the values from the clicked note.

Update the UI

In the JSX for rendering each note, add an onClick event to the top-level div element for each note. Call the handleNoteClick function and pass the note object to it:

"note-item" onClick={() => handleNoteClick(note)}>
  <div className="notes-header">
    <button>xbutton>
  div>
  <h2>{note.title}h2>
  <p>{note.content}p>

Since we are iterating over notes using the map function, this onClick handler will be added to each note automatically.

Save user changes

Now that we have the capability for the user to edit a note, we'll implement the functionality to save the changes they make to both the title and content of a note into our state.

The `handleUpdateNote` Function

Let's create a new function called handleUpdateNote:

const handleUpdateNote = (event: React.FormEvent) => {
  event.preventDefault();

  if (!selectedNote) {
    return;
  }

  const updatedNote: Note = {
    id: selectedNote.id,
    title: title,
    content: content,
  };

  const updatedNotesList = notes.map((note) => (note.id === selectedNote.id ? updatedNote : note));

  setNotes(updatedNotesList);
  setTitle("");
  setContent("");
  setSelectedNote(null);
};

Within this function, we use event.preventDefault() to prevent the form from automatically submitting when the "Save" button is clicked. We also validate if a note is selected. If not, we exit the function early to prevent potential errors.

Next, we form an updated note object based on the selected note's id and the updated title and content. After that, we utilize the map function to generate a new array of notes, replacing the selected note with our updated note where the id matches. The updated array is then set to our state using the setNotes function. Finally, we reset our title, content, and selectedNote state values to their initial states.

The `handleCancel` Function

We'll also implement a simple handleCancel function to reset our form and selected note when the user decides not to proceed with an update:

const handleCancel = () => {
  setTitle("");
  setContent("");
  setSelectedNote(null);
};

Update the JSX

Let's introduce conditional rendering in our JSX to display the appropriate buttons based on whether a note is selected for editing or not:

"note-form"
  onSubmit={(event) => (selectedNote ? handleUpdateNote(event) : handleAddNote(event))}
>
  {/* ... other form elements ... */}
  {selectedNote ? (
    <div className="edit-buttons">
      <button type="submit">Savebutton>
      <button onClick={handleCancel}>Cancelbutton>
    div>
  ) : (
    <button type="submit">Add Notebutton>
  )}

Within our form's onSubmit event, we've added a conditional. If a note is selected, we'll trigger the handleUpdateNote function. Otherwise, the handleAddNote function will be executed.

Test the Implementation

After incorporating these changes, run your application. When you select a note, make modifications, and click on "Save", you'll observe the note gets updated.

Delete Notes from the UI

The last piece of functionality we need on the frontend before moving to the backend development is the ability to delete notes. You'll recall that we added a small "X" button to each note for this purpose. Clicking this button should remove the note from the UI. Let's jump back into the App.tsx file and implement this.

The `deleteNote` Function

First, create a function named deleteNote as follows:

const deleteNote = (event: React.MouseEvent, noteId: number) => {
  event.stopPropagation();

  const updatedNotes = notes.filter((note) => note.id !== noteId);

  setNotes(updatedNotes);
};

This function takes in two parameters: the event object and the noteId. The event.stopPropagation() line is crucial here because the delete button is nested within a clickable note. It prevents the deleteNote event from interfering with the click event on the note itself. This is especially important when dealing with nested onClick events.

The Filtering Logic

The core of the delete functionality lies in the filter method applied to the notes array. This method loops through the array and applies a function to each element, much like the map method. It will only return the notes whose IDs do not match the noteId provided, effectively removing the selected note.

We save this newly filtered array into a variable called updatedNotes and then update our state with it by calling setNotes(updatedNotes).

Add the `onClick` Event

After defining the deleteNote function, attach it to the delete button within the note. Pass in the event and the note ID, like so:

Test the Functionality

Now, if you run your app and click the delete button on a given note, you will observe that the note disappears from the UI.

PART 2 - Create the Backend

After implementing UI functionalities, it's time to set up a backend that allows us to persist notes when the user adds, edits, or deletes them. For this, create a new folder in your project at the top level and name it notes-app-server. Even though it might seem like the server code is in the same directory as the UI, they are entirely separate and will run independently.

Initial Setup

Open your terminal and navigate to the notes-app-server folder you just created.
Run the following commands:

npm init
npm i ts-node typescript nodemon @types/cors @types/express @types/node --save-dev
npm i @prisma/client cors express prisma
npx tsc --init

npm init: Initializes a new npm module and gives you access to npm packages.
npm i ... --save-dev: Installs development dependencies like TypeScript and type definitions.
npm i ...: Installs production dependencies like Express and Prisma.

Modify `package.json`

After running the above commands, navigate to your package.json and update the scripts section with:

"start": "npx nodemon"

This script uses nodemon for hot-reloading.

Implement the Server

Now, within the notes-app-server directory, create a src folder and within it, an index.ts file. Insert the following code:

import express from "express";
import cors from "cors";

const app = express();

app.use(express.json());
app.use(cors());

app.get("/api/notes", async (req, res) => {
  res.json({ message: "success!" });
});

app.listen(5000, () => {
  console.log("server running on localhost:5000");
});

import express and cors: We import the required libraries for our server.
const app = express();: Initializes a new Express application.
app.use(express.json());: Parses the JSON body from incoming API requests.
app.use(cors());: Adds CORS support.
app.listen(5000, ...): This starts the server listening on port 5000.

Test

Finally, you can test the server by navigating to the notes-app-server directory in your terminal and running:

npm start

You should see the console log: server running on localhost:5000. To further test, you can use a curl command to hit the /api/notes endpoint. If everything is set up correctly, you'll get a JSON object back.

Create a Postgres Database

ElephantSQL is a PostgreSQL database hosting service that makes it easy to set up, maintain, and scale your PostgreSQL database. Here's how to get started with creating a database using ElephantSQL.

Navigate to the ElephantSQL website.
If you don't have an account, you can sign up for free. If you already have one, go ahead and log in.

Step 2: Create a New Instance

Once logged in, you'll find yourself on the "Dashboard" page.
Click on the "Create New Instance" button.
You'll be taken to a page where you can set the details for your new PostgreSQL database instance.

Step 3: Choose a Plan

You can start with a free "Tiny Turtle" plan, which is perfect for small projects and testing.
Select the plan that best suits your needs and click "Select".

Step 4: Configure Your Instance

You'll be asked to name your instance. Choose a name that you'll remember and that describes the purpose of the database.
You can also select the data center that is geographically closest to you or your users for better performance.
Click on "Review" and then "Create instance" to finalize the creation.

Step 5: Access Your Database

Once the instance is created, click on it in the Dashboard.
Here, you'll see the "Details" tab which includes all the information you need to connect to your database: URL, User & Default database, Password, and more.

Populate the DB

Open your web browser and navigate to the ElephantSQL website. Log
in to your account.

Step 2: Open your Instance

Once logged in, click on the name of the database instance you've set up.

Step 3: Navigate to the SQL Browser

In the left sidebar, find and click on "SQL Browser" or something similar (it might say "Browser").

Step 4: Run SQL Query

In the SQL Query editor that appears, you can type or paste in your SQL command:

INSERT INTO "public"."Note" (title, content)
VALUES ('test title', 'test content bla bla');

After entering the SQL, click on the "Execute" or "Run" button.

That should insert a new row into your Note table with the title 'test title' and content 'test content bla bla'.

Optional: Verify the Insert

You may also want to verify if the data has been inserted correctly. For that, you could use:

SELECT * FROM "public"."Note";

Run this SQL query in the same SQL browser, and it should return all rows from the Note table, including the one you've just inserted.

And that's it! You've inserted a new row into your table through the ElephantSQL web console.

Connect to DB from Node.js backend using Prisma

Step 1: Copy the ElephantSQL Connection URL

Once you've set up your ElephantSQL database, make sure to copy the connection URL that appears on your dashboard. This URL includes your username and password to the database, so keep it secure.

Step 2: Create an `.env` File

Navigate to your notes-app-server directory and create a new .env file:

touch .env

Open this file and add the following line to specify the database connection URL:

DATABASE_URL="your_connection_url_here"

Make sure not to commit this .env file to your Git repository to keep your credentials secure.

Step 3: Initialize Prisma

If you haven't installed Prisma yet, install it first:

npm install prisma --save-dev

Now, initialize Prisma in the notes-app-server directory:

npx prisma init

This command will create a new prisma folder containing a schema.prisma file.

Step 4: Configure `schema.prisma`

Open schema.prisma in your text editor. You'll see that Prisma has already generated some configurations for you. Update the datasource block to use the environment variable:

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

Step 5: Create the Note Model

Below the datasource block, add a new model block to represent a Note:

model Note {
  id      Int     @id @default(autoincrement())
  title   String
  content String
}

Step 6: Generate Prisma Client and Database Table

Run the following command to generate your Prisma client and create the database tables:

npx prisma db push

Step 7: Add Prisma to Your Application

First, import Prisma at the top of your index.ts:

import { PrismaClient } from "@prisma/client";

Then, initialize the Prisma client:

const prisma = new PrismaClient();

Step 8: Query Your Database

Now you can use Prisma in your application to query the database. For example, in a GET endpoint:

app.get("/notes", async (req, res) => {
  const notes = await prisma.note.findMany();
  res.json(notes);
});

Optional: Install Thunder Client in VS Code

(Feel free to skip this step if you already have a preferred API client)

Using curl is useful for quickly testing APIs, but it becomes cumbersome when you need to build out more complex requests. For instance, handling POST requests with custom bodies and headers can be more complicated.

To make API requests more straightforward, we'll install a client designed for this purpose.

While there are several options like Postman, we're going to focus on installing Thunder Client within VS Code, which makes it simple to execute requests right from your IDE.

To install Thunder Client, navigate to the Extensions section in VS Code and type "Thunder Client" in the search bar. You'll find it in the list of available extensions, identifiable by its purple logo. Click "Install," and upon completion, you'll see a Thunder Client option appear on the left-hand taskbar of your IDE.

Once you've clicked on Thunder Client, a list of your past requests will display. To initiate a new request, click the "New Request" button at the top. This action opens a new tab within Visual Studio Code.

Before proceeding, ensure that your server is running. Open the terminal and verify this. We will use Thunder Client to test our GET endpoint and get familiar with the request-making process. In the URL bar, enter the address of your 'notes' endpoint and specify that it's a GET request.

Click "Send," and you'll see a small window displaying the response. If the status code is 200 and you see an array containing your note, you've successfully made a GET request. Thunder Client will be our tool of choice for testing subsequent create, update, and delete requests. Of course, feel free to use any other tool you're comfortable with for this purpose.

Create POST Endpoint

In this section, we'll add an endpoint to our Express application that allows us to create a new note. Locate the index.ts file and insert the following code below your existing GET endpoint:

app.post("/api/notes", async (req, res) => {
  const { title, content } = req.body;

  if (!title || !content) {
    return res.status(400).send("title and content fields required");
  }

  try {
    const note = await prisma.note.create({
      data: { title, content },
    });
    res.json(note);
  } catch (error) {
    res.status(500).send("Oops, something went wrong");
  }
});

The structure is similar to the GET endpoint, but we're using app.post this time. We specify the URL for this POST endpoint and then define our function.

Inside the function, the first task is to extract title and content from the req.body. This is what the UI will send when a user submits the "Add Note" form.

After obtaining title and content, we utilize the Prisma client that we set up earlier to create a new note. We pass the title and content to the prisma.note.create() method, which returns a new note object complete with an ID. This object is then sent back as a JSON response.

To test the endpoint, go to the Thunder Client tab in VS Code. Switch the HTTP method from GET to POST while keeping the URL the same. Click the "Body" tab, which should default to JSON, and input some test values for title and content. After hitting "Send," you should receive a 200 OK status along with the created note, containing an ID, title, and content.

For robustness, we've added validation and error-handling. If either title or content is missing, the server returns a 400 Bad Request status with an appropriate error message. To test this, remove either title or content from the request body and resend it. You should now see a 400 status code along with your error message.

Additionally, we use a try-catch block to handle any errors thrown by the Prisma client. This helps in cases of database connection issues or other unforeseen errors, preventing the backend from crashing.

Finally, you can test the GET endpoint again. It should now return two notes: the first one manually added to the database, and the second one just created through Thunder Client. Switch the method back to GET in Thunder Client and hit "Send"; you should see two notes in the response.

Create PUT Endpoint

In this segment of the tutorial, we'll focus on adding the ability to update a note. Add the following code snippet below the code for your previous POST endpoint:

app.put("/api/notes/:id", async (req, res) => {
  const { title, content } = req.body;
  const id = parseInt(req.params.id);

  if (!title || !content) {
    return res.status(400).send("title and content fields required");
  }

  if (!id || isNaN(id)) {
    return res.status(400).send("ID must be a valid number");
  }

  try {
    const updatedNote = await prisma.note.update({
      where: { id },
      data: { title, content },
    });
    res.json(updatedNote);
  } catch (error) {
    res.status(500).send("Oops, something went wrong");
  }
});

The structure of this app.put function is similar to the GET and POST endpoints you've already created. The major difference is the :id parameter in the URL. This acts as a placeholder, allowing you to specify the ID of the note you wish to update.

Inside the function, you'll notice we extract title and content from req.body, just like before. Additionally, we retrieve the ID from req.params and convert it to an integer using parseInt(), as our database stores IDs as integers.

We've added validation checks to ensure that the id exists and is a valid number. If either id, title, or content is missing or invalid, the API returns a 400 status code along with an error message.

Next, we use a try-catch block to attempt the update operation. Within the try section, we call the prisma.note.update() function. We specify the id in a where object and provide the new title and content via a data object. If the operation succeeds, the updated note is sent back in the response. In case of an error, the catch block will return a 500 status and an error message.

To test this, switch to your Thunder Client tab in VS Code. Update the method to PUT and set the URL to include the ID of the note you want to update, for example, /api/notes/3. In the request body, send JSON data with the new title and content. Upon hitting "Send", a 200 status should confirm the update. The returned note should reflect your changes.

To double-check, perform a GET request on the /api/notes endpoint. You should see the updated note in the list.

Lastly, test the validation by supplying an invalid ID, like a random string. The API should return an error message stating that the ID must be a valid number.

Create DELETE Endpoint

In addition to our existing endpoints, it's crucial to add validation for empty title or content fields in our app.put function, since these fields are required by our database. Revisit your app.put function in index.ts and add similar validation to what we added for the POST request. Specifically, if either title or content is empty, return a 400 status code along with an error message.

With that in place, let's move on to the DELETE endpoint. Add the following code just after your PUT endpoint:

app.delete("/api/notes/:id", async (req, res) => {
  const id = parseInt(req.params.id);

  if (!id || isNaN(id)) {
    return res.status(400).send("ID field required");
  }

  try {
    await prisma.note.delete({
      where: { id },
    });
    res.status(204).send();
  } catch (error) {
    res.status(500).send("Oops, something went wrong");
  }
});

This app.delete function works similarly to the update (app.put) endpoint. It also accepts an ID as part of the URL parameters (query params should be URL parameters or route parameters).

First, we validate that the provided ID is a valid number. If it isn't, we return a 400 status code and an accompanying error message.

Once the ID is validated, we proceed to delete the note using Prisma's delete method. In the try block, we specify which note to delete by its ID in the where object. Upon successful deletion, we return a 204 status code, which indicates 'No Content.' This is a standard way to signal to the frontend or API consumers that the deletion was successful.

If an error occurs during the deletion, the catch block returns a 500 status code along with a generic error message.

To test the new DELETE endpoint, switch your HTTP method to DELETE in your testing tool (like Thunder Client or Postman). Use the ID of the note you wish to delete, such as /api/notes/3, and hit 'Send'. You should receive a 204 status code, indicating the operation was successful. To confirm, perform a GET request on your /api/notes endpoint and observe that the note with the specified ID has indeed been removed.

PART 3 - Connect UI to Backend

Now that we have our backend and UI ready, it's time to connect them. We will do this by using the built in fetch function to call our backend from our UI.

Get and Display Notes

Let's dive back into our frontend code. Just below our state declarations at the top of our component, we're going to introduce a useEffect hook:

useEffect(() => {
  // ...
}, []);

Inside this useEffect, we'll define an asynchronous function named fetchNotes. We need to put this in a separate function because React does not support making the useEffect hook asynchronous directly:

const fetchNotes = async () => {
  // ...
};

To handle any potential errors from the API, we'll wrap our API logic inside a try-catch block:

try {
  // ...
} catch (e) {
  console.log(e);
}

Inside the try block, we use the native fetch function to make an API call. Our API is running at http://localhost:5000/api/notes. By default, fetch performs a GET request, which is what we need:

const response = await fetch("http://localhost:5000/api/notes");

After making the request, we'll process the response and convert it to JSON. The API returns an array of notes, which we'll capture in a variable named notes of type Note[]:

const notes: Note[] = await response.json();

If everything goes smoothly, the next step is to update our state with the notes fetched from the API:

setNotes(notes);

In the catch block, we'll log any errors that may occur:

console.log(e);

We've defined fetchNotes, but haven't called it yet. To invoke this function, add a call to fetchNotes() at the end of the useEffect block:

fetchNotes();

Lastly, add an empty dependency array to ensure that this code only runs once when the component is first mounted:

}, []);

After saving your changes, you should see the notes from your database displayed in the browser. If you've added or deleted notes directly through the database, those changes should be reflected here.

To wrap things up, you can remove any hardcoded array that you initially added to your notes state variable. Instead, populate it with the data fetched from the API:

const [notes, setNotes] = useState([]);

This ensures that the notes state is initially empty, then populated by the useEffect through the fetchNotes function.

Completed Code for this Section

  const [notes, setNotes] = useState([]);


  useEffect(() => {
    const fetchNotes = async () => {
      try {
        const response = await fetch(
          "http://localhost:5000/api/notes"
        );

        const notes: Note[] =
          await response.json();

        setNotes(notes);
      } catch (e) {
        console.log(e);
      }
    };

    fetchNotes();
  }, []);

Save New Note

Next, let's explore how to save a note to our backend. We already have a function called handleAddNote that deals with adding a note to the UI:

const handleAddNote = async (
  event: React.FormEvent
) => {
  // ...
};

To start, remove any code that manually creates a new note object on the frontend. This is because our backend will return this object with all its properties once the note has been saved to the database.

As in our previous example, we'll use a try-catch block to handle the API logic and error handling:

try {
  // API logic here
} catch (e) {
  console.log(e);
}

Place your existing state-changing function calls (setNotes, setTitle, and setContent) inside the try block. These will be executed after the API successfully saves the note:

setNotes([newNote, ...notes]);
setTitle("");
setContent("");

To call the API, we'll use the fetch function, similar to how we fetched notes. The difference is that this time, we need to pass a second argument to fetch to specify the HTTP method and payload:

const response = await fetch(
  "http://localhost:5000/api/notes",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      title,
      content,
    }),
  }
);

Don't forget to add the async keyword to the handleAddNote function signature if you haven't already, as we are using the await keyword inside the function.

The server will respond with the newly created note object, which we can then add to our UI. Convert the response to JSON and store it in a variable named newNote:

const newNote = await response.json();

Finally, in the catch block, we log any errors that might occur:

console.log(e);

Also, make sure to add headers to specify the content type of the data we are sending:

headers: {
  "Content-Type": "application/json",
}

Save your changes and test the functionality in the browser. Use the form to add a new note and click "Add Note." If everything is set up correctly, your new note should appear in the list.

Completed Code for this Section

  const handleAddNote = async (
    event: React.FormEvent
  ) => {
    event.preventDefault();
    try {
      const response = await fetch(
        "http://localhost:5000/api/notes",
        {
          method: "POST",
          headers: {
            "Content-Type": "application/json",
          },
          body: JSON.stringify({
            title,
            content,
          }),
        }
      );

      const newNote = await response.json();

      setNotes([newNote, ...notes]);
      setTitle("");
      setContent("");
    } catch (e) {
      console.log(e);
    }
  };

Save Updated Note

Next, let's explore how to save a note to our backend. We already have a function called handleAddNote that deals with adding a note to the UI:

const handleAddNote = async (
  event: React.FormEvent
) => {
  // ...
};

As in our previous example, we'll use a try-catch block to handle the API logic and error handling:

try {
  // API logic here
} catch (e) {
  console.log(e);
}

Place your existing state-changing function calls (setNotes, setTitle, and setContent) inside the try block. These will be executed after the API successfully saves the note:

setNotes([newNote, ...notes]);
setTitle("");
setContent("");

const response = await fetch(
  "http://localhost:5000/api/notes",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      title,
      content,
    }),
  }
);

Don't forget to add the async keyword to the handleAddNote function signature if you haven't already, as we are using the await keyword inside the function.

The server will respond with the newly created note object, which we can then add to our UI. Convert the response to JSON and store it in a variable named newNote:

const newNote = await response.json();

Finally, in the catch block, we log any errors that might occur:

console.log(e);

Also, make sure to add headers to specify the content type of the data we are sending:

headers: {
  "Content-Type": "application/json",
}

Save your changes and test the functionality in the browser. Use the form to add a new note and click "Add Note." If everything is set up correctly, your new note should appear in the list.

Completed Code for this Section

  const handleAddNote = async (
    event: React.FormEvent
  ) => {
    event.preventDefault();
    try {
      const response = await fetch(
        "http://localhost:5000/api/notes",
        {
          method: "POST",
          headers: {
            "Content-Type": "application/json",
          },
          body: JSON.stringify({
            title,
            content,
          }),
        }
      );

      const newNote = await response.json();

      setNotes([newNote, ...notes]);
      setTitle("");
      setContent("");
    } catch (e) {
      console.log(e);
    }
  };

Save Deleted Note

In this section, we'll discuss how to delete a note by invoking an API endpoint. We'll focus on the deleteNote function for this functionality:

const deleteNote = async (
  event: React.MouseEvent,
  noteId: number
) => {
  // ...
};

First, we need to make our function asynchronous to handle API calls. So, add the async keyword to the function declaration like this:

const deleteNote = async (
  event: React.MouseEvent,
  noteId: number
) => {
  // ...
};

Next, let's add a try-catch block to manage the API call. The catch block is essential for logging errors, which prevents the application from crashing unexpectedly:

try {
  // API logic here
} catch (e) {
  console.log(e);
}

Copy the existing UI-update logic you have and paste it into the try block, right after the API call. This ensures that the UI only updates if the API call is successful.

Now, let's get to the main part—making the API call to delete the note. To do so, we'll use the fetch API:

await fetch(
  `http://localhost:5000/api/notes/${noteId}`,
  {
    method: "DELETE",
  }
);

Note that the URL is a template string. It allows us to inject the ID of the note (noteId) that we want to delete. This noteId is passed into our deleteNote function when the user clicks the delete button corresponding to a specific note.

We specify the HTTP method as "DELETE" to indicate that we're requesting to delete a note:

method: "DELETE",

Unlike the 'add' or 'update' operations, there's no need to assign the API response to a variable, as we're not expecting any data to be returned:

await fetch(
  `http://localhost:5000/api/notes/${noteId}`,
  {
    method: "DELETE",
  }
);

After successfully deleting the note, we filter out the deleted note from our local notes state:

const updatedNotes = notes.filter(
  (note) => note.id !== noteId
);
setNotes(updatedNotes);

Finally, if everything goes smoothly and you save your changes, try running the application in the browser. Click the delete button for a specific note, and then refresh the page. You'll see that the note has been removed successfully.

Completed Code for this Section

  const deleteNote = async (
    event: React.MouseEvent,
    noteId: number
  ) => {
    event.stopPropagation();

    try {
      await fetch(
        `http://localhost:5000/api/notes/${noteId}`,
        {
          method: "DELETE",
        }
      );
      const updatedNotes = notes.filter(
        (note) => note.id !== noteId
      );

      setNotes(updatedNotes);
    } catch (e) {
      console.log(e);
    }
  };

The End - Why not try the bonus challenges?

Congratulations on making it to the end! If you enjoyed this project, I have created a list of additional challenges to try over at codecoyotes.com.

If you have any questions or suggestions feel free to drop me a message here. See you in the next one!

full stack - freeCodeCamp.org

How to Build a Fashion App That Helps You Organize Your Wardrobe

Table of Contents

What the App Does

Why I Built It

Tech Stack

Product Walkthrough (What Users See)

1. Onboarding and Account Setup

2. Wardrobe Upload

3. Outfit Recommendations

4. Shopping and Discard Assistants

How I Built It

1. Frontend Setup (React + Vite)

2. Backend Architecture with FastAPI

3. Recommendation Logic

4. Authentication and Secure Multi-user Design

5. Background Jobs for Long-running Operations

6. Data Model and Feedback Capture

Challenges I Faced

1. Image-heavy endpoints were slower than I wanted

2. JWT sessions needed real server-side control

3. User data isolation had to be explicit

4. Docker made the project easier to share, but only after the stack was organized

What I Learned

What I Want to Improve Next

Future Improvements

Conclusion

How to Build a Full-Stack CRUD App with React, AWS Lambda, DynamoDB, and Cognito Auth

What You'll Build

Table of Contents

Who This Is For

Prerequisites

Architecture Overview

Part 1: Set Up Your AWS Account and Tools

1.1 Create Your AWS Account

1.2 Install the AWS CLI and CDK

1.3 Configure Your AWS Credentials (IAM)

Phase 1: Create an IAM User

Phase 2: Generate Access Keys

Phase 3: Connect Your Terminal to AWS

Part 2: Set Up the Project Structure

2.1 Create the Workspace

2.2 Initialize the Frontend (Next.js)

2.3 Initialize the Backend (CDK)

2.4 Understanding CDK Before You Write Any Code

Part 3: Define the Database (DynamoDB)

Part 4: Write the Lambda Functions

A Note on the AWS SDK

4.1 Create Vendor Lambda

4.2 Get Vendors Lambda

4.3 Delete Vendor Lambda

Part 5: Build the API with API Gateway

5.1 Add Lambda Functions and API Gateway to the Stack

Part 6: Deploy the Backend to AWS

6.1 Bootstrap Your AWS Environment

6.2 Deploy

6.3 Troubleshooting: How to Read AWS Error Logs

Error: 502 Bad Gateway

Part 7: Build the React Frontend

7.1 Define the Vendor Type

7.2 Create the API Service Layer

7.3 Build the Main Page

Vendor Tracker

Add New Vendor

Current Vendors ({vendors.length})

7.4 Test the App Locally

Verifying the connection to AWS:

Part 8: Add Authentication with Amazon Cognito

8.1 Add Cognito to the CDK Stack

8.2 Install and Configure AWS Amplify

8.3 Wire Providers into the App Layout

8.4 Protect the UI with withAuthenticator

Add New Vendor

Current Vendors ({vendors.length})

8.5 Pass the Auth Token to API Calls

8.6 Troubleshooting Cognito

"Unconfirmed" user error after sign-up

401 Unauthorized errors after deployment

Part 9: Deploy the Frontend with S3 and CloudFront

9.1 Configure Next.js for Static Export