@pixel-pulse/next-cache-brain-core 0.3.0 → 0.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +149 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
feat: transition to beta with new smartFetch engine and renamed DevTools
|
|
2
|
+
|
|
3
|
+
- Rename `CacheDevtools` to `CacheBrainDevtools` for brand consistency.
|
|
4
|
+
- Implement `smartFetch` with support for `swr`, `cache-first`, and `network-first` strategies.
|
|
5
|
+
- Add real-time synchronization between core and UI via global event bridge.
|
|
6
|
+
- Update documentation and README for NPM launch.# 🧠 Next Cache Brain (Beta)
|
|
7
|
+
|
|
8
|
+
> **The intelligent caching layer for Next.js and React.** > Monitor, debug, and optimize your data fetching with a beautiful real-time DevTools interface.
|
|
9
|
+
|
|
10
|
+
`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.
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## ⚠️ Beta Version Notice
|
|
15
|
+
|
|
16
|
+
This project is currently in **Beta**. We are actively refining the API and performance.
|
|
17
|
+
|
|
18
|
+
- Please report any bugs via GitHub Issues.
|
|
19
|
+
- Expect breaking changes until version **1.0.0**.
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## 📦 Installation
|
|
24
|
+
|
|
25
|
+
Install both the core engine and the DevTools UI:
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
npm install @pixel-pulse/next-cache-brain-core @pixel-pulse/next-cache-brain-devtools
|
|
29
|
+
# or
|
|
30
|
+
pnpm add @pixel-pulse/next-cache-brain-core @pixel-pulse/next-cache-brain-devtools
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
35
|
+
## Usage
|
|
36
|
+
|
|
37
|
+
### 1. Setup the Provider and UI
|
|
38
|
+
|
|
39
|
+
In your Next.js `app/layout.tsx`, wrap your application in the `CacheBrainProvider` and add the `CacheBrainDevtools` component.
|
|
40
|
+
|
|
41
|
+
```tsx
|
|
42
|
+
// app/layout.tsx
|
|
43
|
+
import {
|
|
44
|
+
CacheBrainProvider,
|
|
45
|
+
CacheBrainDevtools,
|
|
46
|
+
} from "@pixel-pulse/next-cache-brain-devtools";
|
|
47
|
+
|
|
48
|
+
export default function RootLayout({
|
|
49
|
+
children,
|
|
50
|
+
}: {
|
|
51
|
+
children: React.ReactNode;
|
|
52
|
+
}) {
|
|
53
|
+
return (
|
|
54
|
+
<html lang="en">
|
|
55
|
+
<body>
|
|
56
|
+
<CacheBrainProvider>
|
|
57
|
+
{children}
|
|
58
|
+
|
|
59
|
+
{/* enabled={true} shows the Brain Icon in development mode */}
|
|
60
|
+
<CacheBrainDevtools
|
|
61
|
+
enabled={process.env.NODE_ENV === "development"}
|
|
62
|
+
/>
|
|
63
|
+
</CacheBrainProvider>
|
|
64
|
+
</body>
|
|
65
|
+
</html>
|
|
66
|
+
);
|
|
67
|
+
}
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
### 2. Implement Caching Strategies
|
|
73
|
+
|
|
74
|
+
Import the `smartFetch` engine from the `core` package. All strategies automatically synchronize with the DevTools UI via the internal event bridge.
|
|
75
|
+
|
|
76
|
+
Option 1: `cache-first`
|
|
77
|
+
|
|
78
|
+
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.
|
|
79
|
+
|
|
80
|
+
```tsx
|
|
81
|
+
const data = await smartFetch(url, {
|
|
82
|
+
strategy: "cache-first",
|
|
83
|
+
ttl: 60 * 1000, // 1 minute
|
|
84
|
+
dedupe: true,
|
|
85
|
+
});
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Option 2: `swr` (Stale-While-Revalidate)
|
|
89
|
+
|
|
90
|
+
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.
|
|
91
|
+
|
|
92
|
+
```tsx
|
|
93
|
+
const data = await smartFetch(url, {
|
|
94
|
+
strategy: "swr",
|
|
95
|
+
ttl: 30 * 1000, // 30 seconds
|
|
96
|
+
dedupe: true,
|
|
97
|
+
});
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
Option 3: `network-first`
|
|
101
|
+
|
|
102
|
+
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.
|
|
103
|
+
|
|
104
|
+
```tsx
|
|
105
|
+
const data = await smartFetch(url, {
|
|
106
|
+
strategy: "network-first",
|
|
107
|
+
ttl: 10 * 1000,
|
|
108
|
+
dedupe: false,
|
|
109
|
+
});
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Option 3: `no-cache`
|
|
113
|
+
|
|
114
|
+
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.
|
|
115
|
+
|
|
116
|
+
```tsx
|
|
117
|
+
const data = await smartFetch(url, {
|
|
118
|
+
strategy: "no-cache",
|
|
119
|
+
});
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
---
|
|
123
|
+
|
|
124
|
+
### 3. Full Implementation Example
|
|
125
|
+
|
|
126
|
+
Here is how you would use it inside a Next.js Server Component:
|
|
127
|
+
|
|
128
|
+
```tsx
|
|
129
|
+
import { smartFetch } from "@pixel-pulse/next-cache-brain-core";
|
|
130
|
+
|
|
131
|
+
async function ProductList() {
|
|
132
|
+
const url = "https://api.example.com/products";
|
|
133
|
+
|
|
134
|
+
// Using cache-first for optimized performance
|
|
135
|
+
const products = await smartFetch(url, {
|
|
136
|
+
ttl: 60000,
|
|
137
|
+
strategy: "cache-first",
|
|
138
|
+
dedupe: true,
|
|
139
|
+
});
|
|
140
|
+
|
|
141
|
+
return (
|
|
142
|
+
<ul>
|
|
143
|
+
{products.map((p: any) => (
|
|
144
|
+
<li key={p.id}>{p.name}</li>
|
|
145
|
+
))}
|
|
146
|
+
</ul>
|
|
147
|
+
);
|
|
148
|
+
}
|
|
149
|
+
```
|