@prismicio/next 1.1.0-alpha.1 → 1.1.0

package/dist/types.d.ts

@@ -1,21 +1,64 @@
-import type { PreviewData, NextApiRequest } from "next";
+import type { PreviewData } from "next";
 import type { ClientConfig } from "@prismicio/client";
+declare module "@prismicio/client" {
+    interface RequestInitLike {
+        next?: RequestInit["next"];
+    }
+}
 /**
  * Configuration for creating a Prismic client with automatic preview support in
  * Next.js apps.
  */
-export type CreateClientConfig = {
+export type CreateClientConfig = ClientConfig & {
     /**
-     * Preview data coming from Next.js context object. This context object comes
-     * from `getStaticProps` or `getServerSideProps`.
+     * **Only used in the Pages Directory (/pages).**
      *
-     * Pass `previewData` when using outside a Next.js API endpoint.
+     * The `previewData` object provided in the `getStaticProps()` or
+     * `getServerSideProps()` context object.
      */
     previewData?: PreviewData;
     /**
-     * A Next.js API endpoint request object.
+     * **Only used in the Pages Directory (/pages).**
      *
-     * Pass a `req` object when using in a Next.js API endpoint.
+     * The `req` object from a Next.js API route.
+     *
+     * @see Next.js API route docs: \<https://nextjs.org/docs/api-routes/introduction\>
      */
-    req?: NextApiRequest;
-} & ClientConfig;
+    req?: NextApiRequestLike;
+};
+/**
+ * The minimal set of properties needed from `next`'s `NextRequest` type.
+ *
+ * This request type is only compatible with Route Handlers defined in the `app`
+ * directory.
+ */
+export type NextRequestLike = {
+    headers: {
+        get(name: string): string | null;
+    };
+    url: string;
+    nextUrl: unknown;
+};
+/**
+ * The minimal set of properties needed from `next`'s `NextApiRequest` type.
+ *
+ * This request type is only compatible with API routes defined in the `pages`
+ * directory.
+ */
+export type NextApiRequestLike = {
+    query: Partial<Record<string, string | string[]>>;
+    cookies: Partial<Record<string, string>>;
+};
+/**
+ * The minimal set of properties needed from `next`'s `NextApiResponse` type.
+ *
+ * This request type is only compatible with API routes defined in the `pages`
+ * directory.
+ */
+export type NextApiResponseLike = {
+    redirect(url: string): NextApiResponseLike;
+    clearPreviewData(): NextApiResponseLike;
+    status(statusCode: number): NextApiResponseLike;
+    json(body: any): void;
+    setPreviewData(data: object | string): NextApiResponseLike;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@prismicio/next",
-	"version": "1.1.0-alpha.1",
+	"version": "1.1.0",
 	"description": "Helpers to integrate Prismic into Next.js apps",
 	"keywords": [
 		"typescript",
@@ -18,14 +18,8 @@
 	"sideEffects": false,
 	"exports": {
 		".": {
-			"react-server": {
-				"import": "./dist/react-server.js",
-				"require": "./dist/react-server.cjs"
-			},
-			"default": {
-				"import": "./dist/index.js",
-				"require": "./dist/index.cjs"
-			}
+			"import": "./dist/index.js",
+			"require": "./dist/index.cjs"
 		},
 		"./package.json": "./package.json"
 	},
@@ -70,7 +64,8 @@
 		"eslint-plugin-react-hooks": "^4.6.0",
 		"eslint-plugin-tsdoc": "^0.2.17",
 		"happy-dom": "^9.9.2",
-		"next": "^13.0.0",
+		"next": "^13.4.0",
+		"node-fetch": "^3.3.1",
 		"prettier": "^2.8.8",
 		"prettier-plugin-jsdoc": "^0.4.2",
 		"react": "^18.1.0",

package/src/PrismicPreview.tsx

@@ -1,11 +1,8 @@
-"use client";
-
 import * as React from "react";
-import { useRouter } from "next/router";
+import * as prismic from "@prismicio/client";
 import Script from "next/script";
 
-import { getPrismicPreviewCookie } from "./lib/getPrismicPreviewCookie";
-import { getPreviewCookieRepositoryName } from "./lib/getPreviewCookieRepositoryName";
+import { PrismicPreviewClient } from "./PrismicPreviewClient";
 
 /**
  * Props for `<PrismicPreview>`.
@@ -18,26 +15,23 @@ export type PrismicPreviewProps = {
 	repositoryName: string;
 
 	/**
+	 * **Only used in the Pages Directory (/pages).**
+	 *
 	 * The URL of your app's Prismic preview endpoint (default: `/api/preview`).
 	 * This URL will be fetched on preview update events.
-	 *
-	 * **Note**: If your `next.config.js` file contains a `basePath`, it is
-	 * automatically included.
 	 */
 	updatePreviewURL?: string;
 
 	/**
+	 * **Only used in the Pages Directory (/pages).**
+	 *
 	 * The URL of your app's exit preview endpoint (default: `/api/exit-preview`).
 	 * This URL will be fetched on preview exit events.
-	 *
-	 * **Note**: If your `next.config.js` file contains a `basePath`, it is
-	 * automatically included.
 	 */
 	exitPreviewURL?: string;
 
 	/**
-	 * Children to render adjacent to the Prismic Toolbar. The Prismic Toolbar
-	 * will be rendered last.
+	 * Children to render adjacent to the Prismic Toolbar.
 	 */
 	children?: React.ReactNode;
 };
@@ -45,8 +39,8 @@ export type PrismicPreviewProps = {
 /**
  * React component that sets up Prismic Previews using the Prismic Toolbar. When
  * the Prismic Toolbar send events to the browser, such as on preview updates
- * and exiting, this component will automatically update the Next.js preview
- * cookie and refresh the page.
+ * and exiting, this component will automatically refresh the page with the
+ * changes.
  *
  * This component can be wrapped around your app or added anywhere in your app's
  * tree. It must be rendered on every page.
@@ -54,127 +48,15 @@ export type PrismicPreviewProps = {
 export function PrismicPreview({
 	repositoryName,
 	children,
-	updatePreviewURL = "/api/preview",
-	exitPreviewURL = "/api/exit-preview",
+	...props
 }: PrismicPreviewProps): JSX.Element {
-	const router = useRouter();
-
-	const resolvedUpdatePreviewURL = router.basePath + updatePreviewURL;
-	const resolvedExitPreviewURL = router.basePath + exitPreviewURL;
-
-	React.useEffect(() => {
-		/**
-		 * Starts Preview Mode and refreshes the page's props.
-		 */
-		const startPreviewMode = async () => {
-			// Start Next.js Preview Mode via the given preview API endpoint.
-			const res = await globalThis.fetch(resolvedUpdatePreviewURL);
-
-			// We check for `res.redirected` rather than `res.ok`
-			// since the update preview endpoint may redirect to a
-			// 404 page. As long as it redirects, we know the
-			// endpoint exists and at least attempted to set
-			// preview data.
-			if (res.redirected) {
-				globalThis.location.reload();
-			} else {
-				console.error(
-					`[<PrismicPreview>] Failed to start or update Preview Mode using the "${resolvedUpdatePreviewURL}" API endpoint. Does it exist?`,
-				);
-			}
-		};
-
-		const handlePrismicPreviewUpdate = async (event: Event) => {
-			// Prevent the toolbar from reloading the page.
-			event.preventDefault();
-
-			await startPreviewMode();
-		};
-
-		const handlePrismicPreviewEnd = async (event: Event) => {
-			// Prevent the toolbar from reloading the page.
-			event.preventDefault();
-
-			// Exit Next.js Preview Mode via the given preview API endpoint.
-			const res = await globalThis.fetch(resolvedExitPreviewURL);
-
-			if (res.ok) {
-				globalThis.location.reload();
-			} else {
-				console.error(
-					`[<PrismicPreview>] Failed to exit Preview Mode using the "${resolvedExitPreviewURL}" API endpoint. Does it exist?`,
-				);
-			}
-		};
-
-		if (router.isPreview) {
-			// Register Prismic Toolbar event handlers.
-			window.addEventListener(
-				"prismicPreviewUpdate",
-				handlePrismicPreviewUpdate,
-			);
-			window.addEventListener("prismicPreviewEnd", handlePrismicPreviewEnd);
-		} else {
-			const prismicPreviewCookie = getPrismicPreviewCookie(
-				globalThis.document.cookie,
-			);
-
-			if (prismicPreviewCookie) {
-				// If a Prismic preview cookie is present, but Next.js Preview
-				// Mode is not active, we must activate Preview Mode manually.
-				//
-				// This will happen when a visitor accesses the page using a
-				// Prismic preview share link.
-
-				/**
-				 * Determines if the current location is a descendant of the app's base
-				 * path.
-				 *
-				 * This is used to prevent infinite refrehes; when
-				 * `isDescendantOfBasePath` is `false`, `router.isPreview` is also
-				 * `false`.
-				 *
-				 * If the app does not have a base path, this should always be `true`.
-				 */
-				const locationIsDescendantOfBasePath = window.location.href.startsWith(
-					window.location.origin + router.basePath,
-				);
-
-				const prismicPreviewCookieRepositoryName =
-					getPreviewCookieRepositoryName(prismicPreviewCookie);
-
-				if (
-					locationIsDescendantOfBasePath &&
-					prismicPreviewCookieRepositoryName === repositoryName
-				) {
-					startPreviewMode();
-				}
-			}
-		}
-
-		// On cleanup, unregister Prismic Toolbar event handlers.
-		return () => {
-			window.removeEventListener(
-				"prismicPreviewUpdate",
-				handlePrismicPreviewUpdate,
-			);
-			window.removeEventListener("prismicPreviewEnd", handlePrismicPreviewEnd);
-		};
-	}, [
-		repositoryName,
-		resolvedExitPreviewURL,
-		resolvedUpdatePreviewURL,
-		router.isPreview,
-		router.basePath,
-	]);
+	const toolbarSrc = prismic.getToolbarSrc(repositoryName);
 
 	return (
 		<>
 			{children}
-			<Script
-				src={`https://static.cdn.prismic.io/prismic.js?repo=${repositoryName}&new=true`}
-				strategy="lazyOnload"
-			/>
+			<PrismicPreviewClient repositoryName={repositoryName} {...props} />
+			<Script src={toolbarSrc} strategy="lazyOnload" />
 		</>
 	);
 }

package/src/PrismicPreviewClient.tsx

@@ -0,0 +1,159 @@
+"use client";
+
+import { useEffect } from "react";
+import { useRouter as usePagesRouter } from "next/router";
+import { useRouter } from "next/navigation";
+
+import { getPrismicPreviewCookie } from "./lib/getPrismicPreviewCookie";
+import { getPreviewCookieRepositoryName } from "./lib/getPreviewCookieRepositoryName";
+
+import { PrismicPreviewProps } from "./PrismicPreview";
+
+type PrismicPreviewClientProps = Omit<PrismicPreviewProps, "children">;
+
+export function PrismicPreviewClient({
+	repositoryName,
+	updatePreviewURL = "/api/preview",
+	exitPreviewURL = "/api/exit-preview",
+}: PrismicPreviewClientProps): null {
+	let isAppRouter = true;
+	let isPreviewMode = false;
+	let basePath = "";
+	let refresh: () => void;
+
+	try {
+		// eslint-disable-next-line react-hooks/rules-of-hooks
+		const router = usePagesRouter();
+
+		isAppRouter = false;
+		basePath = router.basePath;
+		isPreviewMode = router.isPreview;
+		refresh = () => router.replace(router.asPath, undefined, { scroll: false });
+	} catch {
+		// Assume we are in App Router. Ignore the error.
+
+		// eslint-disable-next-line react-hooks/rules-of-hooks
+		const router = useRouter();
+
+		refresh = router.refresh;
+	}
+
+	useEffect(() => {
+		/**
+		 * Starts Preview Mode and refreshes the page's props.
+		 */
+		const startPreviewMode = async () => {
+			const resolvedUpdatePreviewURL = basePath + updatePreviewURL;
+
+			// Start Next.js Preview Mode via the given preview API endpoint.
+			const res = await globalThis.fetch(resolvedUpdatePreviewURL);
+
+			// We check for `res.redirected` rather than `res.ok`
+			// since the update preview endpoint may redirect to a
+			// 404 page. As long as it redirects, we know the
+			// endpoint exists and at least attempted to set
+			// preview data.
+			if (res.redirected) {
+				refresh();
+			} else {
+				console.error(
+					`[<PrismicPreview>] Failed to start or update Preview Mode using the "${resolvedUpdatePreviewURL}" API endpoint. Does it exist?`,
+				);
+			}
+		};
+
+		const handlePrismicPreviewUpdate = async (event: Event) => {
+			// Prevent the toolbar from reloading the page.
+			event.preventDefault();
+
+			if (isAppRouter) {
+				refresh();
+			} else {
+				await startPreviewMode();
+			}
+		};
+
+		const handlePrismicPreviewEnd = async (event: Event) => {
+			// Prevent the toolbar from reloading the page.
+			event.preventDefault();
+
+			if (isAppRouter) {
+				refresh();
+			} else {
+				const resolvedExitPreviewURL = basePath + exitPreviewURL;
+
+				// Exit Next.js Preview Mode via the given preview API endpoint.
+				const res = await globalThis.fetch(resolvedExitPreviewURL);
+
+				if (res.ok) {
+					// TODO: Can we do better than a full page reload?
+					// globalThis.location.reload();
+					refresh();
+				} else {
+					console.error(
+						`[<PrismicPreview>] Failed to exit Preview Mode using the "${resolvedExitPreviewURL}" API endpoint. Does it exist?`,
+					);
+				}
+			}
+		};
+
+		window.addEventListener("prismicPreviewUpdate", handlePrismicPreviewUpdate);
+		window.addEventListener("prismicPreviewEnd", handlePrismicPreviewEnd);
+
+		if (!isPreviewMode) {
+			const prismicPreviewCookie = getPrismicPreviewCookie(
+				globalThis.document.cookie,
+			);
+
+			if (prismicPreviewCookie) {
+				// If a Prismic preview cookie is present, but Next.js Preview
+				// Mode is not active, we must activate Preview Mode manually.
+				//
+				// This will happen when a visitor accesses the page using a
+				// Prismic preview share link.
+
+				/**
+				 * Determines if the current location is a descendant of the app's base
+				 * path.
+				 *
+				 * This is used to prevent infinite refrehes; when
+				 * `isDescendantOfBasePath` is `false`, `router.isPreview` is also
+				 * `false`.
+				 *
+				 * If the app does not have a base path, this should always be `true`.
+				 */
+				const locationIsDescendantOfBasePath = window.location.href.startsWith(
+					window.location.origin + basePath,
+				);
+
+				const prismicPreviewCookieRepositoryName =
+					getPreviewCookieRepositoryName(prismicPreviewCookie);
+
+				if (
+					locationIsDescendantOfBasePath &&
+					prismicPreviewCookieRepositoryName === repositoryName
+				) {
+					startPreviewMode();
+				}
+			}
+		}
+
+		return () => {
+			window.removeEventListener(
+				"prismicPreviewUpdate",
+				handlePrismicPreviewUpdate,
+			);
+			window.removeEventListener("prismicPreviewEnd", handlePrismicPreviewEnd);
+		};
+	}, [
+		basePath,
+		exitPreviewURL,
+		isAppRouter,
+		isPreviewMode,
+		refresh,
+		repositoryName,
+		updatePreviewURL,
+	]);
+
+	return null;
+}

package/src/enableAutoPreviews.ts

@@ -1,23 +1,8 @@
 import { PreviewData } from "next";
-import type * as prismic from "@prismicio/client";
+import { cookies } from "next/headers";
+import * as prismic from "@prismicio/client";
 
-interface PrismicNextPreviewData {
-	ref: string;
-}
-
-/**
- * Determines if a Next.js preview data object contains Prismic preview data.
- *
- * @param previewData - The Next.js preview data object to check.
- *
- * @returns `true` if `previewData` contains Prismic preview data, `false`
- *   otherwise.
- */
-const isPrismicNextPreviewData = (
-	previewData: PreviewData,
-): previewData is PrismicNextPreviewData => {
-	return typeof previewData === "object" && "ref" in previewData;
-};
+import { NextApiRequestLike } from "./types";
 
 /**
  * Configuration for `enableAutoPreviews`.
@@ -37,27 +22,25 @@ export type EnableAutoPreviewsConfig<
 		prismic.Client,
 		"queryContentFromRef" | "enableAutoPreviewsFromReq"
 	>;
-} & (
-	| {
-			/**
-			 * A Next.js context object (such as the context object from
-			 * `getStaticProps` or `getServerSideProps`).
-			 *
-			 * Pass a `context` object when using `enableAutoPreviews` outside a
-			 * Next.js API endpoint.
-			 */
-			previewData?: TPreviewData;
-	  }
-	| {
-			/**
-			 * A Next.js API endpoint request object.
-			 *
-			 * Pass a `req` object when using `enableAutoPreviews` in a Next.js API
-			 * endpoint.
-			 */
-			req?: prismic.HttpRequestLike;
-	  }
-);
+
+	/**
+	 * **Only used in the Pages Directory (/pages).**
+	 *
+	 * The `previewData` object provided in the `getStaticProps()` or
+	 * `getServerSideProps()` context object.
+	 */
+	previewData?: TPreviewData;
+
+	/**
+	 * **Only used in the Pages Directory (/pages).**
+	 *
+	 * The `req` object from a Next.js API route.
+	 *
+	 * @see Next.js API route docs: \<https://nextjs.org/docs/api-routes/introduction\>
+	 */
+	req?: NextApiRequestLike;
+};
+
 /**
  * Configures a Prismic client to automatically query draft content during a
  * preview session. It either takes in a Next.js `getStaticProps` context object
@@ -69,16 +52,61 @@ export const enableAutoPreviews = <TPreviewData extends PreviewData>(
 	config: EnableAutoPreviewsConfig<TPreviewData>,
 ): void => {
 	if ("previewData" in config && config.previewData) {
-		// If preview data is being passed from Next Context then use queryContentFromRef
-
-		const { previewData } = config;
+		// Assume we are in `getStaticProps()` or
+		// `getServerSideProps()` with active Preview Mode (`pages`
+		// directory).
 
-		if (isPrismicNextPreviewData(previewData) && previewData.ref) {
-			config.client.queryContentFromRef(previewData.ref);
+		if (
+			typeof config.previewData === "object" &&
+			"ref" in config.previewData &&
+			typeof config.previewData.ref === "string"
+		) {
+			config.client.queryContentFromRef(config.previewData.ref);
 		}
 	} else if ("req" in config && config.req) {
-		// If the req object is passed then use enableAutoPreviewsFromReq
+		// Assume we are in an API Route (`pages` directory).
 
 		config.client.enableAutoPreviewsFromReq(config.req);
+	} else {
+		// Assume we are in App Router (`app` directory) OR
+		// `getStaticProps()`/`getServerSideProps()` with an inactive
+		// Preview Mode (`pages` directory).
+
+		// We use a function value so the cookie is checked on every
+		// request. We don't have a static value to read from.
+		config.client.queryContentFromRef(() => {
+			let cookie: string | undefined;
+			try {
+				cookie = cookies().get(prismic.cookie.preview)?.value;
+			} catch {
+				// noop - We are probably in
+				// `getStaticProps()` or `getServerSideProps()`
+				// with inactive Preview Mode where `cookies()`
+				// does not work. We don't need to do any
+				// preview handling.
+
+				return;
+			}
+
+			// We are probably in App Router (`app` directory).
+
+			// We only return the cookie if a Prismic Preview session is active.
+			//
+			// An inactive cookie looks like this (URL encoded):
+			// 	{
+			// 		"_tracker": "abc123"
+			// 	}
+			//
+			// An active cookie looks like this (URL encoded):
+			// 	{
+			// 		"_tracker": "abc123",
+			// 		"example-prismic-repo.prismic.io": {
+			// 			preview: "https://example-prismic-repo.prismic.io/previews/abc:123?websitePreviewId=xyz"
+			// 		}
+			// 	}
+			if (cookie && /\.prismic\.io/.test(cookie)) {
+				return cookie;
+			}
+		});
 	}
 };

package/src/exitPreview.ts

@@ -1,46 +1,34 @@
-import type { NextApiResponse, NextApiRequest } from "next";
+import { NextResponse } from "next/server";
+
+import { NextApiRequestLike, NextApiResponseLike } from "./types";
 
 /**
  * Configuration for `exitPreview`.
  */
 export type ExitPreviewConfig = {
 	/**
-	 * The `req` object from a Next.js API route. This is given as a parameter to
-	 * the API route.
+	 * The `req` object from a Next.js API route.
 	 *
-	 * @see Next.js API route docs: {@link https://nextjs.org/docs/api-routes/introduction}
+	 * @see Next.js API route docs: \<https://nextjs.org/docs/api-routes/introduction\>
 	 */
-	// `req` is no longer used in `exitPreview()`. It previously would
-	// redirect the user to the referring URL, but it no longer has that
-	// behavior.
-	//
-	// `req` is retained as a parameter to make setting up an exit preview
-	// API route easier (this eliminates the awkward need to handle an
-	// unused `req` param).
-	//
-	// It is also retained in case it is needed in the future, such as
-	// reading headers or metadata about the request.
-	req: {
-		headers: NextApiRequest["headers"];
-	};
+	req: NextApiRequestLike;
 
 	/**
-	 * The `res` object from a Next.js API route. This is given as a parameter to
-	 * the API route.
+	 * The `res` object from a Next.js API route.
 	 *
-	 * @see Next.js API route docs: {@link https://nextjs.org/docs/api-routes/introduction}
+	 * @see Next.js API route docs: \<https://nextjs.org/docs/api-routes/introduction\>
 	 */
-	res: {
-		clearPreviewData: NextApiResponse["clearPreviewData"];
-		status: NextApiResponse["status"];
-		json: NextApiResponse["json"];
-	};
+	res: NextApiResponseLike;
 };
 
 /**
+ * **Only use this function in the Pages Directory (/pages).**
+ *
  * Exits Next.js's Preview Mode from within a Next.js API route.
  */
-export function exitPreview(config: ExitPreviewConfig): void {
+export async function exitPreview(
+	config: ExitPreviewConfig,
+): Promise<NextResponse | void> {
 	// Exit the current user from Preview Mode.
 	config.res.clearPreviewData();