@prismetic/next-preview-core 1.0.0 → 1.0.1

package/dist/index.d.mts

@@ -0,0 +1,41 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React$1 from 'react';
+
+/**
+ * React Query provider for Preview Mode.
+ * Part of @prismetic/next-preview-core.
+ *
+ * Wrap the preview build's component tree in this provider to enable
+ * client-side caching of Strapi data. Layout data (Navbar, Footer)
+ * 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.
+ */
+declare function PreviewProviders({ children, staleTime }: {
+    children: React.ReactNode;
+    staleTime?: number;
+}): react_jsx_runtime.JSX.Element;
+
+/**
+ * A generic Higher-Order Component for Preview Mode data fetching.
+ * Part of @prismetic/next-preview-core.
+ *
+ * @param {React.Component} WrappedComponent - The pure UI component to render once data is fetched.
+ * @param {Function} fetcherFn - An async function that fetches data (receives component props as argument).
+ * @param {Function} cacheKeyGenerator - A function that returns a React Query queryKey array (receives component props).
+ *
+ * @example
+ * // In your project's preview wrapper:
+ * import { withLivePreview } from "@prismetic/next-preview-core";
+ * import HomeUI from "../HomeUI";
+ * import { fetchHomepageContent } from "@/api/queryModules";
+ *
+ * export const PreviewHome = withLivePreview(
+ *   HomeUI,
+ *   ({ locale }) => fetchHomepageContent(locale),
+ *   ({ locale }) => ["homepage", locale]
+ * );
+ */
+declare function withLivePreview<P extends object>(WrappedComponent: React$1.ComponentType<P>, fetcherFn: (props: P) => Promise<any>, cacheKeyGenerator: (props: P) => any[]): (props: P) => react_jsx_runtime.JSX.Element;
+
+export { PreviewProviders, withLivePreview };

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React$1 from 'react';
+
+/**
+ * React Query provider for Preview Mode.
+ * Part of @prismetic/next-preview-core.
+ *
+ * Wrap the preview build's component tree in this provider to enable
+ * client-side caching of Strapi data. Layout data (Navbar, Footer)
+ * 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.
+ */
+declare function PreviewProviders({ children, staleTime }: {
+    children: React.ReactNode;
+    staleTime?: number;
+}): react_jsx_runtime.JSX.Element;
+
+/**
+ * A generic Higher-Order Component for Preview Mode data fetching.
+ * Part of @prismetic/next-preview-core.
+ *
+ * @param {React.Component} WrappedComponent - The pure UI component to render once data is fetched.
+ * @param {Function} fetcherFn - An async function that fetches data (receives component props as argument).
+ * @param {Function} cacheKeyGenerator - A function that returns a React Query queryKey array (receives component props).
+ *
+ * @example
+ * // In your project's preview wrapper:
+ * import { withLivePreview } from "@prismetic/next-preview-core";
+ * import HomeUI from "../HomeUI";
+ * import { fetchHomepageContent } from "@/api/queryModules";
+ *
+ * export const PreviewHome = withLivePreview(
+ *   HomeUI,
+ *   ({ locale }) => fetchHomepageContent(locale),
+ *   ({ locale }) => ["homepage", locale]
+ * );
+ */
+declare function withLivePreview<P extends object>(WrappedComponent: React$1.ComponentType<P>, fetcherFn: (props: P) => Promise<any>, cacheKeyGenerator: (props: P) => any[]): (props: P) => react_jsx_runtime.JSX.Element;
+
+export { PreviewProviders, withLivePreview };

package/dist/index.js

@@ -0,0 +1,71 @@
+"use client";
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  PreviewProviders: () => PreviewProviders,
+  withLivePreview: () => withLivePreview
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/PreviewProviders.tsx
+var import_react_query = require("@tanstack/react-query");
+var import_react = require("react");
+var import_jsx_runtime = require("react/jsx-runtime");
+function PreviewProviders({ children, staleTime = 5 * 60 * 1e3 }) {
+  const [queryClient] = (0, import_react.useState)(
+    () => new import_react_query.QueryClient({
+      defaultOptions: {
+        queries: {
+          staleTime,
+          refetchOnWindowFocus: false,
+          retry: 1
+        }
+      }
+    })
+  );
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_react_query.QueryClientProvider, { client: queryClient, children });
+}
+
+// src/withLivePreview.tsx
+var import_react_query2 = require("@tanstack/react-query");
+var import_jsx_runtime2 = require("react/jsx-runtime");
+function withLivePreview(WrappedComponent, fetcherFn, cacheKeyGenerator) {
+  return function PreviewComponent(props) {
+    const queryKey = cacheKeyGenerator(props);
+    const { data, isLoading } = (0, import_react_query2.useQuery)({
+      queryKey,
+      queryFn: () => fetcherFn(props)
+    });
+    if (isLoading) {
+      return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { style: { minHeight: "100vh", display: "flex", alignItems: "center", justifyContent: "center" }, children: "Loading preview..." });
+    }
+    if (!data) {
+      return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { children: "Page not found" });
+    }
+    return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(WrappedComponent, { ...props, ...data });
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PreviewProviders,
+  withLivePreview
+});

package/dist/index.mjs

@@ -0,0 +1,44 @@
+"use client";
+
+// src/PreviewProviders.tsx
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { useState } from "react";
+import { jsx } from "react/jsx-runtime";
+function PreviewProviders({ children, staleTime = 5 * 60 * 1e3 }) {
+  const [queryClient] = useState(
+    () => new QueryClient({
+      defaultOptions: {
+        queries: {
+          staleTime,
+          refetchOnWindowFocus: false,
+          retry: 1
+        }
+      }
+    })
+  );
+  return /* @__PURE__ */ jsx(QueryClientProvider, { client: queryClient, children });
+}
+
+// src/withLivePreview.tsx
+import { useQuery } from "@tanstack/react-query";
+import { jsx as jsx2 } from "react/jsx-runtime";
+function withLivePreview(WrappedComponent, fetcherFn, cacheKeyGenerator) {
+  return function PreviewComponent(props) {
+    const queryKey = cacheKeyGenerator(props);
+    const { data, isLoading } = useQuery({
+      queryKey,
+      queryFn: () => fetcherFn(props)
+    });
+    if (isLoading) {
+      return /* @__PURE__ */ jsx2("div", { style: { minHeight: "100vh", display: "flex", alignItems: "center", justifyContent: "center" }, children: "Loading preview..." });
+    }
+    if (!data) {
+      return /* @__PURE__ */ jsx2("div", { children: "Page not found" });
+    }
+    return /* @__PURE__ */ jsx2(WrappedComponent, { ...props, ...data });
+  };
+}
+export {
+  PreviewProviders,
+  withLivePreview
+};

package/integration_guide.md

@@ -0,0 +1,151 @@
+# 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.

package/package.json

@@ -1,10 +1,16 @@
 {
   "name": "@prismetic/next-preview-core",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Hybrid static/preview architecture for Next.js + Strapi projects",
-  "main": "./src/index.ts",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
   },
   "keywords": [
     "next.js",
@@ -12,9 +18,19 @@
     "preview",
     "static"
   ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  },
   "license": "MIT",
   "peerDependencies": {
-    "react": ">=18",
-    "@tanstack/react-query": ">=5"
+    "@tanstack/react-query": ">=5",
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "@types/react": "^19.2.14",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
   }
-}
+}

package/src/PreviewProviders.tsx

@@ -13,7 +13,7 @@ import { useState } from "react";
  *
  * @param {number} [staleTime=300000] - How long (ms) cached data is considered fresh. Default: 5 minutes.
  */
-export function PreviewProviders({ children, staleTime = 5 * 60 * 1000 }) {
+export function PreviewProviders({ children, staleTime = 5 * 60 * 1000 }: { children: React.ReactNode; staleTime?: number }) {
   const [queryClient] = useState(
     () =>
       new QueryClient({

package/src/withLivePreview.tsx

@@ -1,6 +1,7 @@
 "use client";
 
 import { useQuery } from "@tanstack/react-query";
+import React from "react";
 
 /**
  * A generic Higher-Order Component for Preview Mode data fetching.
@@ -22,8 +23,12 @@ import { useQuery } from "@tanstack/react-query";
  *   ({ locale }) => ["homepage", locale]
  * );
  */
-export function withLivePreview(WrappedComponent, fetcherFn, cacheKeyGenerator) {
-  return function PreviewComponent(props) {
+export function withLivePreview<P extends object>(
+  WrappedComponent: React.ComponentType<P>,
+  fetcherFn: (props: P) => Promise<any>,
+  cacheKeyGenerator: (props: P) => any[]
+) {
+  return function PreviewComponent(props: P) {
     const queryKey = cacheKeyGenerator(props);
 
     const { data, isLoading } = useQuery({

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "es2020",
+    "module": "esnext",
+    "lib": ["DOM", "DOM.Iterable", "ESNext"],
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "strict": true,
+    "jsx": "react-jsx",
+    "declaration": true,
+    "baseUrl": "."
+  },
+  "include": ["src/**/*"]
+}

package/tsup.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/index.ts"],
+  format: ["cjs", "esm"],
+  dts: true,
+  clean: true,
+  external: ["react", "react-dom", "@tanstack/react-query"],
+  esbuildOptions(options) {
+    // Force Next.js App Router client directive on the output bundles
+    options.banner = {
+      js: '"use client";',
+    };
+  },
+});