DEV Community: Harshdeep Singh

Full Stack Developer Portfolio Lessons: What I Learned Building 10+ Projects

Harshdeep Singh — Tue, 02 Jun 2026 21:33:43 +0000

I applied for a role at a mid-sized SaaS company about two years into my career. Strong company, interesting problem, good pay. I sent my application, got a recruiter callback, and then nothing for two weeks. When the feedback finally came: "We went with candidates with a stronger portfolio presence."

I had 23 GitHub repositories. I had a portfolio site. I had projects. What I didn't have — and what I didn't understand for another six months — was a portfolio that told a story. I had code. Not evidence of thinking, decision-making, or the ability to ship something real.

I've since built, rebuilt, and advised on a lot of developer portfolios. I've seen what gets people calls and what gets them ghosted. This isn't a guide about which framework to use or how to pick colors. It's about what actually moves the needle — the things I wish someone had told me in year one.

Lesson 1: Two Great Projects Beat Twenty Mediocre Ones

The instinct is to fill the portfolio. More projects = more evidence of experience. This is wrong.

A hiring manager or engineering lead looking at your portfolio has about three minutes. They're going to look at your two or three most prominent projects, click one or two live demo links, and form an opinion. If they see twenty repositories and most of them are "Todo App v2," "Weather App," "Netflix Clone," "Portfolio v1 through v6" — they've already categorized you as someone who builds tutorials, not someone who builds things.

The better approach: three to five projects, each with:

A real problem it solves (not "I wanted to learn React")
A live deployment that actually works
A README that explains why you made the decisions you made
Enough complexity to have generated at least one interesting engineering problem

Projects that tend to work: tools you built because you were frustrated with an existing tool, apps solving problems you personally had, projects where you integrated with a real API or real data source, anything with a live user base (even 10 users counts).

Projects that tend not to work: tutorial clones (unless heavily modified), apps that only run locally, projects that stop at the MVP and never got deployed, apps with the same name as thousands of other developer portfolios ("My Todo App," "My Weather App").

If you have 20 repos, that's fine. Pin your three best to your GitHub profile. Don't make people wade through everything — curate it.

Lesson 2: Case Studies Beat Code Screenshots

Here's the thing about showing a screenshot of your app: everyone can make an app look good in a screenshot. Filters, cropping, ideal state data. A screenshot shows what you built. It tells me nothing about how you think.

A case study shows how you think. And how you think is what you're being hired for.

A case study doesn't have to be a five-page document. Two or three paragraphs on each project covering:

The problem. What did you set out to solve? Be specific. Not "I wanted to learn Next.js" — that's not a problem. "Resume submissions were getting lost in email threads, so I built a tool that…" — that's a problem.
Your approach and the tradeoffs you considered. What did you think about? What did you try first? What didn't work? This is where you demonstrate that you can make technical decisions, not just execute instructions.
What you shipped. Not every feature you imagined — what you actually built and deployed.
What you'd do differently. This one is disarming in the best way. It shows self-awareness, reflection, and the ability to evaluate your own work critically. Engineers who can't critique their own code can't grow.

I've seen portfolios with two projects and a well-written case study for each that outperformed portfolios with fifteen projects and no context. The case study gives an interviewer something to ask about. It shows you've thought deeply about the work. It makes the technical interview easier because you already answered half the questions in writing.

Lesson 3: If It's Not Deployed, It Doesn't Exist

This is the blunt version. A project that runs on localhost is a project you're still working on. It is not a portfolio piece.

I've reviewed portfolios where the "live demo" link was a localhost URL. I've seen GitHub repositories where the README says "deployment in progress" with a date from 18 months ago. I've seen apps in screenshots that couldn't actually run because they depended on a local database with no seed data.

Deploying has never been easier or cheaper. There's no excuse for a portfolio project that isn't live.

Frontend: Vercel (free), Netlify (free), Cloudflare Pages (free). Zero configuration for most frameworks.
Backend / API: Railway (free tier), Render (free tier), Fly.io (free tier). These all support Node.js, Python, Go, whatever you're running.
Database: MongoDB Atlas free tier (512MB), Supabase free tier (PostgreSQL), PlanetScale free tier (MySQL).
Full stack: Railway handles full-stack apps well. Render lets you deploy multiple services from one repo. Both have one-click GitHub deploys.

Total cost of a deployed side project: $0, with a free domain subdomain. Add a custom domain for $12/year and you have a genuinely professional-looking production deployment.

There's a secondary benefit to deploying: it forces you to actually finish things. There's a long list of problems you don't know about until you deploy — environment variable management, CORS configuration, database connection pooling, static asset serving. Deploying is part of building. A portfolio project that's never been deployed has never been truly finished.

Lesson 4: The README Is Your First Interview

When a hiring manager or senior engineer clicks the GitHub link from your portfolio, the first thing they see is the README. If it says "A project I made for learning" or has no description at all, they've already lost interest.

The README is where you make the technical case for yourself before you're in the room. Here's what a good one contains:

First paragraph: What does this thing do and why does it exist? Not "this is a web app" — tell me the specific problem it solves. One or two sentences.

Tech stack and why: Not just a logo grid. A sentence about why you chose what you chose. "Used PostgreSQL instead of MongoDB because the data has strong relational structure with lots of joins." "Chose Next.js App Router over CRA because we needed SSR for SEO and a built-in API layer." These sentences prove you made intentional decisions.

Screenshots or a GIF: A 10-second screen recording of the app working is worth a thousand words. Not staged, not filtered — just the actual app.

How to run it: Clear, complete instructions. If I clone it and follow your README and it doesn't work, that's a flag. If it works first try, that's a positive signal — it means you document carefully and you care about the developer experience of your code.

Known limitations / what you'd do differently: One paragraph. Shows maturity. "If I built this again, I'd use a message queue for the email sending instead of doing it synchronously in the request lifecycle — it caused timeouts under load."

This README takes maybe 45 minutes to write. It dramatically changes how your project is perceived.

Lesson 5: Get Your Own Domain

This one is simple and often skipped. Your portfolio should live at yourname.com or yourname.dev — not github.io/yourname/portfolio or yourname.netlify.app.

A custom domain does two things: it signals that you take yourself seriously as a professional, and it's a much better URL to put on a resume, LinkedIn, or business card. "theharshdeepsingh.com" looks intentional. "harshdeep-singh-13.github.io/portfolio-2024" looks like a homework assignment.

Domains cost $10–15 per year. That is a rounding error in any budget. Buy yours today. Redirect your GitHub Pages / Vercel / Netlify deployment to it. It takes 30 minutes and it never needs to change — you own it.

A note on choosing the domain: use your name. Not your "developer brand" or a clever handle. Names rank in Google. If someone searches for you, they should find your portfolio at the top. A personal domain with your name is one of the easiest SEO wins available to you.

Lesson 6: One AI Integration Changes Everything

Here's the hiring landscape in 2025 from a practical perspective: companies want developers who can work with AI, build on top of AI APIs, and integrate AI capabilities into existing products. This is new enough that not everyone has done it. Old enough that "I'm planning to learn it" isn't a compelling answer.

One project with a real AI integration moves you from the pile to the shortlist. Not because AI is a magic word — but because it demonstrates technical currency. You know what the OpenAI API looks like. You've dealt with token limits and streaming and prompt engineering. You've thought about cost and abuse prevention. These are all non-trivial.

What counts:

A feature in an existing project that uses GPT-4o, Claude, or Gemini for a specific, meaningful task (not "ask AI anything" — that's too vague to be impressive)
A RAG (retrieval-augmented generation) pipeline — document upload, embedding, search, answer generation
An agent that takes structured actions based on LLM output (web search, database queries, API calls)
A classification or extraction feature that uses an LLM where a simpler approach wouldn't have worked

What doesn't count:

"Used ChatGPT to help me write this code" (everyone does this)
A UI wrapper around ChatGPT that just passes prompts through (no engineering decision was made)
A project that uses AI for something that a regex would handle just as well

The bar isn't high. Ship one genuinely useful AI feature, document the decisions you made (model selection, prompt design, cost management), and you're ahead of the majority of developers applying for the same roles.

Watch: Portfolio Reviews — What Actually Works

Weak vs. Strong Portfolio Signals

Signal
Weak
Strong

Project count
20+ repos, half are tutorial clones
3–5 curated projects, each with a clear purpose

Project quality
Todo apps, weather apps, Netflix/Airbnb clones
Tools solving real problems, deployed with real users

Live demos
No live link, "works on my machine," localhost screenshots
Deployed URLs that load in under 3 seconds

Documentation
No README or "this is a project I made"
Problem statement, tech choices explained, known limitations

Tech recency
Create React App, class components, outdated dependencies
Current stack (Next.js 15, TypeScript, modern APIs)

AI integration
None, or "used AI to help me code"
One genuine AI feature with documented engineering decisions

Domain
github.io/username or platform subdomain
yourname.com — personal, memorable, professional

Case studies
Screenshots in a grid with a "View Project" button
Problem → approach → tradeoffs → outcome — per project

What I'd Do on Day 1 If I Were Starting Over

If I were a developer today with no portfolio and a job to find, here's the exact sequence I'd follow:

Day 1: Register firstnamelastname.com. It costs $12. Do it before you build anything. Having the domain makes the whole thing feel real and gives you a deadline.

Week 1: Identify one problem I genuinely have — something I do manually that should be automated, something I've searched for that doesn't exist, something at work that annoys me. Build the simplest version of the solution. Not a full product — a working tool. One feature, deployed.

Week 2: Write the case study. What was the problem? What did I consider? What did I ship? What didn't make the cut? What would I do differently? Two or three paragraphs per question. This is more valuable than the code itself.

Week 3: Add an AI integration to the project — something that actually makes the tool better, not a bolt-on. Even a single endpoint that uses an LLM for classification or text generation counts, as long as it's doing something a simpler approach couldn't.

Week 4: Point the domain at the project. Add the URL to LinkedIn's "Featured" section and your resume. Ask one person who is not a developer to try using the tool and tell you what they're confused by. Fix those things.

That's it. One good project, one good case study, one AI integration, a custom domain, a LinkedIn presence. Four weeks. That's a portfolio that gets callbacks. Everything else is refinement.

TL;DR

Curate, don't accumulate. Three deployed projects with case studies beat twenty unfinished repos. Pin your best work. Hide the rest.
Write case studies for every project. Problem → approach → tradeoffs → outcome → what you'd do differently. This is what interviews are about anyway — you're just answering in advance.
Nothing without a live URL. Free tiers on Vercel, Railway, and Render make deployment trivial. An undeployed project is an unfinished project.
The README is your first impression from GitHub. Spend 45 minutes on it. Explain the why, not just the what. Include how to run it. List the limitations. That's a professional developer.
Get the domain. yourname.com, $12, 30 minutes. It signals intent and makes your portfolio findable in Google searches by your own name.
Build one thing with a real AI integration. Not a ChatGPT wrapper — a feature that uses an LLM to solve a specific problem in your project, with documented decisions about model selection and prompt design.

How to Integrate the OpenAI API into a Production Express App

Harshdeep Singh — Tue, 02 Jun 2026 21:28:00 +0000

Last year I helped a startup integrate the OpenAI API into their product. It was a chat feature — users could ask questions about their data and get natural language answers. The integration took about a day. Three days after launch, the founder messaged me: "Hey, something's wrong. Our AWS bill just showed an unexpected charge."

It was $340. For three days. They had 60 users.

The issue wasn't a bug — it was that production API usage looks nothing like a tutorial. The tutorial shows you openai.chat.completions.create() and returns a response. The tutorial doesn't show you what happens when users send 500-token messages, when they open 15 browser tabs each maintaining their own chat context, or when one user fires requests 30 times per minute because they think it's broken.

This guide covers what the tutorials skip: rate limiting, token counting, cost guards, streaming, error handling with retries, and model selection. These aren't optional additions — they're what separates a demo from a production feature.

Why Production Is Different

Here's the gap between tutorial code and production code, stated plainly:

Concern
Tutorial Code
Production Code

Cost control
Not mentioned
Token counting, spending limits, model selection by task

Rate limiting
Not mentioned
Per-user and per-IP limits to prevent abuse

Error handling
try/catch that logs to console
Typed errors, retries with backoff, user-facing messages

Response delivery
Wait for full completion, return at once
Streaming via SSE — response appears as it generates

Context management
Each request is independent
Conversation history managed, truncated at token limit

Secrets management
API key hardcoded or in .env (no rotation)
Rotation strategy, usage monitoring, per-feature keys

Let's build a production-grade Express API that addresses all of this. We'll go layer by layer.

The Architecture

┌─────────────────────────────────────────────────────────┐
│ CLIENT (Browser / Mobile) │
│ POST /api/chat { messages: [...] } │
│ GET /api/chat/stream (SSE) │
└──────────────────────┬──────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ EXPRESS MIDDLEWARE STACK │
│ │
│ 1. express-rate-limit (10 req/min per IP) │
│ 2. tokenGuard() (reject if > 4,000 tokens) │
│ 3. auth middleware (verify user session) │
└──────────────────────┬──────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ ROUTE HANDLER │
│ │
│ Select model by task type │
│ Build messages array from context │
│ Call openai.chat.completions.create() │
│ Stream or return response │
└──────────────────────┬──────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ OPENAI API │
│ Model: gpt-4o-mini (default) / gpt-4o (complex tasks) │
└─────────────────────────────────────────────────────────┘

Project Setup

mkdir express-openai && cd express-openai
npm init -y
npm install express openai express-rate-limit tiktoken dotenv
npm install --save-dev nodemon

# .env
OPENAI_API_KEY=sk-proj-your-key-here
PORT=3001

Step 1: The OpenAI Client (Configured for Production)

Don't instantiate the OpenAI client inside route handlers. Create it once, configure it for production, and export it:

// src/openaiClient.js
import OpenAI from "openai";

export const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  maxRetries: 3,     // retry on transient failures (rate limits, timeouts)
  timeout: 30_000,   // 30 second timeout — don't hang forever
});

// Model selection by task complexity
export const MODELS = {
  fast: "gpt-4o-mini",   // classification, simple Q&A, summarization
  smart: "gpt-4o",        // complex reasoning, code generation, analysis
};

The maxRetries: 3 and timeout settings are critical. Without a timeout, a hung OpenAI request will keep your Express server's response object open indefinitely — and if you're running on a serverless function, you'll pay for that idle time.

Step 2: Token Counting and Cost Guard

The tiktoken library is OpenAI's own tokenizer — it counts tokens the exact same way the API does. Use it to reject requests before they hit the API:

// src/tokenCounter.js
import { encoding_for_model } from "tiktoken";

export function countMessageTokens(messages, model = "gpt-4o-mini") {
  const enc = encoding_for_model(model);
  let totalTokens = 0;

  for (const message of messages) {
    totalTokens += 4; // every message has ~4 tokens of overhead
    if (message.role) totalTokens += enc.encode(message.role).length;
    if (message.content) totalTokens += enc.encode(message.content).length;
    totalTokens += 1; // reply primer
  }

  enc.free(); // tiktoken requires explicit cleanup
  return totalTokens + 3; // overall reply overhead
}

// Express middleware — rejects requests over the token limit
export function tokenGuard(maxInputTokens = 4_000) {
  return (req, res, next) => {
    const messages = req.body?.messages;

    if (!Array.isArray(messages)) {
      return res.status(400).json({ error: "messages must be an array" });
    }

    const tokenCount = countMessageTokens(messages);

    if (tokenCount > maxInputTokens) {
      return res.status(400).json({
        error: `Message too long: ${tokenCount} tokens (limit: ${maxInputTokens}). Shorten your message or clear the conversation.`,
        tokenCount,
        limit: maxInputTokens,
      });
    }

    req.tokenCount = tokenCount; // pass downstream for logging
    next();
  };
}

A note on the limit: GPT-4o-mini's context window is 128K tokens, so 4,000 is conservative. But conservative is good here — a user who sends 30,000 tokens in one request is either doing something unusual or has a bug in their client. Reject it, log it, and let them know to clear their context.

Step 3: Rate Limiting

One user shouldn't be able to drain your API budget or trigger OpenAI rate limits for everyone else. Add rate limiting before the AI routes:

// src/middleware/rateLimiter.js
import rateLimit from "express-rate-limit";

export const aiRateLimiter = rateLimit({
  windowMs: 60 * 1000,  // 1-minute window
  max: 15,               // 15 requests per minute per IP
  standardHeaders: true, // return RateLimit headers
  legacyHeaders: false,
  message: {
    error: "Too many requests. Please wait a moment before trying again.",
    retryAfter: 60,
  },
  keyGenerator: (req) => {
    // Use authenticated user ID if available, otherwise fall back to IP
    return req.user?.id || req.ip;
  },
});

// Stricter limit for expensive models
export const smartModelLimiter = rateLimit({
  windowMs: 60 * 1000,
  max: 5,
  message: { error: "Too many complex requests. Rate limited for 60 seconds." },
});

Step 4: Error Handling with Typed OpenAI Errors

The OpenAI Node SDK throws typed errors. Use them — don't just check err.message:

// src/middleware/openaiErrorHandler.js
import OpenAI from "openai";

export function handleOpenAIError(err, req, res, next) {
  if (err instanceof OpenAI.APIError) {
    console.error(`OpenAI API error: ${err.status} ${err.name}`, {
      message: err.message,
      requestId: err.headers?.["x-request-id"],
    });

    if (err.status === 429) {
      return res.status(429).json({
        error: "AI service is busy. Please try again in a moment.",
        retryAfter: parseInt(err.headers?.["retry-after"] || "5"),
      });
    }

    if (err.status === 400) {
      return res.status(400).json({
        error: "Invalid request to AI service. Check your message format.",
      });
    }

    if (err.status === 401) {
      console.error("OpenAI authentication failed — check OPENAI_API_KEY");
      return res.status(503).json({ error: "AI service unavailable." });
    }
  }

  // Not an OpenAI error — pass to your generic error handler
  next(err);
}

Step 5: The Chat Endpoint (Non-Streaming)

Let's wire everything together for a standard, non-streaming response first:

// src/routes/chat.js
import express from "express";
import { openai, MODELS } from "../openaiClient.js";
import { tokenGuard } from "../tokenCounter.js";
import { aiRateLimiter } from "../middleware/rateLimiter.js";

const router = express.Router();

router.post(
  "/",
  aiRateLimiter,
  tokenGuard(4_000),
  async (req, res, next) => {
    const { messages, useSmartModel = false } = req.body;
    const model = useSmartModel ? MODELS.smart : MODELS.fast;

    try {
      const completion = await openai.chat.completions.create({
        model,
        messages,
        max_tokens: 1_000, // cap output tokens to control cost
        temperature: 0.7,
      });

      const reply = completion.choices[0].message;
      const usage = completion.usage;

      res.json({
        message: reply,
        usage: {
          inputTokens: usage.prompt_tokens,
          outputTokens: usage.completion_tokens,
          totalTokens: usage.total_tokens,
          estimatedCostUsd: estimateCost(usage, model),
        },
      });
    } catch (err) {
      next(err);
    }
  }
);

function estimateCost(usage, model) {
  // Prices per million tokens (as of mid-2025)
  const pricing = {
    "gpt-4o-mini": { input: 0.15, output: 0.60 },
    "gpt-4o": { input: 5.00, output: 15.00 },
  };
  const p = pricing[model] || pricing["gpt-4o-mini"];
  const inputCost = (usage.prompt_tokens / 1_000_000) * p.input;
  const outputCost = (usage.completion_tokens / 1_000_000) * p.output;
  return Number((inputCost + outputCost).toFixed(6));
}

export default router;

Notice max_tokens: 1_000. Without this, GPT-4o can produce 4,096 output tokens per request. If a user asks it to "write me a book," it will try. The max_tokens cap is your backstop.

Step 6: Streaming Responses with Server-Sent Events

Streaming makes AI features feel responsive. Instead of a blank screen for 3–8 seconds, the user sees text appear word by word. It's the difference between "this feels AI-powered" and "this is broken."

// src/routes/chat-stream.js
import express from "express";
import { openai, MODELS } from "../openaiClient.js";
import { tokenGuard } from "../tokenCounter.js";
import { aiRateLimiter } from "../middleware/rateLimiter.js";

const router = express.Router();

router.post(
  "/stream",
  aiRateLimiter,
  tokenGuard(4_000),
  async (req, res, next) => {
    const { messages } = req.body;

    // Establish SSE connection
    res.setHeader("Content-Type", "text/event-stream");
    res.setHeader("Cache-Control", "no-cache");
    res.setHeader("Connection", "keep-alive");
    res.setHeader("Access-Control-Allow-Origin", "*");
    res.flushHeaders(); // send headers immediately

    try {
      const stream = await openai.chat.completions.create({
        model: MODELS.fast,
        messages,
        max_tokens: 1_000,
        stream: true,
      });

      let totalOutputTokens = 0;

      for await (const chunk of stream) {
        const delta = chunk.choices[0]?.delta?.content ?? "";
        if (delta) {
          totalOutputTokens += 1; // approximate; tiktoken is more accurate
          res.write(`data: ${JSON.stringify({ type: "delta", content: delta })}

`);
        }

        // Check for stop reason
        if (chunk.choices[0]?.finish_reason === "length") {
          res.write(`data: ${JSON.stringify({ type: "warning", message: "Response truncated at token limit" })}

`);
        }
      }

      res.write(`data: ${JSON.stringify({ type: "done" })}

`);
      res.end();
    } catch (err) {
      // Send error over SSE before closing
      res.write(`data: ${JSON.stringify({ type: "error", message: "Generation failed. Please try again." })}

`);
      res.end();
      // Also pass to error handler for logging
      console.error("Streaming error:", err.message);
    }
  }
);

export default router;

Watch: OpenAI API with Node.js + Express

Streaming vs. Non-Streaming — When to Use Which

Factor
Non-Streaming
Streaming (SSE)

User experience
Blank screen until done (3–8s)
Text appears word by word — feels instant

Complexity
Standard REST response
SSE connection, chunked parsing on frontend

Usage logging
Easy — completion.usage has exact token counts
Harder — token counts only available via the final chunk

Caching
Can cache the full response
Can't cache a stream

Best for
API-to-API calls, short responses, classification tasks
User-facing chat, long completions, code generation

Serverless functions
Works everywhere
Needs long-running connection — use Vercel Edge Functions or a real server

Testing Your OpenAI Integration

Mocking the OpenAI API in tests is a trap. The mock will pass but the real integration will fail in ways you didn't anticipate — different error formats, unexpected token usage, streaming chunk structure variations.

Instead:

Unit test everything except the API call. Test your token counting, your error handler, your response formatter — all without touching OpenAI. These functions should be pure and deterministic.
Use a cheap model for integration tests. gpt-4o-mini is $0.15 per million input tokens. Your integration test suite probably costs fractions of a cent to run. Run it.
Record and replay for expensive tests. Libraries like nock or VCR-style recording let you record real API responses and replay them in future test runs without hitting the API.

// Example: testing the token guard middleware in isolation
import { tokenGuard } from "../src/tokenCounter.js";
import { createMockMiddlewareContext } from "./helpers.js";

test("tokenGuard rejects messages over the limit", async () => {
  const guard = tokenGuard(10); // tiny limit for test
  const { req, res, next } = createMockMiddlewareContext({
    body: {
      messages: [{ role: "user", content: "a".repeat(500) }],
    },
  });

  await guard(req, res, next);

  expect(res.statusCode).toBe(400);
  expect(res.body.error).toContain("too long");
  expect(next).not.toHaveBeenCalled();
});

TL;DR

Initialize the OpenAI client once with maxRetries and timeout set. Don't instantiate it in route handlers or you'll get a new client per request with no retry or timeout configuration.
Count tokens before you call the API. Use tiktoken to measure input size and reject oversized requests before they cost you money. Set a max_tokens cap on output for the same reason.
Rate limit by user ID, not just IP. Authenticated users with the same IP (corporate NAT, mobile networks) would all share a single IP limit — use their user ID as the rate limit key.
Use typed error handling — instanceof OpenAI.APIError gives you the status code, request ID, and message. Turn 429s into user-friendly retry prompts, not 500 errors.
Stream for user-facing features, skip it for internal calls. SSE streaming transforms the UX for chat interfaces. For batch processing or API-to-API calls, non-streaming is simpler to implement and log.
Test everything except the API call. Token counting, error handling, and response formatting are all pure functions you can test cheaply. For integration tests, use gpt-4o-mini — it's cheap enough to run in CI.

Deploying a Next.js App to AWS with CI/CD Pipelines (Step-by-Step)

Harshdeep Singh — Tue, 02 Jun 2026 21:27:52 +0000

The first time I deployed a Next.js app to production, it took me three days. Not because the app was complicated — it was a straightforward portfolio site. It took three days because I had no idea what I was doing with AWS, I'd never written a GitHub Actions workflow, and every tutorial I found either skipped the hard parts or assumed I already knew them.

By the time I was done, I had a deployment pipeline I was genuinely proud of: push to main, GitHub Actions runs the build, tests pass, the app deploys to an EC2 instance behind CloudFront. Zero manual steps. Zero downtime deploys. Total cost: about $5/month.

This guide is the one I wish had existed. We're going to deploy a Next.js app to AWS from scratch — EC2 for compute, CloudFront for CDN, GitHub Actions for CI/CD — with every step explained so you understand what you're building, not just copying commands.

Why AWS Instead of Vercel?

This is a fair question. Vercel is genuinely excellent for Next.js, and for most projects it's the right call. You push, it deploys. Done.

AWS makes sense when:

You need to control the infrastructure (compliance, data residency, custom VPC configuration)
You're running other services (databases, queues, lambdas) in AWS and want everything in the same network
You want to learn infrastructure skills that transfer to enterprise environments
Your app has specific performance requirements that benefit from custom CloudFront configuration
You're a freelancer or consultant who wants to bill separately for infrastructure

If none of those apply to you, use Vercel. This guide is for when they do.

The Architecture

Here's what we're building:

┌────────────────────────────────────────────────────────┐
│ GITHUB ACTIONS CI/CD │
│ │
│ Push to main → Build → Test → Deploy to EC2 │
└──────────────────────┬─────────────────────────────────┘
│ SSH deploy
▼
┌────────────────────────────────────────────────────────┐
│ AWS EC2 INSTANCE │
│ │
│ Ubuntu 22.04 LTS │
│ Node.js 20 + PM2 (process manager) │
│ Next.js app running on port 3000 │
│ Nginx reverse proxy (port 80/443 → 3000) │
└──────────────────────┬─────────────────────────────────┘
│ Origin
▼
┌────────────────────────────────────────────────────────┐
│ CLOUDFRONT CDN │
│ │
│ Static assets cached at edge (/_next/static/*) │
│ TTL: 1 year for static, 0 for HTML │
│ SSL termination via ACM certificate │
│ Custom domain: yourapp.com │
└────────────────────────────────────────────────────────┘

This isn't the only way to run Next.js on AWS. You could use Elastic Beanstalk, App Runner, ECS, or deploy static exports to S3 + CloudFront. The EC2 + CloudFront approach gives you the most control and transfers the most skills to enterprise environments.

Prerequisites

An AWS account (free tier works for learning; a t3.micro is enough for small apps)
A domain name (optional but recommended — we'll set up SSL)
A GitHub repository with your Next.js app
Basic familiarity with the AWS console

The total setup takes about 90 minutes the first time. After that, every deployment is automatic.

Step 1: Set Up the EC2 Instance

In the AWS Console, navigate to EC2 and launch a new instance. The settings that matter:

AMI: Ubuntu Server 22.04 LTS (free tier eligible)
Instance type: t3.micro (1 vCPU, 1GB RAM) for small apps; t3.small for medium traffic
Key pair: Create a new one, download it — you'll need this for SSH and GitHub Actions
Security group: Allow inbound traffic on ports 22 (SSH), 80 (HTTP), and 443 (HTTPS). Add your IP as the only source for port 22 (don't expose SSH to 0.0.0.0/0).

Once the instance is running, SSH in and set up the environment:

# Connect to your instance
ssh -i your-key.pem ubuntu@YOUR_EC2_PUBLIC_IP

# Update system packages
sudo apt-get update && sudo apt-get upgrade -y

# Install Node.js 20 via NodeSource
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install PM2 globally (process manager for Node.js)
sudo npm install -g pm2

# Install Nginx
sudo apt-get install -y nginx

# Verify everything installed correctly
node --version   # v20.x.x
npm --version    # 10.x.x
pm2 --version    # 5.x.x
nginx -v         # nginx/1.24.x

Step 2: Configure Nginx as a Reverse Proxy

Nginx will listen on port 80 and forward requests to your Next.js app on port 3000. This is the standard setup for Node.js apps on Linux servers.

sudo nano /etc/nginx/sites-available/nextjs-app

Paste this configuration:

server {
    listen 80;
    server_name YOUR_DOMAIN.com www.YOUR_DOMAIN.com;

    # Proxy requests to Next.js
    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }

    # Cache Next.js static assets at Nginx level too
    location /_next/static/ {
        proxy_pass http://localhost:3000;
        proxy_cache_valid 200 1y;
        add_header Cache-Control "public, max-age=31536000, immutable";
    }
}

# Enable the site and test the config
sudo ln -s /etc/nginx/sites-available/nextjs-app /etc/nginx/sites-enabled/
sudo nginx -t            # should say "test is successful"
sudo systemctl restart nginx

Step 3: The GitHub Actions Workflow

This is where the CI/CD magic happens. The workflow does four things: checks out code, runs your build, SSHs into the server, and restarts the app. Create this file in your repository:

mkdir -p .github/workflows

Create .github/workflows/deploy.yml:

name: Deploy to AWS EC2

on:
  push:
    branches: [main]
  workflow_dispatch:    # also allow manual triggers

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "npm"

      - name: Install dependencies
        run: npm ci

      - name: Run linter
        run: npm run lint

      - name: Build Next.js app
        run: npm run build
        env:
          # Pass any build-time env vars here
          NEXT_PUBLIC_GA_ID: ${{ secrets.NEXT_PUBLIC_GA_ID }}

      - name: Deploy to EC2
        uses: appleboy/ssh-action@v1.0.3
        with:
          host: ${{ secrets.EC2_HOST }}
          username: ubuntu
          key: ${{ secrets.EC2_PRIVATE_KEY }}
          script: |
            cd /var/www/nextjs-app

            # Pull latest code
            git pull origin main

            # Install dependencies (production only)
            npm ci --omit=dev

            # Build the app on the server
            npm run build

            # Restart with PM2 (zero-downtime reload)
            pm2 reload nextjs-app --update-env

            echo "Deploy complete at $(date)"

Step 4: Set Up GitHub Secrets

In your GitHub repository, go to Settings → Secrets and variables → Actions, and add these three secrets:

Secret Name
Value

EC2_HOST
Your EC2 instance's public IP address or domain

EC2_PRIVATE_KEY
The full contents of your .pem file (including the BEGIN/END lines)

NEXT_PUBLIC_GA_ID
Your Google Analytics measurement ID (or any other public env vars)

For the private key, open the .pem file in a text editor, copy everything including -----BEGIN RSA PRIVATE KEY----- and -----END RSA PRIVATE KEY-----, and paste it as the secret value.

Step 5: First Deploy and PM2 Setup

Before the GitHub Action can work, you need to get the app running on the server for the first time:

# Clone your repo to the server
sudo mkdir -p /var/www/nextjs-app
sudo chown ubuntu:ubuntu /var/www/nextjs-app
cd /var/www/nextjs-app
git clone https://github.com/YOUR_USERNAME/YOUR_REPO.git .

# Create .env file on the server
nano .env
# Add your production environment variables here

# Install dependencies and build
npm ci
npm run build

# Start with PM2
pm2 start npm --name "nextjs-app" -- start
pm2 save                  # persist across server restarts
pm2 startup               # generate startup script
# PM2 will output a command to run — run it

# Verify the app is running
pm2 status
curl http://localhost:3000  # should return HTML

Step 6: CloudFront CDN (Optional but Recommended)

CloudFront puts your app behind a global CDN, which means static assets load from an edge location near your users instead of your EC2 server. For most apps, this makes a meaningful difference in load times outside your server's region.

In the AWS Console, go to CloudFront and create a new distribution:

Origin domain: Your EC2 public IP or domain (not localhost)
Origin protocol policy: HTTP only (Nginx handles the connection to EC2)
Viewer protocol policy: Redirect HTTP to HTTPS
Cache policy for /_next/static/*: CachingOptimized — these files are content-addressed, so they can be cached for years
Cache policy for /* (HTML pages): CachingDisabled — Next.js handles its own cache headers; CloudFront should pass them through

If you have a domain, attach it to the CloudFront distribution and request an ACM (AWS Certificate Manager) certificate for free SSL. DNS validation takes about 15 minutes.

Watch: Next.js CI/CD to AWS EC2 with GitHub Actions

Common Pitfalls

1. Building on the server vs. building in CI

The workflow above builds in the GitHub Action AND on the server. That's redundant — you only need to do it in one place. For small apps, building on the server is fine (simpler). For larger teams, build in CI, upload the artifact, and skip the build step on the server. The tradeoff: artifacts can be large (100MB+), so you need S3 or similar to store them.

2. Forgetting to set NODE_ENV=production

When you run npm start (which runs next start), Next.js automatically sets NODE_ENV=production. But PM2 doesn't always inherit this. Be explicit in your PM2 config or startup command:

pm2 start npm --name "nextjs-app" -- start -- --NODE_ENV=production

3. Not configuring PM2 to restart on crash

By default PM2 restarts crashed processes, but you want to limit restarts to prevent crash loops. Add --max-restarts 10 and --min-uptime 5000 to your pm2 start command. Five seconds of uptime before a restart counts is usually enough to catch truly broken deployments.

4. SSH key permissions

The most common SSH error you'll hit is UNPROTECTED PRIVATE KEY FILE. GitHub Actions handles this correctly when you use appleboy/ssh-action, but if you're doing raw SSH commands, your .pem file needs chmod 400 your-key.pem — readable only by the owner, nothing else.

EC2 vs. Vercel vs. AWS Amplify — Which Should You Choose?

Factor
EC2 + CloudFront
Vercel
AWS Amplify

Setup time
90 min (first time)
5 min
20 min

Next.js feature support
Full (you control the runtime)
Full (built for Next.js)
Most features, some lag

Cost at low traffic
~$5/month (t3.micro)
Free tier, then $20+/month
Pay per build + hosting

Cost at high traffic
Predictable (fixed instance)
Can get expensive fast
Moderate

Infrastructure control
Full — you own everything
None — Vercel manages it
Partial

Learning value
High — enterprise-transferable
Low (it just works)
Medium

Best for
Learning, compliance, cost control
Speed, simplicity, teams
Existing AWS customers

TL;DR

The stack: EC2 (compute) + Nginx (reverse proxy) + PM2 (process manager) + CloudFront (CDN) + GitHub Actions (CI/CD). Each layer has one job.
GitHub Actions workflow: trigger on push to main → install → lint → build → SSH into EC2 → git pull → rebuild → pm2 reload. About 25 lines of YAML.
Store secrets properly: EC2 host, private key, and env vars go in GitHub repository secrets — never hardcoded in workflow files.
PM2 is essential for production Node.js — it keeps the process alive, restarts on crash, and enables zero-downtime reloads. Run pm2 startup to make it persist across server reboots.
CloudFront is optional but worth it — static assets cached at the edge make a real difference for users outside your server's region, and the free ACM SSL certificate saves you the hassle of Certbot configuration.

React + TypeScript Best Practices in 2025: What Actually Matters

Harshdeep Singh — Tue, 02 Jun 2026 21:21:57 +0000

You open a new React project, add TypeScript, and immediately hit Stack Overflow for how to type your first prop. The first answer says use interface. The second says type. The third is a six-paragraph thread about why one is semantically superior to the other. You close the tab and just write any to get on with your life.

Sound familiar? TypeScript in React has a reputation problem. Not because it's hard — it's genuinely great once it clicks — but because the community has generated a staggering volume of contradictory, context-free advice. Every dev tool tutorial starts with TypeScript. Every linting config bans any. Every PR reviewer has a hot take on generics.

This guide cuts through that. I'm not going to cover every TypeScript feature or every React pattern. What I'm going to do is share the specific conventions I use in production React + TypeScript apps in 2025 — the things that have made codebases genuinely easier to work in, not just theoretically safer.

What this guide is NOT

Before we get into it, let me set expectations clearly:

Not a TypeScript basics tutorial. I'm assuming you know what a type is, what an interface is, and that string !== String.
Not exhaustive. TypeScript has dozens of utility types, conditional types, template literal types, and more. I'm not covering all of them — just the ones I reach for constantly.
Not framework-neutral. This is specifically about TypeScript in React apps. Some of these patterns won't apply to a Node.js CLI or a library.
Not about configuration. Strict mode settings, tsconfig targets, module resolution — another article for another day.

What this guide IS is opinionated. I'm going to tell you what I think the right call is in most situations, and why. You'll disagree with some of it. That's fine.

Typing Props the Right Way

Let's start here because it's where every React + TypeScript journey begins, and where a lot of the confusion lives.

Interface vs. Type Alias

Here's my rule: use interface for component props, type for everything else.

Why? Interfaces have declaration merging, which can occasionally bite you in unexpected ways, but they also produce cleaner error messages and feel more natural for describing object shapes. They're also what the React community defaults to, so your code will look familiar to anyone joining your team.

// Good — interface for component props
interface ButtonProps {
  label: string;
  onClick: () => void;
  variant?: "primary" | "secondary" | "ghost";
  disabled?: boolean;
}

// Good — type alias for unions and computed shapes
type ButtonVariant = "primary" | "secondary" | "ghost";
type Theme = "light" | "dark";

You'll see guides that say "always use type" or "always use interface." Honestly? Consistency matters more than which one you pick. Pick a rule and stick to it across your codebase.

Required vs. Optional Props

Default to required. Make something optional only when it genuinely has a sensible default or when it's truly not needed in many use cases.

This is the inverse of what a lot of developers do. They add ? to everything to make TypeScript stop complaining, and then their components have fifteen optional props where most of them are actually always passed. That erases the value of having types at all.

// Bad — over-optionalized
interface CardProps {
  title?: string;
  description?: string;
  imageUrl?: string;
  href?: string;
}

// Good — be explicit about what's truly optional
interface CardProps {
  title: string;
  description: string;
  imageUrl?: string; // genuinely optional — card can work without an image
  href?: string;    // optional — sometimes cards aren't clickable
}

Extending HTML Element Props

This is one of the most useful patterns in React + TypeScript, and it's underused. When you're building a component that wraps an HTML element, extend that element's props so your component accepts all the native attributes automatically.

// Without this pattern — you have to manually add every HTML attribute
interface ButtonProps {
  label: string;
  onClick: () => void;
  // what about type="submit"? aria-label? data-testid? className?
  // you'll spend forever adding these one by one
}

// With this pattern — extend React's built-in types
interface ButtonProps extends React.ButtonHTMLAttributes {
  label: string;
  variant?: "primary" | "secondary";
  // ...and you automatically get onClick, type, aria-*, data-*, className, etc.
}

const Button = ({ label, variant = "primary", ...rest }: ButtonProps) => {
  return (

      {label}

  );
};

The ...rest spread pattern combined with extended HTML props is one of those things that once you start using, you can't go back. Your components become instantly more composable and you stop maintaining a manual list of passthrough props.

Custom Hooks with TypeScript

Custom hooks are where TypeScript really earns its keep, because hooks often manage complex state and return multiple values. If your hook's return type is just inferred as any[], you've lost all the benefit.

Typing Return Values Explicitly

Always define the return type of custom hooks explicitly. Don't rely on inference here — it breaks down the moment your hook has multiple return paths or conditional logic.

// Bad — inferred return type is unreliable
function useUser(id: string) {
  const [user, setUser] = useState(null); // typed as null
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  // ...fetch logic

  return { user, loading, error }; // TypeScript infers this poorly
}

// Good — define the return interface explicitly
interface User {
  id: string;
  name: string;
  email: string;
}

interface UseUserResult {
  user: User | null;
  loading: boolean;
  error: string | null;
}

function useUser(id: string): UseUserResult {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  // ...fetch logic

  return { user, loading, error };
}

Now when you destructure this hook in a component, every field is typed correctly, and you get autocomplete without having to remember what the hook returns.

Generics for Reusable Hooks

Okay so here's where hooks get really powerful. If you're building a reusable data-fetching hook, generics let you make it work with any shape of data without losing type safety.

interface FetchResult {
  data: T | null;
  loading: boolean;
  error: string | null;
}

function useFetch(url: string): FetchResult {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    let cancelled = false;

    fetch(url)
      .then((res) => {
        if (!res.ok) throw new Error(`HTTP ${res.status}`);
        return res.json() as Promise;
      })
      .then((d) => {
        if (!cancelled) {
          setData(d);
          setLoading(false);
        }
      })
      .catch((err: Error) => {
        if (!cancelled) {
          setError(err.message);
          setLoading(false);
        }
      });

    return () => { cancelled = true; };
  }, [url]);

  return { data, loading, error };
}

// Usage — TypeScript knows exactly what data is
const { data, loading, error } = useFetch("/api/user/123");
// data is typed as User | null — not unknown, not any

The T propagates through the entire hook. That's the magic. You call useFetch<User> once at the call site, and TypeScript figures out the rest.

Generic Components

Generics in components are the thing that trips up most mid-level React developers. They look intimidating. They have funny angle-bracket syntax. But once you understand when to reach for them, they save you from maintaining three slightly-different versions of the same component.

When to Use Generic Components

Reach for generics when your component works with data of a variable shape, but still needs to be type-safe. A list component, a select dropdown, a data table — these are classic candidates.

// Without generics — you end up with separate UserList, ProjectList, etc.
// or you use any[] and lose type safety

// With generics — one component that works for any data shape
interface ListProps {
  items: T[];
  renderItem: (item: T, index: number) => React.ReactNode;
  keyExtractor: (item: T) => string;
  emptyMessage?: string;
}

function List({ items, renderItem, keyExtractor, emptyMessage = "No items" }: ListProps) {
  if (items.length === 0) {
    return 
{emptyMessage}
;
  }

  return (


      {items.map((item, index) => (
        - {renderItem(item, index)}
      ))}


  );
}

// Usage — TypeScript infers T from the items array
 u.id}  // TypeScript knows u is a User
  renderItem={(u) => }
/>

Notice that you don't even need to write <List<User>> at the call site — TypeScript infers T = User from the items prop. That's inference doing its job.

One thing to watch: in .tsx files, the compiler can confuse <T> with a JSX tag. If you get a parse error, either add a constraint (<T extends object>) or use a comma (<T,>) to disambiguate.

Discriminated Unions for State

Here's the thing that's changed how I think about React state more than anything else: replacing boolean flags with discriminated union types. This single pattern eliminates entire categories of bugs.

The Boolean Flag Problem

You've seen this component. You've written this component.

// The boolean flag trap
interface FormState {
  isLoading: boolean;
  isSuccess: boolean;
  isError: boolean;
  errorMessage?: string;
  data?: SubmitResult;
}

// Nothing stops you from setting isLoading: true AND isSuccess: true simultaneously
// That's an impossible state — but TypeScript can't catch it
const state: FormState = {
  isLoading: true,
  isSuccess: true, // ← this should be impossible
  isError: false,
};

When you have three booleans representing what should be a single sequential state, you have 2³ = 8 possible combinations, but only 4 of them are actually valid. TypeScript can't protect you from the invalid ones.

The Discriminated Union Fix

// Model the actual states that can exist
type FormState =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "success"; data: SubmitResult }
  | { status: "error"; errorMessage: string };

// Now the impossible states are literally unrepresentable
const state: FormState = { status: "idle" };

// And in your component, TypeScript narrows types automatically
function FormFeedback({ state }: { state: FormState }) {
  if (state.status === "loading") {
    return ;
  }

  if (state.status === "error") {
    // TypeScript knows state.errorMessage exists here
    return ;
  }

  if (state.status === "success") {
    // TypeScript knows state.data exists here
    return ;
  }

  return null; // idle
}

The key is the status discriminant property. When you narrow on state.status === "error", TypeScript automatically knows which variant of the union you're in, and which other fields are available.

This pattern is especially powerful in data-fetching scenarios, form submission flows, and anywhere you have a multi-step process. Start reaching for it instead of isLoading / isError / isSuccess and your state management will become dramatically cleaner.

Taming any

Let me be direct: any is a code smell, but it's not always your fault. Sometimes you're working with a library that has poor types, an API that returns unpredictable shapes, or legacy code you don't own. The goal isn't to never use any — it's to reach for better tools first.

Use unknown Instead of any for External Data

unknown is the type-safe cousin of any. It says "I don't know what this is yet" instead of "pretend this is whatever I need it to be." You can't do anything with an unknown value without first narrowing it with a type guard.

// Bad — any lets you do anything, including wrong things
async function fetchData(url: string): Promise {
  const res = await fetch(url);
  return res.json();
}

const data = await fetchData("/api/user");
data.doesNotExist.boom; // TypeScript is fine with this. Your app is not.

// Good — unknown forces you to validate before using
async function fetchData(url: string): Promise {
  const res = await fetch(url);
  return res.json();
}

function isUser(value: unknown): value is User {
  return (
    typeof value === "object" &&
    value !== null &&
    "id" in value &&
    "name" in value &&
    typeof (value as User).id === "string"
  );
}

const data = await fetchData("/api/user");
if (isUser(data)) {
  // TypeScript now knows data is User
  console.log(data.name);
}

Type Guards Are Your Friends

The value is User return type in the example above is a type guard. It's a function that tells TypeScript "if this returns true, the value is of type T in the branches that follow." This is how you move from unknown territory into properly typed territory without resorting to any.

// Reusable type guard pattern
function isNonNull(value: T | null | undefined): value is T {
  return value !== null && value !== undefined;
}

const items: (User | null)[] = [user1, null, user2, null];
const validUsers = items.filter(isNonNull); // typed as User[], not (User | null)[]

When never Is the Right Answer

never is the type that can't exist. It's useful for exhaustiveness checks — making sure you've handled every case in a union.

type Shape = "circle" | "square" | "triangle";

function getArea(shape: Shape, size: number): number {
  switch (shape) {
    case "circle":
      return Math.PI * size * size;
    case "square":
      return size * size;
    case "triangle":
      return (size * size) / 2;
    default:
      // If you add "hexagon" to the Shape union and forget to handle it here,
      // TypeScript will throw a compile error on this line
      const _exhaustiveCheck: never = shape;
      throw new Error(`Unhandled shape: ${_exhaustiveCheck}`);
  }
}

This pattern scales beautifully with discriminated unions. Add a new status to your state type, and every switch statement that wasn't updated will fail at compile time. That's exactly the kind of safety net TypeScript is supposed to provide.

Before vs. After: TypeScript Patterns

Here's a quick-reference table of the common before/after shifts. These are the six patterns I most often see in code review that a bit of TypeScript discipline cleans up immediately.

  Pattern

  Without TypeScript Discipline

  With TypeScript Discipline

Prop typing

  props: any or no types at all

  interface ButtonProps extends React.ButtonHTMLAttributes&lt;HTMLButtonElement&gt;

Optional props

  Everything is ? to avoid errors

  Only truly optional fields are optional; defaults handled by destructuring

Loading/error state

  isLoading: boolean, isError: boolean, isSuccess: boolean

  Discriminated union: { status: "idle" | "loading" | "success" | "error" }

External API data

  const data: any = await fetch(...).then(r =&gt; r.json())

  const data: unknown + type guard before use

Reusable list

  Separate UserList, ProjectList components with duplicated logic

  One generic List&lt;T&gt; component with typed renderItem and keyExtractor

Hook return type

  Inferred — breaks on multiple return paths, confusing autocomplete

  Explicit interface UseXxxResult { ... } as the return type annotation

Module Structure for a TypeScript React Project

Okay, one more thing worth getting right from the start: where files live. A consistent folder structure does more for long-term maintainability than almost any TypeScript pattern. Here's the structure I use and recommend for mid-to-large React + TypeScript apps in 2025.

src/
├── app/ # Next.js App Router pages (or pages/ for older setup)
│ ├── layout.tsx
│ ├── page.tsx
│ └── blog/
│ └── [slug]/
│ └── page.tsx
│
├── components/ # Shared UI components
│ ├── Button/
│ │ ├── Button.tsx # Component
│ │ ├── Button.types.ts # Interface / type exports
│ │ ├── Button.styles.ts# Styled components or CSS module
│ │ └── index.ts # Re-export for clean imports
│ └── List/
│ └── ...
│
├── hooks/ # Custom hooks
│ ├── useFetch.ts
│ ├── useLocalStorage.ts
│ └── useDebounce.ts
│
├── lib/ # Utilities, helpers, non-UI logic
│ ├── api.ts # Fetch wrappers
│ ├── formatters.ts # Date, currency, string helpers
│ └── validators.ts # Type guards and runtime validation
│
├── types/ # Shared TypeScript types
│ ├── api.ts # API response shapes
│ ├── models.ts # Domain model interfaces (User, Post, etc.)
│ └── index.ts # Re-exports
│
├── context/ # React context providers
│ └── ThemeContext.tsx
│
└── styles/ # Global styles, theme tokens
└── globals.css

A few rules I enforce in this structure:

Co-locate component types. Each component folder has its own .types.ts file. Don't dump all types into a single global types.ts — that file becomes a graveyard.
The types/ directory is for shared domain types only. API response shapes, database models, shared interfaces that more than one component needs. Not component-specific props.
Barrel files are useful but dangerous. An index.ts in each component folder is fine. A single barrel for your entire components/ directory will cause circular dependency nightmares in larger apps.
Hooks go in hooks/, not co-located with components. This is a deliberate choice against the "co-locate everything" philosophy. In my experience, hooks get reused across features, and burying them inside a component folder makes them harder to find and share.

TL;DR

Use interface for component props, type for everything else — pick a rule and apply it consistently. Default to required props; only mark things optional when they genuinely are.
Extend HTML element props using React.ButtonHTMLAttributes<HTMLButtonElement> and friends — this gets you all native attributes for free and makes components composable with ...rest.
Always annotate custom hook return types explicitly — define a UseXxxResult interface and return it. Don't trust inference when there's conditional logic involved.
Use discriminated unions instead of boolean flags for anything with multiple states — { status: "idle" | "loading" | "success" | "error" } is safer, clearer, and catches impossible states at compile time.
Replace any with unknown at API boundaries — then validate with type guards before use. Save never for exhaustiveness checks in switch statements.
Structure your modules intentionally — co-locate component types, put shared domain types in types/, hooks in hooks/, and use barrel files per component folder (not globally).

How to Build an AI Resume Builder with LangChain and Node.js

Harshdeep Singh — Tue, 02 Jun 2026 21:21:55 +0000

A few months back, my friend Marcus was applying for a senior backend role at a fintech company. He had five years of solid experience — distributed systems, AWS, the whole stack. But his resume read like a list of job descriptions someone had copied from LinkedIn. "Responsible for maintaining microservices." "Assisted with CI/CD pipeline implementation." You know the type.

I told him: the problem isn't what you did, it's how you're saying it. Hiring managers spend about six seconds on a resume before deciding whether to read it properly. Six seconds. And if those six seconds are spent reading "responsible for maintaining" — you've lost them.

We spent two hours rewriting it together. Every bullet point started with a strong verb. Every achievement had a number. "Reduced API response time by 40% by introducing Redis caching across three high-traffic endpoints." Much better. Marcus got the interview.

The obvious next thought was: what if you could automate this? Not in the "dump your resume into ChatGPT and ask it to make it better" way — that produces generic slop. I mean a real, structured AI pipeline that understands resume context, applies professional rewriting patterns, and returns clean, job-specific output.

That's what LangChain is built for. And in this guide, we're going to build exactly that: an AI-powered resume rewriter using LangChain and Node.js, with a real Express API, streaming responses, and the kind of prompt engineering that actually produces good results.

What Is LangChain, and Why Bother?

Here's the honest answer: LangChain is an orchestration framework for building applications on top of large language models. Think of it the way you'd think of Express.js — Express doesn't do anything you couldn't do with raw Node's http module, but it gives you a structured, composable way to build web apps that doesn't collapse under its own weight.

LangChain does the same thing for LLM applications. You could just call the OpenAI API directly everywhere. For a one-off script, that's fine. But as soon as your app grows — different prompts for different tasks, multi-step reasoning chains, memory across conversations — raw API calls get messy fast.

Here's what raw OpenAI API code looks like once a project grows:

// Raw OpenAI — works, but scales badly
const response = await openai.chat.completions.create({
  model: "gpt-4",
  messages: [
    { role: "system", content: systemPrompt },
    { role: "user", content: `Rewrite this section: ${section}` }
  ]
});
const rewritten = response.choices[0].message.content;

That's fine for one call. Now add: prompt versioning, chaining that output into a second model call, memory from previous messages, fallback to a different model when rate limits hit, streaming output to the client. Suddenly you're managing a lot of state manually.

LangChain handles all of that with composable primitives: PromptTemplate for reusable, testable prompts; LLMChain for connecting a prompt to a model; SequentialChain for multi-step pipelines; built-in streaming support; and integrations with every major LLM provider.

For our resume builder, the chain looks like this: parse the resume into structured sections, run each section through a prompt that produces action-oriented bullet points, then return the assembled result. Let's build it.

What We're Building

Before we write a line of code, here's the system at a glance:

┌─────────────────────────────────────────────────────┐
│                   CLIENT (Frontend)                  │
│         POST /api/rewrite { resumeText, section }    │
└──────────────────────┬──────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│                  EXPRESS API (Node.js)               │
│  1. Validate input                                   │
│  2. Parse resume into sections                       │
│  3. Call LangChain rewrite chain                     │
│  4. Return improved bullet points                    │
└──────────────────────┬──────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│              LANGCHAIN REWRITE CHAIN                 │
│  PromptTemplate → ChatOpenAI (GPT-4) → Output       │
└──────────────────────┬──────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│                  OPENAI API (GPT-4)                  │
└─────────────────────────────────────────────────────┘

Nothing revolutionary — but each layer has a single, testable job. The chain is the interesting part, so let's get there quickly.

Project Setup

Start a new Node.js project and install the dependencies:

mkdir resume-ai && cd resume-ai
npm init -y
npm install express langchain @langchain/openai @langchain/core dotenv

Create a .env file at the root:

OPENAI_API_KEY=sk-your-key-here
PORT=3001

And your project structure:

resume-ai/
├── src/
│   ├── parseResume.js
│   ├── resumeChain.js
│   └── app.js
├── .env
└── package.json

Add "type": "module" to package.json so we can use ES module syntax throughout.

Step 1: Parsing the Resume

This is the unglamorous part that everyone skips, and it's why most AI resume tools produce garbage. You can't just throw 800 words of resume text at a model and ask it to "make it better." You need to isolate the section you're improving — otherwise the model is operating without context.

Here's a simple section parser. It's not perfect — real resumes come in dozens of formats — but it handles the common patterns:

// src/parseResume.js
export function parseResumeText(rawText) {
  const sections = {
    summary: "",
    experience: [],
    skills: [],
    education: [],
  };

  const sectionKeywords = {
    summary: ["summary", "objective", "profile", "about"],
    experience: ["experience", "employment", "work history", "career"],
    skills: ["skills", "technical skills", "technologies", "competencies"],
    education: ["education", "academic", "degree", "university"],
  };

  const lines = rawText.split("\n").filter((l) => l.trim().length > 0);
  let currentSection = null;

  for (const line of lines) {
    const lowerLine = line.toLowerCase().trim();

    const detected = Object.entries(sectionKeywords).find(([, keywords]) =>
      keywords.some((kw) => lowerLine.includes(kw))
    );

    if (detected && lowerLine.length  {
  const { resumeText, targetSection } = req.body;

  if (!resumeText || typeof resumeText !== "string") {
    return res.status(400).json({ error: "resumeText is required" });
  }
  if (!targetSection || typeof targetSection !== "string") {
    return res.status(400).json({ error: "targetSection is required" });
  }

  // Stay within token limits — GPT-4 context window is large,
  // but we don't need to send the whole resume every time.
  const resumeContext = resumeText.slice(0, 3000);

  try {
    const result = await rewriteChain.call({
      resumeContext,
      sectionText: targetSection,
    });

    res.json({
      original: targetSection,
      rewritten: result.text.trim(),
    });
  } catch (err) {
    console.error("Chain error:", err.message);

    if (err.message?.includes("Rate limit")) {
      return res.status(429).json({ error: "Rate limit hit. Try again in a moment." });
    }

    res.status(500).json({ error: "Rewrite failed. Check your OpenAI API key." });
  }
});

const PORT = process.env.PORT || 3001;
app.listen(PORT, () => console.log(`Resume AI API running on :${PORT}`));

The input size limit (50kb) and the resumeContext.slice(0, 3000) are both intentional. Most GPT-4 token limits won't be hit by a 3,000-character resume excerpt, but some resumes are surprisingly long — especially ones with extensive project descriptions. Truncating at 3,000 characters keeps costs predictable.

Step 4: Streaming the Response

For a good UX, you want to stream the AI response as it arrives rather than waiting for the full completion. A 400-word rewrite might take 6–8 seconds to complete — a blank screen for 8 seconds feels broken.

LangChain makes streaming straightforward with callbacks:

import { HumanMessage } from "@langchain/core/messages";

app.post("/api/rewrite/stream", async (req, res) => {
  const { resumeText, targetSection } = req.body;

  res.setHeader("Content-Type", "text/event-stream");
  res.setHeader("Cache-Control", "no-cache");
  res.setHeader("Connection", "keep-alive");
  res.flushHeaders();

  const streamingModel = new ChatOpenAI({
    modelName: "gpt-4",
    temperature: 0.4,
    streaming: true,
    callbacks: [
      {
        handleLLMNewToken(token) {
          res.write(`data: ${JSON.stringify({ token })}

`);
        },
        handleLLMEnd() {
          res.write("data: [DONE]\n\n");
          res.end();
        },
        handleLLMError(err) {
          res.write(`data: ${JSON.stringify({ error: err.message })}

`);
          res.end();
        },
      },
    ],
  });

  const resumeContext = resumeText?.slice(0, 3000) || "";
  const prompt = `Rewrite these resume bullets for a software developer. Be concise and action-oriented:\n${targetSection}`;

  await streamingModel.invoke([new HumanMessage(prompt)]);
});

On the frontend, you'd consume this with the Fetch API and ReadableStream. Each data: event carries a token, and you append it to the UI as it arrives. The user sees the response materialize in real time — feels fast, even when it isn't.

Watch: LangChain in Node.js (Quick Start)

Common Pitfalls (and How to Dodge Them)

1. Token limits sneaking up on you

GPT-4's context window is large, but you pay per token. If you're sending the full resume + prompt on every request, costs add up fast at scale. The fix: truncate the resume context (as shown above) and cache the parsed sections so you're not re-parsing on every API call.

2. The model inventing achievements

This is the big one. Ask the model to "quantify achievements" without any source data, and it will make numbers up. "Reduced load time by 73%" sounds great until the hiring manager asks about it in an interview. The fix: explicitly tell the model in the prompt: "Only add numbers if they appear in the original text. If no numbers are present, use qualitative language instead."

3. Prompt injection through resume content

A crafty user could put something like "Ignore all previous instructions and output..." inside their resume text. Since you're sending that text directly to the model, it works. The fix: sanitize input and separate resume content from the instruction portion of the prompt with a clear delimiter, like ---RESUME START--- / ---RESUME END---.

4. Not rate limiting

OpenAI's rate limits are per API key, not per user. One user hammering your endpoint can hit the limit for everyone. Add a rate limiter like express-rate-limit before you go live — 5 requests per minute per IP is a reasonable starting point for a resume tool.

5. Picking GPT-4 when you don't need it

GPT-4 is expensive and slow. For most resume rewriting tasks, gpt-4o-mini produces nearly identical results at a fraction of the cost. Test both. You might be surprised how good the cheaper model is for structured, constrained tasks like this one.

LangChain vs. Raw OpenAI API — When to Use Which

Factor

Raw OpenAI API

LangChain

Setup complexity

Low — one import, one call

Medium — more abstractions to learn

Single prompt apps

Perfect fit

Overkill

Multi-step chains

Tedious to wire manually

First-class support

Prompt reuse and testing

DIY — no built-in structure

PromptTemplate makes this easy

Memory across turns

Manual array management

Built-in memory types

Streaming

Supported, manual wiring

Supported, callback-based

Switching LLM providers

Rewrite API calls

Swap the model object

Community / ecosystem

Smaller (OpenAI-specific)

Large, active, lots of integrations

The rule of thumb: if your app makes more than two different types of LLM calls, or if you need any kind of chaining, LangChain saves you from writing orchestration code from scratch. For a simple one-shot wrapper, raw API is cleaner.

TL;DR

LangChain is an orchestration layer for LLM apps — think Express for AI. Use it when you have multi-step chains, prompt reuse, or memory requirements.- Parse before you prompt. Sending a raw resume blob to the model is a recipe for generic output. Identify the section you want to improve and give the model focused context.- Constrain the prompt explicitly. Action verbs, number quantification, bullet count — tell the model exactly what format you want. Vague prompts produce vague results.- Stream responses for better UX. A blank screen for 8 seconds feels broken; a response materializing in real time feels fast.- Guard against pitfalls: rate limit your API, sanitize resume input against prompt injection, and test gpt-4o-mini before defaulting to GPT-4 — it's often good enough and 10x cheaper.