DEV Community: AddWeb Solution Pvt Ltd

API Contract-Driven Development (Build Reliable Systems Without Guesswork)

Ankit Parmar — Wed, 27 May 2026 10:23:48 +0000

“A big part of the essence of building a program is in fact the debugging of the specification.” - Fred Brooks

Modern applications often fail not because of bad code-but because of misaligned expectations between frontend and backend. APIs change, fields break, and teams waste time debugging integration issues.

API Contract-Driven Development fixes this at the root.

Instead of building first and integrating later, teams define the API contract upfront, align on it, and then implement against that contract independently.

In this article, we’ll explore how Contract-Driven Development works, why it matters, and how it enables scalable, predictable systems.

Why API Contracts Matter

Without a defined contract, teams face:

Breaking API changes
Miscommunication between frontend and backend
Delayed integrations
Fragile deployments

Contracts solve this by:

Defining clear expectations upfront
Acting as a single source of truth
Enabling parallel development
Preventing unexpected breaking changes

What Is Contract-Driven Development?

Contract-Driven Development (CDD) is an approach where:

API structure is defined before implementation
Both frontend and backend agree on the contract
Development happens independently but consistently

A contract includes:

Endpoints
Request/response structure
Data types
Error formats

Core Philosophy

“The interface is the system.” - Alan Kay

The contract defines how systems interact-everything else is implementation detail.

Key Takeaways

API contracts eliminate ambiguity between teams
Enable parallel frontend and backend development
Reduce integration bugs and rework
Improve system reliability and predictability
Work best with tools like OpenAPI and schema validation
Essential for scaling teams and microservices
Promote clear ownership and accountability

Index

Introduction
What Is an API Contract?
Contract-First vs Code-First
How Contract-Driven Development Works
Architecture Overview
Defining API Contracts (Conceptual)
Development Workflow
Validation and Testing
Versioning and Evolution
Tooling and Ecosystem
Why This Approach Makes Sense
Watch Out For
Next Steps You Can Take
Interesting Facts
FAQ
Conclusion

1. Introduction

As systems grow, frontend and backend teams often move independently. Without a shared agreement, APIs become a moving target-leading to broken integrations and wasted time.

Contract-Driven Development introduces structure. By defining the API upfront, teams align early and build with confidence.

2. What Is an API Contract?

An API contract is a formal agreement that defines how two systems communicate.
It specifies:

Endpoint paths
HTTP methods
Request payloads
Response formats
Status codes
Error structures

Think of it as a blueprint for communication.

“The most damaging phrase in the language is: ‘It’s always been done this way.’” - Grace Hopper

3. Contract-First vs Code-First

Contract-First (Recommended)

Define API using schema (OpenAPI, JSON Schema)
Generate mocks and clients
Implement backend afterward

Code-First

Build backend first
Document later

Problem:

Documentation often becomes outdated
Frontend depends on unstable APIs

4. How Contract-Driven Development Works

High-level flow:

Define API contract
Share with teams
Generate mocks
Frontend builds against mock API
Backend implements contract
Validate both sides

Result:

No surprises during integration

5. Architecture Overview

Frontend (React / Mobile)
↓
API Contract (OpenAPI)
↓
Backend Implementation
↓
Validation Layer
Key idea:
The contract sits in the middle as the source of truth.

“Controlling complexity is the essence of computer programming.” - Brian Kernighan

6. Defining API Contracts (Conceptual)

A contract is typically written using:

OpenAPI (Swagger)
JSON Schema
GraphQL schema

Example (simplified):

paths:
/users:
get:
responses:
200:
description: List users
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string

This defines:

Structure
Types
Expected response

7. Development Workflow

Step 1: Define contract
Step 2: Review with team
Step 3: Generate mock server
Step 4: Frontend development
Step 5: Backend implementation
Step 6: Contract validation

Parallel development becomes possible.

8. Validation and Testing

Contracts are enforced using:

Schema validation
Contract testing

Two key approaches:

Consumer-Driven Contracts

Frontend defines expectations

Provider Validation

Backend ensures it matches contract

Tools:

Pact
Postman

9. Versioning and Evolution

APIs evolve. Contracts help manage change safely.
Best practices:

Use versioning (/v1, /v2)
Avoid breaking changes
Deprecate gradually
Maintain backward compatibility

“Simplicity is prerequisite for reliability.” - Edsger W. Dijkstra

10. Tooling and Ecosystem

Popular tools include:

OpenAPI Specification
Swagger
Stoplight
Insomnia

These tools help:

Design APIs
Generate docs
Create mocks
Validate contracts

11. Why This Approach Makes Sense

Eliminates ambiguity
Reduces integration issues
Enables parallel development
Improves developer productivity
Scales across teams and services

12. Watch Out For

Over-engineering simple APIs
Poorly defined contracts
Lack of versioning strategy
Ignoring backward compatibility

13. Next Steps You Can Take

Introduce OpenAPI in your project
Add contract validation in CI/CD
Generate mock APIs for frontend
Adopt contract testing tools
Document APIs properly

14. Interesting Facts

Contract-first development is widely used in microservices architectures. https://microservices.io/patterns/apigateway.html
API contracts act as a single source of truth across teams. https://stoplight.io/api-design-guide
Contract testing significantly reduces integration failures in production.https://martinfowler.com/articles/consumerDrivenContracts.html

15. FAQ

1. Is contract-driven development only for large systems?
No, it’s useful even for small teams to avoid confusion.

2. Is this the same as API documentation?
No. Documentation is derived from the contract, not the source.

3. Can I use this with GraphQL?
Yes. GraphQL schema acts as a contract.

4. Does this slow down development?
Initially slightly-but saves massive time later.

5. Is it required for microservices?
Highly recommended.

16. Conclusion

API Contract-Driven Development brings clarity to one of the most fragile parts of modern systems-communication between services.

By defining expectations upfront, you get:

Predictable integrations
Faster development
Fewer bugs
Better scalability

If your team struggles with broken APIs, miscommunication, or slow integration cycles, adopting a contract-first approach is a practical, high-impact improvement.

About the Author:Ankit is a full-stack developer at AddWebSolution and AI enthusiast who crafts intelligent web solutions with PHP, Laravel, and modern frontend tools.

Designing Permission Systems Beyond RBAC (ABAC)

Mayank Goyal — Tue, 26 May 2026 08:04:47 +0000

“Simple permissions work for small systems. Context-aware permissions power enterprise systems.”

Key Takeaways

RBAC breaks down at scale
ABAC enables dynamic, context-aware authorization
Permissions should depend on attributes, not only roles
Centralized policy engines improve maintainability
Fine-grained authorization is essential for modern SaaS
Performance and caching are critical in permission systems

Introduction

Most applications start with simple role-based permissions:

Admin - Full access
Editor - Edit content
Viewer - Read-only access

This works initially.

But as systems grow, requirements become more complex:
Managers can edit only their department’s data
Support agents can access tickets only during work hours
Users can download reports only from trusted devices
Contractors lose access after project expiration Traditional RBAC (Role-Based Access Control) struggles to handle these dynamic conditions cleanly. This is where ABAC (Attribute-Based Access Control) becomes essential.

Instead of asking:

“What role does this user have?”

ABAC asks:

“Should this specific user perform this action on this resource under these conditions?”

That difference changes everything.

Index

Introduction
Why Traditional RBAC Fails at Scale
Core Concepts of ABAC
RBAC vs ABAC (Deep Comparison)
Core Principles of Modern Permission Architecture
Designing a Scalable Authorization System
Policy Engine Architecture
Attribute Modeling Strategy
Multi-Tenant Permission Design
Real-Time Authorization Challenges
Caching & Performance Optimization
Frontend Authorization Patterns
Backend Enforcement Strategy
Audit Logging & Compliance
Testing Authorization Systems
Real-World Example (Enterprise SaaS)
Interesting Facts
Stats
FAQ’s
Conclusion

Why Traditional RBAC Fails at Scale

RBAC becomes difficult in enterprise systems because permissions explode over time.
Example:

Admin
RegionalAdmin
RegionalManager
RegionalManagerReadOnly
FinanceManager
FinanceManagerEU
FinanceManagerUS
SupportLevel1
SupportLevel2

Soon you face:

Role explosion & Duplicate permissions
Hardcoded business logic
Complex exception handling
Difficult audits

“Every special-case role is usually a hidden architecture problem.”

Core Concepts of ABAC

ABAC evaluates permissions using attributes.

1. User Attributes
Examples:

department = finance
region = EU
employmentType = contractor
clearanceLevel = 3

2. Resource Attributes
Examples:

document.ownerId
document.region
document.classification

3. Action Attributes
Examples:

read
write
delete
approve
export

4. Environment Attributes
Examples:

currentTime
IP address
device type
geo location

RBAC vs ABAC (Deep Comparison)

Core Principles of Modern Permission Architecture

1. Centralized Authorization
Never scatter permission checks everywhere.

Bad
if (user.role === 'admin') {}

Better
authorizationService.can(user, 'delete', project)

2. Policy-Based Design
Permissions should be defined as policies.

Example:
Managers can edit invoices in their own department.

NOT:
if role === manager && department === ...

3. Least Privilege Principle
Users should receive the minimum access necessary.

This minimizes:

Security risks
Data leaks
Insider threats

4. Deny by Default
If no rule explicitly allows access:

ACCESS = DENIED

Always.

Designing a Scalable Authorization System

Recommended High-Level Architecture

  Client
   ↓
  API Gateway
   ↓
   Authorization Layer
   ↓
   Policy Engine
   ↓
   Attribute Store

Folder Structure Example

src/
│
├── auth/
│   ├── policies/
│   ├── guards/
│   ├── attributes/
│   ├── services/
│   ├── engines/
│   └── audit/
│
├── features/
│   ├── billing/
│   ├── analytics/
│   └── users/
│
├── shared/
└── core/

“Authorization logic is infrastructure, not UI logic.”

Policy Engine Architecture

A policy engine evaluates authorization decisions.

Example Flow

User requests action
↓
Load user attributes
↓
Load resource attributes
↓
Evaluate policies
↓
Return allow/deny

Example Policy

export const invoicePolicy = {
 action: 'edit',
 resource: 'invoice',
 evaluate: ({ user, resource }) => {
   return (
     user.department === resource.department &&
     user.clearanceLevel >= 2
   );
 }
};

Attribute Modeling Strategy

Poor attribute design creates long-term problems.

Good Attribute Categories

Avoid
Storing derived permissions directly

Bad:
canEditInvoices = true

Better:
department = finance
role = manager

Multi-Tenant Permission Design
Enterprise SaaS applications require tenant isolation.

Example
Tenant A users must NEVER access Tenant B data.

Every authorization check should include:

resource.tenantId === user.tenantId

Missing this is one of the most dangerous SaaS security bugs.

Real-Time Authorization Challenges
Permissions can change instantly.

Examples:

User suspension
Role updates
Subscription expiration
Emergency revocation

Challenges:

Stale JWT permissions
Cached authorization data
Distributed systems consistency

Recommended:

Short-lived tokens
Server-side validation
Permission versioning

Caching & Performance Optimization

Authorization can become expensive at scale.

Large systems may process:

Millions of permission checks per minute

Optimization Strategies

1. Policy Caching
Cache compiled policies.

2. Attribute Caching
Use Redis for frequently accessed attributes.

3. Decision Memoization
Cache repeated authorization decisions.

4. Batch Authorization
Instead of:
1000 separate permission checks
Use:
1 bulk evaluation

Frontend Authorization Patterns

Frontend authorization is for UX only.
Backend authorization is mandatory.

Good Frontend Pattern

<Can action="edit" resource="invoice">
 <EditButton />
</Can>

Avoid

Relying solely on hidden buttons
Attackers can still call APIs directly.

Backend Enforcement Strategy

Backend APIs must ALWAYS enforce authorization.

Example:

app.post('/invoice/:id', async (req, res) => {
 const allowed = await auth.can(
   req.user,
   'edit',
   invoice
 );

 if (!allowed) {
   return res.status(403).json({
     error: 'Forbidden'
   });
 }
});

“UI permissions improve experience. Backend permissions protect systems.”

Audit Logging & Compliance

Modern enterprises require full auditability.

Track:

Who accessed what
When access occurred
Why permission was granted
Policy evaluation result

Example:

User 482 edited invoice 882
Policy: FinanceManagerPolicy
Timestamp: 2026-05-22T10:14Z

Critical for:

SOC2
HIPAA
GDPR
ISO compliance

Testing Authorization Systems

Authorization bugs are security bugs.

Recommended Testing Levels

Example

test('contractor cannot access finance data', () => {
 const result = canAccess(contractor, financeReport);
 expect(result).toBe(false);
});

Real-World Example (Enterprise SaaS)

Scenario

A project management platform requires:

Admins - Full access
Managers - Manage own teams
Contractors - Limited projects only
Clients - Read-only assigned projects

Authorization Service

export const canAccessProject = ({ user,  project,  action }) => {
 if (user.role === 'admin') {
   return true;
 }
 if (user.teamId === project.teamId && action !== 'delete' ) {
   return true;
 }
 return false;
};

Frontend Usage

<Can action="update" resource={project}>
   <ProjectSettings />
</Can>

API Enforcement

if (!canAccessProject({ user, project, action })) {
  throw new ForbiddenError();
}

Interesting Facts

ABAC originated from military-grade access control systems where contextual authorization was mandatory. NIST ABAC Guide
Google’s BeyondCorp security model heavily relies on context-aware authorization principles. Google BeyondCorp
Modern cloud IAM systems from AWS and Azure support ABAC-style policies.AWS IAM ABAC Documentation
Policy engines like OPA (Open Policy Agent) are increasingly adopted in Kubernetes and cloud-native systems.Open Policy Agent

Stats

Fine-grained authorization is becoming a core requirement for enterprise SaaS platforms due to increasing compliance and multi-tenant security demands. Auth Authorization Trends](https://auth0.com/blog/what-is-abac-and-how-to-implement-it/)
Open Policy Agent is widely adopted across cloud-native infrastructure for centralized policy enforcement.CNCF OPA Project
Zero Trust architectures increasingly depend on contextual authorization instead of static role systems. Microsoft Zero Trust Model

FAQ’s

Q1. Is RBAC obsolete?
No. RBAC is still useful.

RBAC for broad roles
ABAC for fine-grained rules

Q2. Is ABAC harder to implement?
Yes, but it scales much better for complex systems.

Q3. Should authorization live in the frontend?
No.Frontend checks are UX enhancements only and Backend enforcement is mandatory.

Q4. What is the biggest authorization mistake?
Embedding permission logic directly inside business code everywhere.

Q5. Which companies benefit most from ABAC?

Enterprise SaaS
FinTech
Healthcare
Government systems
Multi-tenant platforms

Conclusion

Modern applications require more than static roles.

As systems scale, authorization becomes:

Context-aware
Dynamic
Fine-grained
Policy-driven The future of scalable security architecture lies beyond simple RBAC systems.

By adopting ABAC principles, centralized policy engines, and clean authorization architecture, teams can build systems that are:

More secure
Easier to scale
Easier to audit
Easier to maintain

“Authentication identifies users. Authorization defines boundaries.”

About the Author:Mayank is a web developer at AddWebSolution, building scalable apps with PHP, Node.js & React. Sharing ideas, code, and creativity.

Handling Long-Running Processes in UI

Abodh Kumar — Fri, 22 May 2026 10:47:24 +0000

In modern web and desktop applications, users routinely trigger operations that cannot complete in a single render cycle - file uploads, video transcoding, AI generation, data exports, batch imports, report generation, and complex calculations. Unlike a simple API call that resolves in milliseconds, these processes can take seconds, minutes, or even hours. How your interface communicates progress, allows cancellation, and survives navigation defines whether users trust your application or abandon it mid-task.

Key Takeaway

Always model four states - queued, running, completed, and failed - for every long-running process, no exceptions.
Show determinate progress (with a percentage or ETA) whenever the duration is predictable; never leave users guessing how long they have to wait.
Decouple long-running work from the component lifecycle - the user must be free to navigate without aborting the task.
Provide cancellation for any process that takes longer than three seconds; users must always feel in control.
Use Web Workers, background tabs, or server-side jobs to keep the main thread responsive during heavy computation.
Persist process state across reloads and navigations so users can recover after refresh, network drops, or accidental tab closures.
Notify users on completion through in-app toasts, browser notifications, or email - never expect them to keep watching the screen.

Introduction
Understanding the Four Process States
Communicating Progress - Determinate, Indeterminate & Multi-Stage
Handling Cancellation, Failure & Recovery
Building a Custom useLongRunningTask Hook
Advanced Techniques
Stats & Interesting Facts
FAQ
Conclusion

1. Introduction

A long-running process is any operation whose duration exceeds the user's natural attention span for a single interaction - generally anything beyond two to three seconds. Examples are everywhere in modern software: uploading a 500 MB video, running an AI image generation job, exporting a 100,000-row spreadsheet, transcoding audio, performing a database migration triggered from an admin panel, or compiling a project in a browser-based IDE.

These processes share a common trait: the user initiates them, then has nothing to do but wait. If your interface handles that wait poorly - by freezing, hiding, or silently failing - users assume your application is broken. Worse, they may close the tab, lose their work, and never return.

Done well, long-running process UX feels almost magical. The user uploads a file, sees a clear progress indicator, navigates to another page, gets a notification when the upload finishes, and never once feels trapped. Done badly, the same operation produces a frozen browser tab, an indefinite spinner, and a frustrated user.

This article covers a complete strategy for handling long-running processes in modern web UIs - from foundational state modeling and progress indicators to background workers, cancellation patterns, resumable uploads, and cross-session persistence.

2. Understanding the Four Process States

Unlike short API calls (which only need three states), long-running processes require a richer state model. Every long-running task should be in exactly one of these four states at any given moment:

2.1 The Queued State

The queued state exists from the moment the user triggers the action until the process actually begins executing. This is non-trivial: many systems queue work behind a rate limiter, a worker pool, or a server-side job queue. The user needs to know their request was accepted, where they are in the queue, and roughly when execution will start. Skipping this state and jumping straight to "running" lies to the user when there is real waiting time before any work happens.

2.2 The Running State

The running state covers the actual execution. This is where progress communication matters most. Depending on the nature of the task, you may know the percentage complete (a file upload), the current step out of N (a multi-stage pipeline), or only that work is happening (an open-ended AI generation). Each calls for a different visual treatment.

2.3 The Completed State

When the process finishes successfully, the UI must transition into a clear success state - ideally with a summary of what was produced, a link to the result, and an action the user can take next. A common mistake is to silently return to the previous screen, which leaves users uncertain whether the task actually succeeded.

2.4 The Failed or Cancelled State

Any failure - whether from a server error, a timeout, a quota exceedance, or an explicit user cancellation - must surface to the user with a clear explanation and, where applicable, a way to retry or resume. Cancellation deserves special treatment: it was intentional, so the message should confirm rather than alarm.

A foundational pattern using a single status enum keeps these states explicit:

import { useState, useReducer } from 'react';

const initialState = {
  status: 'idle', // idle | queued | running | completed | failed | cancelled
  progress: 0,
  result: null,
  error: null,
};

function processReducer(state, action) {
  switch (action.type) {
    case 'queue':    return { ...initialState, status: 'queued' };
    case 'start':    return { ...state, status: 'running', progress: 0 };
    case 'progress': return { ...state, progress: action.value };
    case 'complete': return { ...state, status: 'completed', progress: 100, result: action.result };
    case 'fail':     return { ...state, status: 'failed', error: action.error };
    case 'cancel':   return { ...state, status: 'cancelled' };
    case 'reset':    return initialState;
    default:         return state;
  }
}

function ExportButton() {
  const [state, dispatch] = useReducer(processReducer, initialState);

  async function startExport() {
    dispatch({ type: 'queue' });
    const job = await api.createExportJob();

    dispatch({ type: 'start' });
    const unsubscribe = subscribeToJob(job.id, {
      onProgress: (value) => dispatch({ type: 'progress', value }),
      onComplete: (result) => dispatch({ type: 'complete', result }),
      onError:    (error) => dispatch({ type: 'fail', error: error.message }),
    });

    return unsubscribe;
  }

  if (state.status === 'idle')      return <button onClick={startExport}>Start Export</button>;
  if (state.status === 'queued')    return <QueuedIndicator />;
  if (state.status === 'running')   return <ProgressBar value={state.progress} />;
  if (state.status === 'completed') return <DownloadLink href={state.result.url} />;
  if (state.status === 'failed')    return <ErrorPanel message={state.error} onRetry={startExport} />;
  if (state.status === 'cancelled') return <CancelledNotice onRestart={startExport} />;
}

3. Communicating Progress - Determinate, Indeterminate & Multi-Stage

The single biggest factor in how users tolerate waiting is whether they can predict how much longer they have to wait. Research in UX psychology consistently shows that perceived duration is far more important than actual duration - and the right progress indicator can make a 30-second wait feel shorter than a 10-second wait with no feedback.

3.1 Determinate Progress Bars - When You Know the Total

A determinate progress bar shows a percentage, an ETA, or both. Use it whenever you can reasonably estimate the total work - file uploads (you know the byte size), batch imports (you know the row count), or paginated data exports (you know the page count). Always pair the visual bar with a numeric percentage and, if possible, an estimated time remaining.

function ProgressBar({ value, etaSeconds, label }) {
  return (
    <div className="progress-container" role="progressbar"
         aria-valuenow={value} aria-valuemin={0} aria-valuemax={100}
         aria-label={label}>
      <div className="progress-track">
        <div className="progress-fill" style={{ width: `${value}%` }} />
      </div>
      <div className="progress-meta">
        <span>{Math.round(value)}%</span>
        {etaSeconds != null && <span>{formatEta(etaSeconds)} remaining</span>}
      </div>
    </div>
  );
}
function formatEta(seconds) {
  if (seconds < 60) return `${Math.round(seconds)}s`;
  if (seconds < 3600) return `${Math.round(seconds / 60)}m`;
  return `${(seconds / 3600).toFixed(1)}h`;
}

3.2 Indeterminate Indicators - For Unknown Durations

Some tasks have genuinely unknowable duration: an AI text generation, a complex SQL query, or any process behind an opaque external service. In these cases, a determinate bar would be a lie. Use an indeterminate animation - a sweeping bar, a pulsing shape, or a series of step descriptions - to communicate "we are working" without falsely promising a specific finish time. Where possible, replace pure motion with descriptive status text that updates as the task progresses ("Analyzing input...", "Generating response...", "Finalizing output...").

function IndeterminateProgress({ stage }) {
  return (
    <div className="indeterminate" role="status">
      <div className="indeterminate-bar" />
      <p className="stage-label">{stage || 'Working...'}</p>
    </div>
  );
}
// CSS
/*
.indeterminate-bar {
  position: relative;
  height: 4px;
  background: #e0e0e0;
  overflow: hidden;
  border-radius: 2px;
}
.indeterminate-bar::after {
  content: '';
  position: absolute;
  height: 100%;
  width: 30%;
  background: #4a90e2;
  animation: slide 1.4s ease-in-out infinite;
}
@keyframes slide {
  0%   { left: -30%; }
  100% { left: 100%; }
}
*/

3.3 Multi-Stage Progress

Many real-world processes are pipelines: upload → validate → process → export → notify. A single progress bar collapses this into one number, hiding useful information. A stepper or checklist UI exposes each stage individually, so the user sees not only "we are 60% done" but "we just finished processing and are now exporting." This builds confidence that the system is making real progress, especially for long pipelines where any single stage may pause for a while.

function MultiStageProgress({ stages, currentStage }) {
  return (
    <ol className="stage-list">
      {stages.map((stage, i) => {
        const status = i < currentStage ? 'done' : i === currentStage ? 'active' : 'pending';
        return (
          <li key={stage.id} className={`stage stage-${status}`}>
            <span className="stage-icon">
              {status === 'done' && '✓'}
              {status === 'active' && <Spinner />}
              {status === 'pending' && '○'}
            </span>
            <span className="stage-label">{stage.label}</span>
            {status === 'active' && stage.detail && (
              <span className="stage-detail">{stage.detail}</span>
            )}
          </li>
        );
      })}
    </ol>
  );
}

The function of design is letting design function. - Micha Commeren

4. Handling Cancellation, Failure & Recovery

A process that cannot be cancelled is a trap. A process that fails without explanation is worse. Robust long-running UX treats cancellation, failure, and recovery as first-class concerns rather than afterthoughts.

4.1 Cancellation - Always Available, Always Clean

Any process taking longer than three seconds should expose a cancel control. Cancellation must be honest: if the work is already partially complete on the server, the UI must explain what happens to that partial result (kept, discarded, or rolled back). Silent or unreliable cancellation - where the button does nothing or the work continues anyway - destroys user trust faster than an outright crash.

function CancellableUpload({ file }) {
  const [progress, setProgress] = useState(0);
  const [status, setStatus] = useState('idle');
  const controllerRef = useRef(null);

  async function start() {
    const controller = new AbortController();
    controllerRef.current = controller;
    setStatus('running');

    try {
      await uploadFile(file, {
        signal: controller.signal,
        onProgress: setProgress,
      });
      setStatus('completed');
    } catch (err) {
      if (err.name === 'AbortError') {
        setStatus('cancelled');
      } else {
        setStatus('failed');
      }
    }
  }

  function cancel() {
    controllerRef.current?.abort();
  }

  return (
    <div>
      {status === 'running' && (
        <>
          <ProgressBar value={progress} />
          <button onClick={cancel}>Cancel upload</button>
        </>
      )}
      {status === 'cancelled' && (
        <p>Upload cancelled. No data was saved.</p>
      )}
    </div>
  );
}

4.2 Distinguishing Failure Modes

Long-running failures are not all the same. Group them into categories your UI can respond to differently:

Recoverable network failures - The connection dropped mid-upload. Offer automatic retry, ideally resuming from the last successful chunk rather than restarting.
Server-side processing errors - The server accepted the input but couldn't complete the work (transcoding error, malformed data row, AI safety rejection). Show the specific reason and, where possible, a way to fix and retry.
Quota or limit errors - The user hit a plan limit, rate limit, or storage cap. Surface the specific limit and a clear path to resolve it (upgrade, free up space, wait).
Timeouts - The process exceeded a maximum allowed duration. Communicate this honestly rather than letting the spinner run indefinitely.
User cancellation - Treat differently from failure. Confirm the cancellation succeeded, state what was kept or discarded, and offer a clear restart path.

4.3 Recovery and Resumability

For any process that takes more than a few seconds, design for the assumption that something will go wrong - the network will drop, the tab will close, the laptop will sleep. The most resilient UIs persist process state to durable storage (IndexedDB, localStorage, or a server-side job record) so that on next load, the user can resume from where they left off.

function useResumableUpload(fileId) {
  const [state, setState] = useState(() => {
    const saved = localStorage.getItem(`upload:${fileId}`);
    return saved ? JSON.parse(saved) : { offset: 0, status: 'idle' };
  });

  useEffect(() => {
    localStorage.setItem(`upload:${fileId}`, JSON.stringify(state));
  }, [fileId, state]);

  async function resume(file) {
    setState(s => ({ ...s, status: 'running' }));
    for (let offset = state.offset; offset < file.size; offset += CHUNK_SIZE) {
      const chunk = file.slice(offset, offset + CHUNK_SIZE);
      await uploadChunk(fileId, offset, chunk);
      setState({ offset: offset + CHUNK_SIZE, status: 'running' });
    }
    setState(s => ({ ...s, status: 'completed' }));
    localStorage.removeItem(`upload:${fileId}`);
  }

  return { state, resume };
}

5. Building a Custom useLongRunningTask Hook

Repeating queue/run/cancel/recover logic in every component is unmaintainable. A custom hook centralizes the lifecycle, exposes a clean API to components, and ensures every long-running task in your app behaves consistently.

5.1 The useLongRunningTask Hook

import { useReducer, useRef, useCallback, useEffect } from 'react';

function useLongRunningTask(taskFn) {
  const [state, dispatch] = useReducer(processReducer, initialState);
  const controllerRef = useRef(null);

  const start = useCallback(async (...args) => {
    if (controllerRef.current) controllerRef.current.abort();
    const controller = new AbortController();
    controllerRef.current = controller;

    dispatch({ type: 'queue' });

    try {
      dispatch({ type: 'start' });
      const result = await taskFn(...args, {
        signal: controller.signal,
        onProgress: (value) => dispatch({ type: 'progress', value }),
      });
      if (!controller.signal.aborted) {
        dispatch({ type: 'complete', result });
      }
    } catch (err) {
      if (err.name === 'AbortError') {
        dispatch({ type: 'cancel' });
      } else {
        dispatch({ type: 'fail', error: err.message });
      }
    }
  }, [taskFn]);

  const cancel = useCallback(() => {
    controllerRef.current?.abort();
  }, []);

  const reset = useCallback(() => {
    controllerRef.current?.abort();
    dispatch({ type: 'reset' });
  }, []);

  useEffect(() => {
    return () => controllerRef.current?.abort();
  }, []);

  return { ...state, start, cancel, reset };
}
// Usage
function VideoExport({ projectId }) {
  const task = useLongRunningTask((id, opts) => api.exportVideo(id, opts));

  if (task.status === 'idle')
    return <button onClick={() => task.start(projectId)}>Export Video</button>;

  if (task.status === 'queued' || task.status === 'running')
    return (
      <div>
        <ProgressBar value={task.progress} />
        <button onClick={task.cancel}>Cancel</button>
      </div>
    );

  if (task.status === 'completed')
    return <DownloadLink href={task.result.url} onDismiss={task.reset} />;

  if (task.status === 'failed')
    return <ErrorPanel message={task.error} onRetry={() => task.start(projectId)} />;

  if (task.status === 'cancelled')
    return <p>Export cancelled. <button onClick={task.reset}>Start over</button></p>;
}

5.2 Decoupling From the Component Lifecycle

A subtle but critical point: the hook above ties the task lifetime to the component that started it. If the user navigates away, the task is cancelled. For most long-running processes, that is the wrong default - users expect to start a job, leave the page, and find it still running when they return. The fix is to store the running task in a global state container (Zustand, Redux, or a React context provider above the router) so it survives navigation:

import { create } from 'zustand';

const useTaskStore = create((set, get) => ({
  tasks: {}, // taskId -> task state

  startTask(taskId, taskFn, args) {
    const controller = new AbortController();
    set(s => ({ tasks: { ...s.tasks, [taskId]: { status: 'running', progress: 0, controller } } }));

    taskFn(...args, {
      signal: controller.signal,
      onProgress: (value) => set(s => ({
        tasks: { ...s.tasks, [taskId]: { ...s.tasks[taskId], progress: value } }
      })),
    })
      .then(result => set(s => ({
        tasks: { ...s.tasks, [taskId]: { ...s.tasks[taskId], status: 'completed', result } }
      })))
      .catch(err => set(s => ({
        tasks: { ...s.tasks, [taskId]: { ...s.tasks[taskId], status: 'failed', error: err.message } }
      })));
  },

  cancelTask(taskId) {
    get().tasks[taskId]?.controller.abort();
  },
}));

Now any component anywhere in the tree can read the task's current state, and the task continues to run regardless of which page is mounted.

Progress is impossible without change, and those who cannot communicate progress will be assumed to have made none. - Adapted from George Bernard Shaw

6. Advanced Techniques

6.1 Web Workers for CPU-Bound Tasks

If your long-running process is heavy computation in the browser - image processing, parsing a large CSV, encrypting a file - running it on the main thread will freeze the UI. A Web Worker moves the work to a background thread, keeping animations smooth and inputs responsive.

function useWorkerTask(workerUrl) {
  const [progress, setProgress] = useState(0);
  const [result, setResult] = useState(null);
  const workerRef = useRef(null);

  function start(payload) {
    const worker = new Worker(workerUrl, { type: 'module' });
    workerRef.current = worker;

    worker.onmessage = (e) => {
      if (e.data.type === 'progress') setProgress(e.data.value);
      if (e.data.type === 'done')     { setResult(e.data.result); worker.terminate(); }
    };
    worker.postMessage({ type: 'start', payload });
  }

  function cancel() {
    workerRef.current?.terminate();
  }

  return { progress, result, start, cancel };
}

6.2 Server-Sent Events for Real-Time Progress

For long-running server-side jobs, polling for status is wasteful and laggy. Server-Sent Events (SSE) give you a one-way streaming connection that pushes progress updates as the server produces them - ideal for AI generation, video transcoding, or any workflow where the server is the source of truth.

function useJobStream(jobId) {
  const [state, setState] = useState({ status: 'connecting', progress: 0 });

  useEffect(() => {
    const source = new EventSource(`/api/jobs/${jobId}/stream`);

    source.addEventListener('progress', (e) => {
      const data = JSON.parse(e.data);
      setState({ status: 'running', progress: data.progress, stage: data.stage });
    });

    source.addEventListener('complete', (e) => {
      setState({ status: 'completed', result: JSON.parse(e.data) });
      source.close();
    });

    source.addEventListener('error', () => {
      setState(s => ({ ...s, status: 'failed', error: 'Connection lost' }));
      source.close();
    });

    return () => source.close();
  }, [jobId]);

  return state;
}

6.3 Browser Notifications and Tab-Title Updates

Users will not stare at a progress bar for ten minutes. They will switch tabs, check email, or walk away. To bring them back when the work is done, use the Notifications API for a native push and update the document title with a status icon so a glance at the tab strip tells them whether to come back.

function useCompletionNotification(status, message) {
  useEffect(() => {
    if (status === 'completed') {
      document.title = '✓ Done — ' + originalTitle;
      if (Notification.permission === 'granted') {
        new Notification('Process complete', { body: message });
      }
    } else if (status === 'failed') {
      document.title = '✗ Failed — ' + originalTitle;
    } else if (status === 'running') {
      document.title = '⏳ Working — ' + originalTitle;
    } else {
      document.title = originalTitle;
    }
  }, [status, message]);
}

Always request notification permission contextually - at the moment the user starts a long task, not on page load. Cold-start permission prompts are denied 90% of the time.

6.4 Persistent Background Jobs With Service Workers

For uploads, exports, or syncs that should survive even if the user closes the tab, register a Service Worker with the Background Sync API. The browser holds the work in a queue and resumes it when the network is available, even if the originating page is gone. This pattern powers the "your message will be sent when you're back online" experience in modern messaging apps.

async function queueBackgroundUpload(file) {
  const reg = await navigator.serviceWorker.ready;
  await reg.sync.register('upload-pending');
  await stashFileInIndexedDB(file);
}

// In the service worker
self.addEventListener('sync', (event) => {
  if (event.tag === 'upload-pending') {
    event.waitUntil(processQueuedUploads());
  }
});

7. Stats & Interesting Facts

According to research compiled by the Nielsen Norman Group, the upper limit for keeping a user's attention focused on a dialog without progress feedback is approximately 10 seconds - past this, users start switching context and may abandon the task entirely. Source: https://www.nngroup.com/articles/response-times-3-important-limits/
A study by Chris Harrison and colleagues at Carnegie Mellon University found that progress bars with backward-decelerating animation (fast at first, slowing down) are perceived as up to 12% faster than uniform progress bars covering the same actual time. Source: https://www.chrisharrison.net/index.php/Research/ProgressBars
Akamai's 2017 online retail performance report found that a two-second delay during a checkout-related process more than doubled the bounce rate. Long-running processes without clear progress feedback amplify this effect dramatically.Source: https://www.akamai.com/newsroom/press-release/akamai-releases-spring-2017-state-of-online-retail-performance-report
According to Cloudflare's State of Application Security report, large-file uploads abandoned mid-transfer due to lack of resumability cost e-commerce and SaaS platforms millions of dollars in lost user productivity each year.Source: https://www.cloudflare.com/lp/state-of-application-security-report/
Chrome's Web Vitals data shows that pages with a Total Blocking Time over 600ms - common when long-running processes run on the main thread - have measurably higher abandonment rates than pages that offload work to Web Workers.Source: https://web.dev/articles/tbt
A 2024 study published by the Baymard Institute found that 27% of e-commerce checkout abandonment is attributable to interfaces that appear unresponsive during payment processing - a textbook long-running process UX failure.Source: https://baymard.com/lists/cart-abandonment-rate
Stripe's developer documentation reports that approximately 8% of payment-confirmation flows experience a network interruption between request and confirmation, making resumable, idempotent process handling essential for financial UX.Source: https://stripe.com/docs/payments/payment-intents

8. FAQ

1. When should a process be treated as "long-running" and given a dedicated UX, rather than just a spinner?

Ans: A useful heuristic is the three-second rule: any process that may take longer than three seconds in the 95th-percentile case deserves dedicated long-running UX. Below that threshold, a simple loading state is sufficient. Above it, you need progress feedback, cancellation, and survivability across navigation. Be honest about your real-world latency distribution, not the best case on a fast network.

2. Should a long-running task be tied to a single component, or should it survive navigation?

Ans: It depends on the user's mental model. If the task is conceptually local to the page (e.g., a search refinement), tying it to the component is fine. If the user thinks of the task as something they "started" - an upload, an export, a video render - it should survive navigation, ideally by living in a global state container or being driven by a server-side job that the UI subscribes to.

3. How do I show progress when the duration is genuinely unknown?

Ans: Show an indeterminate animation paired with descriptive status text that updates as the process advances ("Connecting...", "Analyzing...", "Generating output..."). This gives the user something to read and watch, signals real progress, and avoids the lie of a fake percentage. Never display a fabricated ETA - users notice when bars stall at 99% and lose trust.

4. What is the best way to cancel a long-running task that is partially complete on the server?

Ans: Always be explicit about what cancellation means in the UI. If the server can roll back the partial work, say so ("Cancel and discard"). If the partial work will be kept, say that instead ("Cancel — your progress so far will be saved"). Ambiguity here causes users to hesitate or, worse, to refresh the page mid-task and lose data.

5. How should I handle a tab being closed in the middle of a long-running process?

Ans: For client-driven processes, persist progress to IndexedDB or localStorage and offer to resume on next visit. For server-driven jobs, use a server-side job record so the work continues regardless of the client - the user can simply reconnect and the UI subscribes to the existing job. For uploads specifically, use a chunked, resumable protocol (tus.io is the open standard).

6. Should I use polling or streaming (SSE/WebSockets) for progress updates?

Ans: Streaming is strictly better for user experience: lower latency, less server load, no wasted requests. Use polling only when streaming infrastructure is unavailable, or as a fallback when the stream connection drops. If you do poll, use exponential backoff and a maximum interval to avoid hammering the server for jobs that take hours.

7. How do I keep the UI responsive during a CPU-heavy process in the browser?

Ans: Move the work to a Web Worker. The main thread is responsible for rendering and input handling - any long-running computation there will freeze the UI, drop frames, and make the page feel broken. Workers communicate via postMessage and have access to most APIs you need for compute-heavy tasks. For very large datasets, consider streaming results back in chunks rather than waiting for the entire computation to finish.

8. What's the right way to notify a user that a long-running task has finished if they've switched tabs?

Ans: Layer your notifications. First, update the document title with a status icon - users glance at tab strips constantly. Second, fire a Web Notification if permission has been granted. Third, for tasks that may complete after the user has fully closed the app, send an email or push notification from the backend. Never rely on a single channel; users check different channels at different times.

The most precious resource we all have is time. - Steve Jobs

9. Conclusion

Long-running processes are not edge cases - they are central to modern application UX. Every minute spent improving how your app handles uploads, exports, generations, and batch jobs returns disproportionate user trust. The strategies described in this article each address a specific dimension of that experience:

Explicit four-state modeling ensures queued, running, completed, and failed are always represented, never collapsed or implicit.
Progress communication - whether determinate, indeterminate, or multi-stage - turns waiting from a passive frustration into an informed wait.

Cancellation and recovery put the user in control, ensuring no process can trap them or destroy work silently.
Custom hooks and global stores decouple long-running tasks from the component lifecycle, so navigation and unmounts don't kill in-flight work.

Web Workers, SSE, and Service Workers keep the UI responsive, pipe real-time updates, and let work survive tab closures.
Notifications and title updates bring users back the moment their work is ready, instead of forcing them to babysit a progress bar.

The browser and modern frameworks give you every primitive you need. The responsibility lies with developers to compose them with care, treat long-running UX as a design problem rather than an engineering afterthought, and remember that for many users the difference between a finished task and an abandoned one is whether the interface respected their time.

The best long-running UX feels like a quiet promise kept. The user starts something, the system honors that intent through whatever conditions arise, and at the end - whether seconds or hours later - delivers the result clearly. That invisibility, that reliability, is the mark of mature product engineering.

About the Author: Abodh is a PHP and Laravel Developer at AddWeb Solution, skilled in MySQL, REST APIs, JavaScript, Git, and Docker for building robust web applications.

Accessibility (a11y) in Modern Apps

Vatsal Acharya — Fri, 15 May 2026 12:17:50 +0000

“The power of the Web is in its universality. Access by everyone regardless of disability is an essential aspect.” - Tim Berners-Lee

Key Takeaways

Accessibility (a11y) ensures apps are usable by everyone, including people with disabilities
It improves UX, SEO, and performance, not just compliance
Modern apps must support keyboard navigation, screen readers, and visual adjustments
Ignoring accessibility leads to real business loss + legal risks
Accessibility is not a feature - it’s a foundation

Index

What is Accessibility (a11y)?
Why Accessibility Matters
Types of Disabilities to Consider
Core Principles (WCAG)
Common Accessibility Mistakes
Practical Implementation (Frontend + Backend)
Tools for Testing Accessibility
Real-World Examples
Key Takeaways
FAQs
Conclusion

What is Accessibility (a11y)?

Accessibility (often shortened as a11y, because there are 11 letters between “a” and “y”) refers to designing applications that can be used by people with:

Visual impairments
Hearing impairments
Motor disabilities
Cognitive limitations

It ensures your app works with:

Screen readers
Keyboard-only navigation
Voice controls
Assistive technologies

Why Accessibility Matters

Most devs think: “My users don’t need this.”
That’s usually wrong.

1. Real Users Need It
Millions rely on assistive tech daily
Temporary disabilities (injuries, fatigue) also matter

2. Better UX for Everyone
Keyboard shortcuts = power users love it
Proper contrast = better readability for all

3. SEO Benefits
Semantic HTML improves indexing
Alt text improves image discoverability

4. Legal Compliance
Many countries enforce accessibility standards
Non-compliance can lead to lawsuits

Types of Disabilities to Consider

Visual

Blindness
Low vision
Color blindness

Hearing

Deafness
Hard of hearing

Motor

Limited hand movement
Cannot use a mouse

Cognitive

Dyslexia
ADHD
Memory issues

“The Web is fundamentally designed to work for all people, whatever their hardware, software, language, location, or ability.” - World Wide Web Consortium (W3C)

Core Principles (WCAG)

Accessibility is guided by WCAG (Web Content Accessibility Guidelines):

1. Perceivable

Users must be able to see/hear content
→ Example: Alt text for images

2. Operable

Users must be able to navigate
→ Example: Keyboard navigation

3. Understandable

Content must be clear and predictable

4. Robust

Works across devices and assistive tech

Common Accessibility Mistakes

Missing alt text on images
Using div instead of semantic tags (button, nav)
No keyboard navigation support
Poor color contrast
Forms without labels
Auto-playing videos without controls

Practical Implementation

1. Semantic HTML (Most Important)

<button>Submit</button> <!-- Correct -->
<div onclick="submit()">Submit</div> <!-- Wrong -->

2. Alt Text for Images

<img src="product.jpg" alt="Red running shoes with white sole">

3. Keyboard Accessibility
Ensure all interactive elements are reachable via Tab
Use :focus styles

button:focus {
outline: 2px solid blue;
}

4. ARIA (Use Carefully)

<button aria-label="Close menu">X</button>

Rule: Don’t use ARIA if native HTML can do the job

5. Forms Accessibility

<label for="email">Email</label>
<input id="email" type="email" />

6. Color Contrast

Minimum ratio: 4.5:1
Avoid light gray text on white background

7. Screen Reader Support
Test using:

NVDA (Windows)
VoiceOver (Mac)

8. Accessibility in React

<button onClick={handleClick}>
 Submit
</button>

Avoid:

<div onClick={handleClick}>
 Submit
</div>

9. Accessibility in Laravel (Backend)

Validate meaningful error messages
Return proper status codes
Support localization (multi-language)

“Accessibility is not a feature, it is a social trend.” - Antonio Santos

Tools for Testing Accessibility

Lighthouse (Chrome DevTools)
axe DevTools
WAVE
Screen readers

Real-World Example

Imagine:

A user cannot use a mouse
Your app has no keyboard navigation

Your app is completely unusable
That’s not a “minor bug” - that’s total failure

Interesting Facts

Over 1 billion people live with some form of disability. Source
Accessibility improvements can increase conversion rates Source
Many accessibility fixes take less than 5 minutes
Around 40.9% of color combinations on major websites still fail WCAG contrast requirements. Source

FAQs

Q1: Is accessibility only for disabled users?
No - it improves usability for everyone.

Q2: Is ARIA enough?
No - proper HTML matters more.

Q3: Does accessibility slow development?
Initially yes, but saves time later.

“Designing for accessibility does not only benefit people with disabilities - it benefits everyone.” - Microsoft

Conclusion

Accessibility is not optional anymore.
Modern apps must be:

Inclusive
Usable
Compliant If your app isn’t accessible, it’s not truly “modern.”

About the Author:Vatsal is a web developer at AddWebSolution. Building web magic with Laravel, PHP, MySQL, Vue.js & more.

Managing Environment Variables in React Properly

Lakashya Upadhyay — Wed, 29 Apr 2026 07:36:27 +0000

Environment variables in React often look simple at first, but they can quickly become a source of bugs, leaks, and deployment confusion if handled carelessly. In modern React apps, especially with Vite or CRA, the way you name, store, and access environment variables matters just as much as the values themselves.

This guide walks through the most common mistakes developers make when managing environment variables in React, explains why they happen, and shows how to set up a clean and reliable environment configuration strategy.

Key Takeaways

Use the correct prefix for your build tool: REACT_APP_ for CRA and VITE_ for Vite.youtubevite
Never store secrets in client-side environment variables, because anything shipped to the browser can be inspected.
Keep .env.local for local-only values and add env files to .gitignore when appropriate.
Use import.meta.env in Vite instead of process.env.
Keep environment variables documented, consistent, and validated before the app uses them.

Index

Why This Matters
Mistake 1: Using the Wrong Environment Variable Prefix
Mistake 2: Treating Client-Side Env Vars Like Secrets
Mistake 3: Mixing process.env and import.meta.env
Mistake 4: Hardcoding URLs Instead of Using Config
Mistake 5: Not Using .env.local Properly
Mistake 6: Forgetting to Restart the Dev Server
Mistake 7: Keeping Too Many Environment Files Without a Clear Rule
Mistake 8: Not Validating Required Variables
Mistake 9: Committing Sensitive .env Files to Git
Mistake 10: Poor Naming and Documentation
Frequently Asked Questions (FAQs)
Interesting Facts & Stats
Conclusion

1. Why This Matters

React environment variables are usually used for API URLs, feature flags, analytics IDs, and deployment settings. The problem is that frontend apps are bundled for the browser, so misconfigured variables can lead to broken builds, undefined values, or exposed configuration that should never have been public.

A small mistake like using API_URL instead of VITE_API_URL or REACT_APP_API_URL can make the value unavailable in your app. Another common issue is assuming environment variables are private when they are actually shipped to the client bundle.

A good environment strategy makes your app:

Easier to deploy across dev, staging, and production.
Safer to maintain in a team.
Less likely to break from config mistakes.
Easier to document and onboard new developers.

2. Mistake 1: Using the Wrong Environment Variable Prefix

“Your variable name matters more than you think.”

In React, the framework or build tool only exposes specific environment variables to the client. In Create React App, custom variables must begin with REACT_APP_, while Vite exposes variables prefixed with VITE_ through import.meta.env.youtube
Example of the mistake:

text
API_URL=https://api.example.com
js
console.log(import.meta.env.API_URL);

How to fix it:
Use the correct prefix for your tool.

text
VITE_API_URL=https://api.example.com
js
console.log(import.meta.env.VITE_API_URL);
For CRA:
text
REACT_APP_API_URL=https://api.example.com
js
console.log(process.env.REACT_APP_API_URL);

Benefits:

Variables are actually available in the app.
Builds behave consistently across environments.
Your team knows which config values are intended for frontend use.

3. Mistake 2: Treating Client-Side Env Vars Like Secrets

“Anything in a React bundle is public.”

A very common misunderstanding is storing passwords, private tokens, or database credentials in frontend env files. React environment variables are bundled into client-side code, which means users can inspect them in the browser.

Example of the mistake:

text
VITE_STRIPE_SECRET_KEY=sk_live_12345

This is dangerous because any secret exposed to the front end can be discovered by end users.

How to fix it:
Use frontend env vars only for:

Public API base URLs.
Feature flags.
Analytics public IDs.
Non-sensitive deployment settings. Keep sensitive secrets on the backend, and let your React app communicate with a server API instead.

Benefits:

Better security.
Less risk of accidental leaks.
Cleaner separation between frontend and backend responsibilities.

4. Mistake 3: Mixing process.env and import.meta.env

“Use the syntax your build tool expects.”

One of the most frequent bugs in Vite apps is using process.env, which is a CRA/Node-style pattern. Vite expects values from import.meta.env.

Example of the mistake in Vite:

js
console.log(process.env.VITE_API_URL);

How to fix it:

js
console.log(import.meta.env.VITE_API_URL);
In CRA, the equivalent pattern is usually:
js
console.log(process.env.REACT_APP_API_URL);

Benefits:

Avoids undefined errors.
Keep your code compatible with the correct build environment.
Reduces confusion when switching between CRA and Vite.

5. Mistake 4: Hardcoding URLs Instead of Using Config

“Hardcoding works until deployment changes.”

A lot of React apps start with hardcoded endpoints like http://localhost:3000, then later break when deployed to staging or production. This makes the app harder to move between environments and increases refactoring work later.

Example of the mistake:

js
const baseUrl = 'http://localhost:8000/api';

How to fix it:
Move environment-specific values into env files.

text
VITE_API_URL=https://api.example.com
js
const baseUrl = import.meta.env.VITE_API_URL;

Benefits:

One codebase works across multiple environments.
Easier switching between dev and production.
Cleaner deployment pipeline.

6. Mistake 5: Not Using .env.local Properly

“Local overrides should stay local.”
A common best practice is to place developer-specific values in .env.local, which is intended for local overrides and usually not committed. This is especially useful when each developer has different local endpoints, test credentials, or personal feature flags.

Example structure:

text
.env
.env.development
.env.production
.env.local

How to fix it:

Use .env for shared defaults.
Use .env.local for machine-specific values.
Use .env.development and .env.production for environment-specific behavior.

Benefits:

Cleaner collaboration.
Fewer accidental git commits of personal values.
Easier developer onboarding.

7. Mistake 6: Forgetting to Restart the Dev Server

“Env changes are not always hot-reloaded.”

In many React setups, environment file changes do not always appear immediately in the running dev server. If a variable seems stuck or undefined, the first thing to try is restarting the server.

How to fix it:

Stop the dev server.
Save the .env file.
Start the server again.

Benefits:

Saves debugging time.
Prevents confusion when values appear stale.
Ensures the bundler picks up the latest config.

8. Mistake 7: Keeping Too Many Environment Files Without a Clear Rule

“Too many env files can become configuration chaos.”

It’s easy to end up with .env, .env.local, .env.development, .env.staging, .env.production, and several team-specific variants without a clear structure. That usually makes it hard to know which value is active in which environment.

How to fix it:
Define a simple convention:

.env for shared defaults.
.env.local for developer-specific overrides.
.env.development for local development.
.env.production for production build values.

Benefits:

Easier to understand.
Less confusion during deployment.
More predictable configuration behavior.

9. Mistake 8: Not Validating Required Variables

“Missing config should fail early.”

If your app depends on a value like VITE_API_URL, it should not silently continue with undefined. A missing environment variable often leads to broken API calls, blank screens, or confusing runtime errors.

How to fix it:
Check required values at app startup.

js
const apiUrl = import.meta.env.VITE_API_URL;

if (!apiUrl) {
  throw new Error('VITE_API_URL is missing');
}

Benefits:

Fails fast during development.
Prevents subtle runtime bugs.
Makes deployment issues easier to catch.

10. Mistake 9: Committing Sensitive .env Files to Git

“Git remembers everything.”

Another common mistake is committing real environment files to source control. Even if the repo later becomes private, the secret may already have been exposed in history.

How to fix it:

Add .env, .env.local, and secret files to .gitignore.
Commit only .env.example.
Put placeholder values in examples.

Example:

text
VITE_API_URL=
VITE_APP_NAME=

Benefits:

Protects secrets.
Makes setup easier for teammates.
Keeps the repo safer and cleaner.

11. Mistake 10: Poor Naming and Documentation

“Clear names save time later.”

Vague variable names like URL1, KEY, or TOKEN make maintenance harder. Good naming conventions help your team understand what belongs where and reduce mistakes when moving between projects.

Better names:

VITE_API_URL
VITE_APP_NAME
VITE_GOOGLE_MAPS_KEY
REACT_APP_BACKEND_URL

How to fix it:

Use uppercase letters and underscores.
Prefix only values meant for the frontend.
Document each variable in your README or .env.example.

Benefits:

Easier onboarding.
Better readability.
Less confusion during refactoring or deployment.

12. Frequently Asked Questions (FAQs)

Q. Can I use environment variables to hide secrets in React?
A. No. Anything shipped to the browser is visible to users, so secrets should stay on the backend.

Q. Why is import.meta.env undefined in my Vite app?
A. The variable probably does not use the VITE_ prefix, or the dev server needs a restart.

Q. What prefix should I use in CRA?
A. Use REACT_APP_ for custom variables in Create React App.youtubeconfigu

Q. Should I commit .env files?
A. Usually not for real secrets. Commit .env.example instead.

Q. Do I need separate env files for every environment?
A. Not always, but a clear convention for local, development, and production makes projects easier to manage.

13. Interesting Facts & Stats

Vite exposes custom client-side env variables through import.meta.env, and only variables prefixed with VITE_ are exposed by default. Source: Vite Env Variables and Modes
CRA requires the REACT_APP_ prefix for custom environment variables to be available in React code. Source: React .env File Hierarchy | Master Environment Variables in CRA & Vite
Many environment variable bugs are not code bugs at all, but naming or build-tool configuration issues. Source: React Environment Variables: Basics, Tutorial, and Best Practices
Using .env.local for local-only settings is a widely recommended pattern for safer collaboration. Source: React Environment Variables: Basics, Tutorial, and Best Practices

14. Conclusion

Managing environment variables in React is less about storing values and more about building a predictable configuration system. Once you follow the right prefixing rules, keep secrets off the client, and separate local, development, and production values properly, environment setup becomes much more reliable.

A good React environment strategy is simple:

Use the correct build-tool syntax.
Keep secrets on the server.
Document variables clearly.
Fail fast when config is missing.

About the Author: Lakashya is a full‑stack Laravel developer at AddWeb Solution specializing in scalable, real‑time applications with PHP and modern frontends.

Building Reusable UI Components in React (Clean & Scalable Approach)

Ankit Parmar — Mon, 27 Apr 2026 08:33:36 +0000

“Programs must be written for people to read, and only incidentally for machines to execute.” - Harold Abelson

Modern frontend applications grow fast-and without a solid component strategy, they become hard to maintain, inconsistent, and fragile. Reusable UI components solve this by promoting consistency, reducing duplication, and enabling scalable architecture.

But simply “reusing components” isn’t enough. Poorly designed components can create more problems than they solve.

In this article, we’ll explore how to build clean, reusable, and scalable UI components in React, focusing on architecture, patterns, and real-world practices-not just syntax.

Why Reusable Components Matter

Without reusable components, teams often face:

UI inconsistencies across pages
Duplicate logic and styling
Difficult debugging and updates
Slower development velocity

Reusable components help you:

Standardize design and behavior
Reduce code duplication
Improve maintainability
Speed up development

What Makes a Component Truly Reusable?

A reusable component is:

Generic → Works in multiple contexts
Composable → Can be combined with other components
Configurable → Controlled via props
Decoupled → Not tied to specific business logic Bad example: A UserDashboardCard hardcoded for one screen Good example: A Card component configurable via props

Core Philosophy
“Components should do one thing, and do it well.”
Focus on:
Separation of concerns
Clear interfaces (props)
Minimal assumptions

Key Takeaways

Reusable components reduce duplication and improve maintainability
Keep components small, focused, and composable
Use props for flexibility, not hardcoded values
Separate UI from business logic
Follow consistent folder and naming conventions
Avoid premature abstraction-refactor when patterns emerge
Design systems and shared libraries scale teams effectively

Index

Introduction
What Are Reusable Components?
Component Design Principles
Types of Reusable Components
Structuring Your Component Folder
Props and Configuration
Composition vs Inheritance
Styling Strategies
Handling State and Logic
Building a Design System
Common Mistakes to Avoid
Why This Approach Works
Watch Out For
Next Steps You Can Take
Interesting Facts
FAQ
Conclusion

1. Introduction

As React applications grow, managing UI becomes increasingly complex. Without a reusable component strategy, developers often duplicate UI patterns, leading to inconsistent designs and bloated codebases.
Reusable components solve this by encapsulating UI and behavior into modular building blocks. When done correctly, they create a system where features can be built faster and maintained more easily.

“Simplicity is prerequisite for reliability.” - Edsger W. Dijkstra

2. What Are Reusable Components?

Reusable components are UI elements that can be used across multiple parts of an application without modification.
Examples:

Buttons
Inputs
Modals
Cards
Tables
They are not tied to:
Specific pages
Business logic
Hardcoded data

3. Component Design Principles

1. Single Responsibility
Each component should handle one concern.

2. Reusability Over Specificity
Avoid embedding business logic inside UI components.

3. Predictable API
Props should be clear, consistent, and minimal.

4. Composition First
Build complex UI by combining smaller components.

4. Types of Reusable Components

1. Presentational Components

Focus only on UI
No business logic Example: Button, Card, Avatar

2. Container Components

Handle data and logic
Pass data to presentational components

3. Layout Components

Define page structure Example: Grid, Container, Sidebar

4. Compound Components

Multiple components working together Example: Tabs, Dropdown, Accordion

“Duplication is the root of all evil in software.” - Don’t Repeat Yourself principle

5. Structuring Your Component Folder

A scalable structure looks like:

components/
  ui/
    Button/
      Button.jsx
      Button.css
      index.js
  forms/
    Input/
    Select/
  layout/
    Container/

Key idea:

Group by feature or type, not by file type

6. Props and Configuration

Props are the backbone of reusability.
Example:

function Button({ variant = "primary", children, onClick }) {
  return (
    <button className={`btn btn-${variant}`} onClick={onClick}>
      {children}
    </button>
  );
}

Usage:

<Button variant="secondary">Cancel</Button>
<Button variant="primary">Save</Button>

Avoid:

Hardcoding values
Passing too many unrelated props

“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.” - Martin Fowler

7. Composition vs Inheritance

React favors composition over inheritance.
Bad approach:

Extending components like classes Good approach:

<Card>
  <Card.Header>Title</Card.Header>
  <Card.Body>Content</Card.Body>
</Card>

This keeps components:

Flexible
Readable
Easy to extend

8. Styling Strategies

Consistency in styling is critical.
Options:

1. CSS Modules

Scoped styles
Prevent conflicts

2. Tailwind CSS

Utility-first
Fast development

3. Styled Components

Dynamic styling
Component-level styles

Best practice:

Choose one approach and stay consistent

9. Handling State and Logic

Reusable components should avoid heavy logic.
Good pattern:

Keep logic outside
Pass data via props Bad:

// tightly coupled
function UserCard() {
  const user = fetchUser();
}

Good:

function UserCard({ user }) {
  return <div>{user.name}</div>;
}

10. Building a Design System

At scale, reusable components evolve into a design system.
A design system includes:

UI components
Design tokens (colors, spacing, typography)
Usage guidelines

Benefits:

Consistency across teams
Faster onboarding
Easier scaling ## 11. Common Mistakes to Avoid

Over-abstracting too early

Don’t generalize before patterns emerge.

Tight coupling

Avoid linking components to specific APIs or data sources.

Prop explosion

Too many props = hard to use.

Ignoring accessibility

Reusable components must support:

Keyboard navigation
ARIA attributes

12. Why This Approach Works

Reduces duplication
Improves readability
Encourages modular thinking
Makes testing easier
Scales across teams and projects

“The best way to build complex systems is to assemble them from simple, well-defined parts.” - David Parnas

Watch Out For

Over-engineering simple components
Creating unnecessary abstractions
Mixing business logic with UI
Inconsistent naming conventions

Next Steps You Can Take

Refactor duplicated UI into shared components
Introduce a ui/ component library
Document component usage
Add Storybook for visual testing
Enforce design consistency with linting

Interesting Facts

Most large-scale React apps rely heavily on internal component libraries source
Design systems can reduce development time significantly source
Component-driven development is a standard in modern frontend engineering source

16. FAQ

1. How small should a component be?
Small enough to do one job, but not so small that it becomes meaningless.

2. Should every component be reusable?
No. Only abstract when reuse is needed.

3. How do I manage shared components?
Use a centralized components or ui directory.

4. Is Tailwind better for reusable components?
It depends-great for speed, but consistency depends on discipline.

5. Can this scale for large apps?
Yes. This is exactly how large React apps are structured.

17. Conclusion

Building reusable UI components in React is not just about avoiding duplication-it’s about creating a scalable, maintainable architecture.
When done right, you get:

Cleaner code
Faster development
Consistent UI
Easier scaling If your goal is to build production-grade applications, investing in a strong component strategy isn’t optional-it’s foundational.

About the Author:Ankit is a full-stack developer at AddWebSolution and AI enthusiast who crafts intelligent web solutions with PHP, Laravel, and modern frontend tools.

Handling API Errors & Loading States in React (Clean UX Approach)

Abodh Kumar — Wed, 22 Apr 2026 07:40:37 +0000

A user interface is like a joke. If you have to explain it, it is not that good. - Martin LeBlanc

In any real-world React application, you will spend far more time handling what goes wrong than celebrating what goes right. Network failures, slow responses, timeouts, and server errors are not edge cases - they are everyday realities. How you communicate these states to your users defines the quality of your application's user experience.

Key Takeaway

Always model three states - loading, error, and success - for every API call, no exceptions.
Provide meaningful, context-specific error messages - never expose raw error objects to users.
Use skeleton screens instead of spinners where possible to reduce perceived load time.
Implement retry logic with exponential backoff for transient network failures.
Centralize error handling with custom hooks to avoid repeating logic across components.
Distinguish between network errors, HTTP errors, and validation errors - each requires different UX.
Always cancel in-flight requests on component unmount to prevent memory leaks and ghost state updates

Introduction
Understanding the Three API States
Handling Loading States - Spinners, Skeletons & Beyond
Handling API Errors - Graceful Degradation
Building a Custom useFetch Hook
Advanced Techniques
Stats & Interesting Facts
FAQ
Conclusion

1. Introduction

Modern React applications are almost always data-driven, relying on REST APIs, GraphQL endpoints, or third-party services to power their interfaces. Whether you are building a dashboard that fetches analytics data, a shopping app that loads product listings, or a social platform that streams user posts, every API interaction introduces three inevitable possibilities: the data is loading, the data arrived successfully, or something went wrong.
The difference between a great app and a frustrating one often comes down to how gracefully these states are handled. Users who encounter a blank screen during loading, a cryptic "undefined is not an object" message when an error occurs, or an interface that silently fails will lose trust in your product instantly.
This article walks you through a complete, production-ready strategy for handling API errors and loading states in React - covering everything from basic useState patterns and skeleton screens to custom hooks, Axios interceptors, and React Query integration.

2. Understanding the Three API States

Before writing a single line of code, it is essential to model your data fetching around three distinct states. Every API call in your application should reflect exactly one of these states at any given moment:

2.1 The Loading State

The loading state exists from the moment you initiate a request until a response (successful or otherwise) is received. Failing to model this state means users see stale data, empty screens, or worse - an interface that appears broken. A loading state should always trigger visible feedback.

2.2 The Success State

When the API returns the expected data with a successful status code (typically 2xx), the UI transitions to the success state. This is where you render the actual content. Even here, you must consider edge cases like empty arrays, null values, or partially missing fields.

2.3 The Error State

Any response outside the 2xx range, a network timeout, or a connection failure triggers the error state. This is the most neglected of the three, yet it is critical. Users need to know what failed and, where possible, what they can do about it.
A foundational pattern using React's useState hook illustrates this model clearly:

import { useState, useEffect } from 'react';
function UserProfile({ userId }) {
 const [user, setUser] = useState(null);
 const [loading, setLoading] = useState(true);
 const [error, setError] = useState(null);
 useEffect(() => {
   const controller = new AbortController();
   async function fetchUser() {
     try {
       setLoading(true);
       setError(null);
       const res = await fetch(`/api/users/${userId}`, {
         signal: controller.signal
       });
       if (!res.ok) {
         throw new Error(`Server error: ${res.status} ${res.statusText}`);
       }
       const data = await res.json();
       setUser(data);
     } catch (err) {
       if (err.name !== 'AbortError') {
         setError(err.message);
       }
     } finally {
       setLoading(false);
     }
   }
   fetchUser();
   return () => controller.abort(); // cleanup on unmount
 }, [userId]);

 if (loading) return <LoadingSkeleton />;
 if (error) return <ErrorMessage message={error} />;
 return <ProfileCard user={user} />;
}

Design is not just what it looks like and feels like. Design is how it works. - Steve Jobs

3. Handling Loading States - Spinners, Skeletons & Beyond

Not all loading indicators are equal. The choice of loading UI dramatically affects how users perceive your application's speed. Research in UX psychology consistently shows that users tolerate waiting much better when they receive structured, meaningful feedback.

3.1 Spinners - When to Use Them

Spinners (circular progress indicators) are appropriate for short, unpredictable waits - typically actions like form submissions, delete confirmations, or quick one-off requests. They signal activity without implying structure about what is loading. Use them sparingly; overuse of spinners across an interface feels chaotic.

function Spinner() {
 return (
   <div className="spinner-wrapper" role="status" aria-label="Loading">
     <div className="spinner" />
     <span className="sr-only">Loading...</span>
   </div>
 );
}

3.2 Skeleton Screens - The Gold Standard

Skeleton screens render placeholder shapes that mimic the final layout of your content before data arrives. They dramatically reduce perceived loading time by orienting the user to the page structure immediately. Facebook, LinkedIn, YouTube, and Slack all rely heavily on skeleton screens for their primary content feeds.

function ProductCardSkeleton() {
 return (
   <div className="card skeleton">
     <div className="skeleton-image" />
     <div className="skeleton-line wide" />
     <div className="skeleton-line medium" />
     <div className="skeleton-line narrow" />
   </div>
 );
}

// CSS for pulsing animation
/*
.skeleton-line {
 height: 16px;
 background: linear-gradient(90deg, #e0e0e0 25%, #f0f0f0 50%, #e0e0e0 75%);
 background-size: 200% 100%;
 animation: shimmer 1.5s infinite;
 border-radius: 4px;
 margin-bottom: 10px;
}
@keyframes shimmer {
 0% { background-position: 200% 0; }
 100% { background-position: -200% 0; }
}
*/

3.3 Progressive Loading

For data-heavy pages, consider progressive loading: render critical above-the-fold content first, then fetch secondary sections lazily. This approach, combined with React's Suspense boundaries, delivers a fast initial paint even on slower connections.

import { Suspense, lazy } from 'react';
const HeavyChartSection = lazy(() => import('./HeavyChartSection'));
function Dashboard() {
 return (
   <div>
     <HeroMetrics />  {/* Loads immediately */}
     <Suspense fallback={<ChartSkeleton />}>
       <HeavyChartSection />  {/* Loads lazily */}
     </Suspense>
   </div>
 );
}

4. Handling API Errors - Graceful Degradation

Error handling is where most React applications fall short. A robust error handling strategy distinguishes between different failure modes and responds to each appropriately.

4.1 Classifying Errors

Not all errors are the same. Build your error handling logic around these distinct categories:

Network Errors - The request never reached the server (offline, DNS failure, CORS). The user needs to check their connection.
HTTP 4xx Errors - Client-side errors (401 Unauthorized, 403 Forbidden, 404 Not Found, 422 Validation Failed). Each requires a specific response.
HTTP 5xx Errors - Server-side errors (500 Internal Server Error, 503 Service Unavailable). The user should be reassured it is not their fault.
Timeout Errors - The request took too long. Often appropriate to offer a retry.
Validation Errors - The server rejected the data (422). Field-level feedback is critical here.

function classifyError(err, statusCode) {
 if (!statusCode) return { type: 'network', message: 'No internet connection. Please check your network.' };
 if (statusCode === 401) return { type: 'auth', message: 'Your session has expired. Please log in again.' };
 if (statusCode === 403) return { type: 'forbidden', message: 'You do not have permission to view this resource.' };
 if (statusCode === 404) return { type: 'notfound', message: 'The requested resource could not be found.' };
 if (statusCode === 422) return { type: 'validation', message: 'Please check your input and try again.' };
 if (statusCode >= 500) return { type: 'server', message: 'Our servers are having trouble. Please try again shortly.' };
 return { type: 'unknown', message: 'Something went wrong. Please try again.' };
}

4.2 User-Friendly Error Components

Your error component should always communicate what went wrong, ideally offer a recovery action, and never expose raw error objects or stack traces to end users.

function ErrorMessage({ type, message, onRetry }) {
 const icons = {
   network: '📡',
   auth: '🔐',
   forbidden: '🚫',
   notfound: '🔍',
   server: '⚠️',
   unknown: '❓',
 };
 return (
   <div className="error-container" role="alert">
     <span className="error-icon">{icons[type] || icons.unknown}</span>
     <h3 className="error-title">Something went wrong</h3>
     <p className="error-message">{message}</p>
     {onRetry && (
       <button onClick={onRetry} className="retry-button">
         Try Again
       </button>
     )}
   </div>
 );
}

4.3 React Error Boundaries

For rendering errors (not async errors), React's Error Boundary class component catches exceptions thrown during render and prevents the entire tree from unmounting. Pair them with your async error states for comprehensive coverage.

class ErrorBoundary extends React.Component {
 constructor(props) {
   super(props);
   this.state = { hasError: false, error: null };
 }
 static getDerivedStateFromError(error) {
   return { hasError: true, error };
 }
 componentDidCatch(error, info) {
   console.error('ErrorBoundary caught:', error, info);
   // Send to error tracking service (e.g., Sentry)
 }
 render() {
   if (this.state.hasError) {
     return this.props.fallback || <DefaultErrorFallback />;
   }
   return this.props.children;
 }
}
// Usage
<ErrorBoundary fallback={<p>Something went wrong.</p>}>
 <UserDashboard />
</ErrorBoundary>

5. Building a Custom useFetch Hook

Repeating loading/error/success logic in every component is a maintenance nightmare. A custom hook centralizes this logic, ensures consistency, and makes components dramatically cleaner.

5.1 The useFetch Hook

function useFetch(url, options = {}) {
 const [data, setData] = useState(null);
 const [loading, setLoading] = useState(true);
 const [error, setError] = useState(null);
 const abortRef = useRef(null);
 const fetchData = useCallback(async () => {
   // Abort any in-flight request
   if (abortRef.current) abortRef.current.abort();
   const controller = new AbortController();
   abortRef.current = controller;
   setLoading(true);
   setError(null);

   try {
     const res = await fetch(url, {
       ...options,
       signal: controller.signal,
     });
     if (!res.ok) {
       const errData = await res.json().catch(() => ({}));
       throw Object.assign(new Error(errData.message || res.statusText), {
         status: res.status,
       });
     }
     const result = await res.json();
     setData(result);
   } catch (err) {
     if (err.name !== 'AbortError') {
       setError({ message: err.message, status: err.status });
     }
   } finally {
     setLoading(false);
   }
 }, [url]);

 useEffect(() => {
   fetchData();
   return () => abortRef.current?.abort();
 }, [fetchData]);

 return { data, loading, error, refetch: fetchData };
}
// Usage in a component
function ProductList() {
 const { data, loading, error, refetch } = useFetch('/api/products');

 if (loading) return <ProductListSkeleton />;
 if (error) return <ErrorMessage message={error.message} onRetry={refetch} />;
 if (!data?.length) return <EmptyState />;

 return (
   <ul>
     {data.map(product => <ProductCard key={product.id} product={product} />)}
   </ul>
 );
}

5.2 Adding Retry Logic with Exponential Backoff

Transient network errors often resolve themselves within seconds. Implementing automatic retry with exponential backoff dramatically improves resilience in unstable network environments.

async function fetchWithRetry(url, options = {}, maxRetries = 3) {
 for (let attempt = 0; attempt <= maxRetries; attempt++) {
   try {
     const res = await fetch(url, options);
     if (!res.ok && res.status >= 500 && attempt < maxRetries) {
       // Retry on 5xx with exponential backoff: 1s, 2s, 4s
       await new Promise(r => setTimeout(r, Math.pow(2, attempt) * 1000));
       continue;
     }
     return res;
   } catch (err) {
     if (attempt === maxRetries) throw err;
     await new Promise(r => setTimeout(r, Math.pow(2, attempt) * 1000));
   }
 }
}

There are only two types of API calls: those that have failed, and those that have not failed yet. Plan for both. - Unknown, React Community Proverb

6. Advanced Techniques

6.1 Using React Query for Robust Data Fetching

For production applications, React Query (now TanStack Query) provides battle-tested data fetching with built-in caching, background refetching, stale-while-revalidate patterns, and automatic retry - all without writing custom hooks from scratch.

import { useQuery } from '@tanstack/react-query';
function UserProfile({ userId }) {
 const { data, isLoading, isError, error, refetch } = useQuery({
   queryKey: ['user', userId],
   queryFn: () => fetch(`/api/users/${userId}`).then(res => {
     if (!res.ok) throw new Error('Failed to fetch user');
     return res.json();
   }),
   retry: 3,
   retryDelay: attemptIndex => Math.min(1000 * 2 ** attemptIndex, 10000),
   staleTime: 5 * 60 * 1000, // 5 minutes
 });

 if (isLoading) return <LoadingSkeleton />;
 if (isError) return <ErrorMessage message={error.message} onRetry={refetch} />;
 return <ProfileCard user={data} />;
}

6.2 Axios Interceptors for Global Error Handling

When using Axios, interceptors allow you to handle common error scenarios globally - such as redirecting to login on 401, showing a toast notification on 5xx errors, or refreshing tokens transparently.

import axios from 'axios';
import toast from 'react-hot-toast';
const api = axios.create({ baseURL: '/api' });
api.interceptors.response.use(
 response => response,
 error => {
   const status = error.response?.status;
   if (status === 401) {
     window.location.href = '/login';
   } else if (status >= 500) {
     toast.error('Server error. Our team has been notified.');
   } else if (!error.response) {
     toast.error('Network error. Please check your connection.');
   }
   return Promise.reject(error);
 }
);
export default api;

6.3 Optimistic Updates

For actions like liking a post or toggling a bookmark, optimistic updates apply the change to the UI immediately before the server confirms it. If the request fails, the UI rolls back. This technique makes interfaces feel instantaneous.

instantaneous.
function LikeButton({ postId, initialLiked }) {
 const [liked, setLiked] = useState(initialLiked);
 const [likeCount, setLikeCount] = useState(0);
 async function handleLike() {
   // Optimistically update UI
   const wasLiked = liked;
   setLiked(!wasLiked);
   setLikeCount(c => wasLiked ? c - 1 : c + 1);
   try {
     await api.post(`/posts/${postId}/like`, { liked: !wasLiked });
   } catch {
     setLiked(wasLiked);
     setLikeCount(c => wasLiked ? c + 1 : c - 1);
     toast.error('Could not update like. Please try again.');
   }
 }
 return <button onClick={handleLike}>{liked ? '❤️' : '🤍'} {likeCount}</button>;
}

6.4 Global Loading Indicator

For applications with many simultaneous API calls, a global loading bar (like the thin progress bar at the top of GitHub's pages) provides ambient feedback without disrupting the UI. Libraries like NProgress integrate cleanly with React.

import NProgress from 'nprogress';
import 'nprogress/nprogress.css';
// In your Axios instance
api.interceptors.request.use(config => { NProgress.start(); return config; });
api.interceptors.response.use(
 response => { NProgress.done(); return response; },
 error => { NProgress.done(); return Promise.reject(error); }
);

7. Stats & Interesting Facts

According to Google research, 53% of mobile users abandon a site that takes longer than 3 seconds to load. Effective loading state UX directly impacts retention.Source: https://www.thinkwithgoogle.com/marketing-strategies/app-and-mobile/mobile-page-speed-new-industry-benchmarks/
A study by the Nielsen Norman Group found that users perceive skeleton screens as significantly faster than equivalent spinner-based loading experiences, even when actual load times are identical. Source: https://www.nngroup.com/articles/progress-indicators/
According to State of JS surveys, React Query and SWR are now used by over 40% of React developers who fetch remote data, largely because of their built-in loading and error state management. Source: https://stateofjs.com
Research from Amazon found that every 100ms increase in page load time reduced sales by 1%. Loading state UX is not just a UX concern - it is a business metric.Source: https://www.fastcompany.com/1825005/how-one-second-could-cost-amazon-16-billion-sales
The HTTP Archive reports that the median mobile page makes over 70 separate HTTP requests. Without proper loading state management per request, the cumulative UX degradation is significant. Source: https://httparchive.org/reports/state-of-the-web
Sentry's 2023 developer survey found that unhandled promise rejections from API calls are among the top three sources of JavaScript errors in production React applications. Source: https://sentry.io/resources/developer-survey/
According to UX research by Toptal, 88% of online consumers are less likely to return to a site after a bad user experience - silent API failures with no user feedback are a primary driver of this statistic. Source: https://www.toptal.com/designers/ux/ux-statistics-insights-infographic

Good error messages are a form of documentation. They tell the user what went wrong, why it matters, and what to do about it. - Jakob Nielsen, Nielsen Norman Group

8. FAQ

1. Why should I model loading and error states separately rather than using a single "status" string?

Ans: Using separate boolean flags (loading, error) is simpler for most cases and avoids state machine complexity. However, a single status enum ("idle" | "loading" | "success" | "error") is a valid and arguably more explicit pattern, especially as state logic grows. The critical principle is that all three states must always be represented - never leave any one implicit.

2. What is the difference between a loading skeleton and a placeholder?

Ans: A skeleton screen mimics the actual layout and shape of the content that will appear, giving users a structural preview. A generic placeholder (e.g., a grey box or spinner) gives no structural information. Skeleton screens outperform generic placeholders in perceived performance because they orient the user before the content arrives.

3. Should I use React Query or write custom hooks for data fetching?

Ans: For simple, one-off fetch calls, a custom hook is sufficient and avoids adding a dependency. For production apps with complex caching, pagination, background syncing, or optimistic updates, React Query (TanStack Query) or SWR are strongly recommended. They solve problems that custom hooks inevitably re-implement poorly over time.

4. How should I handle validation errors returned from an API (HTTP 422)?

Ans: Parse the error response body to extract field-level validation messages and display them directly adjacent to the relevant form fields. Never show a generic error message for validation failures - users need to know exactly which field failed and why. React Hook Form and Formik both integrate well with server-side validation error patterns.

5. What should I do if a component unmounts before an API call completes?

Ans: Always use an AbortController to cancel in-flight requests in your useEffect cleanup function. Without this, the component will attempt to update state after unmounting, causing the classic React warning about updating state on an unmounted component, and potentially causing memory leaks.

6. Is it ever appropriate to silently swallow API errors without user feedback?

Ans: Only for non-critical background operations where failure has no impact on the user's task - for example, firing an analytics event or pre-fetching secondary content. For any operation the user explicitly triggered or depends on, always provide feedback. Silent failures destroy user trust.

7. How should I handle errors in React Server Components (Next.js App Router)?

Ans: In Next.js App Router, use the error.tsx file convention to define error boundaries per route segment. For server-side data fetching, use try/catch in async server components and return appropriate fallback UI. The notFound() function handles 404 cases, while the error.tsx boundary handles unexpected errors.

8. How do I test loading and error states in React components?

Ans: Use Mock Service Worker (MSW) to intercept API calls in tests without mocking fetch directly. MSW allows you to simulate slow responses (for loading state tests), 4xx/5xx error responses (for error state tests), and successful responses - giving you realistic integration test coverage of all three states.

9. Conclusion.

Handling API errors and loading states cleanly is not a nice-to-have - it is the baseline of professional React development. Every layer described in this article serves a specific purpose in a complete, user-respecting data fetching strategy:

Explicit state modeling ensures loading, error, and success are always accounted for - never left implicit.
Skeleton screens reduce perceived loading time by orienting users to the page structure before content arrives.
Error classification provides users with actionable, context-specific messages rather than generic failure notices.
Custom hooks centralize data fetching logic and eliminate repetition across components.
Retry logic and request cancellation add resilience and prevent memory leaks in production environments.
React Query and Axios interceptors provide production-grade abstractions for complex data fetching scenarios.

React provides all the primitives you need. The responsibility lies with developers to compose them thoughtfully, test all three states rigorously, and treat error handling as a first-class feature rather than an afterthought.

The best UX is invisible - a user who never sees a cryptic error message, never stares at a blank screen, and always feels in control is experiencing excellent error handling. That invisibility is the mark of a truly polished React application.

About the Author:Abodh is a PHP and Laravel Developer at AddWeb Solution, skilled in MySQL, REST APIs, JavaScript, Git, and Docker for building robust web applications.

Data Fetching Strategies in Next.js - SSR, SSG, ISR, and RSC

Vatsal Acharya — Mon, 20 Apr 2026 10:46:48 +0000

“Performance is not a feature - it’s the foundation. Next.js gives you the tools to build it right.”

Key Takeaways

Next.js provides multiple data fetching strategies depending on performance and freshness needs.
SSR fetches data on every request and is best for dynamic content.
SSG generates pages at build time, making it extremely fast.
ISR updates static pages after deployment without full rebuilds.
RSC (React Server Components) is the modern default in App Router.
Caching in Next.js is controlled using fetch options like cache and revalidate.
Real-world apps use a combination of SSR, SSG, ISR, and RSC - not just one.

Index

Why data fetching strategy matters
Quick comparison table
Server-Side Rendering (SSR)
Static Site Generation (SSG)
- 4b Incremental Static Regeneration (ISR)
React Server Components (RSC)
App Router vs Pages Router
Caching in App Router
Real-world app architecture
Common mistakes
Stats
Interesting Facts
FAQs
Summary
Conclusion

Introduction

Why does data fetching strategy actually matter?

In a classic React app, data fetching is simple: useEffect fires after the component mounts, you hit an API, and update state.

Easy to reason about - but there’s a problem:
The user sees a blank or loading screen until JavaScript executes and the fetch completes.

For small apps, this is fine.
At scale, it becomes a serious UX and SEO issue.

How Next.js Solves This

“Modern web development is not about fetching data - it’s about fetching it intelligently.”

Next.js lets you decide:
Where and when data should be fetched

Each strategy is a tradeoff between:

Freshness
Performance
Server cost
Complexity

Mental Model
Think of it as a spectrum:

Fully Dynamic → SSR
Fully Static → SSG
In Between → ISR + RSC

Quick Reference - All Strategies at a Glance

Important Note
RSC is not a replacement for SSR, SSG, or ISR.
It’s a new rendering model that can behave like any of them.

Strategy 01

Server-Side Rendering (SSR)

When a request comes in:
Next.js fetches data on the server before sending HTML

Pages Router Example

export async function getServerSideProps(context) {
 const { req } = context
 oop-
 const session = await getSession(req)

 if (!session) {
   return {
     redirect: {
       destination: '/login',
       permanent: false
     }
   }
 }

 const res = await fetch(`https://api.example.com/users/${session.userId}`)
 const user = await res.json()

 return {
   props: { user }
 }
}

Key Behavior

Runs on every request
Full HTML is returned
No loading state on client

When to Use SSR

User-specific content
Authentication logic
Real-time data
Accessing cookies/headers

When NOT to Use SSR

Same data for all users
Rarely changing content
Performance-sensitive pages

Important
SSR adds latency - your API speed = your page speed.

Strategy 02

Static Site Generation (SSG)

SSG generates pages at build time and serves static HTML.

Example

export async function getStaticProps() {
 const res = await fetch('https://api.example.com/posts')
 const data = await res.json()

 return {
   props: { data }
 }
}

Dynamic Routes Example

export async function getStaticPaths() {
 const res = await fetch('https://api.example.com/posts')
 const posts = await res.json()

 return {
   paths: posts.map(post => ({
     params: { slug: post.slug }
   })),
   fallback: false
 }
}

When to Use SSG

Blogs
Docs
Landing pages

Tradeoff

Very fast
Not real-time

Strategy 03

Incremental Static Regeneration (ISR)

ISR = SSG + automatic updates

How It Works

Serve static page
After interval → regenerate in background
Next request gets fresh page

Example

export async function getStaticProps() {
 const res = await fetch('https://api.example.com/products')
 const products = await res.json()

 return {
   props: { products },
   revalidate: 60
 }
}

Key Insight

Revalidation only happens when a request comes
No traffic = no update

On-Demand ISR (Better Approach)

export default async function handler(req, res) {
 if (req.headers['x-webhook-secret'] !== process.env.WEBHOOK_SECRET) {
   return res.status(401).json({ message: 'Unauthorized' })
 }

 const { slug } = req.body

 await res.revalidate(`/products/${slug}`)

 return res.json({ revalidated: true })
}

When to Use ISR

Product pages
News
CMS-driven content

Strategy 04 (Modern Default)

React Server Components (RSC)

“RSC changes the game: less JavaScript, better performance, cleaner architecture.”

In App Router:
Components run on the server by default

Example

async function getProducts() {
 const res = await fetch('https://api.example.com/products', {
   next: { revalidate: 60 }
 })

 return res.json()
}

export default async function Page() {
 const products = await getProducts()

 return (
   <div>
     {products.map(p => (
       <p key={p.id}>{p.name}</p>
     ))}
   </div>
 )
}

Controlling Behavior

fetch(url, { cache: 'force-cache' }) // SSG
fetch(url, { cache: 'no-store' }) // SSR
fetch(url, { next: { revalidate: 60 } }) // ISR

Key Benefits

No useEffect
No client-side fetching
Smaller JS bundle

Important Rule
Client components cannot import server components
Data flows server → client

Architecture

App Router vs Pages Router

Pages Router

getServerSideProps / getStaticProps
Page-level fetching
Older system

App Router

Async components
Component-level fetching
Server-first approach
Supports streaming App Router is the future

Deep Dive

Caching in App Router

There are 4 cache layers:

Common Issue

“Why is my data not updating?”
Usually due to Router cache

Fix

router.refresh()

Revalidation Example

import { revalidateTag } from 'next/cache'
revalidateTag('products')

Production Patterns

Real-World Architecture

E-commerce

Homepage → SSG
Product Page → ISR
Cart → SSR
Layout → RSC

SaaS

Landing → SSG
Dashboard → SSR
Docs → ISR

Real apps use combination of strategies

“The best data fetching strategy is not SSR or SSG - it’s choosing the right one at the right time.”

Anti-Patterns

Common Mistakes

1. Using SSR everywhere
Expensive + slow
Use ISR instead

2. Ignoring server/client boundary
Causes runtime errors

3. No error handling
Can crash entire page

4. Fetching in client unnecessarily
Adds JS + loading delay

5. Misunderstanding ISR timing
Low traffic = stale data

Stats

According to Vercel, static generation can significantly improve performance by serving pre-rendered pages from a CDN, reducing server computation.Source: https://nextjs.org/docs/pages/building-your-application/rendering/static-site-generation
Next.js has millions of weekly downloads and is one of the most widely used React frameworks.Source: https://www.npmjs.com/package/next
Next.js is used by companies like Netflix, TikTok, and Hulu for high-performance applications.Source: https://nextjs.org/showcase

Interesting Facts

Next.js was created and is maintained by Vercel.Source: https://nextjs.org
Incremental Static Regeneration (ISR) was introduced in Next.js 9.5.Source: https://nextjs.org/blog/next-9-5
React Server Components (RSC) became stable with the App Router in Next.js 13.Source: https://nextjs.org/blog/next-13
Next.js enables full-stack development by combining frontend and backend capabilities in a single framework.Source: https://nextjs.org/docs

FAQ

1. Is SSR outdated?
No - it’s still essential for dynamic and user-specific data.

2. Is RSC replacing SSR/SSG?
No - it enhances them and gives more flexibility.

3. Can we mix all strategies?
Yes - and that’s the recommended approach.

4. Which is best for SEO?
SSG and SSR both are great for SEO.

5. Can ISR work with dynamic routes?
Yes

6. Where to store API keys?
Server-side only

7. App Router or Pages Router?
New projects → App Router

8. How to avoid waterfall fetches?
Use RSC

Summary

The Decision Tree

Ask:
Does data change per user?

Yes → SSR / RSC (no-store) Does data rarely change?
Yes → SSG Does it update periodically?
Yes → ISR Using App Router?
Use RSC + fetch control

Final Insight

Use Server Components for data
Use Client Components for interactivity
Use ISR for scalability

Conclusion

Data fetching in Next.js is not about memorizing functions…
It’s about choosing the right strategy at the right time.

Use SSR for dynamic data
Use SSG for static content
Use ISR for balance
Use RSC for modern optimization

Once you understand this:

Your apps become faster
Your architecture becomes scalable
Your performance improves significantly

About the Author:Vatsal is a web developer at AddWebSolution. Building web magic with Laravel, PHP, MySQL, Vue.js & more.

Docker Image with Multi-Stage Builds & Docker Images Optimization

Rajan Vavadia — Wed, 15 Apr 2026 08:24:49 +0000

“Docker is not a virtualization technology. It is an application delivery technology.” - Mike Coleman (Docker)

Introduction
Overview: Multi-Stage Build Strategy (Builder + Production)
Stage 1: Builder - Compile Extensions, Install Tools & Dependencies
Stage 2: Production - Minimal Runtime Image
The .dockerignore File
Practical Setup (Step-by-step)
Quotes
FAQs
Key Takeaways
Conclusion

1. Introduction

This document explains how to build a production-ready PHP 8.4-FPM Docker image using a multi-stage Dockerfile. The image ships with all the PHP extensions, CLI tools (Composer, WP-CLI, Drush, Drupal Console), and Node.js needed for WordPress and Drupal projects - while keeping the final image lean and secure.

The approach uses a two-stage build:

Stage 1 (Builder): Compiles PHP extensions, installs development tools, and downloads CLI utilities.
Stage 2 (Production): Starts from a clean php:8.4-fpm base, copies only the compiled artifacts and runtime libraries, applies security hardening, and runs as a non-root user.

Why multi-stage?

A single-stage Dockerfile that compiles extensions and installs build tools leaves behind compilers, header files, and package caches that bloat the image and increase the attack surface. Multi-stage builds solve this by discarding everything that is not needed at runtime.

2. Overview: Multi-Stage Build Strategy (Builder + Production)

Stage 1 (Builder) starts from php:8.4-fpm and installs: - 20+ PHP extensions using install-php-extensions (handles build dependencies and cleanup internally). - Composer, WP-CLI, Drush, and Drupal Console. - Node.js 20.x for front-end tooling.

Stage 2 (Production) starts from a fresh php:8.4-fpm and: - Copies compiled extension .so files and their .ini configs from the builder. - Copies CLI binaries (Composer, WP-CLI, Drush, Drupal Console, Node.js). - Installs only the runtime shared libraries needed by the extensions. - Applies OPcache tuning and PHP security settings. - Creates a non-root user (appuser) for PHP-FPM. - Add a health check.

Why separate stages?

Smaller image: Build tools (gcc, make, autoconf, header files) are discarded. Only runtime libraries remain.
Faster pulls and deploys: Less data to transfer across registries and hosts.
Reduced attack surface: No compilers or dev packages in production.
Clearer troubleshooting: Build failures are isolated to Stage 1; runtime issues are isolated to Stage 2.

3. Stage 1: Builder - Compile Extensions, Install Tools & Dependencies

3.1 Base Image

FROM php:8.4-fpm AS builder
We use the official php:8.4-fpm image (based on Debian 13 Trixie) as the builder base. This gives us the PHP source, phpize, and docker-php-ext-install out of the box.

3.2 PHP Extension Installation

Single tool for all PHP extensions (handles build deps + cleanup internally)
COPY --from=mlocati/php-extension-installer /usr/bin/install-php-extensions /usr/bin/

Install all PHP extensions in one layer
RUN install-php-extensions \
bcmath \
bz2 \
calendar \
exif \
gd \
gmp \
imagick \
intl \
mailparse \
mongodb \
mysqli \
opcache \
pcntl \
pdo \
pdo_mysql \
pdo_pgsql \
soap \
sockets \
sodium \
xsl \
zip

Why install-php-extensions?

It automatically installs the OS-level build dependencies (e.g., libpng-dev, libicu-dev), compiles the extension, and removes the build dependencies - all in one step.
It replaces the manual apt-get install && docker-php-ext-configure && docker-php-ext-install && apt-get purge pattern.
It supports PECL extensions (like imagick, mongodb, mailparse) with the same syntax.
We use COPY --from=mlocati/php-extension-installer to pull the binary directly from the tool’s official image, without adding another FROM stage.

Extensions included and why:

3.3 CLI Tools Installation
Install Composer, WP-CLI, Drush, and Drupal Console in one layer
RUN apt-get update && apt-get install -y --no-install-recommends \
git \
unzip \
&& rm -rf /var/lib/apt/lists/* \
Composer
&& curl -sSL https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer \
WP-CLI
&& curl -sSL https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar -o /usr/local/bin/wp \
&& chmod +x /usr/local/bin/wp \
Drupal Console
&& curl -sSL https://drupalconsole.com/installer -o /usr/local/bin/drupal \
&& chmod +x /usr/local/bin/drupal

Composer: PHP dependency manager. Installed globally at /usr/local/bin/composer.
WP-CLI: WordPress command-line interface for managing WordPress installations.
Drupal Console: CLI tool for generating boilerplate code and interacting with Drupal.
git and unzip are needed by Composer to fetch packages; they are installed here but not carried over to the production stage.

3.4 Drush Installation

ENV COMPOSER_HOME=/usr/local/share/composer
RUN composer global require drush/drush:8.* --no-interaction --prefer-dist
Drush (Drupal Shell) is installed globally via Composer. COMPOSER_HOME is set explicitly so the entire vendor directory can be copied to the production stage.

3.5 Node.js Installation

RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
&& apt-get install -y --no-install-recommends nodejs \
&& rm -rf /var/lib/apt/lists/*
Node.js 20.x (LTS) is installed for front-end build tools (npm scripts, asset compilation). NVM is intentionally avoided - a single global Node.js installation is simpler and more predictable in a container.

“Build once, run anywhere - but make sure what you build is only what you need.” - Container best practice principle

4. Stage 2: Production - Minimal Runtime Image

4.1 Fresh Base and Labels

FROM php:8.4-fpm AS production

LABEL maintainer="AddWeb Solutions" \
description="PHP 8.4-FPM production image with WordPress/Drupal tooling"
A fresh php:8.4-fpm base - none of the builder’s build tools, caches, or temp files exist here.

4.2 Copying Artifacts from Builder

Copy PHP extensions and their configs from builder
COPY --from=builder /usr/local/lib/php/extensions/ /usr/local/lib/php/extensions/
COPY --from=builder /usr/local/etc/php/conf.d/ /usr/local/etc/php/conf.d/

Copy CLI tools from builder
COPY --from=builder /usr/local/bin/composer /usr/local/bin/composer
COPY --from=builder /usr/local/bin/wp /usr/local/bin/wp
COPY --from=builder /usr/local/bin/drupal /usr/local/bin/drupal
COPY --from=builder /usr/local/share/composer /usr/local/share/composer

Copy Node.js from builder
COPY --from=builder /usr/bin/node /usr/bin/node
COPY --from=builder /usr/bin/npm /usr/bin/npm
COPY --from=builder /usr/bin/npx /usr/bin/npx
COPY --from=builder /usr/lib/node_modules /usr/lib/node_modules
COPY --from=builder selectively pulls only the compiled .so files, .ini configs, and CLI binaries. Everything else (compilers, header files, build caches) is left behind.

4.3 Runtime Libraries

RUN apt-get update && apt-get install -y --no-install-recommends \
# Runtime libs required by PHP extensions
libbz2-1.0 \
libfreetype6 \
libgmp10 \
libicu76 \
libjpeg62-turbo \
libmagickwand-7.q16-10 \
libavif16 \
libpng16-16 \
libpq5 \
libxslt1.1 \
libzip5 \
# Essential runtime utilities only
cron \
curl \
default-mysql-client \
ffmpeg \
sendmail \
supervisor \
unzip \
sqlite3 \
&& apt-get purge -y --auto-remove -o APT::AutoRemove::RecommendsImportant=false \
&& rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*

Key points:

Runtime libs only: We install the shared libraries (.so files) that the compiled PHP extensions link against. These are the -dev-less counterparts (e.g., libpng16-16 not libpng-dev).
Debian Trixie package names: Since php:8.4-fpm is based on Debian 13 (Trixie), some package names differ from Bookworm (e.g., libicu76 instead of libicu72, libmagickwand-7.q16-10 instead of libmagickwand-6.q16-6, libzip5 instead of libzip4).
Essential utilities: cron (scheduled tasks), curl (health checks, API calls), default-mysql-client (database operations), ffmpeg (media processing), sendmail (email delivery), supervisor (process management), unzip, sqlite3.
Cleanup: apt-get purge --auto-remove removes packages that were pulled in only as install dependencies, and rm -rf /var/lib/apt/lists/* clears the package cache.

Runtime libraries mapped to extensions:

4.4 Drush Symlink

ENV COMPOSER_HOME=/usr/local/share/composer
RUN ln -s /usr/local/share/composer/vendor/bin/drush /usr/local/bin/drush
Makes drush available in $PATH without modifying the PATH variable.

4.5 OPcache Tuning

RUN { \
echo 'opcache.memory_consumption=128'; \
echo 'opcache.interned_strings_buffer=8'; \
echo 'opcache.max_accelerated_files=4000'; \
echo 'opcache.revalidate_freq=60'; \
echo 'opcache.fast_shutdown=1'; \
echo 'opcache.enable_cli=1'; \
echo 'opcache.validate_timestamps=0'; \
} > /usr/local/etc/php/conf.d/opcache-recommended.ini

validate_timestamps=0 is a production optimization - PHP never starts the filesystem to check if files have changed. When you deploy new code, restart PHP-FPM to pick up the changes.

4.6 Security Hardening

RUN { \
echo 'expose_php=Off'; \
echo 'display_errors=Off'; \
echo 'log_errors=On'; \
echo 'error_log=/dev/stderr'; \
echo 'allow_url_fopen=Off'; \
} > /usr/local/etc/php/conf.d/security.ini

4.7 Non-Root User

RUN groupadd -g 1000 appuser && useradd -u 1000 -g appuser -m appuser

WORKDIR /var/www/html
RUN chown -R appuser:appuser /var/www/html
Running PHP-FPM as a non-root user reduces the blast radius if the application is compromised. The appuser (UID 1000) owns the web root.

4.8 Health Check

HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
CMD php-fpm-healthcheck || kill -0 $(cat /var/run/php-fpm.pid 2>/dev/null) || exit 1
Docker checks every 30 seconds whether PHP-FPM is responding. After 3 consecutive failures, the container is marked unhealthy, and orchestrators (Docker Compose, Swarm, Kubernetes) can restart it.

4.9 Expose and CMD

EXPOSE 9000

CMD ["php-fpm"]
PHP-FPM listens on port 9000 (FastCGI). A reverse proxy (Nginx, Apache, Caddy) forwards requests to this port.

5. The .dockerignore File

.git
.github
.gitignore
.md
LICENSE
docker-compose.yml
.env*
.vscode
.idea
node_modules
vendor
.docker

The .dockerignore prevents unnecessary files from being sent to the Docker build context. This speeds up builds and avoids leaking secrets (.env files) or bloating the image with node_modules or vendor directories.

6. Practical Setup (Step-by-step)

6.1 Build the Image

docker build -t php8.4-multistage --target production .
The --target production flag tells Docker to stop at the production stage and discard the builder. If --target is omitted, Docker builds up to the last stage (which is already in production in this Dockerfile).

6.2 Run the Container

docker run -d \
--name php-app \
-p 9000:9000 \
-v ./src:/var/www/html \
php8.4-multistage
Mount your application source code at /var/www/html. PHP-FPM will serve it on port 9000.

6.3 Pair with Nginx (docker-compose example)

version: '3.8'

services:
php:
build:
context: .
target: production
volumes:
- ./src:/var/www/html
networks:
- app-network

nginx:
image: nginx:alpine
ports:
- "80:80"
volumes:
- ./src:/var/www/html
- ./nginx.conf:/etc/nginx/conf.d/default.conf
depends_on:
- php
networks:
- app-network

networks:
app-network:
driver: bridge

6.4 Verify Extensions

docker exec php-app php -m
This lists all loaded PHP modules. Confirm that gd, imagick, intl, opcache, pdo_mysql, etc., are all present.

6.5 Verify CLI Tools

docker exec php-app composer --version
docker exec php-app wp --version
docker exec php-app drush --version
docker exec php-app node --version
docker exec php-app npm --version

6.6 Check phpinfo

Create a phpinfo file
docker exec php-app bash -c "echo '<?php phpinfo();' > /var/www/html/info.php"

Quick test with built-in server
docker exec -d php-app php -S 0.0.0.0:8085 -t /var/www/html
Open http://localhost:8085/info.php in your browser to see the full PHP configuration. Remove info.php after testing - never leave it exposed in production.

6.7 Common Improvements (optional)

Use BuildKit cache mounts to speed up repeated builds: RUN --mount=type=cache,target=/var/cache/apt apt-get update && ...
Pin the PHP version (e.g., php:8.4.18-fpm) for reproducible builds instead of using the floating 8.4-fpm tag.
Add a .env-based PHP config layer for settings that vary between environments (memory_limit, upload_max_filesize).
Use Docker Compose profiles to add Xdebug only in development (avoid Xdebug in production).
Scan the image with Trivy or Docker Scout for vulnerability reporting before pushing to a registry.

“The art of simplicity is a puzzle of complexity.” - Douglas Horton

8. FAQs

Q1. Why use multi-stage builds instead of a single Dockerfile?
A. A single-stage build carries compilers, dev headers, and package caches into the final image. Multi-stage builds discard all of that, resulting in a smaller, more secure image.

Q2. Why install-php-extensions instead of docker-php-ext-install? A. install-php-extensions handles OS dependency installation, extension compilation, and cleanup automatically. It also supports PECL extensions (imagick, mongodb, mailparse) with the same syntax, eliminating the need for separate pecl install commands.

Q3. Why is the base image Debian Trixie? Can I use Bookworm or Alpine?
A. The official php:8.4-fpm tag is built on Debian 13 (Trixie) as of 2025. If you need Bookworm, use php:8.4-fpm-bookworm. Alpine (php:8.4-fpm-alpine) is smaller but uses musl libc, which can cause compatibility issues with some extensions (notably ImageMagick).

Q4. Why are the runtime library package names different from older guides?
A. Debian Trixie renamed several packages as part of the 64-bit time_t transition and library version bumps. For example: libicu72 became libicu76, libmagickwand-6.q16-6 became libmagickwand-7.q16-10, and libzip4 became libzip5. Always verify package names against the base image’s Debian version.

Q5. How do I find the correct runtime library names if I change the base image?
A. Run a temporary container and use ldd to check for missing libraries:
docker run --rm your-image bash -c \
"for so in /usr/local/lib/php/extensions//.so; do \
ldd \$so 2>/dev/null | grep 'not found'; \
done"
Then search for the correct package with apt-cache search .

Q6. What does validate_timestamps=0 mean for deployments?
A. OPcache will never check if PHP files on disk have changed. This avoids filesystem stat calls on every request (faster). The tradeoff: after deploying new code, you must restart PHP-FPM (docker restart ) to pick up changes.

Q7. Why create a non-root user?
A. Running as root inside a container means a compromised application has full control over the container filesystem. A non-root user limits the damage.

Q8. Can I add Xdebug for local development?
A. Yes, but do not include it in the production image. Use a separate development stage or a Docker Compose override file that installs Xdebug on top of the production image.

9. Key Takeaways

Multi-stage builds separate build-time complexity from runtime simplicity.
install-php-extensions eliminates the manual dance of installing dev packages, compiling, and cleaning up.
Always match runtime library package names to the base image’s Debian version (Trixie uses libicu76, libzip5, libmagickwand-7.q16-10, libavif16).
OPcache with validate_timestamps=0 is a significant performance win for production.
Security hardening (expose_php=Off, display_errors=Off, allow_url_fopen=Off) should be the default, not an afterthought.
Non-root user + health check + .dockerignore round out a production-ready setup.
Use ldd to diagnose missing shared libraries when extensions fail to load.

10. Conclusion

This multi-stage Dockerfile provides a clean, repeatable way to build a PHP 8.4-FPM production image with everything needed for WordPress and Drupal projects. The builder stage handles all the heavy lifting - compiling extensions, installing Composer, WP-CLI, Drush, Drupal Console, and Node.js - while the production stage starts fresh and copies only what is needed at runtime. Combined with OPcache tuning, security hardening, a non-root user, and a health check, the result is an image that is smaller, faster, and more secure than a traditional single-stage build. When paired with Nginx via Docker Compose, it forms a solid foundation for deploying PHP applications in any environment.

About the Author:Rajan is a DevOps Engineer at AddWebSolution, specializing in automation infrastructure, Optimize the CI/CD Pipelines and ensuring seamless deployments.

Architecting Large-Scale Next.js Applications (Folder Structure, Patterns, Best Practices)

Mayank Goyal — Mon, 13 Apr 2026 10:25:46 +0000

“Good architecture makes the system easy to understand; great architecture makes it hard to break.”

Key Takeaways

Feature-based architecture is critical
Separate UI, logic, and data layers
Prefer server components for performance
Centralize API logic
Use scalable state management
Optimize early, not later

Index

Introduction
Why Architecture Matters
Core Principles of Scalable Architecture
Advanced Folder Structure (Enterprise-Level)
Architectural Patterns (Deep Dive)
State Management at Scale
Data Fetching & API Layer Design
Authentication & Authorization Architecture
Performance Optimization (Advanced)
Error Handling & Logging
Testing Strategy (Production-Ready)
Dev Experience & Code Quality
Deployment & Infrastructure Strategy
Real-World Example (Enterprise Dashboard)
Interesting Facts
Stats
FAQ’s
Conclusion

Introduction

Building small Next.js apps is easy. Scaling them to support millions of users, multiple developers, and complex business logic is not.
Large-scale applications require:

Clean architecture
Predictable structure
Separation of concerns
Strong conventions Next.js (especially App Router) provides powerful primitives, but it does NOT enforce architecture, that’s your responsibility.

This guide gives you a production-grade blueprint.

Why Architecture Matters

At scale, poor architecture leads to:

Tight coupling between components
Duplicate logic across features
Slow builds & performance bottlenecks
Difficult onboarding for new developers

Good architecture enables:

Independent feature development
Faster debugging
Better scalability
Easier refactoring

Core Principles of Scalable Architecture

1. Separation of Concerns
Divide responsibilities:

UI → components
Logic → hooks/services
Data → API layer

2. Feature Isolation
Each feature should be self-contained.
Think like mini-apps inside your app.

3. Single Responsibility Principle
Each file/module should do one thing well.

4. Dependency Direction
Components depend on hooks
Hooks depend on services
Services depend on APIs
NOT the other way around.

5. Scalability First Mindset
Design for scale even if you’re small today.

Advanced Folder Structure (Enterprise-Level)

src/
│
├── app/                         # Next.js App Router
│   ├── (public)/
│   ├── (auth)/
│   ├── dashboard/
│   │   ├── layout.tsx
│   │   ├── page.tsx
│
├── features/                    # Feature modules (CORE)
│   ├── auth/
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── services/
│   │   ├── api/
│   │   ├── store/
│   │   └── types.ts
│   │
│   ├── products/
│   ├── orders/
│   └── users/
│
├── shared/                      # Cross-feature reusable code
│   ├── components/
│   ├── hooks/
│   ├── utils/
│   └── constants/
│
├── core/                        # App-level logic
│   ├── config/
│   ├── providers/
│   ├── middleware/
│   └── guards/
│
├── services/                    # Global services (rare)
├── lib/                         # Low-level utilities
├── types/                       # Global types
├── styles/
└── tests/

“Fetching data is easy. Fetching it efficiently is architecture.”

Key Insight
Avoid “global chaos” folders like components/ for everything
Prefer feature-based grouping

Architectural Patterns (Deep Dive)

1. Feature-Based Architecture (MOST IMPORTANT)
Each feature owns:
UI
logic
API calls
state

features/products/
    components/
    hooks/
    services/
    store/

2. Layered Architecture

UI Layer (Components)
↓
Hooks Layer (Business Logic)
↓
Service Layer (API Calls)
↓
API Layer (External systems)

3. Server vs Client Component Strategy

Example:

// Server Component
export default async function Page() {
  const data = await getProducts();
  return <ProductsClient data={data} />;
}

4. Smart vs Dumb Components
Smart → fetch + logic
Dumb → UI only

5. Composition Pattern
Avoid inheritance. Use composition:

<Card>
  <ProductInfo />
</Card>

State Management at Scale

When NOT to use global state

Static data
Server-fetched data

Recommended Strategy

Example (Zustand Advanced)

import { create } from 'zustand';
export const useCartStore = create((set) => ({
  items: [],
  addItem: (item) =>
    set((state) => ({ items: [...state.items, item] })),
  clearCart: () => set({ items: [] })
}));

Data Fetching & API Layer Design

Bad Practice
Calling fetch directly in components everywhere.

Good Practice

features/products/
  services/productService.ts

export const getProducts = async () => {
  const res = await fetch('/api/products');
  return res.json();
};

“Every unnecessary render is a tax on your use.”

Caching Strategy

Authentication & Authorization Architecture

Recommended Setup

Middleware for route protection
Server-side session validation
Role-based access Example:

// middleware.ts
export function middleware(req) {
  const token = req.cookies.get('token');
  if (!token) return Response.redirect('/login');
}

Performance Optimization (Advanced)

Techniques

Code splitting (dynamic imports)
Partial hydration
Edge rendering
Image optimization
Memoization

Example

const Chart = dynamic(() => import('./Chart'), {
  ssr: false
});

Error Handling & Logging

Centralized Error Handling

export const handleError = (error) => {
  console.error(error);
};

Logging Tools

Sentry
LogRocket

Testing Strategy (Production-Ready)

Example

test('adds item to cart', () => {
  const store = useCartStore.getState();
  store.addItem({ id: 1 });
  expect(store.items.length).toBe(1);
});

Dev Experience & Code Quality

ESLint + Prettier
Husky (pre-commit hooks)
Strict TypeScript
Absolute imports (@/features/...)

Deployment & Infrastructure Strategy

Recommended Stack

Hosting → Vercel
DB → PostgreSQL
CDN → Cloudflare
Monitoring → Sentry

Scaling Tips

Use Edge Functions
Optimize bundle size
Enable caching

Real-World Example (Enterprise Dashboard)

Structure

features/dashboard/
   components/
      StatsCard.tsx
   hooks/
      useStats.ts
   services/
      dashboardService.ts

Service

export const fetchStats = async () => {
  const res = await fetch('/api/stats');
  return res.json();
};

Hook

export const useStats = () => {
  const [stats, setStats] = useState(null);

  useEffect(() => {
    fetchStats().then(setStats);
  }, []);

  return stats;
};

Component

export const StatsCard = ({ data }) => {
  return <div>{data.totalUsers}</div>;
};

Page

export default function DashboardPage() {
  const stats = useStats();

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

  return <StatsCard data={stats} />;
}

Interesting Facts

Next.js App Router defaults to Server Components.Source: https://nextjs.org/docs/app/building-your-application/rendering/server-components
Middleware runs at the Edge.Source: https://nextjs.org/docs/pages/api-reference/file-conventions/middleware
File-based routing reduces ~40% boilerplate.Source: https://nextjs.org/docs/app/building-your-application/routing
Built-in optimizations replace many libraries.Source: https://nextjs.org/docs/architecture
ISR allows hybrid static + dynamic pages.Source: https://nextjs.org/docs/pages/building-your-application/rendering/incremental-static-regeneration

Stats

Next.js is one of the fastest-growing React frameworks and is widely adopted for production-grade applications. Source: https://nextjs.org/showcase
Next.js has 120,000+ stars on GitHub, reflecting its strong developer adoption and community support. Source: https://github.com/vercel/next.js
According to the State of JS survey, Next.js consistently ranks among the top frameworks in developer satisfaction and usage. Source: https://stateofjs.com/
Vercel, the company behind Next.js, serves billions of requests per week across applications deployed on its platform. Source: https://vercel.com/customers
Next.js enables hybrid rendering (SSR, SSG, ISR), which improves performance and scalability for modern web applications. Source: https://nextjs.org/docs/pages/building-your-application/rendering
File-based routing in Next.js simplifies development by automatically mapping files to routes, reducing manual configuration. Source: https://nextjs.org/docs/app/building-your-application/routing

FAQ’s

Q1. Is Redux necessary?
No. Use Zustand unless you need complex workflows.

Q2. How to organize large teams?

Feature ownership
Code reviews
Clear folder structure

Q3. Should I use monorepo?
Yes, for multi-app systems (Nx / Turborepo).

Q4. Where to keep reusable components?
shared/components

Q5. What is the biggest mistake?
Mixing everything in global folders.

Conclusion

Scaling a Next.js application is more about architecture than code. The difference between a messy app and a scalable system lies in:

Structure
Discipline
Consistency By following feature-based design, layered architecture, and modern Next.js patterns, you can build applications that scale effortlessly with both users and teams.

About the Author:Mayank is a web developer at AddWebSolution, building scalable apps with PHP, Node.js & React. Sharing ideas, code, and creativity.

ELK Stack Setup for Centralized Log Management & Monitoring

Rajan Vavadia — Wed, 08 Apr 2026 11:42:01 +0000

“The goal is to turn data into information, and information into insight.” - Carly Fiorina

Introduction
Stage 1: Elasticsearch - The Search & Storage Engine
Stage 2: Logstash - The Data Processing Pipeline
Stage 3: Kibana - The Visualization Layer
Stage 4: Filebeat - The Lightweight Log Shipper
Connecting the Pieces - End-to-End Data Flow
Practical Setup (Step-by-step)
Troubleshooting Common Issues
Quotes
FAQs
Key Takeaways
Conclusion

1. Introduction

When your application runs on a single server, tailing a log file is enough. When it runs across multiple servers, containers, or microservices - you need centralized logging. Scattered logs across dozens of servers make debugging slow, error correlation impossible, and incident response reactive instead of proactive.

This guide walks through setting up a production-ready ELK stack (Elasticsearch, Logstash, Kibana) with Filebeat for centralized log collection, processing, and visualization. The setup covers a real-world scenario: a Java Spring Boot application running on one server, with the ELK stack on a separate server.

The approach uses a four-component architecture:

Filebeat (Application Server): Lightweight agent that tails log files and ships them to Logstash.
Logstash (ELK Server): Receives raw logs, parses and transforms them, and forwards structured data to Elasticsearch.
Elasticsearch (ELK Server): Stores, indexes, and makes logs searchable in near real-time.
Kibana (ELK Server): Web UI for searching, visualizing, and building dashboards from log data.

Why centralized logging?
Manually SSH-ing into each server and grepping through log files does not scale. Centralized logging solves this by aggregating all logs into a single searchable location.
You get:

Single pane of glass for all application and infrastructure logs.
Real-time search across millions of log entries in milliseconds.
Correlation of events across services and servers by timestamp.
Alerting on error patterns before users report issues.
Retention and compliance with configurable index lifecycle policies.

Component Responsibilities

Why separate servers?

- Resource isolation: Elasticsearch is memory-hungry. Running it on the application server competes with your app for RAM and CPU.
- Independent scaling: You can scale the ELK server (more RAM, bigger disk) without touching production application servers.
- Security boundary: The ELK server can sit in a private subnet, accessible only to internal services and authorized users.

2. Stage 1: Elasticsearch - The Search & Storage Engine

2.1 What is Elasticsearch?
Elasticsearch is a distributed search and analytics engine built on Apache Lucene. In the ELK stack, it serves as the storage and search backend - every log line that Logstash processes ends up as a document in an Elasticsearch index.

2.2 Installation
Import the Elasticsearch GPG key
wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo gpg --dearmor -o /usr/share/keyrings/elasticsearch-keyring.gpg

Add the APT repository
echo "deb [signed-by=/usr/share/keyrings/elasticsearch-keyring.gpg] https://artifacts.elastic.co/packages/8.x/apt stable main" | sudo tee /etc/apt/sources.list.d/elastic-8.x.list

Install Elasticsearch
sudo apt-get update && sudo apt-get install -y elasticsearch

2.3 Configuration
The main configuration file is /etc/elasticsearch/elasticsearch.yml:
Cluster and node identity
cluster.name: my-cluster
node.name: node-1

Data and log paths
path.data: /var/lib/elasticsearch
path.logs: /var/log/elasticsearch

Network - bind to all interfaces for external access
network.host: 0.0.0.0
http.host: 0.0.0.0

Discovery - single node (no cluster formation)
discovery.type: single-node

Security - disable for internal/dev setups
xpack.security.enabled: false
xpack.security.enrollment.enabled: true
xpack.security.http.ssl:
enabled: false
xpack.security.transport.ssl:
enabled: false

Configuration settings explained:

Security note: xpack.security.enabled: false is acceptable for internal/development setups behind a firewall. For production environments exposed to the internet, always enable security with TLS certificates and user authentication.

2.4 Start and Enable
sudo systemctl daemon-reload
sudo systemctl enable elasticsearch
sudo systemctl start elasticsearch

2.5 Verify
curl http://localhost:9200
Expected response:
{
"name": "node-1",
"cluster_name": "my-cluster",
"version": {
"number": "8.x.x"
},
"tagline": "You Know, for Search"
}

2.6 Memory Considerations
Elasticsearch defaults to a 1GB heap (-Xms1g -Xmx1g). For production:

Set heap to 50% of available RAM, but never more than 31GB (to stay within compressed OOPs).
Edit /etc/elasticsearch/jvm.options.d/heap.options: -Xms2g -Xmx2g
Ensure the system has enough RAM for both the JVM heap and filesystem cache (Lucene relies heavily on OS page cache).

3. Stage 2: Logstash - The Data Processing Pipeline

3.1 What is Logstash?
Logstash is a server-side data processing pipeline that ingests data from multiple sources, transforms it, and sends it to Elasticsearch. It sits between Filebeat and Elasticsearch, adding structure to raw log lines.

3.2 Installation
sudo apt-get install -y logstash

3.3 Pipeline Configuration
Logstash pipelines are defined in /etc/logstash/conf.d/. Each pipeline has three sections: input, filter, and output.
Create /etc/logstash/conf.d/boardgame.conf:
input {
beats {
port => 5044
}
}

filter {
#Parse Spring Boot log format
grok {
match => { "message" => "%{TIMESTAMP_ISO8601:timestamp} %{LOGLEVEL:loglevel} %{GREEDYDATA:logmessage}" }
}
}

output {
elasticsearch {
hosts => ["localhost:9200"]
index => "boardgame-logs-%{+YYYY.MM.dd}"
}
}
Pipeline sections explained:

Input - Where data comes from:
input {
beats {
port => 5044
}
}

Filter - How data is transformed:
filter {
grok {
match => { "message" => "%{TIMESTAMP_ISO8601:timestamp} %{LOGLEVEL:loglevel} %{GREEDYDATA:logmessage}" }
}
}

The grok filter parses unstructured log lines into structured fields (timestamp, loglevel, logmessage). This enables filtering by log level in Kibana (e.g., show only ERROR logs).

Output - Where data goes:
output {
elasticsearch {
hosts => ["localhost:9200"]
index => "boardgame-logs-%{+YYYY.MM.dd}"
}
}

Why daily indices? Daily indices make retention management simple - delete old indices by date. They also improve search performance because Elasticsearch can skip entire indices when querying a specific time range.

3.4 Start and Enable
sudo systemctl daemon-reload
sudo systemctl enable logstash
sudo systemctl start logstash

3.5 Verify
Check if Logstash is listening on port 5044
sudo ss -tlnp | grep 5044

Check Logstash logs for pipeline startup
sudo journalctl -u logstash --no-pager -n 20
Look for: Pipeline started {"pipeline.id"=>"main"} in the logs.

4. Stage 3: Kibana - The Visualization Layer

4.1 What is Kibana?
Kibana is the web interface for the ELK stack. It connects to Elasticsearch and provides tools for searching logs (Discover), building visualizations (charts, graphs, maps), and creating dashboards for real-time monitoring.

4.2 Installation
sudo apt-get install -y kibana

4.3 Configuration
Edit /etc/kibana/kibana.yml:
Bind to all interfaces for external access
server.host: "0.0.0.0"

Connect to Elasticsearch over plain HTTP
elasticsearch.hosts: ["http://localhost:9200"]

Critical configuration points:

Common pitfall: If Elasticsearch has xpack.security.http.ssl.enabled: false but Kibana is configured with https:// in elasticsearch.hosts, Kibana will fail to connect with Unable to retrieve version information from Elasticsearch. Always match the protocol.

Settings to remove or comment out when SSL is disabled:
Comment out or remove these lines
elasticsearch.ssl.certificateAuthorities: [/path/to/ca.crt]
elasticsearch.username: "kibana_system"
elasticsearch.password: "pass"

4.4 Start and Enable
sudo systemctl daemon-reload
sudo systemctl enable kibana
sudo systemctl start kibana

Kibana takes 30–60 seconds to fully initialize.

4.5 Verify
curl http://localhost:5601/api/status

Expected: {"status":{"overall":{"level":"available"}}} - the level should be available, not unavailable.

4.6 Create a Data View
Once data is flowing, create a data view so Kibana knows which indices to query:

Open http://:5601 in a browser.
Navigate to Stack Management > Data Views (under Kibana section).
Click Create data view.
Fill in the fields:

Now go to Discover (under Analytics) to search and explore your logs.

4.7 AWS Security Group
If running on AWS EC2, ensure the security group allows inbound traffic:

Never expose port 9200 to the public internet unless Elasticsearch security is enabled with TLS and authentication.

“Logs are the immune system of your infrastructure - they tell you when something is wrong before it becomes a crisis.” - DevOps principle

5. Stage 4: Filebeat - The Lightweight Log Shipper

5.1 What is Filebeat?
Filebeat is a lightweight log shipper that runs on the application server. It tails log files, handles log rotation, tracks read positions (so it never sends duplicate lines), and ships logs to Logstash or Elasticsearch with minimal resource overhead.

5.2 Why Filebeat instead of sending directly to Logstash?

Filebeat decouples your application from the logging pipeline. If Logstash or Elasticsearch goes down, Filebeat queues events and retries automatically. Your application keeps writing to its log file without interruption.

5.3 Installation (on the Application Server)
Use the same Elastic repository
sudo apt-get update && sudo apt-get install -y filebeat

5.4 Configuration
Edit /etc/filebeat/filebeat.yml:
filebeat.inputs:

type: log enabled: true paths:
- /home/ubuntu/Boardgame/target/app.log multiline.pattern: '^\d{4}-\d{2}-\d{2}' multiline.negate: true multiline.match: after

output.logstash:
hosts: [":5044"]

processors:

add_host_metadata: when.not.contains.tags: forwarded
add_cloud_metadata: ~

logging.level: info

Configuration explained:
Input section:

Multiline settings (critical for Java/Spring Boot stack traces):

This ensures that a multi-line Java stack trace is treated as a single log event, not dozens of separate lines:
2026-03-11 06:37:55 ERROR Something went wrong
java.lang.NullPointerException
at com.example.Service.process(Service.java:42)
at com.example.Controller.handle(Controller.java:15)
Without multiline config, each line of the stack trace becomes a separate Elasticsearch document - making it impossible to correlate errors.

Output section:

Processors:

YAML formatting rules (common source of errors):

5.5 Start and Enable
Clear old registry to re-read files from the beginning
sudo rm -rf /var/lib/filebeat/registry

sudo systemctl daemon-reload
sudo systemctl enable filebeat
sudo systemctl start filebeat

5.6 Verify
Check Filebeat status
sudo systemctl status filebeat

Check logs - look for "Harvester started"
sudo journalctl -u filebeat --no-pager -n 20
Key indicators in the logs:

6. Connecting the Pieces - End-to-End Data Flow

6.1 The Complete Pipeline
[Spring Boot App]
│
│ writes logs to disk
▼
[/home/ubuntu/Boardgame/target/app.log]
│
│ Filebeat tails the file
▼
[Filebeat] ──── port 5044 ────► [Logstash]
│
│ grok filter parses log lines
▼
[Elasticsearch]
index: boardgame-logs-2026.03.11
│
│ Kibana queries the index
▼
[Kibana]
http://:5601

6.2 Verifying Each Link
Test each component in order, from bottom to top:

Elasticsearch is running and accessible
curl http://localhost:9200
Logstash is listening for Beats input
sudo ss -tlnp | grep 5044
Kibana can reach Elasticsearch
curl http://localhost:5601/api/status
Filebeat can reach Logstash (from application server)
telnet 5044
Data is actually in Elasticsearch
curl http://localhost:9200/_cat/indices?v | grep boardgame
Check document count
curl http://localhost:9200/boardgame-logs-*/_count

7. Practical Setup (Step-by-step)

7.1 Server Requirements

7.2 ELK Server Setup (in order)

Step 1: Add Elastic repository
wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo gpg --dearmor -o /usr/share/keyrings/elasticsearch-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/elasticsearch-keyring.gpg] https://artifacts.elastic.co/packages/8.x/apt stable main" | sudo tee /etc/apt/sources.list.d/elastic-8.x.list
sudo apt-get update

Step 2: Install all three components
sudo apt-get install -y elasticsearch logstash kibana

Step 3: Configure Elasticsearch
sudo nano /etc/elasticsearch/elasticsearch.yml
Set: network.host: 0.0.0.0
Set: discovery.type: single-node
Set: xpack.security.enabled: false
Set: xpack.security.http.ssl.enabled: false
Set: xpack.security.transport.ssl.enabled: false

Step 4: Configure Logstash pipeline
sudo nano /etc/logstash/conf.d/boardgame.conf
Add input (beats, port 5044), filter (grok), output (elasticsearch)

Step 5: Configure Kibana
sudo nano /etc/kibana/kibana.yml
Set: server.host: "0.0.0.0"
Set: elasticsearch.hosts: ["http://localhost:9200"]
Remove/comment any SSL certificate lines

Step 6: Start services
sudo systemctl enable elasticsearch logstash kibana
sudo systemctl start elasticsearch logstash kibana

7.3 Application Server Setup

Step 1: Install Filebeat
sudo apt-get install -y filebeat

Step 2: Configure Filebeat
sudo nano /etc/filebeat/filebeat.yml
Replace entire file with clean config (see Section 6.4)

Step 3: Clear registry and start
sudo rm -rf /var/lib/filebeat/registry
sudo systemctl enable filebeat
sudo systemctl start filebeat

7.4 Kibana Data View Setup

Verify data arrived in Elasticsearch
curl http://:9200/_cat/indices?v | grep boardgame
Then in the Kibana UI: 1. Stack Management > Data Views > Create data view 2. Name: Boardgame Logs, Index pattern: boardgame-logs-*, Timestamp: @timestamp 3. Save data view to Kibana 4. Go to Discover to explore your logs

7.5 Optional: Index Lifecycle Management

For production, configure automatic index cleanup to prevent disk from filling up:
Create an ILM policy that deletes indices older than 30 days
curl -X PUT "http://localhost:9200/_ilm/policy/boardgame-logs-policy" -H 'Content-Type: application/json' -d'
{
"policy": {
"phases": {
"hot": {
"actions": {
"rollover": {
"max_size": "5gb",
"max_age": "1d"
}
}
},
"delete": {
"min_age": "30d",
"actions": {
"delete": {}
}
}
}
}
}'

8. Troubleshooting Common Issues

8.1 Kibana shows “Unable to retrieve version information from Elasticsearch”

Cause: Protocol mismatch - Kibana is using https:// but Elasticsearch has SSL disabled.
Fix:
Check current Kibana config
sudo grep "elasticsearch.hosts" /etc/kibana/kibana.yml

Fix: change https to http
elasticsearch.hosts: ["http://localhost:9200"]

Comment out any SSL certificate lines
elasticsearch.ssl.certificateAuthorities: [...]

sudo systemctl restart kibana

8.2 Filebeat shows harvester.open_files: 0

Cause: Filebeat config is malformed (duplicate sections, wrong indentation, or double-quoted regex).
Fix: - Ensure filebeat.yml has no duplicate top-level keys. - Use single quotes for multiline.pattern (YAML treats \d in double quotes as an escape sequence). - Top-level keys (filebeat.inputs:, output.logstash:, processors:) must start at column 0.
Validate the config
sudo filebeat test config -c /etc/filebeat/filebeat.yml

Clear registry and restart
sudo rm -rf /var/lib/filebeat/registry
sudo systemctl restart filebeat

8.3 No boardgame-logs-* indices in Elasticsearch

Cause: Filebeat cannot reach Logstash on port 5044.
Fix:
From the application server, test connectivity
telnet 5044

If connection refused - open port 5044 in the ELK server's security group
If connection times out - check if Logstash is running
sudo systemctl status logstash

8.4 Kibana Data View shows “No data streams, indices, or index aliases match”

Cause: No data has been ingested yet, or the index pattern is wrong.
Fix:
List all indices
curl http://localhost:9200/_cat/indices?v

Check the exact index name and match your pattern accordingly
If index is "boardgame-logs-2026.03.11", pattern should be "boardgame-logs-*"

8.5 Logstash is running but not receiving data

Cause: Logstash pipeline failed to start, or the config file has syntax errors.
Fix:
Test the Logstash config
sudo /usr/share/logstash/bin/logstash --config.test_and_exit -f /etc/logstash/conf.d/

Check Logstash logs
sudo journalctl -u logstash --no-pager -n 30

“You can’t manage what you can’t measure.” - Peter Drucker

9. FAQs

Q1. Why use the ELK stack instead of cloud-native logging (CloudWatch, Stackdriver)?
ELK gives you full control over data retention, parsing rules, and costs. Cloud logging services charge per GB ingested, which becomes expensive at scale. ELK is free (open-source) - you only pay for the infrastructure.

Q2. Why Filebeat instead of sending logs directly from the application?
Filebeat decouples your application from the logging pipeline. If Logstash or Elasticsearch goes down, Filebeat queues events and retries. Your application keeps running without blocking on log delivery. Filebeat also uses ~10–30 MB RAM versus Logstash’s 500 MB+, making it ideal for application servers.

Q3. Can I skip Logstash and send Filebeat directly to Elasticsearch?
Yes. Set output.elasticsearch instead of output.logstash in Filebeat. However, you lose the ability to parse and transform logs with grok filters. For simple use cases (no parsing needed), direct shipping is fine.

Q4. Why daily indices (boardgame-logs-2026.03.11) instead of a single index?
Daily indices enable simple retention management (delete indices older than N days), improve search performance (Elasticsearch skips irrelevant time ranges), and make index management operations (backup, restore) more granular.

Q5. How much disk space does the ELK stack need?
Rough estimate: 1 GB of raw logs produces ~1.5–2 GB of Elasticsearch data (due to indexing overhead). For 100 MB/day of logs with 30-day retention, budget ~6 GB for Elasticsearch data.

Q6. Why must multiline.pattern use single quotes in YAML?
YAML interprets backslash sequences in double-quoted strings (\d becomes an invalid escape). Single quotes treat the content literally, preserving the regex pattern for Filebeat.

Q7. How do I add more application servers?
Install Filebeat on each server, point it to the same Logstash endpoint. Add a fields section to distinguish servers:
filebeat.inputs:

type: log enabled: true paths:
- /var/log/myapp/*.log fields: server_name: web-02 environment: production

Q8. Is this setup production-ready as described?
For internal use, yes. For public-facing production, enable Elasticsearch security (xpack.security.enabled: true), use TLS certificates for all inter-component communication, put Kibana behind a reverse proxy with authentication, and configure Index Lifecycle Management for automatic cleanup.

10. Key Takeaways

Centralized logging transforms debugging from “SSH into each server and grep” to “search once, find everywhere.”
Filebeat belongs on the application server, not the ELK server. It is lightweight (~10–30 MB RAM) and handles backpressure gracefully.
Logstash’s grok filter turns unstructured log lines into structured, searchable fields (timestamp, loglevel, logmessage).
Protocol mismatch (https:// vs http://) between Kibana and Elasticsearch is the most common setup failure. Always match the protocol to Elasticsearch’s actual SSL configuration.
YAML formatting causes most Filebeat config errors - use single quotes for regex, no duplicate keys, no leading spaces on top-level keys.
Daily indices (boardgame-logs-%{+YYYY.MM.dd}) simplify retention management and improve query performance.
Security is not optional in production - enable xpack.security, use TLS, and restrict port access via security groups.
Test connectivity bottom-up: Elasticsearch first, then Logstash, then Kibana, then Filebeat.

11. Conclusion

Setting up the ELK stack is not just about installing four packages - it is about building a reliable data pipeline that turns scattered log files into searchable, visualizable insights. Each component has a clear role: Filebeat ships, Logstash transforms, Elasticsearch stores, and Kibana visualizes.

The most common failures are not in the software itself, but in the configuration glue between components: protocol mismatches between Kibana and Elasticsearch, YAML formatting errors in Filebeat, unopened firewall ports between servers, and missing runtime dependencies.

By following the step-by-step approach in this guide - installing bottom-up (Elasticsearch → Logstash → Kibana → Filebeat), verifying each component before moving to the next, and understanding why each configuration setting exists - you can set up a production-grade centralized logging system that scales from a single application to dozens of services.

Once the pipeline is flowing, the real value begins: building dashboards for error rates, setting up alerts for anomalies, and turning your logs from an afterthought into your first line of defense.

About the Author:Rajan is a DevOps Engineer at AddWebSolution, specializing in automation infrastructure, Optimize the CI/CD Pipelines and ensuring seamless deployments.

Nginx + PHP + MySQL Optimisations and Parameter Calculations

Narendra Chauhan — Fri, 03 Apr 2026 06:38:00 +0000

“Premature optimization is the root of all evil but lack of optimisation is the root of outages.”

Introduction
Architecture Overview
Why Optimisation Is Required
Nginx Optimisations & Parameter Calculations
PHP-FPM Optimisations & Parameter Calculations
MySQL Optimisations & Parameter Calculations
System-Level Optimisations (Linux)
Practical Example: Small vs Medium vs Large Server
Interesting Facts & Statistics
FAQs
Key Takeaways
Conclusion

1. Introduction

Modern web applications rely heavily on the Nginx + PHP + MySQL (LEMP) stack. While default configurations work for testing, they are not suitable for production traffic.

Optimisation ensures:

Faster page load time
Better concurrency handling
Lower memory and CPU usage
Higher stability under load

This document explains what to optimise, why to optimise, and how to calculate parameters practically.

2. Architecture Overview

A typical request flow:

Client sends HTTP request
Nginx handles connection & static content
PHP-FPM processes dynamic PHP requests
MySQL serves data from database
Response sent back to client

Each layer must be tuned together, not individually.

3. Why Optimisation Is Required

Default settings:

Are conservative
Waste available RAM
Limit concurrency
Cause slow response under load

Common Problems Without Optimisation

502 / 504 Gateway errors
High CPU load
PHP-FPM “server reached max_children”
MySQL “Too many connections”

4. Nginx Optimisations & Parameter Calculations

Key Nginx Parameters
worker_processes auto;
worker_connections 4096;

What is worker_processes
Number of worker processes
Best practice: match CPU cores

nproc
Example:
4 CPU cores → worker_processes 4;
What is worker_connections
Maximum connections per worker

Total Max Connections
worker_processes × worker_connections

Example

4 × 4096 = 16,384 concurrent connections

Recommended Extra Optimisations

use epoll;
multi_accept on;

sendfile on;
tcp_nopush on;
tcp_nodelay on;

keepalive_timeout 65;
keepalive_requests 1000;

5. PHP-FPM Optimisations & Parameter Calculations

Key PHP-FPM Settings

pm = dynamic
pm.max_children = 20
pm.start_servers = 5
pm.min_spare_servers = 5
pm.max_spare_servers = 10

How to Calculate pm.max_children

Find average PHP process memory: ps -ylC php-fpm --sort:rss
Formula: Available RAM for PHP / Avg PHP process size

Example

Available RAM: 2 GB
Avg PHP process: 100 MB

2048 / 100 ≈ 20
pm.max_children = 20

Other Important PHP Optimisations

request_terminate_timeout = 60
max_execution_time = 60
memory_limit = 256M

Enable OPcache

opcache.enable=1
opcache.memory_consumption=256
opcache.max_accelerated_files=20000

6. MySQL Optimisations & Parameter Calculations

Key MySQL Parameters

innodb_buffer_pool_size = 2G
innodb_buffer_pool_instances = 2
max_connections = 200

How to Calculate innodb_buffer_pool_size

Allocate 60–70% of total RAM (dedicated DB server)

Example

Server RAM: 4 GB

4 × 70% ≈ 2.8 GB
Use 2G or 3G

Connection Calculation

Additional Recommended Settings

query_cache_type = 0
slow_query_log = 1
slow_query_log_file = /var/log/mysql/slow.log
long_query_time = 2

7. System-Level Optimisations (Linux)

File Descriptors

ulimit -n 100000

Kernel Tuning

net.core.somaxconn = 65535
net.ipv4.tcp_max_syn_backlog = 65535
vm.swappiness = 10

8. Practical Server Size Examples

Small Server (2 CPU / 2 GB RAM)

Nginx workers: 2
worker_connections: 2048
PHP max_children: 10
MySQL buffer pool: 1G

Medium Server (4 CPU / 8 GB RAM)

Nginx workers: 4
worker_connections: 4096
PHP max_children: 30–40
MySQL buffer pool: 4–5G

Large Server (8 CPU / 16 GB RAM)

Nginx workers: 8
worker_connections: 8192
PHP max_children: 60–80
MySQL buffer pool: 10–12G

Practical Demonstration (Images Explained)

Step 1. NGINX OPTIMISATION

Parameter Calculations
Step 1.1 Backup current nginx.conf

  sudo cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak

Step 1.2 Check current config

  cat /etc/nginx/nginx.conf

Screenshot: Current state before changes

Step 1.3 Edit nginx.conf

sudo nano /etc/nginx/nginx.conf

Replace/update with this optimized config:

user www-data;
  worker_processes 2;                    # = nproc (2 cores)
  worker_rlimit_nofile 65535;
  pid /run/nginx.pid;
  include /etc/nginx/modules-enabled/*.conf;

  events {
      worker_connections 1024;           # 2 x 1024 = 2048 total connections
      use epoll;                         # Linux best event model
      multi_accept on;                   # Accept multiple connections at once
  }

  http {

      # Basic Settings
      sendfile on;
      tcp_nopush on;
      tcp_nodelay on;
      keepalive_timeout 30;              # Reduced from default 75s
      keepalive_requests 100;
      types_hash_max_size 2048;
      server_tokens off;                 # Hide nginx version

      client_max_body_size 20m;
      client_body_buffer_size 128k;
      client_header_buffer_size 1k;
      large_client_header_buffers 4 8k;
      client_body_timeout 12;
      client_header_timeout 12;
      send_timeout 10;

      include /etc/nginx/mime.types;
      default_type application/octet-stream;

      # Logging Settings
      access_log /var/log/nginx/access.log;
      error_log /var/log/nginx/error.log warn;   # Only warn+ to reduce I/O

      # Gzip Settings
      gzip on;
      gzip_vary on;
      gzip_proxied any;
      gzip_comp_level 3;                 # Level 3 = good ratio, low CPU
      gzip_min_length 1024;              # Don't compress tiny files
      gzip_buffers 16 8k;
      gzip_http_version 1.1;
      gzip_types
          text/plain
          text/css
          text/javascript
          application/javascript
          application/json
          application/xml
          image/svg+xml
          font/woff2;


      # Open File Cache
      open_file_cache max=1000 inactive=20s;
      open_file_cache_valid 30s;
      open_file_cache_min_uses 2;
      open_file_cache_errors on;

      # FastCGI Cache (optional - enable per site)
      fastcgi_cache_path /var/cache/nginx levels=1:2 keys_zone=PHPCACHE:10m
                         max_size=100m inactive=60m use_temp_path=off;

      include /etc/nginx/conf.d/*.conf;
      include /etc/nginx/sites-enabled/*;
  }

Step 1.4 Create FastCGI cache directory

 sudo mkdir -p /var/cache/nginx
  sudo chown www-data:www-data /var/cache/nginx

Step 1.5 Test and reload Nginx

sudo nginx -t
  sudo systemctl reload nginx

Screenshot: nginx -t showing syntax is ok and test is successful

Step 1.6 Verify Nginx is running with new settings

sudo nginx -T | grep -E "worker_processes|worker_connections|gzip|keepalive_timeout"
systemctl status nginx

Screenshot: Running status + key parameters

Step 2. PHP-FPM OPTIMISATION

Parameter Calculations
Available RAM for PHP-FPM: ~150MB (conservative, leaving room for MySQL + Nginx)
Average PHP-FPM process size: ~30-40MB
Formula: pm.max_children = 150 / 35 ≈ 4

PHP-FPM Parameters Calculation
pm
Formula: Dynamic (best for variable traffic)
Value: dynamic

pm.max_children
Formula: 150MB ÷ 35MB/process
Value: 4

pm.start_servers
Formula: pm.max_children / 2
Value: 2

pm.min_spare_servers
Formula: pm.start_servers / 2
Value: 1

pm.max_spare_servers
Formula: pm.start_servers
Value: 2

pm.max_requests
Formula: Prevent memory leaks
Value: 500

Step 2.1 Check PHP-FPM version path

  php -v
  ls /etc/php/

Step 2.2 Backup pool config

sudo cp/etc/php/8.4/fpm/pool.d/www.conf/etc /php/8.4/fpm/pool.d/www.conf.bak
sudo cp /etc/php/8.4/fpm/php.ini /etc/php/8.4/fpm/php.ini.bak

Step 2.3 Check current PHP process memory usage

Run this to see actual PHP-FPM process sizes

ps aux | grep php-fpm | grep -v grep | awk '{sum += $6} END {print "Total RSS:", sum/1024, "MB"; print "Count:", NR; print "Avg per process:", sum/NR/1024, "MB"}'

Screenshot: Current process sizes.

Step 2.4 Edit PHP-FPM pool config

sudo nano /etc/php/8.4/fpm/pool.d/www.conf

Find and update these values (search with Ctrl+W in nano):

[www]
user = www-data
group = www-data

listen = /run/php/php8.4-fpm.sock
listen.owner = www-data
listen.group = www-data

pm = dynamic
pm.max_children = 4
pm.start_servers = 2
pm.min_spare_servers = 1
pm.max_spare_servers = 2
pm.max_requests = 500     ;Restart workers after 500 requests (prevents memory leaks)
pm.process_idle_timeout = 10s

pm.status_path = /status  ; Enable FPM status page
ping.path = /ping

slowlog = /var/log/php8.4-fpm-slow.log
request_slowlog_timeout = 5s     ; Log requests taking > 5 seconds
security.limit_extensions = .php

Step 2.5 Tune PHP OPcache
sudo nano /etc/php/8.4/mods-available/opcache.ini

zend_extension=opcache

  ; Enable OPcache
  opcache.enable=1
  opcache.enable_cli=0

  ; Memory: 64MB for low-RAM server
  opcache.memory_consumption=64
  opcache.interned_strings_buffer=8
  opcache.max_accelerated_files=10000

  ; Production settings (set validate_timestamps=0 in prod)
  opcache.validate_timestamps=1
  opcache.revalidate_freq=60

  opcache.save_comments=1
  opcache.max_wasted_percentage=10
  opcache.use_cwd=1

  ; JIT (PHP 8.x feature)
  opcache.jit_buffer_size=32M
  opcache.jit=1255

Step 2.6 Tune PHP.ini key values
sudo nano /etc/php/8.4/fpm/php.ini

Find and update:
  ; Memory limit per PHP process
  memory_limit = 128M

  ; Upload/POST limits
  upload_max_filesize = 20M
  post_max_size = 25M
  max_execution_time = 60
  max_input_time = 60

  ; Error handling (production)
  display_errors = Off
  log_errors = On
  error_log = /var/log/php_errors.log

  ; Session handling
  session.gc_maxlifetime = 1440
  session.cookie_httponly = 1
  session.cookie_secure = 1

  ; Disable dangerous functions
  disable_functions = exec,passthru,shell_exec,system,proc_open,popen

Step 2.7 Restart PHP-FPM and verify

sudo php-fpm8.4 -t
  sudo systemctl restart php8.4-fpm
  sudo systemctl status php8.4-fpm

Screenshot: PHP-FPM status showing active (running)

Step 2.8 Verify OPcache is active

php -r "var_dump(opcache_get_status());" | head -30

- or check via CLI

php -i | grep -E "opcache|OPcache"

Screenshot: OPcache enabled status

Step 2.9 Check PHP-FPM processes after restart

  ps aux | grep php-fpm | grep -v grep

- Should show master + 2 worker processes (pm.start_servers=2)

Screenshot: FPM process list

Step 3. MYSQL OPTIMISATION

Parameter Calculations

RAM budget for MySQL: ~200MB (out of 914MB total)

innodb_buffer_pool_size
Formula: ~20% of RAM (shared server)
Value: 192M

innodb_buffer_pool_instances
Formula: buffer_pool ÷ 128M
Value: 1

max_connections
Formula: Low RAM = conservative
Value: 50

innodb_log_file_size
Formula: 25% of buffer pool
Value: 48M

tmp_table_size
Formula: Memory temporary tables
Value: 16M

max_heap_table_size
Formula: Same as tmp_table_size
Value: 16M

thread_cache_size
Formula: Reuse threads
Value: 8

table_open_cache
Formula: Open tables cache
Value: 400

Step 3.1 Check current MySQL config and status

sudo cp /etc/mysql/mysql.conf.d/mysqld.cnf /etc/mysql/mysql.conf.d/mysqld.cnf.bak

- Check current variables

mysql -u root -p -e "SHOW VARIABLES LIKE 'innodb_buffer_pool%';"
  mysql -u root -p -e "SHOW VARIABLES LIKE 'max_connections';"
  mysql -u root -p -e "SHOW STATUS LIKE 'Threads_connected';"

Screenshot: Current MySQL variables

Step 3.2 Check actual MySQL memory usage

mysql -u root -p -e "
  SELECT
    ROUND(@@innodb_buffer_pool_size/1024/1024, 0) AS 'Buffer Pool MB',
    ROUND(@@key_buffer_size/1024/1024, 0) AS 'Key Buffer MB',
    @@max_connections AS 'Max Connections',
    @@thread_stack/1024 AS 'Thread Stack KB';
  "

Screenshot: Current MySQL memory config

Step 3.3 Edit MySQL config

sudo nano /etc/mysql/mysql.conf.d/mysqld.cnf

Add/update under [mysqld]:

[mysqld]
  pid-file        = /var/run/mysqld/mysqld.pid
  socket          = /var/run/mysqld/mysqld.sock
  datadir         = /var/lib/mysql
  log-error       = /var/log/mysql/error.log

  #
  # ===== MEMORY SETTINGS =====
  # Server has 914MB RAM - allocate ~200MB for MySQL
  #
  innodb_buffer_pool_size         = 192M    # Main InnoDB cache (most important!)
  innodb_buffer_pool_instances    = 1       # 1 instance (< 1GB pool)
  innodb_log_file_size            = 48M     # ~25% of buffer pool
  innodb_log_buffer_size          = 8M
  innodb_flush_log_at_trx_commit  = 2       # Slight risk, big perf gain (use 1 for strict ACID)

  #
  # ===== CONNECTION SETTINGS =====
  #
  max_connections         = 50             # Low RAM = keep connections limited
  thread_cache_size       = 8             # Reuse threads, avoid creation overhead
  wait_timeout            = 120           # Kill idle connections after 2 min
  interactive_timeout     = 120

  #
  # ===== QUERY CACHE (removed in MySQL 8.0, skip) =====
  # MySQL 8.0 removed query_cache - use ProxySQL or app-level cache

  #
  # ===== TABLE CACHE =====
  #
  table_open_cache        = 400
  table_definition_cache  = 400

  #
  # ===== TEMP TABLES =====
  #
  tmp_table_size          = 16M
  max_heap_table_size     = 16M

  #
  # ===== InnoDB I/O =====
  #
  innodb_file_per_table           = 1
  innodb_flush_method             = O_DIRECT  # Avoid double buffering with OS cache
  innodb_read_io_threads          = 2         # = CPU cores
  innodb_write_io_threads         = 2         # = CPU cores

  #
  # ===== SLOW QUERY LOG =====
  #
  slow_query_log          = 1
  slow_query_log_file     = /var/log/mysql/slow.log
  long_query_time         = 2             # Log queries > 2 seconds
  log_queries_not_using_indexes = 1

  #
  # ===== BINARY LOG (disable if not using replication) =====
  #
  # skip-log-bin                           # Uncomment if no replication needed

Step 3.4 Validate and restart MySQL

sudo mysqld --validate-config
  sudo systemctl restart mysql
  sudo systemctl status mysql

Screenshot: MySQL status active

Step 3.5 Verify new MySQL variables

mysql -u root -p -e "
  SELECT 'innodb_buffer_pool_size' AS Variable,
         ROUND(@@innodb_buffer_pool_size/1024/1024,0) AS 'Value (MB)'
  UNION SELECT 'max_connections', @@max_connections
  UNION SELECT 'innodb_log_file_size MB', ROUND(@@innodb_log_file_size/1024/1024,0)
  UNION SELECT 'tmp_table_size MB', ROUND(@@tmp_table_size/1024/1024,0)
  UNION SELECT 'thread_cache_size', @@thread_cache_size;
  "

Screenshot: New values confirmed

Step 3.6 Check MySQL memory usage post-restart

  free -h
  ps aux | sort -k6 -rn | head -10

Screenshot: Overall memory after all services tuned

“Measure first, tune second, and monitor always.”

Step 4. FINAL VERIFICATION

Step 4.1 Check all services running

  systemctl status nginx php8.4-fpm mysql --no-pager

Step 4.2 Full memory picture

free -h
  ps aux --sort=-%mem | head -15

Step 4.3 Check nginx + PHP working together

Test nginx config is still valid
  sudo nginx -t

 Test PHP-FPM socket exists
  ls -la /run/php/php8.4-fpm.sock

 Check FPM status (if you added status page to your site config)
  curl http://localhost/status

Step 4.4 Check MySQL slow log is active

mysql -u root -p -e "SHOW VARIABLES LIKE 'slow_query%';"

Step 4.5 Final health summary

echo "=== NGINX ===" && nginx -v && systemctl is-active nginx
  echo "=== PHP-FPM ===" && php -v | head -1 && systemctl is-active php8.4-fpm
  echo "=== MYSQL ===" && mysql --version && systemctl is-active mysql
  echo "=== MEMORY ===" && free -h

Screenshot: Final health check

Your server is fully optimised. All phases verified:

Phase 0 Swap 2GB active
Phase 1 Nginx tuned
Phase 2 PHP-FPM + OPcache + JIT enabled
Phase 3 MySQL InnoDB / connections / slow query log active

9. Interesting Facts & Statistics

1 second delay can reduce conversions by 7%
OPcache can improve PHP performance by 2–3×
MySQL buffer pool cache hit ratio above 99% is ideal
Nginx handles 10× more concurrent connections than traditional servers

11. FAQs

Q1. Should I optimise Nginx, PHP, or MySQL first?
Start with PHP-FPM and MySQL, then tune Nginx.

Q2. Can wrong tuning crash the server?
Yes. Over-allocating RAM causes OOM kills.

Q3. Are these values fixed forever?
No. Recalculate after traffic growth.

Q4. Do I need load testing?
Yes. Use tools like ab, wrk, or k6.

12. Key Takeaways

Optimisation is calculation-based, not guesswork
PHP-FPM memory calculation is critical
MySQL buffer pool has the biggest performance impact
Nginx handles concurrency, not application logic
Monitoring is mandatory after tuning

13. Conclusion

Optimising Nginx + PHP + MySQL is not about copying configs from the internet—it is about understanding server resources, calculating limits, and balancing load across layers.
A well-optimised stack:

Handles higher traffic
Reduces downtime
Improves user experience
Saves infrastructure cost

About the Author:Narendra is a DevOps Engineer at AddWebSolution, specializing in automating infrastructure to improve efficiency and reliability.

DEV Community: AddWeb Solution Pvt Ltd

API Contract-Driven Development (Build Reliable Systems Without Guesswork)

Why API Contracts Matter

What Is Contract-Driven Development?

Core Philosophy

Key Takeaways

Index

1. Introduction

2. What Is an API Contract?

3. Contract-First vs Code-First

4. How Contract-Driven Development Works

5. Architecture Overview

6. Defining API Contracts (Conceptual)

7. Development Workflow

8. Validation and Testing

9. Versioning and Evolution

10. Tooling and Ecosystem

11. Why This Approach Makes Sense

12. Watch Out For

13. Next Steps You Can Take

14. Interesting Facts

15. FAQ

16. Conclusion

Designing Permission Systems Beyond RBAC (ABAC)

Key Takeaways

Introduction

Index

Why Traditional RBAC Fails at Scale

Core Concepts of ABAC

RBAC vs ABAC (Deep Comparison)

Core Principles of Modern Permission Architecture

Designing a Scalable Authorization System

Policy Engine Architecture

Attribute Modeling Strategy

Caching & Performance Optimization

Frontend Authorization Patterns

Audit Logging & Compliance

Real-World Example (Enterprise SaaS)

Interesting Facts

Stats

FAQ’s

Conclusion

Handling Long-Running Processes in UI

Key Takeaway

Table of Contents

1. Introduction

2. Understanding the Four Process States

3. Communicating Progress - Determinate, Indeterminate & Multi-Stage

4. Handling Cancellation, Failure & Recovery

5. Building a Custom useLongRunningTask Hook

6. Advanced Techniques

7. Stats & Interesting Facts

8. FAQ

9. Conclusion

Accessibility (a11y) in Modern Apps

Key Takeaways

Index

What is Accessibility (a11y)?

Why Accessibility Matters

Types of Disabilities to Consider

Core Principles (WCAG)

Common Accessibility Mistakes

Practical Implementation

Tools for Testing Accessibility

Real-World Example

Interesting Facts

FAQs

Conclusion

Managing Environment Variables in React Properly

Key Takeaways

Index

1. Why This Matters

2. Mistake 1: Using the Wrong Environment Variable Prefix

3. Mistake 2: Treating Client-Side Env Vars Like Secrets

4. Mistake 3: Mixing process.env and import.meta.env

5. Mistake 4: Hardcoding URLs Instead of Using Config

6. Mistake 5: Not Using .env.local Properly

7. Mistake 6: Forgetting to Restart the Dev Server

8. Mistake 7: Keeping Too Many Environment Files Without a Clear Rule

9. Mistake 8: Not Validating Required Variables