DEV Community: James Mogambi

🚀 Deploy Next.js 16 on cPanel Without a VPS!

James Mogambi — Sat, 25 Jul 2026 15:12:40 +0000

James Mogambi

Jul 25

How to Deploy Next.js 16 on cPanel Using Standalone Build (Step-by-Step Guide)

#node #nextjs #cpanel #webdev

6 min read

How to Deploy Next.js 16 on cPanel Using Standalone Build (Step-by-Step Guide)

James Mogambi — Sat, 25 Jul 2026 14:25:24 +0000

A step-by-step walkthrough for deploying your Next.js 16 application on cPanel shared hosting with the standalone output feature

Introduction

If you've built a Next.js 16 application and want to host it on cPanel, you've probably noticed that traditional cPanel hosting wasn't designed for modern React frameworks. Unlike static HTML sites or PHP applications, Next.js requires a Node.js runtime to handle server-side rendering, API routes, and other dynamic features.

The good news? It's absolutely possible to deploy Next.js 16 on cPanel. And the best way to do it is using Next.js's standalone output feature.

In this guide, I'll walk you through every step of the process—from configuring your application to making it live on your cPanel hosting. No prior experience with Node.js deployment on cPanel? No problem. I've got you covered.

Why Choose the Standalone Build?

Before we dive into the technical steps, let's understand why the standalone approach is your best bet for cPanel deployment.

What is a Standalone Build?

In Next.js 14 and above, the framework introduced a game-changing build feature: output: "standalone". When you enable this, Next.js creates a self-contained deployment package that includes:

Your built application code
Only the essential dependencies (not all of node_modules)
A minimal server.js entry point
All necessary runtime files

Benefits Over Traditional Deployment

Smaller deployment package (50–100 MB vs. 300–500 MB).
Minimal dependencies bundled with the application.
Simpler deployment—upload and run without installing packages.
Faster application startup.
Higher compatibility with shared cPanel hosting.
Lower maintenance effort and easier updates.

For cPanel shared hosting, where storage and resources are often limited, the standalone build is a lifesaver. It fits within the constraints while still delivering the full Next.js experience.

Before You Begin

Ensure you have the following ready before deploying:

A local development machine with Node.js 20 or later installed.
A Next.js 16 application (this guide also works with Next.js 14 and 15).
Access to your cPanel account with the "Setup Node.js App" feature enabled.
Node.js 20+ installed on your hosting server (verify this with your hosting provider).
A file upload method, such as cPanel File Manager or an FTP client.
A domain or subdomain where your Next.js application will be hosted.

Step-by-Step Deployment Guide

Let's get down to business. I'll break this down into eight clear steps.

Step 1: Configure next.config.js

The first thing you need to do is tell Next.js that you want a standalone build. Open your next.config.js (or next.config.ts if you're using TYpescript) and add the output: "standalone" option.

Open your next.config.js (or next.config.ts if you're using TypeScript) and add the output: "standalone" option:

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: "standalone",

  // If you're using remote images
  images: {
    remotePatterns: [
      {
        protocol: "https",
        hostname: "**",
      },
    ],
  },

  // Your other config options here
};

module.exports = nextConfig;

What this does: This tells Next.js to build your application in standalone mode, packaging everything needed for deployment into the ".next/standalone" folder.

Step 2: Update package.json

While not strictly necessary, it's good practice to update your package.json scripts to reflect the standalone build.

{
  "name": "your-app-name",
  "version": "1.0.0",
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "node server.js",
    "lint": "next lint"
  },
  "dependencies": {
    "next": "^16.0.0",
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  }
}

Notice the start script now points to node server.js instead of next start. This is crucial because we'll be using the standalone server.

Step 3: Build Your Application Locally

Now it's time to build the application. Open your terminal, navigate to your project root, and run:

npm run build

This process may take a few minutes, depending on your application's size. Once complete, you'll see a success message along with the build output.

After the build completes, look inside your project folder. You'll notice a new .next directory with the following structure:

Step 4: Prepare the Standalone Deployment Package

Here's the most important part—and the most common point of confusion.

The Next.js build process places your static assets in .next/static, while the standalone server files are in .next/standalone. For a complete deployment, you need to merge these together.

4.1 Create Your Deployment Folder
First, create a new folder (I'll call it deploy for clarity):
mkdir deploy

4.2 Copy the Standalone Files
Copy everything from .next/standalone/ into your deploy folder:

On Mac/Linux

cp -r .next/standalone/* deploy/

On Windows (PowerShell)

Copy-Item -Recurse -Path ".next\standalone\*" -Destination "deploy\"

4.3 Copy the Static Files (CRITICAL STEP)
This is the step that many developers miss. The static files need to be inside the .next folder of your deployment/standalone package:

On Mac/Linux

cp -r .next/static deploy/.next/static

On Windows (PowerShell)

Copy-Item -Recurse -Path ".next\static" -Destination "deploy\.next\static"

4.4 Copy Your Public Folder
If your application uses a public folder for assets like images, favicons, or robots.txt, copy it as well:

On Mac/Linux

cp -r public deploy/public

On Windows (PowerShell)

Copy-Item -Recurse -Path "public" -Destination "deploy\public"

4.5 Copy package.json
Having package.json in the deployment helps with debugging and references:

cp package.json deploy/

4.6 Your Final Structure
Your deploy folder should now look like this:

4.7 Create the ZIP Archive
Compress the entire deploy folder into a ZIP file:

zip -r deploy.zip deploy/

Why ZIP? cPanel's file manager has a built-in extractor for ZIP files, making uploads much faster than transferring individual files via FTP

Step 5: Upload to cPanel

Now that you have your deploy.zip file, it's time to get it onto your server.
Upload Using cPanel File Manager

Log in to your cPanel account.
Open File Manager.
Navigate to your application's target directory (or create one where ypu files will stay).
Upload the deploy.zip file.
Wait for the upload to finish.
Extract the ZIP archive.
Move the extracted files from the deploy folder into the target directory if necessary.

Important: After extraction, the folder structure should be:

Step 6: Configure Node.js App in cPanel

This is where the magic happens—telling cPanel to run your Next.js application as a Node.js service.

6.1 Access the Setup Node.js App Tool
In cPanel, scroll to the Software section
Click on Setup Node.js App (sometimes called "Node.js Selector" or "Node.js")

6.2 Create a New Application
Click the +CREATE APPLICATION button. You'll see a form with several fields.

6.3 Fill in Application Settings

When setting up your Node.js app in cPanel, use these settings:

Node.js version: 20.x or higher
Application mode: Production
Application root: The folder where you extracted your app files
Application URL: Your domain or subdomain
Startup file: server.js

6.4 Save and Create
Click the CREATE button at the bottom of the form. cPanel will now:

Set up the application
Create the necessary Node.js environment
Attempt to start your application

Step 7: Start and Verify Your Application

After creating the application, you'll be taken to the application management page.

7.1 Start the Application
If the application says "Stopped", click the START APP button
If it says "Running", you're good to go
If it's in an error state, check the logs (more on this below)

7.2 Test Your Application
Open a new browser window
Navigate to your application URL
Your Next.js 16 app should load!
Check these key features:

✅ Homepage loads correctly
✅ Navigation between pages works
✅ API routes are functional
✅ Dynamic routes (if any) resolve correctly
✅ Images and static assets load

7.3 Monitor the Application
From the application management page, you can:
View logs – Check the Log button to see application output
Restart app – If you make changes or encounter issues
Edit settings – Update environment variables or configuration

Conclusion

Deploying a Next.js 16 application on cPanel might seem daunting at first, especially given that traditional shared hosting wasn't built with modern JavaScript frameworks in mind. However, as this guide has demonstrated, the standalone output feature makes it not just possible, but surprisingly straightforward.

The standalone build approach solves the core challenges of cPanel deployment—limited storage, restricted resources, and lack of native Node.js support—by creating a lightweight, self-contained package that runs efficiently within these constraints. No more struggling with massive node_modules folders or complex dependency installations on the server.

How to Install Ubuntu on Your Laptop or Desktop: A Step-by-Step Guide

James Mogambi — Sun, 19 Oct 2025 10:19:37 +0000

Ready to switch to a free, secure, and customizable operating system? Ubuntu, one of the most popular Linux distributions, is perfect for beginners and pros alike. Whether you’re tired of Windows, want a lightweight OS for an old laptop, or need a powerful system for coding, Ubuntu has you covered. In this step-by-step guide, we’ll walk you through installing Ubuntu 24.04 LTS on your laptop or desktop, from downlosading the installer to setting up your new system. Don’t worry if you’re new to Linux — we’ll keep it simple and include screenshots to guide you. Let’s get started!

Why Choose Ubuntu?

Before we dive in, here’s why Ubuntu might be the right choice for you:

Free and Open Source – No licensing fees or restrictions.
Secure and Private – Built-in security features and fewer malware risks.
Lightweight and Fast – Ideal for older hardware or performance enthusiasts.
Software Center – Easy access to thousands of free apps.
Large Community Support – Tons of tutorials, forums, and updates.

What You’ll Need

Before you begin the installation, make sure you have the following:

A USB flash drive (at least 4GB)
A stable internet connection
A laptop or desktop (64-bit architecture recommended)
Backed-up data (Ubuntu installation may erase your files)

Step 1: Download Ubuntu ISO

Go to the official Ubuntu website
Choose the version you want (the latest LTS is recommended for most users).
Click Download to get the ISO file (~5.9GB in size).

Step 2: Create a Bootable USB Drive

You’ll need a tool to turn the ISO into a bootable USB. Popular options:

For Windows: Use Rufus
For macOS: Use Etcher
For Linux: Use the Startup Disk Creator or dd command

For this tutorial i'll use Windows(Rufus) , feel free to use your OS

Instructions using Rufus (Windows):

Insert your USB drive.
Launch Rufus and select your USB under Device.
Click Select and choose the Ubuntu ISO file.
Leave other settings as default and click Start.
Wait for the process to complete.

Important! For the partition scheme, select GPT if you are using a newer computer. Otherwise, go with MBR.

Step 3: Boot from USB

Restart your computer.
Enter the boot menu by pressing the key specific to your system (usually F2, F12, Esc, or Del).
This will bring up a menu where you can manually select the USB device to boot.

Note: The F12 key is often used to access the boot menu, but sometimes Escape, F2, or F10 can also do the job. If you're not sure which key to use, keep an eye out for a quick message when your computer starts up. This message will usually tell you which key you need to press to open the boot menu.

Step 4: Installation Setup

During the installation process, you’ll be guided through several setup steps:

Keyboard Layout

Choose your preferred language and keyboard layout.

Updates and Other Software

You can choose to install third-party software (recommended for Wi-Fi, graphics, etc.).

Installation Type

Choose one of the following:

Erase disk and install Ubuntu – Wipes your entire disk (be careful!).
Install Ubuntu alongside Windows – Dual-boot option.
Something else – Manual partitioning for advanced users.

⚠️ Important: Make sure your data is backed up if choosing to erase the disk.

Time Zone

Select your location.

User Details

Enter your name, computer name, username, and password.
Click Continue to start the installation.

Step 5: Wait for Installation to Complete

Ubuntu will now install. This process may take 15–30 minutes depending on your hardware. Once complete, you’ll be prompted to restart your computer.

Remove the USB drive when instructed and press Enter.

Step 6: Welcome to Ubuntu!

After rebooting, you’ll land on the Ubuntu desktop. From here, you can:

Connect to Wi-Fi
Explore the Ubuntu Software Center
Install essential apps (e.g., Firefox, LibreOffice, VS Code)
Customize your desktop environment

Post-Installation Tips

To make the most of your new Ubuntu system:

Run Updates: Open a terminal and run:

sudo apt update && sudo apt upgrade

💬 Final Thoughts

Installing Ubuntu is a great step towards a faster, more secure, and more customizable computing experience. Whether you're a curious beginner or a seasoned developer, Ubuntu has the flexibility and power to meet your needs.

With this guide, you’re equipped to install Ubuntu like a pro. Don't be afraid to explore and make it your own. The open-source world awaits!

Have questions or ran into issues? Drop them in the comments—we’re here to help!
`

Step-by-Step Guide to M-Pesa STK Push in React Native with Daraja API

James Mogambi — Tue, 07 Oct 2025 20:03:12 +0000

Mobile payments are the heartbeat of Kenya’s digital economy, and M-Pesa is the undisputed king. If you’re building a mobile app with React Native or Expo, integrating Safaricom’s Daraja API for Lipa na M-Pesa Online can unlock seamless payments for your users.

In this guide, we’ll walk through how to set up a simple Express backend to handle the Daraja API and a React Native frontend to trigger STK Push payments.

What is STK Push?

STK Push leverages the SIM Application Toolkit to send a prompt directly to a customer’s phone, asking them to enter their M-Pesa PIN to complete a payment. It eliminates the need for customers to remember paybill numbers, account numbers, or transaction codes, significantly reducing friction in the payment process.

What You’ll Need:

A Safaricom Daraja API account: Sign up here
Node.js and Express installed
React Native development environment (Expo)
Ngrok (for exposing your local backend to Safaricom’s Callback).

Step 1: Set Up the Express Backend

Create a new folder and initialize your Node project:


mkdir backend
cd backend
npm init -y
npm install express axios  dotenv

Here’s what each module does:

express → A popular Node.js framework for building web servers and APIs. We use it to create endpoints like /stkpush (to initiate payments) and /callback (to handle responses from Safaricom).
axios → A promise-based HTTP client. It makes it easy to send requests to the M-Pesa Daraja API (e.g., requesting an access token or triggering an STK push).
dotenv → A module that loads environment variables from a .env file into process.env. This allows us to securely store sensitive credentials like the Consumer Key, Consumer Secret, Shortcode, and Passkey outside our codebase.

Create a ‘.env’ file for your credentials


MPESA_CONSUMER_KEY=your-consumer-key
MPESA_CONSUMER_SECRET=your-consumer-secret
MPESA_SHORTCODE=174379
MPESA_PASSKEY=your-passkey
CALLBACK_URL= https://your-ngrok-url/callback

To integrate with the M-Pesa Daraja API, you first need to obtain your credentials from the Safaricom Daraja Developer Portal. Start by logging in and navigating to the My Apps tab, where you can create a new app. While creating the app, select Lipa na M-Pesa Sandbox and M-Pesa Sandbox as the API products. Once the app is created, you will be provided with a Consumer Key and Consumer Secret, which you should copy and save securely in your .env file.

The Consumer Key and Consumer Secret are used for authentication with the M-Pesa Daraja API.

Next, go to the APIs tab, and under M-Pesa Express , you will find a Shortcode and Passkey for sandbox testing.

On the Simulator page (as shown in the screenshot below), you’ll see the Shortcode (listed as Party B) together with the Passkey. Make sure to copy both values and save them securely in your .env file.

These credentials are meant for the sandbox environment to allow you to test payments. When moving your application to production, Safaricom will provide you with a new set of credentials for the live environment once your application is approved.

Create server.js


import express from "express";
import axios from "axios";
import dotenv from "dotenv";

dotenv.config();
const app = express();
app.use(express.json());

const getAccessToken = async () => {
  try {
    const url =
      "https://sandbox.safaricom.co.ke/oauth/v1/generate?grant_type=client_credentials";
    const auth = Buffer.from(
      `${process.env.MPESA_CONSUMER_KEY}:${process.env.MPESA_CONSUMER_SECRET}`
    ).toString("base64");

    const response = await axios.get(url, {
      headers: {
        Authorization: `Basic ${auth}`,
      },
    });
    return response.data.access_token;
  } catch (error) {
    console.error("Error getting access token:", error);
    throw error;
  }
};

const getPassword = (timestamp) => {
  const shortCode = process.env.MPESA_SHORTCODE;
  const passKey = process.env.MPESA_PASSKEY;
  const password = `${shortCode}${passKey}${timestamp}`;
  return Buffer.from(password).toString("base64");
};

const getTimestamp = () => {
  const date = new Date();
  const year = date.getFullYear();
  const month = String(date.getMonth() + 1).padStart(2, "0");
  const day = String(date.getDate()).padStart(2, "0");
  const hours = String(date.getHours()).padStart(2, "0");
  const minutes = String(date.getMinutes()).padStart(2, "0");
  const seconds = String(date.getSeconds()).padStart(2, "0");

  return `${year}${month}${day}${hours}${minutes}${seconds}`;
};

// @api triggers stk push via lipa-na-mpesa-online
// default shortcode for development/sandbox environment is 174379
app.post("/stkpush", async (req, res) => {
  try {
    const { phoneNumber, amount } = req.body;
    const token = await getAccessToken();

    // Format phone number (remove leading 0 or +254)
    let formattedPhone = phoneNumber;
    if (phoneNumber.startsWith("0")) {
      formattedPhone = `254${phoneNumber.slice(1)}`;
    } else if (phoneNumber.startsWith("+254")) {
      formattedPhone = phoneNumber.slice(1);
    }

    // Prepare STK Push request
    const timestamp = getTimestamp();
    const password = getPassword(timestamp);
    const shortCode = process.env.MPESA_SHORTCODE;

    const url =
      "https://sandbox.safaricom.co.ke/mpesa/stkpush/v1/processrequest";

    const data = {
      BusinessShortCode: shortCode,
      Password: password,
      Timestamp: timestamp,
      TransactionType: "CustomerPayBillOnline",
      Amount: amount,
      PartyA: formattedPhone,
      PartyB: shortCode,
      PhoneNumber: formattedPhone,
      CallBackURL: process.env.CALLBACK_URL,
      AccountReference: "Test Payment",
      TransactionDesc: "Test Payment",
    };

// Make STK Push request
    const stkRes = await axios.post(url, data, {
      headers: {
        Authorization: `Bearer ${token}`,
        "Content-Type": "application/json",
      },
    });

    res.json(stkRes.data);
  } catch (err) {
    console.error(err.response?.data || err.message);
    res.status(500).json({ error: "Payment initiation failed" });
  }

// this callback is called upon successful transaction
app.post("/callback", (req, res) => {
  console.log("STK Callback response:", JSON.stringify(req.body));

  // Extract info from callback
  const callbackData = req.body.Body.stkCallback;

  // Always respond to Safaricom with a success to acknowledge receipt
  res.json({ ResultCode: 0, ResultDesc: "Accepted" });

  // Process the callback data as needed for your application
  if (callbackData.ResultCode === 0) {
    // Payment successful
    const transactionDetails = callbackData.CallbackMetadata.Item;
    // Process the successful payment
    console.log("Payment successful");

    // In production application, you would:
    // 1. Update your database
    // 2. Fulfill the order
    // 3. Notify the customer
    // etc.
  } else {
    // Payment failed
    console.log("Payment failed:", callbackData.ResultDesc);
  }
});

app.listen(3000, () => console.log("Server running on

This code sets up an Express.js server that integrates with Safaricom’s M-Pesa Daraja API to handle STK Push (Lipa Na M-Pesa Online) payments.

It authenticates with M-Pesa by generating an OAuth access token using the consumer key and secret.
It builds a secure password using the business shortcode, passkey, and a timestamp (required by Daraja).
The /stkpush endpoint allows clients to initiate a payment by sending a phone number and amount, which triggers the STK push request to the customer’s phone.
Phone numbers are formatted into the required 2547XXXXXXXX format before sending the request.
M-Pesa then sends the transaction results (success or failure) to the /callback endpoint.
The server acknowledges the callback and can process successful payments (e.g., update a database, confirm an order, or notify the user).

To start the Express backend, run:


node server.js

Use Ngrok to expose your local server:


ngrok http 3000

Using ngrok ensures your local development environment behaves just like a live server, making it easier to test and debug the full payment flow before deploying to production.

Update environment variable CALLBACK_URL your .env file with the Ngrok URL.

Your .env file should be similar to this:


MPESA_CONSUMER_KEY=your-consumer-key
MPESA_CONSUMER_SECRET=your-consumer-secret
MPESA_SHORTCODE=174379
MPESA_PASSKEY=your-passkey
CALLBACK_URL= https://your-ngrok-url/callback

Step 2: React Native Frontend

Create a new React Native project:


npx create-expo-app@latest
cd frontend
npm install axios

In app/(tabs)/index.js:

This React Native screen creates the mobile user interface for initiating an M-Pesa STK Push payment.

It uses React hooks (useState) to manage input values for the phone number, amount, and a loading state when submitting the payment.
The form has two input fields: Phone number (formatted as 2547XXXXXXXX) and Amount to pay.

When the user taps “Pay Now”, the initiatePayment function runs:

It makes a POST request to the backend /stkpush endpoint (exposed through an ngrok URL).
If successful, it alerts the user to check their phone for the M-Pesa popup.
If there’s an error, it shows a failure alert.
While the request is processing, the button is disabled and shows a loading spinner (ActivityIndicator) instead of text.
The screen design uses some custom UI components (ParallaxScrollView, ThemedText, ThemedView) for styling, plus a nice animated React logo header.

// app/(tabs)/index.js
import { Image } from "expo-image";
import {
  ActivityIndicator,
  Alert,
  StyleSheet,
  Text,
  TextInput,
  TouchableOpacity,
  View,
} from "react-native";

import { HelloWave } from "@/components/HelloWave";
import ParallaxScrollView from "@/components/ParallaxScrollView";
import { ThemedText } from "@/components/ThemedText";
import { ThemedView } from "@/components/ThemedView";
import { useState } from "react";

export default function HomeScreen() {
  const [phoneNumber, setPhoneNumber] = useState("");
  const [amount, setAmount] = useState("");
  const [loading, setLoading] = useState(false);

  const initiatePayment = async () => {
    // Validate inputs first
    if (!phoneNumber || !amount) {
      Alert.alert("Missing Info", "Please enter both phone number and amount.");
      return;
    }

    setLoading(true);
    try {
      const response = await fetch(
        "https://your-ngrok-url/stkpush",
        {
          method: "POST",
          headers: {
            "Content-Type": "application/json",
          },
          body: JSON.stringify({
            phoneNumber: phoneNumber.replace("+", ""),
            amount,
          }),
        }
      );

      if (!response.ok) {
        throw new Error(`HTTP error! Status: ${response.status}`);
      }

const data = await response.json();
      Alert.alert("Success", "STK Push initiated. Check your phone.");
      console.log(data);
    } catch (error) {
      Alert.alert("Error", "Failed to initiate payment.");
      console.error(error);
    } finally {
      setLoading(false);
    }
  };

return (
    <ParallaxScrollView
      headerBackgroundColor={{ light: "#A1CEDC", dark: "#1D3D47" }}
      headerImage={
        <Image
          source={require("@/assets/images/partial-react-logo.png")}
          style={styles.reactLogo}
        />
      }
    >
      <ThemedView style={styles.titleContainer}>
        <ThemedText type="title">Welcome!</ThemedText>
        <HelloWave />
      </ThemedView>
      <ThemedView style={styles.stepContainer}>
        <View style={styles.container}>
          <Text style={styles.title}>Lipa na M-Pesa Online</Text>
          <TextInput
            style={styles.input}
            placeholder="Phone Number (e.g., 2547XXXXXXXX)"
            value={phoneNumber}
            onChangeText={setPhoneNumber}
            keyboardType="phone-pad"
          />
          <TextInput
            style={styles.input}
            placeholder="Amount"
            value={amount}
            onChangeText={setAmount}
            keyboardType="numeric"
          />

          <TouchableOpacity
            style={[styles.btn, loading && { opacity: 0.6 }]}
            onPress={initiatePayment}
            disabled={loading}
          >
            {loading ? (
              <ActivityIndicator color="#fff" />
            ) : (
              <Text style={styles.btnText}>Pay Now</Text>
            )}
          </TouchableOpacity>
        </View>
      </ThemedView>
    </ParallaxScrollView>
  );
}

const styles = StyleSheet.create({
  titleContainer: {
    flexDirection: "row",
    alignItems: "center",
    gap: 8,
  },
  stepContainer: {
    gap: 8,
    marginBottom: 8,
  },
  reactLogo: {
    height: 178,
    width: 290,
    bottom: 0,
    left: 0,
    position: "absolute",
  },
  container: { flex: 1, padding: 20, justifyContent: "center" },
  title: {
    fontSize: 24,
    fontWeight: "bold",
    marginBottom: 20,
    textAlign: "center",
  },
  input: {
    borderWidth: 1,
    borderColor: "#ccc",
    padding: 10,
    marginBottom: 10,
    borderRadius: 5,
  },

  btn: {
    backgroundColor: "#0A84FF",
    paddingVertical: 15,
    borderRadius: 8,
    alignItems: "center",
    width: "100%",
    marginTop: 10,
  },
  btnText: {
    color: "#fff",
    fontSize: 16,
    fontWeight: "600",
  },
});

To run the mobile app, we use Expo CLI. After installing it globally with npm install -g expo-cli, start the project by running npx expo start. This opens the Expo Developer Tools and shows a QR code you can scan using the Expo Go app on your phone, or you can launch the app directly on an Android emulator (a) or iOS simulator (i). Expo takes care of bundling and live reloading, so you can instantly see changes as you develop.

Remember to replace your Ngrok endpoint for the fetch operation to work appropriately.

Step 3: Test the Integration

Launch your backend and frontend.
Use a valid Safaricom number in sandbox format (e.g., 2547XXXXXXXX).
Watch your phone for the STK Push prompt.
Check your backend logs for the callback.

Conclusion

You’ve just built a working M-Pesa payment flow using Daraja API, Express, and React Native. This setup is perfect for e-commerce, service apps, or any platform that needs mobile payments that need to integrate mpesa payments.

Mastering State Management in React Native with Zustand: A Modern Guide.

James Mogambi — Tue, 07 Oct 2025 10:43:57 +0000

State management is a cornerstone of building robust React Native(RN) apps, but it’s often a source of complexity and performance bottlenecks, especially on resource-constrained mobile devices. Redux, once the gold standard, can feel like overkill with its boilerplate and heavy dependencies. Enter Zustand, a lightweight, hook-based state management library that’s taking the RN community by storm in 2025. With React Native 0.80 and 0.81 pushing modern architectures like Fabric and Hermes, Zustand’s simplicity and performance make it a perfect fit for mobile apps.

In this article, we’ll dive deep into using Zustand in React Native. You’ll learn how to set it up, build a real-world to-do app, add persistence for offline support, and optimize performance. We’ll also compare Zustand to Redux with benchmarks and share best practices to avoid common pitfalls. Whether you’re prototyping a startup app or scaling an enterprise project, this guide will equip you to leverage Zustand effectively. Let’s get started!

Why Zustand for React Native

Zustand, created by the team behind Jotai, is a minimal state management library that uses a single store and hooks to manage state. Unlike Redux, it requires no providers or complex setup, and its fine-grained updates minimize re-renders, making it ideal for React Native’s performance-sensitive environment. Here’s why Zustand is trending :

Lightweight: 2KB minified vs. Redux’s ~20KB (with middleware).
Simple API: Hook-based with no boilerplate, perfect for rapid prototyping.
Performance: Selective re-renders ensure only components using specific state slices update.
TypeScript Support: First-class TypeScript integration for type-safe stores.
RN Compatibility: Works seamlessly with Hermes (RN’s default JS engine since 0.80) and Fabric’s concurrent rendering.

With developers on X praising Zustand for “buttery-smooth” updates and “no-boilerplate” setup, it’s clear why it’s a go-to for modern RN apps. Let’s see it in action.

Setting Up Zustand in a React Native App

To demonstrate Zustand’s power, we’ll build a simple to-do list app in React Native. The app will let users add tasks, toggle completion, and persist data for offline use. Let’s start with setup.

Step 1: Initialize Your Project

Create a new React Native app using Expo (or npx react-native init for bare RN):


npx create-expo-app@latest ZustandTodoApp
cd ZustandTodoApp

Install Zustand

npm install zustand

Step 2: Create a Zustand Store

Zustand uses a single create function to define a store. Let’s create a store for our to-do app in src/store.ts:


// src/store.ts
import { create } from 'zustand';

interface Todo {
  id: number;
  text: string;
  completed: boolean;
}

interface TodoState {
  todos: Todo[];
  addTodo: (text: string) => void;
  toggleTodo: (id: number) => void;
}

export const useTodoStore = create<TodoState>((set) => ({
  todos: [],
  addTodo: (text) =>
    set((state) => ({
      todos: [...state.todos, { id: Date.now(), text, completed: false }],
    })),
  toggleTodo: (id) =>
    set((state) => ({
      todos: state.todos.map((todo) =>
        todo.id === id ? { ...todo, completed: !todo.completed } : todo
      ),
    })),
}));

This store defines:

A todos array to hold tasks. — An addTodo action to append new tasks. — A toggleTodo action to mark tasks as completed.

Notice the TypeScript interface for type safety and the use of set with immutable updates, which ensures predictable state changes.

Step 3: Build the UI

Let’s create a simple UI in index.tsx to interact with the store:


import React, { useState } from ‘react’;
import { View, Text, TextInput, Button, TouchableOpacity, StyleSheet } from ‘react-native’;
import { useTodoStore } from ‘./src/store’;

export default function App() {
  const [input, setInput] = useState(‘’);
  const { todos, addTodo, toggleTodo } = useTodoStore();

  return (
    <View style={styles.container}>
      <TextInput
        style={styles.input}
        value={input}
        onChangeText={setInput}
        placeholder="Enter a task"
      />
      <Button title="Add Todo" onPress={() => { addTodo(input); setInput(‘’); }} />
      {todos.map((todo) => (
        <TouchableOpacity key={todo.id} onPress={() => toggleTodo(todo.id)}>
          <Text
            style={[
              styles.todo,
              { textDecorationLine: todo.completed ? ‘line-through’ : ‘none’ },
            ]}
          >
            {todo.text}
          </Text>
        </TouchableOpacity>
      ))}
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, padding: 20 },
  input: { borderWidth: 1, padding: 10, marginBottom: 10 },
  todo: { fontSize: 18, marginVertical: 5 },
});

Run the app with npx expo start. You now have a functional to-do list that adds and toggles tasks, powered by Zustand. The store’s simplicity shines — no providers, no connect HOCs, just hooks.

Adding Persistence for Offline Support

Mobile apps often need offline capabilities, and Zustand makes this easy with its persist middleware. Let’s add persistence using @react-native-async-storage/async-storage to save todos across app restarts.

Step 1: Install AsyncStorage


npm install @react-native-async-storage/async-storage

Step 2: Update the Store

Modify src/store.ts to include persistence:


import { create } from 'zustand';
import { persist, createJSONStorage } from 'zustand/middleware';
import AsyncStorage from '@react-native-async-storage/async-storage';

interface Todo {
  id: number;
  text: string;
  completed: boolean;
}

interface TodoState {
  todos: Todo[];
  addTodo: (text: string) => void;
  toggleTodo: (id: number) => void;
}

export const useTodoStore = create<TodoState>()(
  persist(
    (set) => ({
      todos: [],
      addTodo: (text) =>
        set((state) => ({
          todos: [...state.todos, { id: Date.now(), text, completed: false }],
        })),
      toggleTodo: (id) =>
        set((state) => ({
          todos: state.todos.map((todo) =>
            todo.id === id ? { ...todo, completed: !todo.completed } : todo
          ),
        })),
    }),
    {
      name: 'todo-storage', // Key in AsyncStorage
      storage: createJSONStorage(() => AsyncStorage),
    }
  )
);

The persist middleware saves the store’s state to AsyncStorage and rehydrates it on app start. Test it by adding todos, closing the app, and reopening — it’ll retain your tasks.

Step 3: Handle Persistence Caveats

Storage Limits: AsyncStorage has a ~6MB limit on iOS. For large datasets, consider splitting stores or using SQLite.
Performance: Persisting every state change can be costly. Use partialize to persist only specific fields


persist(
    (set) => ({ ... }), // Same as above
    {
      name: 'todo-storage',
      storage: createJSONStorage(() => AsyncStorage),
      partialize: (state) => ({ todos: state.todos }), // Only persist todos
    }
  )

Optimizing Performance with Selectors

Zustand’s fine-grained updates prevent unnecessary re-renders, but you can optimize further with selectors. For example, if you only need completed todos, avoid subscribing to the entire store:


const completedTodos = useTodoStore((state) => state.todos.filter((todo) => todo.completed));

return (
  <View>
    <Text>Completed Todos: {completedTodos.length}</Text>
    {completedTodos.map((todo) => (
      <Text key={todo.id}>{todo.text}</Text>
    ))}
  </View>
);

This ensures the component only re-renders when completedTodos changes, not when new todos are added. For large lists, this can cut re-renders by 50% or more, critical for low-end devices.

Zustand vs. Redux: A Performance Comparison

To understand Zustand’s edge, let’s compare it to Redux in a React Native app with a 1000-item list. We’ll measure re-renders and CPU usage on a mid-range Android device (e.g., Android 10 emulator).

Setup

Using zustand store


import {create} from zustand

const useListStore = create((set) => ({
    items: Array.from({ length: 1000 }, (_, i) => ({ id: i, text: `Item ${i}` })),
    updateItem: (id, text) => set((state) => ({
      items: state.items.map((item) => (item.id === id ? { ...item, text } : item)),
    })),
  }));

Redux Setup(using @reduxjs/toolkit):


import { createSlice } from '@reduxjs/toolkit';
import { configureStore } from '@reduxjs/toolkit';

  const listSlice = createSlice({
    name: 'list',
    initialState: { items: Array.from({ length: 1000 }, (_, i) => ({ id: i, text: `Item ${i}` })) },
    reducers: {
      updateItem: (state, action) => {
        state.items = state.items.map((item) =>
          item.id === action.payload.id ? { ...item, text: action.payload.text } : item
        );
      },
    },
  });

  const store = configureStore({ reducer: listSlice.reducer });

Test Scenario

Update one item and measure:

Re-renders: Using React Native Debugger’s component inspector.
CPU Usage: Via Flipper’s performance monitor.

Results

Zustand

Re-renders: Only components using the updated item re-render (1–2 components).
CPU Usage: ~10% lower due to no middleware overhead.
Bundle Size: ~2KB.

Redux

Re-renders: All connected components re-render unless optimized with reselect.
CPU Usage: Higher due to dispatching and middleware (e.g., Redux Thunk).
Bundle Size: ~20KB with middleware.

Verdict: Zustand is 30–50% more efficient for simple to medium-sized RN apps. Redux shines for complex middleware or server sync but requires more optimization to match Zustand’s performance.

Best Practices and Common Pitfalls

Best Practices

Use Selectors: Always use selectors to subscribe to specific state slices.
Modular Stores: Split large apps into multiple stores (e.g., useAuthStore, useUiStore) for clarity.
Leverage Hermes: Ensure Hermes is enabled (default in RN 0.80+) for faster JS execution.
Debugging: Use devtools middleware with Flipper:


import { devtools } from 'zustand/middleware';
const useTodoStore = create(devtools((set) => ({ ... })));

Common Pitfalls

Overusing Global State: Use React Context for UI-only state (e.g., themes) to keep Zustand focused on app logic.
Persistence Overhead: Avoid persisting large state trees. Use partialize to limit stored data.
TypeScript Issues: Ensure complex state shapes are typed correctly to avoid inference errors.

Conclusion: Why Zustand Is the Future for React Native

Zustand’s simplicity, performance, and TypeScript support make it a game-changer for React Native state management in modern time. Its minimal footprint and compatibility with RN’s modern architecture (Fabric, Hermes, React 19.1) position it as a go-to for everything from prototypes to enterprise apps. By following this guide, you’ve built a to-do app, added persistence, and learned how to optimize performance.