Bragging on social media about a clever script is one thing, but pushing a vibe coded app to prod comes with many security risks.

With so many AI dev tools out there now, code reviews become more critical than ever.

This article will explore what vibe coding means and how code reviews should adapt in the era of AI.

Table of Contents:

1. What is Vibe Coding?

2. How to Implement Vibe Coding in Practice

3. Why isn’t Vibe Coded Output Production Ready?

   • Context gaps are the first crack.

   • Those gaps lead directly to integration blind spots.

   • The most serious risk is security by omission.

   • Testing and correctness evidence are thin.

   • Operability lags behind.

4. Guidelines for AI Code Reviews

   • Code Review Process in Vibe Coding

5. Checklist for Reviewing AI Generated Code

6. How to Work Effectively with AI Tools

7. Conclusion

What is Vibe Coding?

In early 2025, AI researcher Andrej Karpathy popularized the term vibe coding to describe a new way of development in which you “fully give in to the vibes” and let AI write code while you focus on high level intent.

A developer expresses their desired functionality in plain language, and an AI system (like an LLM) generates the source code to implement it.

This code-by-prompt approach allows even beginners to produce working code without deep knowledge of programming languages. Karpathy joked that with advanced IDE agents (like Cursor’s Composer mode), “I barely even touch the keyboard... I ‘Accept All’ always, I don’t read the diffs anymore... and it mostly works”.

So, vibe coding is coding by vibe and trusting AI to handle the heavy lifting.

How to Implement Vibe Coding in Practice

In practice, vibe coding usually involves using AI assistants and adapting your workflow to a more interactive, prompt-driven style.

Here’s an overview of how you can “vibe code” a project:

Step 1: Choose an AI assistant

Select a development env that supports AI code generation. Popular choices include Cursor and GitHub Copilot.

Step 2: Define your requirements

Instead of writing boilerplate code, describe what you want to build. Provide AI with a specific prompt detailing functionality. The more context and detail you give, the better AI can fulfill your intent.

For example, when I ran an SEO inspection for my website, DevTools Academy, I used this prompt in Cursor:

“Now, act as a senior product engineer and UX strategist. Evaluate and improve https://www.devtoolsacademy.com with a practical, no-fluff lens.

Scope:

• UX

• SEO and technical SEO

• Positioning and messaging

• Copywriting and information architecture

• What to add to stand out in the developer tools space.”

This prompt works well because it gives the AI a clear role, a defined scope, and a specific intent. AI knows it’s not just fixing SEO but also reviewing how the site communicates value to devs. That combination of clarity and context produces actionable insights instead of surface-level suggestions.

Below is a screenshot of that audit in progress and showing how I reviewed code, metadata, and UX recommendations side by side.

You can checkout the full code on my open source blog here and check out closed PRs. This will help you learn how I use all these coding agents on a production ready app.

Step 3: Review the code

AI will produce initial code based on your prompt. Think of this as a prototype – it’s not perfect. Run the code and see how it behaves.

Let’s look at an example: here, CodeRabbit is reviewing one of my pull requests on GitHub. I had pushed a small fix to sort blog posts correctly and make sure the RSS feed reflects the latest publish date. Within seconds, CodeRabbit analyzed the diff, understood the intent behind my change, and explained exactly what the new code does.

It pointed out that the fix now sorts posts before mapping them, uses the sorted data for both items and the lastBuildDate, and ensures proper chronological order throughout the feed.

It’s like having a senior reviewer who not only checks syntax but also validates logic and confirms that your reasoning holds up.

This is just a reminder to expect imperfections. Vibe coding embraces a “code first, refine later” mindset. This means you get a working version quickly, then iteratively improve it. You might go through a few cycles of prompt -> code -> test -> tweak.

Step 4: Validate, debug, polish

Once AI generated code meets your expectations, do a final review.

Throughout the process, the core idea is that you collaborate with the AI. The AI agent serves as a coding assistant, making real-time suggestions, automating tedious boilerplate, and even generating entire modules on your behalf.

Why Isn’t Vibe Coded Output Production Ready?

Vibe coding moves fast: you describe intent, the AI produces something that runs, and you’re off to the next prompt. What’s missing is the slow, unglamorous work that usually turns a draft into shippable software, like shared context, architectural alignment, verification, and documentation.

AI generates plausible code based on patterns it has seen. But it doesn’t understand your team’s history, your system’s constraints, or the implicit rules that keep everything coherent over time.

That mismatch shows up the moment a “works on my machine” demo meets a real codebase.

Let’s explore the common pitfalls of vibe-coded code, so you’ll know what to watch for. Then, in the checklist section below, I’ll outline practical strategies to address or prevent each issue.

Context gaps are the first crack.

AI only sees what you show it, so it’s easy for it to make the right local choice and the wrong global one: duplicating logic that already exists, choosing defaults that conflict with prior decisions, or introducing functions that don’t respect domain boundaries.

The result is code that looks reasonable in isolation but collides with existing assumptions and conventions once integrated.

Those gaps lead directly to integration blind spots.

Drafts often ignore the lived details of your environment – shared utilities, cross-cutting concerns, configuration, deployment hooks, and operational policies. Interfaces may line up at a glance and still fail at runtime because the draft doesn’t fit how your system composes modules, handles errors, or manages state across services.

The most serious risk is security by omission.

AI rarely includes robust input validation, clear authentication and authorization paths, or rate limiting unless you spell it out. Secrets handling and logging tend to be superficial or missing. That leaves common exposure points like request handlers, job processors, and webhook endpoints without the checks that prevent injection, SSRF, mass assignment, or data exfiltration.

Even when the surface looks tidy, the absence of explicit security controls means you’re trusting defaults you didn’t choose.

Testing and correctness evidence are thin.

Quality suffers in quieter ways, too. Beyond “it runs,” there’s little to demonstrate behavior across edge cases or to guard against regressions.

Performance and scalability remain unknowns: extra network calls, N+1 patterns, and quadratic loops sneak in because nobody measured them. Dependencies and environments drift as versions aren’t pinned, infrastructure isn’t declared, and configuration lives only in the author’s head, making behavior differ across machines and CI.

Operability lags behind.

A lack of metrics, missing health/readiness probes, and no runbook make failures harder to detect and slower to recover from. Add in data quality and compliance concerns (PII handling, encoding assumptions, transitive license obligations), and you have code that demos well but isn’t ready for production’s reliability, security, and audit demands.

In short, vibe-coded output accelerates drafting but skips the shared understanding and evidence that make software safe to ship.

Until those gaps are closed, it’s a prototype, not a release.

Guidelines for AI Code Reviews

Your team should keep pre-AI engineering standards as the bar, including security, tests, readability, maintainability, performance, and docs. AI should change how fast you gather the evidence for those standards, not how much evidence you require. In other words, use AI to accelerate the path to your existing bar, never to lower it.

Using AI, you can generate code at speed. But if reviews take the same amount of time (or more time), you lose some of the benefit. The goal isn’t to relax standards, it’s to shorten the time to prove you met them. That means layering in automation (tests, static analysis, secret scans, SCA) and AI-assisted review to catch obvious issues quickly so human reviewers can focus on intent, architecture, and risk.

Well-used assistants can help here. For example, tools like CodeRabbit, GitHub Copilot PR Reviewer, Claude Code, Cursor’s Bugbot, Graphite’s AI Review, and Greptile can highlight potential bugs, security gaps, style deviations, and mismatched intent, and summarize diffs for faster context. Treat these as accelerators for your existing process, not as replacements for judgment.

Code Review Process in Vibe Coding

The fundamentals of good code reviews haven’t changed – and in fact, they’re more critical now.

Below are some key principles to maintain speed without sacrificing quality.

1. Trust, but verify.

A reviewer usually assumes the author understands the system. With vibe-coded output, the “author” may be an AI with limited context. If something looks odd or unnecessary, question it. Run the code, add/execute tests, or ask the developer/AI for clarification on intent and constraints.

2. Don’t let reviews become a bottleneck.

Vibe coding generates code quickly. If human review takes as long as hand-writing the change, you’ve erased the gain.

Combat this by front-loading automation: run unit/integration tests, static analysis (lint/SAST), secret scans, SCA, and basic perf checks in CI to clear the noise. Then reviewers spend their time on design trade-offs, boundary cases, and risk. The balance is: high standards, faster evidence.

3. Use AI code reviews wisely

AI can help review code just as it helps generate it. Modern “pair reviewer” tools scan a PR and surface likely bugs, security issues, missing tests, or style violations in minutes plus give natural-language summaries of the change.

Tools you can consider include CodeRabbit, GitHub Copilot PR Reviewer, Claude Code, Cursor Bugbot, Graphite, and Greptile. Many integrate with the CLI/IDE and GitHub/GitLab to leave actionable comments.

Think of them as fast first-pass reviewers that increase coverage and consistency across PRs.

4. Human judgment is still irreplaceable.

Even the best AI reviewer is an assistant. Keep humans accountable for correctness, security posture, architectural fit, and user impact. A healthy pattern is AI first-pass > human second-pass that inspects invariants, failure modes, and long-term maintainability.

5. Maintain a high bar for quality.

It’s tempting to accept “it runs” when an AI wrote it. Don’t. Stakeholders still expect software to be robust, secure, and maintainable. Keep DRY, readability, and testability standards. Insist on input validation, authZ checks where relevant, and sensible logging/metrics. If you can’t provide evidence that you met the bar, you haven’t met it.

6. Educate and document

When reviewers find bugs or security flaws in AI-generated code, capture the lesson.

Update internal guides with patterns like “When generating handlers, validate and bound inputs, add rate limits, log request IDs, avoid N+1 queries, and sanitize user-visible output.” Over time, bake these into prompts, templates, repo scaffolds, and CI checks so the next AI draft starts closer to done.

Checklist for Reviewing AI Generated Code

Before approving any vibe-coded change, make the standards explicit and verifiable. Use this checklist to confirm behavior, security, performance, integration, and documentation so the draft you got from AI becomes code you can safely ship.

Here’s a checklist a human reviewer should go through before approving vibe-coded output:

1. Define the code’s purpose (scope & non-goals).

Be explicit about what this change does and does not do. Tie it to a user story/ticket and call out non-goals so “helpful” AI changes don’t creep in.

2. Verify X and Y (behavior and edge cases).

Be clear about what you’re verifying. For example, verify input parsing and pagination boundaries, verify that error paths return the correct status and body, and verify that database writes are idempotent. Run existing tests, add missing unit/integration tests, and reproduce edge inputs (empty, null, huge, unicode).

3. Perform code-quality checks (readability, DRY, refactor needs).

AI often produces verbose or duplicated logic. Ensure names are meaningful, side effects are clearly stated, and duplication is removed or minimized. Run linters/formatters, collapse repetition, and extract helpers where they aid clarity.

4. Analyze organization and structure (make sure it fits the architecture).

AI writes code in isolation. Confirm the change uses existing utilities, layers, and boundaries (domain/services/controllers/jobs). Check imports and module placement, avoid reinventing existing helpers, and align with repository conventions.

5. Validate inputs and assumptions (make the implicit explicit).

List the assumptions the AI made (default locale/timezone, allowed ranges, required fields). Add schema validation (DTO/class validators/JSON Schema). Empty, null, over-max, non-ASCII, unexpected enum, malicious strings. And finally, enforce limits/timeouts.

6. Perform security audits (minimum pass).

• AuthN/AuthZ: Confirm endpoint checks identity and authorization paths; deny-by-default.

• Inputs: Sanitize/validate inputs, prevent injection (SQL/NoSQL/command), and escape user-visible output.

• Secrets: No secrets in code/diff/logs, use env/secret manager, and rotate any test keys.

• Abuse controls: Add rate limits, size limits, and timeouts on network and disk operations. Run SAST/secret scan/SCA, and fix or justify findings.

7. Do a performance evaluation (right now, at a small scale).

Look for N+1s, needless network calls, unbounded loops, quadratic sorts. Add a micro-benchmark or run a quick load test for hot paths. Set sensible cache/timeout/retry with jitter where applicable.

8. Manage dependencies (pin, justify, minimize).

Review any new libraries. Are they necessary? Maintained? License compatible? Pin versions, add lockfiles, or remove unused transitive adds.

9. Review documentation (what to add and where).

Ensure the docs are in line with the code. AI often changes some parts or adds code blocks at different places while resolving various issues. These changes might not make it into the docs.

10. Observability (see problems early).

Use structured logs with request/trace IDs, key counters/timers (success/error/latency), health/readiness probes, and a basic dashboard or alert stub.

11. Compliance and data handling (when applicable).

Identify any personally identifiable information (PII), document collection/retention, ensure masking/redaction in logs, verify dependency licenses and data-residency constraints.

How to Work Effectively with AI Tools

At this point, you can probably see why it’s very important to understand the actual skills involved in AI-assisted development.

There’s a pretty big difference between an experienced developer who uses AI tools to help them get more done, and a newbie who thinks AI can build the next Facebook or Google just with a simple prompt.

An inexperienced dev will ask AI something like "Hey, Build me Twitter and make no mistakes"

But an experienced developer who has a solid fundamentals might say say something like:

• "AI, we're building a Twitter replica. Use $SQL_Database, Use $Language, Avoid $Common_Pitfalls, Follow $Standard_Practices."

• "The generated code is prone to X problem, implement this fix."

• "Implementation of $X is flawed because of $Y, do $Z instead."

So as you can see, you still need to know the how's and the why's and what depends on what. Often you’ll just need to make the changes manually, because it will be faster. And you don’t want to outsource the critical thinking part, which is the part that AI can't actually do.

LLMs are good at information retrieval. If you know nothing about what you’re looking for, then asking an AI isn’t going to be that helpful (or that reliable). But if you have an idea, some background knowledge/context, and the skills to verify AI’s responses, then it can be really helpful.

Last month, I shared in my newsletter how my current coding loop looks in practice.

I draft with Claude Code (or Copilot/Cursor), open a PR, and let an AI reviewer like CodeRabbit (or Copilot PR Reviewer / Cursor Bugbot or Greptile) do the first pass. CI runs tests and scans.

I repeat until everything’s green and the PR is ready to merge. It’s fast, but it’s still disciplined.

If you want to understand why this kind of workflow is becoming essential, read this article: Era of AI Slop Cleanup Has Begun. I talk about what’s happening in AI-assisted engineering, where generating code is easy, but keeping it clean and production ready takes experience – and you must have good programming skills.

Conclusion

AI-generated code can boost productivity – but production value still comes from software that is robust, secure, and maintainable.

Mindless code generation creates technical debt. But when you integrate AI thoughtfully, with guardrails, verification, tests, security checks, and documentation, you can go faster without lowering your standards.

That's it for this article. I hope you learned something new today.

If you have any questions about code reviews, engineering, startups, or business in general, please find me on Twitter: @TheAnkurTyagi. I’d be more than happy to discuss them.

Want to read more interesting articles like this?

You can read more about the latest dev tools like this one on my website.

And managers frequently view refactoring as "not a business need" until it boils over and becomes the most significant business need possible.

"Oh, our software somehow works. We can't implement any new changes. And oh, everyone is quitting because work is miserable."

In this article, I’ll walk you through the steps I use to refactor a complex codebase. We’ll talk about setting goals, writing tests, breaking up monoliths into smaller modules, verifying changes, making sure existing features still work, and keeping tabs on performance. I’ll also show you how to speed up reviews using AI tools.

By following these steps, you can turn complex, fragile code into a clean, reliable codebase your team can own.

The Issue of Technical Debt

As projects grow and evolve, technical debt increases. Code that was once functional and manageable turns into an unmaintainable mess, where even small changes become risky and time-consuming.

Despite the obvious need for cleanup, refactoring rarely gets prioritized because there's always something more urgent, new features, bug fixes, and client demands.

I’ve had conversations with engineers, many of whom are working on enterprise software and are fully aware of their codebase's code smells and inconsistencies. They dislike the situation but feel powerless to change it.

So how do we shift from a culture of writing for pure functionality to a culture that values maintainability, especially for complex codebases?

It’s usually a mistake to completely halt new feature development for a long refactoring period (except perhaps in emergencies). Business needs still exist, and putting everything on hold can create tension and lost opportunities. It’s better to find a balance so you’re still delivering value to users even as you clean under the hood.

While there is no one-size-fits-all solution, a structured approach can help teams introduce sustainable refactoring practices, even in environments where management is resistant. Let’s explore how this works.

Table of Contents:

• What is Refactoring?

• Preparing for Refactoring

  • Secure Management Buy-in

  • Ensure a Safety Net with Automated Testing

  • Identify High-Risk Areas

  • Set Clear Refactoring Goals

• Techniques for Refactoring Complex Codebases

  • 1. Identifying and Isolating Problem Areas

  • 2. Incremental vs. Big Bang Refactoring

  • 3. Breaking Down Monolithic Code

  • 4. Ensuring Backward Compatibility

  • 5. Handling Dependencies and Tight Coupling

  • 6. Testing Strategies (Safely Refactoring with Confidence)

  • 7. Refactoring Without Breaking Performance

  • 8. Automate Code Reviews with AI Tools

  • Summary

What is Refactoring?

Many people all too often use the word "refactor" when they mean a targeted rewrite.

As Martin Fowler famously said,

“Refactoring is a controlled technique for improving the design of an existing code base. Its essence is applying a series of small behavior-preserving transformations... However, the cumulative effect... is quite significant.”​

In practice, this means continuously polishing code to reduce complexity and technical debt.

While traditional software development follows a linear approach of designing first and coding second, real-world projects often evolve in ways that lead to structural decay. Refactoring counteracts this by continuously refining the codebase, transforming disorganized or inefficient implementations into well-structured, maintainable solutions.

A targeted rewrite is a focused overhaul of a specific aspect of an application, often affecting multiple parts of the codebase. It carries more risk than refactoring but is still controlled and contained.

Preparing for Refactoring

Even the most skilled refactoring effort can stall without proper preparation. Before you start moving code around, laying a foundation that will keep your work organized and your team on the same page is crucial.

Here are some steps you can take to ensure your refactoring efforts are successful.

Secure Management Buy-in

As I’ve already discussed, getting time for refactoring can be difficult in feature-driven organizations. Often, management will accept refactoring investment if you can tie it to business outcomes, faster time to market, fewer outages (which translates to happier customers), and the ability to take on new initiatives.

Make those connections explicit. For example, you could say:

“If we refactor our reporting engine now, it will make it feasible to add the analytics module next quarter, which unlocks a new revenue stream.”

Or use data:

“We spent 30% of our last sprint fixing bugs in module Y. After refactoring Y, we expect that to drop significantly, freeing time for new features.”

Business-minded arguments help justify the balance.

Ensure a Safety Net with Automated Testing

As you refactor, tests are your safety net. Before modifying a component, write characterization tests around it if they don’t exist.

# example: characterization test for a legacy function
def legacy_calculate_discount(price, rate):
    # ... complex logic you don't fully understand yet ...
    return price * (1 - rate/100) if rate < 100 else 0

def test_legacy_calculate_discount():
    # capture existing behavior
    assert legacy_calculate_discount(100, 10) == 90
    assert legacy_calculate_discount(50, 200) == 0

These tests capture the current behavior, so you’ll know if you accidentally change it. Unit tests, integration tests, and e2e tests all validate that refactoring hasn’t broken anything.

It’s often worth investing time in setting up a continuous integration pipeline so that every change triggers automated tests. This gives rapid feedback and confidence that you’re not introducing regressions. Robust testing and CI/CD enable you to move faster and refactor with peace of mind.

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with: python-version: '3.10'
      - run: pip install -r requirements.txt
      - run: pytest --maxfail=1 --disable-warnings -q

Identify High-Risk Areas

The first step is to figure out what to refactor. High-risk areas are parts of the code likely to cause bugs or slow development. Common signs include long methods, large classes, duplicate code, and complex conditional logic​.

Such code “smells” often hint at deeper design problems. Tools like static analysis can automatically flag these issues.

For example, SonarQube will mark code smells (like high complexity or long methods) that increase technical debt​. Using SonarQube or similar tools, you can generate reports on code complexity (for example, cyclomatic complexity metrics​) and find hotspots in the codebase that need more attention.

Set Clear Refactoring Goals

Before refactoring code, define the goal.

Goals must be specific and measurable. For example, you might aim to reduce a class’s size or a function’s cyclomatic complexity by a certain amount or to increase unit test coverage from 60% to 90%.

Each goal is tied to a measurable outcome: shorter methods, fewer if statements or classes with a single responsibility, faster execution for processing orders, higher test coverage, and no unused code. These targets will guide our refactoring plan and let us verify when we’ve succeeded.

Tip: Write down your refactoring goals and share them with your team. This sets expectations that you’re not adding new features in this effort, just making the code cleaner and more robust. It also helps justify the time spent by showing the benefits (like more straightforward future additions and fewer bugs).

Techniques for Refactoring Complex Codebases

1. Identifying and Isolating Problem Areas

It can be overwhelming to decide where to start refactoring a large codebase. Not every part of the code needs refactoring – some areas are delicate or rarely touched.

The most impactful refactoring efforts typically target the “problem areas”: parts of the codebase that are overly complex, error-prone, or act as bottlenecks for development and performance. Identifying these areas is a crucial first step.

Techniques for Finding Hotspots

Team knowledge & developer frustration

Don’t underestimate the value of anecdotal information from the team. Which parts of the code do developers dread working in? Often, the team’s instincts point to areas that are hard to understand or modify (for example, “the accounting module is a black box, we hate touching it”). These could be areas to improve.

In my experience, simply asking, “If you had a magic wand, which part of the code would you rewrite?” yields very insightful answers.

Code complexity metrics

Use static analysis tools to measure cyclomatic complexity, code duplication, large functions/classes, and so on. Files or modules with extremely high complexity numbers or thousands of lines are good candidates for scrutiny. But static complexity alone doesn’t tell the whole story – a file might be ugly but rarely touched.

Change frequency (Churn)

Look at version control history to see which files are often changed, especially those associated with bug fixes or incidents.

Hotspot analysis

A robust approach combines complexity and change frequency to find “hotspots.” For example, a tool or technique plotting modules by their complexity and how often they change can highlight the problematic areas. CodeScene (a code analysis tool) popularized this: hotspots are parts of the code that are highly complex and frequently modified, indicating areas where “paying down debt has a real impact”​.

If a module is a mess and developers are in it every week, improving that module will likely yield outsized benefits (fewer bugs, faster adds).

Performance bottlenecks and crashes

Some parts of the codebase become targets for refactoring because they cause frequent performance problems or outages. For instance, if a specific service or job crashes often or can’t keep up with the load, you might need to refactor it for stability.

How to Isolate Problem Areas

Once you’ve identified a hotspot or problem area, the next challenge is isolating it so you can refactor safely. In a complex system, nothing lives in complete isolation. That problematic module likely interacts with many others.

Here are strategies to isolate and tackle it:

Break dependencies (Create seams)

Michael Feathers (in Working Effectively with Legacy Code) introduced the concept of “seams” – places where you can cut into a codebase to isolate a part for testing or refactoring. This might mean introducing an interface or abstraction between components so you can work on one side independently.

For example, suppose PaymentService is tightly coupled to StripeGateway, with direct calls scattered throughout the code.

# payment_service.py

def charge_customer(order_id, amount):
    # Hardcoded dependency to Stripe
    stripe = StripeGateway()
    stripe.charge(order_id, amount)

To isolate and refactor the payment logic safely, you can introduce a PaymentProcessor interface and have PaymentService depend on that interface instead. Then, create an adapter like StripeAdapter that implements PaymentProcessor and delegates to the existing Stripe logic.

This way, you can safely refactor or even replace the Stripe integration behind the StripeAdapter without impacting PaymentService or any other module that uses it. As long as the PaymentProcessor interface is honored, the rest of the system remains unaffected.

# interfaces.py

class PaymentProcessor:
    def charge(self, order_id, amount):
        raise NotImplementedError


# stripe_adapter.py

class StripeAdapter(PaymentProcessor):
    def charge(self, order_id, amount):
        # Internally still uses Stripe
        stripe = StripeGateway()
        stripe.charge(order_id, amount)


# payment_service.py (Refactored)

class PaymentService:
    def __init__(self, processor: PaymentProcessor):
        self.processor = processor

    def charge_customer(self, order_id, amount):
        self.processor.charge(order_id, amount)

“Branch-by-abstraction”

This technique is related to the above and is often used in continuous delivery. The idea is to add a layer of abstraction (like an interface or proxy) in front of the old code, have both old and new code implementations behind it, and then gradually shift usage from the old to the new implementation. For a while, you might have a temporary state where both versions exist (perhaps toggled by a config or feature flag).

This is similar to how the strangler fig pattern works at an architectural level. It’s a bit of extra work (since you maintain two paths for a while), but it allows you to migrate functionality and fall back if needed incrementally.

Aim to identify the 20% of the code causing 80% of the problems. Focus your refactoring energy there for maximum impact. When you do, create a plan to isolate that area via abstractions, interfaces, modules, or other means so that you can work on it with minimal risk of side effects. The more you can contain the blast radius of a refactoring, the more confidently you can move forward.

2. Incremental vs. Big Bang Refactoring

One of the first strategic decisions is approaching the refactor incrementally or going for a “big bang” overhaul. In most cases, an incremental approach is preferable, but there are scenarios where more significant coordinated refactoring steps are considered.

Let’s break down what these mean:

# before: one large function with multiple responsibilities
def process_order(order):
    validate(order)
    apply_discount(order)
    save_to_db(order)
    send_confirmation(order)
    log_metrics(order)
    update_loyalty_points(order)
    # potentially more steps 

# after: refactored incrementally into clearer, smaller units
def process_order(order):
    validate(order)
    apply_discount(order)
    persist_and_notify(order)

def persist_and_notify(order):
    save_to_db(order)
    send_confirmation(order)
    log_metrics(order)
    update_loyalty_points(order)

Incremental refactoring

This means making small, manageable changes over time rather than attempting a massive overhaul in one shot. The system should remain functional at each step (even internally in transition). The advantage is risk mitigation: each small change is less likely to go wrong, and it’s easier to pinpoint and fix if it does.

Incremental delivery lets you confirm changes in production and makes diagnosing issues easier since you’re only changing one small thing at a time​. It also means the system keeps running during the refactor, so there’s less pressure to rush to “get the system back to working condition”​. If priorities shift, you can pause after some increments and still have a working product.

Big bang refactoring (Rewrite)

This is the “tear it down and rebuild” approach. You stop adding new features, possibly freeze the code for a period, and devote a considerable effort to redesigning or rewriting a significant portion (or the entirety) of the system. The idea is to emerge on the other side with a brand new, clean system.

So when (if ever) is a big bang justified? Perhaps when the existing system is truly untenable – for example, an outdated technology that must be replaced (such as a platform that can’t meet new performance or security requirements or code written in a language no longer supported). Even then, wise teams often simulate a big bang by breaking it into stages or developing the new system in parallel.

Whenever possible, favor an incremental refactoring strategy. Teams successfully pull off massive transformations by treating the big refactor as a series of mini-refactors under a shared vision.

3. Breaking Down Monolithic Code

Many complex codebases start life as a single monolithic application, one deployable, a single code project, or a tightly coupled set of modules all maintained and released together.

Over time, monoliths can become unwieldy, builds take forever, a change in one area can unintentionally affect another, and teams can be complex to scale because everyone is stepping on each other’s toes in the same code. A common refactoring challenge for senior engineers is modularising or splitting a monolith into more manageable pieces.

# define the interface
class PaymentProcessor:
    def charge(self, amount): ...

# old implementation
class LegacyProcessor(PaymentProcessor):
    def charge(self, amount):
        # original code

# new implementation behind a feature flag
class NewProcessor(PaymentProcessor):
    def charge(self, amount):
        # cleaner code

def get_processor():
    if config.feature_new_payment:
        return NewProcessor()
    return LegacyProcessor()

# usage remains the same
processor = get_processor()
processor.charge(100)

Strategies for modularization.

• Layer separation: Start by enforcing logical layer boundaries. For example, separate the user interface code from business logic and separate business logic from data access. In a messy monolith, these concerns often get mixed together. By organizing the code into layers (even within the same repository), you can limit the ripple effect of changes.

• Domain-based modularization: If your system spans multiple business domains or functional areas, consider splitting along those lines. For example, an e-commerce monolith might be separated into modules like Accounts, Orders, Products, Shipping, and so on.
  Each could become a subsystem or a package. The goal is to minimize the information these modules need to know about each other’s internals (high cohesion within modules and clear APIs between them).

• Microservices or services extraction: In recent years, the trend has been to break monoliths into microservices, independent services that communicate over APIs. This form of architectural refactoring can significantly improve independent deployability and scalability. But it’s a significant undertaking with complexities (distributed systems, network calls, and so on). If you decide to go this route, do it gradually.
  A proven method is the strangler fig pattern mentioned earlier: you pick one piece of functionality and rewrite or extract it as a separate service, redirect traffic or calls to the new service. At the same time, the rest of the monolith remains intact and iteratively does this for other pieces​.

• Modular monolith: Not every system needs to go full microservices. There’s an approach called a modular monolith, essentially structuring your single application into well-defined modules that communicate via explicit interfaces (almost like internal microservices but without the overhead of separate deployments).

This can give you many microservices' advantages (clear boundaries, separate development responsibility) while avoiding operational complexity.

• Identify shared utilities vs. truly independent components: In breaking down a monolith, some code is widely shared (like utility functions or cross-cutting concerns such as authentication). It might make sense to factor those into libraries or services first, as they will be needed by whatever other pieces you split out.

While breaking down a monolith, maintaining functionality during the transition is essential. Techniques like backward compatibility (discussed next) and thorough testing will be your safety net.

Finally, be prepared for the team workflow to change. If you move to microservices, teams might take ownership of different services, requiring more DevOps and communication across teams. If you keep a modular monolith, enforce code ownership or review rules to keep the modules from tangling up again (for example, you might restrict direct database access from one module to another’s tables, and so on).

4. Ensuring Backward Compatibility

A critical concern during large refactoring is: Will our changes break existing contracts?

In other words, can other systems, modules, or clients that rely on our code work as expected after we refactor? Backward compatibility is especially important if your codebase provides public APIs (to external customers or other teams), data persisted in a certain format, configuration files that users have written, etc.

Here are some strategies and considerations to maintain backward compatibility:

Suppose you have a widely-used function like send_email(to, subject, body). You want to refactor the internal logic to support additional features like HTML formatting, but you don’t want to break existing callers.

Instead of changing the function signature, you keep the public API unchanged and delegate to a new internal function:

# original API
def send_email(to, subject, body):
    # send mail...

# refactored internals, keep signature
def send_email(to, subject, body):
    sendv2(to=to, subject=subject, body=body)

def sendv2(to, subject, body, html=True):
    # new implementation with HTML support

The internal send_email_v2() function adds new capabilities like HTML formatting, but older code using send_email() still works without any modifications.

If you're introducing a new, improved version like send_email_v2(to, subject, body, html=True), it's good practice to:

• Mark the old version (send_email) as deprecated in documentation.

• Ensure the old version internally calls the new one.

• Give other teams time to migrate at their own pace.

Use versioning for external APIs

If your system provides an HTTP API or similar to external clients, the safest route for major changes is to version the API. Introduce a v2 API endpoint for the refactored logic, keep v1 running (maybe internally calling v2 or using a translation layer). Clients can move to v2 at their own pace.

It’s extra work to maintain two APIs temporarily, but it prevents a breaking change from angering users or causing outages. Always communicate changes clearly and provide migration guides if applicable.

Have a clear deprecation policy

Make sure there’s a policy (and communication) around how long deprecated features will be supported. For internal APIs, maybe it’s one release cycle. For external ones, maybe multiple cycles or never removal without a major version bump. A good practice is to announce deprecation early.

If you’re exposing an HTTP API, consider introducing a new versioned endpoint (for example, /api/v2/send_email) and maintain the older /api/v1/send_email temporarily. Internally, v1 might call v2 with default parameters, ensuring behavior stays consistent for existing clients.

In summary, maintain backward compatibility whenever possible, and implement a clear deprecation policy for anything you do change​.

Write adapter or compatibility layers

In some cases, you can write an adapter to bridge old and new systems. For instance, suppose you refactor the underlying data model of your application, but you still have old configuration files in the old format. Rather than forcing all those files to be rewritten immediately, you could write a small adapter that translates the old format to the new one at runtime (or during startup). This way, old data continues to work.

Test for compatibility

Include tests that specifically ensure backward compatibility. For instance, if you have a public API, keep a suite of tests using the old API contracts and run them against the refactored code, they should still pass.

In summary, ensure that as you refactor, the external behavior and contracts remain consistent. This careful approach protects your users and downstream systems, allowing you to reap the internal benefits of refactoring without causing external chaos.

5. Handling dependencies and tight coupling

One of the hairiest aspects of refactoring a large codebase is dealing with deeply interdependent code. Complex systems often suffer from tight coupling. Module A assumes details about Module B and vice versa, global variables or singletons are used all over, or a change in one place ripples through half the codebase.

Reducing coupling is a significant aim of refactoring because it makes the code more modular, meaning each piece can be understood, tested, and changed independently. So, how do we gradually loosen the coupling in a legacy system?

Let’s go over some strategies to reduce coupling.

Introduce interfaces or abstraction layers

A very effective way to decouple is to put an interface between components. For example, if you have a class that directly queries a database, introduce an interface and have the class use that instead. The underlying database code implements the interface.

# before: direct instantiation
class OrderService:
    def __init__(self):
        self.repo = OrderRepository()

# after: inject dependency
class OrderService:
    def __init__(self, repo):
        self.repo = repo

# wiring up in application startup
repo = OrderRepository(db_conn)
service = OrderService(repo)

Now, that class no longer depends on how the data is fetched. Applying the dependency inversion principle depends on abstractions, not concretions.

Use dependency injection

Once you have interfaces, use dependency injection to supply concrete implementations. Many frameworks support DI containers, or you can do it manually (passing in dependencies via constructors). Dependency injection means code A doesn’t instantiate code B itself – instead, B is passed into A.

This approach also makes unit testing easier (you can inject mock dependencies).

Facades or wrapper services

If a particular subsystem is heavily entangled with others, consider creating a Facade, an object that provides a simplified interface to a larger body of code. Other parts of the system are then called the Facade, not the many internal methods of the subsystem. Internally, the subsystem can be refactored (even split into smaller pieces) as long as the Facade’s outward interface remains consistent.

This is similar to how microservices work (other services don’t care how one service is implemented internally – they just call its API), but you can do it in-process, too.

Gradual replacement (Parallel Run)

If a specific component is to be replaced with a new implementation, it can help to run them in parallel for a while. For instance, if you have a spaghetti module that you want to redo correctly, you could leave the spaghetti code in place for legacy calls but start routing new calls to the new module.

The result is a codebase where changes in one area (hopefully) won’t unpredictably break another, a key property of a maintainable system.

6. Testing Strategies (Safely Refactoring with Confidence)

A robust testing strategy will give you the confidence to make sweeping changes because you’ll know quickly if something important breaks. Here’s how to approach testing in the context of a large refactoring:

Establish a baseline with regression tests

Before you even begin refactoring a particular component, make sure you have tests that cover its current behavior. You're lucky if the codebase already has a good test suite, but many legacy systems have inadequate tests.

One of the first tasks in those cases is often writing characterization tests. A characterization test is a test that documents what the system currently does, not what we think it should do​.

As Feathers says, “a characterization test is a test that characterizes the actual behavior of a piece of code.” This allows you to take a snapshot of what it does and ensure that it doesn’t change​.

This gives you a safety net so you can refactor with confidence that you’re not introducing regressions​. Use automated test suites to help things run smoothly (unit, integration, end-to-end).

Continuous integration (CI)

It is highly recommended that testing be integrated into a CI pipeline that runs on every commit or merge. This way, you catch a bug during refactoring as soon as you introduce it, tightening the feedback loop.

Canary releases and feature flags

Beyond pre-release testing, consider strategies for safely deploying refactored code. A canary release involves rolling out the change to a small subset of users or servers first, observing it, and then gradually expanding​.

This is great for catching issues that tests might miss (for example, performance issues or edge cases in production data). If the canary looks good (no errors, metrics are healthy), you proceed to full rollout. If not, you rollback quickly—with only a small impact scope.

Performance and load testing

If performance is a concern, incorporate performance tests into your strategy. This can be done in a staging environment. You might reconsider your approach or optimize the new code if you see a significant regression.

Testing legacy code lacking tests

If you’re dealing with a part of the system with zero tests (not uncommon in older code), prioritize getting at least some coverage there. There are also techniques like approval testing (where you generate output and have a human approve it as correct, then use that as a baseline for future tests). The key is not to refactor entirely in the dark; give yourself at least a flashlight in the form of tests!

In sum, a strong testing strategy is non-negotiable for refactoring complex systems. It’s your safety net, early warning system, and guide to know that your “cleanup” hasn’t broken anything vital.

7. Refactoring Without Breaking Performance

A common concern when refactoring is whether these cleaner code changes will make my system slower or more resource-hungry. Ideally, refactoring is about the internal structure and shouldn’t change external behavior, and performance is part of the behavior.

In theory, performance should remain the same if you don’t change algorithms or data structures in a way that affects complexity.

In practice, though, performance can be inadvertently affected by refactoring. The new code may be more readable but uses more memory, or perhaps a critical caching mechanism was removed in the spirit of simplicity.

Senior engineers need to be mindful of performance-sensitive parts of the system when refactoring and take steps to avoid regressions (or even improve performance where possible).

Here’s how to refactor with performance in mind:

Identify performance-critical code paths

Not all codes are equal regarding performance impact. If you refactor them, treat it almost like a functional change: you must re-measure performance afterwards. You have more leeway for parts of the code that run rarely or are not bottlenecks.

Use profiling before and after

A profiler is a tool that measures where time is spent in your code or how memory is allocated. It’s beneficial to run a profiler on the code before refactoring a module to see how it behaves, and then run it after to compare. If you see, for example, that after refactoring, a function now shows up as taking 30% of execution time (when it was negligible before), that’s a red flag. Maybe the new code calls it more times than before.

import cProfile, pstats
from mymodule import slow_function

def profile(fn):
    profiler = cProfile.Profile()
    profiler.enable()
    fn()
    profiler.disable()
    stats = pstats.Stats(profiler).strip_dirs().sort_stats('cumtime')
    stats.print_stats(10)

# run before refactor
profile(lambda: slow_function())

# after you refactor slow_function(), re-run and compare stats

When possible, improve performance through refactoring

On the flip side, refactoring can help performance.

For example, by refactoring duplicated code into one place, you can use better caching in that one place. So, watch for performance improvement opportunities that arise naturally as you refactor.

Performance should be treated as part of the “external behavior” that needs to be preserved in a good mindset. Refactoring should ideally not make things slower for users. To ensure that, incorporate performance checks into your plan, especially for critical sections. Measure, don’t guess. The end goal is a codebase that is both clean and fast enough.

8. Automate Code Reviews with AI tools

Refactoring code is an ongoing process, not a one-time event – AI code review tools help enforce clean-code standards, catch smells early, and reduce the repetitive tasks that can bog down human reviewers. This frees your engineers to focus on deeper architectural or domain-specific issues.

One powerful option is CodeRabbit, an AI-driven review platform designed to cut review time and bugs in half.

Here’s how it works and why it can boost your refactoring workflow:

AI-powered contextual feedback

CodeRabbit analyzes pull requests line by line, applying both advanced language models and static analysis under the hood. It flags potential bugs, best-practice deviations, and style issues before a human opens the PR.

Some other features include:

• Auto-generated summaries and 1-click fixes – Summarize large PRs and apply straightforward fixes instantly.

• Real-time collaboration and AI chat – Chat with the AI for clarifications, alternate code snippets, and instant feedback.

• Integrates with popular dev platforms – Supports GitHub, GitLab, and Azure DevOps for seamless PR scanning.

CodeRabbit even has a free AI code reviews in VS Code and with this VS Code extension, you can get the most advanced AI code reviews directly in your code editor, saving review time, catching more bugs, and helping you in refactoring.

Summary

Refactoring a complex enterprise codebase is like renovating a large building while people still live in it without collapsing the structure.

Refactoring should be an ongoing process. You prevent the codebase from decaying by incorporating these practices into your regular development (perhaps allocating some time each sprint for refactoring or doing it opportunistically when touching your code). Each minor refactoring should not be too complex, and the cumulative effect is significant.

As Martin Fowler puts it, a series of small changes can lead to a significant improvement in design.

That's it for this blog. I hope you learned something new today.

If you want to read more interesting articles about developer tools, React, Next.js, AI and more, then I'll encourage you to checkout my blog.

Some of the new and interesting articles I've written in the last 24 months.

• Cursor vs Windsurf

• How to Implement Role-Based Access Control in Next.js

• AI Code Reviewers vs Human Code Reviewers

• How to Build a Custom Video Conferencing App with Stream and Next.js

• How to Perform Code Reviews in Tech – The Painless Way

You can get in touch if you have any questions or corrections. I’m expecting them.

And if you found this blog useful, please share it with your friends and colleagues who might benefit from it as well. Your support enables me to continue producing useful content for the tech community.

Now it’s time to take the next step by subscribing to my newsletter and following me on Twitter.

This guide provides a straightforward and flexible template for code reviews that you can apply to your engineering team. The only requirement is that your app code is open source.

You can test a TypeScript workflow, Java workflow, Python workflow, PHP, Ruby or even some wacky web stack you invented. And it doesn’t matter if you’re developing on Windows, Linux, or Mac. Best of all, you don’t have to perform convoluted configuration or install software beyond a yaml.

I’ve been in engineering for the last 15 years, and code reviews have a bad reputation. We’ve all witnessed or lived through horror stories where sometimes it feels like every previous line gets torn to shreds.

So, what can you do differently? How can you make reviewing your code painless so that even the biggest nitpick on your team has nothing but praise?

After participating in code reviews for a decade, taking code reviews less personally is the single biggest thing you can do to improve your code. Why? Because all software is iterative. Even “perfect” code will eventually become outdated. Instead of thinking of it like a graded assignment, think of it as a part of the process.

Table of Contents:

• Prerequisites

• What is a Code Review?

• What is the Purpose of a Code Review?

• Why is Doing Code Reviews Hard?

• Can AI Replace Code Reviews?

• What to Focus on During a Code Review

• Code Review Best Practices And Process

• What is CodeRabbit?

  • How Does CodeRabbit Help?

  • A GitHub Repo to Test

  • Additional Examples

• Conclusion

Prerequisites

This tutorial uses free, open-source tools. You’ll need to have a GitHub account to help you make your code reviews more pleasant and valuable.

What is a Code Review?

The term “code review” can refer to various activities, from simply reading code over your teammate’s shoulder to a 10-person meeting where you dissect code line by line. I use the term to refer to a formal and written process, but not so heavyweight as a series of in-person code inspection meetings.

In a project where you work on a repository with other developers, after you complete your work, you commit, push, and create a pull request on the VCS, most likely using Git commands. Then, everyone reviews the pull request to determine whether it’s okay to use. If so, they approve it, and that code gets used in the project.

What is the Purpose of a Code Review?

Code Reviews are a tool for knowledge transfer. They help make devs more efficient when doing maintenance on a part of the system they didn't write.

When you review a pull request, it’s an opportunity to iron out issues before they become technical debt.

Code reviews can also be a good setting for mentoring junior developers.

Now, let’s discuss what is not the purpose of a code review:

• Finding bugs. That's what tests (unit, integration, e2e, api, and so on…)are for.

Nitpicking on style issues – settle for one style and use formatters or AI tools to enforce it. Just keep in mind that there are many things that an AI tool cannot check. Code reviews are an excellent place to ensure the code is sufficiently documented or self-documenting.

Do you want to know how you can check this? Return to the code you wrote 6-12 months ago and try to understand what it was written to do.

If you understand it quickly, that means it's readable, and the code review was done properly and in a helpful manner.

Why is Doing Code Reviews Hard?

Despite their importance, many devs don’t like doing code reviews – in part because they can be challenging, especially if you’re not following best practices.

Here are some pain points I’ve observed during my years of participating in code reviews:

• When people talk about code reviews, they focus on the reviewer. But the developer who writes the code is just as crucial to the review as the person who reads it.

• Doing a code review is not an automatic routine for a developer.

• The reviewer may sometimes just do a partial review and add new comments at every pass, even on code in the previous review(s) that remained untouched.

• Sometimes, the code reviewer may not clearly express their expectations.

• Multiple code reviewers can often have diverging opinions, leading to (too) long discussions.

• The developer does not understand the comments from reviewers and requires back-and-forth discussions.

• The developer addresses code review comments differently than agreed upon during the review process.

These pain points often bottleneck our development velocity. But recent advances in AI-assisted code review tools have started addressing these common friction points in our PR workflows.

Let's explore how AI-powered tools, along with some best practices, can address these review challenges and optimize your development workflow.

Can AI Replace Code Reviews?

While AI hasn’t replaced human code reviews, it is a powerful force multiplier in the review process.

Here's how: AI code reviews excel as a preliminary screening tool, catching common issues before human reviewers see the code. This becomes especially valuable in open-source projects where maintainer bandwidth is limited.

I recently started using AI code reviews on a case-by-case basis for my projects.

AI tools improve my existing workflows, reduce failure rates by detecting logic errors early on, and boost productivity. So I’ve added it to my CI/CD pipelines. It doesn't have to be perfect at detecting logic errors, as long as its false positive rate is very low (ideally as close to 0 as possible).

Most importantly, AI reviews respect the golden rule of 'value your reviewer's time' by handling routine checks. This allows human reviewers to focus on architecture, business logic, and complex edge cases.

This approach positions AI as a complementary tool that augments rather than replaces human expertise in the code review process.

What to Focus on During a Code Review

When reviewing code, try to prioritise what matters most using the Code Review Pyramid. This is a framework that helps you focus your attention where it creates the most value.

Think of it like building a house — start with the foundation before worrying about paint colours.

The pyramid has five layers, from most critical (bottom) to least critical (top):

1. API Semantics: Core design decisions that affect users

2. Implementation Semantics: The code's functionality, security, and performance

3. Documentation: Clear explanation of how to use the code

4. Tests: Verification that everything works as intended

5. Code Style: Formatting and naming conventions

Source: The Code Review Pyramid by Gunnar Morling

Remember: if you want to catch issues/bugs, there are more appropriate processes for that. That is why we have automated testing, canary releases, testing environments, and so on.

In my personal opinion, using code reviews as a bug catching tool is somewhat of an anti-pattern where you're compensating for a development process that may be lacking some key steps/processes.

To me, a code review is much more about managing technical debt and ensuring that quality is produced, while shipping more features.

In doing a code review, you should make sure that:

• The code is readable

• It has appropriate unit tests

• The developer used clear names for everything

• The code is well-designed and isn’t more complex than it needs to be

• Test cases make sense and have comprehensive coverage

• It’s something the team can maintain in the long run

• There are no architectural issues that will block the team

• The code fits the team's idea of quality

• You’re thinking about what you can learn from the PR

• You’re sharing any knowledge the developer might use in their PR

• You’re thinking about how you can empower the dev through your positive feedback

• The PR has a clear changelist description

Code Review Best Practices And Process

There is no general rule in engineering for code reviews, as what you’ll need to focus on depends on many factors. You can and should set up the process according to your company standards and way of working as a team.

Here are some factors you’ll need to think about before setting up a code review process:

• The size and type of company you’re in (for example a startup vs a large corporation)

• The number of developers on your team

• Your budget

• The timeframe you’re working with

• Your and your team’s workloads

• The complexity of the code

• The abilities and skills of the reviewer(s)

• The availability of the reviewer(s)

As an example, at my work we have a very simple rule: all code changes must be reviewed by at least one developer before a merge or a commit to the trunk.

Code reviews need a systematic approach, but maintaining consistency across every PR is challenging. It’s useful to let computers handle repetitive checks (style, formatting) while humans focus on what matters most: architecture and logic. This balanced approach makes reviews both thorough and sustainable.

Take a look at this example. It shows how we can optimize our code review process by intelligently delegating tasks between humans and automated tools. The diagram below illustrates a typical code style review workflow, comparing manual human review steps against automated tooling.

The diagram shows a real problem we all face in code reviews. See the left side? That's we humans doing manual formatting checks: finding weird spaces, fixing indents, writing comments about it... pretty tedious stuff. But check out the right side: that's where tools like Prettier just fix these formatting issues automatically.

No meetings, no back-and-forth – just done. That's why I started using CodeRabbit, which is a dev tool that caught my attention recently.

What is CodeRabbit?

The CodeRabbit docs describe the tool pretty effectively, so I’ll just leave this here:

CodeRabbit is an AI-powered code reviewer that delivers context-aware feedback on pull requests within minutes, reducing the time and effort needed for manual code reviews. It provides a fresh perspective and catches issues that are often missed, enhancing the overall review quality. – from the CodeRabbit docs

How Does CodeRabbit Help?

Let me walk you through a real example. When you submit a PR, CodeRabbit:

1. Performs a PR summary on the fly:

• First, it gives you a quick overview of what changed.

• It also explains the impact in plain English (great for non-tech folks in your team).

• Then it includes a detailed walkthrough of file changes.

2. Does a “Smart Code Review”:

• It drops comments right on the specific lines that need attention.

• It also suggests fixes in diff format that you can apply them with one click.

• And it shows what commits and files it checked (which is helpful for tracking review coverage).

3. Give you interactive feedback:

• You can chat with it right in the PR comments.

• You can ask it questions about specific code changes to get more details.

• And it remembers your team's patterns and preferences which is super helpful for consistency’s sake (which I discussed above).

4. Extra Helpful Features:

• CodeRabbit validates changes against linked GitHub/GitLab issues.

• It creates sequence diagrams to visualize changes.

• And it can perform one-click fixes on applications for simple issues.

I first discovered CodeRabbit last month while I was searching for something else on GitHub. I accidentally came across it and I was surprised by how many people are already using it.

I instantly signed up because I was looking for exactly such a solution which could help me and my team out with our reviews.

I read through the CodeRabbit docs and was very impressed.

Getting started using it is pretty much a plug and play process.

In the next section, we’ll go through the quick steps you can follow to enable CodeRabbit using an example repo.

• Sign up at coderabbit.ai using your GitHub account.

• Go to Add Your Repository.

• And that's it. CodeRabbit starts reviewing your PRs automatically.

A GitHub Repo to Test

As an example GitHub repo to test, we’ll use devtoolsacademy: my blog on everything about awesome developer tools.

First, visit the CodeRabbit login page and login via GitHub.

Next, add CodeRabbit to some of your public GitHub repositories.

Now, CodeRabbit is fully integrated and ready to do code reviews on your selected repo.

Yes: it’s that simple and fast. And in my opinion, it’s one of the main reasons the tool is so useful.

Here are some sample PRs for you to check out:

• https://github.com/tyaga001/devtoolsacademy/pull/10

• https://github.com/tyaga001/devtoolsacademy/pull/13

• sartography/spiff-arena#1233 (comment)

• kmesiab/equilibria#1 (comment)

• kamiazya/web-csv-toolbox#60 (comment)

• openreplay/openreplay#1858 (comment)

• ls1intum/Artemis#8037 (comment)

Additional Examples

Conclusion

Everyone’s code needs reviewing. Just because someone is the most senior person on the team does not mean that their code doesn’t need to be reviewed.

In this article, I talked about code reviews along with some common pain points. I then showed you how you can leverage CodeRabbit to iterate quickly through your code reviews and focus more on business.

Further reading

In this article I talked about basic intro to CodeRabbit, because that was my use case with my blog.

For more advanced functionality, check out the official CodeRabbit docs or read their blog.

Before I End

I hope you found it helpful learning how to use AI tools for code reviews.

If you like my writing, these are some of my other most recent articles.

• Neon Postgres vs Supabase

• MongoDB vs. PostgreSQL

• Supabase vs Clerk

• How I Built a Video Conferencing App with Stream and Next.js

• How to Implement Fine-Grained Authorization in Java

Follow me on Twitter to stay updated on my open source projects.

FGA allows you to set up detailed access controls that specify who can do what and under which conditions.

In this tutorial, you will learn how to implement fine-grained authorization in Java and Spring Boot using Permit.io.

Here is the source code (remember to give it a star ⭐).

I hope you enjoyed my previous blog about building a custom video conferencing app with Stream and Next.js. These blogs reflect my journey in creating DevTools Academy, a platform designed to help developers discover amazing developer tools.

This tutorial is another effort to introduce you to a super helpful developer tool that I recently explored.

Table of Contents:

• What is Permit?

• Prerequisites

• What is Fine-Grained Authorization?

  • Role-Based Access Control (RBAC)

  • Attribute-Based Access Control (ABAC)

  • Relationship-Based Access Control (ReBAC)

• How to Implement Fine-Grained Authorization

  • Implementing Role-Based Access Control

  • Implementing Attribute-Based Access Control

  • Implementing Relationship-Based Access Control

• How to Implement FGA in Java and SpringBoot

  • Step 1: Setting Up the E-commerce Application

  • Step 2: Get your Environment API Key

  • Step 3: Deploy Policy Decision Point (PDP)

  • Step 4: Running the App

• Next Steps

  • Before We End...

What is Permit?

Permit.io is a full stack, plug-and-play application-level authorization solution that allows you to implement a secure, flexible, authorization layer within minutes, so you can focus on what matters most.

Prerequisites

To fully understand the tutorial, you need to have a basic understanding of Java and Spring Boot. You’ll also need the following:

• Permit.io: A developer tool that simplifies the implementation of FGA.

• Spring Boot Starter Web: Provides essential components for building web applications, including RESTful APIs.

• Gradle: A build tool for managing dependencies.

• JDK 11 or later: The Java Development Kit version required to compile and run your Spring Boot app.

• Postman or cURL: Tools for testing your API endpoints.

What is Fine-Grained Authorization?

Fine-grained authorization offers access control to resources by determining who can access them, to what extent, and under specified conditions.

Contrary to coarse-grained authorization (that handles access based on categories like user roles such as "admin" or "user"), fine-grained authorization gives you the flexibility to define access at a granular level, for specific resources or actions and even attributes.

In Fine Grained Authorization there exist 3 types of policy models for managing authorization; Role Based Access Control (RBAC), Attribute Based Access Control (ABAC), and Relationship-Based Access Control (ReBAC).

Let's take a look, at each of these approaches and see how you can implement them in your application.

Role-Based Access Control (RBAC)

RBAC is a security approach that controls resource access based on the roles of users within an organization. This model streamlines permissions by organizing users into roles and managing access control according to these defined roles.

Key Concepts in RBAC:

Users: People who use the system such as employees or customers.

Roles: A set of permissions or access privileges assigned to a group of users based on their responsibilities or tasks such as admin, manager, or customer.

Permissions: The rights granted to users for interacting with resources, such as read, write, or delete.

Attribute-Based Access Control (ABAC)

ABAC is a versatile and adaptive access control model that decides who can or cannot access resources based on attributes, like user details. The ABAC model allows you to define fine-grained authorization based on user attributes.

Key Concepts in ABAC:

Attributes: Characteristics or properties used to make access control decisions. Attributes are typically categorized into:

• User Attributes: Information about the user (for example, role, department, job title, age, and so on).

• Resource Attributes: Characteristics of the resource (for example, file type, data classification level, creation date, owner).

• Action Attributes: The action the user is trying to perform (for example, read, write, delete, approve).

• Environmental Attributes: Contextual information about the access request (for example, time of day, location, device type, IP address).

Relationship-Based Access Control (ReBAC)

ReBAC is an access control system that grants permissions to access resources based on the relationship between entities within a system. The approach emphasizes defining and managing access control by mapping out how users relate to resources and other entities such as organizations or groups.

Key Concepts of ReBAC:

Entities: Users, resources (such as files and documents), and other entities, such as groups or organizational units.

Relationships: The connections that specify the relationship between two entities. A user might be the "owner" of a document or a "member" of a team, for instance.

Policies: Rules that use relationships to determine access rights. A user can access a resource or execute an action on it if they have a particular relationship with it.

How to Implement Fine-Grained Authorization

Now that you have a basic understanding of RBAC, ABAC, and ReBAC, let’s see how we can implement these models in an e-commerce app.

Implementing Role-Based Access Control

Step 1: Navigate to Permit.io, and then create an account and your workspace.

By default, you should see a project that includes two environments: Development and Production.

Step 2: Create a resource named Products. To create the resource, open the Policy tab on the left sidebar and then open the Resources tab at the top. After that, click the Create a Resource button and then create a resource called Products with actions read, create, update, and delete.

Step 3: Create another resource called Reviews with actions read, create, update, and delete.

Step 4: Open the Policy Editor tab. You’ll see that 3 roles named admin, editor, and viewer were created.

• Role admin has permission to create, delete, read, or update a product or a review.

• Role editor has permission to create, read, or update a product or a review but not delete any.

• Role viewer has permission to create and read a product or a review but not delete or update any.

Implementing Attribute-Based Access Control

Step 1: Open the Resources tab, then click the Add Attributes button.

• Add an attribute called vendor

• Add an attribute called the customer

Step 2: Open the ABAC Rules tab, then create a new ABAC Resource Set called Own Products that depends on the Products resource. After that, add a condition that gives permissions only to the user who created a product based on the vendor attribute.

Step 3: Create another ABAC Resource Set called Own Reviews that depends on the Reviews resource.

Implementing Relationship-Based Access Control

Step 1: Open the Resources tab and edit the Products resource. Add role vendor in the ReBAC options section. Then set products as parent of reviews in the relations section.

Step 2: Edit the Reviews resource by adding role customer in the ReBAC options section, as shown below:

Step 3: Go to Policy Editor tab and add:

• role vendor permission to update and delete own products.

• role customer permission to update and delete their own reviews on products.

How to Implement FGA in Java and SpringBoot

Now that we have defined RBAC, ABAC, and ReBAC policies in the Permit.io web interface, let’s learn how to enforce them in an E-Commerce Management System application using the Permit.io API.

There’s a lot of code coming up, so make sure you read through the extensive comments I’ve left throughout each code block. These will help you understand more fully what’s going on in this code.

Step 1: Setting Up the E-commerce Application

To set up the e-commerce application and git clone the source code.

git clone https://github.com/tyaga001/java-spring-fine-grained-auth.git

Installing Permit package SDK

To install the Permit package SDK, you add the SDK under the dependencies block in the build.graddle file.

## Dependencies

To set up the necessary dependencies for your Spring Boot project, include the following in your `build.gradle` file:

```groovy
dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0'
    developmentOnly 'org.springframework.boot:spring-boot-devtools'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'

    // Add this line to install the Permit.io Java SDK in your project
    implementation 'io.permit:permit-sdk-java:2.0.0'
}

Initializing the Permit SDK

You can initialize the Permit SDK Client using the code below:

package com.boostmytool.store.config;

import io.permit.sdk.Permit;
import io.permit.sdk.PermitConfig;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration  // Marks this class as a configuration class for Spring IoC
public class PermitClientConfig {

    @Value("${permit.api-key}")  // Inject Permit API key from application properties
    private String apiKey;

    @Value("${permit.pdp-url}")  // Inject Permit PDP (Policy Decision Point) URL from application properties
    private String pdpUrl;

    /**
     * Creates a Permit client bean with custom configuration
     * @return Permit client instance
     */
    @Bean
    public Permit permit() {
        return new Permit(
                new PermitConfig.Builder(apiKey)  // Initialize PermitConfig with API key
                        .withPdpAddress(pdpUrl)   // Set the PDP address
                        .withDebugMode(true)      // Enable debug mode for detailed logging
                        .build()                  // Build the PermitConfig object
        );
    }
}

Syncing Users with SDK

To start enforcing permissions, you should first sync a user to Permit, and then assign them a role.

In the code below, the UserService class provides methods for user login, signup, role assignment, and authorization, with exception handling for possible errors when interacting with the Permit API.

package com.boostmytool.store.service;

import com.boostmytool.store.exception.ForbiddenAccessException;
import com.boostmytool.store.exception.UnauthorizedException;
import io.permit.sdk.Permit;
import io.permit.sdk.api.PermitApiError;
import io.permit.sdk.api.PermitContextError;
import io.permit.sdk.enforcement.Resource;
import io.permit.sdk.enforcement.User;
import org.springframework.stereotype.Service;

import java.io.IOException;

@Service  // Marks this class as a Spring service, making it a candidate for component scanning
public class UserService {
    private final Permit permit;

    // Constructor injection for the Permit SDK
    public UserService(Permit permit) {
        this.permit = permit;
    }

    /**
     * Simulates user login by creating and returning a Permit User object.
     * 
     * @param key User's unique key
     * @return User object
     */
    public Object login(String key) {
        return new User.Builder(key).build();
    }

    /**
     * Handles user signup by creating and syncing a new Permit User.
     * 
     * @param key User's unique key
     * @return Created and synced User object
     */
    public User signup(String key) {
        var user = new User.Builder(key).build();
        try {
            permit.api.users.sync(user);  // Syncs the new user with the Permit service
        } catch (PermitContextError | PermitApiError | IOException e) {
            throw new RuntimeException("Failed to create user", e);  // Handles exceptions during user creation
        }
        return user;
    }

    /**
     * Assigns a role to the user within the "default" environment.
     * 
     * @param user User object to assign the role to
     * @param role Role to be assigned
     */
    public void assignRole(User user, String role) {
        try {
            permit.api.users.assignRole(user.getKey(), role, "default");  // Assigns role in the "default" environment
        } catch (PermitApiError | PermitContextError | IOException e) {
            throw new RuntimeException("Failed to assign role to user", e);  // Handles exceptions during role assignment
        }
    }

    /**
     * Checks if the user is authorized to perform a specific action on a resource.
     * 
     * @param user User object requesting authorization
     * @param action Action to be authorized
     * @param resource Resource on which the action will be performed
     * @throws UnauthorizedException if user is not logged in
     * @throws ForbiddenAccessException if user is denied access
     */
    public void authorize(User user, String action, Resource resource) {
        if (user == null) {
            throw new UnauthorizedException("Not logged in");  // Throws exception if user is not logged in
        }
        try {
            var permitted = permit.check(user, action, resource);  // Performs authorization check
            if (!permitted) {
                throw new ForbiddenAccessException("Access denied");  // Throws exception if access is denied
            }
        } catch (PermitApiError | IOException e) {
            throw new RuntimeException("Failed to authorize user", e);  // Handles exceptions during authorization
        }
    }
}

Then in the code below, the UserController class exposes REST API endpoints for user signup and role assignment. It interacts with the UserService class to handle user-related business logic and provides appropriate HTTP responses.

package com.boostmytool.store.controllers;

import com.boostmytool.store.exception.UnauthorizedException;
import com.boostmytool.store.service.UserService;
import io.permit.sdk.enforcement.User;
import jakarta.servlet.http.HttpServletRequest;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController  // Indicates that this class handles HTTP requests and returns JSON responses
@RequestMapping("/api/users")  // Base URL path for all user-related operations
public class UserController {
    private final UserService userService;

    // Constructor injection of UserService, containing business logic for user operations
    public UserController(UserService userService) {
        this.userService = userService;
    }

    /**
     * Handles user signup requests.
     * Endpoint: POST /api/users/signup
     * 
     * @param key Unique key for the new user
     * @return Created User object
     */
    @PostMapping("/signup")
    public User signup(@RequestBody String key) {
        return userService.signup(key);  // Calls the signup method in UserService to create a new user
    }

    /**
     * Handles assigning a role to the logged-in user.
     * Endpoint: POST /api/users/assign-role
     * 
     * @param request HTTP request, used to retrieve the current user
     * @param role Role to be assigned to the current user
     */
    @PostMapping("/assign-role")
    public void assignRole(HttpServletRequest request, @RequestBody String role) {
        // Retrieves the current user from the request attributes
        User currentUser = (User) request.getAttribute("user");

        // Throws an exception if the user is not logged in
        if (currentUser == null) {
            throw new UnauthorizedException("Not logged in");
        }

        // Assigns the specified role to the current user
        userService.assignRole(currentUser, role);
    }
}

Creating RBAC, ABAC, and ReBAC Policy Enforcement Point

In the code below, the ProductService class manages CRUD operations for products and reviews, handling permissions and roles via the Permit API.

Each operation includes user authorization checks, with appropriate exception handling for Permit API errors and resource not found scenarios.

package com.boostmytool.store.service;

import com.boostmytool.store.exception.ResourceNotFoundException;
import com.boostmytool.store.model.Product;
import com.boostmytool.store.model.Review;
import io.permit.sdk.Permit;
import io.permit.sdk.api.PermitApiError;
import io.permit.sdk.api.PermitContextError;
import io.permit.sdk.enforcement.Resource;
import io.permit.sdk.enforcement.User;
import io.permit.sdk.openapi.models.RelationshipTupleCreate;
import io.permit.sdk.openapi.models.ResourceInstanceCreate;
import io.permit.sdk.openapi.models.RoleAssignmentCreate;
import org.springframework.stereotype.Service;

import java.io.IOException;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.concurrent.atomic.AtomicInteger;

@Service  // Marks this class as a Spring service
public class ProductService {

    private final List<Product> products = new ArrayList<>();  // In-memory list to store products
    private final AtomicInteger productIdCounter = new AtomicInteger();  // Counter to generate unique product IDs
    private final AtomicInteger reviewIdCounter = new AtomicInteger();   // Counter to generate unique review IDs

    // Builders for Permit resource instances (product and review)
    private final Resource.Builder productResourceBuilder = new Resource.Builder("product");
    private final Resource.Builder reviewResourceBuilder = new Resource.Builder("review");

    private final UserService userService;  // Service for handling user-related operations
    private final Permit permit;  // Permit SDK instance for handling authorization and resource management

    // Constructor for injecting dependencies
    public ProductService(UserService userService, Permit permit) {
        this.userService = userService;
        this.permit = permit;
    }

    // Method to authorize a user for a given action on a resource
    private void authorize(User user, String action, Resource resource) {
        userService.authorize(user, action, resource);
    }

    // Authorizes a user to perform an action on a specific product
    private void authorize(User user, String action, Product product) {
        var attributes = new HashMap<String, Object>();
        attributes.put("vendor", product.getVendor());  // Add vendor attribute to the product
        userService.authorize(user, action, productResourceBuilder.withKey(product.getId().toString()).withAttributes(attributes).build());
    }

    // Authorizes a user to perform an action on a specific review
    private void authorize(User user, String action, Review review) {
        var attributes = new HashMap<String, Object>();
        attributes.put("customer", review.getCustomer());  // Add customer attribute to the review
        userService.authorize(user, action, reviewResourceBuilder.withKey(review.getId().toString()).withAttributes(attributes).build());
    }

    // Retrieves a product by its ID, throws an exception if not found
    private Product getProductById(int id) {
        return products.stream().filter(product -> product.getId().equals(id))
                .findFirst().orElseThrow(() -> new ResourceNotFoundException("Product with id " + id + " not found"));
    }

    // Retrieves all products, checks if the user is authorized to "read" products
    public List<Product> getAllProducts(User user) {
        authorize(user, "read", productResourceBuilder.build());  // User must have "read" permission
        return new ArrayList<>(products);  // Return a copy of the products list
    }

    // Retrieves a product by its ID, checks if the user is authorized to "read" the product
    public Product getProduct(User user, int id) {
        authorize(user, "read", productResourceBuilder.build());
        return getProductById(id);
    }

    // Adds a new product, authorizes the user and creates resource instances and role assignments in Permit
    public Product addProduct(User user, String content) {
        authorize(user, "create", productResourceBuilder.build());  // Check if user can create a product
        Product product = new Product(productIdCounter.incrementAndGet(), user.getKey(), content);  // Create new product

        try {
            // Create resource instance in Permit and assign "vendor" role to the user for this product
            permit.api.resourceInstances.create(new ResourceInstanceCreate(product.getId().toString(), "product").withTenant("default"));
            permit.api.roleAssignments.assign(new RoleAssignmentCreate("vendor", user.getKey()).withResourceInstance("product:" + product.getId()).withTenant("default"));
        } catch (IOException | PermitApiError | PermitContextError e) {
            throw new RuntimeException("Failed to create resource instance or role assignment: " + e.getMessage());
        }

        products.add(product);  // Add product to in-memory list
        return product;
    }

    // Updates a product's content, checks if the user is authorized to "update" the product
    public Product updateProduct(User user, int id, String content) {
        Product product = getProductById(id);  // Get the product by its ID
        authorize(user, "update", product);  // Check if user can update the product
        product.setContent(content);  // Update product content
        return product;
    }

    // Deletes a product, checks if the user is authorized to "delete" the product
    public void deleteProduct(User user, int id) {
        boolean isDeleted = products.removeIf(product -> {
            if (product.getId().equals(id)) {
                authorize(user, "delete", product);  // Check if user can delete the product
                return true;
            } else {
                return false;
            }
        });

        if (!isDeleted) {
            throw new ResourceNotFoundException("Product with id " + id + " not found");
        }

        try {
            permit.api.resourceInstances.delete("product:" + id);  // Remove product resource instance from Permit
        } catch (IOException | PermitApiError | PermitContextError e) {
            throw new RuntimeException(e);
        }
    }

    // Adds a review to a product, creates a resource instance and relationship in Permit
    public Review addReview(User user, int productId, String content) {
        authorize(user, "create", reviewResourceBuilder.build());  // Check if user can create a review
        Product product = getProductById(productId);  // Get the product by its ID
        Review review = new Review(reviewIdCounter.incrementAndGet(), user.getKey(), content);  // Create new review

        try {
            // Create a resource instance for the review and set relationship with the product
            permit.api.resourceInstances.create(new ResourceInstanceCreate(review.getId().toString(), "review").withTenant("default"));
            permit.api.relationshipTuples.create(new RelationshipTupleCreate("product:" + productId, "parent", "review:" + review.getId()));
        } catch (IOException | PermitApiError | PermitContextError e) {
            throw new RuntimeException(e);
        }

        product.addReview(review);  // Add the review to the product
        return review;
    }

    // Updates a review's content, checks if the user is authorized to "update" the review
    public Review updateReview(User user, int productId, int reviewId, String content) {
        Product product = getProductById(productId);  // Get the product by its ID
        Review review = product.getReviews().stream().filter(c -> c.getId().equals(reviewId))
                .findFirst().orElseThrow(() -> new ResourceNotFoundException("Review with id " + reviewId + " not found"));

        authorize(user, "update", review);  // Check if user can update the review
        review.setContent(content);  // Update review content
        return review;
    }

    // Deletes a review, checks if the user is authorized to "delete" the review
    public void deleteReview(User user, int productId, int reviewId) {
        Product product = getProductById(productId);  // Get the product by its ID
        boolean isDeleted = product.getReviews().removeIf(review -> {
            if (review.getId().equals(reviewId)) {
                authorize(user, "delete", review);  // Check if user can delete the review
                return true;
            } else {
                return false;
            }
        });

        if (!isDeleted) {
            throw new ResourceNotFoundException("Review with id " + reviewId + " not found");
        }

        try {
            permit.api.resourceInstances.delete("review:" + reviewId);  // Remove review resource instance from Permit
        } catch (IOException | PermitApiError | PermitContextError e) {
            throw new RuntimeException(e);
        }
    }
}

Then in the code below, the ProductController class handles HTTP requests related to products and their reviews. It exposes endpoints for managing products (like creating, updating, deleting, and retrieving) and for managing product reviews.

package com.boostmytool.store.controllers;

import com.boostmytool.store.model.Product;
import com.boostmytool.store.model.Review;
import com.boostmytool.store.service.ProductService;
import io.permit.sdk.enforcement.User;
import jakarta.servlet.http.HttpServletRequest;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController  // Indicates that this class is a Spring REST controller
@RequestMapping("/api/products")  // Base URL for all endpoints in this controller
public class ProductController {

    private final ProductService productService;  // ProductService instance to handle product-related operations

    @Autowired  // Autowires ProductService bean automatically
    public ProductController(ProductService productService) {
        this.productService = productService;
    }

    // GET request to retrieve all products
    @GetMapping
    public List<Product> getAllProducts(HttpServletRequest request) {
        User currentUser = (User) request.getAttribute("user");  // Gets the authenticated user from the request
        return productService.getAllProducts(currentUser);  // Calls ProductService to get all products for the user
    }

    // GET request to retrieve a product by its ID
    @GetMapping("/{id}")
    public Product getProductById(HttpServletRequest request, @PathVariable("id") int id) {
        User currentUser = (User) request.getAttribute("user");  // Gets the authenticated user from the request
        return productService.getProduct(currentUser, id);  // Calls ProductService to get the product by ID for the user
    }

    // POST request to add a new product
    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)  // Sets the response status to 201 (Created)
    public Product addProduct(HttpServletRequest request, @RequestBody String content) {
        User currentUser = (User) request.getAttribute("user");  // Gets the authenticated user from the request
        return productService.addProduct(currentUser, content);  // Calls ProductService to add a new product
    }

    // PUT request to update an existing product by its ID
    @PutMapping("/{id}")
    public Product updateProduct(HttpServletRequest request, @PathVariable("id") int id, @RequestBody String content) {
        User currentUser = (User) request.getAttribute("user");  // Gets the authenticated user from the request
        return productService.updateProduct(currentUser, id, content);  // Calls ProductService to update the product by ID
    }

    // DELETE request to delete a product by its ID
    @DeleteMapping("/{id}")
    public String deleteProduct(HttpServletRequest request, @PathVariable("id") int id) {
        User currentUser = (User) request.getAttribute("user");  // Gets the authenticated user from the request
        productService.deleteProduct(currentUser, id);  // Calls ProductService to delete the product by ID
        return "Deleted product with id " + id;  // Returns a success message after deletion
    }

    // POST request to add a new review to a product by product ID
    @PostMapping("/{id}/review")
    public Review addReview(HttpServletRequest request, @PathVariable("id") int id, @RequestBody String content) {
        User currentUser = (User) request.getAttribute("user");  // Gets the authenticated user from the request
        return productService.addReview(currentUser, id, content);  // Calls ProductService to add a review to the product
    }

    // PUT request to update an existing review by product and review ID
    @PutMapping("/{id}/review/{reviewId}")
    public Review updateReview(HttpServletRequest request, @PathVariable("id") int id, @PathVariable("reviewId") int reviewId, @RequestBody String content) {
        User currentUser = (User) request.getAttribute("user");  // Gets the authenticated user from the request
        return productService.updateReview(currentUser, id, reviewId, content);  // Calls ProductService to update the review
    }

    // DELETE request to delete a review by product and review ID
    @DeleteMapping("/{id}/review/{reviewId}")
    public String deleteReview(HttpServletRequest request, @PathVariable("id") int id, @PathVariable("reviewId") int reviewId) {
        User currentUser = (User) request.getAttribute("user");  // Gets the authenticated user from the request
        productService.deleteReview(currentUser, id, reviewId);  // Calls ProductService to delete the review
        return "Deleted review with id " + reviewId + " from product " + id;  // Returns a success message after deletion
    }
}

Step 2: Get your Environment API Key

In the UI Dashboard, copy the Environment API Key of the active environment.

Then add the env API key and PDP URL in the application.yaml file.

permit:
  pdpUrl: 'http://localhost:7766'
  apiKey: "Your Permit environment API Key"

Step 3: Deploy Policy Decision Point (PDP)

The Policy Decision Point (PDP) is deployed in your VPC and is in charge of evaluating your authorization requests. The PDP will ensure zero latency, great performance, high availability, and improved security.

Use the command below to pull the Permit.io PDP container from Docker Hub.

docker pull permitio/pdp-v2:latest

Then run the container.

docker run -it -p 7766:7000 --env PDP_DEBUG=True --env PDP_API_KEY=<YOUR_API_KEY> permitio/pdp-v2:latest

Step 4: Running the App

You can run the application using the following Gradle command:

./gradlew bootRun

Viewing and Creating Products

Let’s now interact with the application endpoints using REQBIN.

First, create a new user using the /api/users/signup endpoint.

curl -X POST "http://localhost:8080/api/users/signup" -H "Content-Type: application/json" -d 'johndoe'

You should be able to view the user in your Permit project, under Directory > All Tenants.

Initially, the user has no roles, so it cannot do much. For example, trying to list the products will result in a 403 Forbidden response, as shown below. The 403 error code means the user doesn’t have permissions to access the requested resource, which is products in this case. You can learn more about the difference between 401 and 403 error codes here.

For the user to view a list of products, assign them a viewer role using the command below:

curl -X POST "http://localhost:8080/api/users/assign-role" \
-H "Authorization: Bearer johndoe" \
-H "Content-Type: application/json" \
-d 'viewer'

You should see that user johndoe was assigned role viewer, as shown below:

Since a viewer can create a product, use the command below to create a product with user johndoe.

curl -X POST "http://localhost:8080/api/products" -H "Authorization: Bearer johndoe" -H "Content-Type: application/json" -d 'MacBook'

You should see that a new product is created with ID 1 and that the user johndoe has been added as the vendor.

Adding Reviews To Products

To add reviews to products, create another user called jane.

curl -X POST "http://localhost:8080/api/users/signup" -H "Content-Type: application/json" -d 'jane'

For the user to add a review to products, assign them a viewer role using the command below:

curl -X POST "http://localhost:8080/api/users/assign-role" \
-H "Authorization: Bearer jane" \
-H "Content-Type: application/json" \
-d 'viewer'

Then you can add a review to the product added by johndoe using the command below:

curl -X POST "http://localhost:8080/api/products/1/review" -H "Authorization: Bearer jane" -H "Content-Type: application/json" -d 'The product was in good quality'

Congratulations! You’ve completed the project for this tutorial.

Next Steps

Now that you've learned how to implement fine-grained authorization in your Java and Spring Boot applications using Permit.io, you might want to explore further.

Here are some valuable resources:

• Permit.io docs

• RBAC VS ABAC: Choosing the Right Authorization Policy Model

Before We End

I hope you found this tutorial insightful.

Here are some of my other recent blog posts that you might enjoy:

• Learn React – A Guide to the Key Concepts

• Neon Postgres vs Supabase

• Full Stack Development with Next.js, Clerk, and Neon Postgres

For more tutorials on amazing developer tools, be sure to check out my blog DTA.

Follow me on Twitter to get live updates on my other projects.

Happy coding.

And building a project like a video conferencing app from scratch can feel even more overwhelming, especially with the complexities of managing video streams, user auth, and real-time interactions.

But what if I told you there’s an easier way to do this – one that lets you build your video conferencing app in a fraction of the time?

In this article, I’ll show you how I built a video conferencing app using Stream and Clerk in Next.js.

Here is the source code (remember to give it a star ⭐).

Before we start, let me tell you why I wrote this tutorial.

I’m a Software Engineer who cares about writing and I love to code, design, develop, and then teach people.

I've been using open-source projects, products, and services for a while now, and contributing to many of them to improve them how I can. Last month I built an open-source blog for “awesome developer tools“ called - devtoolsacademy

This article is about sharing the experience I’ve had using yet another awesome developer tool.

Table of Contents:

• What is Stream?

• Prerequisites

• How to Build the App Interface with Next.js

  • The Create Link Modal

  • The Instant Meeting Modal

  • The Join Meeting Modal

• How to Authenticate Users with Clerk

• How to Set Up Stream in a Next.js app

• How to Create and Join Calls with Stream

  • Creating and Scheduling calls

  • Joining calls and the Meeting Page

  • Retrieving Upcoming Calls

• Next Steps

What is Stream?

Stream is an open-source cloud-based platform that provides APIs and SDKs for building scalable and feature-rich real-time applications. It offers pre-built UI components for creating enterprise-grade software apps with features like chat, video, audio, and activity feeds.

Here's how I'll use Stream while building the app:

• Set up real-time video and audio calls

• Use Stream's UI components to quickly build the interface

• Implement key features like video and audio calls

• Call Types – I'll implement instant meetings and pre-scheduled calls using Stream

• Leverage Stream's call and participant objects to manage call state

Prerequisites

To fully understand the tutorial, you need to have a basic understanding of React and Next.js. You’ll also need the following:

• Stream React SDK - provides pre-built UI components for adding video call features quickly.

• Stream Node.js SDK - for managing server-side interactions and keeping Stream's state in sync.

• Clerk - a comprehensive user management platform to handle authentication effortlessly.

• Headless UI - provides accessible UI components for building user-friendly applications.

• React Copy-to-Clipboard - allows users to easily copy meeting links within the app.

• React Icons - offers a library of easily integrated icons.

How to Build the App Interface with Next.js

In this section, I'll guide you through creating the user interface for the video-conferencing app. The interface will allow users to easily create, join, and schedule meetings, as well as view their upcoming meetings.

First, let’s create a Next.js TypeScript project by running the code snippet below:

npx create-next-app facetime-app

Then install the following packages:

• React icons - a popular React icons package

• Headless UI - provides a set of accessible UI components

• React-copy-to-clipboard - a lightweight package that enables us to copy meeting links.

npm install react-icons @headlessui/react react-copy-to-clipboard

Copy the code snippet below into the app/page.tsx file:

"use client";
import { useState } from "react";
import { FaLink, FaVideo } from "react-icons/fa";
import InstantMeeting from "@/app/modals/InstantMeeting";
import UpcomingMeeting from "@/app/modals/UpcomingMeeting";
import CreateLink from "@/app/modals/CreateLink";
import JoinMeeting from "@/app/modals/JoinMeeting";

export default function Dashboard() {
    const [startInstantMeeting, setStartInstantMeeting] =
        useState<boolean>(false);
    const [joinMeeting, setJoinMeeting] = useState<boolean>(false);
    const [showUpcomingMeetings, setShowUpcomingMeetings] =
        useState<boolean>(false);
    const [showCreateLink, setShowCreateLink] = useState<boolean>(false);

    return (
        <>
            <button
                className=' top-5 right-5 text-sm fixed bg-green-500 px-2 w-[150px] hover:bg-green-600 py-3 flex flex-col items-center text-white rounded-md shadow-sm cursor-pointer z-10'
                onClick={() => setJoinMeeting(true)}
            >
                <FaVideo className='mb-[3px] text-white' />
                Join FaceTime
            </button>

            <main className='w-full h-screen flex flex-col items-center justify-center'>
                <h1 className='font-bold text-2xl text-center'>FaceTime</h1>
                <div className='flex flex-col'>
                    <button
                        className='text-green-500 underline text-sm text-center cursor-pointer'
                        onClick={() => setShowUpcomingMeetings(true)}
                    >
                        Upcoming FaceTime
                    </button>
                </div>

                <div className='flex items-center justify-center space-x-4 mt-6'>
                    <button
                        className='bg-gray-500 px-4 w-[200px] py-3 flex flex-col items-center hover:bg-gray-600 text-white rounded-md shadow-sm'
                        onClick={() => setShowCreateLink(true)}
                    >
                        <FaLink className='mb-[3px] text-gray-300' />
                        Create link
                    </button>
                    <button
                        className='bg-green-500 px-4 w-[200px] hover:bg-green-600 py-3 flex flex-col items-center text-white rounded-md shadow-sm'
                        onClick={() => setStartInstantMeeting(true)}
                    >
                        <FaVideo className='mb-[3px] text-white' />
                        New FaceTime
                    </button>
                </div>
            </main>

            {startInstantMeeting && (
                <InstantMeeting
                    enable={startInstantMeeting}
                    setEnable={setStartInstantMeeting}
                />
            )}
            {showUpcomingMeetings && (
                <UpcomingMeeting
                    enable={showUpcomingMeetings}
                    setEnable={setShowUpcomingMeetings}
                />
            )}
            {showCreateLink && (
                <CreateLink enable={showCreateLink} setEnable={setShowCreateLink} />
            )}
            {joinMeeting && (
                <JoinMeeting enable={joinMeeting} setEnable={setJoinMeeting} />
            )}
        </>
    );
}

The code snippet above renders multiple buttons that allow users to perform actions like joining, creating, and scheduling a call. Each button opens a modal that prompts the user to provide additional details specific to the action they are performing.

Next, let’s create a modals folder within the Next.js app directory and add the following components to the modals folder:

cd app
mkdir modals && cd modals
touch CreateLink.tsx InstantMeeting.tsx JoinMeeting.tsx UpcomingMeeting.tsx

The CreateLink modal allows users to provide a description and schedule a time for the call. The InstantMeeting modal lets users start an instant meeting by providing a call description. The JoinMeeting modal enables users to enter a call link and join a meeting. And the UpcomingMeeting modal displays all scheduled upcoming calls.

The Create Link Modal

Copy the code snippet below into the CreateLink modal:

"use client";
import {
    Dialog,
    DialogTitle,
    DialogPanel,
    Transition,
    Description,
    TransitionChild,
} from "@headlessui/react";
import { Fragment, SetStateAction, useState, Dispatch } from "react";
import CopyToClipboard from "react-copy-to-clipboard";
import { FaCopy } from "react-icons/fa";

export default function CreateLink({ enable, setEnable }: Props) {
    const [showMeetingLink, setShowMeetingLink] = useState(false);
    const [facetimeLink, setFacetimeLink] = useState<string>("");
    const closeModal = () => setEnable(false);

    return (
        <>
            <Transition appear show={enable} as={Fragment}>
                <Dialog as='div' className='relative z-10' onClose={closeModal}>
                    <TransitionChild
                        as={Fragment}
                        enter='ease-out duration-300'
                        enterFrom='opacity-0'
                        enterTo='opacity-100'
                        leave='ease-in duration-200'
                        leaveFrom='opacity-100'
                        leaveTo='opacity-0'
                    >
                        <div className='fixed inset-0 bg-black/75' />
                    </TransitionChild>

                    <div className='fixed inset-0 overflow-y-auto'>
                        <div className='flex min-h-full items-center justify-center p-4 text-center'>
                            <TransitionChild
                                as={Fragment}
                                enter='ease-out duration-300'
                                enterFrom='opacity-0 scale-95'
                                enterTo='opacity-100 scale-100'
                                leave='ease-in duration-200'
                                leaveFrom='opacity-100 scale-100'
                                leaveTo='opacity-0 scale-95'
                            >
                                <DialogPanel className='w-full max-w-2xl transform overflow-hidden rounded-2xl bg-white p-6 align-middle shadow-xl transition-all text-center'>
                                    {showMeetingLink ? (
                                        <MeetingLink facetimeLink={facetimeLink} />
                                    ) : (
                                        <MeetingForm
                                            setShowMeetingLink={setShowMeetingLink}
                                            setFacetimeLink={setFacetimeLink}
                                        />
                                    )}
                                </DialogPanel>
                            </TransitionChild>
                        </div>
                    </div>
                </Dialog>
            </Transition>
        </>
    );
}

The code snippet above renders a form that allows users to input a description and select a time to schedule a call. Once the call is created, the generated link is displayed and can be copied.

Finally, add the MeetingForm and MeetingLink components below the CreateLink component:

const MeetingForm = ({
    setShowMeetingLink,
    setFacetimeLink,
}: {
    setShowMeetingLink: React.Dispatch<SetStateAction<boolean>>;
    setFacetimeLink: Dispatch<SetStateAction<string>>;
}) => {
    const [description, setDescription] = useState<string>("");
    const [dateTime, setDateTime] = useState<string>("");

    const handleStartMeeting = async (e: React.FormEvent<HTMLFormElement>) => {
        e.preventDefault();
        console.log({ description, dateTime });
    };

    return (
        <>
            <DialogTitle
                as='h3'
                className='text-lg font-bold leading-6 text-green-600'
            >
                Schedule a FaceTime
            </DialogTitle>

            <Description className='text-xs opacity-40 mb-4'>
                Schedule a FaceTime meeting with your cliq
            </Description>

            <form className='w-full' onSubmit={handleStartMeeting}>
                <label
                    className='block text-left text-sm font-medium text-gray-700'
                    htmlFor='description'
                >
                    Meeting Description
                </label>
                <input
                    type='text'
                    name='description'
                    id='description'
                    value={description}
                    onChange={(e) => setDescription(e.target.value)}
                    className='mt-1 block w-full text-sm py-3 px-4 border-gray-200 border-[1px] rounded mb-3'
                    required
                    placeholder='Enter a description for the meeting'
                />

                <label
                    className='block text-left text-sm font-medium text-gray-700'
                    htmlFor='date'
                >
                    Date and Time
                </label>

                <input
                    type='datetime-local'
                    id='date'
                    name='date'
                    required
                    className='mt-1 block w-full text-sm py-3 px-4 border-gray-200 border-[1px] rounded mb-3'
                    value={dateTime}
                    onChange={(e) => setDateTime(e.target.value)}
                />

                <button className='w-full bg-green-600 text-white py-3 rounded mt-4'>
                    Create FaceTime
                </button>
            </form>
        </>
    );
};

The MeetingForm component accepts the call description and scheduled time, while the MeetingLink component displays the generated call link and allows users to copy it.

const MeetingLink = ({ facetimeLink }: { facetimeLink: string }) => {
    const [copied, setCopied] = useState<boolean>(false);
    const handleCopy = () => setCopied(true);

    return (
        <>
            <DialogTitle
                as='h3'
                className='text-lg font-bold leading-6 text-green-600'
            >
                Copy FaceTime Link
            </DialogTitle>

            <Description className='text-xs opacity-40 mb-4'>
                You can share the facetime link with your participants
            </Description>

            <div className='bg-gray-100 p-4 rounded flex items-center justify-between'>
                <p className='text-xs text-gray-500'>
                    {`${process.env.NEXT_PUBLIC_FACETIME_HOST}/${facetimeLink}`}
                </p>

                <CopyToClipboard
                    onCopy={handleCopy}
                    text={`${process.env.NEXT_PUBLIC_FACETIME_HOST}/${facetimeLink}`}
                >
                    <FaCopy className='text-green-600 text-lg cursor-pointer' />
                </CopyToClipboard>
            </div>

            {copied && (
                <p className='text-red-600 text-xs mt-2'>Link copied to clipboard</p>
            )}
        </>
    );
};

The Instant Meeting Modal

Copy the following code snippet into the InstantMeeting modal:

"use client";
import {
    Dialog,
    DialogTitle,
    DialogPanel,
    Transition,
    Description,
    TransitionChild,
} from "@headlessui/react";
import { FaCopy } from "react-icons/fa";
import CopyToClipboard from "react-copy-to-clipboard";
import { Fragment, useState, Dispatch, SetStateAction } from "react";
import { useStreamVideoClient } from "@stream-io/video-react-sdk";
import { useUser } from "@clerk/nextjs";
import Link from "next/link";

export default function InstantMeeting({ enable, setEnable }: Props) {
    const [showMeetingLink, setShowMeetingLink] = useState(false);
    const [facetimeLink, setFacetimeLink] = useState<string>("");

    const closeModal = () => setEnable(false);

    return (
        <>
            <Transition appear show={enable} as={Fragment}>
                <Dialog as='div' className='relative z-10' onClose={closeModal}>
                    <TransitionChild
                        as={Fragment}
                        enter='ease-out duration-300'
                        enterFrom='opacity-0'
                        enterTo='opacity-100'
                        leave='ease-in duration-200'
                        leaveFrom='opacity-100'
                        leaveTo='opacity-0'
                    >
                        <div className='fixed inset-0 bg-black/75' />
                    </TransitionChild>

                    <div className='fixed inset-0 overflow-y-auto'>
                        <div className='flex min-h-full items-center justify-center p-4 text-center'>
                            <TransitionChild
                                as={Fragment}
                                enter='ease-out duration-300'
                                enterFrom='opacity-0 scale-95'
                                enterTo='opacity-100 scale-100'
                                leave='ease-in duration-200'
                                leaveFrom='opacity-100 scale-100'
                                leaveTo='opacity-0 scale-95'
                            >
                                <DialogPanel className='w-full max-w-2xl transform overflow-hidden rounded-2xl bg-white p-6 align-middle shadow-xl transition-all text-center'>
                                    {showMeetingLink ? (
                                        <MeetingLink facetimeLink={facetimeLink} />
                                    ) : (
                                        <MeetingForm
                                            setShowMeetingLink={setShowMeetingLink}
                                            setFacetimeLink={setFacetimeLink}
                                        />
                                    )}
                                </DialogPanel>
                            </TransitionChild>
                        </div>
                    </div>
                </Dialog>
            </Transition>
        </>
    );
}

The code snippet above renders a form that allows users to provide a call description. Once the call is created, the link is generated and available to be copied before starting the call.

Finally, add the MeetingForm and MeetingLink components below the CreateLink component:

const MeetingForm = ({
    setShowMeetingLink,
    setFacetimeLink,
}: {
    setShowMeetingLink: Dispatch<SetStateAction<boolean>>;
    setFacetimeLink: Dispatch<SetStateAction<string>>;
}) => {
    const [description, setDescription] = useState<string>("");

    const handleStartMeeting = async (e: React.FormEvent<HTMLFormElement>) => {
        e.preventDefault();
        console.log({ description });
    };

    return (
        <>
            <DialogTitle
                as='h3'
                className='text-lg font-bold leading-6 text-green-600'
            >
                Create Instant FaceTime
            </DialogTitle>

            <Description className='text-xs opacity-40 mb-4'>
                You can start a new FaceTime instantly.
            </Description>

            <form className='w-full' onSubmit={handleStartMeeting}>
                <label
                    className='block text-left text-sm font-medium text-gray-700'
                    htmlFor='description'
                >
                    Meeting Description
                </label>
                <input
                    type='text'
                    name='description'
                    id='description'
                    value={description}
                    required
                    onChange={(e) => setDescription(e.target.value)}
                    className='mt-1 block w-full text-sm py-3 px-4 border-gray-200 border-[1px] rounded mb-3'
                    placeholder='Enter a description for the meeting'
                />

                <button className='w-full bg-green-600 text-white py-3 rounded mt-4'>
                    Proceed
                </button>
            </form>
        </>
    );
};

The MeetingForm component accepts the call description, while the MeetingLink component displays the generated call link and allows users to copy it before starting the call.

The Join Meeting Modal

Copy the code snippet below into the JoinMeeting.tsx file. It renders a form that accepts the call link and redirects users to the call page.

"use client";
import {
    Dialog,
    DialogTitle,
    DialogPanel,
    Transition,
    TransitionChild,
} from "@headlessui/react";
import { useRouter } from "next/navigation";
import { Fragment, useState } from "react";

export default function JoinMeeting({ enable, setEnable }: Props) {
    const closeModal = () => setEnable(false);

    return (
        <>
            <Transition appear show={enable} as={Fragment}>
                <Dialog as='div' className='relative z-10' onClose={closeModal}>
                    <TransitionChild
                        as={Fragment}
                        enter='ease-out duration-300'
                        enterFrom='opacity-0'
                        enterTo='opacity-100'
                        leave='ease-in duration-200'
                        leaveFrom='opacity-100'
                        leaveTo='opacity-0'
                    >
                        <div className='fixed inset-0 bg-black/75' />
                    </TransitionChild>

                    <div className='fixed inset-0 overflow-y-auto'>
                        <div className='flex min-h-full items-center justify-center p-4 text-center'>
                            <TransitionChild
                                as={Fragment}
                                enter='ease-out duration-300'
                                enterFrom='opacity-0 scale-95'
                                enterTo='opacity-100 scale-100'
                                leave='ease-in duration-200'
                                leaveFrom='opacity-100 scale-100'
                                leaveTo='opacity-0 scale-95'
                            >
                                <DialogPanel className='w-full max-w-2xl transform overflow-hidden rounded-2xl bg-white p-6 align-middle shadow-xl transition-all text-center'>
                                    <CallLinkForm />
                                </DialogPanel>
                            </TransitionChild>
                        </div>
                    </div>
                </Dialog>
            </Transition>
        </>
    );
}

Add the CallLinkForm below the JoinMeeting component:

const CallLinkForm = () => {
    const [link, setLink] = useState<string>("");
    const router = useRouter();

    const handleJoinMeeting = (e: React.FormEvent<HTMLFormElement>) => {
        e.preventDefault();
        router.push(`${link}`);
    };

    return (
        <>
            <DialogTitle
                as='h3'
                className='text-lg font-bold leading-6 text-green-600'
            >
                Join FaceTime
            </DialogTitle>

            <form className='w-full' onSubmit={handleJoinMeeting}>
                <label
                    className='block text-left text-sm font-medium text-gray-700'
                    htmlFor='link'
                >
                    Enter the FaceTime link
                </label>
                <input
                    type='url'
                    name='link'
                    id='link'
                    value={link}
                    onChange={(e) => setLink(e.target.value)}
                    className='mt-1 block w-full text-sm py-3 px-4 border-gray-200 border-[1px] rounded mb-3'
                    placeholder='Enter the FaceTime link'
                />

                <button className='w-full bg-green-600 text-white py-3 rounded mt-4'>
                    Join now
                </button>
            </form>
        </>
    );
};

Congratulations! You’ve completed the app’s interface.

How to Authenticate Users with Clerk

Clerk is a user management platform that enables you to add auth to web apps.

You can 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";

const protectedRoutes = createRouteMatcher([
    "/facetime(.*)",
    "/dashboard",
    "/",
]);

//👇🏻 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 "./globals.css";

export default function RootLayout({
    children,
}: {
    children: React.ReactNode;
}) {
    return (
        <ClerkProvider>
            <html lang='en'>
                <body className={inter.className}>
                    <nav className='w-full py-4 md:px-8 px-4 text-center flex items-center justify-between sticky top-0 bg-white '>
                        <div className='flex items-center justify-end gap-5'>
                            {/*-- if user is signed out --*/}
                            <SignedOut>
                                <SignInButton mode='modal' />
                            </SignedOut>
                            {/*-- if user is signed in --*/}
                            <SignedIn>
                                <UserButton />
                            </SignedIn>
                        </div>
                    </nav>

                    {children}
                </body>
            </html>
        </ClerkProvider>
    );
}

After completing this, users will be prompted to create an account or sign in before they can access the application pages.

Finally, create a Clerk account and set up a new Clerk application. Add your Clerk publishable and secret keys to the .env.local file in your project.

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=<publishable_key>
CLERK_SECRET_KEY=<secret_key>

How to Set Up Stream in a Next.js app

First, create a Stream account and set up an organization to house your app. Then, copy the following credentials into your .env.local file:

STREAM_APP_ID=<your_app_id>
NEXT_PUBLIC_STREAM_API_KEY=<your_stream_api_key>
STREAM_SECRET_KEY=<your_stream_secret_key>
NEXT_PUBLIC_FACETIME_HOST=http://localhost:3000/facetime

Next, install Stream React Video SDK and the Stream Node.js SDK.

npm install @stream-io/video-react-sdk @stream-io/node-sdk

Create a providers folder containing a StreamVideoProvider.tsx file and copy the following code snippet into the file:

"use client";
import { tokenProvider } from "@/actions/stream.actions";
import { StreamVideo, StreamVideoClient } from "@stream-io/video-react-sdk";
import { useState, ReactNode, useEffect } from "react";
import { useUser } from "@clerk/nextjs";

const apiKey = process.env.NEXT_PUBLIC_STREAM_API_KEY!;

export const StreamVideoProvider = ({ children }: { children: ReactNode }) => {
    const [videoClient, setVideoClient] = useState<StreamVideoClient>();

    const { user, isLoaded } = useUser();

    useEffect(() => {
        if (!isLoaded || !user || !apiKey) return;
        if (!tokenProvider) return;
        const client = new StreamVideoClient({
            apiKey,
            user: {
                id: user?.id,
                name: user?.primaryEmailAddress?.emailAddress,
                image: user?.imageUrl,
            },
            tokenProvider, //👉🏻 pending creation
        });

        setVideoClient(client);
    }, [user, isLoaded]);

    if (!videoClient) return null;

    return <StreamVideo client={videoClient}>{children}</StreamVideo>;
};

Let’s wrap the entire app with the StreamVideoProvider component, which initializes a Stream client to identify each user.

The StreamVideoClient function takes an object containing the API key, the user object with details from Clerk, and a tokenProvider.

Next, let’s create a Next.js server action (tokenProvider) that generates the token.

Create an actions folder, add a stream.actions.ts file, and copy the following code snippet into the file:

//👇🏻 tokenPrvoider function
"use server";

import { currentUser } from "@clerk/nextjs/server";
import { StreamClient } from "@stream-io/node-sdk";

const STREAM_API_KEY = process.env.NEXT_PUBLIC_STREAM_API_KEY!;
const STREAM_API_SECRET = process.env.STREAM_SECRET_KEY!;

export const tokenProvider = async () => {
    const user = await currentUser();

    if (!user) throw new Error("User is not authenticated");
    if (!STREAM_API_KEY) throw new Error("Stream API key secret is missing");
    if (!STREAM_API_SECRET) throw new Error("Stream API secret is missing");

    const streamClient = new StreamClient(STREAM_API_KEY, STREAM_API_SECRET);

    const expirationTime = Math.floor(Date.now() / 1000) + 3600;
    const issuedAt = Math.floor(Date.now() / 1000) - 60;

    //👇🏻 generates a Stream user token
    const token = streamClient.generateUserToken({
        user_id: user.id,
        exp: expirationTime,
        validity_in_seconds: issuedAt,
    });
    //👇🏻 returns the user token
    return token;
};

Finally, update the RootLayout function in the app/layout.tsx file by wrapping the entire application with the StreamVideoProvider component:

import "@stream-io/video-react-sdk/dist/css/styles.css";
import { StreamVideoProvider } from "./providers/StreamVideoProvider";

export default function RootLayout({
    children,
}: {
    children: React.ReactNode;
}) {
    return (
        <ClerkProvider>
            <html lang='en'>
                <body className={inter.className}>
                    <StreamVideoProvider>
                        <nav className='w-full py-4 md:px-8 px-4 text-center flex items-center justify-between sticky top-0 bg-white '>
                            <div className='flex items-center justify-end gap-5'>
                                {/*-- if user is signed out --*/}
                                <SignedOut>
                                    <SignInButton mode='modal' />
                                </SignedOut>
                                {/*-- if user is signed in --*/}
                                <SignedIn>
                                    <UserButton />
                                </SignedIn>
                            </div>
                        </nav>

                        {children}
                    </StreamVideoProvider>
                </body>
            </html>
        </ClerkProvider>
    );
}

Congratulations! You've successfully integrated Stream into the Next.js app.

How to Create and Join Calls with Stream

In this section, you'll learn how to create, schedule, and join calls using the Stream SDK. You'll also learn how to set up the meeting room with the necessary components and fetch upcoming calls from Stream.

Creating and Scheduling calls

To create an instant meeting, execute the handleStartMeeting function. It generates a random ID for the call and creates the meeting using the current date and the provided description.

import { useStreamVideoClient } from "@stream-io/video-react-sdk";
import { useUser } from "@clerk/nextjs";
const client = useStreamVideoClient();
const { user } = useUser();

const handleStartMeeting = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    if (!client || !user) return;
    try {
        const id = crypto.randomUUID();
        const call = client.call("default", id);
        if (!call) throw new Error("Failed to create meeting");

        await call.getOrCreate({
            data: {
                starts_at: new Date(Date.now()).toISOString(),
                custom: {
                    description,
                },
            },
        });

        setFacetimeLink(`${call.id}`);
        setShowMeetingLink(true);
    } catch (error) {
        console.error(error);
        alert("Failed to create Meeting");
    }
};

The call.getOrCreate() function accepts an optional call description along with the current date and time to initiate the call.

It also allows you to schedule calls for a specific time in the future. In this case, you can specify the desired date and time, and Stream will automatically schedule the call for that period.

import { useStreamVideoClient } from "@stream-io/video-react-sdk";
import { useUser } from "@clerk/nextjs";
const client = useStreamVideoClient();
const { user } = useUser();

const handleScheduleMeeting = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    if (!client || !user) return;
    try {
        const id = crypto.randomUUID();
        const call = client.call("default", id);
        if (!call) throw new Error("Failed to create meeting");

        await call.getOrCreate({
            data: {
                //👇🏻 only necessary changes
                starts_at: new Date(dateTime).toISOString(),
                custom: {
                    description,
                },
            },
        });
        setFacetimeLink(`${call.id}`);
        setShowMeetingLink(true);
    } catch (error) {
        console.error(error);
        console.error("Failed to create Meeting");
    }
};

Joining calls and the Meeting Page

Recall that the meeting link in the app is declared as:

`${process.env.NEXT_PUBLIC_FACETIME_HOST}/${facetimeLink}`
// 👉🏻 format: <http://localhost:3000/facetime/><call.id>

Therefore, we need to create the /facetime/<callID> route to enable users to join a call. To do this, create a facetime folder with an [id] directory inside, and within that directory, add a page.tsx file. Then, copy the following code snippet into the file:

"use client";
import { useGetCallById } from "@/app/hooks/useGetCallById";
import { useUser } from "@clerk/nextjs";
import {
    StreamCall,
    StreamTheme,
    PaginatedGridLayout,
    CallControls,
} from "@stream-io/video-react-sdk";
import { useParams, useRouter } from "next/navigation";
import { useEffect, useState } from "react";

export default function FaceTimePage() {
    const { id } = useParams<{ id: string }>();
    const [confirmJoin, setConfirmJoin] = useState<boolean>(false);
    const [camMicEnabled, setCamMicEnabled] = useState<boolean>(false);
    const router = useRouter();
    //👇🏻 gets call details by ID
    const { call, isCallLoading } = useGetCallById(id);

    useEffect(() => {
        if (camMicEnabled) {
            call?.camera.enable();
            call?.microphone.enable();
        } else {
            call?.camera.disable();
            call?.microphone.disable();
        }
    }, [call, camMicEnabled]);

    //👇🏻 enable users to join calls
    const handleJoin = () => {
        call?.join();
        setConfirmJoin(true);
    };

    if (isCallLoading) return <p>Loading...</p>;

    if (!call) return <p>Call not found</p>;

    return (
        <main className='min-h-screen w-full items-center justify-center'>
            <StreamCall call={call}>
                <StreamTheme>
                    {confirmJoin ? (
                        <MeetingRoom />
                    ) : (
                        <div className='flex flex-col items-center justify-center gap-5'>
                            <h1 className='text-3xl font-bold'>Join Call</h1>
                            <p className='text-lg'>
                                Are you sure you want to join this call?
                            </p>
                            <div className='flex gap-5'>
                                <button
                                    onClick={handleJoin}
                                    className='px-4 py-3 bg-green-600 text-green-50'
                                >
                                    Join
                                </button>
                                <button
                                    onClick={() => router.push("/")}
                                    className='px-4 py-3 bg-red-600 text-red-50'
                                >
                                    Cancel
                                </button>
                            </div>
                        </div>
                    )}
                </StreamTheme>
            </StreamCall>
        </main>
    );
}

When users visit the meeting page, they are presented with a confirmation message, allowing them to confirm that they want to join the call.

In the code snippet above:

• The useGetCallById hook is a custom function that retrieves call details based on the call ID.

• The handleJoin function allows users to join the call and then displays the <MeetingRoom /> component.

Add the MeetingRoom component below the FaceTimePage component:

const MeetingRoom = () => {
    const router = useRouter();

    const handleLeave = () => {
        confirm("Are you sure you want to leave the call?") && router.push("/");
    };

    return (
        <section className='relative min-h-screen w-full overflow-hidden pt-4'>
            <div className='relative flex size-full items-center justify-center'>
                <div className='flex size-full max-w-[1000px] items-center'>
                    <PaginatedGridLayout />
                </div>
                <div className='fixed bottom-0 flex w-full items-center justify-center gap-5'>
                    <CallControls onLeave={handleLeave} />
                </div>
            </div>
        </section>
    );
};

The PaginatedGridLayout arranges participants in a grid layout with pagination, allowing you to manage larger video calls by displaying a set number of participants per page.

The CallControls component provides built-in actions, such as muting, video toggling, and screen sharing, that can be performed during a call. Both components are part of the Stream SDK, making integration seamless.

Additionally, you can switch to the SpeakerLayout, which highlights the dominant speaker or shared screen while displaying other participants in a smaller view.

Finally, create a hooks folder containing the useGetCallById.ts file and copy the code snippet below into the file:

import { useEffect, useState } from "react";
import { Call, useStreamVideoClient } from "@stream-io/video-react-sdk";

export const useGetCallById = (id: string | string[]) => {
    const [call, setCall] = useState<Call>();
    const [isCallLoading, setIsCallLoading] = useState(true);

    const client = useStreamVideoClient();

    useEffect(() => {
        if (!client) return;

        const loadCall = async () => {
            try {
                const { calls } = await client.queryCalls({
                    filter_conditions: { id },
                });

                if (calls.length > 0) setCall(calls[0]);

                setIsCallLoading(false);
            } catch (error) {
                console.error(error);
                setIsCallLoading(false);
            }
        };

        loadCall();
    }, [client, id]);

    return { call, isCallLoading };
};

The code snippet above filters the call list and returns the call with a matching ID, allowing users to join the specified call.

Retrieving Upcoming Calls

To retrieve upcoming calls from Stream, you can create a custom hook that fetches all the calls created by the user, as well as the calls they are a member of.

import { useEffect, useState } from "react";
import { useUser } from "@clerk/nextjs";
import { Call, useStreamVideoClient } from "@stream-io/video-react-sdk";

export const useGetCalls = () => {
    const { user } = useUser();
    const client = useStreamVideoClient();
    const [calls, setCalls] = useState<Call[]>();
    const [isLoading, setIsLoading] = useState(false);

    useEffect(() => {
        const loadCalls = async () => {
            if (!client || !user?.id) return;
            setIsLoading(true);
            try {
                //👇🏻 gets all the calls the user is featured in
                const { calls } = await client.queryCalls({
                    sort: [{ field: "starts_at", direction: -1 }],
                    filter_conditions: {
                        starts_at: { $exists: true },
                        $or: [
                            { created_by_user_id: user.id },
                            { members: { $in: [user.id] } },
                        ],
                    },
                });

                setCalls(calls);
            } catch (error) {
                console.error(error);
            } finally {
                setIsLoading(false);
            }
        };

        loadCalls();
    }, [client, user?.id]);

    const now = new Date();

    //👇🏻 gets only calls that are yet to start
    const upcomingCalls = calls?.filter(({ state: { startsAt } }: Call) => {
        return startsAt && new Date(startsAt) > now;
    });

    return { upcomingCalls, isLoading };
};

The useGetCalls hook retrieves the list of upcoming calls, which can then be displayed in the UpcomingMeeting modal.

Congratulations! You’ve completed the project for this tutorial.

Check out the live app here.

Next Steps

So far, you’ve learned how to build a video conferencing app. If you'd like to learn more about how you can leverage Stream to build scalable apps, then check out these resources:

• How to integrate Stream Chat Messaging

• How to integrate Stream Audio and Video calls

• How integrate Stream Activity Feeds

Before We End...

I hope you found it insightful and that it has given you enough motivation on how to build apps using awesome developer tools.

These are some of my other most recent blog posts.

• State of Databases for Serverless in 2024

• Neon Postgres vs Supabase

• MongoDB vs. PostgreSQL

Check out my blog for more tutorials like this on awesome developer tools.

Follow me on Twitter to stay updated on my side projects and ongoing learning.

Happy coding.

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 ⭐).

Table of Contents

1. What is Neon?
2. Building the Invoice Application with Next.js
3. How to Authenticate Users Using Clerk
4. How to Add Neon to a Next.js app
5. How to Set Up Neon Serverless Driver with Drizzle ORM in Next.js
6. Creating the API endpoints for the application
7. How to Print and Download Invoices in Next.js
8. How to Send Digital Invoices with Resend and React Email
9. 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:

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<HTMLInputElement | HTMLSelectElement>
 ) => {
        const { name, value } = e.target;
        setInputBankInfo((prevState) => ({
 ...prevState,
 [name]: value,
 }));
 };

    //👇🏻 updates the bank info
    const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
        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 Information</h2>
          <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=''>Select</option>
                <option value='$'>USD</option>
                <option value='€'>EUR</option>
                <option value='£'>GBP</option>
              </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<string>("");
  const [customerEmail, setCustomerEmail] = useState<string>("");
  const [customerAddress, setCustomerAddress] = useState<string>("");
  const [loading, setLoading] = useState<boolean>(false);
  const [customers, setCustomers] = useState([]);

  const handleAddCustomer = (e: React.FormEvent<HTMLFormElement>) => {
    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'>Customers</h2>
          <p className='opacity-70 mb-4'>Create and view all your customers</p>

          <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&apos;s Name</label>
                <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 Address</label>
                <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 Address</label>
            <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<Item[]>([]);
  const [customer, setCustomer] = useState<string>("");
  const [invoiceTitle, setInvoiceTitle] = useState<string>("");
  const [itemCost, setItemCost] = useState<number>(1);
  const [itemQuantity, setItemQuantity] = useState<number>(1);
  const [itemName, setItemName] = useState<string>("");
  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<HTMLFormElement>) => {
    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 invoice</h2>

          <form className='w-full flex flex-col' onSubmit={handleFormSubmit}>
            <label htmlFor='customer'>Customer</label>
            <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'>Title</label>
            <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 List</h3>

              <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'>Price</p>
                  <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<Invoice[]>([]);

  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'>History</h2>
          <p className='opacity-70 mb-4'>View all your invoices and their status</p>

          {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:

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.

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:

Copy your database connection string into the .env.local file.

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.

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.

Inside the db folder, add an actions.ts, and schema.ts file:

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.

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.

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.

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:

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<HTMLDivElement, Props>((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 Amount</p>
          </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<any>();

  // States for the data
  const [customer, setCustomer] = useState<Customer>();
  const [bankInfo, setBankInfo] = useState<BankInfo>();
  const [invoice, setInvoice] = useState<Invoice>();

  // 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:

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.

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 <onboarding@resend.dev>",
            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:

• Neon documentation
• Awesome Neon
• Neon example projects
• How to integrate Neon with Vercel
• How to import your data from a Postgres database to Neon

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.

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.

Table of Contents:

• What is Neon?
• Why Neon?
• How to add Neon to a Next.js app
• How to set up Neon Serverless Driver with Drizzle ORM in Next.js
• How to Build the Application Interface with Next.js
• How to Authenticate Users with Clerk
• CRUD Operations with the Neon Database
• Conclusion
• 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

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:

Next, install the Neon Serverless package:

Create a .env.local file and copy your database connection string into the file:

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.

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.

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

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.

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<boolean>(false);
    const [content, setContent] = useState<string>("");
    const [title, setTitle] = useState<string>("");
    const router = useRouter();

    const onChangeContent = useCallback((value: string) => {
        setContent(value);
    }, []);

    const handleCreatePost = async (e: React.FormEvent<HTMLFormElement>) => {
        e.preventDefault();
        console.log({ title, content });
        router.push("/");
    };

    return (
        <div className='min-h-[100vh]'>
            <main className='md:px-8 py-8 px-4 w-full'>
                <form className='flex flex-col w-full' onSubmit={handleCreatePost}>
                    <label htmlFor='title' className='text-sm text-blue-600'>
                        Title
                    </label>
                    <input
                        type='text'
                        name='title'
                        id='title'
                        value={title}
                        required
                        onChange={(e) => setTitle(e.target.value)}
                        className='px-4 py-3 border-2 rounded-md text-lg mb-4'
                    />

                    <label htmlFor='content' className='text-sm text-blue-600'>
                        Content
                    </label>
                    <SimpleMDE value={content} onChange={onChangeContent} id='content' />

                    <button
                        type='submit'
                        disabled={publishing}
                        className='bg-blue-600 mt-2 text-white py-3 rounded-md'
                    >
                        {publishing ? "Publishing....please wait" : "Publish Post"}
                    </button>
                </form>
            </main>
        </div>
    );
}

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<boolean>(true);
    const [post, setPost] = useState<Post | null>(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 (
        <div>
            <main className='w-full md:px-8 px-4'>
                <header className='mb-6 py-4'>
                    <div className='flex items-center justify-between mb-2'>
                        <h2 className='text-3xl text-blue-700 font-bold'>{post?.title}</h2>

                        <div className='flex items-center'>
                            <button
                                className='px-4 py-2 rounded text-xs bg-red-200 hover:bg-red-40 mr-3'
                                onClick={() => deletePost()}
                            >
                                Delete
                            </button>
                        </div>
                    </div>

                    <div className='flex'>
                        <p className='text-red-500 mr-8 text-sm'>
                            Author: <span className='text-gray-700'>{post?.author}</span>
                        </p>
                        <p className='text-red-500 mr-6 text-sm'>
                            Posted on:{" "}
                            <span className='text-gray-700'>
                                {formatDateString(post?.created_at!)}
                            </span>
                        </p>
                    </div>
                </header>

                <div className='text-sm text-justify'>
                    <ReactMarkdown remarkPlugins={[remarkGfm]}>
                        {post?.content!}
                    </ReactMarkdown>
                </div>
            </main>
        </div>
    );
}

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

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.

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.

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:

• Neon documentation
• Neon example projects
• How to integrate Neon with Vercel
• How to import your data from a Postgres database to Neon

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.

This data holds immense value, promising to improve decision-making, streamline operations, and unlock deep customer insights.

But data often remains siloed and inaccessible. It may be spread across different departments and systems, and it can be challenging to understand and utilize effectively.

This is where the concept of Retrieval-Augmented Generation (RAG) technology comes in. By combining the power of retrieval-based techniques and modern generative AI tools, you can build Retrieval-Augmented Generation (RAG) chat applications that allow you to interact with your data using a simple chat interface.

What is Retrieval-Augmented Generation (RAG)?

But before you can chat about your data, a lot of “legwork” is involved. Setting up the infrastructure – the pipeline, vector database, message broker, and knowledge retrieval – is a complex and time-consuming process. This is where the open source tool Agent Cloud comes in.

In this guide, you'll learn all about Agent Cloud and what it can do. We'll start by looking at some background info and the current problems we're dealing with. Then, we'll see how Agent Cloud can help solve them.

How I Started Working with Agent Cloud

I'm passionate about new technology and developer tools, and I sit somewhere between Product Marketing, Growth, and Developer Advocacy. I specialize in the creation of high-quality, technical written content for educational purposes.

I've been involved with the web for ~14 years, the last 4 of which have been documented in punishing detail on my website.

I liked being a Software Engineer but, what I really love to do is code, design, develop, and then write.

Earlier this year I met Andrew (founder of Agent cloud) in a private Slack group. He was seeking someone who could not only write about the product but also discuss and teach people about what they're building. I reached out to him, and after two rounds of discussions, we began working together.

I started with building some cool RAG chatbots in my local and later wrote a couple of comprehensive guides on "How to Build a RAG Chatbot with Agent Cloud".

In this article, I'll teach you how to build a RAG chat app using Agent Cloud to privately and securely talk with your Google Sheets data. I'll also talk about why I think Agent Cloud is good open source developer tool.

Table of Contents:

• What is Agent Cloud?
• What is RAG?
• Challenges of Building a RAG Chatbot Without Agent Cloud
• Prerequisites
• How to Set Up Agent Cloud via Docker
• How to Add Models in Agent Cloud
• How to Create Your GCP Service Account Key
• How to Enable Google Sheets API
• How to Set Up your Data Sources
• How to Set Up tools
• How to Set Up an Agent
• How to Create a Task
• How to Set Up your App
• Conclusion

What is Agent Cloud?

Agent Cloud is an open-source platform that lets you build private, secure chat applications powered by large language models (think ChatGPT).

It streamlines this process by providing a "RAG as a service" offering and a built-in pipeline that allows you to split, chunk, and embed data from over 300 sources (including Google Sheets, Salesforce, Atlassian Confluence, BigQuery, MongoDB, Postgres Data, SharePoint, and OneDrive).

Data sources

What is Retrieval-Augmented Generation?

RAG is a process for enhancing the accuracy of large language models. It does this through the on-demand retrieval of external data and by injecting context into the prompt, at runtime.

This data can come from various sources, such as your customers' documentation/web pages (through scraping), and data or documents from dozens (if not hundreds) of 3rd party applications like their Databases, Google BigQuery, HubSpot, Google Ads, Google Analytics 4 (GA4) and so on.

For those who want to dive deeper into Retrieval-Augmented Generation and understand its broader applications and significance, I highly recommend reading this comprehensive blog by NVIDIA. It offers valuable insights and context that complement the practical aspects covered in this article.

Challenges of Building a RAG Chatbot Without Agent Cloud

If you're working with these AI tools on a daily basis, it becomes easy to understand the value they bring and realize the significance of Agent Cloud in simplifying the chatbot development process.

But to fully appreciate its benefits, you should understand how chatbot development was handled before such tools were available.

Before tools like Agent Cloud, creating a RAG (Retrieval-Augmented Generation) chatbot was a daunting and resource-intensive task. You had to manually integrate various components, which required significant expertise in multiple areas.

Here are some challenges faced and the solutions the Agent Cloud team had to devise:

Data Retrieval and Management:

List of data sources

• Problem: Ensuring that the chatbot could efficiently retrieve and manage data from sources like Google Sheets, Databases, and so on.
• Without Agent Cloud: Developers had to write custom scripts for data retrieval, often using APIs to fetch data from Google Sheets. This involved handling data formatting, error checking, and real-time updates manually. It was a time-consuming process prone to errors.
• Agent Cloud's Solution: Automates data retrieval and management, ensuring seamless and accurate integration with minimal manual intervention.

Natural Language Processing (NLP):

• Problem: Implementing NLP to understand user queries and generate human-like responses.
• Without Agent Cloud: Developers needed to integrate standalone NLP engines such as TensorFlow. This required training models on vast datasets, fine-tuning them for accuracy, and constantly updating them to handle new queries effectively.
• Agent Cloud's Solution: Offers built-in NLP capabilities, significantly reducing setup time and providing high-quality language understanding out of the box.

Scalability and Maintenance:

• Problem: Ensuring the chatbot could handle increasing data loads and user interactions.
• Without Agent Cloud: Building a scalable architecture meant investing in robust server infrastructure, writing efficient code, and continuously monitoring and maintaining the system to handle growth.
• Agent Cloud's Solution: Designed to scale effortlessly, allowing developers to focus on improving functionality rather than managing infrastructure.

User Interaction and Experience:

Agent cloud app UI

• Problem: Creating an engaging and user-friendly interface.
• Without Agent Cloud: Developers had to build custom interfaces, often from scratch, which required additional design and development resources. Ensuring smooth interactions and responsiveness was a major challenge.
• Agent Cloud's Solution: Provides pre-built templates and easy integration options, enhancing the user experience with minimal effort.

By understanding these challenges, you can see how a tool like Agent Cloud helps the process of building RAG chatbots. It addresses the pain points of manual data handling, complex NLP integration, scalability issues, and user interface design, providing an all-in-one solution that saves time and resources.

Prerequisites

You don't need any prior knowledge of RAG chat apps or Google Sheets to follow along because Agent Cloud handles the data splitting, encoding, storage, and synchronization. This allows you to focus on talking to your data and interpreting the results.

How to Set Up Agent Cloud via Docker

First, you'll need to install Docker on your system if you don't have it already. Docker is a platform for running containerized applications.

Open your terminal and run the following command to clone the Agent Cloud repository from GitHub:

Use the following command to move into the newly cloned agentcloud directory:

To run Agent Cloud locally, execute this command:

This command will grant executable permissions to the install.sh script and then run it. The script will download the necessary Docker images and start the Agent Cloud containers within your Docker environment.

local dev setup- agent cloud

Once the installation script finishes successfully, you can view the running Agent Cloud containers in the Docker application.

local docker services

Once everything is up and running, you can access the Agent Cloud user interface in your web browser.

Navigate to the URL:

This will typically open the registration page where you can create an account to use Agent Cloud.

signup- page- agent cloud

You can now log in using the credentials you created during signup.

Once you've successfully registered and logged in, you'll be greeted by the Agent Cloud user interface. This interface provides a central hub for managing your data sources, agents, tasks, models, applications, credentials, and so on.

Home screen - agent cloud

Congratulations! You've successfully set up Agent Cloud. Now let's move on to the next step and build our RAG chat application using Google Sheets as the data source.

How to Add Models in Agent Cloud

Go to the Models tab in Agent Cloud. Click the Add Models button to add two types of models.

• A fast embed model is a lightweight model that runs locally on your machine. It splits and chunks your data before embedding it.
• OpenAI is a popular cloud-based LLM provider.

Models screen- agent cloud

How to Create Your GCP Service Account Key

Agent Cloud offers two authentication methods for accessing your Google Sheets data:

• Google (Auth) – This method involves directly authorizing Agent Cloud through your Google account.
• Service Key Account – This approach utilizes a service key, a credential specifically created for application access to Google Cloud Platform (GCP) services, including Google Sheets.

For this guide, I'll focus on the service key account method, which is generally considered a more secure and streamlined approach for application-to-application communication.

Here is what you’ll need:

• A Google Cloud Platform (GCP) project with the Google Sheets API enabled.
• A service account key is created within your GCP project. This key will be used to authenticate Agent Cloud.

I'll walk you through creating a service account key in your GCP project and configuring Agent Cloud to use it to access your Google Sheets data.

First, create a Google Cloud Platform account. Then create a new project. You can give your project any name that you prefer.

How to Create a GCP Account

Navigate to the "IAM & Admin" section and select "Service Accounts."

IAM and Admin Screen

Click "Create Service Account" and provide a name and description.

How to add service account

Enter your service account name and unique service ID, then click Done.

How to create a service account in GCP

Under the actions tab, click the manage keys option.

Project

Click the ADD KEY button and select the Create Key option.

Select JSON as the key type, then click on Create New Key.

Add keys in GCP

Select JSON as the key type, then click on Create. Your service account JSON or key JSON will automatically download.

Create private key in GCP

Keep this file safe we will use it later for authentication.

How to Enable Google Sheets API

You'll also need to enable the Google Sheets API in your Google Cloud project.

Open the left navigation menu and navigate to "APIs & Services" and then "Library."

APIs and Services in GCP

Type "Google Sheets API" in the search bar and press Enter.

The Google Sheets API will appear in the search results. Click on it.

Google Sheets API

On the API details page, click the "ENABLE" button.

Enable- Google Sheets API

How to Set Up your Data Sources

Agent Cloud empowers you to process data from a wide range of sources.

In this guide, I'll use Google Sheets as the data source. Sheets is a popular web-based spreadsheet application included in Google Workspace. Google Sheets allows you to create, edit, and collaborate on spreadsheets in real-time.

For this example, I'll be working with a financial consumer complaints dataset stored in a Google Sheet.

This dataset contains several columns representing key sales stages and details, potentially including:

• Complaint ID
• Submitted Via
• Date Submitted
• Date Received
• State
• Product
• Sub-product
• Issue
• Sub-issue
• Company
• Public Response
• Company Response to Consumer
• Timely Response?

Here's how to connect your Google Sheets data:

Navigate to the Data Sources tab within the Agent Cloud interface.

Click the button labeled New Connection. This will initiate the process of adding a new data source.

Data Sources- Screen- Agent Cloud

Search and select “Google sheets” as the data source.

Create a Datasource

I've named our data source Financial Consumer Complaints, which you can name however you want. Add a clear and concise description. The data sync will be manual. This means you'll need to initiate the data refresh process whenever you want the latest information from your Google Sheets to be reflected in Agent Cloud.

Enter the appropriate row batch size. Row batch size means how many rows are processed from the Google sheet. For example, the default value 200 would process rows 1-201, then 201-401, and so on.

Choose the authentication method as “Service Account Key Authentication”.

Enter the JSON key we downloaded earlier above under the Service Account Information field.

Enter the link to the Google spreadsheet you want to sync. To copy the link, click the 'Share' button in the top-right corner of the spreadsheet, then click 'Copy link'.

Adding details under datasource

Click the submit button.

Select the collection and fields you want to sync to the vector database and enter their descriptions.

Model pop-up

Click continue and Choose the field you want to embed then choose the model.

Data sources

The connection to your Google Sheet is now established.

During the initial run, Agent Cloud will process your spreadsheet data and convert it into a format suitable for efficient retrieval. This processed data will then be stored within Agent Cloud's vector store.

New- datasource- screen

If you're comfortable with technical details, you can verify the data's presence in the Qdrant vector store running locally on port 6333.

This can be accessed through: http://localhost:6333/dashboard#/collections.

Look for a new collection corresponding to your Google Sheet data.

collection-screen

You can click the collection to view the payloads and the fields populated in the collection.

Payload

How to Set Up Tools

Tools play a crucial role in facilitating effective interaction between the AI agent and its environment, enabling seamless information processing and action execution aligned with its objectives.

These tools can include functions, APIs, data sources, and resources tailored to empower the agent to autonomously and efficiently undertake diverse tasks. While you have the flexibility to craft your own tools as per their requirements, Agent Cloud also streamlines the process by automatically generating a tool upon the addition of a new data source,

Click the Tools tab tools to switch to the Tools page and click the New button.

Enter the tools' names and add a description. A verbose and detailed description helps agents better understand when to use each tool.

Choose the data source and click the Save button.

Edit tool screen

How to Set Up an Agent

AI Agents are intelligent systems that excel at handling routine or repetitive tasks by perceiving their environment, collecting data, and using that data to make decisions.

Click the Agents tab and then click on the New Agent button.

New Agent Screen

Define an Agent's Name, Role, Goal, and Backstory as shown below.

In the "Model" section, choose the AI engine to power your agent's reasoning capabilities. For this example, we've selected "OpenAI GPT-4" as both the Model and Function Calling Model.

Choose the tool we set up earlier under Tools (Optional).

Adding Details in Agent Screen

If "OpenAI GPT-4" isn't already configured within Agent Cloud, you can easily add it. Click on the "Model" field and select "Add new model." A new window will appear, allowing you to define the model's name, type, credentials (your OpenAI API key), and the specific LLM model.

Model- popup

Click the Save button. Once you save this information, "GPT-4" will be available for future agent creation.

Agents-Screen

How to Create a Task

Tasks are specific actions assigned to agents for completion. To create a new task, navigate to the Tasks tab and click the "Add Task" button.

Create Tasks Screen

Enter the following details in the below pop-up window.

• Task name: Give your task a clear and concise title that reflects its purpose.
• Detailed description of what the task entails.
• Choose the tool we created earlier, which is “Financial Consumer Complaint” in my case.
• Select the preferred Agent we created earlier we named it “Customer Complaints Agent”

Adding Details in Tasks Screen

Click the Save button to save the task.

How to Set Up Your App

Now, buckle up because we're about to embark on the exciting part: creating a conversational app. This app will transform our data source into a chat partner, allowing you to have interactive conversations and unlock insights through natural language.

So far, we've laid the foundation for our app. We've created:

• A data source.
• A data retrieval tool.
• An Agent.
• Tasks.

Click the Apps tab and then click the New App Button, and then enter the details below:

New App Screen

• App name – Enter the name you’d like to give to your app.
• Enter a description of what our App.
• Select a Tasks
• Select an Agent
• Choose a Chat Manager Model – Pick the Open AI model we configured earlier.

App Screen

Now, let's test our app.

Clicking the play button will open a chat window for us where we can have a conversation.

Play Button in App Screen

A chat interface window should be opened for us where we can chat with our data. For instance, with the data I have used, I can prompt the app to summarize some of the issues raised by customers related to the Mortgage product.

Live Chat with Data

Or I can have it summarize company responses related to different issues.

Answer Screen

Conclusion

In this tutorial, we explored building a RAG chat application using Agent Cloud and Google Sheets.

We covered setting up Google Sheets as a data source, embedding the data for efficient retrieval, and storing it within a vector store like Qdrant. We also learned how to create tools for Agents (chatbot components) and build an app chat interface where users can interact with the data without writing a single line of code.

If you want to read more interesting articles about developer tools, React, Next.js, AI and more, then I'll encourage you to checkout my blog.

Some of the fresh articles I've written this year.

• How I Build a Blog with Next.js and Firebase
• How I Build a Task Management App with React and Appwrite
• How I Build a Notes App Using React and Supabase – The Complete Guide
• How I Build a RAG Chat App With Agent Cloud and BigQuery

You can get in touch if you have any questions or corrections. I’m expecting them.

And if you found this tutorial useful, please share it with your friends and colleagues who might benefit from it as well. Your support enables me to continue producing useful content for the tech community.

Now it’s time to take the next step by subscribing to my newsletter and following me on Twitter.

This guide follows the 80/20 rule – we'll focus on a few key React concepts that you'll use in the majority of your work with React.

I created this resource for beginner and intermediate developers. In it, I’ll cover all the basic concepts you need to know to get started with React.

Are you ready to build your first React app? Let’s get started.

By the time you finish this guide, you should have a solid understanding of React basics, including:

• What is React?
• How Much JavaScript Do You Need to Know Before Learning React?
• Why Learn React?**
• How to Set Up React
• Key Concepts to Understand in React
• What is JSX?
• What is React State?
• Props in React
• How to display list items in React
• React Event Handlers
• React Hooks
• Data Flow in React

These topics will form the foundation for all advanced concepts you'll learn later on.

This guide is a great resource for JavaScript programmers who are starting to learn React.

What is React?

React is a JavaScript library for building web app user interfaces.

It's open-source and developed by Facebook. With React, you can create a quick and scalable web app by breaking the UI down into smaller components.

React adopts a declarative style, but what does that mean? You might have come across the terms imperative and declarative in coding discussions, so let's break it down.

In imperative coding, you instruct the computer on what steps to take to achieve the result.

Here's an example:

let num = [1,2,3,4];
let tripled  = [];
for(let i = 0; i < num.length; i++){
    let newNum = num[I] * 3;
    tripled.push(newNum)
}
console.log(tripled)   // [ 3, 6, 9, 12 ]

In the code above, we give step-by-step instructions to carry out certain tasks. If our instructions are incorrect, the machine might not deliver the expected outcome. It only does what we clearly instruct it to do.

On the flip side, in declarative programming, we state our desired outcome, and the computer works out the steps to achieve it.

Here’s an example:

let num = [1,2,3,4];
let tripled = num.map((n) =>  n * 3);
console.log(tripled)  // [ 3, 6, 9, 12 ]

In each cycle, the program multiplies the num by three and adds it to an array.

We aren’t providing step-by-step instructions, yet the actions are carried out. This declarative approach is what makes React run so efficiently, and it's one of its standout features.

How Much JavaScript Do You Need to Know Before Learning React?

The initial question often is, how well should you know JavaScript before tackling React? I think it's important to have a solid understanding of JavaScript's core concepts before diving into any framework or library, as it will benefit you in the long run.

Let’s say you want to become a web developer and you want to use React as your primary technology.

Here is a high-level roadmap you can use to make sure you have the knowledge you need:

• Learn the basics of JavaScript.
• Learn about web pages and web development technologies like HTML and CSS.
• Learn the basics of Node.js and Express.
• Be able to write some kind of simple Node.js web app.
• Learn about the different frameworks (React) and technologies developers use to develop Node.js apps.
• Learn some kind of database to use with Node.js.
• Learn computer science basics, like Algorithms and Data structures.
• Learn best practices for writing good code.
• Learn how to design the architecture of a React.js app.

Having some kind of plan in place is important. You can always change and adapt the plan, but if you don’t have the plan to begin with, you’ll be aimlessly wandering and you may end up frustrated and be more likely to give up.

So the simple answer to this question is, once you're confident in your JavaScript basics, go ahead and start learning about and building projects with React. You can read this article to make sure you understand those fundamental JS concepts.

The tech field moves quickly with new languages or frameworks coming out often. If you focus on building a strong foundation, you'll be set to dive in.

Here are some more useful resources for learning JavaScript:

• freeCodeCamp's JS course
• The Modern JavaScript Tutorial
• '33 JavaScript Concepts' on GitHub
• Official JS Documentation (MDN)

Why Learn React?

There are a number of reasons why learning this popular JavaScript library is beneficial.

Here are a few:

• React is well-liked in frontend development due to its reusable UI components, flexibility, and ease of debugging. This helps developers build large web apps more efficiently.
• Chances are, you'll come across a React project either in your current job or in the future.
• For a JavaScript programmer, facing React-based questions in job interviews is common.
• Many frameworks or libraries, like NextJs and Gatsby, are built on top of React.
• React enhances your development skills as it encourages good practices. It helps you consider data flow and global state management in your apps, along with its design patterns prompting you to think about various scenarios and edge cases.

For more insights, you can read my article on Why You Should Learn React.

How React Stands Out from Other JavaScript Ecosystem Tools

Firstly, React is speedy as it utilizes the virtual DOM to display data, updating only the altered parts when data changes.

React also encourages breaking down code into small, reusable chunks. This makes it manageable rather than tackling a large codebase all at once.

Beyond this, React simplifies debugging and speeds up large-scale development.

It's also SEO-friendly, which is crucial for business visibility on search engines like Google. And being open-source with a large community, React offers ample support and a variety of tools and extensions to ease its usage and debugging.

Now, with a better understanding of React's benefits, let’s go ahead and set up React in our local development environment.

How to Set Up React

First, you need to install Node.js. It allows you to execute JavaScript code and run React applications on your computer.

You can install it from the website and check its current version using the code snippet below.

Setting up local development environment

Ensure you have Node 14.0.0 or higher on your machine to install the latest React version.

Then, to quickly set up a React app, there are a couple ways you can go. If you want, you can use the official tool, create-react-app. Executing npx create-react-app my-app will download the latest React version. But this method is no longer recommended for installing React.

Instead, you can create a React app using Vite, which is a development environment for modern applications.

Run the code snippet below within your terminal, provide a name for your project, and select React as the framework.

npm install

Start the development server by running the npm run dev within your terminal.

The app will launch on your local port 5173 by default.

Now, we're set to deep dive into the core concepts of React.

Key Concepts to Understand in React

React Components

The browser returns a set of React elements, called components, that appear on the computer screen.

In React, a web page can be divided into multiple components that make up the entire elements on the screen. This helps us adhere to the DRY (Don’t Repeat Yourself) principle and write cleaner code.

React splits the UI into independent and reusable pieces (components). Each component name must start with a capital letter, which makes it readable. They have their own styles, APIs, logic, and structures.

There are two types of React Components:

• Class or stateful components
• Functional or stateless components

Class Components (Stateful)

This method for creating React components is considered outdated. Although still supported by React, it is not recommended because new features in React are based on function components and hooks.

Class Components are declared using the JavaScript class keyword. They are called stateful because the variables within the components are linked to them using the JavaScript this keyword.

To create class components, you need to extend the default React component which contains a constructor function with all the required states. The class component displays its elements via a render function.

Let’s consider a Hello World component using Class Components.

import React, { Component } from 'react';

class HelloWorld extends Component {
  constructor(props) {
    super(props);
    // Initialize state
    this.state = {
      greeting: 'Hello, World!'
    };
  }

  render() {
    return (
      <div>
        <h1>{this.state.greeting}</h1>
      </div>
    );
  }
}

The code snippet above creates a Class Component with a state called greeting containing a "Hello World" value. The state is declared using the this.state keyword and the render method then displays the value of the greeting state within an h1 element.

Remember: you should generally avoid using class components in your applications, and use functional components instead – which we'll discuss now.

Functional Components (Stateless)

Functional components are a modern way of writing React. They follow the JavaScript ES6 method of writing functions. A functional component accepts a single argument known as props (object data), mostly returned with a JSX element.

Functional components receive data as props from different components. You'll learn how to manage state a little later in this guide.

Consider the example below:

import "useState" from "react"
function App() {
  const [name, addName] = useState('');
  function handleAddName(event) {
    addName(event.target.value);
  }
  return (
    <div>
      <form>
      <label>
        Name:
        <input type="text" value={name} onChange={handleAddName} />
      </label>
      </form>
      <p>
        Welcome {name}, I hope you will learn a lot in this Handbook. 
      </p>
    </div>
  );
}

Function components are declared similarly to JavaScript functions. The difference is that components accept props and render JSX elements. You'll learn more about JSX next.

What is JSX?

Every component you see uses JSX. The best thing about React is that you can easily embed JavaScript into JSX. It gives you the flexibility to build fast UIs. But wait, what is JSX?

JSX stands for JavaScript Syntax Extension, and it lets you use HTML-like syntax in your React components.

A function called React.createElement() enables us to create JSX elements in React. It accepts three arguments – the HTML element, an object containing the HTML element’s attribute, and the content of the HTML element.

Let’s see some examples: The code snippet above creates a button that displays “Click here” with a background colour and text color attributes.

React.createElement( 
'button', 
{ color : 'white', backgroundColor: 'blue'},
'Click here'
)

But developers don’t create JSX elements this way. In fact, you don’t need to use the React.createElement() function because it creates a lot of unnecessary lines of code and will be difficult to create deeply nested JSX elements.

Instead, React provides an easier way of writing JSX elements. They are similar to HTML elements and accept an attribute called className that replaces the class attribute in HTML.

There are two rules concerning JSX elements:

• class is a JavaScript keyword. Therefore, use className instead of class when styling your JSX elements.
• A component can only return one JSX element. But when you need to display more than one JSX element, put them in a single container element.

Let’s see some examples:

function Greeting() {
  return (
  <h1 className="heading">Welcome to React </h1>
  );
}

The code snippet above shows a Greeting component that returns a single JSX element. It displays “Welcome to React” using the h1 element. The className attribute adds the “heading” style to the JSX element.

Consider another component that returns multiple JSX elements:

function Greeting() {
  return (
<div>
  <h1 className="heading">Welcome to React </h1>
 <p>This message is sponsored by FreeCodeCamp
</div>
  );
}

The code snippet above returns more than one JSX element nested within a parent element. So it is important to note that all JSX elements must be within a parent container.

What’s the Difference Between HTML and JSX?

JSX syntax looks like HTML. In HTML, we use class attributes for styling purposes. In JavaScript, ‘Class’ is a reserved word. So we can’t use the class keyword. For this, React uses className instead of Class as the default for styling.

Consider the example below:

<!DOCTYPE html>
<html lang="en">
    <head>
        <style>
            .heading {
                color: #3498db;
            }

            .paragraph {
                font-size: 18px;
            }
        </style>
    </head>
    <body>
        <h1 class="heading">Welcome to React</h1>
        <p class="paragraph">Happy learning</p>
    </body>
</html>

The code snippet above shows an HTML document that displays a heading and paragraph elements on the web page. The elements are styled using the CSS class selector (HTML class attribute).

Let’s recreate this with JSX elements:

'const App = () => {
    return (
        <div>
            <h1 className='heading'>Welcome to React</h1>
            <p className='paragraph'>Happy learning</p>
        </div>
    );
};

The code snippet above displays the heading and paragraph JSX elements and uses the className attribute to style each of them. You can add a CSS file containing your styles within your project.

What is React State?

State is a key concept in React apps. You can think of state as a collection of information or objects that tell you where you can access and store your data. Anything outside of a component, for example, can’t access its data. It’s private and controlled by the component.

Every React component has its own state. Whenever a state changes, the component gets re-rendered. This happens when a user clicks a button, responds, or interacts with something on the page.

The children components can access these states via props (which we’ll discuss below) passed by the parent’s component.

Let’s consider some examples of React state:

const [name, setName] = useState("")
const [age, setAge] = useState(0)
const [products, setProducts] = useState(["rice", "beans"])

The code snippet above shows some examples of React states. A state can be an array, string, object, or number. The useState hook accepts the initial value of the state as a parameter, and the state name and state function (for modifying its value) are destructured from the useState hook.

const [stateName, stateFunction]= useState(<initial_value>)

Consider a form that accepts a user’s name and age and displays them, like this:

function UserInfo() {
  const [name, setName] = useState('');
  const [age, setAge] = useState(0);

  function handleNameChange(event) {
    setName(event.target.value);
  }
  function handleAgeChange(event) {
    setAge(parseInt(event.target.value));
  }
  return (
    <div>
      <form>
      <label>
        Name:
        <input type="text" value={name} onChange={handleNameChange} />
      </label>
      <label>
        Age:
        <input type="number" value={age} onChange={handleAgeChange} />
      </label>
     </form>
      <p>
        Your name is {name} and your age is {age}.
      </p>
    </div>
  );
}
export default UserInfo;

The code snippet above accepts the user’s name and age and stores them within the React states. The functions handleNameChange and handleAgeChange accept the user’s input and update the state’s values.

Global State vs Local State in React

Global States refers to state values used in multiple components within the application. In some cases, they can be updated anywhere within the application.

For instance, when a user changes from dark to light mode while using your application. This state affects the overall view of the application to ensure that all the components change colour.

To do this, you may need to declare a state like this:

const [darkmode, setDarkMode] = useState(false)

This state gets updated when a user toggles a switch within the application. This state is global because it is passed into all the components within the application to ensure that their views change depending on the state's value.

Let's see an example:

const App = () => {
    const [darkMode, setDarkMode] = useState(false);
    return (
        <div>
            <Home darkMode={darkMode} />
            <Profile darkMode={darkMode} setDarkMode={setDarkMode}>
        </div>
    );
};

From the code snippet above, we have an App and a Profile component. The App component is a higher-order component that renders two components and contains a state called darkMode that toggles the mood of the application.

The sub-components (Home and Profile) accept the states and update their element's colour depending on the state's value.

From the Profile component, darkMode is a global state, and name is a local state because the name state is declared and bound to the Profile component only, and darkMode is available to other states apart from the App component.

Local states are state variables bound to a component. They are used outside that component, meaning they are local to that component.

For instance, the name state is local to the Profile component:

const Profile = () => {
    const [name, setName] = useState("Ankur");
    const toggleName = () => setName("Tyagi");
    return (
        <div>
            <h1>Hi, I'm {name}</h1>
            <button onClick={toggleName}> Toggle Name </button>
        </div>
    );
};

The code snippet above toggles the name state between “Ankur” and “Tyagi” when a user clicks the button, and the state is not used anywhere outside the Profile component.

Props in React

Props are data transferred from a parent to a child component. Props can’t be modified, because they are read-only. A child component can not change the values of the props received from the parent component.

The diagram below shows that a component accepts props from another component and displays them as JSX elements within the component.

Diagram showing how props work

For example, let’s consider an application that allows users to toggle the application theme.

const App = () => {
    const [darkMode, setDarkMode] = useState(false);
    return (
        <div>
            <Home darkMode={darkMode} />
            <Profile darkMode={darkMode} setDarkMode={setDarkMode}>
        </div>
    );
};

The code snippet above shows that the Home and Profile components accept the darkMode state and its function as props. The Home component accepts the darkMode value and the Profile component accepts the state’s value and its function.

Now, how do we access the prop values within these components? You can do this via a method called Destructuring.

Destructuring props in React

Props destructuring is a simple phenomenon similar to how we get object values in JavaScript. Let’s see an example:

const profile = {
 name: "Ankur Tyagi",
 age: 22,
 role: "Technical Writer",
};

From the code snippet above, the object contains a name, age, and role property. In JavaScript, you can get the values of each property using the objectName.

Therefore, you can access each value as shown below:

console.log(profile.name)  //"Ankur Tyagi"
console.log(profile.age) //22
console.log(profile.role) //"Technical Writer"

However, destructuring provides a better and much cleaner way of getting the values within an object or array.

const profile = {
 name: "Ankur Tyagi",
 age: 22,
 role: "Technical Writer",
};
//Destructuring the object
const { name, age, role } = profile;
console.log(`My name is ${name}. I am a ${role} and ${age}years old`);

const friends = ["Tejas", "Brad", "Ankit"]
//Destructuring the array
const [first, second, third] = friends

console.log(first)

From the code snippet above, the object properties and array values are destructured from the parent enabling us to reference each values using the property name or a variable name. Destructuring provides a cleaner way of accessing the values in an object or an array.

But React uses this ES6 syntax to simplify how you access values within objects and arrays and values from props. Note that when you pass data into components via props, the data is added as a property to the props object.

const App = () => {
    const [darkMode, setDarkMode] = useState(false);
    return (
        <div>
            <Home darkMode={darkMode} />
            <Profile darkMode={darkMode} setDarkMode={setDarkMode}>
        </div>
    );
};

The Profile component destructures the darkMode and setDarkMode values from the props object parameter, thereby, enabling us to interact with the data directly.

Every React component has a default props object that enables data sharing between components and you can access the props value using any of the destructuring methods below:

const Component = (props) => {

State vs Props

State and props are used for holding data within a React application. But they serve different purposes.

• States are mutable, and Props are immutable. Data stored in a state can be modified, while Props can not be modified (read-only).

const App = () => {
    //👇🏻 state
    const [name, setName] = useState("Ankur");
    ////👇🏻 modify state
    const changeName = () => setName("Tyagi");

    return (
        <div>
            <Profile name={name} />
        </div>
    );
};

//👇🏻 accepts name as props
const Profile = ({ name }) => {
    return (
        <div>
            <h1>Hi, I'm {name}</h1>
            <p>Welcome to my tutorial</p>
        </div>
    );
};

The code snippet above shows that when you declare a state, React allows you to create a function that modifies the state value. Also, states become props (read-only) when you pass them into other components.

• State are local to a component while Props are from a parent component. From the code snippet above, the name state is local to the App component but becomes a prop when passed into the Profile component.

How to Display List Items in React

So far, you’ve seen how to display states and props values within JSX elements in React. But in some cases, you may need to display list items on a webpage – for example, data received from an API endpoint. How do we render this in React? You’ll learn about that shortly.

Let’s consider the following code snippet that renders a list of foods:

export default function App() {
    const products = ["Rice", "Beans", "Yam", "Eggs"]
    return (
        <div>
            <ul>
                {products.map((item) => (
                    <li>{item}</li>
            ))}
            </ul>  
        </div>
    )
}

In React, the JavaScript function array.map() is used to render list items. But the code snippet is incomplete. Each list item must have a unique key prop to enable React keep track of each item within the list.

Warning stating that each child in the list should have a unique key prop.

To fix this, update the code snippet as shown below:

export default function App() {
    const products = ["Rice", "Beans", "Yam", "Eggs"]
    return (
        <div>
            <ul>
                {products.map((item, index) => (
                    <li key={index}>{item}</li>
            ))}
            </ul>

        </div>
    )
}

The array.map() function accepts two arguments: the list item and its position within the array. So you can set the key prop to the index (item position) to enable React to distinguish each item from the others.

The key prop optimizes React's performance and is useful for performing CRUD operations with list items.

Let's consider a to-do list that enables users to create and delete to-do items.

import { useState } from "react";

export default function App() {
    const [todoList, setTodoList] = useState([]);
    const [todo, setTodo] = useState("");

    const handleSubmit = (e) => {
        e.preventDefault();
        setTodoList([...todoList, { todo, id: Math.random() * 1000 }]);
        setTodo("");
    };
    const handleDelete = (id) => {
        const newTodoList = todoList.filter((item) => item.id !== id);
        setTodoList(newTodoList);
    };

    return (
        <div>
            <h1>Todo List</h1>
            <form onSubmit={handleSubmit}>
                <input
                    type='text'
                    name='todo'
                    id='todo'
                    value={todo}
                    onChange={(e) => setTodo(e.target.value)}
                    required
                />
                <button type='submit'>Add Todo</button>
            </form>

            <div>
                {todoList.map((item) => (
                    <div key={item.id}>
                        <p>{item.todo}</p>
                        <button onClick={() => handleDelete(item.id)}>Delete</button>
                    </div>
                ))}
            </div>
        </div>
    );
}

The handleSubmit function accepts the user’s input and adds it to the to-do list, and the handleDelete function removes the selected to-do from the to-do list using its id.

The code snippet above displays the items within the to-do list and uses the items’ ids to identify each to-do when adding and removing items from the list.

Example todo list - adding and deleting items

React Event Handlers

When we click some button or interact with the UI, we expect a response. This is made possible with Event handlers. These event handlers determine which action is performed when the user interacts with them (that is, when some event is performed).

If you know how to handle events in JavaScript, it won't be that hard to understand how to do it in React. There are just a couple differences.

In React, event handlers are written in camelCase form like this: onClick, onChange, and so on.

Here’s an example that shows the difference between writing event handlers in HTML and React. Both code snippet executes a function called handleClick when a user clicks the button.

In HTML:

<button onclick="handleClick()">
You clicked a button
</button>

In React:

<button onClick={handleClick}>
You clicked a button
</button>

In React, you need to use event handlers when submitting a form and modifying the value of a state. Let’s see some examples:

import { useState } from "react";

export default function App() {
    const [todo, setTodo] = useState("");

    const handleSubmit = (e) => {
        e.preventDefault();
        console.log({ todo });
    };

    return (
        <div>
            <h1>Todo List</h1>
            <form onSubmit={handleSubmit}>
                <input
                    type='text'
                    name='todo'
                    id='todo'
                    value={todo}
                    onChange={(e) => setTodo(e.target.value)}
                    required
                />
                <button type='submit'>Add Todo</button>
            </form>
        </div>
    );
}

There are two event handlers in the code snippet above: the onSubmit and the onChange handlers.

The onChange event handler updates the todo state with the form’s input as the user enters a value into the form field.

The onSubmit event handles the form submission. In most React forms, you’ll come across the function event.preventDefault(). It prevents the page from reloading (default action) every time a user submits the form.

React Hooks

Hooks are a critical feature of React that were introduced in V16.8.

In class components, we encounter some problems:

• We have to take care of Auto-binding and “This”
• The code gets lengthier, and serval lifecycle methods are hard to follow.
• It is hard to share logic and reuse components

To solve all of these class-related problems, the React team created hooks. They help you write cleaner, more readable, and maintainable code. So let’s learn about few of the Hooks and how to use them.

The useState hook

useState is used for creating a state variables. It enables us to create and change state variables within our components.

useState returns a pair of values. The first one is the current state and the second is the function that updates it.

const [value, setValue] = useState(<initial Value>)

Let’s create a counter using the useState hook:

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

We initialize a count state and set it to “0”. The handleClick function modifies the count state using the setCount function to increase the count value by 1.

The code snippet below modifies the count state when the user clicks the increment and the decrement buttons.

function Counter = () => {
    const [count, setCount] = useState(0);
    function handleClickInc(){
        setCount(counter => counter + 1)
    }
    function handleClickDec(){

The useEffect hook

The useEffect hook is an essential hook that enables us to perform actions when various changes occur within a React component, such as data fetching, when a component re-renders, and so on.

The useEffect hook accepts two parameters: a function and a dependency array. The function is executed depending on the conditions within the dependency array.

useEffect(()=> {

There are three ways you can use the useEffect hook:

• Without a dependency array
• With an empty dependency array
• With a dependency array containing values.

Without a dependency array

A useEffect hook without a dependency array will run every time the component re-renders due to an event or a state change. You should not use the useEffect hook this way because it leads to performance issues.

Assuming there is a useEffect hook within the Counter component, it will return when the component mounts on the page and every time the counter changes.

import { useEffect, useState } from "react"

export default function Counter() {
    const [count, setCount] = useState(0);

    const increment = () => setCount( prev => prev + 1)
    const decrement = () => setCount( prev => prev - 1)

    useEffect(() => {
        console.log("Run everytime count changes");
    });


    return (
        <div>
            <h1>Count: {count}</h1>
            <div>
                <button onClick={increment}>Increase</button>
                <button onClick={decrement}>Decrease</button>
            </div>
        </div>
    );
}

Note that you should avoid using useEffect without its dependency array – it will cause performance issues within your application.

With an empty dependency array

A useEffect hook can also contain an empty dependency array. This means that the function within the useEffect function should run only once – when the component mounts or is loaded on the web page.

This method is mostly used when you need to fetch data from an API endpoint and display it on the web page when it loads.

Here is an example, the useEffect function runs only once (when the page mounts). An empty dependency array tells React that the useEffect runs once – when the component is rendered on the web page.

import { useEffect, useState } from "react"

export default function App() {
    const [count, setCount] = useState(0);

    const increment = () => setCount( prev => prev + 1)
    const decrement = () => setCount( prev => prev - 1)

    useEffect(() => {
        console.log("Run only once when component is mounted");
    }, []);

    return (
        <div>
            <h1>Count: {count}</h1>
            <div>
                <button onClick={increment}>Increase</button>
                <button onClick={decrement}>Decrease</button>
            </div>
        </div>
    );
}

With a dependency array containing values

In this previous section, you learned that declaring a useEffect function without a dependency array causes performance issues. So how can we execute function that runs when the counter changes?

This is where the dependency array helps. It contains the values that the function depends on. The function runs when the component is rendered and when the value of variables within the array changes.

Let’s update the useEffect hook to run only when the count changes.

import { useEffect, useState } from "react"

export default function App() {
    const [count, setCount] = useState(0);

    const increment = () => setCount( prev => prev + 1)
    const decrement = () => setCount( prev => prev - 1)

    useEffect(() => {
        console.log("useEffect runs when count changes");
    }, [count]);

    return (
        <div>
            <h1>Count: {count}</h1>
            <div>
                <button onClick={increment}>Increase</button>
                <button onClick={decrement}>Decrease</button>
            </div>
        </div>
    );
}

The useReducer hook

The useReducer is commonly used in components that have a large number of states and multiple event handlers. It enables you to manage complex states within your application.

You should just use the useState hook when there are a few states within your components. Use the useReducer hook when you have a lot of states to manage.

The useReducer hook is divided into four parts: the state, the reducer function, the action, and the dispatch function.

The state is an object containing all states declared within the application.

The reducer function manipulates the state directly and returns a copy of the result, and the dispatch function triggers the reducer function when an event occurs.

The action is an object containing a type and a payload property.

The type property specifies the exact action to be executed by the reducer function, and the payload can accept data from the user or other parts of the application.

Let’s see how this works by re-creating the Counter component using the useReducer hook:

import { useReducer } from "react";

The useReducer hook accepts two arguments: the reducer function and the state object. It returns the states and the dispatch function.

const [state, dispatch] = useReducer(reducerFunction, {states});

From the Counter component, the useReducer hook accepts the reducer function and the counter’s initial state.

import {useReducer} from "react"  
//👇🏻 declares the useReducer hook
 const [state, dispatch] = useReducer(reducer, { counter: 0 }));

After declaring the useReducer hook, you need to create the reducer function which handles the state manipulation.

//👇🏻 reducer function
 const reducer = (state, action) => {
  switch (action.type) {
   case "increase":
    return { counter: state.counter + 1 };
   case "decrease":
    return { counter: state.counter - 1 };
   default:
    return state;
  }
 };

The reducer function accepts a state and action parameter. The action object determines the action to be carried out by the reducer function.

Finally, we have the dispatch function that states the type of action and passes its value into the reducer function to enable it carry out the required task.

const increaseCounter = () => {
  dispatch({ type: "increase" });
 };

 const decreaseCounter = () => {
  dispatch({ type: "decrease" });
 };

You can also pass data into the reducer function via the dispatch. For example, you can increase the counter by 2 by passing the data as a payload via the dispatch function.

const increaseBy2 = () => {
  dispatch({type: "increaseBy2", payload: {number: 2}})
 }

Then, create its action within the reducer function as shown below:

const reducer = (state, action) => {
  switch (action.type) {
   case "increase":
    return { counter: state.counter + 1 };
   case "decrease":
    return { counter: state.counter - 1 };
   case "increaseBy2":
    return { counter: state.counter + action.payload.number };
   default:
    return state;
  }
 };

The useReducer hook is much more useful in components containing numerous states and various state modifications, because it enables you to write the code in a cleaner way.

Data Flow in React

Data flows from top to bottom in React, meaning you can only pass data from a parent to a child component. This is where props come in handy. But sometimes you may need to pass data from a child to a parent component. How do we achieve this?

You can accomplish this by lifting the state up. This involves moving the state from the child component to the parent component where the state is needed. Keep in mind, though, that this solution may not be effective because it might lead to prop drilling.

What is Prop Drilling?

Prop drilling occurs when the parent and child components are not directly linked, and you need to pass the data via multiple components before it reaches the child component that needs the data.

Let's consider an example: suppose we have an App component that renders various parts of the application. Then, a Products component displays the list of available products, and we need to show the total number of products within the Nav component at the top of the screen.

To solve this, you may need to move the products into the App component and pass them as props into all the child components until they reach the Nav and Product components. This process is called prop drilling. The product data will have to pass through components that do not require it.

Diagram illustrating how prop drilling works

State management libraries like Redux Toolkit, React Context API, and Zustand can help solve this problem. They enable you to create a store within your application that allows all the components to access the store independently without interacting with a parent component.

Any changes made to a state within the store reflect within all the required components. Feel free to research and learn about this topic more.

Diagram showing how using a state management library can help

Wrapping Up

That’s all for this tutorial. I hope you found the discussion enlightening and are now better equipped to make informed decisions in your React journey.

If you're eager to dive deeper into React and expand your skills, I've got a treasure trove of resources right on my blog. From beginner-friendly tutorials to advanced tips and tricks, there's something for everyone looking to master this powerful library.

Don't miss out on my latest React tutorials:

• Understanding React Hooks: A Beginner's Guide - Read Here
• State Management in React: Redux vs Context API - Read Here
• How to Use and Validate Forms in React - Read Here

If you want to learn React according to industry standards, here is where I’ve shared my experience: Best Practices for Keeping a React Project Clean and Efficient.

You can get in touch if you have any questions or corrections. I’m expecting them.

And if you found this tutorial useful, please share it with your friends and colleagues who might benefit from it as well. Your support enables me to continue producing useful content for the tech community.

Now it’s time to take the next step by subscribing to my newsletter and following me on Twitter.

A newsletter on Career, Business, Writing and Life advice for Engineers

It can also simply be the place where you build a loyal audience within your niche, share your knowledge and ideas, and help other devs.

The benefits of having a personal blog as a developer