Rename CacheDevtools to CacheBrainDevtools for brand consistency.
Implement smartFetch with support for swr, cache-first, and network-first strategies.
Add real-time synchronization between core and UI via global event bridge.
Fix: Resolve localStorage key mismatch to ensure persistence on refresh.
Update documentation and README for NPM launch.# 🧠 Next Cache Brain (Beta)

The intelligent caching layer for Next.js and React. > Monitor, debug, and optimize your data fetching with a beautiful real-time DevTools interface.

next-cache-brain provides a suite of high-level fetching strategies (SWR, Cache-First, Network-First) paired with a visual debugger to help you understand exactly what’s happening in your application's cache.

⚠️ Beta Version Notice

This project is currently in Beta. We are actively refining the API and performance.

Please report any bugs via GitHub Issues.
Expect breaking changes until version 1.0.0.

📦 Installation

Install both the core engine and the DevTools UI:

npm install @pixel-pulse/next-cache-brain-core @pixel-pulse/next-cache-brain-devtools
# or
pnpm add @pixel-pulse/next-cache-brain-core @pixel-pulse/next-cache-brain-devtools

Usage

1. Setup the Provider and UI

In your Next.js app/layout.tsx, wrap your application in the CacheBrainProvider and add the CacheBrainDevtools component.

// app/layout.tsx
import {
  CacheBrainProvider,
  CacheBrainDevtools,
} from "@pixel-pulse/next-cache-brain-devtools";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <CacheBrainProvider>
          {children}

          {/* enabled={true} shows the Brain Icon in development mode */}
          <CacheBrainDevtools
            enabled={process.env.NODE_ENV === "development"}
          />
        </CacheBrainProvider>
      </body>
    </html>
  );
}

2. Implement Caching Strategies

Import the smartFetch engine from the core package. All strategies automatically synchronize with the DevTools UI via the internal event bridge.

Option 1: cache-first

Best for static or rarely changing data (e.g., product details, settings). It checks the cache first and only hits the network if the data is expired or missing.

const data = await smartFetch(url, {
  strategy: "cache-first",
  ttl: 60 * 1000, // 1 minute
  dedupe: true,
});

Option 2: swr (Stale-While-Revalidate)

Best for dynamic feeds (e.g., social posts, dashboards). It returns the cached data immediately while fetching fresh data in the background to update the cache for the next request.

const data = await smartFetch(url, {
  strategy: "swr",
  ttl: 30 * 1000, // 30 seconds
  dedupe: true,
});

Option 3: network-first

Best for critical real-time data (e.g., stock prices, chat). It always tries the network first but falls back to the cache if the user is offline or the request fails.

const data = await smartFetch(url, {
  strategy: "network-first",
  ttl: 10 * 1000,
  dedupe: false,
});

Option 3: no-cache

Bypasses the caching logic entirely. This is useful for testing or for data that should never be stored, while still allowing the request to be tracked in the Cache Brain DevTools.

const data = await smartFetch(url, {
  strategy: "no-cache",
});

3. Full Implementation Example

Here is how you would use it inside a Next.js Server Component:

import { smartFetch } from "@pixel-pulse/next-cache-brain-core";

async function ProductList() {
  const url = "https://api.example.com/products";

  // Using cache-first for optimized performance
  const products = await smartFetch(url, {
    ttl: 60000,
    strategy: "cache-first",
    dedupe: true,
  });

  return (
    <ul>
      {products.map((p: any) => (
        <li key={p.id}>{p.name}</li>
      ))}
    </ul>
  );
}