DEV Community: Kelechi Oliver A.

Observability from Day One: What We Got Wrong in v1 and How We Fixed It in v2

Kelechi Oliver A. — Fri, 03 Apr 2026 05:49:12 +0000

The worst kind of production incident is the one where you're staring at a broken system and you have absolutely nothing to go on. No traces, no structured logs, no metrics. Just a user saying "it's not working" and a handful of console.log statements that, somehow, didn't fire.

That was v1. And when things broke — and they did break — we were flying blind.

What We Actually Got Wrong in v1

It wasn't that we didn't care about observability. We just didn't treat it as a first-class concern. It was the kind of thing we told ourselves we'd add "later, once the core features are stable." Later never came. The system grew, the edge cases multiplied, and every debugging session became a painful exercise in guesswork.

The logs were unstructured strings. Some requests had context, most didn't. There was no way to correlate a frontend error with a specific backend request, let alone trace it through multiple services. When an error did bubble up, the message was something like "Something went wrong" — a message written in a hurry during a deadline and never revisited, or a huge pile of stack trace with no real meaning.

We had no concept of log levels applied consistently. No error codes. No request IDs are threaded through the system. The word "metrics" meant checking the AWS console manually and hoping something looked obviously wrong.

The v2 Decision: Observability Isn't a Feature, It's Infrastructure

When we started v2, we made one rule early: observability goes in before the first route handler. Not as a sprint backlog item, not as a nice-to-have after launch. Day zero.

That decision shaped everything. We picked OpenTelemetry as the foundation because it's vendor-neutral, now GA for traces and metrics (logs became stable in late 2024), and has a strong ecosystem around Node.js. We'd export everything via OTLP to a collector, and the collector would forward to CloudWatch. The pipeline looked like this:

App (OTEL SDK) → OTLP (gRPC) → ADOT Collector (sidecar) → CloudWatch

The ADOT (AWS Distro for OpenTelemetry) collector runs as a sidecar and handles the translation to CloudWatch Logs, Metrics, and X-Ray traces. It means the app doesn't need to know about AWS — it just speaks OTLP.

The Bootstrap: Why Order of Operations Matters More Than You Think

Here's the thing nobody warns you about until you've wasted a day debugging it: OpenTelemetry auto-instrumentation only works if the SDK is initialized before your application code loads. If NestJS bootstraps first, the auto-instrumentation patches never take hold. You end up with an SDK running but capturing nothing.

The fix is to use a separate instrumentation entry point and ensure it runs before the app boots. Here's what that looks like:

// instrumentation.ts — loaded via --require flag BEFORE app bootstrap
import 'dotenv/config';
import { createOtelSDK } from '@your-org/observability/sdk';

const collectorEndpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
const environment = process.env.ENVIRONMENT;

if (!environment) {
  // Fail loudly — missing env at startup is better than silent no-op observability
  throw new Error('Environment variable ENVIRONMENT is required for OTEL');
}

export const otelSDK: ReturnType<typeof createOtelSDK> = createOtelSDK({
  collectorEndpoint,
  environment,
  serviceName: 'my-service',
});

otelSDK.start();

This file gets loaded via --require ./dist/instrumentation.js in the Node startup command, before anything else runs. The SDK is live before a single NestJS module is instantiated. One thing to be explicit about: --require needs the compiled .js output, not the TypeScript source. Your package.json start script should look something like this:

"scripts": {
  "start": "node --require ./dist/instrumentation.js ./dist/main.js",
  "start:dev": "tsx --require ./src/instrumentation.ts ./src/main.ts"
}

In production you're running the compiled output. Locally, tsx (or ts-node) handles the TypeScript without a build step.

The SDK Factory: Configuring What You Actually Need

The createOtelSDK factory is where all three pillars — traces, metrics, logs — come together. It's also where you make important decisions about noise reduction.

// sdk.ts — creates and configures the NodeSDK instance
export function createOtelSDK(config: OtelConfig): NodeSDK {
  // gRPC OTLP endpoint — no scheme prefix, just host:port (4317 is the standard gRPC port)
  // If you switch to HTTP exporters, use 'http://localhost:4318/v1/traces' instead
  const collectorEndpoint = config.collectorEndpoint || 'localhost:4317';
  const attributes = makeOtelAttributes(config);

  const sdk = new NodeSDK({
    resource: new Resource(attributes),

    // Batch spans before exporting — reduces overhead vs. SimpleSpanProcessor
    spanProcessor: new BatchSpanProcessor(
      new OTLPTraceExporter({ url: collectorEndpoint }),
    ),

    metricReader: new PeriodicExportingMetricReader({
      exporter: new OTLPMetricExporter({ url: collectorEndpoint }),
    }),

    logRecordProcessors: [
      // BatchLogRecordProcessor is a direct named export from @opentelemetry/sdk-logs
      new BatchLogRecordProcessor(
        new OTLPLogExporter({ url: collectorEndpoint }),
      ),
    ],

    instrumentations: [
      getNodeAutoInstrumentations({
        // fs instrumentation generates a span for EVERY file read — absolute noise
        '@opentelemetry/instrumentation-fs': { enabled: false },
        '@opentelemetry/instrumentation-pg': { enabled: true },
        '@opentelemetry/instrumentation-http': {
          // Health checks hit every few seconds — keep them out of your traces
          ignoreIncomingRequestHook: (request) => {
            return request.url?.includes('/health') ?? false;
          },
        },
      }),
      new PinoInstrumentation({
        // logHook is required — without it, trace context is NOT injected automatically
        logHook: (_span, record) => {
          record['trace_id'] = _span?.spanContext().traceId;
          record['span_id'] = _span?.spanContext().spanId;
        },
      }),
      new ORPCInstrumentation(),   // traces our RPC layer
    ],
  });

  // Handle both SIGTERM (containers/k8s) and SIGINT (Ctrl+C in dev) — don't lose buffered spans
  const shutdown = () =>
    sdk
      .shutdown()
      .then(
        () => console.log('OTEL SDK shut down successfully'),
        (err: unknown) => console.log('Error shutting down OTEL SDK', err),
      )
      .finally(() => process.exit(0));

  process.on('SIGTERM', shutdown);
  process.on('SIGINT', shutdown);

  return sdk;
}

Two things I want to call out here. First, disabling instrumentation-fs is intentional. Enabling it will flood your traces with file system operations — every module load, every config file read. It's useless for debugging and expensive in volume. Turn it off.

Second, the PinoInstrumentation is doing something important: via the logHook, it injects trace_id and span_id into every Pino log record. Worth noting — this is not automatic out of the box. Without the explicit logHook, the instrumentation wraps Pino's methods but doesn't attach trace context to log records. The hook is what makes it useful. Once it's wired in, that's the bridge between your logs and your traces. When you see an error in CloudWatch Logs, you take the trace_id and jump directly to the corresponding trace in X-Ray. In v1, this kind of correlation didn't exist. In v2, it's a few lines of config.

Wiring Observability into NestJS Without It Becoming a Mess

We wrapped all of this into an ObservabilityModule that every service imports once. It handles Pino logging configuration and OpenTelemetry metrics in one place:

// observability.module.ts
@Module({})
export class ObservabilityModule {
  static forRootAsync(): DynamicModule {
    return {
      module: ObservabilityModule,
      imports: [
        ConfigModule,
        LoggerModule.forRootAsync({
          inject: [ConfigService],
          useFactory: (configService: ConfigService) => ({
            // Pretty-print in TTY (local dev), raw JSON in production
            ...transport,
            pinoHttp: {
              level: configService.get<string>('LOG_LEVEL', 'info'),
              useLevel: 'debug',
              stream: process.stdout,
              // Non-negotiable: never log auth headers or cookies
              redact: ['req.headers.authorization', 'req.headers.cookie'],
              ...transport,
            },
          }),
        }),
        OpenTelemetryModule.forRootAsync({
          inject: [ConfigService],
          useFactory: (configService: ConfigService) => {
            const endpoint = configService.get<string>(
              'OTEL_EXPORTER_OTLP_ENDPOINT',
            );
            if (!endpoint) {
              // Warn, don't crash — useful in local dev without a collector running
              console.warn('OTEL collector endpoint not configured...');
              return { metrics: { enabled: false } };
            }
            return { metrics: { hostMetrics: true } };
          },
        }),
      ],
      exports: [LoggerModule],
    };
  }
}

The transport variable at the top deserves mention. In a TTY environment (local dev), we use pino-pretty to get human-readable output. In production, process.stdout.isTTY is false, so we get raw JSON — which is what CloudWatch Logs Insights expects for structured querying. One module, two behaviors, no manual switching.

What "Normalized Logs" Actually Means in Practice

Structured logging sounds obvious until you've inherited a codebase where half the logs are strings and the other half are JSON objects with inconsistent field names. Normalization means you make decisions upfront and enforce them everywhere.

In v2, every log record has a consistent shape: a level field, a message, a trace_id and span_id (injected via the PinoInstrumentation logHook we configure in the SDK factory), and any additional context as typed fields — not concatenated into the message string. Errors include an error_code field as a first-class property, not buried in a message.

Log levels are treated seriously. info is for events that are expected and worth tracking. warn is for degraded states that aren't failures yet. error is for things that need attention — and they include stack traces. debug is off in production by default, toggled via LOG_LEVEL env var when you need to investigate something specific.

Redacting req.headers.authorization and req.headers.cookie isn't optional. These are the fields most likely to appear in HTTP request logs, and logging them — even accidentally — is a security incident waiting to happen. Pino's redact config handles it before the log record ever leaves the process.

The Real Takeaway

The observability debt we carried in v1 cost us far more than if we'd built it in from the start. Not just in debugging time — in confidence. When you don't have traces, you don't fully understand your own system. You have theories, not facts.

OpenTelemetry, Pino, and a collector sidecar aren't a heavy stack. The setup I've described here is maybe a day of work for a new project. The cost of not doing it is paid every time something breaks in production and you're staring at CloudWatch with nothing useful to show for it.

Build it in on day zero. Not day thirty. Not after launch. Day zero.

The Architecture That Lets Us Sleep: Scalable Uploads with S3 presigned URLs

Kelechi Oliver A. — Sat, 04 Oct 2025 19:53:49 +0000

I've tackled the complexities of file management across numerous projects, and one truth always holds: large file uploads pose a significant threat to backend stability and available bandwidth. The traditional method of funnelling huge files through your application server is a recipe for bottlenecks. Fortunately, we don't have to settle for that complexity. By integrating Amazon S3, we can utilize features like pre-signed URLs and Multipart Uploads to offload the entire data transfer process. This crucial step not only simplifies our architecture but ensures the upload remains scalable and efficient without overloading our own infrastructure.

In this article, we will build a Next.js video gallery app optimized for handling large file uploads. To ensure maximum performance and keep the interface snappy, we'll implement file chunking and execute the entire upload process off the main UI thread. This approach eliminates blocking, resulting in a significantly faster and more reliable user experience.

A complete project can be found on Github

Prerequisites

Before diving in, ensure you have the following:

AWS Account with permissions to use S3
Node.js (v18+) installed locally

An AWS S3 Pre-Signed URL is a special, time-limited link created by your backend that provides temporary access to a private S3 object. It allows an unauthorized user to securely upload or download a file directly to S3 without needing any AWS credentials or exposing your sensitive access keys. For detailed documentation, see Download and upload objects with presigned URLs - Amazon Simple Storage Service.

So with the foundational concepts established, we're done with definitions and ready to build. Let's immediately pivot to development and construct a practical application. This project will serve as a clear, working illustration of our key takeaway: how combining S3 Pre-Signed URLs with Multipart Uploads radically improves both the efficiency and the user experience of handling large file uploads

This is what we would be building. The complete code can be found on Github.

Initialise a Next.js project

npx create-next-app@latest mini-video-gallery --typescript --tailwind --eslint --app --src-dir --import-alias "@/*"
cd mini-video-gallery

Next, let’s install the required dependencies

# AWS SDK for S3 operations
npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner

# shadcn/ui setup
npx shadcn@latest init
npx shadcn@latest add button progress card separator

Since we’re working with AWS, we need to set up env’s for secret keys to authenticate requests

Create a new file .env.local, copy and paste this inside

AWS_ACCESS_KEY_ID=your_aws_access_key_id
AWS_SECRET_ACCESS_KEY=your_aws_secret_access_key
AWS_REGION=us-east-1
AWS_S3_BUCKET_NAME=your_s3_bucket_name

Get an access key from the AWS IAM console, read more on how to generate access keys here. Also, ensure you have an existing S3 bucket or create a new S3 bucket.

Replace the follow with their relevant values your_aws_access_key_id, your_aws_secret_access_key and your_s3_bucket_name

Next, we need to configure Next.js to support web workers

Update next.config.ts

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  experimental: {
    webpackBuildWorker: true,
  },
};

export default nextConfig;

Now let’s set up our API routes to handle generating pre-signed URLs.

Note: Codes within the following sections are snippets; check the relevant files on GitHub for the complete code.

src/app/api/presigned-url/route.ts This route handles generating presigned URLs for simple uploads (<20mb)

import { NextRequest, NextResponse } from 'next/server';
import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';

const s3Client = new S3Client({
  region: process.env.AWS_REGION,
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  },
});

export async function POST(request: NextRequest) {
  const { fileName, fileType, fileSize } = await request.json();

  const timestamp = Date.now();
  const uniqueFileName = `${timestamp}-${fileName}`;

  const command = new PutObjectCommand({
    Bucket: process.env.AWS_S3_BUCKET_NAME,
    Key: uniqueFileName,
    ContentType: fileType,
  });

  const presignedUrl = await getSignedUrl(s3Client, command, {
    expiresIn: 3600,
  });

  return NextResponse.json({
    presignedUrl,
    fileName: uniqueFileName,
    fileSize,
  });
}

src/app/api/multipart-upload/route.ts This route handles multipart upload for large files (>20mb). Get the complete code from the project repository on GitHub

import { NextRequest, NextResponse } from 'next/server';
import { 
  S3Client, 
  CreateMultipartUploadCommand,
  UploadPartCommand,
  CompleteMultipartUploadCommand,
} from '@aws-sdk/client-s3';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';

// S3 client configuration...

export async function POST(request: NextRequest) {
  const { action, fileName, fileType, uploadId, partNumber, parts } = await request.json();

  switch (action) {
    case 'initiate':
      return await initiateMultipartUpload(fileName, fileType);
    case 'getUploadUrl':
      return await getUploadPartUrl(fileName, uploadId, partNumber);
    case 'complete':
      return await completeMultipartUpload(fileName, uploadId, parts);
    // ... other cases
  }
}

src/app/api/files/route.ts This route fetches uploaded videos from S3

import { S3Client, ListObjectsV2Command, GetObjectCommand } from '@aws-sdk/client-s3';

export async function GET() {
  const command = new ListObjectsV2Command({
    Bucket: process.env.AWS_S3_BUCKET_NAME!,
    MaxKeys: 100,
  });

  const response = await s3Client.send(command);

  // Filter for video files and generate signed URLs
  const videoExtensions = ['.mp4', '.mov', '.avi', '.mkv', '.webm', '.m4v'];
  // ... processing logic
}

Now, let’s create a web worker to handle file upload in the background

src/workers/multipart-upload.worker.ts This worker would handle large file uploads in the background

interface MultipartUploadData {
  fileName: string;
  fileType: string;
  file: File;
  chunkSize: number;
}

self.onmessage = async function(e) {
  const { type, data } = e.data;

  if (type === 'START_MULTIPART_UPLOAD') {
    await handleMultipartUpload(data);
  }
};

async function handleMultipartUpload(data: MultipartUploadData) {
  // 1. Initiate a multipart upload
  // 2. Split the file into chunks
  // 3. Upload each part with progress tracking
  // 4. Complete multipart upload
}

This web worker would run outside the main UI thread, handle file chunking, while providing real-time progress updates as well as handling errors and retries.

Next, let's add UI components

src/components/FileUpload.tsx This component presents an interface to select files, drag and drop to trigger the upload event

export default function FileUpload({ onUploadComplete }: FileUploadProps) {
  const [selectedFile, setSelectedFile] = useState<File | null>(null);
  const [uploading, setUploading] = useState(false);
  const [uploadProgress, setUploadProgress] = useState<UploadProgress>({});

  const MAX_FILE_SIZE_FOR_SIMPLE_UPLOAD = 20 * 1024 * 1024; // 20MB

  const uploadFile = async () => {
    if (selectedFile.size <= MAX_FILE_SIZE_FOR_SIMPLE_UPLOAD) {
      await handleSimpleUpload(selectedFile);
    } else {
      await handleMultipartUpload(selectedFile);
    }
  };

  // Drag & drop interface with progress bar
  return (
    <Card className="w-full max-w-2xl mx-auto">
      <CardHeader>
        <CardTitle className="flex items-center gap-2">
          <Upload className="h-5 w-5" />
          Upload Video
        </CardTitle>
      </CardHeader>
      ...
   )
}

Let’s also add a component to display the uploaded videos

src/components/VideoGallery.tsx This would call the list files endpoint to fetch files uploaded to S3.

export default function VideoGallery({ refreshTrigger }: VideoGalleryProps) {
  const [videos, setVideos] = useState<VideoFile[]>([]);
  const [selectedVideo, setSelectedVideo] = useState<VideoFile | null>(null);

  // Fetch videos from API
  // Display in grid layout
  // Video player for selected video
  // Download functionality
}

Next, we need to include a layout component.

src/app/page.tsx Our layout component has the file upload component at the top and the video gallery component at the bottom

export default function Home() {
  const [refreshTrigger, setRefreshTrigger] = useState(0);

  const handleUploadComplete = () => {
    setRefreshTrigger(prev => prev + 1);
  };

  return (
    <div className="min-h-screen bg-gray-50">
      <div className="container mx-auto px-4 py-8">
        <FileUpload onUploadComplete={handleUploadComplete} />
        <VideoGallery refreshTrigger={refreshTrigger} />
      </div>
    </div>
  );
}

Finally, this is what the complete project structure should look like. Note: additional files can be copied from the GitHub repository.

├── src/
│   ├── app/
│   │   ├── api/
│   │   │   ├── presigned-url/route.ts
│   │   │   ├── multipart-upload/route.ts
│   │   │   └── files/route.ts
│   │   └── page.tsx
│   ├── components/
│   │   ├── FileUpload.tsx
│   │   ├── VideoGallery.tsx
│   │   └── ui/ (shadcn components)
│   └── workers/
│       └── multipart-upload.worker.ts
├── .env.local
└── next.config.ts

CORS Configuration

Uploading files to S3 from the browser can result in CORS issues; we need to configure S3 to allow upload requests from our web app running locally.

Follow these steps to configure CORS from the AWS console:

Go to S3 Console
Select your Bucket, then click Permissions
Scroll to "Cross-origin resource sharing (CORS)”
Edit and paste the configuration below

[
    {
        "AllowedHeaders": ["*"],
        "AllowedMethods": ["GET", "PUT", "POST", "DELETE", "HEAD"],
        "AllowedOrigins": ["http://localhost:3000", "https://yourdomain.com"],
        "ExposeHeaders": ["ETag", "x-amz-version-id"],
        "MaxAgeSeconds": 3000
    }
]

Running app

With that done, we can run the app using npm run dev. Test the app by uploading sample videos, and also check your Chrome Dev Tools for network requests.

Conclusion

Congratulations! We've reached the finish line! By leveraging S3 Pre-Signed URLs and Multipart Uploads, we've built a file gallery app that is not just functional, but genuinely robust. We successfully offloaded heavy file processing to a separate thread on the client side, keeping our main UI buttery smooth. Best of all, because the heavy lifting now relies on the massive, resilient power of AWS S3 instead of our own backend bandwidth, we can all sleep a little sounder tonight, knowing our application is scaled and ready for whatever our users throw at it.

As with everything in software engineering, we can extend this approach further with parallel uploads, retry logic, and progressive streaming for even more robustness.

Thanks for getting to this point. Happy coding, bye for now.

References
Cover Photo by Thomas William on Unsplash

Simplifying API Communication with the BFF Pattern in NextJS

Kelechi Oliver A. — Mon, 22 Sep 2025 10:20:07 +0000

In one of my recent projects, the frontend had to juggle 5 different APIs, each having a different response schema. This issue of multiple backends has now become a common struggle as modern web applications often rely on multiple APIs, microservices, and third-party integrations. While this architecture is powerful, it can introduce complexity for the frontend, such as handling multiple data sources, managing authentication, and dealing with inconsistent response formats.

This is where the Backend-for-Frontend (BFF) pattern comes in. Instead of letting the frontend talk to all APIs directly, you place a thin backend layer between them. With Next.js, this pattern fits naturally, thanks to its API routes and server-side rendering (SSR) capabilities. If you’ve ever struggled with messy API responses or token handling on the client, you’ve already felt the need for a BFF layer.

In this article, we’ll explore what the BFF pattern is, why it matters, and how you can implement it effectively using Next.js.

What is the Backend-for-Frontend (BFF) Pattern?

The Backend-for-Frontend (BFF) pattern is an architectural approach where a dedicated backend layer is created specifically for a frontend application (e.g., web, mobile, or desktop).

Instead of having the frontend communicate directly with multiple microservices, APIs, or databases, the BFF acts as an adapter that:

Orchestrates data from multiple sources.
Shapes the responses to suit frontend requirements.
Manages authentication and authorization.

In short, the BFF provides a single, tailored API surface that makes frontend development faster and simpler.

What are the benefits of this pattern?

Simplified frontend logic: Since the BFF layer acts like a proxy, the UI only needs to interact with one API.
Optimized payloads: Only the necessary data is returned.
Improved security: Tokens and credentials are handled on the server, not the client.
Flexibility: Each frontend (web, mobile, IoT) can have its own tailored BFF.
Consistency: The BFF ensures a unified response format across diverse backend services.

Enough of the theory, I believe we now have some understanding of what the BFF pattern is and what benefits it provides. Next, let’s look through some code samples to see how we can implement this pattern using Nextjs.

Implementing the BFF Pattern with Next.js and NestJS

Architecture

Frontend (Next): Renders UI and interacts only with the BFF layer.
BFF Layer Next API Routes: Acts as a proxy between the frontend and backend.
Backend Nest: Provides domain logic, connects to databases, and exposes microservices.

For the backend, we can have different services running as multiple instances of Nest application, each backend service handles different business domains such as auth, inventory, notification, etc.

Sample NestJS controller

// auth.controller.ts
import { Controller, Get, Param } from '@nestjs/common';
import { AuthService } from './auth.service';

@Controller('auth')
export class AuthController {
  constructor(private readonly authService: authService) {}

  @Get('user/:id')
  async findUserById(@Param('id') id: string) {
    return this.authService.findUserById(id);
  }
}

A service would be:

import { Injectable } from '@nestjs/common';

@Injectable()
export class AuthService {
  async findUserById(id: string) {
    // Mocked DB call
    return { id, name: 'Alice', email: 'alice@example.com' };
  }
}

Backend runs at http://localhost:4000/auth/user/:id.

Frontend

Next.js BFF API Route

// api/profile.ts

import type { NextApiRequest, NextApiResponse } from 'next';

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  const { id } = req.query;

  const response = await fetch(`http://localhost:4000/auth/users/${id}`);
  const user = await response.json();

  // Define a response structure independent of the backend.
    // You can also provide client-side fallbacks or mock responses based on contracts.
    // This allows you to implement client-specific logic and maintain flexibility.

  // Shape response for the frontend  
  res.status(200).json({
    id: user.id,
    displayName: user.name,
    contact: user.email
  });
}

Call BFF inside a component

// pages/dashboard.tsx

import { useEffect, useState } from 'react';

export default function Dashboard() {
  const [profile, setProfile] = useState<any>(null);

  useEffect(() => {
    async function loadProfile() {
      const res = await fetch('/api/profile?id=123'); // single API 
      const data = await res.json();
      setProfile(data);
    }
    loadProfile();
  }, []);

  if (!profile) return <p>Loading...</p>;

  return (
    <div>
      <h1>Welcome, {profile.displayName}</h1>
      <p>Email: {profile.contact}</p>
    </div>
  );
}

Frontend is now no longer coupled with backend, we have the ability to enhance the BFF layer as well as connect to different backend source in order to fulfil any frontend UI requirements.

The real win here is that your frontend team stays focused on UI, while the BFF quietly handles API messiness, security, and data shaping in the background.

Key Takeaways

Reduces Coupling Between Frontend and Backend
- The frontend only talks to the BFF, not to multiple microservices directly.
- If backend APIs change, only the BFF layer is updated — the frontend remains untouched.
- This reduces the risk of frontend breakage and makes backend evolution safer.
Manages Frontend Complexity
- Instead of each component juggling multiple API calls, the BFF aggregates responses into a single, tailored endpoint.
- Frontend developers can focus purely on UI/UX logic without worrying about data orchestration, token handling, or payload shaping.
- Results in cleaner, more maintainable React/Next.js codebases.
Adds Flexibility Across Platforms
- Each frontend (web, mobile, IoT) can have its own BFF, optimized for its unique needs.
- A mobile app might get lightweight, compressed data while the web app receives richer, more detailed payloads — all from separate BFFs pointing to the same backend.
- The backend services remain consistent, while the BFF adapts to each frontend’s context.
Enables Better Security and Governance
- API keys, tokens, and sensitive logic stay in the BFF layer, never exposed to the client.
- Centralized place for applying rate-limiting, logging, and caching policies.

Some use cases of the BFF Pattern

E-commerce app: Imagine a product page that needs to pull in details, reviews, recommendations, and pricing. Without a BFF, your frontend would make four different API calls and stitch everything together. With a BFF, you ask one endpoint, and it delivers exactly what the UI needs in one go.
SaaS dashboards: Dashboards are notorious for pulling data from everywhere, analytics, billing, user profiles, notifications. A BFF acts like the middle manager that gathers all the information, so your frontend doesn’t have to chase after five different services every time a page loads.
Multi-channel apps (web + mobile): A web app might want the full dataset, while the mobile version only needs a trimmed-down payload for performance. With separate BFFs, you can shape responses differently for each client without touching the backend services.
Microservices environments: If your system is split into many microservices like in my case, exposing them all directly to the frontend can get messy fast. A BFF hides that sprawl and presents a single, clean API to the UI.
Third-party integrations: Ever had to deal with APIs like Stripe, Twilio, or Salesforce? They all come with different formats and authentication quirks. A BFF can normalize these responses and handle token management behind the scenes, so your frontend team doesn’t need to worry about it.

Conclusion

The Backend-for-Frontend (BFF) pattern provides a practical way to reduce complexity, improve security, and decouple frontend teams from backend changes. By introducing a thin adapter layer, the frontend gets exactly the data it needs in the right format, while backend services remain clean and independent.

As seen above, Next.js handles UI rendering and API orchestration, while NestJS focuses on core business logic and scalability, together striking a balance between developer productivity and system robustness.

If we were to push this setup further, we can consider doing

Contract-First API Development with ts-rest
- Ensures both frontend and backend share a strongly-typed contract.
- Prevents mismatched API payloads and improves developer experience.
- Example: Define your API in ts-rest once and generate client + server types.
Authentication & Authorization with Cognito or Auth0
- Offload user management, login flows, and token handling to battle-tested identity providers.
- The BFF validates and refreshes tokens securely on behalf of the frontend.
- Keeps sensitive credentials away from the client.
Caching & Performance Enhancements
- Add caching (e.g., Redis, edge caching with Vercel) to reduce API round-trips.
- Improves frontend performance and backend scalability.
Observability and Logging
- The BFF is a perfect place to centralize logging, monitoring, and error reporting for frontend requests.

Deploying a React Application to AWS Cloudfront

Kelechi Oliver A. — Thu, 10 Mar 2022 02:56:55 +0000

Ever wondered how to deploy your single page React application to AWS Cloudfront service?. In this article I would be showing you how to deploy a sample React application to AWS Cloudfront

We would be deploying

Manually using AWS cloud console
Automated using Github Action

Components

AWS Cloudfront: This is a content delivery network (CDN) provided by Amazon. Users access content through AWS nearest edge location. It can be used for delivering fast and secure websites, accelerate dynamic content delivery and api’s, stream live and on demand video.

AWS S3: This is a cost effective, highly performant object storage service provided by Amazon. It allows you to store objects such as documents, video, images, blobs, etc. It can be used for backups, cold storage, file storage, archiving, web frontend host, etc.

Github Action: Github Action is an automation tool for automating developers workflows, just like CircleCI, Jenkins, it can be used to create CI/CD pipelines.

Deployment
As shown on the diagram below, we would be uploading our static assets (html,js,css) to S3 and then creating a Cloudfront distribution to use the uploaded asset. On subsequent deployments we would invalidate the existing distribution to enable Cloudfront fetch new content from S3.

Manual Deployment
In order to manually deploy to Cloudfront ensure you have the following

An AWS account with access to create S3 buckets and Objects as well as create Cloudfront distribution. Your normal AWS account would do, if you’re an IAM user ensure you have those permissions
A sample React application, you can clone one here

First, let's get our static assets ready. Depending on your package manager (npm or yarn) run npm install to install dependencies and npm run build to build project, doing this would populate our build folder with the built assets (html,css,js etc)

Next, Open your browser and login to your AWS account, search and select S3 from services, create a new bucket with the following fields

Bucket name: Enter a globally unique name
Leave the other fields default, and click “create bucket”.

Click to Select the newly created bucket, click upload and upload all files in the build folder.

Next, create a Cloudfront distribution, search and select Cloudfront from services, click “create distribution”, on the creation form, do the following

Origin domain: select your new s3 bucket name
S3 bucket access: select “Yes use OAI (bucket can restrict access to only CloudFront)”
Origin access identity: click “Create new OAI”
Bucket policy: select “Yes, update the bucket policy”
Click “Create distribution”

This would create a new distribution and update your S3 bucket policy, allowing Cloudfront to get objects.

Next, lets update the distribution error pages, Click on your newly created distribution and at the top tab menu click “Error pages”, then click “Create custom error response”, fill in the following

HTTP error code: select “443: Forbidden”
Error caching minimum TTL: enter 30
Customize error response: select “Yes”
Response page path: enter “/index.html” without the quotes
HTTP Response code: select “200:OK”

Finally, click “Create custom error response”.
Repeat these steps with HTTP error code “404”

Finally, let's check our application. With the distribution selected, click on the “General” tab, under details, click on the square like icon to copy the distribution domain name, paste this on a new browser tab to test application deployment.

Note: ensure you’re not seeing a “Deploying” status under Last Modified, if so wait till it’s complete.

After all these is done, when next you update your application code, and needs to redeploy, just build and re-upload your new assets to the same bucket created earlier, this would overwrite the existing files, then move over to your cloudfront distribution, selected distribution and click on the “Invalidations” tab, click “Create invalidation”, under “Add object paths” enter /*, finally click “Create invalidation”. This would invalidate the cached assets on Cloudfront while updating the distribution with the newly uploaded assets on S3.

Automating Deployment with Github Action
Here we would be automating the manual steps above using Github Action, to follow along ensure you have the following

AWS CLI user, this can be done by going to IAM service on AWS console, and creating a new user with programmatic access and Administrative permission, copy the account secret id and secret key, we would be needing it
Github repository with sample react application

With our S3 bucket and Cloudfront distribution created, we would be using Github Action to automate building and deployment of our frontend application whenever a push is made to the repository’s master branch.

First, on S3 we’ll need to enable Access Control List (ACL) to allow our CLI user with programmatic access to push objects to an S3 bucket created by another user. Open your bucket, click on the permissions tab, scroll down to Object Ownership, click edit, select “ACLs enabled”, select “Object writer” and click “Save changes”, scroll down to “Access control list (ACL)” while on permissions tab check that your CLI user canonical id is on the ACL, if it isn’t add it by clicking edit, click add “grantee”, paste in your CLI user canonical id and select “list”, “write” access then click “Save changes”.
Note: you can run the following command on your terminal to check your CLI user canonical id aws s3api list-buckets --query Owner.ID --output text, ensure you have AWS CLI with credentials setup on your terminal before doing this

Next, push your sample application code to Github, login to Github and select the repository, click on the settings tab

Let’s add secrets that’ll be used in Github action, on the sidebar menu, click “Secrets”, then click “Actions”, click “New repository secret” to add a repository secret that would be used by Github Action.

Next, enter the name of the key AWS_ACCESS_KEY_ID, and for value, paste in the value of your programmatic AWS user access key id, click “Add secret”. Repeat this step for AWS_SECRET_ACCESS_KEY and “AWS_DEFAULT_REGION”, for AWS_DEFAULT_REGION you can type in any region of choice such as us-east-1.
Here you can also add any environment variable used by your application

Next, create an action workflow file for our project, still on the repository, click “Actions”, click “set up a workflow yourself” and paste in the script below.

name: Frontend Cloudfront Deployment

on:
  push:
    branches:
      - master

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [12.x]
    steps:
    - uses: actions/checkout@v2

    - name: Use Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v1
      with:
        node-version: ${{ matrix.node-version }}

    - name: Yarn Install
      run: yarn install

    - name: Yarn Build
      run: yarn build
      env:
        REACT_APP_API_URL: ${{ secrets.REACT_APP_API_URL }}

    - name: Share artifact inside workflow
      uses: actions/upload-artifact@v1
      with:
        name: build-artifact
        path: build

  deploy:
    runs-on: ubuntu-latest
    needs: build
    steps:
      # get build artifact
      - name: Get artifact
        uses: actions/download-artifact@v1
        with:
          name: build-artifact

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v1
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: ${{ secrets.AWS_DEFAULT_REGION }}

      # Copy build to s3
      - name: Deploy to S3
        run: |
          S3_BUCKET=s3://<s3-bucket-name>
          aws s3 sync . $S3_BUCKET --acl private
        working-directory: build-artifact

      - name: Create Cloudfront Invalidation
        run: |
          DISTRIBUTION_ID=<distribution-id>
          aws cloudfront create-invalidation --distribution-id $DISTRIBUTION_ID --paths /*
        working-directory: build-artifact

Replace <s3-bucket-name> and <distribution-id> with your bucket name and distribution id respectively. From the script you can find references to our secrets created earlier.
Click “Start commit”, add a commit message and commit directly to master.

Finally, click on “Actions” to see your newly created workflow running, once this is completed, open your Cloudfront url to see the updated application.

I’m glad we made it this far 👏, we’ve covered a lot. For a more detailed explanation please check the video here. I made a video to properly explain the steps, so if you’re having issues just watch the video.

Perhaps you find this helpful, please leave a LIKE, Cheers!