@prismetic/next-preview-core 1.0.0

package/README.md

@@ -0,0 +1,118 @@
+# @prismetic/next-preview-core
+
+Hybrid static/preview architecture for Next.js + Strapi projects.
+
+Enables a production build that is a pure static export and a preview build hosted on S3 that fetches live Strapi content directly from the browser on page load — no Node.js server required.
+
+## Installation
+
+```bash
+npm install @prismetic/next-preview-core
+```
+
+Also requires `@tanstack/react-query` as a peer dependency:
+
+```bash
+npm install @tanstack/react-query
+```
+
+## Exports
+
+### `PreviewProviders`
+
+Wrap your preview layout in this provider to enable React Query caching. Layout data (Navbar, Footer) fetched once will not refetch on page navigation.
+
+```jsx
+// src/app/[locale]/layout.jsx
+import { PreviewProviders } from "@prismetic/next-preview-core";
+
+const isPreview = process.env.NEXT_PUBLIC_APP_ENV === "preview";
+
+return isPreview ? (
+  <PreviewProviders>
+    <YourPreviewLayoutFetcher locale={locale}>
+      {children}
+    </YourPreviewLayoutFetcher>
+  </PreviewProviders>
+) : (
+  // ... static layout
+);
+```
+
+### `withLivePreview(WrappedComponent, fetcherFn, cacheKeyGenerator)`
+
+A Higher-Order Component that handles `useQuery`, loading/error states, and injects fetched data into your UI component.
+
+| Argument | Type | Description |
+|---|---|---|
+| `WrappedComponent` | `React.Component` | Your pure UI component |
+| `fetcherFn` | `async (props) => data` | Async function that fetches the data |
+| `cacheKeyGenerator` | `(props) => string[]` | Returns the React Query cache key array |
+
+```jsx
+// src/components/preview/PreviewHome.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,
+  ({ locale }) => fetchHomepageContent(locale),
+  ({ locale }) => ["homepage", locale]
+);
+```
+
+Then in your `page.jsx`:
+
+```jsx
+// src/app/[locale]/page.jsx
+import { PreviewHome } from "@/components/preview/PreviewHome";
+
+export default async function LocaleHomePage({ params }) {
+  const { locale } = await params;
+  const isPreview = process.env.NEXT_PUBLIC_APP_ENV === "preview";
+
+  if (isPreview) return <PreviewHome locale={locale} />;
+
+  // Production: fetch data server-side
+  const data = await fetchHomepageContent(locale);
+  return <HomeUI data={data} />;
+}
+```
+
+## Build Commands
+
+| Command | Output |
+|---|---|
+| `npm run build` | Production static export (data baked in at build time) |
+| `npm run build:preview` | Preview static export (client-side fetch on page load) |
+
+Add to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "build": "next build",
+    "build:preview": "NEXT_PUBLIC_APP_ENV=preview next build"
+  }
+}
+```
+
+## Local Development (npm link)
+
+To test changes to this package in a project before publishing:
+
+```bash
+# 1. In this package directory
+npm link
+
+# 2. In your project directory
+npm link @prismetic/next-preview-core
+```
+
+To unlink:
+```bash
+npm unlink @prismetic/next-preview-core
+```

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@prismetic/next-preview-core",
+  "version": "1.0.0",
+  "description": "Hybrid static/preview architecture for Next.js + Strapi projects",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "keywords": [
+    "next.js",
+    "strapi",
+    "preview",
+    "static"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "react": ">=18",
+    "@tanstack/react-query": ">=5"
+  }
+}

package/src/PreviewProviders.tsx

@@ -0,0 +1,35 @@
+"use client";
+
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { useState } 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.
+ */
+export function PreviewProviders({ children, staleTime = 5 * 60 * 1000 }) {
+  const [queryClient] = useState(
+    () =>
+      new QueryClient({
+        defaultOptions: {
+          queries: {
+            staleTime,
+            refetchOnWindowFocus: false,
+            retry: 1,
+          },
+        },
+      })
+  );
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      {children}
+    </QueryClientProvider>
+  );
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+// @prismetic/next-preview-core
+// Company-wide hybrid static/preview architecture for Next.js + Strapi projects
+
+export { PreviewProviders } from "./PreviewProviders";
+export { withLivePreview } from "./withLivePreview";
+

package/src/withLivePreview.tsx

@@ -0,0 +1,49 @@
+"use client";
+
+import { useQuery } from "@tanstack/react-query";
+
+/**
+ * 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]
+ * );
+ */
+export function withLivePreview(WrappedComponent, fetcherFn, cacheKeyGenerator) {
+  return function PreviewComponent(props) {
+    const queryKey = cacheKeyGenerator(props);
+
+    const { data, isLoading } = useQuery({
+      queryKey,
+      queryFn: () => fetcherFn(props),
+    });
+
+    if (isLoading) {
+      return (
+        <div style={{ minHeight: "100vh", display: "flex", alignItems: "center", justifyContent: "center" }}>
+          Loading preview...
+        </div>
+      );
+    }
+
+    if (!data) {
+      return <div>Page not found</div>;
+    }
+
+    // Props spread first, then fetched data takes priority
+    return <WrappedComponent {...props} {...data} />;
+  };
+}