@prismetic/next-preview-core 1.0.1 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prismetic/next-preview-core",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Hybrid static/preview architecture for Next.js + Strapi projects",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",

package/src/PreviewProviders.tsx

@@ -1,3 +1,4 @@
+
 "use client";
 
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
@@ -12,15 +13,24 @@ import { useState } from "react";
  * fetched once will be served from the cache on subsequent page navigations.
  *
  * @param {number} [staleTime=300000] - How long (ms) cached data is considered fresh. Default: 5 minutes.
+ * @param {boolean} [refetchOnWindowFocus=false] - Whether to refetch when the browser tab regains focus. Set to true in preview to auto-refresh after editing in Strapi.
  */
-export function PreviewProviders({ children, staleTime = 5 * 60 * 1000 }: { children: React.ReactNode; staleTime?: number }) {
+export function PreviewProviders({
+  children,
+  staleTime = 5 * 60 * 1000,
+  refetchOnWindowFocus = false,
+}: {
+  children: React.ReactNode;
+  staleTime?: number;
+  refetchOnWindowFocus?: boolean;
+}) {
   const [queryClient] = useState(
     () =>
       new QueryClient({
         defaultOptions: {
           queries: {
             staleTime,
-            refetchOnWindowFocus: false,
+            refetchOnWindowFocus,
             retry: 1,
           },
         },

package/integration_guide.md

@@ -1,151 +0,0 @@
-# Implementing Hybrid Static/Preview Architecture
-
-This guide explains how to implement the `@prismetic/next-preview-core` architecture into any new or existing Next.js + Strapi project.
-
-## 🔴 The Problem
-Modern Next.js applications often use `output: "export"` to build pure static HTML pages for maximum performance and security. However, this creates a major pain point for content editors: **Previewing content.**
-- During a static build, the server fetches data from Strapi and bakes it into HTML.
-- If an editor changes content in Strapi, they cannot see their changes until the entire site is rebuilt via CI/CD, which takes minutes.
-- To provide a live preview, a persistent Node.js server is typically required, defeating the cost/security benefits of a purely static S3/CDN deployment.
-
-## 🟢 The Solution
-A **Hybrid Architecture**. We maintain two separate build outputs using an environment variable (`NEXT_PUBLIC_APP_ENV`):
-1. **Production Build (`production`)**: Normal static export. Data is fetched at build time. Deployed to the production S3 bucket.
-2. **Preview Build (`preview`)**: A unique static export. Instead of fetching data at build time, it builds static "shell" components. When the editor loads the page in the browser, these shells use React Query (`@tanstack/react-query`) to fetch the latest draft content *directly from the Strapi GraphQL API* on the client-side.
-
-This provides the best of both worlds: highly secure static production sites, and instant live previews hosted on S3 that require zero backend compute.
-
----
-
-## 🚀 Step-by-Step Implementation Guide
-
-Follow these steps when setting up a new Next.js project.
-
-### Step 1: Install Dependencies
-
-```bash
-npm install @prismetic/next-preview-core @tanstack/react-query
-```
-
-### Step 2: Update Build Scripts
-In your [package.json](file:///Users/sunnyjhunjhunwala/PSM/repos/psm/next-preview-core/package.json), add a script for the preview build:
-
-```json
-"scripts": {
-  "build": "next build",
-  "build:preview": "NEXT_PUBLIC_APP_ENV=preview next build"
-}
-```
-
-### Step 3: Add the Provider to the Root Layout
-Wrap your preview environment in [PreviewProviders](file:///Users/sunnyjhunjhunwala/PSM/repos/psm/next-preview-core/src/PreviewProviders.tsx#6-36) to enable React Query caching. This ensures global data (like Navbar/Footer) is fetched once and cached during client-side navigation.
-
-**[src/app/[locale]/layout.jsx](file:///Users/sunnyjhunjhunwala/PSM/repos/RedSeaHospitality/turtle-bay-microsite/src/app/%5Blocale%5D/layout.jsx)**
-```jsx
-import { PreviewProviders } from "@prismetic/next-preview-core";
-// ... import your static Header/Footer and dynamic PreviewLayoutFetcher
-
-export default async function LocaleLayout({ children, params }) {
-  const { locale } = await params;
-  const isPreview = process.env.NEXT_PUBLIC_APP_ENV === "preview";
-
-  if (isPreview) {
-    return (
-      <PreviewProviders>
-        <PreviewLayoutFetcher locale={locale}>
-          {children}
-        </PreviewLayoutFetcher>
-      </PreviewProviders>
-    );
-  }
-
-  // Production: fetch statically
-  const layoutData = await fetchLayoutData(locale);
-  return (
-    <>
-      <Header data={layoutData.header} />
-      <main>{children}</main>
-      <Footer data={layoutData.footer} />
-    </>
-  );
-}
-```
-
-### Step 4: Separate Pure UI from Page Logic
-Never put data fetching and UI rendering in the same component. Extract the presentation layer into its own file (e.g., [HomeUI.jsx](file:///Users/sunnyjhunjhunwala/PSM/repos/RedSeaHospitality/turtle-bay-microsite/src/app/%5Blocale%5D/HomeUI.jsx), [DynamicPageUI.jsx](file:///Users/sunnyjhunjhunwala/PSM/repos/RedSeaHospitality/turtle-bay-microsite/src/app/%5Blocale%5D/%5B...slug%5D/DynamicPageUI.jsx)).
-
-**[src/app/[locale]/HomeUI.jsx](file:///Users/sunnyjhunjhunwala/PSM/repos/RedSeaHospitality/turtle-bay-microsite/src/app/%5Blocale%5D/HomeUI.jsx)**
-```jsx
-// A pure function that just takes data and renders standard components
-export default function HomeUI({ homepageData }) {
-  return (
-    <div>
-      <Hero data={homepageData.hero} />
-      <BlockManager blocks={homepageData.blocks} />
-    </div>
-  );
-}
-```
-
-### Step 5: Create the Preview Wrapper
-Use the [withLivePreview](file:///Users/sunnyjhunjhunwala/PSM/repos/psm/next-preview-core/src/withLivePreview.tsx#5-50) HOC to wrap the pure UI component. Give it your data fetching function and a unique cache key.
-
-**[src/components/preview/PreviewHome.jsx](file:///Users/sunnyjhunjhunwala/PSM/repos/RedSeaHospitality/turtle-bay-microsite/src/components/preview/PreviewHome.jsx)**
-```jsx
-"use client";
-
-import { withLivePreview } from "@prismetic/next-preview-core";
-import HomeUI from "@/app/[locale]/HomeUI";
-import { fetchHomepageContent } from "@/api/queryModules";
-
-export const PreviewHome = withLivePreview(
-  HomeUI, // The pure UI
-  ({ locale }) => fetchHomepageContent(locale), // The data fetcher
-  ({ locale }) => ["homepage", locale] // The React Query cache key
-);
-```
-
-### Step 6: Update the Page Route
-Conditionally render the Preview Wrapper or the Static UI based on the environment variable.
-
-**[src/app/[locale]/page.jsx](file:///Users/sunnyjhunjhunwala/PSM/repos/RedSeaHospitality/turtle-bay-microsite/src/app/%5Blocale%5D/page.jsx)**
-```jsx
-import { PreviewHome } from "@/components/preview/PreviewHome";
-import HomeUI from "./HomeUI";
-import { fetchHomepageContent } from "@/api/queryModules";
-
-export default async function LocaleHomePage({ params }) {
-  const { locale } = await params;
-  const isPreview = process.env.NEXT_PUBLIC_APP_ENV === "preview";
-
-  // If preview mode, return the client-side fetching shell
-  if (isPreview) return <PreviewHome locale={locale} />;
-
-  // Production mode: fetch statically during build
-  const data = await fetchHomepageContent(locale);
-  return <HomeUI {...data} />; // Make sure to match prop names
-}
-```
-
-### Step 7: Strapi CORS Configuration
-For preview mode to work, the browser must be able to make a request directly to Strapi. Ensure your Strapi server's `config/middlewares.js` has appropriate CORS rules allowing the preview frontend's domain.
-
-```javascript
-// Example Strapi CORS config
-{
-  name: 'strapi::cors',
-  config: {
-    origin: ['https://preview.yourproject.com', 'http://localhost:3000'],
-    methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'],
-    headers: ['Content-Type', 'Authorization', 'Origin', 'Accept'],
-    keepHeaderOnError: true,
-  },
-}
-```
-
----
-
-## ✅ Final Validation
-1. Run `npm run build:preview`.
-2. Inspect [out/index.html](file:///Users/sunnyjhunjhunwala/PSM/repos/RedSeaHospitality/turtle-bay-microsite/out/index.html) — it should be a nearly empty shell importing JavaScript bundles, not fully populated content.
-3. Serve [out/](file:///Users/sunnyjhunjhunwala/PSM/repos/RedSeaHospitality/turtle-bay-microsite/src/app/%5Blocale%5D/layout.jsx#16-50) locally and view the Network tab in your browser — you should see GraphQL requests fetching data natively on page load.