The gap between what you tell the computer to do and what you want the computer to do is where bugs are born and thrive.

As a moderator on the freeCodeCamp Discord, I frequently see people pop in to say, “I did everything exactly right but my code isn’t working!” These people know what they want their code to do. But they didn’t tell the computer how to do it properly.

To resolve their bug, they must align their desires — their mental model of their code’s behavior — with their code. Assumptions are the truses that preserve that gap.

The Problem with Assumptions

Let’s say that I'm working on a webpage and I want to set an element’s background to be blue. It’s not working as I desire. It’s setting the text color instead of the background color.

I engage my coworker for help. I say to her, “I told the computer to make the background blue. But it’s setting the text color instead!”

My problem is that I didn’t tell the computer to change the background color. I instead mistakenly used the color property. There’s no way that my coworker could know that I was using the wrong property. So my assumption prevented her from helping me.

The Components of a Great Question

Getting help takes effort. The more work you put into seeking help, the more likely you’ll be to obtain the help you need. In my experience, there are 3 components to a great question when you need technical assistance. Great questions contain all of these components.

1. The code that contains the problem

2. Any error messages you’re seeing

3. A description of the issue containing all of the following:

   • The exact steps to reproduce the issue

   • The expected result

   • The actual result

Below, I’ll break down each component in detail in case you’re not sure how to provide it when asking for help.

The Code that Contains the Problem

This is harder than it sounds. Frequently, the reason I fail to fix a bug by myself is that I’m looking in the wrong place. I may be looking in the wrong function, file, or even project! If I go to my coworker for help and only provide her the code that I think contains the problem, then she may not be able to help me out.

This means that it’s important to provide as much context as possible. This increases the chances that the code you share with the people helping you will contain the information they need to help you solve your problem.

Even with decades of experience coding, I frequently have doubts about how certain code will behave. Being able to run the code and experiment with it (add logs, attach a debugger, try different inputs, and so on) is a big part of my process.

There’s lots of ways you might transmit your code to someone to get some help. Here’s some examples:

For Large Projects

If you’re having trouble with a large project (something more than one file or more than a couple hundred lines of code). Then your best bet is to share a GitHub repo containing all the code.

Alternatively, you might create a “minimal reproduction.” If you can make the problem happen in the context of a small amount of code, then you can share that code instead. This can dramatically reduce the amount of work others need to do to help you and increase your chances of getting the answers you’re seeking.

Note: When working on a project for a client or employer, you might not be able to get help from outside sources due to your inability to share the relevant code. Don't share your employer’s or clients’ code publicly unless you have explicit permission to do so!

For Single File Projects

If your project is just one or two files or you’re creating a minimal reproduction of the issue, then you might be able to in-line your code in a chat message or create a GitHub Gist containing the relevant code.

Alternatively, you could use a tool like CodePen or StackBlitz to quickly generate a reproduction of the problem you’re facing.

For freeCodeCamp Lessons

Many of the questions I get on the freeCodeCamp Discord are regarding lessons in the learning platform (the curriculum). When asking a question about one of these lessons, make sure you include:

1. All the code from the editor panel (that is, all the code you have written or modified)

2. A link to the step

Without these two things, providing help gets dramatically harder.

Error Messages

When you’re a newer developer, error messages can be very intimidating. It’s understandable that you might skim over them as they don’t make sense and you’re not sure how to leverage them to solve your problem.

Reading your error messages carefully can be one of the first steps you take to becoming a stronger developer. But even if you don’t know what to make of the message, when seeking help, make sure you give others with experience in reading those messages the opportunity to do so. If there are any error messages in your console or terminal, copy/paste them in their entirety to your post asking for help.

Description of the Issue

When asking for help, you should consider that the person or people you’re asking might not have any context on your situation. It’s up to you to give them the context they need. To make sure you have given that context, include each of the following:

Steps to Reproduce the Issue

What, specifically, did you do that led you to encounter the problem you have? Be as detailed as possible here. Include things like, “I clicked the ‘Submit’ button,” or “I opened https://www.example.com in my browser.”

The Expected Result

Me: “My text is blue!”
My coworker: “That’s nice.”

My coworker wasn’t being dismissive of my problem. She just didn’t know whether it was a problem or not. Maybe I wanted the text to be blue. Maybe the blue text had nothing to do with my problem. Maybe the text only turns blue under certain circumstances.

If I had told my coworker that I expected the background to be blue rather than the text, she might have quickly realized what I did wrong and offered up a good suggestion on how to fix it.

The Actual result

Me: “I wanted my background to be blue!”
My coworker: “That’s nice.”

Forgetting to give the actual result is pretty much just as useless as forgetting to give the expected result. The expected and actual result of your code are both critical to a well-composed question.

When it comes to sharing actual results, screenshots or videos can be quite handy. Just make sure you’re not relying on them to the exclusion of the other components of a good question.

Example Question

Here’s an example of what putting all this guidance together might yield:

I'm on this step: https://www.freecodecamp.org/learn/javascript-algorithms-and-data-structures-v8/learn-introductory-javascript-by-building-a-pyramid-generator/step-33

I tried putting in this code:

for (iterator; condition; iteration) {

}

I expected it to pass, but instead, it gave me an error reading:

ReferenceError: iterator is not defined

Can anyone help me figure out what I'm doing wrong? Here’s a screenshot of the step and error:

The question isn’t long, but it contains all the elements of a quality question as described by this article. It gives the code that contains the problem (including a link to the freeCodeCamp step), the error message that is shown, and the expectations (that it should pass) and actual result (that an error message is shown). It even includes a helpful screenshot showing how the error and result are presented.

Closing Thoughts

This feels like a whole lot of effort. I just want my problem solved. Do I really need to do all of this???

Short answer? Yes. But only because it’s less effort than engaging in a prolonged back and forth as the people trying to help you attempt to get this information. Not just that, but if you go through these steps and collect this information, you might even find that you solve your problem yourself without needing to engage others.

This process might feel tedious at first, but like many things in life, if you practice it regularly then it becomes easier.

You’ve got this. 😎

I have known for a while now that most learners today don't share my love of big thick books, and to be honest, I rarely read those books in their entirety. Those big books often had a lot more exposition about the code than was probably needed. As a book buyer I wanted to make sure that I was getting my money's worth so the thicker they were, the better. It is much more common these days for learners to consume blog based tutorials and videos.

If you're learning to code right now, you've probably experienced the frustration of these formats too. I want to share something I've been working on that might help.

Blogs and Videos

Blog-style tutorials mix code and the explanation of it in a top-to-bottom fashion. Scrolling through these web-based explanations feels familiar and one can copy and paste with ease. However, linking the explanation of the code and the code itself has always been less than ideal. Often I find myself jumping around the blog post wishing I could see the entire code example while working through the explanation. Instead, I am only able to see small parts of the code and it is challenging to see how those parts relate to other parts.

Video tutorials are very popular these days. They solve some of the problems associated with blog-style tutorials. Videos are great because you get two streams of information: the author's audible narrative and the code being written. A viewer can focus on the two streams simultaneously. However, videos have some problems too.

Viewing Videos

From the perspective of the viewer, videos are hard to search through and are not useful as a copy and paste source or a code reference. More importantly, though, they discourage the viewer from taking their time and reflecting on the material. Often, when I am viewing a video tutorial I don't pause and let concepts sink in before the video moves on. Yes, I could be more disciplined and pause and rewind more often but usually I don't.

Making videos

From the perspective of the video creator, it is clear that not all code being developed is interesting to watch. Some of it is not really worth showing the viewer. Not all video creators can keep the narrative interesting the whole time.

I know I struggle with the 'performance' aspect of making videos (you won't find me coding on Twitch anytime soon). Many times after I am done making a video, as I review it, I wish I had mentioned something that I forgot. It is hard to go back and edit the video without scrapping it and starting over.

Storyteller

I have created a new medium to guide viewers through code examples. It combines the best of books, blog posts, and videos. This new medium allows a developer to write code using a top-notch editor (Visual Studio Code) and then replay the development of that code in the browser.

The author can add comments at important points in the evolution of the code. The comments can include text, hand drawn pictures, screenshots, and audio and video recordings. This allows the author to add visualizations that we have in our heads but don't make it into the code itself. The tool is called Storyteller.

Here are a few examples of a 'playback':

• Enlarging a Picture (Python)

• Dynamic Variables and Pointers (C++)

These work best on a big screen. If you are viewing a playback on a small screen you can view it in 'blog' mode (there is button in the top right to switch from 'code' mode to 'blog' mode).

I have created groups of these guided code walk-throughs to help me teach different topics to my students. These are all free and hosted on a website I created called Playback Press. Here are some of the 'books' I have created so far:

• An Animated Introduction to Programming in C++

• An Animated Introduction to Programming with Python

• An Introduction to Web Development from Back to Front

• An Animated Introduction to Clojure

• An Animated Introduction to Elixir

• Database Design and SQL for Beginners

• Mobile App Development with Dart and Flutter

• OO Design Patterns with Java

I usually assign these as readings in my classes instead of using expensive textbooks. It is a lot easier for me to write several programs than it is to find a perfect textbook.

I also use them for in-class demos instead of writing code live. This makes code demos flow much faster and smoother. If I make an interesting mistake while preparing the code I can still highlight it with a comment. If I make an uninteresting or embarrassing mistake I can just ignore it and the students won't focus on it.

The Advantages of Code Playbacks:

• The primary focus is on the code. It is always visible and easy to search and navigate.

• Since the code is so accessible, the explanation of it tends to be short and concise.

• The narrative can include whiteboard style drawings, screenshots, or videos of running code in addition to a text explanation.

• As an author, I can review the code several times and add/edit comments each time I go through it. I don't have to give a perfect performance like I do with a video.

• Comment points highlight when the author wants the viewer to take a moment to really think about the code and reflect on it. The playback only moves forward when the viewer is ready.

• The code mentioned in a comment can be highlighted so the viewer knows exactly where they should be looking.

• The code can be downloaded at any point in the playback. Then a viewer can run it, change it, and add to it.

• The tool is a language independent editor plug-in and can be used to describe programs in any language.

• Viewers only need a web browser to go through a playback.

Recently, I've been exploring how to make playbacks even more useful for learners.

AI as an Infinitely Patient Tutor

I have extended code playbacks to include an AI tutor. One thing I've learned in my years of teaching is that students often hesitate to ask questions. They worry about looking foolish, or they don't want to slow down the class, or they simply can't articulate what's confusing them.

What if every student had access to a patient tutor who never got frustrated with repeated questions and could explain concepts in multiple ways until something clicked?

I've integrated AI directly into the playback experience. As students work through a playback, they can ask questions about anything they're seeing. This might be a specific line of code, a concept I mentioned in a comment, or how something connects to material from earlier in the playback. The AI has full context. It can see the code, it understands where the student is in the playback, and it can provide explanations tailored to that exact moment. The AI is right there with the student, looking at the same code, understanding the same context.

The AI can also generate self-grading multiple choice questions based on the code and comments in a playback. These low-stakes quizzes make the learning experience more engaging and help learners check their understanding as they go.

Let me be clear: the AI doesn't replace me as an instructor. I still create the playbacks. I still decide what concepts to cover, what order to present them, and what examples best illustrate the ideas. The AI is an extension of my teaching, not a replacement for it.

Note: The AI features are available to registered users on Playback Press. Registration is free but logging in is required to access the AI tutor. If you want to see what this feels like, try one of the playbacks linked above and ask the AI a question about what you're seeing.

Conclusion

My goal has always been to help people learn to code. Books gave us depth but demanded commitment. Blogs gave us accessibility but fragmented the code. Videos gave us narrative but took away control. Playbacks keep the code front and center while letting learners move at their own pace and reflect when they need to. Adding AI doesn't change that philosophy, it just means there's always someone available to answer questions. Together, they get closer to the experience of having an expert sit beside you and walk you through a program. That's what I've been trying to build, and I think we're getting there.

Real world applications aren’t just about showing data on a screen. They solve real problems, work with real users, and handle situations that don’t always go as planned. This is where many developers struggle.

When I review junior developers’ résumés, I notice a common pattern: the projects section is often filled with beginner apps that look very similar. In today’s job market, this is usually not enough. Employers want to see that you can build something useful, something people would actually use.

The goal of this article is to help you move past simple Hello World projects like todo apps, calculators, and basic CRUD applications. By the end, you’ll understand how to approach building real applications that solve real problems and feel closer to what is built in the real world.

You might be wondering why you should listen to me.

Over the last 10 years, I’ve spent a lot of time building, breaking, and rebuilding software. I have experimented, failed many times, and eventually built applications that thousands of people use every day. A few weeks ago, I launched one of my own SaaS products and watched real users use it at scale, with over a thousand active users during peak hours, without the system crashing.

I’m sharing this because I’ve been where you are now.

If you continue reading, you will:

• Learn from real experience building applications used by real users

• Learn what not to do, based on years of mistakes and lessons

• Learn what actually works and what helps you stand out as a junior developer

• Clear up common misconceptions that slow people down

This article is not about theory. It’s about building real things.

To drive this point home, we’ll build a real world application that solves a real problem and is used by real people. Along the way, you’ll learn how to come up with real application ideas, how to build them with simple tools, and how to serve them to many users.

If this sounds like something you’re up for, then let’s get started.

Table of Contents

1. You Probably Think You Don’t Know Enough

2. How to Find Real World Application Ideas

3. What Are We Going to Build

4. Prerequisites

5. Step 1: Setting Up the Backend

6. Step 2: Adding Background Removal to the Backend

7. Step 3: Building the Frontend

   • Running and Testing the Application Locally

8. Step 4: Putting the Backend on the Internet

   • Deploying the Backend on Cloud Run

   • Updating the Frontend to Use the Live Backend

9. Step 5: Making the Backend and Frontend Work Together CORS

10. Step 6: Putting the Frontend on the Internet

11. Final Thoughts What You Just Built Matters

You Probably Think You Don't Know Enough

Before we begin, I want to clear up the most common misconception beginners have.

Many developers believe they don’t know enough to start building real world applications. They think they need to learn more JavaScript, more Python, or another framework before they are ready. Some even think learning React is the final step that will suddenly make everything click.

This belief is very common, but it’s not true.

If you know how to write HTML, CSS, and a simple loop or function in any programming language, you already have most of what it takes to build a real world application. This tutorial is proof of that.

That’s why I am writing this article. Not to tell you to learn more first, but to show you how far you can go with what you already know.

How to Find Real World Application Ideas

One question beginners ask a lot is, “What kind of apps should I build?”

This is rarely talked about, but it matters more than most people think.

A simple rule is this: build things that already exist.

Look at the apps you use every day, especially the simple ones. Tools that do one thing well. If you find yourself using an app often, that app is solving a real problem.

For example, people use background removers to clean up images. They use URL shorteners to share links. They use notes apps to save quick thoughts. None of these ideas are new, but they are real.

You don’t need to invent something original. You need to understand a problem and build a working solution for it.

When you replicate real tools, you naturally learn how real applications are structured. You also end up with projects that make sense on a résumé, because they solve problems people recognize.

That’s exactly what we are going to do in this tutorial.

What Are We Going to Build?

I’ll tell you now, it is not going to be another Hello World application. We’re going to be building a background remover web application.

This is the kind of tool people actually use. Designers use it for images, content creators use it for thumbnails, and developers build similar features into real products. It works with real files, real data, and real results.

If you want to see the final result before we start building, you can try the working app here: https://iamspruce.github.io/background-remover/

We’ll build this app using simple tools on purpose. Plain HTML, CSS, and JavaScript for the frontend, and Python for the backend. No heavy frameworks and no complicated setup.

Before we continue, let me clear up another common misconception.

Many developers believe that for an application to be taken seriously, it must be built with complex frameworks. In my experience building applications for clients around the world over the last 10 years, not a single client has ever asked me what framework I used.

They only cared about one thing: Did it work, and did it solve their problem?

Users won’t care how your app is built. They care that it works. If HTML, CSS, and JavaScript can solve the problem, there’s no reason to wait months just to learn a new framework.

Now that we understand why we’re building this app and what problem it solves, it’s time to start writing code.

Prerequisites

Before we start writing code, let’s quickly talk about what you need.

This tutorial is not for absolute beginners, but it’s also not super advanced. If you’ve built small things before and you want to build something that actually feels real, you’re in the right place.

What You Should Already Know

You should be comfortable with:

• Basic HTML: You know what inputs, buttons, images, and divs do.

• Basic CSS: You can style a page and make it look presentable.

• Basic JavaScript: You know how to listen for a button click and send a request using fetch.

That’s enough to follow along.

You don’t need React or any other frontend framework.

Backend Knowledge

For the backend, you don’t need to be a Python expert.

You just need to understand that:

• Python can run a server

• A server can receive requests

• A server can send back responses

Everything else will be explained as we go.

Tools You Need

Make sure you have these installed:

• Python 3.9 or newer

• Git

• A code editor like VS Code

• A browser

No Docker knowledge or cloud experience required.

GitHub Account (Important)

We’ll deploy the backend directly from GitHub, so you’ll need a GitHub account.

If you’ve never pushed a project to GitHub or hosted one before, I’ve already written a beginner-friendly guide you can follow first.

Read that article, then come back here.

A Quick Mindset Check

This is not a copy-paste tutorial. You will see real errors. Things may break. That’s normal. That’s how real applications are built.

Now that we’re clear on what you need, let’s start writing code.

We’ll begin with the backend. This is an important decision, so let’s explain it properly.

Step 1: Setting Up the Backend

What Is a Backend and Why Do We Need One?

A backend is a program that runs on a server and does the heavy work for an application.

In our case, the heavy work is image processing. Removing a background from an image requires libraries that can’t run inside the browser. Browsers are designed for safety and user interaction, not for this kind of processing.

That’s why we need a backend.

The backend will:

• Receive an image from the user

• Remove the background

• Send the processed image back

The frontend will simply talk to this backend later.

Keeping Things Simple on Purpose

Because this might be your first real project, we’re going to keep the backend as simple as possible.

• One programming language (Python)

• One backend file

• No complex folder structure

• No advanced concepts

This is intentional. Real world applications don’t have to start out complex. They typically start small and grow.

Project Structure

Create a new folder called:

background-remover

Inside it, create a folder for the backend:

background-remover/
  backend/

Move into the backend folder:

cd background-remover/backend

Now create a virtual environment:

python -m venv env

A virtual environment keeps this project’s dependencies separate from everything else on your computer. This is standard practice and something you’ll see in real projects.

Now activate it:

macOS or Linux:

source env/bin/activate

Windows:

env\Scripts\activate

Now create a folder for your application code:

mkdir api

Your structure should now look like this:

background-remover/
  backend/
    env/
    api/

At this stage, nothing looks impressive yet. That’s normal.

Installing FastAPI

We’ll use FastAPI to build the backend API.

Install it together with Uvicorn, which is the server that runs our app:

pip install fastapi uvicorn

FastAPI allows us to define endpoints clearly and with very little code, which is perfect for us.

Creating the First Backend File

Inside the api folder, create a file called main.py.

Add the following code:

from fastapi import FastAPI

app = FastAPI()

@app.get("/health")
def health():
    return {"status": "ok"}

Let’s pause and understand what this does.

• We created a FastAPI application

• We added a /health endpoint

• This endpoint simply returns a message

Before building real features, developers always confirm that their server actually runs. That is exactly what this endpoint is for.

Running the Server

From inside the backend folder, start the server:

uvicorn api.main:app --reload

Now open a new terminal and run:

curl http://localhost:8000/health

You should see:

{"status":"ok"}

This is an important moment.

You now have:

• A running backend server

• A real HTTP endpoint

• A response coming from your own code

This is how real backend services start.

Why We Did This First

At this point, you might wonder why we didn’t jump straight into background removal.

The reason is simple: if the server doesn’t run, nothing else matters.

By starting with a health endpoint, we removed uncertainty. We know the server works. Everything we add next is built on top of something we already know is working.

Now that the foundation is in place, we can move on to the real feature.

Step 2: Adding Background Removal to the Backend

Before we write any code here, we need to clear up an important misconception.

A Common Misconception About Machine Learning

When people hear “background removal,” they often think machine learning is too advanced for them.

In real world development, this is almost never how it works.

You aren’t expected to build machine learning models yourself. You use libraries created by others and focus on integrating them correctly.

That is exactly what we’re doing here.

Installing the Background Removal Library

Install the required packages:

pip install rembg pillow onnxruntime

• rembg handles the background removal

• pillow helps us work with images

For our purposes here, you don’t need to understand how these libraries work internally. You only need to know how to use them.

Adding the Background Removal Endpoint

Now update main.py so it looks like this:

from fastapi import FastAPI, UploadFile, File
from rembg import remove
from PIL import Image
import io

app = FastAPI()

@app.get("/health")
def health():
    return {"status": "ok"}

@app.post("/remove-bg")
async def remove_bg(file: UploadFile = File(...)):
    image_bytes = await file.read()
    image = Image.open(io.BytesIO(image_bytes))

    output = remove(image)

    buffer = io.BytesIO()
    output.save(buffer, format="PNG")
    buffer.seek(0)

    return buffer.getvalue()

Let’s explain this carefully.

• The endpoint accepts an uploaded image

• The image is read into memory

• The background is removed

• The result is saved as a PNG with transparency

• The image is returned to the client

This endpoint is the core of our application.

Testing the Endpoint With curl

Before building the frontend, we’ll test the backend directly.

Run this command:

curl -X POST \
  -F "file=@person.jpg" \
  http://localhost:8000/remove-bg \
  --output result.png

Open result.png. If you see the background removed, then the backend is complete.

At this point, you have built a backend that:

• Accepts real user input

• Processes real data

• Returns a meaningful result

This is a real backend.

Where We Are Now

Let’s pause and summarize:

• We set up a backend server

• We confirmed that it runs

• We added a real feature

• We tested it without a frontend

This is exactly how real developers work.

In the next section, we’ll build a simple frontend that talks to this backend and turns it into something users can interact with.

Step 3: Building the Frontend (What the User Actually Sees)

At this point, our backend is working.

It can receive an image, remove the background, and send the result back. But right now, only developers can use it, because it requires terminal commands.

To make this useful to actual (non-technical) people, we need a frontend.

The frontend is simply the part of the application users see and interact with in their browser.

Clearing a Common Misconception About Frontends

Many beginners think building a frontend means learning a framework first.

This is not true.

Frameworks help later, but they aren’t required to build real applications. Under the hood, every frontend still comes down to HTML, CSS, and JavaScript.

That’s why we are using plain HTML, CSS, and JavaScript here. No React, no build tools, no setup. Just the basics.

What Our Frontend Will Do

Our frontend has one job. It will:

• Let the user select an image

• Send that image to the backend

• Receive the processed image

• Show it on the screen

• Allow the user to download it

That’s all.

If it does these things correctly, it’s a real frontend.

Creating the Frontend

Go back to the root of your project and create three files:

index.html
styles.css
app.js

This simple setup is very common. Each file has a clear responsibility, which makes the code easier to understand.

Writing the HTML Page

Open index.html and add the following:

<!DOCTYPE html>
<html>
  <head>
    <title>Background Remover</title>
    <link rel="stylesheet" href="styles.css" />
  </head>
  <body>
    <h1>Background Remover</h1>

    <input type="file" id="imageInput" />
    <button id="removeBtn">Remove Background</button>

    <div class="result">
      <img id="resultImage" />
    </div>

    <a id="downloadLink" download>Download Image</a>

    <script src="app.js"></script>
  </body>
</html>

Right now, this page won’t do anything interesting. That’s expected.

HTML only describes what should be on the page. The behavior comes from JavaScript, which we’ll add after we add some styling.

Adding Some Basic Styling

Open styles.css and add this:

body {
  font-family: sans-serif;
  max-width: 600px;
  margin: 40px auto;
}

button {
  margin-top: 10px;
}

.result {
  margin-top: 20px;
}

img {
  max-width: 100%;
}

#downloadLink {
  display: none;
  margin-top: 10px;
}

This is not about making things look fancy.

The goal here is simply to make the page readable and pleasant to use. Many real internal tools look no better than this. (And you can always improve the styling later if you want.)

Connecting the Frontend to the Backend

Now we’ll write the JavaScript that makes everything work.

Open app.js and add the following code:

const imageInput = document.getElementById("imageInput");
const removeBtn = document.getElementById("removeBtn");
const resultImage = document.getElementById("resultImage");
const downloadLink = document.getElementById("downloadLink");

removeBtn.addEventListener("click", async () => {
  const file = imageInput.files[0];

  if (!file) {
    return;
  }

  const formData = new FormData();
  formData.append("file", file);

  const response = await fetch("http://localhost:8000/remove-bg", {
    method: "POST",
    body: formData,
  });

  const blob = await response.blob();
  const imageUrl = URL.createObjectURL(blob);

  resultImage.src = imageUrl;
  downloadLink.href = imageUrl;
  downloadLink.style.display = "inline";
});

Let’s slow down and explain what’s happening here:

• We read the image selected by the user

• We wrap it in FormData so it can be sent to the backend

• We send it to our /remove-bg endpoint

• We receive the processed image back

• We display it and prepare it for download

This is the moment where the frontend and backend finally talk to each other.

Running the Frontend With Live Server

Before testing, make sure your backend is still running.

Now, instead of opening index.html directly, use the Live Server extension in VS Code.

If you don’t have it installed, just open VS Code extensions, search for “Live Server”, and then install it. Then right click on index.html and click “Open with Live Server”.

This starts a small local server for the frontend.

Why does this matter?

Many browser features work better when files are served through a server instead of opened directly from the file system. Using Live Server also matches how real frontends are served.

Testing the Full Application Locally

Now choose an image and click the button.

If everything is working:

• The image is sent to the backend

• The background is removed

• The result appears on the page

• The download link shows up

Take a moment here. You have just built:

• A backend that processes real data

• A frontend that talks to it

• A complete application running locally

This is already more than a “Hello World” project.

Clearing One More Misconception

Some beginners look at this and think: “This feels too simple to be a real app.”

This is another misconception. Real applications aren’t defined by complexity. They’re defined by usefulness. If your app solves a real problem and people can use it, it’s a real application.

In the next section, we’ll take this exact app and put it on the internet so anyone can use it.

Step 4: Putting the Backend on the Internet

Right now, your backend is running on your computer.

That means:

• It works only for you

• If you close your laptop, it stops

• If someone opens your frontend, it cannot reach your backend

To fix this, we need to run the backend on a computer that is always online.

This process is called deployment.

A Simple Way to Think About Deployment

Deployment does not mean writing new code.

It simply means this: instead of running your backend on your laptop, you run it on another computer that never sleeps.

Everything we do next exists only to make that happen.

Why We Aren’t Using Netlify or Vercel

You might be wondering why we aren’t using Netlify or Vercel. Those platforms are great, but they’re mainly for frontends.

They work best when your app is:

• Static HTML, CSS, and JavaScript

• A frontend framework like React or Vue

• Small serverless functions

Our backend is different. It’s a Python server that:

• Stays running

• Accepts image uploads

• Processes images

• Uses heavy native libraries for background removal

This kind of backend needs a real server, not a lightweight serverless function.

That’s why Netlify and Vercel aren’t a good fit here.

Why We’re Using Cloud Run

Instead, we’re using Cloud Run.

Cloud Run lets us run real backend servers on Google’s infrastructure without managing servers ourselves.

We’re using it because:

• It supports full Python backends

• It deploys directly from GitHub

• It handles scaling and servers for us

• It works well with heavy workloads

• It’s beginner-friendly

Most importantly, it lets you deploy a real backend without learning cloud commands or CI/CD pipelines.

Preparing the Backend for Cloud Run

Before deploying, we need to make sure our backend is ready.

Creating requirements.txt

Inside the backend folder, create a file called requirements.txt.

Add this:

fastapi
uvicorn
rembg
pillow
onnxruntime

This file tells Cloud Run which Python libraries to install.

Creating a GitHub Repository

Cloud Run deploys directly from GitHub, so our code must live there.

From the project root, run:

git init
git add .
git commit -m "Initial background remover project"
git branch -M main
git remote add origin YOUR_REPO_URL
git push -u origin main

This single repository will be used for both backend and frontend.

Deploying the Backend on Cloud Run

Now open your browser and go to Google Cloud Console.

1. Create a New Project

Open Google Cloud Console and click New Project. Give it a name (for example: background-remover) and then click Create.

2. Open Cloud Run

Use the search bar at the top and search for Cloud Run. Then open it.

Cloud Run will automatically enable the required APIs.

You will be asked to set up billing. Google gives you $300 free credit, which is more than enough for this tutorial.

3. Start Creating the Service

Click Create Service and choose Deploy continuously from a repository.

4. Connect Your GitHub Account

Select GitHub as the repository provider and authenticate your GitHub account. Then install Google Cloud Build on your GitHub account. Choose only the repository you want to deploy.

This allows Google Cloud to build and deploy your code automatically.

5. Select the Repository

Then choose the repository you just installed Cloud Build on and select the main branch.

6. Configure the Build

Now comes the important part: building the context directory.

Set this to:

backend

This tells Cloud Run:

“My backend code lives inside the backend folder.”

For the entry command, enter:

uvicorn api.main:app --host 0.0.0.0 --port 8080

This is how Cloud Run starts your FastAPI server.

7. Configure Container Resources

Our backend runs a background-removal model, which is heavy.

So we must increase resources.

• Change memory from 512 MB → 2 GB

• Set CPU to 4

This ensures the model can load and run properly.

8. Deploy

Now click Create.

Cloud Run will:

• Build your app

• Install dependencies

• Create a container

• Deploy it to the internet

You’ll see logs showing the build and deployment process.

This can take a few minutes. That’s normal.

Checking That the Backend Is Live

Once deployment finishes, Cloud Run will show you a public URL.

Test it:

curl https://YOUR_CLOUD_RUN_URL/health

If you see:

{"status":"ok"}

Your backend is officially live on the internet.

Pause here for a second.

You just deployed a real backend. Congratulations.

Updating the Frontend to Use the Live Backend

Open app.js.

Replace:

http://localhost:8000/remove-bg

With:

https://YOUR_CLOUD_RUN_URL/remove-bg

Save the file and reload the frontend.

Step 5: Making the Backend and Frontend Work Together

At this point, we have two things:

• A backend running on the internet

• A frontend running in the browser

Now we want them to talk to each other.

Open your frontend, select an image, and click the button. You’ll notice that it still doesn’t work. This is expected.

What Is Happening Here?

Your frontend is running on one address, while your backend is running on another address.

Browsers are very strict about this. By default, a browser will block requests from one website to another unless the backend explicitly allows it. This is a security feature.

This rule is called CORS.

Clearing a Common Misconception About CORS

When beginners see a CORS error, they often think something is broken.

Nothing is broken. CORS is simply the browser saying: “I need the backend to confirm that this frontend is allowed to talk to it.”

So all we need to do is tell the backend: “It’s okay for requests to come from my frontend.”

Allowing Only Our Frontend (Not Everyone)

Instead of allowing requests from everywhere, we’ll allow requests only from our frontend. This is a good habit to learn early.

Open backend/api/main.py.

Add this import at the top:

from fastapi.middleware.cors import CORSMiddleware

Then, after creating the FastAPI app, add this:

app.add_middleware(
    CORSMiddleware,
    allow_origins=[
        "http://127.0.0.1:5500",
        "http://localhost:5500"
    ],
    allow_methods=["POST"],
    allow_headers=["*"],
)

Why these URLs?

If you’re using the Live Server extension, your frontend is usually served on port 5500. These are the addresses your browser is using locally.

We’re telling the backend: “Only accept requests from this frontend.”

That is exactly what we want.

Redeploying the Backend

Any time you change backend code, you need to redeploy it.

Since our backend is deployed on Cloud Run and set up with automatic deploy, redeploying is simple, all you need to do is push your changes.

From the project root, run:

git add .
git commit -m "Add CORS configuration"
git push

Cloud Run will automatically detect the change and redeploy your backend.

Wait for the deployment to finish. Once it’s done, your backend will now allow requests from your local frontend.

Testing Again

Reload your frontend in the browser.

Select an image and click the button. This time, it should work.

You just handled a real browser security rule that every production app runs into. That alone is a huge learning step.

Step 6: Putting the Frontend on the Internet (GitHub Pages)

Right now, your frontend works only on your computer.

Just like the backend earlier, this means no one else can use it.

Let’s fix that.

Why GitHub Pages?

Our frontend is:

• Just HTML, CSS, and JavaScript

• No backend code

• No build step

This makes it perfect for GitHub Pages. GitHub Pages can host static sites for free, and it’s very beginner friendly.

Preparing the Frontend for Deployment

Make sure all your frontend files are inside the frontend folder:

frontend/
  index.html
  styles.css
  app.js

Open app.js and make sure the backend URL is the Cloud Run URL, not localhost.

fetch("https://YOUR_CLOUD_RUN_URL/remove-bg", {
  method: "POST",
  body: formData,
});

Save the file.

Pushing the Frontend to GitHub

We already created a GitHub repository earlier, so we’ll reuse it.

From the project root, run:

git add .
git commit -m "Add frontend and prepare for GitHub Pages"
git push

Enabling GitHub Pages

1. Go to your repository on GitHub.

2. Open Settings.

3. Click Pages.

Under Source, select:

1. Branch: main

2. Folder: /(root)

Save everything. After a few seconds, GitHub will give you a URL. This URL is now your frontend on the internet.

Updating CORS for the Live Frontend

Now that the frontend is live, go back to backend/api/main.py.

Replace the local origins with your GitHub Pages URL:

allow_origins=[
    "https://YOUR_GITHUB_USERNAME.github.io"
]

Commit and push the change:

git add .
git commit -m "Update CORS for GitHub Pages"
git push

Cloud Run will redeploy the backend automatically.

Final Test

Open your GitHub Pages URL.

Upload an image, remove the background, and download the result.

Everything is now live.

Where You Are Now

Let’s be very clear about what you just did.

You:

• Built a real backend

• Deployed it to the internet

• Built a frontend

• Deployed it to the internet

• Fixed real production issues

• Connected everything properly

This is not a demo project. This is a real application.

In the final section, we’ll wrap things up, talk about what you learned, and where you can go next.

Final Thoughts: What You Just Built Matters

At this point, it is worth stopping and looking back at what you have actually done.

You didn’t just follow steps. You didn’t just copy code. You built a real application.

Let’s Be Clear About What You Accomplished

You started with nothing more than basic tools and ideas.

By the end of this tutorial, you:

• Built a backend that processes real data

• Used a machine learning tool without fear or overthinking

• Exposed a backend to the internet

• Built a frontend with plain HTML, CSS, and JavaScript

• Connected the frontend and backend properly

• Deployed both parts so real users can access them

This is exactly how real applications are built, just at a smaller and more manageable scale.

Why This Is No Longer a “Beginner Project”

Many projects are called beginner projects, but they stop at showing things on a screen.

This one does not.

Your app:

• Accepts real input

• Performs real work

• Runs on real servers

• Handles real browser rules

• Can be shared with anyone

That is the difference between learning syntax and building software.

The Most Important Lesson in This Tutorial

The most important thing you should take away from this is not the project you built.

It is this: You didn’t need to “know more” before you started.

You learned by building. You figured things out as they appeared. You fixed problems when they showed up.

That is how experience is gained. No one has experience before building real applications. No one lacks experience after building many of them.

What You Can Do Next

This project isn’t the end. It’s a starting point.

Here are a few ideas you can explore next, using what you already know:

• Improve the user interface

• Add loading states and better feedback

• Restrict image size or file types

• Add simple rate limiting

• Build another small tool that solves a real problem

You don’t need to jump to frameworks yet.

If you can build a few more projects like this, frameworks will make a lot more sense when you meet them.

One Last Thought

If this was your first real project, you should be proud of yourself.

You moved past tutorials, built something useful, and put it on the internet. That’s the line many developers never cross.

Now that you have crossed it, the next one will be easier.

So keep building!

Source Code and Live Demo

If you want to explore the full project or build on top of it, you can find everything here.

• Live application: https://iamspruce.github.io/background-remover/

• GitHub repository: https://github.com/iamspruce/background-remover

If you have questions, reach me on X at @sprucekhalifa. I write practical tech articles like this regularly.

But learning React can feel overwhelming. With so many new terms, patterns, and frameworks like Next.js in the mix, it’s easy to feel lost.

That’s why this handbook focuses on React itself without unnecessary distractions. Once you’ve mastered React at its core, you’ll have the confidence to use it with or without frameworks to build anything you can imagine.

Table of Contents

1. What You Should Already Know

2. What Exactly Is React?

   • Why the “React” name?

   • Is React a framework?

   • Is React only for web development?

   • What’s the primary goal of React?

3. How to Add a React Component to a Website

   • Create a new project directory

   • Create a DOM container

   • Import React, Babel, and your component

   • Create your component

   • Configure a local server

4. What Is JSX?

   • Can React work without JSX?

   • Example 1: Create a React element with JSX

   • Example 2: Create a React element with regular JavaScript

5. What Is React.createElement()?

6. How to Use JSX

   • Use JSX like any JavaScript expression

   • Wrap multi-line JSX in parentheses

   • Wrap expressions in curly braces

   • Use camelCase to name attributes

   • Close empty JSX tags properly

   • A React component can return only a single element

7. Time to Practice with JSX 🤸‍♂️🏋️‍♀️🏊‍♀️

   • The solution

8. What Is a React Component?

   • Syntax of a React component

   • Example of a React component

   • React components best practices

9. How to Render Lists of Elements from an Array

   • Each React element in an array needs a unique key

   • How to add unique keys to each React element in an array

   • Essential things to know about assigning keys

10. How to Handle Events in React

    • Types of event handlers

    • Example: Inline event handler

    • Example: Referenced event handler

11. What Is React State?

    • Syntax of React state

    • Example of React state

    • React trigger vs render vs commit vs paint

    • What does it mean to trigger a render in React?

    • What does it mean to render React components?

    • What does it mean to commit a React UI to the browser’s DOM?

    • What does it mean to paint the DOM nodes on the screen?

12. What Is the React Ref Hook?

    • Syntax of the React ref Hook

    • Example of the React ref Hook

    • React ref Hook best practices

13. Variables vs Refs vs States in React

    • How do variables work in React?

    • How do refs work in React?

    • How do states work in React?

    • Tips on using variables, refs, and states in React

14. What Is the useEffect Hook?

    • Syntax of the useEffect Hook

    • Example of the useEffect Hook

    • useEffect Hook’s best practices

15. How to Style React Components

    • How to use CSS style sheets to style React elements

    • How to use the inline style attribute to style React elements

    • How to use CSS Modules to style React elements

    • How to use a CSS-in-JS library to style React elements

16. Overview

    • Dive deeper into React

What You Should Already Know

You will get the most value out of this handbook if you are familiar with:

• JavaScript fundamentals (variables, functions, arrays, objects)

• Basic CSS for styling

• HTML basics for structure

If you’ve ever written a small JavaScript file or built a simple “Hello World” website, you are all set!

Let’s get started with the basics.

What Exactly Is React?

React is a component-based JavaScript library for efficiently building user interfaces (UI).

No matter how massive or miniature your project may be, React is well-suited to help you develop any web application efficiently.

Developers primarily use React to build independent, reusable components that can be combined with other isolated user interfaces to create highly scalable applications. For instance, the image below illustrates the individual components of YouTube’s video player page.

In other words, React helps you build complex UIs from small, isolated components that can easily be reused in multiple applications. Each independent component tells React the exact element you want to display on screen.

The image above illustrates React as a highly adaptable library that uses JavaScript functions to build user interfaces for both mobile and web-based applications. Let’s discuss the points highlighted in the image.

Why the “React” name?

The name stems from the idea that React renders your UI and reacts to events in the user interface it has rendered on screen.

Is React a framework?

No, React is a library—not a framework. React serves only as an add-on feature to your application. It’s not designed to be used as an app’s primary support system.

Is React only for web development?

No, you don’t just use React on the web. For instance, ReactDOM helps build web applications, and React Native helps build mobile applications.

Can React be used for full-stack applications?

Absolutely. React is super flexible. You can use it in simple HTML projects, integrate it into existing code, or build complex full-stack applications. Its adaptability makes it suitable for a wide variety of development scenarios.

What’s the primary goal of React?

React’s primary goal is for you to use JavaScript functions to return and manage the UI (HTML element) you want to render (display) on the screen. For instance, consider the following:

function DonationUserInterface() {
  return <button>☕ Buy me a coffee</button>;
}

The JavaScript function above is a React component that returns the UI (HTML button element) we want to display on screen and manage with React. In fact, let’s implement the DonationUserInterface component on a live website using only HTML and JavaScript – no frameworks.

How to Add a React Component to a Website

Follow the steps below to add a donation UI component to a live HTML website.

Create a new project directory

mkdir codesweetly-donation-ui-001

Note: You can use any name you prefer. In this guide, we’ll use codesweetly-donation-ui-001 for demonstration.

Afterward, navigate to your project directory using the command line.

cd path/to/codesweetly-donation-ui-001

Create a DOM container

To add a React component to a webpage, you first need to specify the section of the page where you want to insert the UI. So, create an HTML page:

touch index.html

Afterward, open the new file and add the following code:

<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>CodeSweetly Donation UI</title>
  </head>
  <body>
    <!-- A div container (the DOM node) created for React to manage -->
    <div id="donation-ui"></div>
  </body>
</html>

The snippet above created a DOM node (<div> element), inside which we want React to display and manage a donation user interface. In other words, the <div> represents the website’s section you want React to manage.

Some notes:

• The div’s id attribute is the reference we’ll later use in a JavaScript file to find the container and tell React to insert a donation UI.

• Although most developers use a <div> tag as the DOM container, you can use other HTML elements like the <main> tag.

• You can have multiple DOM containers anywhere inside the <body> element.

• A DOM container is usually left empty, as React will overwrite its content.

Import React, Babel, and your component

Use script tags to load React, Babel, and your component into your project’s HTML page.

<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>CodeSweetly Donation UI</title>
    <!-- Load the React Library -->
    <script src="https://unpkg.com/react@18/umd/react.development.js"></script>
    <!-- Load the ReactDOM API -->
    <script src="https://unpkg.com/react-dom@18/umd/react-dom.development.js"></script>
    <!-- Load the Babel Compiler -->
    <script src="https://unpkg.com/@babel/standalone/babel.min.js"></script>
  </head>
  <body>
    <div id="donation-ui"></div>
    <!-- Load your React component -->
    <script type="text/babel" src="DonationUserInterface.js"></script>
  </body>
</html>

The snippet above uses the first three script tags to load React, ReactDOM, and Babel from unpkg.com.

At the same time, we use the fourth script tag to import our donation component (which we will create in the following section).

Some notes:

• The react package is a library containing React’s core functionality for creating React components.

• The ReactDOM API provides the required methods to use React with the DOM.

• Babel is a compiler that transforms React code into plain JavaScript, as browsers don’t understand React syntax by default.

• The type="text/babel" attribute tells Babel to automatically execute and convert the DonationUserInterface.js script from React code into plain JavaScript.

• The setup above is recommended for learning React only. Don’t use it for public projects (production environment). You can learn how to set up React for production in my Code React Sweetly book.

• The scripts will not work if your internet or unpkg.com’s server is down. So, if nothing renders on-screen, enter each script’s src URL in your browser to confirm if the server responds successfully.

Create your component

Create a DonationUserInterface.js JavaScript file inside the same folder in which your HTML file is located.

touch DonationUserInterface.js

Then, paste the following code inside the JavaScript file you’ve just created:

function DonationUserInterface() {
  const [donate, setDonate] = React.useState(false);

  function createUserInterface() {
    if (donate) {
      return (
        <p>
          <a href="https://www.buymeacoffee.com/codesweetly">Support page</a>.
          Thank you so much! 🎉
        </p>
      );
    }
    return <button onClick={() => setDonate(true)}>☕ Buy me a coffee</button>;
  }
  return createUserInterface();
}

const root = ReactDOM.createRoot(document.getElementById("donation-ui"));
root.render(<DonationUserInterface />);

The snippet above does the following:

1. Defines a component named DonationUserInterface.

2. Initializes the component’s state (built-in object) with the Boolean value false.

3. Programs the component to return a paragraph element if the state’s donate variable is true. Otherwise, it should return a button element.

4. Creates a ReactDOMRoot object instance for the donation-ui HTML element you want React to manage. Afterwards, it assigns the newly created instance to the root variable.

5. Uses the object instance’s render() method to display the DonationUserInterface component inside the root donation-ui.

Configure a local server

HTML files containing ES modules work only through http:// and https:// URLs, not locally via a file:// URL.

Since we previously used the type="text/babel" attribute to convert the DonationUserInterface.js JavaScript file to an ES module, we need a local server, like “Live Server” or “Servor,” to load the HTML document via an http:// scheme. Let’s install Servor so we can use it for this project.

Install the Servor local server

npm install servor@4.0.2 --save-dev

Run your app

After installing Servor, use it to start your app from your terminal:

npx servor --browse --reload

Some notes:

• Close the server using Ctrl + C on Windows or Cmd + C on Mac.

• --browse: Opens the browser once the server starts.

• --reload: Reloads the browser whenever you update the project’s files.

• You can also add the servor command to the "scripts" field of your project’s package.json file:

{
  "scripts": {
    "start": "servor --browse --reload"
  },
  "devDependencies": {
    "servor": "^4.0.2"
  }
}

By doing so, you can run your app from your terminal like this:

npm run start

And that’s it! You’ve successfully added a React component to a live website using a JavaScript function to render a donation UI on screen! 🎉

Are you asking why we’re writing HTML inside JavaScript? Well, that HTML-like code is called JSX. Let’s learn about it.

What Is JSX?

JSX is a JavaScript syntax extension that allows you to build React elements with HTML-like syntax directly inside your JavaScript code.

Tips:

• JSX is sometimes called JavaScript XML or JavaScript Syntax eXtension.

• While JSX looks a lot like HTML, it’s not HTML. Instead, it enables you to use HTML-like syntax along with all the strengths of JavaScript.

Can React work without JSX?

Yes. React can work independently of JSX. But JSX makes it easier to create user interfaces (UI).

In other words, whatever you can do with JSX, you can do the same with plain JavaScript. For instance, consider the two examples below. The first includes JSX syntax, while the second is regular JavaScript syntax.

Example 1: Create a React element with JSX

MyBio.js

function MyBio() {
  return <h1>My name is Oluwatobi.</h1>;
}
const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<MyBio />);

index.html

<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>MyBio App</title>
    <script src="https://unpkg.com/react@18/umd/react.development.js"></script>
    <script src="https://unpkg.com/react-dom@18/umd/react-dom.development.js"></script>
    <script src="https://unpkg.com/@babel/standalone/babel.min.js"></script>
  </head>
  <body>
    <div id="root"></div>
    <script type="text/babel" src="MyBio.js"></script>
  </body>
</html>

In the React snippet above, <h1>My name is Oluwatobi.</h1> and <MyBio /> are JSX.

Tip: React supports the .jsx file extension for files with JSX code. So, if you prefer to differentiate your JSX files from JavaScript, you can rename MyBio.js to MyBio.jsx. Just note that choosing between using .js vs .jsx for files with JSX is entirely up to you. (Your JSX code is simply a syntactic sugar for the React.createElement() JavaScript call.)

Example 2: Create a React element with regular JavaScript

MyBio.js

function MyBio() {
  return React.createElement("h1", null, "My name is Oluwatobi.");
}
const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(React.createElement(MyBio));

index.html

<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>MyBio App</title>
    <script src="https://unpkg.com/react@18/umd/react.development.js"></script>
    <script src="https://unpkg.com/react-dom@18/umd/react-dom.development.js"></script>
    <script src="https://unpkg.com/@babel/standalone/babel.min.js"></script>
  </head>
  <body>
    <div id="root"></div>
    <script type="text/babel" src="MyBio.js"></script>
  </body>
</html>

Everything in the React snippet above is plain JavaScript code.

What Is React.createElement()?

React.createElement() is the JavaScript alternative to JSX. It is a method for creating React elements in regular JavaScript.

Browsers can’t read the JSX syntax. This is why we typically use tools like Babel, TypeScript, and Parcel to compile JSX to a React.createElement(component, props, ...children) JavaScript call.

For instance, <button className="support-btn">Buy me a coffee</button> will transform to React.createElement("button", { className: "support-btn" }, "Buy me a coffee ") at runtime.

Under the hood, the React.createElement() method creates a JavaScript object conventionally called “React element.”

Tip: A React element is a JavaScript object that defines the user interface (UI) you want to render on screen.

A simplified version of a React element looks like this:

const myBioReactElement = {
  type: "h1",
  props: {
    className: null,
    children: "My name is Oluwatobi.",
  },
};

React.createElement() is best for projects that want to avoid compiling tools like Babel. Whereas JSX is a syntactic sugar that makes React code easier to read. So, you are free to choose the syntax that works best for you (but most React projects use JSX for its simplicity).

How to Use JSX

The following tips will help you get up and running with JSX so you can use it in your React projects.

Use JSX like any JavaScript expression

You can use JSX like any other JavaScript expression because, at execution time, JSX transpiles into regular JavaScript.

In other words, you can store JSX expressions in variables, use them in if statements, or make them the return value of functions.

Example:

DisplayMyName.js

const firstName = false;
const myFirstName = <h1>My first name is Oluwatobi.</h1>;
const mylastName = <h1>My last name is Sofela.</h1>;
function DisplayMyName() {
  if (firstName) {
    return myFirstName;
  } else {
    return mylastName;
  }
}
const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<DisplayMyName />);

index.html

<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>DisplayMyName App</title>
    <script src="https://unpkg.com/react@18/umd/react.development.js"></script>
    <script src="https://unpkg.com/react-dom@18/umd/react-dom.development.js"></script>
    <script src="https://unpkg.com/@babel/standalone/babel.min.js"></script>
  </head>
  <body>
    <div id="root"></div>
    <script type="text/babel" src="DisplayMyName.js"></script>
  </body>
</html>

The React snippet above stores JSX code in variables. We also made it the return value of a function’s if...else statement.

Wrap multi-line JSX in parentheses

Wrapping your JSX code in parentheses is best when it spans across multiple lines. Doing so will make your code readable and avoid the pitfalls of automatic semicolon insertion.

const myName = (
  <div>
    <h1>My name is Oluwatobi.</h1>
  </div>
);

The snippet above wraps the div in parentheses because it spans multiple lines.

Wrap expressions in curly braces

Suppose you wish to write JavaScript expressions in your JSX code. In that case, wrap the expression in curly braces like so:

ExpressionInJSX.js

function ExpressionInJSX() {
  return <h2>JSX makes it {10 * 3} times faster to build React UIs.</h2>;
}
const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<ExpressionInJSX />);

index.html

<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>ExpressionInJSX App</title>
    <script src="https://unpkg.com/react@18/umd/react.development.js"></script>
    <script src="https://unpkg.com/react-dom@18/umd/react-dom.development.js"></script>
    <script src="https://unpkg.com/@babel/standalone/babel.min.js"></script>
  </head>
  <body>
    <div id="root"></div>
    <script type="text/babel" src="ExpressionInJSX.js"></script>
  </body>
</html>

Tips:

• React reads curly braces ({...}) in JSX code as a JavaScript expression.

• Using curly braces to embed a JavaScript expression works only if you use it in either of two ways:

  1. Directly between the opening and closing JSX tags:

      <openingTag>I have a {javaScriptExpression} content.</closingTag>
     

  2. As the value of a JSX element’s attribute:

      <openingTag attribute={javaScriptExpression}>I have a content</closingTag>
     

Use camelCase to name attributes

React uses camelCase for JSX attribute keys rather than the lowercase HTML attribute naming convention. This is because, under the hood, JSX compiles into plain JavaScript and, therefore, uses the JavaScript Web APIs.

In other words, instead of writing readonly, use readOnly. Likewise, instead of using maxlength, write maxLength. By doing so, React will gain access to JavaScript’s readOnly and maxLength Web APIs.

Example:

const myName = (
  <div>
    <h1 className="about-me">My name is Oluwatobi.</h1>
  </div>
);

Close empty JSX tags properly

React requires closing all JSX elements explicitly with />, including empty tags. For instance, you’ll need to write an HTML <img> element as <img />.

Example:

const emptyJSXElement = <input type="button" value="Click me" />;

A React component can return only a single element

Creating two or more JSX elements from a component requires wrapping them in a single parent element. Otherwise, React will throw an error. This is because React components return only a single element.

Example:

TwoInnerUIs.js

function TwoInnerUIs() {
  return (
    <div>
      <h1>My name is Oluwatobi.</h1>
      <button>Buy me a coffee</button>
    </div>
  );
}
const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<TwoInnerUIs />);

index.html

<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>TwoInnerUIs App</title>
    <script src="https://unpkg.com/react@18/umd/react.development.js"></script>
    <script src="https://unpkg.com/react-dom@18/umd/react-dom.development.js"></script>
    <script src="https://unpkg.com/@babel/standalone/babel.min.js"></script>
  </head>
  <body>
    <div id="root"></div>
    <script type="text/babel" src="TwoInnerUIs.js"></script>
  </body>
</html>

In the expression above, the <div> is a parent element containing two (2) inner tags.

Tip: React allows using a fragment (empty tag) to group elements. Here’s an example:

function TwoInnerUIs() {
  return (
    <>
      <h1>My name is Oluwatobi.</h1>
      <button>Buy me a coffee</button>
    </>
  );
}
const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<TwoInnerUIs />);

Fragments are a great way to return multiple elements without creating unnecessary tags in the HTML DOM.

Time to Practice with JSX 🤸‍♂️🏋️‍♀️🏊‍♀️

Here is your moment to practice the JSX concepts you’ve learned.

In this exercise, you will convert the regular JavaScript code below to its JSX equivalent:

function SupportCodeSweetly() {
  return React.createElement(
    "div",
    { className: "support-ui" },
    React.createElement(
      "a",
      {
        id: "support-link",
        className: "support-link",
        target: "_blank",
        href: "https://www.buymeacoffee.com/codesweetly",
      },
      "Buy me a coffee"
    ),
    ". Thank you!"
  );
}

const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(React.createElement(SupportCodeSweetly));

Take a moment to try it yourself before looking at the solution below. Even if you have to try a couple times, go back and read the above tips, or google a few things, it’ll help you learn the concepts better.

Ok, now that you’ve tried…

The solution:

function SupportCodeSweetly() {
  return (
    <div className="support-ui">
      <a
        id="support-link"
        className="support-link"
        target="_blank"
        href="https://www.buymeacoffee.com/codesweetly"
      >
        Buy me a coffee
      </a>
      . Thank you!
    </div>
  );
}

const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<SupportCodeSweetly />);

The SupportCodeSweetly component returns the UI we want to display on-screen and manage with React. But what exactly is a React component?

What Is a React Component?

A component in React is a class or function that accepts a single argument called props and returns an element (UI).

Syntax of a React component

The above image illustrates the constituent parts of a React component:

1. A JavaScript function with a Pascal case naming convention.

2. A props parameter, which is the only argument React components accept. (Tip: props is short for properties.)

3. The component’s body, where you place a sequence of statements like variables, hooks, and conditionals.

4. A return statement, which is used to output the user interface (UI) you want React to display on-screen. It can be any valid HTML element.

5. An invocator that executes the component to retrieve its user interface. The invocator can also pass arguments (props) to the component.

Example of a React component

function MyBio(props) {
  return <h1>My name is {props.firstName}.</h1>;
}

Try it on CodeSandbox

The code in the snippet above is a function component that accepts a single argument (props) and returns a React element.

React components best practices

When you’re working with components in React, there are a few best practices you should follow:

• Capitalize the first letter of your component’s name.

• Don’t use bracket notation expressions in React component tags.

• React components work best as pure functions.

• Create components at the top level of your file.

• Split long components into smaller chunks.

As it’s common practice to use components to render a list of elements, let’s now discuss how to implement this optimally.

How to Render Lists of Elements from an Array

Suppose you want to create a list of React elements from an array of data. You can use the JavaScript map() method.

Example:

import ReactDOM from "react-dom/client";

// Define the bestColors array:
const bestColors = ["Blue", "White", "Pink"];

// Use the bestColors array to create a list of React elements:
const bestColorsLiElements = bestColors.map((color) => <li>{color}</li>);

// Render the array of <li> elements to the root DOM:
const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<ul>{bestColorsLiElements}</ul>);

Try it on CodeSandbox

The snippet above used map() to create a new list of React elements by converting each of bestColors items to <li> elements.

Notice that we rendered the list of elements directly in the root.render() method. Typically, you would use a component to do such rendering. So, let’s do some refactoring by moving the bestColorsLiElements variable and the <ul> element into a component:

import ReactDOM from "react-dom/client";

function BestColor() {
  // Define the bestColors array:
  const bestColors = ["Blue", "White", "Pink"];
  // Use the bestColors array to create a list of React elements:
  const bestColorsLiElements = bestColors.map((color) => <li>{color}</li>);
  return <ul>{bestColorsLiElements}</ul>;
}

// Render the array of <li> elements to the root DOM:
const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<BestColor />);

Try it on CodeSandbox

Although the snippet above displays the right content on the screen, it’s not efficient. So, React throws a console error. Let’s discuss the issue.

Each React element in an array needs a unique key

If you check your console, you will see a warning message that says: Each child in a list should have a unique "key" prop.

The message means that whenever you create an array of elements, React needs you to specify a unique identity for each item in the list.

The unique identity keys help React identify changes to the array.

Let’s refactor the previous snippet so that each element in the bestColorsLiElements has a unique key prop.

How to add unique keys to each React element in an array

There are two common ways to assign unique keys to each element of an array. The first is the unrecommended way. While the second is the best technique, it is worth noting.

Not recommended way to assign keys to an array of React elements

One way to add unique keys is to use each item’s index as its key prop.

Tip: By default, if you don’t provide a key prop, React uses each element’s index position in the array to identify them (key=0, key=1, and so on).

Example:

import ReactDOM from "react-dom/client";

function BestColor() {
  const bestColors = ["Blue", "White", "Pink"];
  // Use each item's index as its key prop:
  const bestColorsLiElements = bestColors.map((color, index) => (
    <li key={index}>{color}</li>
  ));
  return <ul>{bestColorsLiElements}</ul>;
}

const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<BestColor />);

Try it on CodeSandbox

The snippet above specifies a key prop on each <li> element. It then uses each item’s index as the prop’s value.

But note that it’s best to avoid using indexes as a React element’s key prop. You should use it only as a last resort when you don’t have stable IDs.

Whenever you use an index as the key prop, ensure the order of items in the array never changes. Otherwise, you may have severe issues with performance and component state.

Best way to assign keys to an array of React elements

The best way to add unique keys to each React element in an array is to use stable IDs from either of the following sources:

• Database: Use the database-generated IDs as the key props if your data comes from a database, as they are unique by default.

• crypto.randomUUID() incrementing counter: Use the randomUUID() method to generate Universally Unique Identifiers if you are creating and storing your data locally. (Note: This method is a web API. So, it’s available only in supporting browsers’ HTTPS contexts.)

• uuid: An NPM package for generating Universally Unique Identifiers if you are creating and persisting your data locally. This is a good alternative to the randomUUID() method for cross-platform compatibility.

Example:

index.js

import { createRoot } from "react-dom/client";
import { bestColors } from "./bestColors.js";

function BestColor() {
  // Use each item's id as its key prop:
  const bestColorsLiElements = bestColors.map((color) => (
    <li key={color.id}>{color.name}</li>
  ));
  return <ul>{bestColorsLiElements}</ul>;
}

const root = createRoot(document.getElementById("root"));
root.render(<BestColor />);

bestColors.js

export const bestColors = [
  { id: crypto.randomUUID(), name: "Blue" },
  { id: crypto.randomUUID(), name: "White" },
  { id: crypto.randomUUID(), name: "Pink" },
];

Try it on CodeSandbox

The snippet above specifies a key prop on each <li> element. It then uses each item’s id as the prop’s value.

Note: Each key prop should be unique among its siblings – not globally. It’s okay to use the same key for an element in a different array.

Essential things to know about assigning keys

Here are essential facts to remember whenever you assign keys to an array of React elements.

1. Set each array element’s key while creating the array

The right place to specify each array element’s unique key is directly inside the map() method while creating the list of elements.

In other words, say you extract your template element into a separate component. Set the key prop on the component’s invocation tag—not on the extracted template element.

Example 1: Incorrect placement of the key prop

index.js

import { createRoot } from "react-dom/client";
import { bestColors } from "./bestColors.js";

function ColorListElement({ color }) {
  // WRONG: Don't place the key outside the map() method.
  return <li key={color.id}>{color.name}</li>;
}

function BestColor() {
  const bestColorsLiElements = bestColors.map((color) => (
    // The key attribute above should have been set here.
    <ColorListElement color={color} />
  ));
  return <ul>{bestColorsLiElements}</ul>;
}

const root = createRoot(document.getElementById("root"));
root.render(<BestColor />);

bestColors.js

export const bestColors = [
  { id: crypto.randomUUID(), name: "Blue" },
  { id: crypto.randomUUID(), name: "White" },
  { id: crypto.randomUUID(), name: "Pink" },
];

Try it on CodeSandbox

The snippet above incorrectly sets each item’s key outside the map() method. You should avoid such a mistake!

Always set the key prop while creating the array of elements. So, the snippet above should have set the key on the component invocation tag – in the map() method.

Example 2: Correct placement of the key prop

index.js

import { createRoot } from "react-dom/client";
import { bestColors } from "./bestColors.js";

function ColorListElement({ color }) {
  return <li>{color.name}</li>;
}

function BestColor() {
  const bestColorsLiElements = bestColors.map((color) => (
    // CORRECT: Always define the key directly inside the map() method.
    <ColorListElement key={color.id} color={color} />
  ));
  return <ul>{bestColorsLiElements}</ul>;
}

const root = createRoot(document.getElementById("root"));
root.render(<BestColor />);

bestColors.js

export const bestColors = [
  { id: crypto.randomUUID(), name: "Blue" },
  { id: crypto.randomUUID(), name: "White" },
  { id: crypto.randomUUID(), name: "Pink" },
];

Try it on CodeSandbox

The snippet above correctly sets each item’s key inside the map() method. This allows React to access the key value for each element in the array returned by the map() method.

Tip: React’s reconciliation (diffing) algorithm is programmed to access the key of each top-level item of the array. It never looks for the key in the child or descendant elements.

2. React does not pass keys to components

React neither transfers the key prop to components nor includes it as an attribute of a rendered element.

React uses keys solely to know the state of array items. They help React identify changes to the array.

So if you need to use a specific key’s value in your component or on your DOM element, you should explicitly pass it as the value of a different attribute.

Example:

index.js

import { createRoot } from "react-dom/client";
import { bestColors } from "./bestColors.js";

function ColorListElement(props) {
  return (
    <li>
      {props.color.name} (ID: {props.id})
    </li>
  );
}

function BestColor() {
  // Use `color.id` as the `key` and `id` props' value.
  const bestColorsLiElements = bestColors.map((color) => (
    <ColorListElement key={color.id} id={color.id} color={color} />
  ));
  return <ul>{bestColorsLiElements}</ul>;
}

const root = createRoot(document.getElementById("root"));
root.render(<BestColor />);

bestColors.js

export const bestColors = [
  { id: crypto.randomUUID(), name: "Blue" },
  { id: crypto.randomUUID(), name: "White" },
  { id: crypto.randomUUID(), name: "Pink" },
];

Try it on CodeSandbox

The snippet above initializes each list item’s id attribute with the same value as the key prop. By so doing, the ColorListElement component can access props.id but not props.key.

3. Always generate the keys outside your components

Never generate keys on the fly (while rendering your components). Instead, create them in your data outside your components. Otherwise, React will recreate the elements on every rendering cycle because the key’s value will always be different.

Example 1: Incorrect place to generate the key prop

index.js

import { createRoot } from "react-dom/client";
import { bestColors } from "./bestColors.js";

function BestColor() {
  // WRONG: Never generate keys on the fly.
  const bestColorsLiElements = bestColors.map((color) => (
    <li key={crypto.randomUUID()}>{color}</li>
  ));
  return <ul>{bestColorsLiElements}</ul>;
}

const root = createRoot(document.getElementById("root"));
root.render(<BestColor />);

bestColors.js

// The keys' values should have been set here (outside the component while creating your data).
export const bestColors = ["Blue", "White", "Pink"];

Try it on CodeSandbox

The snippet above incorrectly generated each element’s key while rendering the BestColor component. You should avoid such a mistake to prevent subtle bugs caused by recreating the elements on every render.

Always create each key’s value in your data outside the component.

Example 2: Correct place to generate the key prop

index.js

import { createRoot } from "react-dom/client";
import { bestColors } from "./bestColors.js";

function BestColor() {
  const bestColorsLiElements = bestColors.map((color) => (
    <li key={color.id}>{color.name}</li>
  ));
  return <ul>{bestColorsLiElements}</ul>;
}

const root = createRoot(document.getElementById("root"));
root.render(<BestColor />);

bestColors.js

// CORRECT: Always generate the key in your data outside the component.
export const bestColors = [
  { id: crypto.randomUUID(), name: "Blue" },
  { id: crypto.randomUUID(), name: "White" },
  { id: crypto.randomUUID(), name: "Pink" },
];

Try it on CodeSandbox

The snippet above correctly generated each element’s key in the array data outside the component.

How to Handle Events in React

Event handling in React involves configuring your JSX elements to respond to user interactions on them (such as mouse clicks, form submission, and element focus).

<jsxTag onEvent={handleEvent}>UI Content</jsxTag>

Here’s what’s going on:

• jsxTag: React elements like <div>, <button>, and <input>.

• onEvent: The event listener you want to add to the React element. Some examples are onClick, onBlur, and onHover.

• handleEvent: The event handler function you want to use to handle (respond to) the specified onEvent type.

Tip: Although you can name the event handler anything you prefer, the typical naming convention is to prefix the event’s name with “handle”. For instance, if the event’s name is focus, the handler’s name will be handleFocus.

Types of event handlers

There are two typical ways to define the event handler function in React:

• Inline event handler: A function defined directly on a JSX element’s opening tag as the value of the event listener prop (onEvent).

• Referenced event handler: A function defined as a separate (independent) logic and linked to an event listener attribute (onEvent) by name referencing.

Example: Inline event handler

export default function App() {
  return (
    <h1 onClick={() => alert("You clicked the heading!")}>
      Oluwatobi is my name.
    </h1>
  );
}

Try it on CodeSandbox

Example: Referenced event handler

export default function App() {
  return <h1 onClick={handleClick}>Oluwatobi is my name.</h1>;
}

const handleClick = () => alert("You clicked the heading!");

Try it on CodeSandbox

React components have a unique memory that allows them to remember things between renderings. This memory is called “state.”

What Is React State?

React state is a component’s memory for storing data that React should remember during a component’s re-rendering and whose update should trigger a new render.

Syntax of React state:

import { useState } from "react";

function App() {
  const [state, setState] = useState(initialState);

  // ...
}

• state: The variable containing the component’s state value.

• setState: A function for updating the state value.

• useState: The state Hook for initializing and retrieving the component’s state.

Example of React state:

import { useState } from "react";

function AboutCompany() {
  const [age, setAge] = useState(5);

  function updateAge() {
    setAge(age + 1);
  }

  return (
    <div>
      <h3>CodeSweetly is {age} years old!</h3>
      <button type="button" onClick={updateAge}>
        Click to update age
      </button>
    </div>
  );
}

export default AboutCompany;

Try it on CodeSandbox

When a user clicks the button UI, the onClick event triggers the updateAge event handler, which uses the setAge setter function to update the component’s age state.

Tip: React will trigger a re-render of your component every time you use useState’s setter function to update your state. But what exactly do the terms “trigger” and “render” mean?

React Trigger vs Render vs Commit vs Paint

Triggering, rendering, committing, and painting are the steps involved in displaying React UIs on screen. Here are the differences between the four steps:

The above slide illustrates the four phases in the lifecycle of a component’s UI:

• Trigger: Specifies the component whose UI you want to display on the screen.

• Render: Calls the component you’ve triggered.

• Commit: Updates the DOM with the UI of the rendered component.

• Paint: Converts the DOM code you’ve committed into user-friendly elements that users can interact with in their browsers.

Let’s discuss these differences in detail.

What does it mean to trigger a render in React?

The trigger event is the first step in displaying a React user interface (UI) on screen. It specifies the component whose UI you want to display on the screen. This event happens on two occasions:

1. When the app starts running. The React application uses the createRoot method to specify the component whose UI you want to render to a DOM node.

import ReactDOM from "react-dom/client";
import DonationUI from "./components/DonationUI.js";

// When the app starts running, you need to use createRoot and its render method to trigger an initial rendering of the app's root component.
const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<DonationUI />);

The snippet above does the following:

• Uses the ReactDOM.createRoot() method to create a ReactDOMRoot object instance for the root element argument.

• Use the object instance’s render() method to trigger an initial rendering of the DonationUI component.

In other words, the createRoot().render() method specifies DonationUI as the component whose UI React should display in the root HTML element.

2. The second reason a trigger event can happen is when a component’s (or its ancestors’) state gets updated with a set function.

DonationUI.js

import React from "react";

function DonationUI() {
  const [donate, setDonate] = React.useState(false);
  function createUserInterface() {
    if (donate) {
      return (
        <p>
          <a href="https://www.buymeacoffee.com/codesweetly">Support page</a>.
          Thank you so much!
        </p>
      );
    }
    // The setDonate function will trigger a re-rendering of the DonationUI component.
    return <button onClick={() => setDonate(true)}>Buy me a coffee</button>;
  }
  return createUserInterface();
}

export default DonationUI;

The snippet above does the following:

1. Defines a component named DonationUI.

2. Initializes the component’s state with the Boolean value false.

3. Programs the component to return a paragraph element if the state’s donate variable is true. Otherwise, it should return a button element.

When users click the button element, the setDonate setter function will trigger a re-rendering of the DonationUI component. Below are the entry script and the HTML code so you can try it yourself locally.

index.js

import ReactDOM from "react-dom/client";
import DonationUI from "./components/DonationUI";

const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<DonationUI />);

index.html

<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>CodeSweetly DonationUI</title>
  </head>
  <body>
    <main id="root"></main>
    <script type="module" src="index.js"></script>
  </body>
</html>

Try it on CodeSandbox

What does it mean to render React components?

The rendering step is when React invokes (calls) the component you’ve triggered with either the createRoot method or a set function. Rendering causes React to invoke a component to produce the UI you want to display on the screen. The component React will render depends on the moment the trigger event occurred:

• For an initial trigger (at the start of the app), React will invoke the app’s root component.

• For update triggers (whenever a component’s state gets updated), React will call the function component whose state update initiated the trigger event.

Tip: Rendering a component means “calling a component” to retrieve its user interface (UI).

What does it mean to commit a React UI to the browser’s DOM?

The committing stage is when React updates the DOM with the UI of the rendered component.

There are some important things to note about this process:

• For an initial render (at the start of the app), React will initialize the root DOM with the root component’s UI. It will use the appendChild() JavaScript API to append the DOM nodes (UI) retrieved from the component into the app’s root HTML element.

• For subsequent re-rendering (after the initial commit), React will only update the DOM nodes if there’s a difference between the previous rendering output and the latest one. No changes will occur if the component’s latest output is the same as the previously committed one.

What does it mean to paint the DOM nodes on the screen?

The painting (browser rendering) stage is when the browser repaints the screen to convert the DOM code to user-friendly elements. This is a browser-level process that begins once React has finished updating (committing) the DOM nodes.

Sometimes, components need to store information that shouldn’t trigger a render when updated. In these situations, you can use a ref.

What Is the React Ref Hook?

The React Ref Hook lets you store values that don’t trigger re-renders when changed.

Syntax of the React ref Hook

The useRef Hook accepts only one optional argument. Here is the syntax:

useRef(initialValue);

• initialValue: The value to store in the component’s ref memory. Any JavaScript data type is allowed.

• useRef(): Returns an object ({ current: initialValue }).

Example of the React ref Hook:

import { useRef } from "react";

function App() {
  const myNameRef = useRef("Oluwatobi");

  function handleClick() {
    console.log(myNameRef.current); // Outputs: "Oluwatobi"
  }

  return <button onClick={handleClick}>Click me</button>;
}

export default App;

Try it on CodeSandbox

The snippet above used the useRef Hook to store a value ("Oluwatobi") whose update shouldn’t trigger re-renders.

React ref Hook best practices

When you’re working with React’s ref hook, there are some best practices you should follow:

• Use dot syntax to access and update a ref object’s value instead of square bracket notation.

• Avoid accessing or updating the current property during rendering to maintain the purity of your components.

• Don’t use a function instance as your initialValue. Pass the function itself, not its output.

• You can use the React ref Hook to manage your HTML DOM nodes.

But what’s the difference between refs, states, and variables, I hear you ask? Let’s find out below.

Variables vs Refs vs States in React

In React, variables, refs, and states allow you to store and mutate data. But they work in different ways. Here are the main distinctions between them:

1. Does its value persist during re-rendering?

   • React Ref: Yes

   • React State: Yes

   • JavaScript Variable: No

2. Would updating its value trigger a re-rendering of the component?

   • React Ref: No

   • React State: Yes

   • JavaScript Variable: No

3. Is it plain JavaScript?

   • React Ref: Yes

   • React State: No

   • JavaScript Variable: Yes

4. Can you declare it outside a component?

   • React Ref: No

   • React State: No

   • JavaScript Variable: Yes

5. Is it usable in conditional statements, loops, or nested functions?

   • React Ref: No

   • React State: No

   • JavaScript Variable: Yes

How do variables work in React?

A variable’s value does not persist during re-rendering. Its value resets at the beginning of a new rendering.

Example:

import { useState } from "react";

function App() {
  let myVar = 0;
  const [myState, setMyState] = useState(0);

  function updateVar() {
    myVar = myVar + 1;
    console.log("myVar =", myVar);
  }

  function updateState() {
    setMyState(myState + 1);
  }

  return (
    <div>
      <h2>Variable: {myVar}</h2>
      <h2>State: {myState}</h2>
      <button onClick={updateVar}>Update Variable</button>
      <button onClick={updateState}>Update State</button>
    </div>
  );
}

export default App;

Try Editing It

The snippet above will:

• Increment the variable’s value when you click the “Update Variable” button. This modification doesn’t trigger a re-rendering of the component because React doesn’t track a variable’s changes.

• Increment the state’s value when you click the “Update State” button. This modification triggers a re-rendering of the component because React requests a re-render whenever you modify the state.

• Reset the variable’s value to zero (0) during each re-rendering of the App component. Therefore, the rendered variable’s value will always be zero (0).

How do refs work in React?

A ref’s value persists during re-rendering, but modifying it doesn’t cause React to re-render the component. In other words, a ref is a plain JavaScript object whose value React remembers while re-rendering your component. But React doesn’t track changes to the ref’s value. So, its modifications don’t trigger a new rendering.

Example:

import { useState, useRef } from "react";

function App() {
  const myRef = useRef(0);
  const [myState, setMyState] = useState(0);

  function updateRef() {
    myRef.current = myRef.current + 1;
    console.log("myRef =", myRef);
  }

  function updateState() {
    setMyState(myState + 1);
  }

  return (
    <div>
      <h2>Ref: {myRef.current}</h2>
      <h2>State: {myState}</h2>
      <button onClick={updateRef}>Update Ref</button>
      <button onClick={updateState}>Update State</button>
    </div>
  );
}

export default App;

Try Editing It

The snippet above will:

• Increment the ref’s value when you click the “Update Ref” button. This modification doesn’t trigger a re-rendering of the component because React doesn’t monitor the ref’s changes.

• Increment the state’s value when you click the “Update State” button. This modification triggers a re-rendering of the component because React requests a re-render whenever you modify the state.

• Retains the ref and state’s value during each re-rendering of the App component.

How do states work in React?

A state’s value persists during re-rendering. Modifying it also causes React to re-render the component.

Example:

import { useState, useRef } from "react";

function App() {
  let myVar = 0;
  const myRef = useRef(0);
  const [myState, setMyState] = useState(0);

  function updateVarAndRef() {
    myVar = myVar + 1;
    myRef.current = myRef.current + 1;
    console.log("myVar =", myVar);
    console.log("myRef =", myRef);
  }

  function updateState() {
    setMyState(myState + 1);
  }

  return (
    <div>
      <h2>Variable: {myVar}</h2>
      <h2>Ref: {myRef.current}</h2>
      <h2>State: {myState}</h2>
      <button onClick={updateVarAndRef}>Update Variable and Ref</button>
      <button onClick={updateState}>Update State</button>
    </div>
  );
}

export default App;

Try Editing It

The snippet above will:

• Increment the variable and ref’s value when you click the “Update Variable and Ref” button. This modification doesn’t trigger a re-rendering of the component because React doesn’t monitor changes to the variable or ref.

• Increment the state’s value when you click the “Update State” button. This modification triggers a re-rendering of the component because React requests a re-render whenever you modify the state.

• Resets the variable’s value during each re-rendering of the App component, while retaining the ref and state’s data.

Tips on using variables, refs, and states in React

• Use variables for values that should reset on every rendering of the component.

• Use the Ref Hook to store values that users do not need to see on screen, as changes to the ref will not trigger a re-rendering of the component.

• React state is ideal for storing values that you want to display on the screen, as state changes trigger a re-rendering of the component.

React components sometimes need to fetch data or change the DOM during different lifecycle phases: trigger, render, commit, and paint. The Effect Hook can help with these tasks.

What Is the useEffect Hook?

The useEffect hook lets function components perform side effects outside React.

Syntax of the useEffect Hook

The useEffect hook accepts two arguments. Here’s the syntax:

useEffect(callback, array);

• callback: The required setup function for the useEffect hook.

• array: (Optional) The reactive dependencies list that indicates when React runs the callback.

Tip: React runs the setup function after the component mounts or when dependencies change.

Example of the useEffect Hook:

import { useState, useEffect } from "react";

function AboutCompany() {
  const [age, setAge] = useState(5);

  useEffect(() => {
    document.title = `🥳🎁🎉 It's CodeSweetly's birthday! 🎉🎁🥳`;
  });

  return (
    <div>
      <h3>CodeSweetly is {age} years old!</h3>
      <button type="button" onClick={() => setAge(age + 1)}>
        Click to update age
      </button>
    </div>
  );
}

export default AboutCompany;

The useEffect code updates the browser’s title after the UI finishes rendering.

useEffect Hook’s best practices

As always, there are some best practices to use this hook most effectively:

• Use useEffect to connect with things outside your React app, such as APIs or timers. If your code has no side effects, you likely don’t need it.

• Avoid adding values to the dependency array unless your effect uses them. Include only the state and props needed to prevent unnecessary re-runs.

• Declare static objects and functions outside components. Place dynamic ones inside your Effect Hook.

• When depending on object props, list each primitive value used in your effect instead of the entire object.

• Use StrictMode to help catch common useEffect hook issues during development.

With the basics of React covered, let’s discuss styling.

How to Style React Components

The four primary ways to style React elements are:

• CSS style sheets

• Inline style attributes

• CSS Modules

• CSS-in-JS Libraries

Let’s discuss the four styling techniques.

How to use CSS style sheets to style React elements

Below are the steps to style JSX elements with regular CSS style sheets.

1. Create a CSS stylesheet

First, create a CSS stylesheet in your React projects.

touch styles.css

Tip: You can create the stylesheet anywhere in your project directory.

2. Define your ruleset

Open the newly created CSS file and declare your styles.

Example:

styles.css

.text {
  color: seagreen;
  font-weight: bold;
}

The CSS snippet above instructs browsers to apply a seagreen color and bold font weight on elements with a text class name.

3. Apply the stylesheet’s ruleset to your element

Import your stylesheet into the component file containing the element you wish to style. Then, apply the stylesheet’s ruleset to it.

Example:

App.js

// Import your stylesheet (the path to your stylesheet may be different).
import "../styles.css";

function App() {
  return <div className="text">Oluwatobi is my name.</div>;
}

export default App;

Try it on CodeSandbox

The snippet above instructs React to apply the "text" ruleset on the element with a className="text" attribute.

How to use the inline style attribute to style React elements

React allows you to apply inline styles to JSX elements in the same way as inline CSS works in HTML. But there are some differences to keep in mind.

First, HTML applies inline styles as a string value:

<div style="color:seagreen; font-weight:bold;">Oluwatobi is my name.</div>

But in React, you must define inline styles as objects, not strings:

<div style={{ color: "seagreen", fontWeight: "bold" }}>
  Oluwatobi is my name.
</div>

The snippet above uses two sets of curly braces because in JSX (as I mentioned above), you wrap JavaScript expressions inside curly braces: for instance, <div>{myNameVariable}</div>.

So, suppose the expression is a JavaScript object literal. In that case, you will need two sets of curly braces: for instance, <div>{{ name: "Oluwatobi" }}</div>.

Therefore, in style={{ color: seagreen, fontWeight: bold }}, the first set of curly braces ({...}) tells React that you want to write a JavaScript expression. The second set of curly braces ({ color: seagreen, fontWeight: bold }) is the JavaScript expression (an object) you are assigning as the style attribute’s value.

Example:

App.js

function App() {
  return (
    <div style={{ color: "seagreen", fontWeight: "bold" }}>
      Oluwatobi is my name.
    </div>
  );
}

export default App;

Try it on CodeSandbox

The React snippet above instructs the computer to apply an inline style to the div element.

You can see that we wrote fontWeight in camelCase. This is because, under the hood, JSX compiles into plain JavaScript. So it uses the JavaScript Web APIs attribute naming convention.

To make your code easier to read, consider storing your inline style object in a separate variable like so:

App.js

function App() {
  // Store your inline style object in a variable:
  const textStyles = { color: "seagreen", fontWeight: "bold" };
  return <div style={textStyles}>Oluwatobi is my name.</div>;
}

export default App;

Try it on CodeSandbox

Tip: The Tailwind CSS framework is an inline styling tool that provides utility classes you can apply directly to an element. It offers additional features that are often lacking in regular inline styling. For example, Tailwind allows you to configure media queries and event states (such as hover, focus, and active) in inline styles.

How to use CSS modules to style React elements

As defined on the official documentation, a CSS Module is a CSS file in which all class names and animation names are scoped locally by default.

CSS Modules share many similarities with a regular CSS style sheet. But there are some essential differences.

1. Filename convention

The syntax for naming a regular CSS stylesheet is [name].css: for instance, codesweetly-styles.css.

But a CSS module’s file naming convention is [name].module.css: for instance, codesweetly-styles.module.css.

2. Styles scope

Importing a CSS style sheet into your script file makes its rulesets available globally to all components (and child components) of that script.

But importing a CSS module into your script file only makes its rulesets available locally to the component that invokes the module’s rule. Also, that component must be in the script that imports the CSS module.

Example:

Create a regular CSS stylesheet in your React project and add some rules to it:

styles.css

.imageInfo {
  text-align: center;
  color: #442109;
}

Also, create a CSS module in the same project and add some rules to it:

styles.module.css

.imageInfo {
  border: 8px ridge #71380f;
  background-color: #ffe5b4;
  padding: 20px 0 7px;
}

Import both the CSS stylesheet and CSS module you’ve just created into your script file:

App.js

import "../styles.css";
import codesweetlyStyles from "../styles.module.css";

function App() {
  return (
    <div className="imageInfo">
      <h1>Random Image</h1>
      <img src="https://picsum.photos/400/400" alt="Random Image" />
      <p>Get a new image each time you refresh your browser.</p>
    </div>
  );
}

export default App;

Try it on CodeSandbox

Go ahead and run your app and check its output in your browser.

After running your app, you will notice that React only applied the CSS stylesheet’s ruleset, not the CSS module’s own.

React did so because the stylesheet’s ruleset is globally available to all elements (and child components) of the page where you imported the sheet.

But the ruleset in the module is locally available only to the component that explicitly invokes the rule.

So, to use your CSS module’s style in your component, you must explicitly execute it like so:

App.js

import "../styles.css";
import codesweetlyStyles from "../styles.module.css";

function App() {
  return (
    <div className={`imageInfo ${codesweetlyStyles.imageInfo}`}>
      <h1>Random Image</h1>
      <img src="https://picsum.photos/400/400" alt="Random Image" />
      <p>Get a new image each time you refresh your browser.</p>
    </div>
  );
}

export default App;

Try it on CodeSandbox

The snippet above uses the codesweetlyStyles.imageInfo code to instruct React to apply the CSS module’s imageInfo ruleset to the div element.

3. Composition

To compose styles together while using a regular CSS style sheet, you must apply multiple classes to your element.

Example: Compose rulesets with regular CSS style sheets

styles.css

.container {
  border: 4px solid blueviolet;
  padding: 30px 15px;
}

.text {
  color: seagreen;
  font-weight: bold;
}

App.js

import "../styles.css";

function App() {
  return <div className="container text">Oluwatobi is my name.</div>;
}

export default App;

Try it on CodeSandbox

Using multiple classes on an element to implement style composition is not the best practice because CSS will use the order of style definitions in the stylesheet to determine the order of precedence based on the CSS cascading rules.

But CSS modules provide a composes declaration that offers greater flexibility in composing your styles to suit your project’s needs.

Example: Compose rulesets with CSS modules

styles.module.css

.container {
  border: 4px solid blueviolet;
  padding: 30px 15px;
}

.text {
  composes: container;
  color: seagreen;
  font-weight: bold;
}

App.js

import styles from "../styles.module.css";

function App() {
  return <div className={styles.text}>Oluwatobi is my name.</div>;
}

export default App;

Try it on CodeSandbox

Although you can define multiple composes declarations in a ruleset, they must precede other rules.

Example: All composes declarations must come before other rules

styles.module.css

.container {
  border: 4px solid blueviolet;
  padding: 30px 15px;
}

.curved {
  border-radius: 20px;
}

.text {
  composes: container;
  composes: curved;
  color: seagreen;
  font-weight: bold;
}

Try it on CodeSandbox

You can simplify the .text ruleset by using a single composes declaration for multiple classes.

Example: Compose classes with a single composes declaration

styles.module.css

.container {
  border: 4px solid blueviolet;
  padding: 30px 15px;
}

.curved {
  border-radius: 20px;
}

.text {
  composes: container curved;
  color: seagreen;
  font-weight: bold;
}

Try it on CodeSandbox

How to use a CSS-in-JS library to style React elements

A CSS-in-JS library allows you to use the complete features of CSS directly within your JavaScript file.

Some of the popular CSS-in-JS libraries are Linaria, Emotion, Pigment CSS, and Panda CSS.

Feel free to try any CSS-in-JS library you prefer. Here, we’ll use Emotion to illustrate how such a styling technique works in a React application.

So, go ahead and install the library into any of your React projects by running:

npm i @emotion/react@11.14.0

After you’ve installed Emotion, import it and use it in your component file like so:

App.js

// The comment below is essential. Emotion will not work without it.
/** @jsxImportSource @emotion/react */

// Define your styles using the JavaScript object syntax.
const codesweetlyStyles = {
  border: "8px ridge #71380f",
  backgroundColor: "#ffe5b4",
  padding: "20px 0 7px",
  textAlign: "center",
  color: "maroon",
  "@media(min-width: 768px)": {
    color: "darkslategray",
  },
};

// Apply the styles to your element.
function App() {
  return (
    <div css={codesweetlyStyles}>
      <h1>Random Image</h1>
      <img src="https://picsum.photos/400/400" alt="Random Image" />
      <p>Get a new image each time you refresh your browser.</p>
    </div>
  );
}

export default App;

Try it on CodeSandbox

The snippet above does the following:

1. Uses the /** @jsxImportSource @emotion/react */ comment (JSX Pragma) to tell the Babel JSX plugin to convert the script’s JSX calls to an Emotion function called jsx instead of React.createElement. Make sure you place the pragma directive above your import statements. Otherwise, the Emotion library will not work.

2. Defines styles in a JavaScript object.

3. Uses Emotion’s css prop feature to apply the styles to the JSX element.

Notice that the css prop is like the inline style attribute. The main difference is that the css props support more CSS features like nested selectors, auto vendor-prefixing, media queries, and event states (such as hover, focus, and active). So, using CSS-in-JS libraries like Emotion lets you write highly flexible and responsive styles directly in your JavaScript files.

Tip: The css prop works on any element that supports the className attribute.

Now, go ahead and run your app and check its output in your browser.

And that’s it! You now know how to use the CSS-in-JS library to style your React elements.

I used Emotion in this article because I like how clean its syntax looks. Feel free to test other CSS-in-JS libraries, such as Pigment CSS. You may find one that suits you better.

Overview

In this handbook, we discussed the core concepts you need to know to start building applications with React. We also used examples to practice creating and styling components.

Whether you’re considering a small personal project or a full-stack app for a larger user base, you now have the foundation to build these projects using React.

Thanks for reading!

Dive deeper into React

This handbook has given you a peek inside my Code React Sweetly book. Whether you’re just starting or want to sharpen your fundamentals, the book walks you through everything from essential concepts to deploying real apps using JavaScript and TypeScript. It is practical, beginner-friendly, and designed to help you code React sweetly!

Why This Matters

When coding traditionally, you’re typing every line yourself, searching documentation, and figuring out syntax. With AI, you can:

• Focus on solving problems instead of remembering syntax

• Learn faster by seeing good code examples in real-time

• Build projects quickly without sacrificing quality

Experienced developers can complete tasks faster with AI assistance. But here's the key: you need to know how to use these tools effectively. And you need a background in programming to do so.

Interested? Let’s dive into the world of AI-based coding tools that have taken the world by storm.

Table of Contents

• Essential AI Terminology

• When to Use AI vs When to Code Yourself

• Prerequisites

• Your Complete Learning Journey

• How to Generate Your First AI-Assisted Code (Quick Start)

• Stage 1: Foundation – Getting Started with AI Coding

• Stage 2: Advanced GitHub Copilot Features

• Stage 3: CLI-Based AI Agents (Claude Code & Gemini)

• Stage 4: Mastery – Combining Tools and Advanced Workflows

• Common AI Issues

• What's Next After Completing All Stages?

• Conclusion

Essential AI Terminology

Before we get started, let’s make sure you understand these key terms:

• Tokens: Think of tokens as "word pieces" – how AI reads your code and text. Each character, word, or symbol uses tokens. Free tiers limit how many tokens you can use.

• Context Window: How much code/conversation the AI can "remember" at once. Like short-term memory, larger windows mean better understanding of your project.

• Hallucinations: When AI confidently suggests wrong information – like making up functions that don't exist. Always verify AI suggestions!

• Prompt: Your instructions to the AI – comments, questions, or requests that guide what code it generates.

When to Use AI vs When to Code Yourself

Use AI for:

• Writing boilerplate code (getters, setters, basic CRUD)

• Learning new frameworks or syntax

• Writing tests and documentation

• Refactoring repetitive patterns

• Getting unstuck on syntax errors

Code yourself when you’re:

• Designing system architecture

• Making security-critical decisions

• Writing complex business logic

• Learning new concepts (first time)

• Working on performance-critical optimizations

The Golden Rule: Use AI to speed up implementation, but keep architectural decisions to yourself. AI is excellent at "how", but you decide "what" and "why."

Prerequisites

Before starting this tutorial, you should have:

• Basic programming experience – You can write simple programs in any language

• A code editor installed – VS Code is recommended (free from code.visualstudio.com)

• Basic Git knowledge – You know how to commit and push code

• Free to start – Many tools now have generous free tiers, and paid plans start around $10-20/month

Your Complete Learning Journey

This comprehensive tutorial is structured as a step-by-step program to transform you into an AI-assisted development expert:

Note: To keep the tutorial approachable, we’ll just focus on a core handful of tools. But you should research and explore more tools that might fit your specific needs beyond the ones we use here.

Your Learning Path:

You'll progress through 4 stages: mastering GitHub Copilot basics, unlocking advanced features like chat modes and agents, exploring CLI tools (Claude Code & Gemini), and finally combining multiple tools strategically for complete project workflows.

First, let's quickly see how you can generate your first AI code snippet.

How to Generate Your First AI-Assisted Code (Quick Start)

Let's start with the absolute basics. Don't worry about choosing the "perfect" tool – you can always switch later. Here's how to get started:

GitHub Copilot (Recommended for Beginners)

You can install GitHub Copilot by following these steps:

1. Open VS Code

2. Click the Extensions icon (or press Ctrl+Shift+X)

3. Search for "GitHub Copilot"

4. Click "Install"

5. Sign in with your GitHub account

GitHub Copilot has a free tier (2000 code completions + 50 chat requests per month), which should be enough for this experiment.

TIP: Students, teachers, and OSS maintainers can get the Pro plan for free, which provides unlimited usage instead of the free tier limits.

Your First AI Suggestion

Once installed, create a new file called test.js and type:

// function to calculate the area of a circle

Press Enter and wait. You'll see gray text appear – that's your AI suggestion! Press Tab to accept it.

That’s it! You’ve just gotten your first AI suggestion! Isn’t that cool?

Stage 1: Foundation – Getting Started with AI Coding

Step 1: Understanding Your Options

Think of AI coding assistants like different types of helpful friends and colleagues. Let’s cover a few:

IDE-based: Some tools are designed to work with familiar code editors or are a standalone fork of editors like VS Code. For example:

• GitHub Copilot (VS Code Extension) – An AI coding assistant from GitHub, works directly in VS Code with tab completion and chat features

• Cursor (Standalone) – VS Code fork with enhanced agent modes, faster autonomous coding, and better handling of large codebase refactoring

• Windsurf (Standalone or VS Code Extension) – Focuses on collaborative AI development with real-time suggestions and team features

• Zed – High-performance editor with built-in AI assistance and fast rendering

CLI-based: Some tools are CLI-based, which you can launch within your terminal app:

• Claude Code – Anthropic's terminal AI for autonomous development sessions and complex reasoning

• Gemini – Google's CLI tool with large context windows and multimodal capabilities (images, documents)

• OpenCode – Open-source alternative with customizable models and local processing options

• Cursor CLI – Terminal version of Cursor for command-line AI assistance

UI-based and Background Agents: Besides these, there are also background agents and tools that can operate entirely in the background, such as performing pull-request reviews and more.

For example, both ChatGPT and Claude's desktop app can edit files on your local file system if you set them up. Similarly, some cloud-based agents can "run in the background" to complete your instructions. We will exclude these from the scope of this guide.

Step 2: Making Your Choice & Learning Automatic Suggestions (Tab Completion)

For your first stage, I recommend starting with either GitHub Copilot. You can always switch to the tool that fits your needs after you learn the basics.

Step 3: Step-by-Step Setup

How to Set Up GitHub Copilot (You can skip this if you already followed the Quick Start earlier)

1. Open VS Code. If you don't have it, download from code.visualstudio.com.

2. Install the Extension

   • Press Ctrl+Shift+X (Windows/Linux) or Cmd+Shift+X (Mac)

   • Type "GitHub Copilot" in the search box

   • Click the blue "Install" button

   • You'll see a pop-up asking you to sign in

3. Sign In

   • Click "Sign in to GitHub"

   • Your browser will open

   • Log in with your GitHub account (create one free at github.com if needed)

   • Click "Authorize GitHub Copilot"

4. Start using Copilot

   • Back in VS Code, you'll see "GitHub Copilot is ready"

Step 4: Mastering Tab Completion

Let's make sure it's working. Create a new file: hello.py. Type this comment and press Enter:

# function to greet a user by name

Wait 1-2 seconds. You should see gray text appear. Just press Tab to accept the suggestion.

What you should see:

# function to greet a user by name
def greet_user(name):
    return f"Hello, {name}!"

If you see this, congratulations! You're now using AI to help you write code.

If you’re having setup issues you can check the Troubleshooting Quick Reference for solutions.

Step 5: Essential Keyboard Shortcuts & First Practice

Here are the only shortcuts you need for your first week:

The Basics:

• Tab – Accept the AI suggestion (use this the most!)

• Esc – Dismiss the suggestion (when you don't want it)

When you're ready for more, try these:

Windows/Linux:

• Alt+] – See the next suggestion

• Alt+[ – See the previous suggestion

• Ctrl+Enter – See all suggestions in a panel

macOS:

• Option+] (or Alt+]) – See the next suggestion

• Option+[ (or Alt+[) – See the previous suggestion

• Ctrl+Enter – See all suggestions in a panel

Stage 1 Practice Exercise

Exercise: Build a Simple Todo App

1. Create a new file called todo.js

2. Start with this comment: // TODO app with add, remove, and list functions

3. Add this comment and wait for AI suggestions: // function to add a new todo item

4. Accept the suggestion with Tab if they look good to you

5. Continue adding comments for remove and list functions

6. Test your functions to make sure they work

Goal: Learn to "converse" with AI through clear comments and build confidence accepting/rejecting suggestions.

Need help? See the Troubleshooting Quick Reference for common issues and solutions.

Ready for the next stage? Before moving on, make sure you can:

- [ ] Get AI suggestions by typing comments
- [ ] Accept suggestions with Tab and dismiss with Esc
- [ ] Use Alt+] and Alt+[ to see different suggestions
- [ ] Write basic functions with AI help

If you're comfortable with these basics, you're ready to learn more powerful Copilot features.

Stage 2: Advanced GitHub Copilot Features

Step 6: Getting Better AI Suggestions

Now that you know the basics, let's learn how to get much better suggestions from your AI. The secret is understanding what your AI can see.

What Your AI Assistant Sees

Think of your AI assistant like a helpful friend looking over your shoulder. It can see:

1. What you're typing right now – Your current file

2. Other open tabs – Files you have open (this is important!)

3. Your project structure – Folder and file names

4. Your comments – This is how you "talk" to the AI

The "Neighboring Tabs" Trick

Here's a pro tip that will save you hours: Keep related files open in tabs.

Example: If you're writing a React component:

• Have your component file open (Button.jsx)

• Also, open your CSS file (Button.css)

• Keep your test file visible too (Button.test.js)

You can then share these additional files as context with the AI in several ways:

• @mention files: Type @filename.js in chat to reference specific files

• Use @workspace: This chat participant can see all files in your project

• Drag and drop: Simply drag files from the explorer into the chat window

• Select code: Highlight code and right-click "Ask Copilot" to include it in context

The AI uses these open files to understand your project structure and suggest more relevant code that matches your existing patterns.

Step 7: Quality Control & Best Practices

Understanding AI Limitations

AI is powerful but it’s not perfect. Here are the key things to watch for:

Common AI Mistakes:

1. Made-up functions: for example, const result = array.superSort(); doesn't exist!

2. Wrong parameters: for example, greetUser("John", "Doe"); when function expects greetUser(name)

3. Overcomplicated solutions: for example, const isEven = (num) => num.toString(2).slice(-1) === "0"; – just use num % 2 === 0

Quick quality checklist:

- [ ] Test the code - does it actually work?
- [ ] Read it - does it make logical sense?
- [ ] Check basics - are all functions/variables defined?
- [ ] Trust instincts - if it feels wrong, investigate

Security Essentials

Before accepting AI suggestions, make sure you check for these security issues:

- [ ] No hardcoded passwords or API keys
- [ ] User input is validated
- [ ] No eval() with user data
- [ ] Error messages don't expose sensitive info

Better Prompt Writing

Here’s a formula for writing solid prompts: What + How + Return type.

// ❌ Vague: "make function"
// ✅ Clear: "function to validate email format using regex, returns boolean"

Repository-Level Customization with Copilot Instructions

GitHub Copilot now supports repository-level customization through .github/copilot-instructions.md files. This feature helps Copilot understand your project's specific patterns and conventions.

Here’s how to set up Copilot instructions:

# Create GitHub directory if it doesn't exist
mkdir -p .github
touch .github/copilot-instructions.md

Example copilot-instructions.md file:

# Copilot Instructions

## Code Style

- Use React functional components with hooks
- Prefer TypeScript over JavaScript for new files
- Use Tailwind CSS for styling
- Follow the existing file structure in `/src/components`

## Testing

- Write tests with React Testing Library
- Place test files in `__tests__` directories
- Use descriptive test names that explain the behavior

## API Patterns

- Use custom hooks for API calls
- Handle loading and error states consistently
- Use React Query for data fetching

## Naming Conventions

- Components: PascalCase (e.g., `UserProfile.tsx`)
- Hooks: camelCase starting with 'use' (e.g., `useUserData.ts`)
- Utilities: camelCase (e.g., `formatDate.ts`)

What this enables:

• Copilot suggests code that matches your project patterns

• Automatically follows your naming conventions

• Suggests appropriate testing approaches

• Understands your preferred libraries and frameworks

Best practices:

• Keep instructions clear and specific

• Update them as your project standards evolve

• Include examples of preferred patterns

• Mention libraries and frameworks you use

Step 8: Unlocking Advanced Copilot Features

Understanding Your Options

GitHub Copilot offers multiple ways to get AI help:

1. Tab Completion (what you've been using) – Suggestions while typing

2. Chat Mode – Have conversations with AI about your code

3. Edit Mode – Ask AI to modify existing code

4. Agent Mode – Let AI work autonomously on big tasks

We’ll discuss these modes in more detail below so you know how they work and when you should use them.

Model Selection

Copilot now offers different AI models for different needs:

Free with subscription:

• GPT-4.1 – Default model with solid all-around performance

• GPT-4 – Reliable for most coding tasks

Premium models (limited monthly usage):

• Claude 3.5 Sonnet – Great for complex logic

• GPT-5 – Latest and most capable

• Gemini 2.0 Flash – Very fast responses

How to switch models: Click the model dropdown in Chat view

Tip: Start with free models (GPT-4.1) for learning, and save premium models for complex problems.

GitHub Copilot Limitations

Here are some important things to consider when you’re using AI to help you out with your coding:

• Internet dependency – Requires stable connection for suggestions

• Context limitations – Only sees open files, not your entire project structure

• Free tier limits – 2,000 completions and 50 chat requests per month

• Code quality varies – Always review suggestions, especially for security-sensitive code

• Learning curve – Takes time to write effective prompts for complex tasks

• Privacy considerations – Your code is sent to GitHub's servers (check your organization's policies)

Basic Chat vs Suggestions

So you might be wondering - when should you use tab completion vs when should you use chat? It’s best to use tab completion for writing new functions, quick syntax help, and completing patterns. You can use chat for explaining existing code, getting help with errors, and planning your approach to problems.

Try it: Open Chat (Ctrl+Shift+I) and ask: "What does this function do?" while selecting code.

Step 9: Mastering Chat and Agent Modes

The Three Chat Modes

1. Ask Mode (Default) – for questions and explanations:

"What does this function do?"
"How can I optimize this code?"
"Explain this error message"

2. Edit Mode – For making changes to existing code:

"Refactor this to use async/await"
"Add error handling to all API calls"
"Convert this to TypeScript"

• Shows inline diffs before applying changes

• Works across multiple files

• Great for systematic refactoring

3. Agent Mode – For autonomous development:

"Create a REST API with authentication"
"Build a todo app with React and testing"
"Migrate this codebase from Vue 2 to Vue 3"

• Press Cmd+Shift+I (Mac) or Ctrl+Shift+Alt+I (Linux) or Ctrl+Shift+I (Windows)

• Works independently for hours

• Installs packages, creates files, runs tests automatically

When to Use Each Mode

Each mode has its particular use cases. Use ask mode when you’re learning new concepts, you want to understand existing code, for getting explanations, and for planning approaches.

Use edit mode when you’re refactoring existing code, applying consistent changes, adding features to existing functions, or for style/pattern updates.

Agent mode is useful for building complete features (30+ minutes of work), setting up new projects, large-scale refactoring, and for when you want to work on other things while AI codes.

Agent Mode Examples

Small agent task (15 minutes):

"Add user authentication to my Express app"

What the agent generated:

// middleware/auth.js
const jwt = require('jsonwebtoken');

const authenticateToken = (req, res, next) => {
  const authHeader = req.headers['authorization'];
  const token = authHeader && authHeader.split(' ')[1];

  if (!token) return res.sendStatus(401);

  jwt.verify(token, process.env.ACCESS_TOKEN_SECRET, (err, user) => {
    if (err) return res.sendStatus(403);
    req.user = user;
    next();
  });
};

// routes/auth.js
router.post('/login', async (req, res) => {
  // Authentication logic with bcrypt
  const accessToken = jwt.sign({username: user.username}, process.env.ACCESS_TOKEN_SECRET);
  res.json({accessToken: accessToken});
});

Key issues I found: The agent initially forgot to hash passwords and didn't include refresh tokens. This required one iteration to fix security gaps and add proper error handling.

Large agent task (4+ hours):

"Modernize this React class-based app to hooks with TypeScript"

What the agent generated:

// Before (Class component)
class UserProfile extends React.Component {
  constructor(props) {
    this.state = { user: null, loading: true };
  }
  // ... lifecycle methods
}

// After (Hooks + TypeScript)
interface User {
  id: number;
  name: string;
  email: string;
}

const UserProfile: React.FC = () => {
  const [user, setUser] = useState<User | null>(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    fetchUser().then(setUser).finally(() => setLoading(false));
  }, []);

  return <div>{loading ? 'Loading...' : user?.name}</div>;
};

Key issuesI found: the agent successfully updated 47 files, but initially had typing issues with event handlers and needed refinement of generic types. The automated tests also required manual review to ensure proper TypeScript coverage.

Using Chat Participants

Chat participants are specialized AI assistants that have access to specific parts of your development environment. Think of them as experts in different areas who can help with targeted tasks.

They’re basically AI helpers prefixed with @ that have special knowledge and capabilities:

• @workspace has access to your entire project structure, and can search files and understand relationships between components. Use @workspace when you need project-wide analysis: "Find all API endpoints in this project" or "Show me where user authentication is implemented."

• @terminal knows about command-line operations, and can suggest shell commands and explain terminal output. Use @terminal for command-line help: "What command runs the tests?" or "How do I build this project for production?"

• @vscode is an expert in VS Code features, and can help with settings, debugging, and editor configuration. Use @vscode for editor assistance: "Set up debugging for Node.js" or "Configure auto-formatting for this project."

Example usage:

@workspace Can you find all the database models in this project?
@terminal What's the command to install dependencies and start the dev server?
@vscode How do I set up breakpoints for debugging this Express app?

Step 10: Power User Features and Advanced Workflows

Beyond the core Copilot features you've learned, there are specialized tools and commands that can supercharge your productivity. These features go beyond basic chat modes and model selection, focusing on complex multi-file operations and advanced automation.

Advanced Slash Commands

/doc - Generate documentation
/explain - Detailed code explanation
/fix - Fix errors in selected code
/tests - Generate unit tests
/new - Create new project structure

Multi-File Operations

Using # References:

The # symbol creates specific references that tell Copilot exactly what to focus on. These references work like precise pointers to different parts of your project:

• #file:filename: References a specific file: #file:UserModel.js

• #codebase: References your entire project codebase for searching

• #selection: References currently selected code

• #editor: References the currently active file

"Update #file:UserModel.js to include timestamps"
"Search #codebase for all database queries"  
"Refactor #selection to use modern JavaScript syntax"
"Add error handling to #editor for all API calls"

These references help Copilot understand exactly where to look and what to change, making multi-file operations much more precise.

Drag and Drop:

Drag and drop is one of the most intuitive ways to provide context to Copilot. You can simply drag files from the VS Code explorer directly into the chat window, and Copilot will instantly understand their contents and structure.

This feature is particularly useful when you're working on related components and need the AI to understand how different files connect together. Copilot remembers these file relationships throughout your conversation, so you don't need to re-upload files when continuing the same discussion.

This context persistence works across multiple chat sessions, making it easy to pick up where you left off on complex multi-file projects.

Stage 2 Practice Exercises

Exercise 1: Chat Mode Practice

1. Use Ask Mode to understand a complex function

2. Switch to Edit Mode to refactor it

3. Compare the approaches

Exercise 2: Agent Mode Project

1. Start Agent Mode (Shift+Cmd+I)

2. Request: "Create a simple todo app with testing"

3. Watch the autonomous development process

4. Review the generated code

Exercise 3: Advanced Features

1. Use @ participants for project questions

2. Experiment with slash commands

3. Practice multi-file operations

Ready for CLI Tools?

You've now learned the basics of GitHub Copilot in VS Code! CLI tools like Claude Code and Gemini offer even more power for terminal-based development.

If you’re interested in terminal AI you can continue to Stage 3 just below. If you prefer to stick with VS Code, just skip to Stage 4 for advanced workflows.

Stage 3: CLI-Based AI Agents (Claude Code & Gemini)

Step 11: Meet Claude Code – Your Terminal AI Assistant

What is Claude Code?

Remember how GitHub Copilot helps you in VS Code? Claude Code does the same thing, but in your terminal.

Instead of typing in VS Code and getting suggestions, you type in your terminal and have conversations with AI. It's like having a coding buddy right in your command line.

Simple example:

In VS Code with Copilot:

// create a function to validate email
[AI suggests code]

In Terminal with Claude Code:

claude
> Create a function to validate email addresses
[AI writes the code for you]

So when should you use VS Code/Copilot and when should you use Claude Code?

Claude Code is great if you:

• Like working in the terminal

• Want to have AI conversations about code

• Need help with command-line tasks

• Want more control over AI interactions

Stick with VS Code Copilot if you:

• Prefer visual editors

• Are happy with your current workflow

• Don't spend much time in terminal

Pricing

Claude Code requires Claude Pro (20/month), or ClaudeMax (100/month) subscription, or pay-per-use with API credits.

Claude Code Limitations

Here are some important considerations if you’re planning to use Claude Code:

• Paid only – No free tier, requires Claude Pro subscription or API credits

• Terminal-based – Less visual than IDE-integrated tools

• Learning curve – Requires comfort with command-line interfaces

• Context management – You need to manage conversation context manually

• Internet dependency – Requires stable connection for all operations

• Session limits – Long autonomous sessions consume significant API credits

Installation

Recommended (all platforms):

npm install -g @anthropic-ai/claude-code

Alternative installs:

• macOS/Linux: curl -fsSL https://claude.ai/install.sh | bash

• Windows: irm https://claude.ai/install.ps1 | iex

Basic Usage

Interactive Mode (Recommended):

Interactive mode is Claude Code's primary interface where you have real-time conversations with the AI. Unlike one-shot commands that execute once and exit, interactive mode creates a persistent session where you can ask follow-up questions, iterate on solutions, and build complex projects over time.

Interactive mode is recommended because:

• Context persistence: Claude remembers the entire conversation and project context

• Iterative development: You can refine requests and build on previous responses

• Real-time collaboration: Ask questions, get explanations, and modify approaches as you work

• Session resumption: Continue previous conversations with claude --resume

Other Modes Available:

• One-shot mode: Single command execution (explained below)

• Agent mode: Autonomous development sessions that can work for hours independently

1. Navigate to your project:

cd your-project
claude

2. Start conversing naturally:

Claude Code > analyze this codebase and suggest improvements

Claude Code > now help me refactor the user authentication

Claude Code > add unit tests for the payment module

3. Continue previous session:

claude --resume

One-shot Commands (for quick tasks):

One-shot commands are single-execution commands that perform a specific task and then exit. Unlike interactive mode, these don't maintain conversation context – they're perfect for quick, standalone tasks.

What are One-shot Commands?

These are commands you run with a specific instruction directly from your terminal, without entering an interactive session. Claude executes the request and provides results immediately.

When to Use One-shot Commands:

• Quick analysis or code reviews

• Simple file modifications

• Automated scripts and CI/CD integration

• When you need a single, specific answer

Examples:

claude "analyze this codebase and suggest improvements"
claude "fix all TypeScript errors in src/"
claude "generate unit tests for utils.js"
claude "explain what this function does" --file src/auth.js

The key difference is that one-shot commands don't remember context between runs, while interactive mode maintains full conversation history and project understanding.

Interactive vs Autonomous Sessions:

Within interactive mode, you can choose between collaborative and autonomous approaches:

Interactive Session (collaborative):

Claude Code > I'm building user authentication. What approach should we take?

You: Use JWT tokens with refresh token rotation

Claude Code > implement JWT authentication with refresh tokens
[Shows you the implementation step by step]

Claude Code > shall I also add password reset functionality?

You: Yes, use email-based reset

Autonomous Session (hands-off development):

Claude Code > Build a complete user management system with authentication, profiles, preferences, and admin features. Use best practices for security and testing.

[Claude works for hours autonomously, providing periodic updates]
[Final result: Complete user management system ready for production]

When to Use Each: Use interactive sessions when learning or when you want control over decisions. Use autonomous sessions for well-defined tasks where you trust Claude to make good choices independently.

Key Features

Thinking Modes (use in interactive session):

Thinking modes are special commands that tell Claude how deeply to analyze before responding. You choose these modes manually based on your problem's complexity.

When to Use Each Mode:

• think – Quick analysis for straightforward tasks: "think: review this function for bugs"

• think hard – Deeper reasoning for complex logic: "think hard: optimize this algorithm"

• think harder – Complex problem solving with multiple considerations: "think harder: design a scalable database schema"

• ultrathink – Maximum depth analysis for architectural decisions: "ultrathink: evaluate microservices vs monolith for this project"

How They Work:

Claude shows you its reasoning process with longer thinking modes. You'll see step-by-step analysis before getting the final answer. Higher thinking modes take longer but provide more thorough solutions.

Choosing the Right Mode:

Use think for quick code reviews, think hard for debugging complex issues, think harder for system design problems, and ultrathink for major architectural decisions that affect your entire project.

Project-Level Customization with Claude.md

One of Claude Code's most powerful features is project-level customization using .claude/CLAUDE.md files. This lets you give Claude context about your specific project, coding standards, and preferences.

Set up CLAUDE.md like this:

# Create project-level configuration
mkdir -p .claude
touch .claude/CLAUDE.md

Here’s an example CLAUDE.md file:

# Project Context

This is a Node.js REST API using Express and PostgreSQL.

## Coding Standards

- Use async/await, never callbacks
- All database queries use Prisma ORM
- Write tests with Jest for all new functions
- Follow RESTful conventions

## Project Structure

- `/src/routes` - API endpoints
- `/src/models` - Database models
- `/src/middleware` - Express middleware
- `/tests` - Unit and integration tests

## Preferences

- Use TypeScript for all new files
- Prefer functional programming patterns
- Include JSDoc comments for all functions

This helps Claude understand your project structure automatically. It also helps Claude follow your specific coding standards, suggest appropriate patterns for your tech stack, and remember your preferences across sessions.

Pro tip: Update your CLAUDE.md as your project evolves to keep Claude's suggestions relevant and accurate.

Claude Code Autonomous Development Sessions

Here’s an example of a multi-hour autonomous development session:

cd your-project
claude

Your prompt: "Build a scalable GraphQL API with real-time subscriptions, authentication, rate limiting, and comprehensive testing"

Claude's 6-hour autonomous process:

Claude Code > ultrathink: analyzing requirements and designing architecture

[Creates detailed technical specifications and development plan]

Claude Code > implementing core GraphQL server with Apollo
[Runs: npm install apollo-server-express graphql]
[Creates: server.js, schema/typeDefs.js, resolvers/index.js]

Claude Code > adding authentication and authorization middleware
[Creates: middleware/auth.js, utils/jwt.js, models/User.js]
[Implements JWT strategy with proper error handling]

Claude Code > setting up real-time subscriptions with Redis
[Runs: npm install graphql-redis-subscriptions]
[Configures WebSocket connections, creates subscription resolvers]

Claude Code > implementing rate limiting and security measures
[Adds helmet, express-rate-limit, query complexity analysis]

Claude Code > writing comprehensive test suite
[Creates unit tests, integration tests, load tests]
[Runs: npm test - sees 8 failing tests]

Claude Code > fixing test failures automatically
[Identifies async timing issues, fixes resolver logic]
[Re-runs tests repeatedly until 94/94 tests pass]

Claude Code > performance optimization and caching
[Implements Redis caching, optimizes database queries]
[Adds performance monitoring and logging]

Claude Code > generating comprehensive documentation
[Creates API docs with examples, README, deployment guide]

Claude Code > final validation and cleanup
[Runs full test suite, checks code coverage: 96%]
[Creates production build and deployment scripts]

This represents 6 hours of autonomous work (you can work on other projects while it’s doing this). The result is a production-ready GraphQL API with authentication, real-time features, and comprehensive testing.

Why this works:

• Autonomous Feedback Loops: Claude runs tests, sees failures, fixes them automatically

• Context Awareness: Maintains understanding of the entire project structure

• Self-Correction: Iterates on solutions until they work properly

• Tool Integration: Uses git, npm, testing frameworks seamlessly

Web Search Integration:

Claude Code can search the web to get current information, which is especially useful since AI training data has cutoff dates. This feature helps you stay current with the latest documentation, best practices, and solutions.

Claude Code > search for the latest React 19 features and update my components

[Claude searches web, then continues the conversation with findings]

Claude Code > now apply those new features to the UserProfile component

When Web Search Helps:

• Getting current documentation for new library versions

• Finding solutions to recent error messages or bugs

• Researching latest best practices and patterns

• Comparing current approaches to problems

The web search happens automatically when Claude detects it needs current information, or you can explicitly request it by mentioning "search" or "latest" in your prompts.

Claude Code Keyboard Shortcuts

You can use these keyboard shortcuts to be even more productive:

Essential controls:

• Ctrl+C – Cancel current input or generation

• Ctrl+D – Exit Claude Code session

• Ctrl+L – Clear terminal screen

• Up/Down arrows – Navigate command history

• Esc + Esc – Edit previous message

Multiline Input:

• \ + Enter – Quick escape to create newline (works in all terminals)

• Option+Enter (Mac) / Shift+Enter (configured) – Insert newline

Step 12: Google Gemini CLI

When to Use Gemini vs Claude Code:

Gemini is another CLI-based AI tool that complements Claude Code rather than competing with it. While Claude Code excels at deep reasoning and complex development tasks, Gemini offers unique advantages: massive context windows (1M+ tokens), generous free limits, and powerful multimodal capabilities.

Use Gemini when you:

• Need to analyze entire large codebases at once

• Want to process images, diagrams, or sketches

• Are working within budget constraints (generous free tier)

• Need extremely large context windows for complex projects

Use Claude Code when you:

• Need sophisticated reasoning and problem-solving

• Want autonomous development sessions

• Prefer advanced thinking modes for complex analysis

• Are building production systems requiring detailed planning

The Best Approach: Many developers use both tools strategically – Gemini for analysis and visual inputs, Claude Code for complex development tasks.

Gemini brings Google's AI to your terminal with generous free limits.

Installation

Using npx (recommended for trying):

npx @google/gemini-cli

Global installation:

npm install -g @google/gemini-cli
gemini  # Starts interactive session

Authentication

1. Sign in with Google:

gemini auth login

2. Check status:

gemini auth status

Free limits:

• 60 requests/minute

• 1,000 requests/day with Google account

Built-in tools:

• /memory – Manage conversation memory

• /stats – View usage statistics

• /tools – List available tools

• /mcp – Configure Model Context Protocol servers

Gemini CLI Limitations

Here are some important considerations if you’re planning to use Gemini:

• Rate limits – 60 requests/minute and 1,000/day on free tier

• Google dependency – Requires Google account and internet connection

• Newer tool – Smaller community and fewer resources compared to GitHub Copilot

• Terminal-focused – Less integration with popular IDEs

• Multimodal processing – Image uploads have size limits (20MB)

• Beta features – Some advanced features may be unstable

Unique Gemini Features

Massive Context Window:
Gemini can handle 1 million+ tokens in a single session, meaning it can analyze entire large codebases simultaneously. This is particularly useful for understanding complex system architectures and relationships between many files.

Multimodal Capabilities:
Gemini can process and understand various types of visual content alongside code, making it uniquely powerful for design-to-code workflows and visual debugging.

Turn Your Sketches Into Code

This is really cool: you can literally draw something on paper and Gemini will turn it into working code!

Here's how to do it:

1. Create your sketch: Draw your idea on paper, a whiteboard, or digital tablet

2. Take a photo or screenshot: Use your phone or take a screenshot to capture the sketch digitally

3. Save the image: Save it as JPG, PNG, or WebP format (under 20MB)

4. Show it to Gemini using the command line:

gemini -p "Turn this sketch into a React component with nice styling" sketch.jpg

Alternative methods:

# If you're in an interactive session, you can reference the file:
gemini
> analyze this UI sketch and create the HTML/CSS: @sketch.jpg

# Or drag and drop in supported terminals
gemini
> implement this design as a Vue component
[drag sketch.jpg into terminal]

Gemini then looks at your drawing and creates:

• A working React component that matches your sketch

• Nice CSS styling that makes it look good

• Form validation if you drew a form

• All the code you need to make it work

It's like having a designer and developer that can read your mind!

Fix Bugs By Showing Gemini Images

Got a bug in your UI? You can show Gemini visual information to help debug:

gemini -p "This UI looks broken. What's wrong and how do I fix it?" image.png

Gemini can analyze visual information and tell you:

• What's causing the problem

• Exactly what code to change

• Sometimes even better ways to do it

Turn Architecture Diagrams Into Code

Draw a system diagram and Gemini can build it:

gemini -p "Build this system architecture with Docker and databases" diagram.jpg

Gemini will:

• Understand your diagram

• Create all the Docker files you need

• Set up the databases and connections

• Give you a working system based on your design

Why This Visual Coding is Amazing

Instead of spending hours translating a design into code, you can:

1. Show Gemini your sketch or design

2. Ask Gemini to build it

3. Get working code in minutes instead of hours and just refine as necessary

Most of the time, Gemini gets pretty close to what you wanted on the first try. Even when it's not perfect, it gives you a great starting point that saves you tons of time.

Step 13: Comparing CLI Tools

Here’s a quick table to help you compare the features of Claude Code and Gemini CLI:

Step 14: Advanced CLI Workflows

Workflow 1: Interactive Code Review with Claude Code

Claude Code > review my recent git changes

[Claude analyzes the diff]

Claude Code > fix the security issue you found in the login function

Claude Code > now create a pull request with a good description

Workflow 2: Conversational Architecture Analysis with Gemini

Gemini > analyze this codebase architecture and identify technical debt

[Gemini provides comprehensive analysis]

Gemini > create a migration plan for the database issues you found

Gemini > generate API documentation for the endpoints

Workflow 3: Interactive Test-Driven Development

Claude Code > I need to add payment processing. Start by writing comprehensive tests

[Claude creates test suite]

Claude Code > now implement the payment service to pass these tests

Claude Code > add error handling and edge cases

Combining VS Code with CLI Tools

The Power of Hybrid Workflows:

The most productive developers don't typically choose just one AI tool – they strategically combine VS Code extensions with CLI tools to maximize their efficiency. Each tool has unique strengths, and combining them creates a workflow that's greater than the sum of its parts.

Benefits of Combining Tools:

• Seamless Context Switching: Start with Copilot for rapid development, then seamlessly move to Claude Code for complex analysis without losing momentum

• Complementary Strengths: Use each tool's best features, like Copilot's real-time suggestions + Claude's deep reasoning + Gemini's visual processing

• Continuous Workflow: No need to copy/paste code between tools - work directly in your project with different AI assistance as needed

• Reduced Mental Load: Tools handle different cognitive tasks, letting you focus on creative problem-solving

How to Practically Combine Tools:

Example workflow – building a user dashboard:

1. Start in VS Code with Copilot: Use tab completion to rapidly build basic component structure

2. Keep VS Code open, launch Claude Code: Get architectural advice and refactoring suggestions while maintaining your editor context

3. Switch to Gemini for visual elements: Upload UI mockups to generate matching styles

4. Return to VS Code: Apply all suggestions with Copilot helping with implementation details

Key Integration Points:

• Shared Project Context: All tools work in the same directory, understanding your project structure

• File System Coordination: Changes made by CLI tools are immediately visible in VS Code

• Version Control Integration: Use CLI tools for git operations while VS Code shows visual diffs

Quick Switching Setup

What is Quick Switching?

A quick switching setup refers to configuring your development environment so you can rapidly move between different AI tools without friction. Instead of typing long commands or navigating through multiple setup steps, you create shortcuts that let you instantly access the right AI tool for your current task.

Add to your shell config (.zshrc or .bashrc):

# Quick AI commands for interactive mode
alias cc="claude"
alias gc="gemini"

# For quick one-shot commands when needed
alias think="claude 'think hard:'"
alias analyze="gemini -p 'analyze:'"

Stage 3 Practice Exercises

Exercise 1: Interactive Claude Code Project Setup

1. Create a new project directory

2. Launch: claude

3. Start conversation: "set up a Node.js Express API with PostgreSQL"

4. Continue chatting: "add authentication middleware"

5. Keep going: "now add comprehensive error handling"

6. Review the generated code and ask questions

Exercise 2: Interactive Gemini Codebase Analysis

1. Navigate to an existing project

2. Launch: gemini

3. Start with: "analyze this codebase and identify potential security vulnerabilities"

4. Follow up: "explain the most critical issue in detail"

5. Continue: "create a fix for the authentication vulnerability"

6. Ask: "what other improvements should I prioritize?"

Exercise 3: Interactive Combined Workflow

1. Start with Copilot in VS Code for initial development

2. Switch to interactive Claude Code session for complex refactoring

3. Use interactive Gemini session for codebase analysis and documentation

4. Practice seamlessly moving between tools

Need help with CLI tools? See the Troubleshooting Quick Reference for setup and common issues.

Stage 4: Mastery – Combining Tools and Advanced Workflows

Step 15: Tool Selection Strategy

When to Use Each Tool

Alright, so when should you use each tool in your workflows?

You can use GitHub Copilot as an inline pair-programmer when speed matters. It helps you crank out new functions, get real-time suggestions as you type, and pick up unfamiliar APIs or frameworks on the fly. It’s also handy for quick docs lookups without breaking your flow.

Then you can switch to Claude Code for bigger, messier jobs: complex multi-file refactors, drafting comprehensive tests, and “thinking out loud” about architecture and trade-offs. Here it also helps with Git tasks like guiding you through operations and assembling pull requests.

Finally, you can reach for the Gemini CLI from the terminal when you need to analyze large codebases end-to-end or incorporate visual inputs (like screenshots/diagrams) into your workflow. It’s useful for lots of runs thanks to a free tier, and it fits scenarios where you might want a customizable, script-friendly setup.

Step 16: Understanding MCP – Making AI Tools Work Together

What is MCP?

MCP (Model Context Protocol) is a simple way to give your AI tools extra powers. Think of it like adding apps to your phone – each MCP server adds a new capability to your AI.

Why Should Beginners Care About MCP?

Here’s the problem without MCP: your AI can only work with what it knows and what you tell it. It can't:

• Search the web for current information

• Test your website automatically

• Remember your project details between sessions

• Connect to your databases or APIs

But with MCP servers, your AI can suddenly:

• Get current information – Search Google for latest docs and solutions

• Test your code – Automatically check if your website works

• Remember your project – Keep track of your architecture and decisions

• Connect to tools – Work with GitHub, databases, and more

So instead of manually doing repetitive tasks, your AI can handle them automatically. This means you’ll spend less time googling error messages, manually testing your code, and explaining your project to the AI each session. And you’ll spend more time actually building things.

Simple MCP Examples for Beginners

Here are beginner-friendly examples of what MCP can do for you:

Example 1: Getting Help Without Googling

You: "This CSS isn't working. Find out why and fix it"

Without MCP: You'd google the error, read docs, try solutions
With MCP: AI searches current CSS docs, finds the issue, fixes it automatically

Example 2: Testing Your Website Automatically

You: "Check if my contact form actually works"

Without MCP: You'd manually fill out the form, check email, test edge cases
With MCP: AI fills out the form, verifies email is sent, tests different inputs

Example 3: AI Remembers Your Project

You: "Add a new feature to my todo app"

Without MCP: You explain your database structure, API routes, frontend framework
With MCP: AI already remembers everything and just builds the feature

Ready to Try MCP?

Don't worry if this seems overwhelming! You can start with just one simple MCP server and add more as you get comfortable.

Easy MCP Setup for Beginners

We’ll start with VS Code (as it’s the easiest option):

1. Open VS Code

2. Go to Extensions (Ctrl+Shift+X)

3. Search for "GitHub Copilot MCP" or similar MCP extensions

4. Click "Install"

And you’re done! The extension handles everything automatically

With this, you get web search capability for your AI, basic project memory, and simple automation features.

To test it out, ask your AI: "Search for the latest React best practices and show me an example". If it can search and bring back current information, MCP is working!

Want More MCP Power?

Once you're comfortable with basic MCP, you can explore a more advanced setup below:

• Custom MCP server installation

• Advanced configuration options

• Building your own MCP integrations

For now, the VS Code extension approach above will give you plenty of AI superpowers to get started!

That's MCP in a nutshell! Start with the simple VS Code extension approach above, and you'll quickly see how much more powerful your AI becomes.

Next Steps

• Try the basic VS Code MCP extension

• Test it with simple requests like "search for X and implement it"

• Once comfortable, explore more MCP servers in Stage 4

MCP transforms your AI from a code suggester into a true development partner. The best part? Once you set it up with one tool, it works with all of them!

MCP Not Working?

If the AI says it can't search the web, there are a couple things you can try.

First, check if the MCP extension is actually installed in VS Code. Then try restarting VS Code. Finally, make sure you're asking in a way the AI understands: "Search for X and show me Y".

If VS Code extension won't install, try checking your internet connection or updating VS Code to the latest version. You can also look for "MCP" or "Model Context Protocol" extensions in different names.

If you’re still having trouble, we’ll cover advanced troubleshooting below. Or you can also ask your AI: "Help me troubleshoot MCP setup".

Advanced MCP Setup and Integration

Manual MCP Server Installation

For advanced users who want full control over their MCP setup:

Step 1: Install MCP Servers

Most MCP servers can be installed via npm:

# For web automation and testing
npm install -g @modelcontextprotocol/server-puppeteer

# For web search without API keys
npm install -g @mcp-servers/duckduckgo

# For database access
npm install -g @modelcontextprotocol/server-postgres

Some servers (like GitHub) use Docker instead:

docker pull ghcr.io/github/github-mcp-server

Step 2: Configure Your Tool

Understanding Hierarchical Configuration:

Each AI tool checks for MCP configurations in multiple locations, prioritizing more specific settings over general ones. This means you can have global defaults but override them for specific projects. Think of it like CSS – more specific rules override general ones.

Claude Code has the most flexible setup:

Claude Code configuration hierarchy (checked in order):

1. Project level: .claude/mcp.json (highest priority)

2. Local settings: .claude/settings.local.json

3. Global config: ~/.claude/mcp.json (fallback)

Other tools:

• VS Code: .vscode/mcp.json (project-level only)

• Cursor: .cursor/mcp.json (project-level only)

• Windsurf: Uses VS Code's configuration format

Here’s an example configuration (works in any tool, just adjust the file location):

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-puppeteer"]
    },
    "duckduckgo": {
      "command": "npx",
      "args": ["@mcp-servers/duckduckgo"]
    },
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

Production MCP Servers

1. Game-Changing Cognitive Tools:

Sequential Thinking Server:
This server transforms how AI approaches complex problems by breaking them into logical steps. When you ask for a large feature implementation, instead of jumping straight to code, the AI first creates a detailed plan with phases, dependencies, and decision points.

This is invaluable for refactoring legacy systems or building new features where order of operations matters. The server maintains this planning context throughout the entire development session, ensuring consistent decision-making.

Memory Bank Server:
Eliminates the frustrating need to re-explain your project structure every session. This server creates persistent memory about your architecture choices, coding standards, team preferences, and project goals. When you return to work days later, the AI immediately knows your database schema, API patterns, and even why certain decisions were made. It's like having a project documentation system that stays perfectly synchronized with your development work.

Knowledge Graph Server:
Creates a living map of your codebase relationships – not just file dependencies, but conceptual connections between features, shared utilities, and architectural patterns. When you modify one component, the AI can instantly identify all related areas that might need updates. This prevents bugs caused by missing related changes and helps with impact analysis during refactoring.

2. Web Automation & Testing Servers:

Puppeteer Server:
Provides headless Chrome browser control for comprehensive testing workflows. The AI can automatically navigate your web application, fill forms, click buttons, and verify expected behaviors.

This is particularly powerful for regression testing – the AI can replay user workflows and catch breaking changes before deployment. It also enables screenshot-based testing and performance monitoring automation.

Playwright Server:
Extends browser automation across Chrome, Firefox, and Safari simultaneously. This server is essential for cross-browser compatibility testing and allows the AI to catch browser-specific issues early in development.

Unlike manual testing, the AI can run identical test scenarios across all browsers in parallel, generating comparative reports on functionality and performance differences.

3. Development Integration Servers:

GitHub Server:
Transforms your terminal into a full GitHub interface with AI intelligence. The AI can automatically create branches, manage pull requests, analyze code review comments, and even generate PR descriptions based on code changes. It can also triage issues, assign labels based on content analysis, and maintain project boards by understanding the relationship between issues and actual code changes.

DuckDuckGo Search Server:
Provides real-time access to current documentation and solutions without API costs. When the AI encounters errors or needs to verify best practices, it can instantly search for the most recent information. This is crucial for rapidly evolving technologies where training data becomes outdated quickly. The server also helps with troubleshooting by finding solutions to error messages you haven't seen before.

PostgreSQL Server:
Enables direct database analysis and optimization. The AI can examine query performance, suggest index optimizations, analyze data patterns, and even generate migration scripts. This server is particularly valuable for debugging production issues where the AI needs to understand actual data distribution and query execution patterns rather than just theoretical database design.

4. Helper Tools:

MCP Compass
Helps you find the right MCP server for any task.

These servers turn your AI from a code suggester into a real development partner that can test, search, remember, and automate!

Step 17: Advanced Prompt Engineering

Contextual Prompting

Provide examples:

// Instead of: "create a validation function"
// Use: "create a validation function like this one but for email:
// function validatePhone(phone) { return /^\d{10}$/.test(phone); }"

Specify constraints:

claude "refactor this code to use functional programming, no loops, use map/filter/reduce"

Include edge cases:

gemini -p "implement user authentication that handles: expired tokens, concurrent logins, rate limiting"

Step 18: Building AI-Assisted Development Pipelines

Automated Code Review Pipeline

1. Pre-commit with Copilot:

// .copilot-instructions
"Review all changes for: security issues, performance problems, code style";

2. PR Review with Claude:

claude "review this PR: git diff main..feature-branch"

3. Documentation with Gemini:

gemini -p "generate changelog and update README for these changes"

Test-Driven AI Development

1. Write test specifications:

claude "write comprehensive test specs for a payment processing system"

2. Generate test code:

gemini -p "implement these test specifications using Jest"

3. Implement with Copilot:

   • Use Agent Mode to implement features

   • Tests guide the implementation

Step 19: Creating Your Personal AI Workflow

Setting Up Your Environment

1. VS Code Settings (settings.json):

{
  "github.copilot.enable": {
    "*": true
  },
  "github.copilot.advanced": {
    "inlineCompletions.enable": true,
    "chat.enabled": true
  }
}

2. Claude Code Configuration (~/.claude/settings.json):

{
  "cleanupPeriodDays": 7,
  "permissions": {
    "allow": [
      "Bash(fd:*)",
      "Bash(rg:*)",
      "Bash(ls:*)",
      "WebFetch(domain:github.com)",
      "WebFetch(domain:stackoverflow.com)"
    ],
    "deny": ["WebFetch(domain:medium.com)"]
  }
}

3. Gemini Setup (~/.gemini/config.json):

{
  "defaultModel": "gemini-2.5-pro",
  "contextWindow": "large",
  "safetyMode": "interactive"
}

Custom Commands and Aliases

Shell aliases for common tasks:

# Launch interactive sessions
alias cc='claude'
alias gc='gemini'

# Quick one-shot commands (when you need them)
alias aicommit='claude "create a git commit with a descriptive message"'
alias aireview='claude "review my uncommitted changes"'
alias complexity='gemini -p "analyze code complexity and suggest simplifications"'
alias security='claude "think harder: check for security vulnerabilities"'
alias aidocs='gemini -p "generate comprehensive documentation"'

Final Project: Build a Full Application with AI

Project Requirements

Build a task management API with:

• User authentication

• CRUD operations

• Real-time updates

• Testing suite

• Documentation

Suggested Workflow

Phase 1: Interactive Planning

# Start Claude Code session
claude

Claude Code > ultrathink: design a scalable task management API architecture

[Claude provides detailed analysis]

Claude Code > now break this down into implementation phases

# Switch to Gemini for specifications
gemini

Gemini > create detailed technical specifications for this task management API

Gemini > include database schema and API endpoint specifications

Phase 2: Interactive Implementation

1. Use Copilot Agent Mode for initial setup

2. Implement features with inline Copilot

3. Switch to interactive Claude Code session for complex logic:

Claude Code > implement the user authentication system we planned

Claude Code > now add the task CRUD operations

Claude Code > integrate real-time updates with WebSockets

Phase 3: Interactive Testing & Documentation

# Claude Code session for testing
claude

Claude Code > write comprehensive tests for all API endpoints

Claude Code > add integration tests for the authentication flow

Claude Code > create performance tests for high load scenarios

# Gemini session for documentation
gemini

Gemini > generate comprehensive API documentation with examples

Gemini > create a developer onboarding guide

Phase 4: Interactive Optimization

# Claude Code for performance optimization
claude

Claude Code > analyze and optimize our database queries

Claude Code > implement caching for frequently accessed data

Claude Code > add monitoring and logging

# Gemini for final review
gemini

Gemini > review the entire codebase for improvements

Gemini > identify potential security vulnerabilities

Gemini > suggest deployment optimizations

Measuring Your Progress

Stage 1 Milestones

• Comfortable with tab completion

• Can write effective prompts

• Understand AI limitations

Stage 2 Milestones

• Using multiple models effectively

• Mastering chat modes and agents

• Using advanced chat features

Stage 3 Milestones

• Fluent with CLI tools

• Can combine VS Code and terminal workflows

• Understanding tool strengths

Stage 4 Milestones

• Created custom AI workflow

• Built complete application with AI

• Can teach others AI-assisted development

Stage 4 Practice Exercises

Exercise 1: Tool Selection Mastery

1. Pick a medium-complexity coding task (for example, "Build a URL shortener API")

2. Plan which tool to use for each phase (design, coding, testing, deployment)

3. Execute using your chosen workflow

4. Document what worked well and what you'd change

Exercise 2: Custom Workflow Creation

1. Identify a repetitive development task in your work

2. Design an AI-assisted workflow using multiple tools

3. Test and refine the workflow

4. Create documentation for teammates

Exercise 3: Complete Project Build

1. Build a small but complete application using only AI assistance

2. Use at least 2 different AI tools strategically

3. Include testing, documentation, and deployment

4. Reflect on productivity gains vs traditional development

Continuing Your Journey

Stay Updated

• Follow tool release notes

• Join AI coding communities

• Experiment with new features

Advanced Topics to Explore

• Custom MCP server development

• AI model fine-tuning

• Enterprise deployment strategies

• Team collaboration patterns

Resources for Continued Learning

• Official documentation for each tool

• Community forums and Discord servers

• Open-source AI coding projects

• Conference talks and tutorials

Common AI Issues

Even with the best AI tools, you'll encounter challenges. These issues are normal and manageable once you understand their patterns. Here are the most common problems developers face and practical solutions that actually work.

"My AI suggestions are terrible!"

Problem: AI gives irrelevant or wrong suggestions

Solution:

• Write clearer comments

• Open related files for context

• Start with simpler tasks

• Make sure you're in the right file type

Example Fix:

// Instead of: "make function"
// Try: "create function to validate US phone number format (xxx) xxx-xxxx"

"AI is too slow"

Problem: Waiting too long for suggestions

Solution:

• Check your internet connection

• Close unnecessary programs

• Try a lighter-weight AI tool

• Be patient - complex suggestions take time

"I'm afraid of becoming dependent on AI"

Problem: Worried about losing coding skills

Solution:

• Use AI as a learning tool, not a crutch

• Always understand the code before accepting

• Practice coding without AI regularly

• Focus on problem-solving, not syntax

"It's suggesting outdated code"

Problem: AI suggests old patterns or deprecated methods

Solution:

• Specify versions in your comments

• Keep your tools updated

• Learn to recognize outdated patterns

Example:

// create React functional component using hooks (not class component)

Troubleshooting Quick Reference

Common Issues (All Tools)

GitHub Copilot Issues

Claude Code Issues

Gemini CLI Issues

Emergency Checklist

When nothing works, try these in order:

1. Restart your editor/terminal

2. Check internet connection

3. Verify you're logged in to the right account

4. Update to latest version of the tool

5. Try a different tool (if one fails, others usually work)

6. Ask the AI itself: "Help me troubleshoottooltoolsetup"

What's Next After Completing All Stages?

Once you've mastered the basics, here are some simple next steps:

Working with Your Team

Team AI Workflow Basics

Shared Prompt Libraries:

Building a team prompt library transforms how your entire team uses AI. Start by creating a shared repository where developers document prompts that work well for your specific domain and codebase.

For example, if you're building e-commerce software, create standardized prompts for common tasks like "generate product catalog API endpoints following our REST conventions" or "create payment processing error handling using our standard patterns."

Document successful Agent Mode workflows that team members can reuse. One developer might discover that Claude Code works particularly well for database migrations when given specific context about your schema evolution practices. By sharing these workflows, you prevent each team member from having to discover effective approaches independently.

Tool Standardization:

Team productivity multiplies when everyone uses compatible AI tools. Agree on primary tools based on your team's needs - for instance, GitHub Copilot for all developers to ensure consistent inline assistance, plus Claude Code for complex architectural tasks that benefit from deep reasoning. Establish clear guidelines about when to use autonomous Agent Mode versus collaborative sessions to prevent conflicts and ensure code quality.

Set up shared MCP server configurations that give all team members access to the same enhanced AI capabilities. This might include team-specific servers for your internal APIs, shared database access, or custom tools that understand your deployment pipeline. When everyone has the same AI capabilities, collaboration becomes seamless.

AI-Generated Code Reviews:

Transform your code review process to work effectively with AI-generated code. Establish conventions for tagging AI-generated sections in pull requests - this helps reviewers focus their attention appropriately. Instead of nitpicking syntax that AI typically handles well, reviewers can concentrate on architectural decisions, business logic correctness, and integration patterns that require human judgment.

Implement rigorous testing for AI-generated code, as automated tests catch AI mistakes more reliably than manual review. Create team standards for testing AI output, including edge cases and integration scenarios that AI might miss. This allows you to benefit from AI's speed while maintaining quality through systematic verification.

Document AI tool decisions in commit messages.

Simple Team Setup

Start small and build up:

• Get everyone using the same AI tools first

• Create a shared document of prompts that work well for your projects

• Figure out when your team should use Agent Mode vs regular assistance

• Set up MCP servers for your most important team tools

For Bigger Projects

As your projects grow, you might want to:

• Try different AI models for different tasks (fast ones for simple code, powerful ones for complex problems)

• Create shortcuts for tasks you do often

• Connect AI tools with your existing development workflow

Keep Learning

AI coding tools improve every month! Stay current by:

• Following the tools' release notes (they email updates)

• Joining Discord communities for AI coding

• Trying new features as they come out

Conclusion

Congratulations! You now have everything you need to start your AI-assisted coding journey. Remember, every expert was once a beginner, and with AI as your coding partner, you can learn and grow faster than ever before.

Remember:

• AI doesn't replace your creativity – it amplifies it

• Every suggestion is a learning opportunity

• Mistakes are part of the journey

• The community is here to help

You're not just learning to code with AI – you're learning about the future of software development. In a few months, you'll wonder how you ever coded without it. The developers who embrace AI assistance today will be the leaders of tomorrow.

Happy coding! 🚀

This loop, known as tutorial hell, is where many aspiring developers get stuck. It feels productive, but over time, you start to realize you’re not really learning how to think or build like a developer. You’re just getting better at following instructions.

In this guide, I’ll walk you through exactly how to break free from that cycle. This is not a pseudo-motivational guide. It’s practical steps based on personal experience, so you can finally start building projects with confidence.

Table of Contents

• Why Tutorials Are Not Enough

• How I Broke Free

• Step 1: Accept That You Know Nothing – Yet

• Step 2: Start Simple

• Step 3: Break Down the Project Into Smaller Parts

• Step 4: Don’t Fear Bugs – They’re Signs of Progress

• Step 5: Show Others Your Work

• Step 6: Build More Similar Projects

• Final Thoughts

Why Tutorials Are Not Enough

Tutorials are a great way to get started. They provide structure, simplify complexity, and offer quick wins that make you feel like you’re making progress. In the early stages, that sense of momentum is crucial.

But tutorials can be deceptive. When you’re following along, you’re not solving problems, you’re just replicating solutions that have been worked out for you. It feels productive, but it’s passive learning. You’re learning how to follow instructions, not how to think through a problem or make decisions on your own – that’s the real trap.

Tutorials teach you how to code, but not how to build. You might learn the syntax, but you’re not learning how to build from scratch, troubleshoot unexpected bugs, or take ownership of a project. Over time, after multiple tutorials, this creates a false sense of mastery. It makes you believe that you’re knowledgeable enough, even though you haven’t tested your skills yet.

I know this because I was stuck there too.

How I Broke Free

Breaking free from tutorial hell was not easy. I had to change my mindset and accept something uncomfortable: I didn’t know as much as I thought I did. That realization stung, but it was freeing. I stopped trying to build big, impressive projects – like a Facebook or Netflix clone – and focused instead on small, achievable ones. Projects that challenged me just enough to learn, but not so much that I would burn out.

I also changed how I approached learning. Instead of trying to absorb everything up front, I started with a goal and only learned what I needed to achieve it. This made my learning process more purposeful and, surprisingly, more enjoyable.

What follows are the exact steps that helped me transition from relying on tutorials to building confidently on my own.

Step 1: Accept That You Know Nothing – Yet

It’s natural to feel confident after completing a few tutorial-based projects. But it’s important to manage your expectations and honestly evaluate your skill level. One pitfall I had was overestimating my ability because of the projects I had built following tutorials.

I had to pause and ask myself an important question: Was the success of those projects dependent on me?

After some reflection, the answer was disappointing but clear – they weren’t. I didn’t possess the knowledge I assumed I had. I was just good at following the carefully laid out instructions from the tutorial.

In hindsight, I realized that building a project is more than just writing code. It involves research, planning, and critical thinking – things tutorials often don’t teach or focus on. Writing code is usually the last thing that’s done. This explains why a common complaint from new developers is, “I know the syntax, but I don’t know what to do when building a project”.

Think of tutorials as training wheels. They help you ride a bicycle (build a project) by providing balance (the tutorial), but they don’t teach you how to maintain that balance on your own. When the training wheels come off – when you try to build independently – you fall off the bicycle because you never learned how to ride one without it.

It’s hard to admit that weeks (or months) of following tutorials have not prepared you as well as you thought. But accepting that truth is the first step toward breaking free from tutorial hell. I had to face this reality, and while it wasn’t easy, that moment of clarity became the turning point in my journey.

Step 2: Start Simple

Choosing a good first project was tricky. The common advice I got was to build a project I liked or that solved a personal problem. While that sounded reasonable, it didn’t work for me as a beginner. After several failed attempts, I realized those ideas required more knowledge than I had, so it led to frustration and self-doubt.

Problem-solving is a vital skill for programmers, but in the early stages, choosing a project based on a personal problem can be counterproductive. The complexity often outweighs your current abilities, creating unnecessary pressure.

As a beginner, your priority should be building confidence. The easiest way to do that is by starting with simple projects. A simple project is one you can do without feeling overwhelmed. For me, that was this project on building a QR code generator.

How did I choose it? I used a simple rule: if I looked at the design or the general idea for a project and had no clue on how to build it, I assumed it was beyond my skill level and looked for something simpler. It was not a quick 2-minute decision – I usually gave myself up to 2 two hours to brainstorm. If I was still stuck after that, it was a sign that the project might be too advanced for me.

Platforms like FrontendMentor and iCodeThis offer free project designs categorized by difficulty. They helped me focus on writing code without worrying about what to build from scratch.

At this stage, my goal was not to build something impressive – it was to build something that worked.

Step 3: Break Down the Project into Smaller Parts

When starting a project, it’s easy to feel overwhelmed by its scope. The key to overcoming that feeling is to break up the project into small, manageable pieces. By starting with the easier tasks, you ease into the process, gain momentum, and build confidence before tackling the harder parts.

For my first project, I divided it into two major sections: the background and the card component. Then I split each section into even smaller parts. Here’s an image of the project:

I started by dividing the card component into clear sections:

• The card background.

• The card size.

• The card contents.

Then I broke the card contents even further:

• The QR image

• The heading text

• The subtext

Next, I turned each of those items into a simple to-do list of actionable tasks:

1. Add a background color to the body element.

2. Create the card component.

3. Give the card a fixed width and height.

4. Center the card component.

5. Add the background color of the card component.

6. Add the QR image.

7. Add the heading text.

8. Add the sub-text.

9. Make the card component responsive.

Here’s how that looked in practice for the first few steps:

Task 1: Add a background color to the body

body {
  background: rgb(220, 220, 220);
}

Task 2: Create the card component

<section class="parent">
  <div class="container">
    <!-- content -->
  </div>
</section>

Task 3: Give the card a fixed width and height

.parent {
  width: 320px;
  height: 500px;
}

Task 4: Center the card component

body {
  display: flex;
  align-items: center;
  justify-content: center;
  height: 100vh;
}

After this, I continued with the same approach for the remaining tasks: adding the card’s background, QR image, heading text, subtext, and finally making the card responsive.

Each small win built my confidence and kept me motivated to move forward. By the end, the entire project felt much less intimidating because I could see steady progress at every step.

Breaking a project into smaller parts is not just about staying organized – it's about making the project feel doable. Focusing on one small task at a time, I moved steadily towards completing the project.

You can see the full source code for this project on my GitHub: View the repo here.

Step 4: Don’t Fear Bugs – They’re Signs of Progress

When I finally started building projects, one of the things I dreaded most was encountering an error. Logical errors were fine by me – they were quiet. No red text in the console to feed my insecurities. But those console errors, written in red, were my nightmare. They made me feel like programming wasn’t for me. Like I should give up and do something else.

It took a while, but eventually I learned to see bugs for what they represented at that stage of my journey: signs of progress. Because if I had a bug, it meant I had written enough code for something to go wrong. That was a big step forward from not knowing where to begin.

When you encounter a bug in your code, start by isolating the problem. Check the error message in your console – it’s usually the best clue on what went wrong. Read it carefully to understand what’s causing the issue. If you’re unsure after reading the error message, copy and search the message online. You will likely find solutions on platforms like Stack Overflow.

Then try out the solutions you find, and once the bug is fixed, take the time to understand both the mistake and the solution. This step is crucial. If you don’t know why the error happened, you are more likely to repeat it.

If there is no error message, you’re likely dealing with a logic bug. Review your code for typos, incorrect variable names, or missed function calls. If everything looks fine, try reverting to the last working version of your project, then reapply your changes one step at a time, testing after each update. This approach helps you pinpoint where the bug was introduced.

If you are still stuck, ask for help. A more experienced developer or a colleague can offer a fresh perspective. If you’re working alone and don’t have anyone to ask, take a break. Go for a walk, or do something completely unrelated. Sometimes, you are just mentally tired, and the solution becomes clear once you return with fresh eyes.

And if nothing works, the project may simply be too complex for your current skill level – and that’s okay. Shift your focus back to something simpler to improve your understanding. You can always return to the project later when you are more experienced.

Step 5: Show Others Your Work

Learning is hard – and learning without feedback is even harder. In this journey, it’s difficult to thrive in isolation. Sometimes, the difference between crossing the finish line and giving up lies in the people around us. That is why it’s essential, especially in the early stages, to join programming communities and consistently share your work online.

When I started, I was building in a bubble for a while, but I always felt I wasn’t making enough progress. Eventually, I joined a few tech communities – Frontend Mentor and Javascript.info on Discord – and that helped me tremendously. I met other developers and even collaborated on a project with two of them. Although the group later dissolved due to circumstances beyond our control, the experience was invaluable.

That project taught me things I couldn’t have learned working alone. I learned how to collaborate with teammates across different time zones, use Git more effectively, resolve merge conflicts, and improve my understanding of the DOM traversal methods.

It’s not an easy step, especially if you are not social media inclined, but it is an important one. These communities are made up of people at different stages of their tech careers. Sharing your struggles and encouraging one another creates a much needed support system. On days when your code doesn’t work and you feel like giving up, these communities will remind you that you are not alone.

Another benefit is access to free code reviews and feedback from more experienced developers. Their insights can accelerate your growth, boost your confidence, and help you approach challenges with a fresh perspective.

Step 6: Build More Similar Projects

Completing your first project is a significant milestone. I remember feeling a strong sense of accomplishment and immediately wanted to take on something more complex. But that decision backfired. The next project I chose, an ecommerce site, was well beyond my current ability. I got stuck halfway, lost momentum, and eventually abandoned it. That experience forced me to reassess how I approached my learning.

I realized that the goal at this stage wasn’t to build something impressive, it was to build consistently. So I returned to simpler projects. I built another card component, landing page, and variations of UI components I had already worked on. These may have seemed repetitive, but each one helped me improve and cement my knowledge. I understood layout better, debugged faster, and wrote cleaner code.

By the time I had built several similar projects, I could feel the difference. I wasn’t just building things, I understood what I was doing and why. The growth gave me the confidence to take on more advanced challenges.

If you’ve just completed your first project, don’t rush to build something complex. Focus on projects that align with your current skill level. Repetition will reinforce what you’ve learned, improve your understanding, and give you the confidence to handle more difficult projects when the time comes.

Final Thoughts

At this point, you have built multiple projects, and your confidence as a developer has grown. That progress deserves acknowledgement. Before jumping into the next big challenge, take time to pause and reflect.

Look back on what you've built. Consider how much you've improved. If there are areas where your approach could have been better, refine them. If not, take a moment to appreciate how far you’ve come. That reflection helps you take stock of what you've learnt and prepares you for what comes next.

When you're ready for your next project, choose it carefully. Choose a project more challenging than your last, but not so complex that it disrupts your momentum. Aim for projects that stretch you just enough to push you forward. Sustainable growth is key.

Breaking free from tutorial hell isn't about quitting tutorials altogether. It's about knowing when to stop relying on them and start thinking for yourself. If you stay consistent and keep building, you will grow into a confident, independent developer.

But a model isn’t truly valuable until it’s in production, serving real users and solving real problems.

In this article, you’ll learn how to ship a production-ready ML application built on serverless architecture.

Table of Contents

• Prerequisites

• What We’re Building

  • AI Pricing for Retailers

  • The Models

  • Tuning and Training

  • The Prediction

  • Performance Validation

• The System Architecture

  • Core AWS Resources in the Architecture

• The Deployment Workflow in Action

  • Step 1: Draft Python Scripts

  • Step 2: Configure Feature/Model Stores in S3

  • Step 3: Create a Flask Application with API Endpoints

  • Step 4: Publish a Docker Image to ECR

  • Step 5: Create a Lambda Function

  • Step 6: Configure AWS Resources

• Building a Client Application (Optional)

  • The React Application

• Final Results

• Conclusion

Prerequisites

This project requires some basic experience with:

• Machine Learning / Deep Learning: The full lifecycle, including data handling, model training, tuning, and validation.

• Coding: Proficiency in Python, with experience using major ML libraries such as PyTorch and Scikit-Learn.

• Full-stack deployment: Experience deploying applications using RESTful APIs.

What We’re Building

AI Pricing for Retailers

This project aims to help a middle-sized retailer compete with large players like Amazon.

Smaller companies often can’t afford significant price discounts, so they can face challenges finding optimal price points as they expand their product lines.

Our goal is to leverage AI models to recommend the best price for a selected product to maximize sales for the retailer, and display it on a client-side user interface (UI):

You can explore the UI from here.

The Models

I’ll train and tune multiple models so that when the primary model fails, a backup model gets loaded to serve predictions.

• Primary Model: Multi-layered feedforward network (on the PyTorch library)

• Backup Models (Backups): LightGBM, SVR, and Elastic Net (on the Scikit-Learn library)

The backup models are prioritized based on learning capabilities.

Tuning and Training

The primary model was trained on a dataset of around 500,000 samples (source) and fine-tuned using Optuna's Bayesian Optimization, with grid search available for further refinement.

The backups are also trained on the same samples and tuned using the Scikit-Optimize framework.

The Prediction

All models serve predictions on logged quantity values.

Logarithmic transformations of the quantity data make the distribution denser, which helps models learn patterns more effectively. This is because logarithms reduce the impact of extreme values, or outliers, and can help normalize skewed data.

Performance Validation

We’ll evaluate model performance using different metrics for the transformed and original data, with a lower value always indicating better performance.

• Logged values: Mean Squared Error (MSE)

• Actual values: Root Mean Squared Log Error (RMSLE) and Mean Absolute Error (MAE)

The System Architecture

We’re going to build a complete ecosystem around an AWS Lambda function to create a scalable ML system:

Fig. The system architecture (Created by Kuriko IWAI)

AWS Lambda is a serverless production where a service provider can run the application without managing servers. Once they upload the code, AWS takes on the responsibility of managing the underlying infrastructure.

In the serverless production, the code is deployed as a stateless function that runs only when it’s triggered by an event like HTTP requests or scheduled tasks.

This event-driven nature makes serverless production extremely efficient in resource allocation because:

• There’s no server management: The cloud provider takes care of operational tasks.

• You have automatic scaling: Serverless applications automatically scale up or down based on demand.

• You have pay-per-use billing: Charged for the exact amount of compute resources the application consumes.

Note that other cloud ecosystems like Google Cloud Platform (GCP) and Microsoft Azure offer comprehensive alternatives to AWS. Which one you choose depends on your budget, project type, and familiarity with each ecosystem.

Core AWS Resources in the Architecture

The system architecture focuses on the following points:

• The application is fully containerized on Docker for universal accessibility.

• The container image is stored in AWS Elastic Container Registry (ECR).

• The API Gateway’s REST API endpoints trigger an event to invoke the Lambda function.

• The Lambda function loads the container image from ECR and perform inference.

• Trained models, processors, and input features are stored in AWS S3 buckets.

• A Redis client serves cached analytical data and past predictions stored in the ElastiCache.

And to build the system, we’ll use the following AWS resources:

• Lamda: Serves a function to perform inference.

• API Gateway: Routes API calls to the Lambda function.

• S3 Storage: Serves feature store and model store.

• ElastiCache: Store cached predictions and analytical data.

• ECR: Stores Docker container images to allow Lambda to pull the image.

Each resource requires configuration. I’ll explore those details in the next section.

The Deployment Workflow in Action

The deployment workflow involves the following steps:

1. Draft data preparation, model training, and serialization scripts

2. Configure designated feature store and model store in S3

3. Create a Flask application with API endpoints

4. Publish a Docker image to ECR

5. Create a Lambda function

6. Configure related AWS resources

We’ll now walk through each of these steps to help you fully understand the process.

For your reference, here is the repository structure:

.
.venv/                  [.gitignore]    # stores uv venv
│
└── data/               [.gitignore]
│     └──raw/                           # stores raw data
│     └──preprocessed/                  # stores processed data after imputation and engineering
│
└── models/             [.gitignore]    # stores serialized model after training and tuning
│     └──dfn/                           # deep feedforward network
│     └──gbm/                           # light gbm
│     └──en/                            # elastic net
│     └──production/                    # models to be stored in S3 for production use
|
└── notebooks/                          # stores experimentation notebooks
│
└── src/                                # core functions
│     └──_utils/                        # utility functions
│     └──data_handling/                 # functions to engineer features
│     └──model/                         # functions to train, tune, validate models
│     │     └── sklearn_model
│     │     └── torch_model
│     │     └── ...
│     └──main.py                        # main script to run the inference locally
│
└──app.py                               # Flask application (API endpoints)
└──pyproject.toml                       # project configuration
└──.env                [.gitignore]     # environment variables
└──uv.lock                              # dependency locking
└──Dockerfile                           # for Docker container image
└──.dockerignore
└──requirements.txt
└──.python-version                      # python version locking (3.12)

Step 1: Draft Python Scripts

The first step is to draft Python scripts for data preparation, model training and tuning.

We’ll run these scripts in a batch process because these are resource-intensive and stateful tasks that aren’t suitable for serverless functions optimized for short-lived, stateless, and event-driven tasks.

Serverless functions also can experience cold starts. With heavy tasks in the function, the API gateway would timeout before serving predictions.

src/main.py

import os
import torch
import warnings
import pickle
import joblib
import numpy as np
import lightgbm as lgb
from sklearn.linear_model import ElasticNet
from sklearn.svm import SVR
from skopt.space import Real, Integer, Categorical
from dotenv import load_dotenv

import src.data_handling as data_handling
import src.model.torch_model as t
import src.model.sklearn_model as sk


if __name__ == '__main__': 
    load_dotenv(override=True)
    os.makedirs(PRODUCTION_MODEL_FOLDER_PATH, exist_ok=True)

    # create train, validation, test datasets
    X_train, X_val, X_test, y_train, y_val, y_test, preprocessor = data_handling.main_script()

    # store the trained preprocessor in local storage
    joblib.dump(preprocessor, PREPROCESSOR_PATH)

    # model tuning and training
    best_dfn_full_trained, checkpoint = t.main_script(X_train, X_val, y_train, y_val)

    # serialize the trained model
    torch.save(checkpoint, DFN_FILE_PATH)

    # svr
    best_svr_trained, best_hparams_svr = sk.main_script(
        X_train, X_val, y_train, y_val, **sklearn_models[1]
    )
    if best_svr_trained is not None:
        with open(SVR_FILE_PATH, 'wb') as f:
            pickle.dump({ 'best_model': best_svr_trained, 'best_hparams': best_hparams_svr }, f)

    # elastic net
    best_en_trained, best_hparams_en = sk.main_script(
        X_train, X_val, y_train, y_val, **sklearn_models[0]
    )
    if best_en_trained is not None:
        with open(EN_FILE_PATH, 'wb') as f:
            pickle.dump({ 'best_model': best_en_trained, 'best_hparams': best_hparams_en }, f)

    # light gbm
    best_gbm_trained, best_hparams_gbm = sk.main_script(
        X_train, X_val, y_train, y_val, **sklearn_models[2]
    )

    if best_gbm_trained is not None:
        with open(GBM_FILE_PATH, 'wb') as f:
            pickle.dump({'best_model': best_gbm_trained, 'best_hparams': best_hparams_gbm }, f)

Run the script to train and serialize the models using the uv package management:

$uv venv
$source .venv/bin/activate
$uv run src/main.py

The main.py script includes several key components.

Scripts for Data Handling

These scripts involve loading original data, structure missing values, and engineer features necessary for the future prediction.

src/data_handling/main.py

import os
import joblib
import numpy as np
import pandas as pd
from sklearn.model_selection import train_test_split

import src.data_handling.scripts as scripts
from src._utils import main_logger


# load and save the original data frame in parquet
df = scripts.load_original_dataframe()
df.to_parquet(ORIGINAL_DF_PATH, index=False)

# imputation
df = scripts.structure_missing_values(df=df)

# feature engineering
df = scripts.handle_feature_engineering(df=df)

# save processed df in csv and parquet
scripts.save_df_to_csv(df=df)
df.to_parquet(PROCESSED_DF_PATH, index=False)


# for preprocessing, classify numerical and categorical columns
num_cols, cat_cols = scripts.categorize_num_cat_cols(df=df, target_col=target_col)
if cat_cols:
    for col in cat_cols: df[col] = df[col].astype('string')

# creates training, validation, and test datasets (test dataset is for inference only)
y = df[target_col]
X = df.copy().drop(target_col, axis='columns')
test_size, random_state = 50000, 42
X_tv, X_test, y_tv, y_test = train_test_split(
    X, y, test_size=test_size, random_state=random_state
)
X_train, X_val, y_train, y_val = train_test_split(
    X_tv, y_tv, test_size=test_size, random_state=random_state
)

# transform the input datasets
X_train, X_val, X_test, preprocessor = scripts.transform_input(
    X_train, X_val, X_test, num_cols=num_cols, cat_cols=cat_cols
)

# retrain and serialize the preprocessor
if preprocessor is not None: preprocessor.fit(X)
joblib.dump(preprocessor, PREPROCESSOR_PATH)

Scripts for Model Training and Tuning (PyTorch Model)

The scripts involve initiating the model, searching optimal neural architecture and hyperparameters, and serializing the fully-trained model so that the system can load the trained model when performing inference.

Because the primary model is built on PyTorch and the backups use Scikit-Learn, we’re drafting the scripts separately.

1. PyTorch Models

The training script contains training the model with the validation over a subset of training data.

It contains the early stopping logic when the loss history is not improved for a given consecutive epochs (that is, 10 epochs).

src/model/torch_model/scripts/training.py

import torch
import torch.nn as nn
import optuna # type: ignore
from sklearn.model_selection import train_test_split

from src._utils import main_logger

# device
device_type = device_type if device_type else 'cuda' if torch.cuda.is_available() else 'mps' if torch.backends.mps.is_available() else 'cpu'
device = torch.device(device_type)

# gradient scaler for stability (only applicable for cuba)
scaler = torch.GradScaler(device=device_type) if device_type == 'cuba' else None

# start training
best_val_loss = float('inf')
epochs_no_improve = 0
for epoch in range(num_epochs):
    model.train()
    for batch_X, batch_y in train_data_loader:
        batch_X, batch_y = batch_X.to(device), batch_y.to(device)
        optimizer.zero_grad()

        try:
            # pytorch's AMP system automatically handles the casting of tensors to Float16 or Float32
            with torch.autocast(device_type=device_type):
                outputs = model(batch_X)
                loss = criterion(outputs, batch_y)

                # break the training loop when models return nan or inf
                if torch.any(torch.isnan(outputs)) or torch.any(torch.isinf(outputs)):
                    main_logger.error(
                        'pytorch model returns nan or inf. break the training loop.'
                    )
                    break

            # create scaled gradients of losses
            if scaler is not None:
                scaler.scale(loss).backward()
                scaler.unscale_(optimizer)  # cliping grad
                nn.utils.clip_grad_norm_(model.parameters(), max_norm=1.0)
                scaler.step(optimizer)  # unscales the gradients
                scaler.update()  # updates the scale

            else:
                loss.backward()
                nn.utils.clip_grad_norm_(model.parameters(), max_norm=1.0) # cliping grad
                optimizer.step()

        except:
            outputs = model(batch_X)
            loss = criterion(outputs, batch_y)
            loss.backward()
            optimizer.step()


    # run validation on a subset of the training dataset
    model.eval()
    val_loss = 0.0

    # switch the torch mode
    with torch.inference_mode():
        for batch_X_val, batch_y_val in val_data_loader:
            batch_X_val, batch_y_val = batch_X_val.to(device), batch_y_val.to(device)
            outputs_val = model(batch_X_val)
            val_loss += criterion(outputs_val, batch_y_val).item()

    val_loss /= len(val_data_loader)

    # check if early stop
    if val_loss < best_val_loss - min_delta:
        best_val_loss = val_loss
        epochs_no_improve = 0
    else:
        epochs_no_improve += 1
        if epochs_no_improve >= patience:
            main_logger.info(f'early stopping at epoch {epoch + 1}')
            break

The tuning script uses the study component from the Optuna library to run the Bayesian Optimization.

The study component choose a neural architecture and hyperparameter set to test from the global search space.

Then, it builds, trains, and validates the model to find the optimal neural architecture that can minimize the loss (MSE, for instance).

src/model/torch_model/scripts/tuning.py

import itertools
import pandas as pd
import numpy as np
import optuna
import torch
import torch.nn as nn
import torch.optim as optim
from torch.utils.data import DataLoader, TensorDataset
from sklearn.model_selection import train_test_split

from src.model.torch_model.scripts.pretrained_base import DFN
from src.model.torch_model.scripts.training import train_model
from src._utils import main_logger

# device
device_type = "cuda" if torch.cuda.is_available() else "mps" if torch.backends.mps.is_available() else "cpu"
device = torch.device(device_type)

# loss function
criterion = nn.MSELoss()

# define objective function for optuna
def objective(trial):
    # model
    num_layers = trial.suggest_int('num_layers', 1, 20)
    batch_norm = trial.suggest_categorical('batch_norm', [True, False])
    dropout_rates = []
    hidden_units_per_layer = []
    for i in range(num_layers):
        dropout_rates.append(trial.suggest_float(f'dropout_rate_layer_{i}', 0.0, 0.6))
        hidden_units_per_layer.append(trial.suggest_int(f'n_units_layer_{i}', 8, 256)) # hidden units per layer

    model = DFN(
        input_dim=X_train.shape[1],
        num_layers=num_layers,
        dropout_rates=dropout_rates,
        batch_norm=batch_norm,
        hidden_units_per_layer=hidden_units_per_layer
    ).to(device)

    # optimizer
    learning_rate = trial.suggest_float('learning_rate', 1e-10, 1e-1, log=True)
    optimizer_name = trial.suggest_categorical('optimizer', ['adam', 'rmsprop', 'sgd', 'adamw', 'adamax', 'adadelta', 'radam'])
    optimizer = _handle_optimizer(optimizer_name=optimizer_name, model=model, lr=learning_rate)

    # data loaders
    batch_size = trial.suggest_categorical('batch_size', [32, 64, 128, 256])
    test_size = 10000 if len(X_train) > 15000 else int(len(X_train) * 0.2)
    X_train_search, X_val_search, y_train_search, y_val_search = train_test_split(X_train, y_train, test_size=test_size, random_state=42)
    train_data_loader = create_torch_data_loader(X=X_train_search, y=y_train_search, batch_size=batch_size)
    val_data_loader = create_torch_data_loader(X=X_val_search, y=y_val_search, batch_size=batch_size)

    # training
    num_epochs = 3000 # ensure enough epochs (early stopping would stop the loop when overfitting)
    _, best_val_loss = train_model(
        train_data_loader=train_data_loader,
        val_data_loader=val_data_loader,
        model=model,
        optimizer=optimizer,
        criterion = criterion,
        num_epochs=num_epochs,
        trial=trial,
    )
    return best_val_loss


# start to optimize hyperparameters and architecture
study = optuna.create_study(direction='minimize', sampler=optuna.samplers.TPESampler())
study.optimize(objective, n_trials=50, timeout=600)

# best 
best_trial = study.best_trial
best_hparams = best_trial.params

# construct the model based on the tuning results
best_lr = best_hparams['learning_rate']
best_batch_size = best_hparams['batch_size']
input_dim = X_train.shape[1]
best_model = DFN(
    input_dim=input_dim,
    num_layers=best_hparams['num_layers'],
    hidden_units_per_layer=[v for k, v in best_hparams.items() if 'n_units_layer_' in k],
    batch_norm=best_hparams['batch_norm'],
    dropout_rates=[v for k, v in best_hparams.items() if 'dropout_rate_layer_' in k],
).to(device)

# construct an optimizer based on the tuning results
best_optimizer_name = best_hparams['optimizer']
best_optimizer = _handle_optimizer(
    optimizer_name=best_optimizer_name, model=best_model, lr=best_lr
)

# create torch data loaders
train_data_loader = create_torch_data_loader(
    X=X_train, y=y_train, batch_size=best_batch_size
)
val_data_loader = create_torch_data_loader(
    X=X_val, y=y_val, batch_size=best_batch_size
)

# retrain the best model with full training dataset applying the optimal batch size and optimizer
best_model, _ = train_model(
    train_data_loader=train_data_loader,
    val_data_loader=val_data_loader,
    model=best_model,
    optimizer=best_optimizer,
    criterion = criterion,
    num_epochs=1000
)

# create a checkpoint for serialization (reconstruct the model using the checkpoint)
checkpoint = {
    'state_dict': best_model.state_dict(),
    'hparams': best_hparams,
    'input_dim': X_train.shape[1],
    'optimizer': best_optimizer,
    'batch_size': best_batch_size
}

# serialize the model w/ checkpoint
torch.save(checkpoint, FILE_PATH)

2. Scikit-Learn Models (Backups)

For Scikit-Learn models, we’ll run k-fold cross validation during training to prevent overfitting.

K-fold cross-validation is a technique for evaluating a machine learning model's performance by training and testing it on different subsets of training data.

We define the run_kfold_validation function where the model is trained and validated using 5-fold cross-validation.

src/model/sklearn_model/scripts/tuning.py

from sklearn.model_selection import KFold
from sklearn.metrics import mean_squared_error

def run_kfold_validation(
        X_train,
        y_train,
        base_model,
        hparams: dict,
        n_splits: int = 5, # the number of folds 
        early_stopping_rounds: int = 10,
        max_iters: int = 200
    ) -> float:

    mses = 0.0

    # create k-fold component
    kf = KFold(n_splits=n_splits, shuffle=True, random_state=42)

    for fold, (train_index, val_index) in enumerate(kf.split(X_train)):
        # create a subset of training and validation datasets from the entire training data
        X_train_fold, X_val_fold = X_train.iloc[train_index], X_train.iloc[val_index]
        y_train_fold, y_val_fold = y_train.iloc[train_index], y_train.iloc[val_index]

        # reconstruct a model
        model = base_model(**hparams)

        # start the cross validation
        best_val_mse = float('inf')
        patience_counter = 0
        best_model_state = None
        best_iteration = 0

        for iteration in range(max_iters):
            # train on a subset of the training data
            try:
                model.train_one_step(X_train_fold, y_train_fold, iteration)
            except:
                model.fit(X_train_fold, y_train_fold)

            # make a prediction on validation data 
            y_pred_val_kf = model.predict(X_val_fold)

            # compute validation loss (MSE)
            current_val_mse = mean_squared_error(y_val_fold, y_pred_val_kf)

            # check if epochs should be stopped (early stopping)
           if current_val_mse < best_val_mse:
                best_val_mse = current_val_mse
                patience_counter = 0
                best_model_state = model.get_params()
                best_iteration = iteration
           else:
                patience_counter += 1

           # execute early stopping when patience_counter exceeds early_stopping_rounds
           if patience_counter >= early_stopping_rounds:
                main_logger.info(f"Fold {fold}: Early stopping triggered at iteration {iteration} (best at {best_iteration}). Best MSE: {best_val_mse:.4f}")
                break


        # after training epochs, reconstruct the best performing model 
        if best_model_state: model.set_params(**best_model_state)

        # make prediction
        y_pred_val_kf = model.predict(X_val_fold)

        # add MSEs
        mses += mean_squared_error(y_pred_val_kf, y_val_fold)

    # compute the final loss (avarage of MSEs across folds)
    ave_mse = mses / n_splits
    return ave_mse

Then, for the tuning script, we use the gp_minimize function from the Scikit-Optimize library.

The gp_minimize function is used to tune hyperparameters with Bayesian optimization.

This function intelligently searches the best hyperparameter set that can minimize the model's error, which is calculated using the run_kfold_validation function defined earlier.

The best-performing hyperparameters are then used to reconstruct and train the final model.

src/model/sklearn_model/scripts/tuning.py

from functools import partial
from skopt import gp_minimize


# define the objective function for Bayesian Optimization using Scikit-Optimize
def objective(params, X_train, y_train, base_model, hparam_names):
    hparams = {item: params[i] for i, item in enumerate(hparam_names)}
    ave_mse = run_kfold_validation(X_train=X_train, y_train=y_train, base_model=base_model, hparams=hparams)
    return ave_mse

# create the search space
hparam_names = [s.name for s in space]
objective_partial = partial(objective, X_train=X_train, y_train=y_train, base_model=base_model, hparam_names=hparam_names)

# search the optimal hyperparameters
results = gp_minimize(
    func=objective_partial,
    dimensions=space,
    n_calls=n_calls,
    random_state=42,
    verbose=False,
    n_initial_points=10,
)
# results
best_hparams = dict(zip(hparam_names, results.x))
best_mse = results.fun

# reconstruct the model with the best hyperparameters
best_model = base_model(**best_hparams)

# retrain the model with full training dataset
best_model.fit(X_train, y_train)

Step 2: Configure Feature/Model Stores in S3

The trained models and processed data are stored in the S3 bucket as a Parquet file.

We’ll draft the s3_upload function where the Boto3 client, a low-level interface to an AWS service, initiates the connection to S3:

import os
import boto3
from dotenv import load_dotenv

from src._utils import main_logger

def s3_upload(file_path: str):
    # initiate the boto3 client
    load_dotenv(override=True)
    S3_BUCKET_NAME = os.environ.get('S3_BUCKET_NAME') # the bucket created in s3
    s3_client = boto3.client('s3', region_name=os.environ.get('AWS_REGION_NAME')) # your default region

    if s3_client:
        # create s3 key and upload the file to the bucket
        s3_key = file_path if file_path[0] != '/' else file_path[1:]
        s3_client.upload_file(file_path, S3_BUCKET_NAME, s3_key)
        main_logger.info(f"file uploaded to s3://{S3_BUCKET_NAME}/{s3_key}")
    else:
        main_logger.error('failed to create an S3 client.')

Model Store

Trained PyTorch models are serialized (converted) into .pth files.

Then, these files are uploaded to the S3 bucket, enabling the system to load the trained model when it performs inference in production.

import torch

from src._utils import s3_upload

# model serialization, store in local
torch.save(trained_model.state_dict(), MODEL_FILE_PATH)

# upload to s3 model store
s3_upload(file_path=MODEL_FILE_PATH)

Feature Store

The processed data is converted into a CSV and Parquet file format.

Then, the Parquet files are uploaded to the S3 bucket, enabling the system to load the lightweight data when it creates prediction data to perform inference in production.

from src._utils import s3_upload

# store csv and parquet files in local
df.to_csv(file_path, index=False)
df.to_parquet(DATA_FILE_PATH, index=False)

# store in s3 feature store
s3_upload(file_path=DATA_FILE_PATH)

# trained preprocessor is also stored to transform the prediction data
s3_upload(file_path=PROCESSOR_PATH)

Step 3: Create a Flask Application with API Endpoints

Next, we’ll create a Flask application with API endpoints.

Flask needs to configure Python scripts in the app.py file located at the root of the project repository.

As showed in the code snippets, the app.py file needs to contain the components in order of:

1. AWS Boto3 client setup,

2. Flask app configuration and API endpoint setup,

3. Loading the trained preprocessor, processed input data X_test, and trained models,

4. Invoke the Lambda function via API Gateway, and

5. The local test section.

Note that X_test should never be used during model training to avoid data leakage.

app.py

from flask import Flask
from flask_cors import cross_origin
from waitress import serve
from dotenv import load_dotenv

from src._utils import main_logger

# global variables (will be loaded from the S3 buckets)
_redis_client = None
X_test = None
preprocessor = None
model = None
backup_model = None

# load env if local else skip (lambda refers to env in production)
AWS_LAMBDA_RUNTIME_API = os.environ.get('AWS_LAMBDA_RUNTIME_API', None)
if AWS_LAMBDA_RUNTIME_API is None: load_dotenv(override=True)


#### <---- 1. AWS BOTO3 CLIENT ---->
# boto3 client 
S3_BUCKET_NAME = os.environ.get('S3_BUCKET_NAME', 'ml-sales-pred')
s3_client = boto3.client('s3', region_name=os.environ.get('AWS_REGION_NAME', 'us-east-1'))
try:
    # test connection to boto3 client
    sts_client = boto3.client('sts')
    identity = sts_client.get_caller_identity()
    main_logger.info(f"Lambda is using role: {identity['Arn']}")
except Exception as e:
    main_logger.error(f"Lambda credentials/permissions error: {e}")

#### <---- 2. FLASK CONFIGURATION & API ENDPOINTS ---->
# configure the flask app
app = Flask(__name__)
app.config['CORS_HEADERS'] = 'Content-Type'

# add a simple API endpoint to serve the prediction by price point to test
@app.route('/v1/predict-price/<string:stockcode>', methods=['GET', 'OPTIONS'])
@cross_origin(origins=origins, methods=['GET', 'OPTIONS'], supports_credentials=True)
def predict_price(stockcode):
    df_stockcode = None

    # fetch request params
    data = request.args.to_dict()

    try:
        # fetch cache
        if _redis_client is not None:
            # returns cached prediction results if any without performing inference
            cached_prediction_result = _redis_client.get(cache_key_prediction_result_by_stockcode)
            if cached_prediction_result: 
                return jsonify(json.loads(json.dumps(cached_prediction_result)))

            # historical data of the selected product
            cached_df_stockcode = _redis_client.get(cache_key_df_stockcode)
            if cached_df_stockcode: df_stockcode = json.loads(json.dumps(cached_df_stockcode))


        # define the price range to make predictions. can be a request param, or historical min/max prices
        min_price = float(data.get('unitprice_min', df_stockcode['unitprice_min'][0]))
        max_price = float(data.get('unitprice_max', df_stockcode['unitprice_max'][0]))

        # create bins in the price range. when the number of the bins increase, the prediction becomes more smooth, but requires more computational cost
        NUM_PRICE_BINS = int(data.get('num_price_bins', 100))
        price_range = np.linspace(min_price, max_price, NUM_PRICE_BINS)

        # create a prediction dataset by merging X_test (dataset never used in model training) and df_stockcode
        price_range_df = pd.DataFrame({ 'unitprice': price_range })
        test_sample = X_test.sample(n=1000, random_state=42)
        test_sample_merged = test_sample.merge(price_range_df, how='cross') if X_test is not None else price_range_df
        test_sample_merged.drop('unitprice_x', axis=1, inplace=True)
        test_sample_merged.rename(columns={'unitprice_y': 'unitprice'}, inplace=True)

        # preprocess the dataset
        X = preprocessor.transform(test_sample_merged) if preprocessor else test_sample_merged

        # perform inference
        y_pred_actual = None
        epsilon = 0
        # try using the primary model
        if model:
            input_tensor = torch.tensor(X, dtype=torch.float32)
            model.eval()
            with torch.inference_mode():
                y_pred = model(input_tensor)
                y_pred = y_pred.cpu().numpy().flatten()
                y_pred_actual = np.exp(y_pred + epsilon)

        # if not, use backups
        elif backup_model:
            y_pred = backup_model.predict(X)
            y_pred_actual = np.exp(y_pred + epsilon)


        # finalize the outcome for client app
        df_ = test_sample_merged.copy()
        df_['quantity'] = np.floor(y_pred_actual) # quantity must be an integer
        df_['sales'] = df_['quantity'] * df_['unitprice'] # compute sales
        df_ = df_.sort_values(by='unitprice')

        # aggregate the results by the unitprice in the price range
        df_results = df_.groupby('unitprice').agg(
            quantity=('quantity', 'median'),
            quantity_min=('quantity', 'min'),
            quantity_max=('quantity', 'max'),
            sales=('sales', 'median'),
        ).reset_index()

        # find the optimal price point
        optimal_row = df_results.loc[df_results['sales'].idxmax()]
        optimal_price = optimal_row['unitprice']
        optimal_quantity = optimal_row['quantity']
        best_sales = optimal_row['sales']

        all_outputs = []
        for _, row in df_results.iterrows():
            current_output = {
                "stockcode": stockcode,
                "unit_price": float(row['unitprice']),
                'quantity': int(row['quantity']),
                'quantity_min': int(row['quantity_min']),
                'quantity_max': int(row['quantity_max']),
                "predicted_sales": float(row['sales']),
            }
            all_outputs.append(current_output)

        # store the prediction results in cache
        if all_outputs and _redis_client is not None:
             serialized_data = json.dumps(all_outputs)
            _redis_client.set(
                cache_key_prediction_result_by_stockcode, 
                serialized_data,
                ex=3600     # expire in an hour
            )

        # return a list of all outputs
        return jsonify(all_outputs)

    except Exception as e: return jsonify([])


# request header management (for the process from API gateway to the Lambda)
@app.after_request
def add_header(response):
    response.headers['Cache-Control'] = 'public, max-age=0'
    response.headers['Access-Control-Allow-Origin'] = CLIENT_A
    response.headers['Access-Control-Allow-Headers'] = 'Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token,Origin'
    response.headers['Access-Control-Allow-Methods'] = 'GET, POST, OPTIONSS'
    response.headers['Access-Control-Allow-Credentials'] = 'true'
    return response

#### <---- 3. LOADING PROCESSOR, DATASET, AND MODELS ---->
load_processor()
load_x_test()
load_model()

#### <---- 4. INVOKE LAMBDA ---->
def handler(event, context):
    logger.info("lambda handler invoked.")
    try:
        # connecting the redis client after the lambda is invoked
        get_redis_client()
    except Exception as e:
        logger.critical(f"failed to establish initial Redis connection in handler: {e}")
        return {
            'statusCode': 500,
            'body': json.dumps({'error': 'Failed to initialize Redis client. Check environment variables and network config.'})
        }

    # use the awsgi package to convert JSON to WSGI
    return awsgi.response(app, event, context)


#### <---- 5. FOR LOCAL TEST ---->
# serve the application locally on WSGI server, waitress
# lambda will ignore this section.
if __name__ == '__main__':   
    if os.getenv('ENV') == 'local':
        main_logger.info("...start the operation (local)...")
        serve(app, host='0.0.0.0', port=5002)
    else:
        app.run(host='0.0.0.0', port=8080)

I’ll test the endpoint locally using the uv package manager:

$uv run app.py --cache-clear

$curl http://localhost:5002/v1/predict-price/{STOCKCODE}

The system provided a list of sales predictions for each price point:

Fig. Screenshot of the Flask app local response

Key Points on Flask App Configuration

There are various points you should take into consideration when configuring a Flask application with Lambda. Let’s go over them now:

1. A Few API Endpoints Per Container

Adding many API endpoints to a single serverless instance can lead to monolithic function concern where issues in one endpoint impact others.

In this project, we’ll focus on a single endpoint per container – and if needed, we can add separate Lambda functions to the system.

2. Understanding the handler Function and the role of AWSGI

The handler function is invoked every time the Lambda function receives a client request from the API Gateway.

The function takes the event argument that includes the request details in a JSON dictionary and passes it to the Flask application.

AWSGI acts as an adapter, translating a Lambda event in JSON format into a WSGI request that a Flask application can understand, and converts the application’s response back into a JSON format that Lambda and API Gateway can process.

3. Using Cache Storage

The get_redis_client function is called once the handler function is called by the API Gateway. This allows the Flask application to store or fetch a cache from the Redis client:

import redis
import redis.cluster
from redis.cluster import ClusterNode

_redis_client = None

def get_redis_client():
    global _redis_client
    if _redis_client is None:
        REDIS_HOST = os.environ.get("REDIS_HOST")
        REDIS_PORT = int(os.environ.get("REDIS_PORT", 6379))
        REDIS_TLS = os.environ.get("REDIS_TLS", "true").lower() == "true"
        try:
            startup_nodes = [ClusterNode(host=REDIS_HOST, port=REDIS_PORT)]
            _redis_client = redis.cluster.RedisCluster(
                startup_nodes=startup_nodes,
                decode_responses=True,
                skip_full_coverage_check=True,
                ssl=REDIS_TLS,                  # elasticache has encryption in transit: enabled -> must be true
                ssl_cert_reqs=None,
                socket_connect_timeout=5,
                socket_timeout=5,
                health_check_interval=30,
                retry_on_timeout=True,
                retry_on_error=[
                    redis.exceptions.ConnectionError,
                    redis.exceptions.TimeoutError
                ],
                max_connections=10,            # limit connections for Lambda
                max_connections_per_node=2     # limit per node
            )
            _redis_client.ping()
            main_logger.info("successfully connected to ElastiCache Redis Cluster (Configuration Endpoint)")
        except Exception as e:
            main_logger.error(f"an unexpected error occurred during Redis Cluster connection: {e}", exc_info=True)
            _redis_client = None
    return _redis_client

4. Handling Heavy Tasks Outside of the handler Function

Serverless functions can experience a cold start duration.

While a Lambda function can run for up to 15 minutes, its associated API Gateway has a timeout of 29 seconds (29,000 ms) for a RESTful API.

So, any heavy tasks like loading preprocessors, input data, or models should be performed once outside of the handler function, ensuring they are ready before the API endpoint is called.

Here are the loading functions called in app.py.

app.py

import joblib

from src._utils import s3_load, s3_load_to_temp_file

preprocessor = None
X_test = None
model = None
backup_model = None


# load processor
def load_preprocessor():
    global preprocessor
    preprocessor_tempfile_path = s3_load_to_temp_file(PREPROCESSOR_PATH)
    preprocessor = joblib.load(preprocessor_tempfile_path)
    os.remove(preprocessor_tempfile_path)


# load input data
def load_x_test():
    global X_test
    x_test_io = s3_load(file_path=X_TEST_PATH)
    X_test = pd.read_parquet(x_test_io)


# load model
def load_model():
    global model, backup_model
    # try loading & reconstructing the primary model
    try:
        # first load io file from the s3 bucket
        model_data_bytes_io_ = s3_load(file_path=DFN_FILE_PATH)
        # convert to checkpoint dictionary (containing hyperparameter set)
        checkpoint_ = torch.load(
            model_data_bytes_io_, 
            weights_only=False, 
            map_location=device
        )
        # reconstruct the model
        model = t.scripts.load_model(checkpoint=checkpoint_, file_path=DFN_FILE_PATH)
        # set the model evaluation mode
        model.eval()

    # else, backup model
     except:
        load_artifacts_backup_model()

Step 4: Publish a Docker Image to ECR

After configuring the Flask application, we’ll containerize the entire application on Docker.

Containerization makes a package of the application, including models, its dependencies, and configuration in machine learning context, as a container.

Docker creates a container image based on the instructions defined in a Dockerfile, and the Docker engine uses the image to run the isolated container.

In this project, we’ll upload the Docker container image to ECR, so the Lambda function can access it in production.

After this, we’ll define the .dockerignore file to optimize the container image:

.dockerignore

# any irrelevant data
__pycache__/
.ruff_cache/
.DS_Store/
.venv/
dist/
.vscode
*.psd
*.pdf
[a-f]*.log
tmp/
awscli-bundle/

# add any experimental models, unnecessary data
dfn_bayesian/
dfn_grid/
data/
notebooks/

Dockerfile

# serve from aws ecr 
FROM public.ecr.aws/lambda/python:3.12

# define a working directory in the container
WORKDIR /app

# copy the entire repository (except .dockerignore) into the container at /app
COPY . /app/

# install dependencies defined in the requirements.txt
RUN pip install --no-cache-dir -r requirements.txt

# define commands
ENTRYPOINT [ "python" ]
CMD [ "-m", "awslambdaric", "app.handler" ]

Test in Local

Next, we’ll test the Docker image by building the container named my-app locally:

$docker build -t my-app -f Dockerfile .

Then, we’ll run the container with the waitress server in local:

$docker run -p 5002:5002 -e ENV=local my-app app.py

The -e ENV=local flag sets the environment variable inside the container, which will trigger the waitress.serve() call in the app.py.

In the terminal, you’ll find a message saying the following:

You can also call the endpoint created to see the results returned:

$uv run app.py --cache-clear

$curl http://localhost:5002/v1/predict-price/{STOCKCODE}

Publish the Docker Image to ECR

To publish the Docker image, we first need to configure the default AWS credentials and region:

• From the AWS account console, issue an access token and check the default region.

• Store them in the ~/aws/credentials and ~/aws/config files:

~/aws/credentials

[default] 
aws_secret_access_key=
aws_access_key_id=

~/aws/config

[default]
region=

After the configuration, we’ll publish the Docker image to ECR.

# authenticate the docker client to ECR
$aws ecr get-login-password --region <your-aws-region> | docker login --username AWS --password-stdin <your-aws-account-id>.dkr.ecr.<your-aws-region>.amazonaws.com

# create repository
$aws ecr create-repository --repository-name <your-repo-name> --region <your-aws-region>

# tag the docker image
$docker tag <your-repo-name>:<your-app-version>  <your-aws-account-id>.dkr.ecr.<your-aws-region>.amazonaws.com/<your-app-name>:<your-app-version>

# push
$docker push <your-aws-account-id>.dkr.ecr.<your-aws-region>.amazonaws.com/<your-repo-name>:<your-app-version>

Here’s what’s going on:

• <your-aws-region>: Your default AWS region (for example, us-east-1 ).

• <your-aws-account-id>: 12-digit AWS account ID.

• <your-repo-name>: Your desired repository name.

• <your-app-version>: Your desired tag name (for example, v1.0).

Now, the Docker image is stored in ECR with the tag:

Fig. Screenshot of the AWS ECR console

Step 5: Create a Lambda Function

Next, we’ll create a Lambda function.

From the Lambda console, choose:

• The Container Image option,

• The container image URL from the pull down list,

• A function name of our choice, and

• An architecture type (arm64 is recommended for a better price-performance).

Fig. Screenshot of AWS Lambda function configuration

The Lambda function my-app was successfully launched.

Connect the Lambda function to API Gateway

Next, we’ll add API gateway as an event trigger to the Lambda function.

First, visit the API Gateway console and create REST API methods using the ARN of the Lambda function (press enter or click to view image in full size):

Fig. Screenshot of the AWS API Gateway configuration

Then, add resources to the created API gateway to create an endpoint:
API Gateway > APIs > Resources > Create Resource

• Align the resource endpoint with the API endpoint defined in the app.py.

• Configure CORS (for example, accept specific origins).

• Deploy the resource to the stage.

Going back to the Lambda console, you’ll find the API Gateway is connected as an event trigger:
Lambda > Function > my-app (your function name)

Fig. Screenshot of the AWS Lambda dashboard

Step 6: Configure AWS Resources

Lastly, we’ll configure the related AWS resources to make the system work in production.

This process involves the following steps:

1. The IAM Role: Controls Who to Access Resources

AWS requires IAM roles to grant temporary, secure permissions to users, mitigating security risks related to long-term credentials like passwords.

The IAM role leverages policies to grant accesses to the selected service. Policies can be issued by AWS or customized by the user by defining the inline policy.

It is important to avoid overly permissive access rights for the IAM role.

1. In the Lambda function console, check the execution role:
   Lambda > Function > <FUNCTION> > Permission > The execution role.

2. Set up the following policies to allow the Lambda’s IAM role to handle necessary operations:

   • Lambda AWSLambdaExecute: Allows executing the function.

   • EC2 Inline policy: Allows controlling the security group and the VPC of the Lambda function.

   • ECR AmazonElasticContainerRegistryPublicFullAccess + Inline policy: Allows storing and pulling the Docker image.

   • ElastiCache AmazonElastiCacheFullAccess + Inline policy: Allows storing and pulling caches.

   • S3: AmazonS3ReadOnlyAccess + Inline policy: Allows reading and storing contents.

Now, the IAM role can access these resources and perfo the allowed actions.

2. The Security Group: Controls Network Traffic

A security group is a virtual firewall that controls inbound and outbound network traffic for AWS resources.

It uses stateful (allowing return traffic automatically) “allow-only” rules based on protocol, port, and IP address, where it denies all traffic by default.

Create a new security group for the Lambda function:
EC2 > Security Groups > <YOUR SECURITY GROUP>

Now, we’ll want to setup inbound / outbound traffic rules.

The inbound rules:

• S3 → Lambda:Type*: HTTPS /* Protocol*: TCP /* Port range*: 443 / Source: Custom**

• ElastiCache → Lambda:Type*: Custom TCP /* Port range*: 6379 / Source: Custom**

*Choose the created security group for the Lambda function as a custom source.

The outbound rules:

• Lambda → Internet: Type*: HTTPS /* Protocol*: TCP /* Port range*: 443 /* Destination*: 0.0.0.0/0*

• ElastiCache → Internet: Type*: All Traffic /* Destination*: 0.0.0.0/0*

3. The Virtual Private Cloud (VPC)

A Virtual Private Cloud (VPC) provides a logically isolated private network for the AWS resources, acting as our own private data center within AWS.

AWS can create a Hyperplane ENI (Elastic Network Interface) for the Lambda function and its connected resources in the subnets of the VPC.

Though it’s optional, we’ll use the VPC to connect the Lambda function to the S3 storage and ElastiCache.

This process involves:

1. Creating a VPC endpoint from the VPC console:VPC > Create VPC.

2. Creating an STS (Security Token Service) endpoint:
   VPC > PrivateLink and Lattice > Endpoints > Create Endpoint >

   • Type*: AWS Service*

   • Service name*: com.amazonaws.<YOUR REGION>.sts*

   • Type*: Interface*

   • VPC: Select the VPC created earlier.

   • Subnets*: Select all subnets.*

   • Security groups*: Select the security group of the Lambda function.*

   • Policy*: Full access*

   • Enable DNS names

The VPC must have a dedicated endpoint for STS to receive temporary credentials from STS.

3. Create an S3 endpoint in the VPC:
   VPC > PrivateLink and Lattice > Endpoints > Create Endpoint >

   • Type*: AWS Service*

   • Service name*: com.amazonaws.<YOUR REGION>.s3*

   • Type*: Gateway*

   • VPC: Select the VPC created earlier.

   • Subnets*: Select all subnets.*

   • Security groups*: Select the security group of the Lambda function.*

   • Policy*: Full access*

Lastly, check the security group of the Lambda function and ensure that its VPC ID directs to the VPC created: EC2 > Security Group > <YOUR SECURITY GROUP FOR THE LAMDA FUNCTION> > VPC ID.

That’s all for the deployment flow.

We can now test the API endpoint in production. Copy the Invoke URL of the deployed API endpoint: API Gateway > APIs > Stages > Invoke URL. Then call the API endpoint and check if it responds predictions:

$curl -H 'Authorization: Bearer YOUR_API_TOKEN' -H 'Accept: application/json' \
     '<INVOKE URL>/<ENDPOINT>'

For logging and debugging, we’ll use the LiveTail of CloudWatch: CloudWatch > LiveTail.

Building a Client Application (Optional)

For full-stack deployment, we’ll build a simple React application to display the prediction using the recharts library for visualization.

Other options for quick frontend deployment include Streamlit or Gradio.

The React Application

The React application creates a web page that fetches and visualizes sales predictions from an external API, recommending an optimal price point.

The app uses useState to manage its data and state, including the selected product, the list of sales predictions, and the loading/error status.

When the user initiates a request, a useEffect hook triggers a fetch request to a Flask backend. It handles the API response as a data stream, processing it line by line to progressively update the predictions.

The AreaChart from the recharts library then visualizes this data. The X-axis represents the price and the Y-axis represents the sales. The chart updates in real-time as the data streams in. Finally, the app displays the optimal price once all the predictions are received.

App.js: (in a separate React app)

import { useState, useEffect } from "react"
import { AreaChart, Area, XAxis, YAxis, CartesianGrid, Tooltip, ResponsiveContainer, ReferenceLine } from 'recharts'


function App() {
  // state
  const [predictions, setPredictions] = useState([])
  const [start, setStart] = useState(false)
  const [isLoading, setIsLoading] = useState(false)

  // product data
  let selectedStockcode = '85123A'
  let selectedProduct = productOptions.filter(item => item.id === selectedStockcode)[0]

  // api endpoint
  const flaskBackendUrl = "YOUR FLASK BACKEND URL"

  // create chart data to display
  const chartDataSales = predictions && predictions.length > 0
    ? predictions
      .map(item => ({
        price: item.unit_price,
        sales: item.predicted_sales,
        volume: item.unit_price !== 0 ? item.predicted_sales / item.unit_price : 0
      }))
      .sort((a, b) => a.price - b.price)
    : [...selectedProduct['histPrices']]

  // optimal price to display
  const optimalPrice = predictions.length > 0
    ? predictions.sort((a, b) => b.predicted_sales - a.predicted_sales)[0]['unit_price']
    : 0

  // fetch prediction results
  useEffect(() => {
    const handlePrediction = async () => {
      setIsLoading(true)
      setPredictions([])
      const errorPrices = selectedProduct['errorPrices']

      await fetch(flaskBackendUrl)
        .then(res => {
          if (res.status !== 200) { setPredictions(errorPrices); setIsLoading(false); setStart(false) }
          else return Promise.resolve(res.clone().json())
        })
        .then(res => {
          if (res && res.length > 0) setPredictions(res)
          else setPredictions(errorPrices)
          setIsLoading(false); setStart(false)
        })
        .catch(err => { setPredictions(errorPrices); setIsLoading(false); setStart(false) })
        .finally(setStart(false))
    }

    if (start) handlePrediction()
    if (predictions && predictions.length > 0) setStart(false)
  }, [flaskBackendUrl, start])


  // render
  if (isLoading) return <Loading />
  return (
    <div>
      <ResponsiveContainer width="100%" height="100%">
        <AreaChart
          key={chartDataSales.length}
          data={chartDataSales.sort(data => data.unit_price)}
          margin={{ top: 10, right: 30, left: 0, bottom: 0 }}
        >
          <CartesianGrid strokeDasharray="3 3" strokeOpacity={0.6} />

          <XAxis
            dataKey="price"
            label={{ value: "Unit Price ($)", position: "insideBottom", offset: 0, fontSize: 12, marginTop: 10 }}
            tickFormatter={(tick) => `$${parseFloat(tick).toFixed(2)}`}
            tick={{ fontSize: 12 }}
            padding={{ left: 20, right: 20 }}
          />

          <YAxis
            label={{ value: "Predicted Sales ($)", angle: -90, position: "insideLeft", fontSize: 12 }}
            tick={{ fontSize: 12 }}
            tickFormatter={(tick) => `$${tick.toLocaleString()}`}
          />

          {/* tooltips with the prediction result data */}
          <Tooltip
            contentStyle={{
              borderRadius: '8px',
              padding: '10px',
              boxShadow: '0px 0px 15px rgba(0,0,0,0.5)'
            }}
            formatter={(value, name) => {
              if (name === 'sales') {
                return [`$${value.toFixed(4)}`, 'Predicted Sales']
              }
              if (name === 'volume') {
                return [`${value.toFixed(0)}`, 'Volume']
              }
              return value
            }}
            labelFormatter={(label) => `Price: $${label.toFixed(2)}`}
          />

          {/* chart area = sales */}
          <Area
            type="monotone"
            dataKey="sales"
            fillOpacity={1}
            fill="url(#colorSales)"
          />

          {/* vertical line for the optimal price */}
          {optimalPrice &&
            <ReferenceLine
              x={optimalPrice}
              strokeDasharray="4 4"
              ifOverflow="visible"
              label={{
                value: `Optimal Price: $${optimalPrice !== null && optimalPrice > 0 ? Math.ceil(optimalPrice * 10000) / 10000 : ''}`,
                position: "right",
                fontSize: 12,
                offset: 10
              }}
            />
          }
        </AreaChart>
      </ResponsiveContainer>

      {optimalPrice && <p>Optimal Price: $ {Math.ceil(optimalPrice * 10000) / 10000}</p>}

    </div>
  )
}

export default App