DEV Community: Aman Kumar Singh

The Production Readiness Checklist

Aman Kumar Singh — Tue, 21 Jul 2026 13:08:40 +0000

In the last article, I walked through finding and fixing the slow parts of a SaaS before launch: N+1 queries, missing indexes, unbounded payloads, the usual suspects. That work makes the product fast. It says nothing about whether the product is actually ready to run unattended, at 3am, when something inevitably goes wrong.

This is the closing article of Module 4 in the Full Stack SaaS Masterclass, and it's meant as a checklist you go through before flipping the switch on a real launch, not a tutorial you follow once and forget. Every item on it is something I've seen skipped on a first release, and every skip eventually became an incident.

"Production ready" doesn't mean gold-plated. It means the gaps that turn a minor bug into a multi-hour outage have been closed, and the ones that remain are gaps you've consciously accepted rather than ones nobody thought about. That distinction is the whole point of a checklist: it forces the conscious part.

Configuration and secrets are locked down

The most common first-launch mistake isn't a code bug. It's a config that quietly behaved differently than everyone assumed. A .env file with production credentials committed by accident. A CORS policy left wide open because it was easier during development. A database connection pool sized for a laptop, not for concurrent traffic.

Before launch, walk through every environment variable your app reads and confirm three things: it has a real value in production, that value came from a secrets manager rather than a plaintext file in the repo, and there's a documented fallback (or a hard failure) if it's missing.

import { z } from 'zod';

const envSchema = z.object({
  NODE_ENV: z.enum(['development', 'staging', 'production']),
  DATABASE_URL: z.string().url(),
  REDIS_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
  CORS_ORIGIN: z.string().url(),
  SENTRY_DSN: z.string().url().optional(),
});

export type Env = z.infer<typeof envSchema>;

export function validateEnv(config: Record<string, unknown>): Env {
  const result = envSchema.safeParse(config);
  if (!result.success) {
    console.error('Invalid environment configuration:', result.error.format());
    process.exit(1);
  }
  return result.data;
}

Wiring this into NestJS's ConfigModule at bootstrap means a missing or malformed secret fails the deploy. It doesn't fail silently at 2pm on a Tuesday when a customer hits the one code path that touches it. The tradeoff is a slightly stricter local dev setup, since every new environment variable now needs a schema entry. That's a cost worth paying; a schema that drifts from reality is a bug waiting to be discovered by a user, not by CI.

The pitfall I see most often here is treating staging and production as identical except for the URL. They rarely are. Different rate limits on a third-party API, different database sizes, different feature flags. Document the differences explicitly rather than assuming staging behavior is a preview of production behavior.

Health, readiness, and graceful shutdown

Your orchestrator, whether it's ECS, Kubernetes, or a plain load balancer, needs a reliable way to know if an instance can take traffic. Without it, a deploy can route requests to a container that's still booting, or keep sending traffic to one that's stuck.

The three things worth having are a liveness check (is the process alive), a readiness check (can it actually serve requests, meaning the database and cache connections are up), and a graceful shutdown handler that stops accepting new work before the process exits.

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  app.enableShutdownHooks();

  const server = await app.listen(process.env.PORT ?? 3000);

  process.on('SIGTERM', async () => {
    console.log('SIGTERM received, draining connections');
    await app.close();
    server.close(() => process.exit(0));
  });
}

bootstrap();

Without this, a rolling deploy or an autoscaler scaling down can kill an instance mid-request, and the client gets a connection reset instead of a response. The fix costs almost nothing to implement. It removes an entire class of intermittent, hard-to-reproduce errors that show up as noise in your error tracker rather than as a clear signal.

Backups exist and, more importantly, restores are tested

Every team says they have backups. Far fewer have actually restored from one. A backup you've never restored is a hypothesis, not a safety net. Automated snapshots from a managed Postgres provider are a reasonable starting point, but they don't protect you from a bad migration that corrupts data quietly over a week, or a schema change that makes an old backup incompatible with current application code.

The practice worth adopting before launch is a quarterly restore drill: take a recent backup, restore it to a scratch environment, and run your application's smoke tests against it. This surfaces two things people usually get wrong: a restore that silently drops a table due to permission issues, and a restore time that's much longer than anyone assumed, which matters a great deal when you're calculating an acceptable recovery time objective.

pg_restore \
  --dbname="$SCRATCH_DATABASE_URL" \
  --clean \
  --if-exists \
  --no-owner \
  --jobs=4 \
  ./backups/latest.dump

The tradeoff is time. A quarterly drill takes an afternoon and produces nothing customer-visible, which makes it easy to deprioritize against feature work. I'd argue that's exactly why it needs to be scheduled rather than left to "whenever there's time," because that time never quite arrives on its own.

Observability that answers "what broke" in minutes, not hours

By the time you're running in production, you should already have metrics, structured logs, and error tracking wired up from earlier articles in this module. The readiness question here is narrower: when something breaks, can an on-call engineer go from alert to root cause without pulling in three other people?

That means alerts are tied to symptoms a customer would notice (elevated error rate, rising latency, a queue backing up) rather than to infrastructure internals nobody can act on at 3am. Logs need to carry a request ID that ties a customer-facing error back to the exact backend trace that produced it. And the on-call rotation needs real access to the dashboards and log queries they'd require, tested before the first real incident rather than during it.

import { Injectable, NestMiddleware } from '@nestjs/common';
import { randomUUID } from 'crypto';
import { Request, Response, NextFunction } from 'express';

@Injectable()
export class RequestIdMiddleware implements NestMiddleware {
  use(req: Request, res: Response, next: NextFunction) {
    const requestId = (req.headers['x-request-id'] as string) ?? randomUUID();
    req.headers['x-request-id'] = requestId;
    res.setHeader('x-request-id', requestId);
    next();
  }
}

A pitfall worth naming directly: alert fatigue. A team that gets paged for every 500 error, including expected ones like a client submitting invalid input, learns to ignore alerts within a month. Reserve pages for things that need a human right now, and route everything else to a dashboard someone checks during business hours.

A rollback path that doesn't require a hero

Launch day confidence usually comes from "we tested it in staging," which is necessary but not sufficient. The question a production readiness review should force is: if this release breaks something for real users an hour after deploy, what's the actual sequence of commands to get back to the last known good state, and has anyone run that sequence before?

For a stateless application, rolling back the deployed image is usually fast if your CI/CD pipeline tags releases by commit SHA and your orchestrator supports a one-command rollback. The harder case is a release that shipped alongside a database migration. If the migration is backward compatible, meaning the old application version still works against the new schema, a rollback is safe. If it isn't, you're stuck rolling forward with a fix instead, which takes longer and is riskier under pressure.

-- Backward compatible: old code ignores the new nullable column
ALTER TABLE organizations ADD COLUMN plan_tier TEXT;

-- Not backward compatible: old code will fail on the NOT NULL constraint
ALTER TABLE organizations ADD COLUMN plan_tier TEXT NOT NULL;

The practical rule is to ship schema changes in two steps: add the column nullable, deploy, backfill, then add the constraint in a later deploy once the old code path is gone. It's more deploys for the same feature, and that's the cost. What you get in exchange is a rollback option that actually works, which matters far more the one time you need it than it costs on every other release.

Security basics that are easy to defer and expensive to skip

None of these are exotic. Rate limiting on authentication and password reset endpoints, so a credential-stuffing attempt doesn't take down your database. Dependency scanning in CI, so a known vulnerability doesn't sit in production for months because nobody was watching. HTTPS enforced everywhere, including internal service-to-service calls if they cross a network boundary you don't fully control. Least-privilege IAM roles, so a compromised container doesn't have write access to every S3 bucket in the account.

# GitHub Actions: dependency vulnerability scan on every PR
name: security-audit
on: [pull_request]
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm audit --audit-level=high

The tradeoff with npm audit --audit-level=high gating a PR is the occasional false positive: a vulnerability in a transitive dependency that doesn't actually apply to how you use the package. That's a legitimate annoyance, and the fix is an explicit, reviewed suppression list, not disabling the check.

Key takeaways

Config validation that fails fast at boot catches an entire category of "worked in staging, broke in production" incidents before they reach a user.
Health checks and graceful shutdown remove intermittent errors caused by deploys and autoscaling, not just visible outages.
A backup nobody has restored is unverified. Schedule restore drills; don't wait for an incident to test them.
Observability should be built around what a human needs to diagnose an incident in minutes, with alerts tied to customer-visible symptoms.
A rollback plan is only real if it's been exercised, and backward-compatible migrations are what make rollback possible at all.
Security basics (rate limiting, dependency scanning, least privilege) are cheap before launch and expensive to retrofit after an incident.

FAQ

What does "production ready" actually mean for a SaaS?
It means the failure modes that turn a small bug into a long outage have been addressed deliberately: validated configuration, health checks, tested backups, actionable alerts, and a working rollback path. It doesn't mean every edge case is handled; it means the team knows which ones aren't, on purpose.

How often should I test my backup restore process?
Quarterly is a reasonable baseline for most SaaS products. The exact cadence matters less than making it a scheduled, repeatable drill rather than something that only happens after an incident forces it.

Should every database migration be backward compatible?
Ideally, yes, especially for anything running multiple instances or doing rolling deploys. Splitting a schema change into an additive step and a later cleanup step costs an extra deploy but keeps rollback available if the release causes problems.

How do I avoid alert fatigue without missing real incidents?
Page only for symptoms a customer would notice: elevated error rates, rising latency, a queue backing up. Route lower-severity signals to a dashboard reviewed during business hours instead of paging for every anomaly.

Do I need a full incident response process before launching?
You need the minimum version: someone is on call, they have access to logs and dashboards, and there's a documented rollback procedure. A formal postmortem template and severity taxonomy can come once you've had a few real incidents to learn from.

Is a production readiness checklist a one-time gate or an ongoing practice?
Treat the first pass as a gate before launch, then revisit the checklist before any major architectural change: a new region, a new data store, a significant traffic increase. The checklist doesn't change much, but what counts as "done" against it does as the system grows.

About the Author

Hi, I'm Aman Singh — Senior Full Stack Engineer specializing in scalable SaaS products, distributed systems, cloud architecture, and AI-powered applications.

I write about System Design, Full Stack Engineering, Distributed Systems, Redis, PostgreSQL, AWS, Node.js, and NestJS.

Portfolio: https://amanksingh.com
GitHub: https://github.com/amansingh1501
Product: https://vowerole.com
Email: aman97aman@gmail.com

A Git Workflow for Small Teams

Aman Kumar Singh — Tue, 21 Jul 2026 08:02:24 +0000

The last few articles set up the folder structure that scales for a full stack SaaS: where the frontend and backend live, how a monorepo shares types, where config sits. None of that matters much if the team can't move code through Git without stepping on each other. This is the last piece of Module 1 in the Full Stack SaaS Masterclass, the series that started with choosing the stack and has been building the foundation ever since.

Git workflow is one of those topics every team has an opinion on, usually inherited from wherever they worked last. Some of those opinions come from companies with fifty engineers and three release trains a day. Applying that process to a team of two or three people building a SaaS product is a good way to spend more time managing branches than writing features.

I've settled on a workflow that's boring on purpose. It borrows the useful parts of GitFlow and trunk-based development, drops the ceremony neither needs, and scales down cleanly to a solo founder and up reasonably far before it needs to change.

Trunk-based, not GitFlow

GitFlow gives you develop, release/*, hotfix/*, and long-lived feature branches that merge back through a maze of rules. It was designed for teams shipping infrequently, with formal release cycles and multiple versions in production at once. A SaaS with one production environment and continuous deploys doesn't have that problem, so most of GitFlow's structure is solving something you don't have.

What I use instead is trunk-based development: one long-lived branch, main, that is always deployable. Every feature branches off main, gets reviewed, and merges back into main within a day or two. There's no develop branch acting as a staging area, because that staging area just becomes a second place bugs can hide and a second merge conflict waiting to happen.

The rule that makes this work is short-lived branches. A feature branch that lives for two weeks accumulates drift from main, and the merge at the end becomes its own project. A feature branch that lives for a day or two barely drifts, so the merge is quick and the diff is reviewable. If a feature is big enough that it can't land in a day or two, that's a signal to break it into smaller, independently mergeable pieces, not a signal to let the branch live longer.

git checkout main
git pull origin main
git checkout -b feat/invoice-pdf-export
# work, commit, push
git push -u origin feat/invoice-pdf-export
# open PR, get it reviewed, merge same day if possible

Branch naming and what actually goes in a commit

Branch names are cheap to standardize and useful once you have more than one branch open. I use a type/short-description format:

feat/invoice-pdf-export
fix/tenant-scoping-in-search
chore/upgrade-nestjs-10
refactor/extract-billing-service

The prefix tells anyone scanning the branch list what kind of change it is before they open a single file. It also maps directly onto commit message conventions, which is where the real payoff shows up.

I use Conventional Commits for the commit message itself:

git commit -m "feat(billing): add PDF export for invoices"
git commit -m "fix(auth): scope refresh token lookup to tenant"
git commit -m "chore(deps): bump nestjs to v10"

The type and optional scope in parentheses aren't decoration. They're what a tool like semantic-release or changelog generator reads to decide whether a merge is a patch, minor, or major version bump, and what goes in the changelog under which heading. Even if you're not auto-generating changelogs yet, writing commits this way costs nothing and means you can add that tooling later without rewriting history.

The message itself should describe the why when the diff doesn't make it obvious. "fix(auth): scope refresh token lookup to tenant" tells you what and where. If the fix involved a non-obvious tradeoff, that belongs in the commit body, not just the PR description, because the PR description doesn't travel with git blame.

Pull requests as the actual quality gate

The pull request, not the branch, is where quality gets enforced. On a small team it's tempting to skip review because "everyone knows what's going on," but a PR does two things that verbal context doesn't: it creates a written record of the decision, and it forces the CI pipeline to run before the code reaches main.

A minimal PR template keeps reviews fast because the reviewer isn't reconstructing context from scratch:

## What changed
## Why
## How to test
## Screenshots (if UI)

Four sections, no essay required. On a two-person team, "why" is often one sentence. That's fine. The point is making sure the next person (including future you) doesn't have to guess.

Branch protection on main is worth setting up on day one, not after the first incident caused by a direct push:

# GitHub branch protection settings (not a workflow file, just documenting intent)
required_status_checks:
  - lint
  - typecheck
  - test
  - build
required_pull_request_reviews:
  required_approving_review_count: 1
enforce_admins: true

On a team of two, required_approving_review_count: 1 means you review each other. On a team of one, you can relax that specific rule, but keep the required status checks. CI catching a broken build before it reaches main doesn't need a second human; it just needs the pipeline to run.

Merge strategy: squash, and why it matters more than it sounds

This is a small decision with an outsized effect on how usable your Git history stays. I squash-merge every PR into main. The feature branch might have eleven commits, six of which say "wip" or "fix typo," but the squashed commit that lands on main is one clean entry with the PR's title and description.

# GitHub: set the merge button to "Squash and merge" as the repository default

The payoff is that git log --oneline main reads like a changelog: one line per shipped feature or fix, not a scroll of intermediate commits. When you need to find when something broke, git bisect walks through meaningful units of change instead of half-finished intermediate states, which makes each bisect step actually testable in isolation.

The tradeoff is that you lose the granular commit history within a feature branch once it's merged. For a small team, that history was rarely useful after the fact anyway. If you genuinely need fine-grained history for a specific piece of work (a complex migration, say), that's a case for a well-organized set of commits within the PR and a merge commit instead of squash for that one PR, not a reason to abandon squash-merge as the default.

Hotfixes and the one exception to the branching rule

Trunk-based development assumes main is always deployable, which holds until it doesn't: a bug ships, it's affecting real users, and you need a fix out now. The instinct to skip process here is understandable and also how a rushed fix introduces a second bug.

The pattern that holds up is the same one used for every other change, just faster: branch from main, fix, PR, merge, deploy. The speed comes from urgency and focus, not from skipping review.

git checkout main
git pull origin main
git checkout -b fix/expired-token-500
# minimal, targeted fix
git push -u origin fix/expired-token-500
# fast review, one approval, merge, deploy

If your CI pipeline and deploy process are fast (and for a small SaaS they should be), a hotfix through this path takes minutes, not hours. If it doesn't, that's a sign to invest in deploy speed, not to build a separate emergency process that bypasses review.

Production pitfalls worth naming explicitly

A few failure modes show up repeatedly on small teams, mostly from copying process that doesn't fit the team's size:

Long-lived feature branches are the single biggest source of painful merges. If a branch has been open more than a few days, rebase it onto main regularly rather than letting the drift compound, or split the work into smaller PRs.

Force-pushing to a shared branch after someone else has pulled it rewrites history out from under them. git push --force-with-lease on your own feature branch, after a rebase, is fine. Force-pushing main is not something a small-team workflow should ever need.

Committing directly to main "just this once" erodes the one guarantee the whole workflow depends on: that main only changes through a reviewed PR with passing CI. It only takes one exception for that guarantee to stop being trustworthy.

Skipping the PR description because "it's a small change" is a habit that costs you exactly when you need it: six months later, trying to understand why a particular line exists.

Key takeaways

Trunk-based development with short-lived feature branches fits small teams better than GitFlow, which solves problems (multiple release trains, long release cycles) most SaaS teams don't have.
Consistent branch naming (type/description) and Conventional Commits cost little and pay off the moment you add changelogs or semantic versioning.
Pull requests are the quality gate, not a formality; branch protection with required status checks enforces that even on a team of one or two.
Squash-merging keeps main's history readable and git bisect useful, at the cost of granular in-branch history you rarely need later.
Hotfixes should follow the same reviewed path as every other change, just faster; skipping review under pressure is how a fix becomes a second incident.
The workflow should scale down to a solo founder and up a fair distance before it needs to change; adding process ahead of team size is the same mistake as adding infrastructure ahead of scale.

FAQ

Should a small team use GitFlow or trunk-based development?
Trunk-based development, for most small SaaS teams. GitFlow's extra branches (develop, release/*, hotfix/*) solve problems around multiple release trains and long release cycles that a continuously deployed SaaS with one production environment usually doesn't have.

What's the right commit message format for a small team?
Conventional Commits (type(scope): description) works well because it's cheap to adopt and unlocks tooling like automated changelogs and semantic versioning later, without requiring you to rewrite history to get there.

Should I squash-merge or use a merge commit for pull requests?
Squash-merge as the default. It keeps main's history to one entry per shipped change, which makes git log and git bisect far more useful. Use a merge commit only for the rare PR where the internal commit history is genuinely worth preserving.

How should a small team handle production hotfixes in Git?
The same way as any other change, just faster: branch from main, make a minimal fix, open a PR, get one review, merge, deploy. Skipping review under pressure is a common way a rushed fix introduces a second bug.

How long should a feature branch stay open before merging?
A day or two, ideally. Branches that live longer accumulate drift from main, which turns the eventual merge into its own project. If a feature can't land in a day or two, break it into smaller, independently mergeable pieces.

Do I need branch protection rules on a two-person team?
Yes, at least for required status checks (lint, typecheck, test, build). Required review count can be relaxed for a solo founder, but a CI gate that blocks a broken build from reaching main doesn't need a second human to be worth having.

About the Author

Hi, I'm Aman Singh — Senior Full Stack Engineer specializing in scalable SaaS products, distributed systems, cloud architecture, and AI-powered applications.

I write about System Design, Full Stack Engineering, Distributed Systems, Redis, PostgreSQL, AWS, Node.js, and NestJS.

Portfolio: https://amanksingh.com
GitHub: https://github.com/amansingh1501
Product: https://vowerole.com
Email: aman97aman@gmail.com

A Folder Structure That Scales for Full Stack SaaS

Aman Kumar Singh — Tue, 21 Jul 2026 08:02:20 +0000

Your .env files are validated and out of Git by now, thanks to the last article on managing environment variables and secrets. The app boots with the right config in every environment. What it doesn't have yet is a shape that survives more than a handful of features.

This is part of the Full Stack SaaS Masterclass, a build-it-for-real series that takes a multi-tenant SaaS from an empty folder to production. Today's topic sounds boring compared to auth or payments, but I've seen more codebases rot from folder structure than from any single bad library choice.

Here's the thing about structure: nobody notices it on day one, when you have three routes and two services. Everybody notices it eighteen months in, when adding a field to an invoice means touching twelve files scattered across four unrelated folders. This article is about setting the shape early enough that it never becomes a rewrite.

Structure by feature, not by file type

The instinct most engineers start with is grouping by technical role: a controllers/ folder, a services/ folder, a dtos/ folder, a models/ folder. It looks tidy in a diagram. It falls apart the moment your app has more than about five features, because every change to one feature touches four different folders and you spend more time navigating than coding.

The alternative is grouping by feature, sometimes called vertical slicing. Everything related to invoices lives under invoices/: the controller, the service, the DTOs, the entity, the tests. Everything related to organizations lives under organizations/. When you add a field to an invoice, you open one folder, not four.

Here's how that looks inside the NestJS API from apps/api, which we set up a few articles back:

apps/api/src/
├── modules/
│   ├── invoices/
│   │   ├── dto/
│   │   │   ├── create-invoice.dto.ts
│   │   │   └── update-invoice.dto.ts
│   │   ├── entities/
│   │   │   └── invoice.entity.ts
│   │   ├── invoices.controller.ts
│   │   ├── invoices.service.ts
│   │   ├── invoices.module.ts
│   │   └── invoices.service.spec.ts
│   ├── organizations/
│   │   ├── dto/
│   │   ├── entities/
│   │   ├── organizations.controller.ts
│   │   ├── organizations.service.ts
│   │   └── organizations.module.ts
│   └── auth/
│       ├── guards/
│       ├── strategies/
│       ├── auth.controller.ts
│       ├── auth.service.ts
│       └── auth.module.ts
├── common/
│   ├── decorators/
│   ├── filters/
│   ├── guards/
│   ├── interceptors/
│   └── pipes/
├── config/
│   └── configuration.ts
├── app.module.ts
└── main.ts

NestJS already nudges you toward this. A module is a feature boundary by design: it declares its own controllers, providers, and imports, and the framework doesn't care how many other modules exist alongside it. Fighting that and going back to a controllers/ folder means fighting the framework's own conventions for no real benefit.

The common/ folder is deliberately small and deliberately generic. It holds things with no feature owner: a global exception filter, a logging interceptor, a @CurrentUser() decorator. If something belongs to one feature, it goes in that feature's folder even if you think you might reuse it later. Premature sharing creates coupling between features that didn't need to know about each other.

The same idea in Next.js, with the App Router doing half the work

Next.js's App Router structure already forces feature-adjacent thinking because routing is filesystem-based. Route groups, the folders in parentheses, let you organize by area of the product without changing the URL:

apps/web/src/app/
├── (marketing)/
│   ├── page.tsx
│   ├── pricing/
│   │   └── page.tsx
│   └── layout.tsx
├── (dashboard)/
│   ├── layout.tsx
│   ├── invoices/
│   │   ├── page.tsx
│   │   ├── [invoiceId]/
│   │   │   └── page.tsx
│   │   └── _components/
│   │       ├── invoice-table.tsx
│   │       └── invoice-status-badge.tsx
│   └── settings/
│       └── page.tsx
├── (auth)/
│   ├── login/
│   │   └── page.tsx
│   └── signup/
│       └── page.tsx
├── api/
│   └── webhooks/
│       └── stripe/
│           └── route.ts
└── layout.tsx

The (marketing) group gets its own layout without a header full of app navigation. The (dashboard) group gets an authenticated layout with a sidebar. Neither prefix appears in the URL: /pricing and /invoices both resolve exactly as you'd expect, because parenthesized segments are organizational only.

The underscore folder, _components/, is Next.js's way of saying "not a route." Anything under an underscore-prefixed folder is opted out of routing entirely. That's exactly what you want for components, hooks, or utilities that belong to one route but shouldn't accidentally become one. Colocating invoice-table.tsx next to the invoices/ route it serves means you don't go hunting through a global components/ folder to find what renders a specific page. Only promote a component to a shared location once a second, unrelated route actually needs it.

What earns a place in packages/, and what doesn't

The monorepo article set up apps/ for deployables and packages/ for shared code. Folder structure inside each app is one problem; deciding what crosses that boundary into a shared package is a different one, and it's where I've watched teams overcorrect the most.

A packages/types folder is an easy call. It has zero business logic, just interfaces, and both apps need the exact same shape for a User or an Invoice. A packages/config folder for shared ESLint and TypeScript config is another easy call, since divergence there is pure friction with no upside.

Where it gets tempting, and often wrong, is a packages/utils grab bag. The moment you write a date-formatting helper in the frontend, it's tempting to move it to a shared package "in case the backend needs it too." Resist that until the backend actually needs it. A shared package you maintain speculatively is a tax you pay on every change, since now two apps depend on it and a "small" edit needs a version bump and a rebuild across the graph. Let duplication happen once or twice. If the same logic shows up a third time in two apps, that's real evidence. Moving it out now pays off a debt instead of prepaying one that might never come due.

// packages/types/src/invoice.ts
export interface Invoice {
  id: string;
  organizationId: string;
  amountCents: number;
  currency: string;
  status: 'draft' | 'sent' | 'paid' | 'void';
  dueDate: string;
}

That's the shape both apps/api and apps/web import. It has no logic to drift, so there's nothing to keep in sync beyond the field list itself, and TypeScript enforces even that for free.

Production pitfalls worth naming early

A few structural mistakes are easy to make and expensive to unwind once real code depends on them.

The first is barrel files everywhere: an index.ts in every folder that re-exports everything inside it. They feel convenient for imports, but they quietly encourage circular dependencies, since it becomes easy for module A to import from module B's barrel, which imports from module A's barrel, without either author noticing. Use barrels sparingly, mainly at package boundaries like packages/types, not inside every feature folder of the API or the app.

The second is letting common/ (or a shared/ folder in the frontend) become a dumping ground. If more than a small fraction of your code lives there, the "shared" folder has quietly become an unstructured second app sitting inside your structured one. Revisit it periodically and move anything with a single obvious owner back into that feature's folder.

The third is inconsistency between the two apps. If apps/api groups by feature but apps/web groups by technical type, every engineer pays a small tax switching mental models depending on which side of the stack they're touching. Picking the same organizing principle on both sides, feature first, keeps the switching cost near zero.

The fourth, specific to NestJS, is a module that imports half the app because a controller in invoices needs one small piece of logic from organizations. That's usually a sign the boundary is drawn in the wrong place, or that the shared piece belongs in a smaller, more focused shared module rather than a direct cross-import between two big feature modules.

Key takeaways

Group code by feature (vertical slices), not by technical layer, on both the NestJS API and the Next.js frontend. It matches how features actually get changed.
NestJS modules are a feature boundary by design; let each module own its controller, service, DTOs, and entities.
Next.js route groups ((name)) organize by area of the product without changing the URL; underscore folders (_components) opt out of routing for colocated code.
Only promote code into packages/ once real duplication shows up twice or more; a speculative shared package is a tax on every future change.
Keep common//shared/ folders small and generic; if they grow large, that's a sign features are being drawn in the wrong place.
Use the same organizing principle (feature-first) across both apps so engineers don't switch mental models when moving between frontend and backend.

FAQ

Should I structure a NestJS project by feature or by layer?
By feature. Group each feature's controller, service, DTOs, and entity together in one module folder. A controllers/, services/, dtos/ split by technical layer looks organized at first but forces every feature change to touch multiple unrelated folders as the app grows.

What's the difference between packages/ and apps/common/shared?
packages/ is for code shared across separately deployed apps in the monorepo, like packages/types used by both the API and the frontend. A common/ folder inside a single app is for cross-feature code within that one app, like a global exception filter or logging interceptor.

How do Next.js route groups work, and do they affect the URL?
A folder wrapped in parentheses, like (dashboard), groups routes and can hold a shared layout, but the parenthesized name never appears in the URL. (dashboard)/invoices/page.tsx still resolves to /invoices.

When should I move code into a shared package instead of duplicating it?
Once the same logic shows up in two apps for the third time, not the first. Two occurrences are often coincidence; a third is a real pattern. Moving code out too early creates a shared dependency you now have to version and rebuild for every small change.

What is a barrel file, and why can it cause circular dependency issues?
A barrel file is an index.ts that re-exports everything in a folder. Overusing them across feature folders makes it easy for two modules to import from each other's barrels indirectly, creating circular dependencies that are hard to trace back to their source. Keep barrels mainly at package boundaries.

How do I know my folder structure has stopped scaling?
A common signal is a single small feature change touching more than two or three folders, or a common/shared folder that's grown as large as your actual feature folders. Both mean the boundaries need revisiting before the next feature makes it worse.

About the Author

Hi, I'm Aman Singh — Senior Full Stack Engineer specializing in scalable SaaS products, distributed systems, cloud architecture, and AI-powered applications.

I write about System Design, Full Stack Engineering, Distributed Systems, Redis, PostgreSQL, AWS, Node.js, and NestJS.

Portfolio: https://amanksingh.com
GitHub: https://github.com/amansingh1501
Product: https://vowerole.com
Email: aman97aman@gmail.com

Managing Environment Variables and Secrets

Aman Kumar Singh — Tue, 21 Jul 2026 07:57:11 +0000

Last time, in Setting Up Docker for Local Development, we got Postgres and Redis running the same way on every machine on the team. That solved "works on my machine" for the infrastructure. It didn't solve the other half of the problem: every one of those services needs credentials, and those credentials need to be different in local dev, staging, and production without anyone copy-pasting a database password into a Slack message.

This is part of the Full Stack SaaS Masterclass, the series where we're building a multi-tenant SaaS from an empty repo to something production-ready. Environment variables feel like the most boring topic in the whole series, and that's exactly why teams get them wrong. Nobody schedules time to think about config until a secret leaks into a git history or a staging database gets pointed at by a production deploy.

You don't need a giant secrets-management platform on day one. A handful of habits, applied consistently, scale fine from a solo project to a team of engineers, and they keep you from being one careless git add . away from a real incident.

Why config deserves its own discipline

Every real app has values that change between environments: database URLs, API keys, JWT secrets, third-party credentials, feature flags. The twelve-factor app methodology calls this out directly: config should live in the environment, not in the code, because code is the same across every deploy and config is not. If your DATABASE_URL is hardcoded, you can't run the same build against staging and production without editing source files, which defeats the entire point of having a build artifact.

The second reason is a security one. Code gets reviewed, diffed, and often made public. Secrets don't get that scrutiny in the same way, and they shouldn't be visible in the same places code is. Once a secret is committed to git, it's in history forever unless you rewrite it. By then it's usually already been rotated in panic, not by plan.

The third reason is less obvious: config bugs are some of the hardest to debug precisely because the code is correct. A missing REDIS_URL in staging doesn't throw a compile error. It throws a runtime error three requests deep into a job queue, at 2am, after the person who set up staging has moved teams. Treating configuration as a first-class, validated part of your app instead of an afterthought is what prevents that class of bug entirely.

Validate config at startup, not at first use

The single highest-leverage habit here is validating every environment variable when the app boots, not the first time some deep service tries to read process.env.STRIPE_SECRET_KEY and gets undefined. Fail fast, with a clear error, before the app accepts a single request.

In NestJS this slots naturally into ConfigModule. Instead of forRoot({ isGlobal: true }) with no validation, define a schema and pass it in:

// src/config/env.validation.ts
import { z } from 'zod';

export const envSchema = z.object({
  NODE_ENV: z.enum(['development', 'test', 'staging', 'production']),
  PORT: z.coerce.number().default(3000),
  DATABASE_URL: z.string().url(),
  REDIS_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
  STRIPE_SECRET_KEY: z.string().startsWith('sk_'),
});

export type EnvConfig = z.infer<typeof envSchema>;

export function validateEnv(config: Record<string, unknown>): EnvConfig {
  const result = envSchema.safeParse(config);

  if (!result.success) {
    const issues = result.error.issues
      .map((issue) => `${issue.path.join('.')}: ${issue.message}`)
      .join('\n');
    throw new Error(`Invalid environment configuration:\n${issues}`);
  }

  return result.data;
}

// src/app.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { validateEnv } from './config/env.validation';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      validate: validateEnv,
    }),
  ],
})
export class AppModule {}

With this in place, a missing JWT_SECRET or a malformed DATABASE_URL crashes the app on boot with a message that names the exact variable, not a stack trace from a random service two weeks later. That trade is almost always worth it: a loud failure in CI or on deploy beats a silent one in production.

The same idea applies on the frontend, though Next.js handles it differently since env vars there get baked into the client bundle at build time if you're not careful. Anything prefixed NEXT_PUBLIC_ ships to the browser. Everything else stays server-only. Keep a small, explicit list of what's actually public:

// apps/web/src/env.ts
const publicEnv = {
  apiUrl: process.env.NEXT_PUBLIC_API_URL,
  stripePublishableKey: process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY,
} as const;

for (const [key, value] of Object.entries(publicEnv)) {
  if (!value) {
    throw new Error(`Missing required public env var for: ${key}`);
  }
}

export { publicEnv };

Naming the boundary explicitly like this means nobody accidentally prefixes a real secret with NEXT_PUBLIC_ just because it was convenient during a late-night fix. That single prefix decides whether a value ends up in a browser's network tab.

Local development: .env files done right

For local dev, a .env file loaded by dotenv (or NestJS's built-in loader) is still the right tool. The discipline is in what goes in git and what doesn't.

Commit an .env.example with every variable name and a placeholder or safe default, never a real value:

# .env.example
NODE_ENV=development
PORT=3000
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/saas_dev
REDIS_URL=redis://localhost:6379
JWT_SECRET=replace-with-a-long-random-string
STRIPE_SECRET_KEY=sk_test_replace_me

Ignore the real one:

# .gitignore
.env
.env.local
.env.*.local

When a new engineer joins, the onboarding step is cp .env.example .env and fill in real local values, most of which come straight from the Docker Compose file we set up previously. .env.example doubles as documentation: anyone can read it and know exactly what the app needs to run, without grepping the codebase for every process.env reference.

One habit worth adding here: run a pre-commit check (a simple secret-scanning tool works fine) that blocks a commit containing anything that looks like a live key. It catches the case where .env gets accidentally un-ignored, or someone pastes a real key into a config file while debugging and forgets to remove it before committing.

Secrets in staging and production

Local .env files don't belong anywhere near a deployed environment. Once you're off a laptop, the secret needs to live somewhere with access control, an audit trail, and rotation support. A plaintext file gives you none of that.

On AWS, that's Secrets Manager or SSM Parameter Store, both of which integrate cleanly with ECS, Lambda, and EC2. The pattern is the same regardless of which one you pick: the secret's value never sits in your deploy config or CI logs, only its identifier does.

// src/config/secrets.ts
import {
  SecretsManagerClient,
  GetSecretValueCommand,
} from '@aws-sdk/client-secrets-manager';

const client = new SecretsManagerClient({ region: process.env.AWS_REGION });

export async function loadSecret(secretId: string): Promise<string> {
  const response = await client.send(
    new GetSecretValueCommand({ SecretId: secretId }),
  );

  if (!response.SecretString) {
    throw new Error(`Secret ${secretId} has no string value`);
  }

  return response.SecretString;
}

In practice, you'd call this once during bootstrap, before ConfigModule validates anything, and inject the resolved values into process.env or directly into your config object. The app code never knows or cares whether a value came from a local .env file or Secrets Manager. That's the point: the same validated config shape works in both places, only the source changes.

For CI/CD, GitHub Actions repository and environment secrets cover most needs. Scope secrets to the environment that needs them (production secrets shouldn't be readable from a PR build), and never echo a secret in a workflow step for debugging. GitHub masks known secret values in logs, but that masking only works for exact string matches, so a secret that gets base64-encoded or partially transformed before printing slips right through the mask.

Common pitfalls worth naming directly

A few mistakes show up often enough to call out on their own.

Logging the entire process.env object "just to check config" is a common one, usually left in during debugging and forgotten. It's an easy way to leak every secret the process holds into a log aggregator that a much wider set of people can read than the codebase itself.

Reusing the same secret across environments is another. If staging and production share a JWT_SECRET, a token issued by one is valid on the other, which turns a staging compromise into a production one.

Long-lived secrets that never rotate are a slow accumulation of risk. Every engineer who's ever had access to a secret, and every system that's ever logged it by accident, remains a potential exposure point for as long as that secret stays valid. Rotation doesn't need to be constant, but it should be possible without a redeploy freeze, which is itself a good test of whether your secrets architecture is sound.

And a subtler one: config drift between environments, where staging quietly ends up with a different flag setting than production because someone made a one-off change and never wrote it down. A validated schema, checked into source control even though the values aren't, keeps every environment honest about what it needs.

Key takeaways

Config belongs in the environment, not in code, per the twelve-factor model, and secrets deserve stricter handling than ordinary config.
Validate every environment variable at startup with a schema (Zod, Joi, or similar) so missing or malformed config fails loudly before the app serves traffic.
Commit .env.example with placeholder values; never commit a real .env. Add it to .gitignore from day one.
On the frontend, treat the NEXT_PUBLIC_ prefix as a hard security boundary between server-only and browser-visible values.
Use a managed secrets store (Secrets Manager, SSM Parameter Store) in staging and production instead of plaintext files or CI variables alone.
Never reuse secrets across environments, and design for rotation from the start rather than bolting it on after an incident.

FAQ

What's the difference between an environment variable and a secret?
An environment variable is any config value that changes between environments, like a port number or a feature flag. A secret is a specific kind of environment variable whose exposure causes harm, such as an API key or database password. Every secret is an environment variable, but not every environment variable needs secret-level handling.

Should I use dotenv in production?
dotenv and similar loaders are fine for local development, where the file lives only on your machine. In staging and production, prefer a managed secrets store or your platform's native secret injection (ECS task definitions, Kubernetes secrets, GitHub Actions environment secrets) so values are access-controlled and auditable rather than sitting in a plaintext file on a server.

How do I stop secrets from leaking into Next.js client bundles?
Only prefix a variable with NEXT_PUBLIC_ if it's genuinely safe to expose in the browser, such as a publishable API key. Keep everything else unprefixed and read it only in server components, API routes, or server actions. Treat the prefix as an explicit, reviewed decision rather than a naming convention you apply casually.

What should happen when a secret leaks into git history?
Rotate the secret immediately; assume it's compromised the moment it's committed, regardless of whether the repo is public. Removing it from git history (with tools like git filter-repo) matters for hygiene, but it doesn't undo the exposure, since the value may already be cached or cloned elsewhere. Rotation is the step that actually closes the risk.

How often should secrets be rotated?
There's no universal schedule; it depends on the sensitivity of the secret and how it's used. What matters more than a fixed cadence is that rotation is possible without downtime or a redeploy freeze. If rotating a database password or JWT signing key requires a maintenance window, that's a sign the architecture needs work, independent of how often you actually do it.

Do I need a secrets manager for a small side project?
Probably not on day one. A well-ignored .env file and platform-native secrets (like your host's environment variable settings) are enough until you have a team, multiple environments, or compliance requirements. Add a dedicated secrets manager when the coordination cost of plaintext values across people and environments starts to outweigh the setup cost of the tool.

About the Author

Hi, I'm Aman Singh — Senior Full Stack Engineer specializing in scalable SaaS products, distributed systems, cloud architecture, and AI-powered applications.

I write about System Design, Full Stack Engineering, Distributed Systems, Redis, PostgreSQL, AWS, Node.js, and NestJS.

Portfolio: https://amanksingh.com
GitHub: https://github.com/amansingh1501
Product: https://vowerole.com
Email: aman97aman@gmail.com

Setting Up Docker for Local Development

Aman Kumar Singh — Tue, 21 Jul 2026 07:57:09 +0000

The Prisma or TypeORM article settled how the API talks to Postgres. What's still missing is the thing that makes all of it reproducible. A way for anyone on the team, including future you on a new laptop, to run the whole stack with one command and get the exact same result.

That's what this article is about. We already reached for Docker to run Postgres in the PostgreSQL setup, so the container habit is half-formed already. Here's what we add: a docker-compose.yml that runs the API, the web app, Postgres, and Redis together. Dockerfiles that support fast local iteration without turning into a production liability. And the handful of pitfalls that waste the most time when a team first containerizes its dev environment.

This is part six of the Full Stack SaaS Masterclass, continuing from the data-access layer we picked last time.

Why containerize local development at all

Docker in local dev doesn't need to match production infrastructure. Your production deployment (ECS, Kubernetes, whatever you land on later in the series) will look different from a laptop compose file regardless. The real case for it is narrower and more practical: it removes an entire category of setup problems.

Without containers, "clone the repo and run it" quietly depends on whatever's already installed on that machine. A specific Node version. A specific Postgres major version. A Redis binary that may or may not exist. Whatever environment quirks have accumulated over years on that developer's laptop. Every one of those is a source of "works on my machine" bugs that have nothing to do with the code.

With containers, the dependency list shrinks to Docker itself. The API doesn't care whether the host has Node 18 or Node 22 installed, because the container brings its own. A new hire runs docker compose up and has a working Postgres, Redis, API, and frontend in minutes, without touching a version manager or an install guide.

The tradeoff is real and worth naming honestly. Containers add a layer of indirection: file changes go through a bind mount, networking goes through Docker's internal DNS instead of localhost in the way you're used to, and debugging occasionally means reasoning about the container boundary instead of just your code. For a small team building fast, that cost is worth paying once setup pain starts showing up as time lost to environment drift rather than actual bugs.

The docker-compose.yml for the whole stack

The postgres service from the previous article stays as it was. Here's the full file with Redis and both apps added:

# docker-compose.yml
services:
  postgres:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_USER: saas
      POSTGRES_PASSWORD: local_dev_only
      POSTGRES_DB: saas_dev
    ports:
      - '5432:5432'
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U saas']
      interval: 5s
      timeout: 3s
      retries: 5

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    ports:
      - '6379:6379'
    volumes:
      - redisdata:/data

  api:
    build:
      context: .
      dockerfile: apps/api/Dockerfile
      target: development
    env_file:
      - apps/api/.env
    ports:
      - '3000:3000'
    volumes:
      - ./apps/api:/app/apps/api
      - ./packages:/app/packages
      - api_node_modules:/app/node_modules
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_started
    command: npm run start:dev

  web:
    build:
      context: .
      dockerfile: apps/web/Dockerfile
      target: development
    env_file:
      - apps/web/.env
    ports:
      - '3001:3000'
    volumes:
      - ./apps/web:/app/apps/web
      - ./packages:/app/packages
      - web_node_modules:/app/node_modules
    depends_on:
      - api
    command: npm run dev

volumes:
  pgdata:
  redisdata:
  api_node_modules:
  web_node_modules:

A few decisions in there are doing real work. The healthcheck on Postgres plus depends_on.condition: service_healthy on the API means the API waits for Postgres to actually accept connections, not just for the container to start. Those are different things, and the gap between them is a classic source of flaky first-run errors. The named volumes for node_modules exist specifically to avoid mounting the host's node_modules into the container, which we'll get to next.

Dockerfiles built for iteration, not just shipping

The same Dockerfile ends up serving two different jobs: fast local iteration and a lean production image. Multi-stage builds let one file do both without compromise.

# apps/api/Dockerfile
FROM node:20-slim AS base
WORKDIR /app
COPY package.json package-lock.json ./
COPY packages ./packages
COPY apps/api/package.json ./apps/api/package.json

FROM base AS development
RUN npm install
COPY apps/api ./apps/api
EXPOSE 3000
CMD ["npm", "run", "start:dev"]

FROM base AS build
RUN npm ci
COPY apps/api ./apps/api
RUN npm run build --workspace=apps/api

FROM node:20-slim AS production
WORKDIR /app
ENV NODE_ENV=production
COPY --from=build /app/apps/api/dist ./dist
COPY --from=build /app/apps/api/node_modules ./node_modules
COPY --from=build /app/apps/api/package.json ./package.json
EXPOSE 3000
CMD ["node", "dist/main.js"]

The development target intentionally uses npm install instead of npm ci and skips the build step entirely. It's optimized for the compose file overwriting /app/apps/api with a live bind mount and running start:dev with a file watcher. The production target does the opposite: a clean npm ci, a real build, and only the compiled output copied into a fresh, smaller base image. Development speed and production leanness pull in different directions, so give them different targets rather than compromising on one file that does neither well.

The node_modules volume trick, and why it matters

Bind-mounting your whole app directory into a container is what gives you hot reload: edit a file on the host, the container sees the change instantly. The problem is node_modules. If you bind-mount the project root as-is, the container's node_modules (built for the container's OS and architecture) gets shadowed by whatever node_modules exists on the host, which was likely installed for a different platform, especially painful on Apple Silicon Macs installing packages with native bindings.

The fix is the named volume already in the compose file above: mount the source directory, then mount an anonymous or named volume specifically over /app/node_modules so it takes precedence over anything the bind mount would otherwise put there. Docker resolves the more specific mount path last, so node_modules keeps living inside the container's own filesystem while everything else stays live-editable from the host.

Skipping this step is the single most common reason a team's "just run docker compose up" onboarding breaks on the first new machine that tries it. The error is usually a cryptic native-module message that has nothing to do with the actual code change someone made.

Networking, environment variables, and the localhost trap

Inside the compose network, services reach each other by service name, not localhost. The API's DATABASE_URL inside the container should point at postgres:5432, not localhost:5432, because localhost inside a container refers to the container itself, and there's no Postgres running there.

# apps/api/.env used by the api service
DATABASE_URL=postgresql://saas:local_dev_only@postgres:5432/saas_dev
REDIS_URL=redis://redis:6379

This trips people up constantly the first time, especially since the exact same .env file, when running the API directly on the host without Docker, needs localhost instead. Keep a .env.docker and a .env.local (or similar) if the team moves between both modes, and be explicit in the README about which one applies where. The failure mode otherwise is a connection refused error that looks like a Postgres problem and is actually a networking-context problem.

Production pitfalls to avoid

A few mistakes are easy to make once Docker is in the daily workflow, and none of them show up until later.

Don't reuse the development compose file for anything resembling production. It bind-mounts source code, runs a file watcher, and has no resource limits. Production needs its own compose file or, more likely by the time you get there, a real orchestrator, which we cover later in the Cloud & DevOps phase of the series.

Don't let the image grow unbounded. A .dockerignore that excludes node_modules, .git, and build artifacts keeps build context small and build times sane; forgetting it is a quiet tax on every single build.

Don't skip depends_on conditions and assume startup order is deterministic. Compose starts containers in dependency order, but "started" and "ready to accept connections" are different states. Skip the healthcheck and you get an API that crash-loops for the first few seconds of every docker compose up.

Finally, watch Docker Desktop's resource allocation on macOS and Windows. A stack running Postgres, Redis, and two Node apps with file watchers active can genuinely strain the default memory and CPU limits. The symptom is usually "everything feels slow" rather than an obvious error, which makes it easy to blame the wrong thing.

Key takeaways

Containerizing local dev removes environment drift, not because it mirrors production exactly, but because it collapses the dependency list down to Docker itself.
One compose file can run Postgres, Redis, the API, and the frontend together, with healthchecks controlling real startup order rather than container-start order.
Multi-stage Dockerfiles let one file serve fast local iteration and a lean production build without compromising either.
Mount a named volume over node_modules inside the container so a host-installed node_modules never shadows the container's own dependencies.
Inside the compose network, services address each other by service name, not localhost; keep separate env files for in-container and on-host runs.
Never point the dev compose file at production. Its bind mounts and lack of resource limits make it unsafe for anything but local iteration.

FAQ

Should I run Postgres and Redis in Docker even if I develop the API directly on my host machine?
Yes, that's a common and reasonable split. Running the stateful services (Postgres, Redis) in containers while running the API directly on the host with npm run start:dev gives you faster debugger attachment and native tooling, while still avoiding the pain of installing and version-matching database servers by hand. Just remember your DATABASE_URL needs localhost in that mode, not the service name.

Why does my API container fail to connect to Postgres even though both are running?
Two common causes. Either the connection string still says localhost instead of the Postgres service name, which only works when both processes run on the host, or the API started before Postgres finished initializing. A depends_on healthcheck condition on the Postgres service fixes the second case.

Do I need Docker Compose if I'm the only developer on the project?
It's still worth it for consistency between your machine and CI, and for making onboarding trivial if the team grows. If the project stays genuinely solo and short-lived, running services natively is a fair simplification; add Compose back once a second person or a CI pipeline needs the same setup.

Why is file watching so slow inside a Docker container on macOS?
Bind mounts on macOS go through a virtualization layer that's slower than native filesystem access, and file-watching mechanisms like inotify don't cross that boundary as efficiently as on Linux. Docker Desktop's newer virtualization backends (VirtioFS on macOS) reduce this significantly, so keeping Docker Desktop current matters more here than most people expect.

Can I use the same Dockerfile for development and production?
Yes, through multi-stage builds with separate targets, as shown above. Trying to use one undifferentiated stage for both usually means either a slow production image full of dev dependencies, or a development setup that requires a full rebuild on every code change, since it lacks the bind-mount and watch behavior a dev loop needs.

What's the difference between depends_on and a healthcheck?
depends_on alone only guarantees Docker starts one container before another; it says nothing about whether the first service is actually ready to accept traffic. Adding a healthcheck to the dependency and a condition: service_healthy on the dependent service makes Compose wait for real readiness, which matters most for databases that take a moment to accept connections after the process starts.

About the Author

Hi, I'm Aman Singh — Senior Full Stack Engineer specializing in scalable SaaS products, distributed systems, cloud architecture, and AI-powered applications.

I write about System Design, Full Stack Engineering, Distributed Systems, Redis, PostgreSQL, AWS, Node.js, and NestJS.

Portfolio: https://amanksingh.com
GitHub: https://github.com/amansingh1501
Product: https://vowerole.com
Email: aman97aman@gmail.com

Choosing Prisma or TypeORM for Your NestJS API

Aman Kumar Singh — Tue, 21 Jul 2026 07:51:59 +0000

Last time, setting up PostgreSQL the right way, I left one thing unresolved on purpose: the database has a schema and a connection string, but nothing in the API talks to it yet. That gap is filled by a data-access layer, and in the NestJS world the two real contenders are Prisma and TypeORM.

This is part six of the Full Stack SaaS Masterclass, and it's the kind of decision that's easy to treat as a coin flip but actually shapes how your team writes queries for years. Get it wrong for your team's style and you'll spend a lot of time fighting the abstraction instead of shipping features.

Here's how each one actually works in a NestJS app, where they genuinely differ, and the production pitfalls that don't show up in the getting-started docs, plus which one I reach for and why.

Why this decision is bigger than it looks

An ORM, or in Prisma's case a query builder with ORM-like ergonomics, sits between every request your API handles and the database that backs it. That's a lot of surface area for a decision made in week one.

Three things make this choice consequential rather than cosmetic:

Migrations become part of your deploy pipeline. Both tools generate and run migrations, but they do it differently enough that switching later means rewriting your entire migration history, not just swapping an import.

Type safety at the query boundary compounds. Loosely typed query results leak looseness into every service and controller downstream. Strictly typed results turn a schema change into a compile error in the right place instead of a runtime surprise in production.

The abstraction shapes how your team thinks about SQL. Some tools want you to write SQL-adjacent code and get out of the way. Others hide SQL almost entirely behind a generated client. Picking one changes what "normal" looks like in code review for the next few years.

None of this needs weeks of debate. It deserves the twenty minutes this article takes, rather than picking whichever one showed up first in a tutorial search.

Prisma: schema-first, with a generated client

Prisma's model is a single source of truth: a schema.prisma file that describes your tables, and a code generation step that turns it into a fully typed client.

// prisma/schema.prisma
datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

generator client {
  provider = "prisma-client-js"
}

model Organization {
  id        String   @id @default(uuid())
  name      String
  users     User[]
  createdAt DateTime @default(now()) @map("created_at")

  @@map("organizations")
}

model User {
  id             String       @id @default(uuid())
  email          String       @unique
  name           String
  organization   Organization @relation(fields: [organizationId], references: [id])
  organizationId String       @map("organization_id")
  createdAt      DateTime     @default(now()) @map("created_at")

  @@map("users")
}

Running npx prisma migrate dev reads that file, diffs it against the current database state, generates a SQL migration, and applies it. Running npx prisma generate produces a TypeScript client with a type for every model and every query shape, including relations.

npx prisma migrate dev --name add_organizations
npx prisma generate

Wiring it into NestJS is a single injectable service that extends PrismaClient and manages its own connection lifecycle:

// src/prisma/prisma.service.ts
import { Injectable, OnModuleInit, OnModuleDestroy } from '@nestjs/common';
import { PrismaClient } from '@prisma/client';

@Injectable()
export class PrismaService extends PrismaClient implements OnModuleInit, OnModuleDestroy {
  async onModuleInit() {
    await this.$connect();
  }

  async onModuleDestroy() {
    await this.$disconnect();
  }
}

// src/modules/users/users.service.ts
import { Injectable } from '@nestjs/common';
import { PrismaService } from '../../prisma/prisma.service';

@Injectable()
export class UsersService {
  constructor(private readonly prisma: PrismaService) {}

  findById(id: string) {
    return this.prisma.user.findUnique({
      where: { id },
      include: { organization: true },
    });
  }
}

The return type of findById is inferred correctly, organization included and all, with no manual type annotation. That's Prisma's strongest pitch: the schema is the type. The client can't drift from what the database actually looks like, because it's generated from a migration history that ran against a real database.

TypeORM: entities, decorators, and the repository pattern

TypeORM takes the more familiar object-relational route. Tables are TypeScript classes decorated with metadata, and a repository object gives you query methods scoped to that entity.

// src/modules/users/entities/user.entity.ts
import {
  Entity, PrimaryGeneratedColumn, Column, ManyToOne,
  CreateDateColumn, JoinColumn,
} from 'typeorm';
import { Organization } from '../../organizations/entities/organization.entity';

@Entity('users')
export class User {
  @PrimaryGeneratedColumn('uuid')
  id: string;

  @Column({ unique: true })
  email: string;

  @Column()
  name: string;

  @ManyToOne(() => Organization, (org) => org.users)
  @JoinColumn({ name: 'organization_id' })
  organization: Organization;

  @Column({ name: 'organization_id' })
  organizationId: string;

  @CreateDateColumn({ name: 'created_at' })
  createdAt: Date;
}

Registering it in the app module and pulling in a repository looks like this:

// src/app.module.ts
import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { UsersModule } from './modules/users/users.module';

@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true }),
    TypeOrmModule.forRootAsync({
      inject: [ConfigService],
      useFactory: (config: ConfigService) => ({
        type: 'postgres',
        url: config.get<string>('DATABASE_URL'),
        entities: [__dirname + '/**/*.entity{.ts,.js}'],
        migrations: [__dirname + '/migrations/*{.ts,.js}'],
        synchronize: false, // never true outside a throwaway sandbox
      }),
    }),
    UsersModule,
  ],
})
export class AppModule {}

// src/modules/users/users.service.ts
import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { User } from './entities/user.entity';

@Injectable()
export class UsersService {
  constructor(
    @InjectRepository(User) private readonly users: Repository<User>,
  ) {}

  findById(id: string) {
    return this.users.findOne({
      where: { id },
      relations: { organization: true },
    });
  }
}

TypeORM's migrations are written and run separately from your entity definitions. You either hand-write a migration in SQL or SQL-adjacent TypeScript, or generate one from a diff against your current entities:

npx typeorm migration:generate src/migrations/AddOrganizations -d src/data-source.ts
npx typeorm migration:run -d src/data-source.ts

That synchronize: false line in the config above is doing real work. TypeORM's synchronize: true will happily mutate your schema to match your entities on every boot, which is fine for a local sandbox and a genuinely dangerous default anywhere real data lives.

Tradeoffs that actually matter

Once you've written a few queries in each, the differences that matter in production stop being about syntax and start being about these:

Type inference depth. Prisma's generated client infers return shapes precisely, including nested includes, without you writing a single interface by hand. TypeORM's typing is real but shallower: relations you forget to load show up as undefined at runtime with a type that still claims they exist, unless you're careful with strict null settings and consistent relations options.

Migration authorship. Prisma's migration files are auto-generated SQL you review and commit; you rarely hand-edit them. TypeORM expects you to be comfortable reading and occasionally writing the generated migration yourself, a feature if your team is SQL-fluent and friction if it isn't.

Escape hatches to raw SQL. Both support raw queries when the query builder can't express what you need: $queryRaw in Prisma, query() on the data source in TypeORM. Prisma's raw escape hatch feels like a deliberate exception. TypeORM's query builder sits closer to SQL by default, so you reach for raw queries less often, at the cost of more verbose everyday code.

Active record versus data mapper. TypeORM supports an active-record style, where entities carry their own save() and remove() methods, alongside the repository pattern shown above. Prisma has no active-record mode; every query goes through the client. Teams that like a model instance managing its own persistence get that option with TypeORM. Prisma keeps persistence logic in services by design, with no alternative path.

Transactions. Prisma wraps a set of operations in $transaction, either as an array of promises or an interactive callback. TypeORM offers the same through dataSource.transaction() or a manually managed QueryRunner when you need row-level locking across several steps.

// Prisma: interactive transaction
await this.prisma.$transaction(async (tx) => {
  const org = await tx.organization.create({ data: { name: 'Acme' } });
  await tx.user.create({
    data: { email: 'owner@acme.com', name: 'Owner', organizationId: org.id },
  });
});

// TypeORM: transaction via the data source
await this.dataSource.transaction(async (manager) => {
  const org = await manager.save(Organization, { name: 'Acme' });
  await manager.save(User, {
    email: 'owner@acme.com',
    name: 'Owner',
    organizationId: org.id,
  });
});

Neither approach is meaningfully safer than the other. Both give you a real transaction boundary, which is what matters.

Production pitfalls worth knowing before you commit

A few things look fine in a tutorial and turn into real problems once real traffic hits.

N+1 queries hide differently in each tool. Prisma's include and TypeORM's relations both prevent the classic N+1 pattern when used up front, but it's easy to lazily reach into a relation later in code that assumed it was loaded. The fix is the same regardless of ORM: decide what a query needs to return before you write it, load it explicitly, and treat unexpected extra queries in your logs as a bug, not a curiosity.

Connection pooling needs a plan beyond the defaults. A serverless deployment target opens and closes many short-lived connections, and neither tool's default pool handles that well without something like PgBouncer in front of Postgres. Confirm your deployment target before assuming defaults are fine.

Migration drift between environments is a process problem, not a tooling one. Both tools can produce a migration that works locally and fails in CI because someone edited the database by hand, the same discipline problem flagged in the previous article. Treat every schema change as a migration file, checked in and reviewed.

Schema-first and entity-first genuinely diverge on refactors. Renaming a column in Prisma means editing one line in schema.prisma and regenerating a migration; the client updates automatically everywhere. Renaming a column with TypeORM entities means updating the decorator, generating or writing the migration, and trusting that every place referencing the old property name gets caught by the compiler. It usually does, but test that assumption before relying on it for a large refactor.

Testing needs a real strategy either way. Mocking a Prisma client or a TypeORM repository works for unit tests, but joins, transactions, and constraint violations only get proven against a real Postgres instance. Plan for an integration suite against a containerized database rather than trusting mocks alone.

If I'm choosing today, for a new SaaS with a small team, I reach for Prisma. The generated types remove a category of drift bugs for free, and the schema-first workflow keeps the whole team looking at one file to understand the data model. TypeORM earns its place when the team is already SQL-fluent and wants active record or fine-grained query builder control, or when the project has legacy TypeORM entities not worth migrating away from. Neither choice is wrong. Just don't switch mid-project once real migrations exist; that cost is the one thing both tools genuinely make expensive.

Key takeaways

Prisma is schema-first: one schema.prisma file generates both migrations and a fully typed client, so query results are inferred without hand-written types.
TypeORM is entity-first: decorated classes define your tables, with a repository or active-record API and separately authored or generated migrations.
Type inference is deeper and more automatic in Prisma; TypeORM is real but needs discipline around loaded relations and strict null settings.
Both support transactions and raw SQL escape hatches; the difference is how often you reach for the escape hatch in everyday code.
N+1 queries, connection pooling under serverless, and migration drift are pitfalls in both tools, not unique to either.
Pick based on team fluency and how schema-first versus entity-first fits how your team already thinks, and treat switching mid-project as an expensive, rare event.

FAQ

Is Prisma or TypeORM better for a NestJS project?
Neither is universally better. Prisma's schema-first model and generated client give deeper type safety with less manual work, which suits most new SaaS projects. TypeORM's entity and repository model suits teams that want SQL-adjacent control, active-record persistence, or already have an existing TypeORM codebase.

Can I use Prisma and TypeORM together in the same NestJS app?
Technically yes, since both can coexist as separate connections, but it's rarely worth the complexity of maintaining two migration histories and two mental models for the same database. Pick one for the whole app unless you have a specific, isolated reason not to.

Does Prisma support raw SQL when the query builder isn't enough?
Yes, through $queryRaw and $executeRaw, both of which stay typed when you tag the result shape. It's an occasional escape hatch, not a primary way of writing queries.

Why shouldn't I use TypeORM's synchronize: true in production?
It mutates your live schema to match your entity definitions on every application boot, with no migration file, no review step, and no rollback path. Convenient for a disposable local sandbox, and a serious risk anywhere real data exists, since a single bad entity change can alter or drop a column silently.

How do migrations work differently between the two tools?
Prisma generates a migration by diffing your schema file against the database's current state, and you rarely edit the generated SQL by hand. TypeORM either generates a migration from an entity diff or expects you to write one directly in SQL-adjacent TypeScript, trading manual control for manual responsibility.

Which ORM handles multi-tenant SaaS schemas better?
Both handle the shared-schema, organization_id-per-row approach shown in this article equally well; the pattern is a modeling decision, not something one ORM does natively and the other doesn't. Row-level security or per-tenant schemas, if you go that route later, add configuration work regardless of which tool you're using.

About the Author

Hi, I'm Aman Singh — Senior Full Stack Engineer specializing in scalable SaaS products, distributed systems, cloud architecture, and AI-powered applications.

I write about System Design, Full Stack Engineering, Distributed Systems, Redis, PostgreSQL, AWS, Node.js, and NestJS.

Portfolio: https://amanksingh.com
GitHub: https://github.com/amansingh1501
Product: https://vowerole.com
Email: aman97aman@gmail.com

Setting Up PostgreSQL the Right Way

Aman Kumar Singh — Tue, 21 Jul 2026 07:51:56 +0000

The NestJS API from last time can validate a request and return a typed User, but right now that user lives nowhere. It's time to give the app a memory. In this series that memory is PostgreSQL, and the way you set it up in the first hour decides whether your data layer stays boring for years or turns into a source of 2am incidents.

This article covers the foundation: getting Postgres running the same way for everyone on the team, connecting the API to it safely, and thinking about your first schema without painting yourself into a corner. Query tuning and partitioning can wait.

This is part five of the Full Stack SaaS Masterclass, continuing from the NestJS API in apps/api.

Run it in Docker, not on your laptop

The first decision is where Postgres actually runs during development, and the answer is a container. Installing Postgres directly on your machine works right up until a teammate has a different version, or you need a second project on a different major release, and then you're debugging the database instead of building features.

We already committed to Docker for local reproducibility back in the stack article. Here's the postgres service in docker-compose.yml at the repo root:

# docker-compose.yml
services:
  postgres:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_USER: saas
      POSTGRES_PASSWORD: local_dev_only
      POSTGRES_DB: saas_dev
    ports:
      - '5432:5432'
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

One docker-compose up and every teammate has Postgres 16 on port 5432 with the same database name. The named pgdata volume means your data survives a container restart, and pinning postgres:16 rather than postgres:latest means an image update never silently changes your major version underneath you.

Connect the API without leaking secrets

The API reaches Postgres through a connection string. Keep it in the environment, never in code, and give it a sensible shape:

# apps/api/.env
DATABASE_URL=postgresql://saas:local_dev_only@localhost:5432/saas_dev

That local_dev_only password is fine to commit to an .env.example because it only ever guards a throwaway local container. Production credentials are a different story, and we'll handle environment variables and secrets properly in their own article shortly. The habit to build now: the code reads DATABASE_URL through @nestjs/config, and the value changes per environment while the code never does.

// reading it the right way, via injected config
const url = this.config.get<string>('DATABASE_URL');

Think in schema, not in tables

Before writing a single CREATE TABLE, it helps to decide how you'll reason about your data. For a multi-tenant SaaS, the question that shapes everything is: how does a row know which organization it belongs to? We'll design multi-tenancy in depth later, but the choice you make here ripples through every table, so it's worth naming early.

For the foundation, keep it simple and correct. A users table with a real primary key, a unique constraint where the data demands one, timestamps, and columns that match the shared User type the frontend and backend both import:

CREATE TABLE users (
  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  email       TEXT NOT NULL UNIQUE,
  name        TEXT NOT NULL,
  created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
);

A few choices in that small block earn their keep. UUID primary keys instead of auto-incrementing integers mean IDs aren't guessable and don't leak how many users you have, which matters the moment IDs appear in URLs. The UNIQUE constraint on email pushes the rule into the database, so two requests racing to register the same address can't both win. And TIMESTAMPTZ rather than a plain timestamp stores the time zone, saving you a category of bugs that only surface once you have users in a second country.

Migrations from the very first table

Never change a schema by hand in a running database and hope everyone else runs the same commands. From day one, every schema change is a migration: a versioned, checked-in file that moves the database from one known state to the next, and that runs the same way on your laptop, in CI, and in production.

The tool you use for migrations usually comes with your data-access layer, which is the subject of the next article. The principle holds regardless of tool. A schema change that isn't a committed migration is a change that will drift between environments and eventually break a deploy.

apps/api/migrations/
├── 0001_create_users.sql
└── 0002_add_organizations.sql   # each one moves the schema forward

Numbered, ordered, forward-only in spirit. When something goes wrong in production, you want to point at an exact migration, not guess which of five people ran which SQL by hand.

What to defer

Postgres has a deep feature set, and almost none of it belongs in your first week. You don't need read replicas or connection pooling infrastructure at zero users; a single instance handles far more traffic than a new SaaS will see for a long time. You don't need partitioning until a table is genuinely large. You don't need to reach for JSONB everywhere just because it's flexible; model relational data relationally and use JSONB for the parts that are actually schemaless.

The foundation is small on purpose: a containerized Postgres, a connection string in the environment, a clean first schema with real constraints, and migrations from the start. That's enough to build real features on, and everything else is a decision you'll make better later, with real data in front of you.

Next in the series, we put a data-access layer on top of this: choosing between Prisma and TypeORM, and wiring it into the NestJS app so those migrations and queries are typed end to end.

Key takeaways

Run Postgres in Docker with a pinned major version and a named volume, so every environment matches and data survives restarts.
Keep the connection string in the environment and read it through config; the value changes per environment, the code never does.
Design your first schema with real constraints: UUID keys, unique constraints, and TIMESTAMPTZ for time.
Treat every schema change as a versioned, committed migration from the very first table.
Defer replicas, partitioning, and JSONB-everywhere until real data justifies them.

FAQ

Should I run PostgreSQL locally or in Docker for development?
Use Docker. A pinned image such as postgres:16 with a named volume gives every teammate the same version and persistent data, and avoids the version mismatches that come from installing Postgres directly on each machine.

Why use UUIDs instead of auto-incrementing IDs?
UUIDs aren't sequential, so they don't reveal how many records you have and aren't guessable when they appear in URLs. Auto-incrementing integers are fine internally but leak information once exposed.

What's the right way to manage schema changes?
Migrations: versioned, checked-in files that move the schema forward and run identically across laptop, CI, and production. Editing a live database by hand causes drift between environments and eventually breaks deploys.

Should I store connection credentials in code?
No. Keep the connection string in an environment variable and read it through your config layer. Only a throwaway local password belongs in a committed .env.example; real credentials stay out of the repo entirely.

When should I worry about replicas and partitioning?
Later. A single Postgres instance serves a new SaaS for a long time. Add read replicas, connection pooling, and partitioning when real traffic or table size makes them necessary, not in anticipation.

About the Author

Hi, I'm Aman Singh — Senior Full Stack Engineer specializing in scalable SaaS products, distributed systems, cloud architecture, and AI-powered applications.

I write about System Design, Full Stack Engineering, Distributed Systems, Redis, PostgreSQL, AWS, Node.js, and NestJS.

Portfolio: https://amanksingh.com
GitHub: https://github.com/amansingh1501
Product: https://vowerole.com
Email: aman97aman@gmail.com

Two Pointers & Sliding Window, Explained Simply

Aman Kumar Singh — Tue, 21 Jul 2026 07:08:50 +0000

The first time someone showed me the sliding window technique, my reaction was mild annoyance. I'd been solving a substring problem with nested loops, feeling clever, and they collapsed it into a single pass with two variables. My O(n²) turned into O(n) and I felt slightly robbed.

That's how two pointers and sliding window work. They look like tricks until they click, and then they feel obvious. They're the answer to a huge slice of array and string problems, especially the ones where a hash map would burn memory you don't need to spend.

This is part three of the Senior Engineer Handbook series. We've covered interview strategy and the hashing patterns. Now the two techniques I reach for whenever the input is sorted or the problem mentions a "substring" or "subarray."

Two pointers: walking from both ends

The setup: a sorted array, and you want a pair that satisfies some condition. The naive move is to check every pair, which is O(n²). Two pointers uses the sortedness to skip almost all of that work.

Put one pointer at the start, one at the end. Look at the sum. Too big? The largest element is too heavy, so move the right pointer left. Too small? Move the left pointer right. Every step eliminates a whole set of pairs you no longer need to check.

function twoSumSorted(nums: number[], target: number): [number, number] | null {
  let left = 0;
  let right = nums.length - 1;

  while (left < right) {
    const sum = nums[left] + nums[right];
    if (sum === target) return [left, right];
    if (sum < target) left++;   // need a bigger sum, move up from the small end
    else right--;               // need a smaller sum, move down from the big end
  }
  return null;
}

Notice this uses zero extra memory. On a sorted array this beats the hash-map version from the last article: same O(n) time, but O(1) space instead of O(n). This is exactly the "the input's sorted, so I'll use two pointers instead of a map" move I mentioned earlier. Saying that in an interview shows you're choosing tools, not reaching for the same one every time.

Two pointers isn't only start-and-end, though. Sometimes both pointers move the same direction at different speeds. That's how you remove duplicates from a sorted array in place, or detect a cycle in a linked list. The unifying idea is: two indices, each moving under its own rule, replacing a nested loop.

Sliding window: the expanding and shrinking frame

Now the one I love. Sliding window is for problems about a contiguous stretch: the longest substring with some property, the smallest subarray that hits a sum, the max of every window of size k.

Picture a frame over the array. You grow it from the right, and when it violates a constraint, you shrink it from the left. The window slides forward, never backtracking, so the whole array is processed in one pass.

Here's the canonical one: longest substring without repeating characters.

function longestUniqueSubstring(s: string): number {
  const lastSeen = new Map<string, number>(); // char -> most recent index
  let start = 0; // left edge of the window
  let best = 0;

  for (let end = 0; end < s.length; end++) {
    const ch = s[end];
    // If we've seen this char inside the current window, jump start past it.
    if (lastSeen.has(ch) && lastSeen.get(ch)! >= start) {
      start = lastSeen.get(ch)! + 1;
    }
    lastSeen.set(ch, end);
    best = Math.max(best, end - start + 1);
  }
  return best;
}

The end pointer expands the window every iteration. The moment we hit a repeat, start jumps forward to kick the duplicate out. The window is always valid, and its widest size is the answer. One pass, O(n).

The part that took me longest to trust: start only ever moves forward. It never resets. That's what keeps it linear: each character enters the window once and leaves at most once.

Fixed vs dynamic windows

Two flavors, and knowing which you're in makes the code fall out naturally.

A fixed window has a known size k: "maximum sum of any k consecutive elements." You slide a frame of constant width: add the new element, drop the one that fell off the back.

function maxSumWindow(nums: number[], k: number): number {
  let sum = 0;
  for (let i = 0; i < k; i++) sum += nums[i]; // first window

  let best = sum;
  for (let i = k; i < nums.length; i++) {
    sum += nums[i] - nums[i - k]; // slide: add front, drop back
    best = Math.max(best, sum);
  }
  return best;
}

That sum += nums[i] - nums[i - k] line is the whole trick. Instead of re-summing k elements every step, you adjust by one in and one out. O(n) instead of O(n·k).

A dynamic window grows and shrinks based on a condition: "smallest subarray with sum ≥ target." You expand until the condition is met, then shrink while it stays met, tracking the best. The unique-substring example above is dynamic. The shape is: expand in the loop, shrink in an inner while.

How to know it's a window problem

The keywords give it away more than almost any other pattern. If I see:

"longest / shortest / maximum / minimum substring or subarray"
"contiguous"
"window of size k"
"at most / at least k of something"

my hand is already reaching for a sliding window. If instead it's a sorted array and I want pairs or a partition point, it's two pointers. If it's neither sorted nor contiguous, I go back to hashing from the last article.

That triage, narrowing to a pattern from the phrasing before I write anything, is the single habit that made interviews stop feeling like luck.

The mistake almost everyone makes

Backtracking the left pointer. People shrink the window, then later move start backward when a new element comes in, and suddenly it's O(n²) again and they can't figure out why it's slow. The whole point of these techniques is that each pointer marches forward and never retreats. If you catch yourself wanting to move a pointer back, the pattern is probably wrong for the problem. Stop and reconsider.

The other one: off-by-one errors in the window width. end - start + 1 is the size of an inclusive window. I've written end - start under pressure more times than I'd like to admit and watched my answer come out one short. Test a two-character example by hand before you trust it.

These two patterns plus the hashing ones from last time cover a genuinely large fraction of what you'll be asked. Next in the series, we go into binary search, including the "search on the answer" trick that solves problems that don't look like search problems at all.

Key takeaways

Two pointers exploits a sorted array to find pairs or partitions in O(n) time and O(1) space, with no hash map needed.
Sliding window handles contiguous substring and subarray problems in a single forward pass.
Fixed windows adjust by one-in-one-out; dynamic windows expand to satisfy a condition, then shrink while it holds.
Both pointers only ever move forward. Backtracking a pointer is the bug that quietly turns O(n) back into O(n²).
Triage by phrasing: "substring/subarray/contiguous/window" means sliding window; "sorted + pairs" means two pointers.

FAQ

When should I use two pointers vs a hash map?
Two pointers when the array is sorted and you want pairs, partitions, or in-place work with O(1) space. A hash map when the data is unsorted and you need to look up values you've already seen. On a sorted array, two pointers usually beats a map on memory.

How do I recognize a sliding window problem?
Look for words like longest, shortest, maximum, minimum paired with substring, subarray, contiguous, or "window of size k." Those almost always point to a sliding window.

What's the difference between a fixed and dynamic sliding window?
A fixed window has a constant size k and slides one element at a time. A dynamic window grows until a condition is satisfied and shrinks while it stays satisfied, so its size changes as it moves.

Why does the sliding window stay O(n) if there's a nested while loop?
Because each element enters the window once and leaves at most once. The inner loop's total work across the whole run is bounded by n, so it's still linear overall.

What's the most common sliding window bug?
Backtracking a pointer, which reintroduces O(n²) behavior, and off-by-one mistakes on window size. Remember an inclusive window is end - start + 1 wide.

About the Author

Hi, I'm Aman Singh — Senior Full Stack Engineer specializing in scalable SaaS products, distributed systems, cloud architecture, and AI-powered applications.

I write about System Design, Full Stack Engineering, Distributed Systems, Redis, PostgreSQL, AWS, Node.js, and NestJS.

Portfolio: https://amanksingh.com
GitHub: https://github.com/amansingh1501
Product: https://vowerole.com
Email: aman97aman@gmail.com

Arrays & Hashing: The Interview Patterns You Must Know

Aman Kumar Singh — Tue, 21 Jul 2026 07:03:42 +0000

If I had to bet on what your next coding interview opens with, I'd put money on an array problem that's secretly a hashing problem. They're everywhere. Two-sum, group anagrams, subarray sums, "find the duplicate." Different clothes, same skeleton underneath.

The engineers who breeze through these aren't faster typists. They've just learned to see the hash map hiding inside the array question. Once you see it, you can't unsee it, and a whole category of problems stops being scary.

This is the second article in the Senior Engineer Handbook series. Last time we covered how to approach interviews. Now we get specific.

Why hashing shows up so often

Most array problems are slow for one reason: you're searching. "Have I seen this value before?" "Does its complement exist?" "How many times has this appeared?" The naive answer to every one of those is a nested loop: scan the array again for each element. That's O(n²), and O(n²) is the thing the interviewer is quietly waiting for you to kill.

A hash map turns "search the whole array" into "check one key." O(n) lookups collapse to O(1). That single move is the difference between the brute-force answer and the one that gets you a callback.

So when a problem involves searching, counting, or matching inside an array, my first instinct is: what would I store in a map to make the lookup instant?

Pattern 1: complement lookup

The classic. You're looking for two things that combine to a target. Instead of checking every pair, store what you've seen and ask whether the piece you need is already there.

function twoSum(nums: number[], target: number): [number, number] | null {
  const seen = new Map<number, number>(); // value -> index
  for (let i = 0; i < nums.length; i++) {
    const need = target - nums[i];
    if (seen.has(need)) return [seen.get(need)!, i];
    seen.set(nums[i], i);
  }
  return null;
}

The mental model: as I walk the array, I keep a record of everything behind me, so when I land on a number I can instantly ask "did its partner already go by?" No second loop. One pass.

This same shape solves far more than two-sum. "Find if any two elements differ by k." "Does a pair exist that sums to a value?" Same skeleton, different arithmetic on the key.

Pattern 2: frequency counting

The second workhorse. Whenever a problem cares about how many times something appears (most frequent element, first non-repeating character, "can these two strings be anagrams"), you're building a frequency map.

function firstUniqueChar(s: string): number {
  const count = new Map<string, number>();
  for (const ch of s) count.set(ch, (count.get(ch) ?? 0) + 1);

  for (let i = 0; i < s.length; i++) {
    if (count.get(s[i]) === 1) return i;
  }
  return -1;
}

Two passes, both O(n). First pass tallies, second pass reads the tally. I like this one in interviews because it's easy to narrate cleanly: "count everything, then find the first thing with a count of one." The interviewer follows you the whole way.

A tell for anagram problems specifically: two strings are anagrams if their frequency maps are identical. You don't need to sort: sorting is O(n log n) and counting is O(n). If you reach for .sort() here, expect the interviewer to ask "can you do better?"

Pattern 3: grouping by a computed key

This one trips people up because the key isn't the value itself. It's something you derive from it. Group anagrams is the poster child: the key is the sorted version of each word, and all words sharing that key belong together.

function groupAnagrams(words: string[]): string[][] {
  const groups = new Map<string, string[]>();
  for (const word of words) {
    // Words that are anagrams collapse to the same sorted key.
    const key = word.split('').sort().join('');
    const bucket = groups.get(key) ?? [];
    bucket.push(word);
    groups.set(key, bucket);
  }
  return [...groups.values()];
}

Worth saying out loud: "I need a signature that's the same for every anagram and different for everything else." Sorted letters is one such signature. A 26-length letter-count array is another (and faster). Naming that idea ("I need a canonical key") is exactly the kind of reasoning senior interviews reward.

Pattern 4: prefix sums with a map

Now the one that separates people. "How many subarrays sum to k?" The brute force checks every subarray, which is O(n²). The trick is a running total plus a hash map of totals you've seen.

function subarraySumEqualsK(nums: number[], k: number): number {
  const seen = new Map<number, number>([[0, 1]]); // prefixSum -> how many times
  let running = 0;
  let count = 0;

  for (const n of nums) {
    running += n;
    // If (running - k) appeared before, every such prefix marks a valid subarray end here.
    count += seen.get(running - k) ?? 0;
    seen.set(running, (seen.get(running) ?? 0) + 1);
  }
  return count;
}

I won't pretend this one is obvious. It took me a few sittings to really get why running - k is the thing to look up. The idea: if the total up to here is running, and some earlier point had total running - k, then the stretch between them sums to exactly k. The map counts how many such earlier points exist.

If you only memorize one non-trivial pattern from this article, make it this one. Prefix-sum-plus-map shows up constantly and always looks impressive because most people don't see it.

When a hash map is the wrong answer

Reaching for a map reflexively is its own trap, so let me push back on my own advice.

Maps cost memory. If the problem says "solve it in O(1) space," a hash map is off the table and they probably want two pointers or in-place index marking instead. If the array is sorted, a map throws away information you could've used; two pointers or binary search is often cleaner and uses no extra space. And for tiny fixed alphabets (lowercase letters), a plain 26-slot array beats a Map on both speed and clarity.

Part of sounding senior is knowing when not to use the tool you like. If you say "a hash map would work, but since the input's sorted I can do this in O(1) space with two pointers," you've just shown range.

How to recognize which pattern you're in

A quick field guide for the pressure of the moment:

Looking for pairs/complements that hit a target → complement lookup
Counting occurrences, or comparing multisets/anagrams → frequency map
Bucketing items that share a derived property → group by computed key
Anything about contiguous subarray sums or counts → prefix sum + map
Sorted input, or an O(1)-space constraint → step back, consider two pointers instead

Say the category out loud when you spot it. "This is a frequency-counting problem" tells the interviewer you've mapped it to a known shape, and it steadies your own hands.

Next in the series, we leave hashing behind for the two techniques that dominate sorted-array and substring problems: two pointers and the sliding window.

Key takeaways

Most slow array solutions are slow because they search; a hash map turns O(n) searches into O(1) lookups.
Four patterns cover the majority of interview questions: complement lookup, frequency counting, grouping by a computed key, and prefix sum with a map.
For anagrams, compare frequency maps instead of sorting; O(n) beats O(n log n).
Prefix-sum-plus-map (subarrays summing to k) is the highest-value non-obvious pattern; learn it cold.
A hash map is the wrong choice when space must be O(1) or the array is already sorted; reach for two pointers there.

FAQ

When should I use a hash map in an array problem?
When you're searching, counting, or matching: anything where the naive answer is a nested loop scanning the array again. A map makes those lookups O(1) and drops the overall time from O(n²) to O(n).

Why not just sort the array instead of hashing?
Sorting is O(n log n) and destroys the original order. Hashing is O(n) and preserves order. Sort only when the problem genuinely needs ordering or when a sorted array unlocks two pointers with O(1) space.

What's the prefix sum pattern and when do I use it?
Keep a running total and store each total in a map. For "count subarrays summing to k," look up running - k to find where valid subarrays start. Use it for any contiguous-subarray sum or count question.

How do I check if two strings are anagrams efficiently?
Build a frequency count for each and compare, or use a single 26-length array of letter counts. Both are O(n), faster than sorting both strings.

Are hash map solutions always the best?
No. They cost memory. If the problem demands O(1) space or the input is sorted, two pointers or binary search is usually cleaner and lighter.

About the Author

Hi, I'm Aman Singh — Senior Full Stack Engineer specializing in scalable SaaS products, distributed systems, cloud architecture, and AI-powered applications.

I write about System Design, Full Stack Engineering, Distributed Systems, Redis, PostgreSQL, AWS, Node.js, and NestJS.

Portfolio: https://amanksingh.com
GitHub: https://github.com/amansingh1501
Product: https://vowerole.com
Email: aman97aman@gmail.com

The Senior Engineer's Guide to Coding Interviews

Aman Kumar Singh — Tue, 21 Jul 2026 07:03:40 +0000

I bombed a coding interview about 4 years into my career. Not because I couldn't code; I'd shipped plenty of production software by that point, and I knew the language cold. I just froze on a problem I'd have solved in 5 minutes at my own desk, and the interviewer sat there watching me flail while I watched myself do the exact same thing, and neither of us really enjoyed the half hour it took.

That whole experience taught me something years of grinding leetcode never did. Senior interviews are a genuinely different game, and if you prepare for one the way a junior would, you tend to get rejected the way a junior does, however strong an engineer you actually happen to be.

So this is more or less the guide I wish someone had handed me back then. It focuses on the approach itself rather than a pile of problems to memorize.

What interviewers are really checking at the senior level

When you ask a junior "can you solve this?", that's basically the whole test right there. When you ask a senior the exact same question, something else is going on underneath it entirely; what they're really asking is whether you can think, and whether they could hand you something vague and half-specified and still trust you to come back with a reasonable answer.

The problem on the whiteboard barely matters on its own; it's mostly a prop for the real evaluation that's happening around it.

What they're really doing the whole time is watching how you work. They notice whether you clarify things before you start typing or whether you assume and charge in. They notice whether you go quiet and freeze the moment you hit a wall, or whether you keep thinking out loud. And they're quietly checking whether you can actually weigh tradeoffs or only really know the one approach, and whether the code you leave behind is something a teammate could still read 6 months later without hating you for it.

I've sat on both sides of that table. As the interviewer, I've honestly passed people who never even finished the problem, just because their reasoning was clean and they were upfront about the gaps; and I've failed people who reached the optimal answer and then couldn't tell me why it actually worked, or what they'd change if the constraints shifted a little. That second group concerned me more, because a correct answer that the candidate can't really explain tells you very little about how they'd actually work day to day.

The framework I actually use

I run more or less the same loop on every single problem. It's deliberately boring, and that's the entire point; a boring, repeatable process is the thing that keeps you actually moving forward when you're under pressure and your mind wants to go blank on you.

Restate and clarify. Say the problem back to them in your own words first, and then ask the questions that actually change the answer: how big the input really is, whether it can be empty, whether there are duplicates in it, whether it's already sorted, and whether you're supposed to be optimizing for time or for space. None of that is stalling. A good clarifying question is one of the clearest early signals of seniority there is.
Talk through the naive approach first. Say the brute-force version out loud, even when it's obviously way too slow. Something like: "the straightforward way here is O(n²), just nested loops comparing every pair; let me get that working first and then optimize." This does two things at once. It gets a working baseline up on the board, and it shows the interviewer that you understand exactly where you're starting from.
Find the bottleneck, then optimize it. Don't jump straight to the clever trick. Point at the expensive part first. "the nested loop is the problem here; if I had O(1) lookups instead of scanning every time, this drops to O(n), which basically points me at a hash map." Optimization should look like a decision you actually made. It shouldn't read as a trick you happened to recall from memory.
Write it cleanly. Use real names. left and right, not i and j, when they actually carry meaning. Add a small helper function when it genuinely improves readability. The interviewer is quietly picturing you as a teammate the whole time you write, so give them an actual reason to want that.
Test it yourself. Walk through a normal case first, then an edge case, out loud, before anyone even asks you to. Catching your own bug is worth a lot more than never having written one in the first place.

Here's the loop applied to the most common opener, two-sum:

function twoSum(nums: number[], target: number): [number, number] | null {
  // seen maps a value we've passed -> the index it was at.
  // One pass, O(1) lookups, so O(n) total instead of the O(n²) double loop.
  const seen = new Map<number, number>();

  for (let i = 0; i < nums.length; i++) {
    const need = target - nums[i];
    if (seen.has(need)) return [seen.get(need)!, i];
    seen.set(nums[i], i);
  }

  return null; // no pair sums to target
}

Nothing there is actually fancy. What makes it a senior answer is really everything around it; the "I'll start with the double loop and then trade space for time" narration, the comment that explains why rather than what, and the null case that's handled instead of just quietly ignored.

The mistakes that sink senior candidates

The first one is going silent, and it's honestly the most damaging thing on this whole list. If you're thinking, then think out loud; an interviewer just can't give you partial credit for reasoning they can't actually hear, and they can't redirect you when they have no idea where you currently are.

The second is optimizing too early. Jumping straight to the clever solution and getting it slightly wrong tends to read worse than just building up methodically. I've watched candidates try to reproduce the optimal answer from memory, get exactly one boundary condition wrong, and then completely struggle to debug it, mostly because they'd memorized the answer without ever really understanding it.

The third is treating clarifying questions as optional. At this level the ambiguity genuinely is part of the test, and often the real work is just noticing that the problem is underspecified and asking the one question that pins it down.

And the last one is ignoring the interviewer's hints. When they ask something like "is there a way to avoid sorting here?", they're effectively handing you the answer, so just take it; defending your own approach while the interviewer is clearly steering you elsewhere is a real red flag about how you'd handle code review later.

How to actually prepare (without wasting three months)

I honestly don't believe in grinding 500 problems. I've never once really seen it correlate with stronger offers, and it just burns people out. A few other things tend to work a lot better than that.

Learn the patterns, not the individual problems. There are really only around 15 that matter: two pointers, sliding window, hashing, BFS/DFS, binary search, heaps, dynamic programming, and a handful of others. Once you learn to recognize which pattern a question is really asking for, you can derive the solution on the spot instead of trying to recall it from memory, and building that recognition is basically what the rest of this series is going to be about.

Do fewer problems, but actually do them properly. 40 problems you can explain line by line will take you a lot further than 200 you only half-remember. After each one, close the editor and try to re-explain the whole approach out loud; if you can't do that, then you didn't really learn it.

Practice talking while you're coding. This one is high-impact and almost always skipped. Record yourself solving a problem out loud; it feels genuinely awkward, but it exposes those long silences you fall into whenever you actually stop to think, which are exactly the thing that hurts you in a real interview.

Simulate the pressure too. Solving a problem calmly on your own is honestly a totally different skill from solving it while somebody else watches you do it. Do mock interviews, and just get used to being a little uncomfortable.

What I tell people the night before

Sleep. A rested brain that actually knows 5 patterns will easily outperform an exhausted one that crammed 20 the night before.

And try to reframe the whole situation while you're at it. You're not being interrogated here. You're pair-programming with someone who just wants to see how you actually work. The best interviews I've ever had genuinely felt like two engineers just solving a problem together, and that's the tone to aim for rather than some kind of performance.

You honestly don't need to be perfect. You need to be clear, upfront about the things you don't know, and steady when the problem gets hard. That's really what senior looks like from the other side of the table.

Next up in this series, we get quite a bit more concrete with the arrays and hashing patterns, which show up in more interviews than just about anything else.

Key takeaways

Senior interviews really test how you think and communicate, and actually reaching the optimal answer is almost secondary to that.
Run the same loop every single time: clarify, state the naive approach, find and fix the bottleneck, write it cleanly, and then test it yourself.
Talking out loud is the highest-impact skill here, and also the most neglected one.
Learn the ~15 core patterns so you can derive solutions instead of just memorizing individual problems.
Take the interviewer's hints, because how you respond to a bit of steering shows how you'd actually take code review.

FAQ

How many LeetCode problems should I solve for a senior interview?
Honestly fewer than you'd probably guess. Something like 40 to 60 that you can genuinely explain, decision by decision, will beat hundreds that you only half-remember; depth and pattern recognition matter here far more than the raw count of problems ever does.

Do senior engineers still get asked LeetCode-style questions?
Often, yes, especially at the bigger companies. But the bar itself moves; it shifts away from "did you actually solve it" and toward "how did you reason, communicate, and handle the ambiguity", so you should expect a lot more follow-ups on tradeoffs and on scale.

What's the most common reason strong engineers fail coding interviews?
They go quiet. Under pressure they just stop narrating what they're doing, and the interviewer is then left unable to credit reasoning they can't actually hear, or to steer someone who has basically gone dark on them.

Should I ask clarifying questions even if the problem seems clear?
Yes, honestly you should. Spotting the ambiguity and asking the right question is a real part of what's being graded here; it reads as experience, and it also quietly stops you from very beautifully solving the wrong problem.

How do I prepare for the "talk while coding" part?
Record yourself. Solve a few problems out loud, alone, and then do some mock interviews with a real person; it genuinely feels awkward, but it drags out that silent-thinking habit that quietly sinks so many otherwise-strong candidates.

About the Author

Hi, I'm Aman Singh — Senior Full Stack Engineer specializing in scalable SaaS products, distributed systems, cloud architecture, and AI-powered applications.

I write about System Design, Full Stack Engineering, Distributed Systems, Redis, PostgreSQL, AWS, Node.js, and NestJS.

Portfolio: https://amanksingh.com
GitHub: https://github.com/amansingh1501
Product: https://vowerole.com
Email: aman97aman@gmail.com

Setting Up NestJS the Right Way

Aman Kumar Singh — Tue, 21 Jul 2026 06:58:32 +0000

Last time we set up the Next.js frontend in apps/web. Now the other half: the NestJS API in apps/api, the service that actually owns the data those shared types describe.

Like the frontend, there's a thirty-second version of this (nest new api, done) and a version that saves you real pain later. NestJS is interesting because it hands you a lot of structure on day one, so the setup work here is mostly about restraint. You turn on the few things every production API genuinely needs, and you resist scaffolding the enterprise patterns you won't touch for months.

This is part four of the Full Stack SaaS Masterclass, continuing from the Next.js app we set up last time. The NestJS app lives in apps/api and shares types with the frontend through the same packages/types.

Modules: the one concept to get right

Everything in NestJS hangs off modules, and getting your mental model right here is most of the battle. A module groups one feature: its controller, its service, and whatever providers that feature needs. The framework wires them together with dependency injection.

The mistake I see most often is at both extremes. Some people stuff the entire app into AppModule and end up with a tangle. Others create a module per file and drown in ceremony. The rule that works: one module per real domain. A UsersModule, an AuthModule, a BillingModule, each owning its own controller and service.

// src/modules/users/users.module.ts
import { Module } from '@nestjs/common';
import { UsersController } from './users.controller';
import { UsersService } from './users.service';

@Module({
  controllers: [UsersController],
  providers: [UsersService],
  exports: [UsersService], // let other modules use it
})
export class UsersModule {}

Start with one or two feature modules and add more as real domains appear. The structure grows out of the product, not out of a diagram you drew before writing anything.

The setup that matters

Inside apps/api, here's what I configure before writing a single endpoint.

TypeScript strict. Same rule as the frontend, non-negotiable. Turn on strict in tsconfig.json from the first file. A backend that grew up loose is even worse to fix than a frontend, because the bugs hide in data handling where they hurt most.

Global validation. This is the single most important production default in the whole setup. Every request body that reaches your handlers should already be validated and typed. NestJS makes this one block of code in main.ts, paired with DTOs that declare the rules.

// src/main.ts
import { NestFactory } from '@nestjs/core';
import { ValidationPipe } from '@nestjs/common';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  app.useGlobalPipes(
    new ValidationPipe({
      whitelist: true,           // strip properties not in the DTO
      forbidNonWhitelisted: true, // reject unknown properties outright
      transform: true,            // turn plain payloads into DTO instances
    }),
  );

  await app.listen(3000);
}
bootstrap();

// src/modules/users/dto/create-user.dto.ts
import { IsEmail, IsString, MinLength } from 'class-validator';

export class CreateUserDto {
  @IsEmail()
  email: string;

  @IsString()
  @MinLength(2)
  name: string;
}

With whitelist and forbidNonWhitelisted on, a request carrying an extra isAdmin: true field it shouldn't have gets rejected before your code ever sees it. That's a security default, not just a tidiness one.

Config, loaded once. Reaching for process.env all over the codebase is how you end up shipping with an undefined secret and no idea which of forty files reads it. Use @nestjs/config to load and validate environment variables once, then inject them.

// src/app.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { UsersModule } from './modules/users/users.module';

@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true }),
    UsersModule,
  ],
})
export class AppModule {}

We'll do proper environment-variable handling, including validation and typed access, in its own article later in this module. For now, loading it in one place is the habit that matters.

Serve the shared types. This is the monorepo paying off on the backend. Your controller returns the same User type the frontend imports, so the contract between the two sides is a single definition rather than two that drift.

// src/modules/users/users.controller.ts
import { Controller, Get, Param } from '@nestjs/common';
import type { User } from '@my-saas/types';
import { UsersService } from './users.service';

@Controller('users')
export class UsersController {
  constructor(private readonly users: UsersService) {}

  @Get(':id')
  getOne(@Param('id') id: string): Promise<User> {
    return this.users.findById(id);
  }
}

If the backend changes what a User is, both this file and the frontend that consumes it stop compiling until they're updated. The mismatch becomes a build error instead of a production bug.

Path aliases. Same as the frontend. Set up @/ so imports stay readable and survive file moves.

// tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "baseUrl": ".",
    "paths": { "@/*": ["./src/*"] }
  }
}

A sane module structure

Here's the layout I use inside apps/api. It scales from three endpoints to three hundred without a reorganization.

apps/api/src/
├── modules/          # one folder per feature (users, auth, billing)
│   └── users/
│       ├── dto/
│       ├── users.controller.ts
│       ├── users.service.ts
│       └── users.module.ts
├── common/           # cross-cutting: guards, filters, interceptors
├── config/           # config schema and helpers
├── app.module.ts
└── main.ts

The common folder is where shared infrastructure lives: an exception filter that shapes error responses consistently, an auth guard, a logging interceptor. Keeping those out of feature modules stops the same boilerplate from being copy-pasted into every corner of the app.

What not to build yet

NestJS documents a lot of advanced machinery, and the temptation on day one is to wire up all of it. Resist that, the same way we resisted extra libraries on the frontend.

You don't need microservices. Start as a modular monolith and split a service out later if a boundary genuinely demands it, which for most SaaS products never happens. You don't need CQRS or event sourcing to save a user's name to a table. You don't need a queue until you have work that runs outside the request cycle, and when you do, BullMQ slots in cleanly later in the series. You don't need custom decorators everywhere; the built-in ones cover almost everything.

Every one of those patterns solves a real problem you probably don't have yet. Add them the day the problem shows up, with the context to use them well, rather than guessing now.

Next in the series, we give this API something to talk to: PostgreSQL, and how to model and connect it in a way you won't regret three migrations from now.

Key takeaways

Organize the app around one module per real domain; avoid both the god-module and the module-per-file extremes.
Turn on TypeScript strict from the first file, exactly as on the frontend.
A global ValidationPipe with whitelist and DTOs is the most important production default, and it doubles as a security control.
Load environment variables once with @nestjs/config instead of scattering process.env through the code.
Return the shared monorepo types from your controllers so the API contract can't silently drift from the frontend.

FAQ

How should I structure a NestJS project?
Group code by feature into modules, one per real domain such as users, auth, or billing, each with its own controller and service. Keep cross-cutting infrastructure like guards and exception filters in a shared common folder. Let new modules appear as new domains do.

What's the most important thing to configure in a new NestJS app?
A global ValidationPipe with whitelist: true, paired with DTOs using class-validator. It guarantees every request body is validated and stripped of unexpected fields before it reaches your handlers, which is both a correctness and a security win.

Should I use NestJS microservices from the start?
No. Begin with a modular monolith. Microservices add deployment and operational complexity you haven't earned at zero users. You can extract a service later if a clear boundary demands it.

How do I share types between NestJS and my frontend?
Put the types in a shared monorepo package and import them on both sides. When a controller returns that shared type, any change to it forces both the API and the frontend to update, so the contract stays in sync.

Why use @nestjs/config instead of process.env directly?
It loads and validates environment variables in one place and lets you inject typed config where you need it. Reading process.env throughout the codebase scatters that dependency and makes missing or misnamed variables hard to catch.

About the Author

Hi, I'm Aman Singh — Senior Full Stack Engineer specializing in scalable SaaS products, distributed systems, cloud architecture, and AI-powered applications.

I write about System Design, Full Stack Engineering, Distributed Systems, Redis, PostgreSQL, AWS, Node.js, and NestJS.

Portfolio: https://amanksingh.com
GitHub: https://github.com/amansingh1501
Product: https://vowerole.com
Email: aman97aman@gmail.com

Setting Up Your Next.js App the Right Way

Aman Kumar Singh — Tue, 21 Jul 2026 06:58:30 +0000

There's a version of "setting up Next.js" that takes thirty seconds: run create-next-app, done. And for a weekend project, that's genuinely all you need. But we're building a SaaS meant to live for years, inside a monorepo, sharing types with a backend. The choices you make in the first hour here quietly shape how the next hundred hours feel.

So this isn't a "run this command" article. It's the handful of setup decisions that actually matter, and the ones people agonize over that don't.

This is part three of the Full Stack SaaS Masterclass, continuing from the Turborepo monorepo we set up last time. The Next.js app lives in apps/web.

App Router or Pages Router?

This is the first fork, and I'll give you a straight answer: for a new project in 2023, use the App Router. The Pages Router isn't bad. It's stable, and a lot of great apps run on it. But the App Router is where React and Next are clearly heading, and starting a multi-year project on the path that's being deprioritized is borrowing trouble.

The App Router's real advantage for a SaaS is Server Components. Your dashboard can fetch data on the server, render it to HTML, and ship less JavaScript to the browser. For an app with a lot of data-heavy pages, that's faster loads and better SEO on your marketing pages, more or less for free.

There's a learning curve. Server Components versus Client Components trips everyone up at first. I'll cover that properly in the React series later. For now: it's worth the curve.

The setup that matters

Inside apps/web, here's what I actually configure before writing any features.

TypeScript, strict. Non-negotiable. Turn on strict mode in tsconfig.json from the very first file. Retrofitting strictness onto a codebase that grew up loose is miserable. I've done it: it's weeks of any whack-a-mole. Pay the small tax now.

Path aliases. Set up @/ to point at your source root so imports stay readable as the app grows.

// tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

The difference this makes six months in:

// without aliases, from a deeply nested file
import { Button } from '../../../../components/ui/Button';

// with aliases, from anywhere
import { Button } from '@/components/ui/Button';

That second version doesn't break when you move the file. The first one does, and you won't notice until runtime.

Consume the shared types. This is the monorepo paying off. Import the User type from the shared package instead of redefining it:

import type { User } from '@my-saas/types';

async function getProfile(): Promise<User> {
  const res = await fetch(`${process.env.API_URL}/me`);
  return res.json();
}

Now if the backend changes the User shape, this file won't compile until you deal with it. That's the safety net we built the monorepo for, doing its job on the frontend.

Tailwind for styling. An opinion, but a well-worn one. For a SaaS you'll build a lot of custom UI, and Tailwind lets you style without inventing a naming system or context-switching to CSS files. If you or your team genuinely prefer CSS Modules or styled-components, that's a fine choice too. This is one of those reversible decisions not worth a war over.

A sane folder structure

People burn absurd amounts of time on folder structure. Here's one that works and that you can stop thinking about:

apps/web/src/
├── app/              # App Router routes
├── components/
│   ├── ui/           # dumb, reusable primitives (Button, Input)
│   └── features/     # feature-specific components
├── lib/              # helpers, API client, utilities
├── hooks/            # custom React hooks
└── styles/           # global css, tailwind entry

The one distinction I'd insist on is ui versus features. ui holds generic primitives that know nothing about your app. A Button doesn't care whether it's on a billing page. features holds components that do: a BillingSummary that knows about invoices. Keeping those separate stops your reusable primitives from slowly getting tangled up in business logic, which is how component libraries rot.

Everything else, don't overthink. You can always move a file. You cannot always undo a strict: false codebase.

What not to install yet

The instinct on day one is to add every library you might need. Resist it. You don't yet know if you need a state management library. Server Components and React's built-in state cover more than they used to. You don't need a data-fetching library until you have data to fetch. You don't need a form library until you have a form.

Each dependency is a thing to learn, update, and occasionally get burned by. Add them when a real need shows up, not in anticipation. The create-next-app default plus TypeScript, Tailwind, and your shared types is a complete enough starting point to build real features on.

Next in the series, we set up the other side: the NestJS backend that serves those shared types, inside the same monorepo.

Key takeaways

For a new multi-year project, start on the App Router. It's where Next.js is heading, and Server Components cut shipped JavaScript.
Turn on TypeScript strict from the first file; retrofitting it later is painful.
Set up @/ path aliases so imports stay stable when you move files.
Import shared types from the monorepo package so frontend and backend can't drift.
Keep reusable ui primitives separate from features components, and don't install libraries until a real need appears.

FAQ

Should I use the App Router or Pages Router for a new Next.js app?
Use the App Router for new projects. It's the direction Next.js is investing in, and Server Components reduce client-side JavaScript and improve SEO. The Pages Router still works but is the legacy path.

Why enable TypeScript strict mode from the start?
Strict mode catches whole categories of bugs at compile time. Adding it to an existing loose codebase means fixing a flood of errors all at once, so it's far cheaper to start strict.

What folder structure should a Next.js SaaS use?
A simple one: app for routes, components/ui for generic primitives, components/features for app-specific components, plus lib, hooks, and styles. Keep reusable primitives free of business logic.

Do I need a state management library like Redux?
Not to start. React's built-in state and Server Components handle a lot now. Add a state library only when you hit genuine shared-state complexity that local state can't handle cleanly.

How do I share types between my Next.js app and backend?
Put the types in a shared monorepo package and import them on both sides. Any change to a type then forces both apps to update, preventing silent mismatches.

About the Author

Hi, I'm Aman Singh — Senior Full Stack Engineer specializing in scalable SaaS products, distributed systems, cloud architecture, and AI-powered applications.

I write about System Design, Full Stack Engineering, Distributed Systems, Redis, PostgreSQL, AWS, Node.js, and NestJS.

Portfolio: https://amanksingh.com
GitHub: https://github.com/amansingh1501
Product: https://vowerole.com
Email: aman97aman@gmail.com

DEV Community: Aman Kumar Singh

The Production Readiness Checklist

Configuration and secrets are locked down

Health, readiness, and graceful shutdown

Backups exist and, more importantly, restores are tested

Observability that answers "what broke" in minutes, not hours

A rollback path that doesn't require a hero

Security basics that are easy to defer and expensive to skip

Key takeaways

FAQ

Further reading

About the Author

A Git Workflow for Small Teams

Trunk-based, not GitFlow

Branch naming and what actually goes in a commit

Pull requests as the actual quality gate

Merge strategy: squash, and why it matters more than it sounds

Hotfixes and the one exception to the branching rule

Production pitfalls worth naming explicitly

Key takeaways

FAQ

Further reading

About the Author

A Folder Structure That Scales for Full Stack SaaS

Structure by feature, not by file type

The same idea in Next.js, with the App Router doing half the work

What earns a place in packages/, and what doesn't

Production pitfalls worth naming early

Key takeaways

FAQ

Further reading

About the Author

Managing Environment Variables and Secrets

Why config deserves its own discipline

Validate config at startup, not at first use

Local development: .env files done right

Secrets in staging and production

Common pitfalls worth naming directly

Key takeaways

FAQ

Further reading

About the Author

Setting Up Docker for Local Development

Why containerize local development at all

The docker-compose.yml for the whole stack

Dockerfiles built for iteration, not just shipping

The node_modules volume trick, and why it matters

Networking, environment variables, and the localhost trap

Production pitfalls to avoid

Key takeaways

FAQ

Further reading

About the Author

Choosing Prisma or TypeORM for Your NestJS API

Why this decision is bigger than it looks

Prisma: schema-first, with a generated client

TypeORM: entities, decorators, and the repository pattern

Tradeoffs that actually matter

Production pitfalls worth knowing before you commit

Key takeaways

FAQ

Further reading

About the Author

Setting Up PostgreSQL the Right Way

Run it in Docker, not on your laptop

Connect the API without leaking secrets

Think in schema, not in tables

Migrations from the very first table

What to defer

Key takeaways

FAQ

Further reading

About the Author

Two Pointers & Sliding Window, Explained Simply

Two pointers: walking from both ends

Sliding window: the expanding and shrinking frame

Fixed vs dynamic windows

How to know it's a window problem

The mistake almost everyone makes

Key takeaways