DEV Community: Samuel Owolabi

What if you are to build for a 1,000,000 daily active users?

Samuel Owolabi — Tue, 20 Jan 2026 11:43:42 +0000

Two years ago, a client approached me to build an end-to-end booking ecosystem. It is a B2B platform for businesses and their customers.

For the Business Dashboard, I built a multi-tenant interface where owners could list their booking packages, manage inventory, manage customers, set booking hours and track their entire operation.

For the Customer Portal, I engineered a seamless flow for real-time booking, Stripe-integrated payment processing, automated daily booking reminders, automated receipt generation, dashboard for customers to view their bookings, reschedule bookings e.t.c.

The initial stack was the standard developer starter pack: a monolithic architecture pushed to GitHub, with Vercel and Railway handling the frontend and backend orchestration.

It was a clean implementation. It performed flawlessly. Businesses are being onboarded and setting up their booking platform, their customers are using their booking platform conveniently, the system works until last year.

When Success Breaks Everything

The platform hit a critical mass that transformed our steady growth into a high-concurrency challenge. We moved from predictable usage to a different league of infrastructure demands where every millisecond of latency translated into lost revenue.

The Shift in Request Volume
We moved from managing users to managing an onslaught. We were hitting millions of API calls and high-frequency I/O operations daily. These weren't just simple reads; they were massive surges in concurrent traffic that ignored any attempt at traditional capacity planning.

The Pressure on System Reliability
There was a much higher expectation for low latency and 99.9% uptime. The SLAs shifted overnight. We started seeing frequent service degradation because the systems were operating under constant resource exhaustion. The infrastructure was gasping for air.

The Complexity of Concurrent Sessions
As the user base grew, we faced challenges with session persistence and shared state. Managing thousands of simultaneous web socket connections for real-time availability updates meant our single-server memory was constantly hitting its ceiling.

Why Traditional Architecture Fails at Scale
When the system started buckling, it became clear that the standard deployment strategy has a ceiling. Growth doesn't just stress your code; it exposes the structural debt in your architecture.

The Catastrophe of Single Points of Failure
Our tight coupling became our biggest vulnerability. I vividly remember when the client called me around 01:00 AM because the entire production environment went down. The culprit was an SMTP timeout. Because the email service was part of the main execution thread, a transient failure in a third-party mail provider caused a deadlock that crashed the entire server.

The Bottleneck of Synchronous Execution
In the original build, everything was synchronous. When a user booked a package, the thread would stay open while processing the payment, updating the DB, and triggering transactional emails. At scale, this created massive overhead, slowing down the response.

The Silent Failures and Data Integrity
At scale, systems rarely just die; they degrade. We started seeing zombie states where a payment went through in Stripe, but the database didn't update because of a timeout. These partial failures are a nightmare for business owners because they create massive manual support work.

The Observability Gap
We are consuming high RAM usage, without evening know what part of the architecture consume that much. We were flying blind because we lacked an observability layer to track CPU Usage, latency, errors, throughput e.t.c

Database Contention Over Compute
We hit the database wall long before we hit compute limits. The primary instance was struggling to manage the lock contention between the heavy analytics queries on the business dashboard and the high-frequency writes from the customer booking portal.

What I did next?

Transitioning to a Distributed Architecture

To resolve these issues, I had to move away from the monolith and design for horizontal scalability. We transitioned the application to run across multiple stateless instances, managed by a Load Balancer and an Auto-Scaling Group (ASG).

Decoupling Data with CQRS and Read Replicas
I separated the Read and Write workloads. We implemented a Primary-Replica configuration where the primary database handles all Write operations, while multiple Read Replicas handle the query traffic. We had to manage Replication Lag to ensure the business and customer dashboard could pull analytics without dragging down the payment engine.

Multi-layer Caching and Edge Delivery
To reduce the load on our origin servers, I implemented a robust caching strategy. We utilized Cloudfront for edge caching of static assets and integrated Redis as a distributed cache for frequently accessed or computationally expensive API queries. Now loads have been reduced on databases and downstream services, and response times improved at high traffic

Asynchronous Event-Driven Architecture
The most critical shift was moving to a Producer-Queue-Consumer model. I offloaded non-critical tasks like emails, push notifications, and analytics processing to background workers using a Message Queue. This decoupled the critical path, allowing the user to receive faster response, while the request is being run as a background job. We have eliminated single points of failure.

Fault Tolerance and Cost Optimization
I deployed instances across multiple Availability Zones (AZs) which eliminated redundancy into every critical path. We set up Database Standbys and automated health checks for automatic failover. Importantly, we used Auto Scaling Groups (ASGs) to automatically scale down during low-traffic hours to ensure we weren't paying for compute we didn't need.

Centralized Logging and Real-time Telemetry
I implemented a centralized logging stack to aggregate data from every distributed instance. This allowed us to query logs across the entire cluster in real-time, making it possible to trace a single user request as it traveled through the load balancer, the API, and the background workers. I set alerts for above usage and user impacting thresholds, monitor trends not just outages. Now we know “what is slow“, “what is failing“, “what has changed“ e.t.c

Takeaway

Building for a million daily active users is less about the tools and more about the discipline of distributed systems. Today, we are managing tens of thousands of active users, but the architecture is now future-proofed to scale to a million and beyond without a total rewrite.

I started simple to prove the business model, but I documented the limits and let real-world telemetry drive our path toward high availability. It’s about being ready for success so that when a million users show up, your system and your sleep schedule can handle it.

Client vs Server-Side Encryption: The Real Meaning of End-to-End Security

Samuel Owolabi — Wed, 08 Oct 2025 21:31:37 +0000

In my early tech journey, I’d always see the phrase “End-to-End Encryption on WhatsApp” and feel a bit skeptical. 🤔 How could WhatsApp not see my messages when their servers were the ones handling them? I honestly thought it was just a clever marketing gimmick.

My curiosity grew when I started learning about crypto wallets. If I lose my seed phrase, why can’t the wallet company just hit a “reset” button and recover it for me? What was happening behind the scenes that made my data so inaccessible, even to the provider?

Later, while working on real projects, I got comfortable implementing security measures like JWT, OAuth, and password hashing with bcrypt. But for a fintech project, I faced a new challenge: encrypting sensitive data moving between our users’ devices and our server. Suddenly, I was working with concepts like AES, data keys, and key management, and it felt fundamentally different from the security tokens I was used to.

The real “aha!” moment came while I was studying for my AWS Certified Developer exam. The course material (Stephane Maarek Udemy Course) finally connected all the dots, giving me a clear picture of how encryption works on both the client’s device and the server. This article is my attempt to share those lessons and clear up the confusion in a simple, beginner-friendly way.

So, What Exactly is Encryption?

At its heart, encryption is the process of taking readable data (plaintext) and scrambling it into an unreadable format (ciphertext) using a special algorithm. The only way to unscramble that data and turn it back into readable plaintext is with the correct decryption key.

Think of it like locking a secret message in a box 📦. Anyone can see the box, but only the person who has the unique key can open it and read the message inside.

Encryption is built on two main approaches:

Symmetric Encryption: Imagine a lockbox that uses the same key to both lock and unlock it. This is great for speed. (e.g., AES).
Asymmetric Encryption: This is like having two different keys. One is a public key that you can give to anyone they can use it to put things in the box and lock it. But only you have the secret private key that can open it. (e.g., RSA).

An Analogy That Made It All Click: The Two Lockboxes

Imagine you want to send a secret letter from Alice to Bob using a courier service. How they handle security is the perfect analogy for client-side vs. server-side encryption.

Scenario 1: Server-Side Encryption (The Courier’s Lockbox)

Alice writes her letter and hands it, unsealed, to the courier. The courier puts the letter into one of their standard company lockboxes and takes it to Bob. The courier company has the master key to all their boxes. They promise not to look, but they technically could if they wanted to. This is super convenient for Alice; she doesn’t have to worry about finding or managing her own lockbox.

Scenario 2: Client-Side Encryption (Alice’s Personal Lockbox)

Alice writes her letter, but before she even calls the courier, she puts it in her own personal lockbox. Only she and Bob have a copy of the key. She then gives the already locked box to the courier. The courier can transport the box, but they have absolutely no way of opening it to see the contents. This is maximum security.

Client-Side Encryption (CSE)

Client-Side Encryption (CSE), also known as end-to-end encryption (E2EE) or zero-knowledge encryption, is the “personal lockbox” approach. The data is encrypted on your device (the client) before it’s sent to the server.

How does it work?

You create something: You type a message or create a file on your phone or computer, or data.
Encrypted on your device: The app you’re using (like WhatsApp or your crypto wallet) uses a key on your device to encrypt this data right then and there.
Scrambled data travels: The unreadable ciphertext is sent over the internet to the server.
Server stores gibberish: The server stores this ciphertext. It has no key and cannot read the data. To the server, it’s just a meaningless blob of information.
Decrypted on the other side: When your friend requests the message, the server sends them the ciphertext. Their app uses its key to decrypt the data back into a readable format on their device.

Use Cases

Social Messaging Apps (WhatsApp, Signal): This finally answered my first question! When you send a message, it’s encrypted on your phone and only decrypted on your friend’s phone. WhatsApp’s servers only pass along the scrambled data. They truly can’t read your messages.
Cryptocurrency Wallets: This solved my second puzzle! Your “seed phrase” is used to create your private key. This key lives only on your device. The wallet provider never sees it. If you lose it, it’s gone forever because they never had a copy to begin with.
Secure Cloud Storage: Services like AWS S3, Tresorit e.t.c allow you to encrypt your files before you upload them. You manage the keys, and the cloud provider simply stores the encrypted blobs.

The Pros of Client Side Encryption

Maximum Privacy & Control: You, and only you (and the recipient), hold the keys. The service provider cannot access your data.
Breach Containment: If the server is hacked, the attackers only get useless ciphertext.
Regulatory Compliance: Helps meet strict data privacy regulations like GDPR and HIPAA, as no unencrypted personal data is processed by the server.

The Cons of Client Side Encryption

Key Management Burden: If the user loses their key, the data is permanently lost. There is no “Forgot Password” option.
Limited Server Functionality: The server can’t search, index, or perform any operations on the data because it can’t read it.
Implementation Complexity: It requires more work on the client-side application.

Server-Side Encryption (SSE)

Encryption happens after data reaches the server. The server manages keys and performs encryption before storage. It is the “delivery company’s lockbox” approach. You send your data to the server, and the server takes on the responsibility of encrypting it.

How does it work?

You send your data: You upload a file or send information to the server. This connection itself is usually encrypted (this is called “in-transit” encryption, thanks to HTTPS), but the server receives the data in its original, readable form.
Server encrypts it: Once your data arrives, the server uses keys that it manages to encrypt it. This is called “encryption at rest.”
Server stores it: The server stores the resulting ciphertext.
Server decrypts for you: When you want your data back, the server fetches the ciphertext, decrypts it using its key, and sends the readable data back to you (again, over a secure connection).

Use Cases

Most Cloud Storage & Databases: When you upload a file to Google Drive, Dropbox, or a standard AWS S3 bucket, this is what’s happening. They encrypt it on their end to protect against someone physically stealing their hard drives.
Backups: When a service backs up its database, it almost always uses SSE to protect that backup file.
Key Management Systems (KMS): This is a more advanced topic, but cloud providers like AWS have services (like KMS) that make it really easy and secure for servers to manage these encryption keys.

The Pros of Server Side Encryption

Convenience: It’s seamless for the user and often simple for the developer to enable. The provider handles all the complexity of key management.
Server Functionality: Since the server can decrypt the data, it can perform useful operations like searching the content of files or indexing database fields.
Easy Recovery: Key management is centralized, so data recovery is possible.

The Cons of Server Side Encryption

The Trust Issue: You must trust the service provider. They have the keys and can technically access your data. This can be a problem if they suffer an internal breach or are compelled by a government to hand over data.
Broader Attack Surface: If an attacker compromises the server and gains access to the key management system, they could potentially decrypt all the data.

A Cool Pro Tip (Bonus): Envelope Encryption

This is a clever technique used by almost all major cloud providers (like AWS KMS) to do SSE really efficiently. Instead of using one super-strong (but slow) key to encrypt huge amounts of data, they do this:

For each file, the system generates a unique, fast key called a Data Key.
The file is quickly encrypted with this Data Key.
Then, a highly protected Master Key is used to encrypt only the tiny Data Key. 4 . The encrypted file and the encrypted Data Key are stored together.

To decrypt, the server first uses the Master Key to unlock the Data Key, and then uses that Data Key to quickly unlock the main file. It’s the best of both worlds: the top-tier security of a master key with the high performance of data keys!

So, Which One Should I Choose for My Project?

Now that we know the difference, the choice becomes a classic trade-off.

Go for Client-Side Encryption (CSE) when…

Your entire product is built on a promise of privacy and trust. You want to be able to look your users in the eye and say, “We cannot see your data, period.” This is essential for secure chat apps, password managers, and services handling extremely sensitive health or legal information.

Go for Server-Side Encryption (SSE) when…

Your priority is user convenience and providing rich features like search and data analytics. SSE is the standard for most applications. It provides a strong security baseline, protects against data center theft, and helps you meet most compliance requirements without putting the burden of key management on your users.

In Conclusion

The debate isn’t about which encryption method is “better,” but which is right for the job. It’s a fundamental choice between giving the user absolute control versus offering centralized convenience.

Understanding this difference locking the box yourself versus letting the courier lock it for you was a huge step in my developer journey. I hope this explanation clears things up for you too and helps you make more informed decisions, both as a developer building secure apps and as a user trusting services with your data.

Deploying a Node.js App to AWS Elastic Beanstalk with GitHub Actions: A Beginner's Guide

Samuel Owolabi — Fri, 08 Aug 2025 11:33:43 +0000

Automating Node.js Deployment to AWS Elastic Beanstalk with GitHub Actions

Automating the deployment of your applications can save you time and streamline your development process. This step-by-step guide will walk you through deploying a Node.js application to AWS Elastic Beanstalk and setting up a CI/CD pipeline using GitHub Actions. By the end, you'll have a fully automated workflow that tests and deploys your code every time you push to your main branch.

This tutorial is designed for beginners with a general familiarity with Git, GitHub, and AWS.

You can find the complete code for this tutorial in this GitHub repository.

What is AWS Elastic Beanstalk?

AWS Elastic Beanstalk is a service that makes it easier to deploy and manage applications in the AWS cloud. You simply upload your application, and Elastic Beanstalk automatically handles the deployment details of capacity provisioning, load balancing, auto-scaling, and application health monitoring.

Why use it?

Simplicity: It abstracts away the complexity of setting up servers, load balancers, and databases.
Scalability: It can automatically scale your application up or down based on demand.
Cost-Effective: With the AWS Free Tier, you can run a simple application like the one in this guide at no cost. You only pay for what you use as your application grows.

What is GitHub Actions?

GitHub Actions is a CI/CD (Continuous Integration/Continuous Deployment) platform that allows you to automate your build, test, and deployment pipeline. You can create workflows that build and test every pull request to your repository or deploy merged pull requests to production.

Our Workflow Structure:

Event: A trigger that starts the workflow, such as a push to a branch.
Jobs: A set of steps that execute on a runner. We will have a test job and a deploy job.
Steps: Individual tasks that run commands in a job.

Why Combine Elastic Beanstalk with GitHub Actions?

Combining these two powerful tools creates a seamless CI/CD pipeline. With every push to your repository, GitHub Actions will automatically test your Node.js application and, if the tests pass, deploy it to your Elastic Beanstalk environment. This automation eliminates manual deployment steps, reduces the risk of human error, and allows you to release new features faster.

Prerequisites

Before we start, make sure you have the following set up:

An AWS Account: You'll need an account with an IAM user that has permissions for Elastic Beanstalk. We'll create the necessary roles during the tutorial.
A GitHub Repository: This is where your Node.js application code will live. For this tutorial, we will be using a pre-configured repository.
Node.js: Ensure you have Node.js (version 18 or higher) installed on your local machine.

Let's Get Started!

Step 1: Set Up Your Node.js Application

To get you started quickly, a simple Node.js application using Express and TypeScript has been prepared.

Clone the Repository: Open your terminal and clone the sample application:

   git clone https://github.com/samowolabi/nodejs-elastic-beanstalk-with-githubactions-app.git
   cd nodejs-elastic-beanstalk-with-githubactions-app

Install Dependencies:

   npm install

This project has a straightforward structure:

.github/workflows/ci.yml: The GitHub Actions workflow file.
src/index.ts: The main application file.
test/app.test.js: A simple test file.
package.json: Defines project scripts and dependencies.
tsconfig.json: The TypeScript configuration file.

Step 2: Set Up AWS Elastic Beanstalk

Now, let's create the environment on AWS where our application will be deployed.

Navigate to Elastic Beanstalk: Log in to your AWS Management Console and go to the Elastic Beanstalk service.

Create a New Environment:
- Click on Create Application.
- Application name: Enter a name, for instance, nodejs-app-eb-gh-app.
- Platform: Select Node.js. For this guide, "Node.js 18" is used.
- Application code: Keep Sample application selected for now.
- Under Presets, select Single instance (which is free-tier eligible).
- Click Next.

Configure Service Access: This screen is crucial for granting Elastic Beanstalk the necessary permissions.

Service role: This role allows Elastic Beanstalk to manage other AWS resources on your behalf.
- If you don't have one, select Create and use new service role.
- A new window will open to create an IAM role. The role will be pre-configured. Simply click Create role.
- Back on the Elastic Beanstalk screen, refresh the dropdown and select the new role (aws-elasticbeanstalk-service-role).
EC2 instance profile: This role grants permissions to the EC2 instances that will run your application.
- Click Create and use new instance profile.
- In the new window, name your role (e.g., aws-elasticbeanstalk-ec2-new-role).
- The necessary policies (AWSElasticBeanstalkWebTier, etc.) will be attached automatically. Click Create role.
- Return to the Elastic Beanstalk screen, refresh, and select the newly created instance profile.

Review and Launch:
- You can skip the networking, database, and tags setup for this simple deployment by clicking Skip to review.
- On the Review page, look over your configurations and click Submit.

AWS will now start building your environment. This process can take a few minutes. Once it's complete, you can access the provided domain, and you will see the default sample application page.

Bonus: Setting Up Environment Variables

Your Node.js application might require environment variables. You can set them up in the Elastic Beanstalk console:

Go to your environment's page.
Click Configuration > Software > Edit.
Under Environment properties, add your key-value pairs (e.g., NODE_ENV = production). Elastic Beanstalk automatically provides the PORT variable.

Step 3: Configure the CI/CD Pipeline with GitHub Actions

Now it's time to connect your GitHub repository to your new Elastic Beanstalk environment.

Get AWS Access Keys: The GitHub Actions workflow needs credentials to deploy to your AWS account.

In the AWS IAM console, navigate to Users and select your IAM user.
Go to the Security credentials tab and click Create access key.
Select Third-party service, acknowledge the recommendation, and proceed.
You will be provided with an Access key ID and a Secret access key. Copy these immediately, as you won't be able to see the secret key again.

Note: Ensure your IAM user has the necessary permissions. For this deployment, the following policies are recommended: elasticbeanstalk:*, s3:*, ec2:*, iam:PassRole, and logs:*.

Add Credentials to GitHub Secrets:
- In your GitHub repository, go to Settings > Secrets and variables > Actions.
- Click New repository secret and add the following:
  - AWS_ACCESS_KEY_ID: Your AWS access key ID.
  - AWS_SECRET_ACCESS_KEY: Your AWS secret access key.

Understand the Workflow File: Open the .github/workflows/ci.yml file in your repository. Let's break down what it does:

   name: CI/CD

   on:
     push:
       branches: [ main, master ]
     pull_request:
       branches: [ main, master ]

   jobs:
     test:
       runs-on: ubuntu-latest

       strategy:
         matrix:
           node-version: [18.x, 20.x]

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

       - name: Setup Node.js ${{ matrix.node-version }}
         uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
           cache: 'npm'

       - name: Install dependencies
         run: npm ci

       - name: Run tests
         run: npm test

       - name: Build project
         run: npm run build

     deploy:
       needs: test
       runs-on: ubuntu-latest
       if: github.ref == 'refs/heads/main' && github.event_name == 'push'

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

       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
           node-version: '20.x'
           cache: 'npm'

       - name: Install dependencies
         run: npm ci

       - name: Build project
         run: npm run build

       - name: Generate deployment package
         run: |
           zip -r deploy.zip . -x '*.git*' 'node_modules/.cache/*' 'src/*' 'test/*' '*.md' '.env*'

       - name: Deploy to Elastic Beanstalk
         uses: einaregilsson/beanstalk-deploy@v22
         with:
           aws_access_key: ${{ secrets.AWS_ACCESS_KEY_ID }}
           aws_secret_key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
           application_name: nodejs-app-eb-gh-app
           environment_name: Nodejs-app-eb-gh-app-env
           version_label: ${{ github.sha }}
           region: us-east-1
           deployment_package: deploy.zip

on: This workflow triggers on a push or pull_request to the main or master branches.
jobs:
- test: This job runs on two Node.js versions (18.x and 20.x). It checks out your code, installs dependencies, and runs your tests (npm test) and build script (npm run build).
- deploy: This job depends on the test job succeeding (needs: test). It only runs on a push to the main branch. It performs the build again, zips the necessary files into deploy.zip, and then uses the beanstalk-deploy action to push the package to your Elastic Beanstalk environment.

Important: Update the application_name, environment_name, and region in the deploy job to match your Elastic Beanstalk setup.

Step 4: Deploy the Application

Now for the magic moment!

Push to Main: Commit any changes you've made and push them to your main branch.

   git add .
   git commit -m "feat: setup CI/CD and deploy to Elastic Beanstalk"
   git push origin main

Monitor the Workflow: Go to the Actions tab in your GitHub repository. You will see your workflow running. Click on it to see the test and deploy jobs in action.

Verify Deployment: Once the deploy job is complete, navigate back to your Elastic Beanstalk environment's URL. You should now see the message: "Hello, TypeScript with Express!".

Conclusion and Troubleshooting

Congratulations! You have successfully set up a fully automated CI/CD pipeline. Every time you push a change to your main branch, GitHub Actions will test your code and deploy it to AWS Elastic Beanstalk.

Common Issues:

Deployment Fails: Double-check that your AWS credentials in GitHub Secrets are correct and that the IAM user has the required permissions. Verify that the application and environment names in your ci.yml file match your Elastic Beanstalk setup exactly.
Build/Test Failures: Run npm test and npm run build locally to debug any issues before pushing.
Check Logs: The first place to look for errors is the GitHub Actions log. For environment-specific issues, check the logs in your AWS Elastic Beanstalk console (Logs > Request Logs > Last 100 Lines).

This automated workflow is a fundamental practice in modern web development that will significantly improve your development and release process.

A practical guide by Samuel Owolabi

Don't Reach for Redux Just Yet: Mastering State with React Context, useReducer, and TypeScript

Samuel Owolabi — Tue, 22 Jul 2025 21:03:16 +0000

A practical guide by Samuel Owolabi

What if you don't actually need Zustand, Jotai, or Redux for your next project?

Hear me out. Those are fantastic libraries, but for a huge number of applications, you can build a powerful, scalable, and type-safe state management system using the tools React already gives you. The secret lies in combining React Context with the useReducer hook and wrapping it all in the warm, safe blanket of TypeScript.

The purpose of this guide is to show you exactly how to set up this pattern in a simple, practical way. We'll cover a real-world example to show how flexible this approach is. Don't be overwhelmed! By the end, you'll be able to manage complex state with confidence.

We'll build a state management system for a simple fintech dashboard. This will allow us to handle things like:

User authentication (login/logout)
A theme switcher (dark/light mode)
User's wallet data (adding, removing, and updating wallets)
A global token for API requests
A selected currency for display

Ready? Let's dive in.

The Core Concepts: What Are We Using and Why?

First, let's quickly break down the tools we're bringing together.

What is React Context? 📝

React Context provides a way to pass data through the component tree without having to pass props down manually at every level. This is the perfect tool for sharing "global" data like the current user, theme, or language. It helps us avoid a problem called "prop drilling."

What is the useReducer Hook? ⚙️

useReducer is a React hook that you can, and should, use as an alternative to useState when you have complex state logic. Instead of just updating the state directly, you "dispatch" actions. A "reducer" function then takes the current state and an action and returns the new state. If you've ever used Redux, this pattern will feel very familiar. It helps keep your state transitions predictable and organized.

Why Add TypeScript to the Mix? 🛡️

TypeScript is a superset of JavaScript that adds static types. Here's why it's a game-changer for this pattern:

Type Safety: It prevents you from putting the wrong kind of data into your state.
Amazing Autocomplete: TypeScript knows exactly what your state looks like. When you type state., it will show you all the available properties.
Smarter Actions: It ensures you dispatch actions with the correct type and payload. For example, if your ADD_WALLET action needs a WalletType payload, TypeScript will give you an error if you try to send a simple string. This catches bugs before you even run the code.

The Folder Structure

We'll organize our context logic into a dedicated contexts folder. This keeps the state management code neatly separated from our UI components. For a Next.js App Router project, it might look like this:

/src
|-- /app
|   |-- layout.tsx          # We'll wrap our app here
|   |-- usage-examples.tsx  # Component to test our context
|
|-- /contexts
|   |-- appContext.tsx      # The main context provider file
|   |-- reducer.tsx         # The reducer function and initial state
|   |-- reducerTypes.tsx    # All our TypeScript types

Step 1: Define Your Types (reducerTypes.tsx)

This is the most important step for achieving type safety. We start by defining the "shape" of our state, the actions we can perform, and the context itself. By doing this first, we let TypeScript guide us through the rest of the implementation.

Here we define the shape of a user's wallet, the entire application state (ContextStateType), and most importantly, our actions. We use a discriminated union for ContextActionTypes. This is a fancy term for a pattern where each object type in the union has a common property (in our case, type) that TypeScript can use to figure out the exact shape of the action, including its payload.

contexts/reducerTypes.tsx

import { Dispatch } from 'react';

export type WalletType = {
    currency: string,
    availableBalance: number,
    pendingBalance: number,
}

export type ContextStateType = {
    theme: 'light' | 'dark',
    selectedCurrency: string,
    userData: {
        firstName: string,
        lastName: string,
        email: string
    },
    token: string, // For API Requests Authentication
    wallets: WalletType[]
}

// Discriminated union for our action types
export type ContextActionTypes = (
    {
        type: 'SET_THEME',
        payload: ContextStateType['theme']
    } | {
        type: 'SET_SELECTED_CURRENCY',
        payload: ContextStateType['selectedCurrency']
    } | {
        type: 'LOGIN_USER',
        payload: ContextStateType['userData']
    } | {
        type: 'SET_TOKEN',
        payload: ContextStateType['token']
    } | {
        type: 'LOGOUT_USER' // An action with no payload
    } | {
        type: 'SET_WALLETS',
        payload: ContextStateType['wallets']
    } | {
        type: 'UPDATE_WALLET',
        payload: WalletType
    } | {
        type: 'ADD_WALLET',
        payload: WalletType
    } | {
        type: 'REMOVE_WALLET',
        payload: WalletType['currency']
    }
)

// Type for our reducer function
export type ReducerType = (
    state: ContextStateType,
    action: ContextActionTypes
) => ContextStateType;

// Type for the context value that will be provided
export type ContextValueType = {
    state: ContextStateType;
    dispatch: Dispatch<ContextActionTypes>;
}

Step 2: Create the Reducer Function (reducer.tsx)

The reducer is the heart of our state logic. It's a pure function that takes the previous state and an action, and returns the next state. We'll also define our initialState here.

Notice how the switch statement handles each action type we defined earlier. Thanks to our discriminated union, if action.type is 'ADD_WALLET', TypeScript knows that action.payload must be a WalletType object.

contexts/reducer.tsx

import { ContextStateType, ContextActionTypes, ReducerType } from './reducerTypes';

// Initial state for the reducer
export const initialState: ContextStateType = {
    theme: 'light',
    selectedCurrency: 'USD',
    userData: {
        firstName: '',
        lastName: '',
        email: ''
    },
    token: '',
    wallets: []
};

export const reducer: ReducerType = (state: ContextStateType, action: ContextActionTypes): ContextStateType => {
    switch (action.type) {
        case 'SET_THEME':
            return { ...state, theme: action.payload };

        case 'SET_SELECTED_CURRENCY':
            return { ...state, selectedCurrency: action.payload };

        case 'LOGIN_USER':
            return { ...state, userData: action.payload };

        case 'SET_TOKEN':
            return { ...state, token: action.payload };

        case 'LOGOUT_USER':
            return {
                ...state,
                userData: initialState.userData,
                token: ''
            };

        case 'SET_WALLETS':
            return { ...state, wallets: action.payload };

        case 'UPDATE_WALLET':
            return {
                ...state,
                wallets: state.wallets.map(wallet =>
                    wallet.currency === action.payload.currency
                        ? { ...wallet, ...action.payload }
                        : wallet
                )
            };

        case 'ADD_WALLET':
            const walletExists = state.wallets.some(wallet => wallet.currency === action.payload.currency);
            if (walletExists) {
                // If wallet exists, update it instead of adding a duplicate
                return {
                    ...state,
                    wallets: state.wallets.map(wallet =>
                        wallet.currency === action.payload.currency
                            ? action.payload
                            : wallet
                    )
                };
            }
            // Add new wallet
            return { ...state, wallets: [...state.wallets, action.payload] };

        case 'REMOVE_WALLET':
            return {
                ...state,
                wallets: state.wallets.filter(wallet => wallet.currency !== action.payload)
            };

        default:
            return state;
    }
};

Step 3: Build the Context Provider (appContext.tsx)

Now we tie everything together. In this file, we:

Create the context using createContext().
Create the AppProvider component. This component will use our useReducer hook to create the state and dispatch function. It then makes them available to all of its children via the <AppContext.Provider> component.
Create a custom hook useAppContext(). This is a best practice that makes consuming the context much cleaner and safer in our components. It abstracts the useContext call and also throws an error if we try to use the context outside of its provider.

contexts/appContext.tsx

import React, { createContext, useContext, useReducer, ReactNode } from 'react';
import { ContextStateType, ContextActionTypes, ContextValueType } from './reducerTypes';
import { reducer, initialState } from './reducer';

// Create the context
const AppContext = createContext<ContextValueType | undefined>(undefined);

// Provider component props
interface AppProviderProps {
    children: ReactNode;
}

// Provider component
export const AppProvider: React.FC<AppProviderProps> = ({ children }) => {
    const [state, dispatch] = useReducer(reducer, initialState);

    const value: ContextValueType = {
        state,
        dispatch
    };

    return (
        <AppContext.Provider value={value}>
            {children}
        </AppContext.Provider>
    );
};

// Custom hook to use the context
export const useAppContext = (): ContextValueType => {
    const context = useContext(AppContext);

    if (context === undefined) {
        throw new Error('useAppContext must be used within an AppProvider');
    }

    return context;
};

Step 4: Wrap Your App (layout.tsx)

For our context to be available everywhere, we need to wrap our entire application with the AppProvider we just created. In a Next.js app, the root layout.tsx is the perfect place to do this.

layout.tsx

import React, { ReactNode } from 'react';
import { AppProvider } from '@/contexts/appContext';

// Root Layout Component
export default async function RootLayout({
    children,
}: {
    children: ReactNode
}) {
    return (
        <html lang="en">
            <body>
                {/* Wrap the entire app with AppProvider */}
                <AppProvider>
                    {children}
                </AppProvider>
            </body>
        </html>
    );
}

Step 5: Using Your New Context! (usage-examples.tsx)

Setup complete! Now for the fun part: using it.

In any component that's a child of AppProvider, you can now use your custom useAppContext hook to get access to the state and the dispatch function.

Here are a few examples of how you might read data and dispatch actions.

app/usage-examples.tsx

import React from 'react';
import { useAppContext } from '@/contexts/appContext';

export const UsageExamples = () => {
    const { state, dispatch } = useAppContext();

    // --- Accessing State Data ---
    const currentTheme = state.theme; // 'light' or 'dark'
    const isLoggedIn = state.userData.email !== '';
    const usdWallet = state.wallets.find(wallet => wallet.currency === 'USD');

    // --- Dispatching Actions ---

    // Toggle between light and dark theme
    const toggleTheme = () => {
        const newTheme = state.theme === 'light' ? 'dark' : 'light';
        dispatch({
            type: 'SET_THEME',
            payload: newTheme
        });
    };

    // Set user data when logging in
    const loginUser = () => {
        dispatch({
            type: 'LOGIN_USER',
            payload: {
                firstName: 'John',
                lastName: 'Doe',
                email: 'john.doe@example.com'
            }
        });
        // Try sending the wrong payload and see TypeScript complain!
        // dispatch({ type: 'LOGIN_USER', payload: 'wrong data' });
    };

    // Add a new wallet
    const addWallet = () => {
        dispatch({
            type: 'ADD_WALLET',
            payload: {
                currency: 'ETH',
                availableBalance: 2.5,
                pendingBalance: 0.1
            }
        });
    };

    // Remove wallet by currency
    const removeWallet = () => {
        dispatch({
            type: 'REMOVE_WALLET',
            payload: 'BTC' // Payload is just a string, as we defined!
        });
    };

    // ... other functions

    return (
        <div>
            <h2>Welcome, {isLoggedIn ? state.userData.firstName : 'Guest'}!</h2>
            <p>Current Theme: {currentTheme}</p>
            <button onClick={toggleTheme}>Toggle Theme</button>
            <button onClick={loginUser}>Login</button>
            {/* ... other UI elements */}
        </div>
    );
};

Bonus: How to Persist State on Refresh?

You're right, there's one problem. If you refresh the page, all your state disappears! We can solve this by syncing our state with the browser's localStorage.

Here is an enhanced version of appContext.tsx that saves the state to localStorage whenever it changes and loads it back on the initial render. This uses the logic from your appContextWithPersistence.tsx file.

contexts/appContext.tsx

import React, { createContext, useContext, useReducer, useEffect, ReactNode } from 'react';
import { ContextStateType, ContextActionTypes, ContextValueType } from './reducerTypes';
import { reducer, initialState } from './reducer';

const AppContext = createContext<ContextValueType | undefined>(undefined);

// Helper function to get initial state from localStorage
const getPersistedState = (): ContextStateType => {
    if (typeof window === 'undefined') {
        return initialState; // Default for server-side rendering
    }
    try {
        const theme = localStorage.getItem('app_theme') as 'light' | 'dark' || initialState.theme;
        const selectedCurrency = localStorage.getItem('app_selectedCurrency') || initialState.selectedCurrency;
        const userData = JSON.parse(localStorage.getItem('app_userData') || 'null') || initialState.userData;
        const wallets = JSON.parse(localStorage.getItem('app_wallets') || 'null') || initialState.wallets;

        return {
            ...initialState, // Start with defaults
            theme,
            selectedCurrency,
            userData,
            wallets,
        };
    } catch (error) {
        console.error('Error loading persisted state:', error);
        return initialState;
    }
};

// Helper function to save state to localStorage
const saveToStorage = (state: ContextStateType) => {
    if (typeof window === 'undefined') return;
    try {
        localStorage.setItem('app_theme', state.theme);
        localStorage.setItem('app_selectedCurrency', state.selectedCurrency);
        localStorage.setItem('app_userData', JSON.stringify(state.userData));
        localStorage.setItem('app_wallets', JSON.stringify(state.wallets));
    } catch (error) {
        console.error('Error saving state to localStorage:', error);
    }
};

export const AppProvider: React.FC<{ children: ReactNode }> = ({ children }) => {
    // Pass the getPersistedState function as the third argument to useReducer
    const [state, dispatch] = useReducer(reducer, initialState, getPersistedState);

    // Save state to localStorage whenever it changes
    useEffect(() => {
        saveToStorage(state);
    }, [state]);

    return (
        <AppContext.Provider value={{ state, dispatch }}>
            {children}
        </AppContext.Provider>
    );
};

export const useAppContext = (): ContextValueType => {
    const context = useContext(AppContext);
    if (context === undefined) {
        throw new Error('useAppContext must be used within an AppProvider');
    }
    return context;
};

Key changes:

A getPersistedState function lazy-initializes our reducer's state with data from localStorage. We pass it as the third argument to useReducer.
A saveToStorage function is called inside a useEffect hook that listens for any changes to the state object. When a change occurs, it saves the new state to localStorage. We've also taken care not to persist sensitive data like an authentication token by always starting with the initialState.

To use this, you would simply import AppProvider from this persistence file instead of the original appContext.tsx in your layout.tsx.

Download full code on my GitHub repo

Conclusion

And there you have it! You've successfully built a robust, type-safe, and maintainable state management solution using only React's built-in tools and TypeScript.

While state management libraries like Redux, Zustand, and Jotai have their place, especially in very large-scale applications, this useContext + useReducer pattern is often more than enough. It gives you centralized logic, predictable state transitions, and top-tier developer experience thanks to TypeScript, all without adding another dependency to your project.

Happy coding!

This article was crafted with care by Samuel Owolabi. Find more of his work on his portfolio.