@pixel-pulse/next-cache-brain-core

✨ Features

• SmartFetch Engine: Unified API for SWR, Cache-First, and Network-First strategies.

• Visual Debugger: A specialized "Brain Interface" to track TTL, revalidation, and deduplication in real-time.

• Event Bridge: Seamless synchronization between core logic and UI components.

• Next.js Optimized: Built to handle the unique caching needs of App Router and Server Components.

⚠️ 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>
  );
}